lib/Catalyst/Plugin/Static/Simple.pm

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