lib/Catalyst/Plugin/Static/Simple.pm

   1 package Catalyst::Plugin::Static::Simple;
   2
   3 use strict;
   4 use base qw/Class::Accessor::Fast Class::Data::Inheritable/;
   5 use File::Slurp;
   6 use File::stat;
   7 use MIME::Types;
   8 use NEXT;
   9
  10 our $VERSION = '0.09';
  11
  12 __PACKAGE__->mk_classdata( qw/_static_mime_types/ );
  13 __PACKAGE__->mk_accessors( qw/_static_file
  14                               _static_apache_mode
  15                               _static_debug_message/ );
  16
  17 # prepare_action is used to first check if the request path is a static file.
  18 # If so, we skip all other prepare_action steps to improve performance.
  19 sub prepare_action {
  20     my $c = shift;
  21     my $path = $c->req->path;
  22
  23     # is the URI in a static-defined path?
  24     foreach my $dir ( @{ $c->config->{static}->{dirs} } ) {
  25         my $re = ( $dir =~ /^qr\//xms ) ? eval $dir : qr/^${dir}/;
  26         if ($@) {
  27             $c->error( "Error compiling static dir regex '$dir': $@" );
  28         }
  29         if ( $path =~ $re ) {
  30             if ( $c->_locate_static_file ) {
  31                 $c->_debug_msg( "from static directory" )
  32                     if ( $c->config->{static}->{debug} );
  33                 return;
  34             } else {
  35                 $c->_debug_msg( "404: file not found: $path" )
  36                     if ( $c->config->{static}->{debug} );
  37                 $c->res->status( 404 );
  38                 return;
  39             }
  40         }
  41     }
  42
  43     # Does the path have an extension?
  44     if ( $path =~ /.*\.(\S{1,})$/xms ) {
  45         # and does it exist?
  46         return if ( $c->_locate_static_file );
  47     }
  48
  49     return $c->NEXT::ACTUAL::prepare_action(@_);
  50 }
  51
  52 # dispatch takes the file found during prepare_action and serves it
  53 sub dispatch {
  54     my $c = shift;
  55
  56     return if ( $c->res->status != 200 );
  57
  58     if ( $c->_static_file ) {
  59         if ( $c->config->{static}->{no_logs} && $c->log->can('abort') ) {
  60            $c->log->abort( 1 );
  61         }
  62         return $c->_serve_static;
  63     }
  64     else {
  65         return $c->NEXT::ACTUAL::dispatch(@_);
  66     }
  67 }
  68
  69 # finalize serves up final header information
  70 sub finalize {
  71     my $c = shift;
  72
  73     # display all log messages
  74     if ( $c->config->{static}->{debug} && scalar @{$c->_debug_msg} ) {
  75         $c->log->debug( "Static::Simple: " .
  76             join( " ", @{$c->_debug_msg} ) );
  77     }
  78
  79     # return DECLINED when under mod_perl
  80     if ( $c->config->{static}->{use_apache} && $c->_static_apache_mode ) {
  81         my $engine = $c->_static_apache_mode;
  82         no strict 'subs';
  83         if ( $engine == 13 ) {
  84             return Apache::Constants::DECLINED;
  85         }
  86         elsif ( $engine == 19 ) {
  87             return Apache::Const::DECLINED;
  88         }
  89         elsif ( $engine == 20 ) {
  90             return Apache2::Const::DECLINED;
  91         }
  92     }
  93
  94     if ( $c->res->status =~ /^(1\d\d|[23]04)$/xms ) {
  95         $c->res->headers->remove_content_headers;
  96         return $c->finalize_headers;
  97     }
  98
  99     return $c->NEXT::ACTUAL::finalize(@_);
 100 }
 101
 102 sub setup {
 103     my $c = shift;
 104
 105     $c->NEXT::setup(@_);
 106
 107     $c->config->{static}->{dirs} ||= [];
 108     $c->config->{static}->{include_path} ||= [ $c->config->{root} ];
 109     $c->config->{static}->{mime_types} ||= {};
 110     $c->config->{static}->{ignore_extensions} ||= [ qw/tt html xhtml/ ];
 111     $c->config->{static}->{ignore_dirs} ||= [];
 112     $c->config->{static}->{use_apache} ||= 0;
 113     $c->config->{static}->{debug} ||= $c->debug;
 114     if ( ! defined $c->config->{static}->{no_logs} ) {
 115         $c->config->{static}->{no_logs} = 1;
 116     }
 117
 118     # load up a MIME::Types object, only loading types with
 119     # at least 1 file extension
 120     $c->_static_mime_types( MIME::Types->new( only_complete => 1 ) );
 121
 122     # preload the type index hash so it's not built on the first request
 123     $c->_static_mime_types->create_type_index;
 124 }
 125
 126 # Search through all included directories for the static file
 127 # Based on Template Toolkit INCLUDE_PATH code
 128 sub _locate_static_file {
 129     my $c = shift;
 130
 131     my $path = $c->req->path;
 132
 133     my @ipaths = @{ $c->config->{static}->{include_path} };
 134     my $dpaths;
 135     my $count = 64; # maximum number of directories to search
 136
 137     DIR_CHECK:
 138     while ( @ipaths && --$count) {
 139         my $dir = shift @ipaths || next DIR_CHECK;
 140
 141         if ( ref $dir eq 'CODE' ) {
 142             eval { $dpaths = &$dir( $c ) };
 143             if ($@) {
 144                 $c->log->error( "Static::Simple: include_path error: " . $@ );
 145             } else {
 146                 unshift( @ipaths, @$dpaths );
 147                 next DIR_CHECK;
 148             }
 149         } else {
 150             $dir =~ s/\/$//xms;
 151             if ( -d $dir && -f $dir . '/' . $path ) {
 152
 153                 # do we need to ignore the file?
 154                 for my $ignore ( @{ $c->config->{static}->{ignore_dirs} } ) {
 155                     $ignore =~ s{/$}{};
 156                     if ( $path =~ /^$ignore\// ) {
 157                         $c->_debug_msg( "Ignoring directory `$ignore`" )
 158                             if ( $c->config->{static}->{debug} );
 159                         next DIR_CHECK;
 160                     }
 161                 }
 162
 163                 # do we need to ignore based on extension?
 164                 for my $ignore_ext
 165                     ( @{ $c->config->{static}->{ignore_extensions} } ) {
 166                         if ( $path =~ /.*\.${ignore_ext}$/ixms ) {
 167                             $c->_debug_msg( "Ignoring extension `$ignore_ext`" )
 168                                 if ( $c->config->{static}->{debug} );
 169                             next DIR_CHECK;
 170                         }
 171                 }
 172
 173                 $c->_debug_msg( 'Serving ' . $dir . '/' . $path )
 174                     if ( $c->config->{static}->{debug} );
 175                 return $c->_static_file( $dir . '/' . $path );
 176             }
 177         }
 178     }
 179
 180     return;
 181 }
 182
 183 sub _serve_static {
 184     my $c = shift;
 185
 186     my $path = $c->req->path;
 187
 188     # abort if running under mod_perl
 189     # note that we do not use the Apache method if the user has defined
 190     # custom MIME types or is using include paths, as Apache would not know
 191     # about them
 192     APACHE_CHECK:
 193     {
 194         if ( $c->config->{static}->{use_apache} ) {
 195             # check engine version
 196             last APACHE_CHECK unless $c->engine =~ /Apache::MP(\d{2})/xms;
 197             my $engine = $1;
 198
 199             # skip if we have user-defined MIME types
 200             last APACHE_CHECK if keys %{ $c->config->{static}->{mime_types} };
 201
 202             # skip if the file is in a user-defined include path
 203             last APACHE_CHECK if $c->_static_file
 204                 ne $c->config->{root} . '/' . $path;
 205
 206              # check that Apache will serve the correct file
 207              if ( $c->apache->document_root ne $c->config->{root} ) {
 208                  $c->log->warn( 'Static::Simple: Your Apache DocumentRoot'
 209                               . ' must be set to ' . $c->config->{root}
 210                               . ' to use the Apache feature.  Yours is'
 211                               . ' currently ' . $c->apache->document_root
 212                               );
 213              }
 214              else {
 215                  $c->_debug_msg( 'DECLINED to Apache' )
 216                     if ( $c->config->{static}->{debug} );
 217                  $c->_static_apache_mode( $engine );
 218                  return;
 219              }
 220         }
 221     }
 222
 223     my $type = $c->_ext_to_type;
 224
 225     my $full_path = $c->_static_file;
 226     my $stat = stat( $full_path );
 227
 228     # the below code all from C::P::Static
 229     if ( $c->req->headers->if_modified_since ) {
 230         if ( $c->req->headers->if_modified_since == $stat->mtime ) {
 231             $c->res->status( 304 ); # Not Modified
 232             $c->res->headers->remove_content_headers;
 233             return 1;
 234         }
 235     }
 236
 237     my $content = read_file( $full_path );
 238     $c->res->headers->content_type( $type );
 239     $c->res->headers->content_length( $stat->size );
 240     $c->res->headers->last_modified( $stat->mtime );
 241     $c->res->output( $content );
 242     return 1;
 243 }
 244
 245 # looks up the correct MIME type for the current file extension
 246 sub _ext_to_type {
 247     my $c = shift;
 248     my $path = $c->req->path;
 249
 250     if ( $path =~ /.*\.(\S{1,})$/xms ) {
 251         my $ext = $1;
 252         my $user_types = $c->config->{static}->{mime_types};
 253         my $type = $user_types->{$ext}
 254                 || $c->_static_mime_types->mimeTypeOf( $ext );
 255         if ( $type ) {
 256             $c->_debug_msg( "as $type" )
 257                 if ( $c->config->{static}->{debug} );
 258             return $type;
 259         }
 260         else {
 261             $c->_debug_msg( "as text/plain (unknown extension $ext)" )
 262                 if ( $c->config->{static}->{debug} );
 263             return 'text/plain';
 264         }
 265     }
 266     else {
 267         $c->_debug_msg( 'as text/plain (no extension)' )
 268             if ( $c->config->{static}->{debug} );
 269         return 'text/plain';
 270     }
 271 }
 272
 273 sub _debug_msg {
 274     my ( $c, $msg ) = @_;
 275
 276     if ( !defined $c->_static_debug_message ) {
 277         $c->_static_debug_message( [] );
 278     }
 279
 280     if ( $msg ) {
 281         push @{ $c->_static_debug_message }, $msg;
 282     }
 283
 284     return $c->_static_debug_message;
 285 }
 286
 287 1;
 288 __END__
 289
 290 =head1 NAME
 291
 292 Catalyst::Plugin::Static::Simple - Make serving static pages painless.
 293
 294 =head1 SYNOPSIS
 295
 296     use Catalyst;
 297     MyApp->setup( qw/Static::Simple/ );
 298
 299 =head1 DESCRIPTION
 300
 301 The Static::Simple plugin is designed to make serving static content in your
 302 application during development quick and easy, without requiring a single
 303 line of code from you.
 304
 305 It will detect static files used in your application by looking for file
 306 extensions in the URI.  By default, you can simply load this plugin and it
 307 will immediately begin serving your static files with the correct MIME type.
 308 The light-weight MIME::Types module is used to map file extensions to
 309 IANA-registered MIME types.
 310
 311 Note that actions mapped to paths using periods (.) will still operate
 312 properly.
 313
 314 You may further tweak the operation by adding configuration options, described
 315 below.
 316
 317 =head1 ADVANCED CONFIGURATION
 318
 319 Configuration is completely optional and is specified within
 320 MyApp->config->{static}.  If you use any of these options, the module will
 321 probably feel less "simple" to you!
 322
 323 =head2 Aborting request logging
 324
 325 Since Catalyst 5.50, there has been added support for dropping logging for a
 326 request. This is enabled by default for static files, as static requests tend
 327 to clutter the log output.  However, if you want logging of static requests,
 328 you can enable it by setting MyApp->config->{static}->{no_logs} to 0.
 329
 330 =head2 Forcing directories into static mode
 331
 332 Define a list of top-level directories beneath your 'root' directory that
 333 should always be served in static mode.  Regular expressions may be
 334 specified using qr//.
 335
 336     MyApp->config->{static}->{dirs} = [
 337         'static',
 338         qr/^(images|css)/,
 339     ];
 340
 341 =head2 Including additional directories
 342
 343 You may specify a list of directories in which to search for your static
 344 files.  The directories will be searched in order and will return the first
 345 file found.  Note that your root directory is B<not> automatically added to
 346 the search path when you specify an include_path.  You should use
 347 MyApp->config->{root} to add it.
 348
 349     MyApp->config->{static}->{include_path} = [
 350         '/path/to/overlay',
 351         \&incpath_generator,
 352         MyApp->config->{root}
 353     ];
 354
 355 With the above setting, a request for the file /images/logo.jpg will search
 356 for the following files, returning the first one found:
 357
 358     /path/to/overlay/images/logo.jpg
 359     /dynamic/path/images/logo.jpg
 360     /your/app/home/root/images/logo.jpg
 361
 362 The include path can contain a subroutine reference to dynamically return a
 363 list of available directories.  This method will receive the $c object as a
 364 parameter and should return a reference to a list of directories.  Errors can
 365 be reported using die().  This method will be called every time a file is
 366 requested that appears to be a static file (i.e. it has an extension).
 367
 368 For example:
 369
 370     sub incpath_generator {
 371         my $c = shift;
 372
 373         if ( $c->session->{customer_dir} ) {
 374             return [ $c->session->{customer_dir} ];
 375         } else {
 376             die "No customer dir defined.";
 377         }
 378     }
 379
 380 =head2 Ignoring certain types of files
 381
 382 There are some file types you may not wish to serve as static files.  Most
 383 important in this category are your raw template files.  By default, files
 384 with the extensions tt, html, and xhtml will be ignored by Static::Simple in
 385 the interest of security.  If you wish to define your own extensions to
 386 ignore, use the ignore_extensions option:
 387
 388     MyApp->config->{static}->{ignore_extensions} = [ qw/tt html xhtml/ ];
 389
 390 =head2 Ignoring entire directories
 391
 392 To prevent an entire directory from being served statically, you can use the
 393 ignore_dirs option.  This option contains a list of relative directory paths
 394 to ignore.  If using include_path, the path will be checked against every
 395 included path.
 396
 397     MyApp->config->{static}->{ignore_dirs} = [ qw/tmpl css/ ];
 398
 399 For example, if combined with the above include_path setting, this
 400 ignore_dirs value will ignore the following directories if they exist:
 401
 402     /path/to/overlay/tmpl
 403     /path/to/overlay/css
 404     /dynamic/path/tmpl
 405     /dynamic/path/css
 406     /your/app/home/root/tmpl
 407     /your/app/home/root/css
 408
 409 =head2 Custom MIME types
 410
 411 To override or add to the default MIME types set by the MIME::Types module,
 412 you may enter your own extension to MIME type mapping.
 413
 414     MyApp->config->{static}->{mime_types} = {
 415         jpg => 'image/jpg',
 416         png => 'image/png',
 417     };
 418
 419 =head2 Apache integration and performance
 420
 421 Optionally, when running under mod_perl, Static::Simple can return DECLINED
 422 on static files to allow Apache to serve the file.  A check is first done to
 423 make sure that Apache's DocumentRoot matches your Catalyst root, and that you
 424 are not using any custom MIME types or multiple roots.  To enable the Apache
 425 support, you can set the following option.
 426
 427     MyApp->config->{static}->{use_apache} = 1;
 428
 429 By default this option is disabled because after several benchmarks it
 430 appears that just serving the file from Catalyst is the better option.  On a
 431 3K file, Catalyst appears to be around 25% faster, and is 42% faster on a 10K
 432 file.  My benchmarking was done using the following 'siege' command, so other
 433 benchmarks would be welcome!
 434
 435     siege -u http://server/static/css/10K.css -b -t 1M -c 1
 436
 437 For best static performance, you should still serve your static files directly
 438 from Apache by defining a Location block similar to the following:
 439
 440     <Location /static>
 441         SetHandler default-handler
 442     </Location>
 443
 444 =head2 Bypassing other plugins
 445
 446 This plugin checks for a static file in the prepare_action stage.  If the
 447 request is for a static file, it will bypass all remaining prepare_action
 448 steps.  This means that by placing Static::Simple before all other plugins,
 449 they will not execute when a static file is found.  This can be helpful by
 450 skipping session cookie checks for example.  Or, if you want some plugins
 451 to run even on static files, list them before Static::Simple.
 452
 453 Currently, work done by plugins in any other prepare method will execute
 454 normally.
 455
 456 =head2 Debugging information
 457
 458 Enable additional debugging information printed in the Catalyst log.  This
 459 is automatically enabled when running Catalyst in -Debug mode.
 460
 461     MyApp->config->{static}->{debug} = 1;
 462
 463 =head1 SEE ALSO
 464
 465 L<Catalyst>, L<Catalyst::Plugin::Static>,
 466 L<http://www.iana.org/assignments/media-types/>
 467
 468 =head1 AUTHOR
 469
 470 Andy Grundman, <andy@hybridized.org>
 471
 472 =head1 CONTRIBUTORS
 473
 474 Marcus Ramberg, <mramberg@cpan.org>
 475
 476 =head1 THANKS
 477
 478 The authors of Catalyst::Plugin::Static:
 479
 480     Sebastian Riedel
 481     Christian Hansen
 482     Marcus Ramberg
 483
 484 For the include_path code from Template Toolkit:
 485
 486     Andy Wardley
 487
 488 =head1 COPYRIGHT
 489
 490 This program is free software, you can redistribute it and/or modify it under
 491 the same terms as Perl itself.
 492
 493 =cut