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 IO::File;
   8 use MIME::Types;
   9 use NEXT;
  10
  11 if ( Catalyst->VERSION le '5.33' ) {
  12     require File::Slurp;
  13 }
  14
  15 our $VERSION = '0.11';
  16
  17 __PACKAGE__->mk_classdata( qw/_static_mime_types/ );
  18 __PACKAGE__->mk_accessors( qw/_static_file
  19                               _static_debug_message/ );
  20
  21 # prepare_action is used to first check if the request path is a static file.
  22 # If so, we skip all other prepare_action steps to improve performance.
  23 sub prepare_action {
  24     my $c = shift;
  25     my $path = $c->req->path;
  26
  27     # is the URI in a static-defined path?
  28     foreach my $dir ( @{ $c->config->{static}->{dirs} } ) {
  29         my $re = ( $dir =~ /^qr\//xms ) ? eval $dir : qr/^${dir}/;
  30         if ($@) {
  31             $c->error( "Error compiling static dir regex '$dir': $@" );
  32         }
  33         if ( $path =~ $re ) {
  34             if ( $c->_locate_static_file ) {
  35                 $c->_debug_msg( 'from static directory' )
  36                     if ( $c->config->{static}->{debug} );
  37                 return;
  38             } else {
  39                 $c->_debug_msg( "404: file not found: $path" )
  40                     if ( $c->config->{static}->{debug} );
  41                 $c->res->status( 404 );
  42                 return;
  43             }
  44         }
  45     }
  46
  47     # Does the path have an extension?
  48     if ( $path =~ /.*\.(\S{1,})$/xms ) {
  49         # and does it exist?
  50         return if ( $c->_locate_static_file );
  51     }
  52
  53     return $c->NEXT::ACTUAL::prepare_action(@_);
  54 }
  55
  56 # dispatch takes the file found during prepare_action and serves it
  57 sub dispatch {
  58     my $c = shift;
  59
  60     return if ( $c->res->status != 200 );
  61
  62     if ( $c->_static_file ) {
  63         if ( $c->config->{static}->{no_logs} && $c->log->can('abort') ) {
  64            $c->log->abort( 1 );
  65         }
  66         return $c->_serve_static;
  67     }
  68     else {
  69         return $c->NEXT::ACTUAL::dispatch(@_);
  70     }
  71 }
  72
  73 # finalize serves up final header information
  74 sub finalize {
  75     my $c = shift;
  76
  77     # display all log messages
  78     if ( $c->config->{static}->{debug} && scalar @{$c->_debug_msg} ) {
  79         $c->log->debug( 'Static::Simple: ' . 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->body( $content );
 196     }
 197     else {
 198         # new method, pass an IO::File object to body
 199         my $fh = IO::File->new( $full_path, 'r' );
 200         if ( defined $fh ) {
 201             $fh->binmode;
 202             $c->res->body( $fh );
 203         }
 204         else {
 205             Catalyst::Exception->throw(
 206                 message => "Unable to open $full_path for reading" );
 207         }
 208     }
 209
 210     return 1;
 211 }
 212
 213 # looks up the correct MIME type for the current file extension
 214 sub _ext_to_type {
 215     my $c = shift;
 216     my $path = $c->req->path;
 217
 218     if ( $path =~ /.*\.(\S{1,})$/xms ) {
 219         my $ext = $1;
 220         my $user_types = $c->config->{static}->{mime_types};
 221         my $type = $user_types->{$ext}
 222                 || $c->_static_mime_types->mimeTypeOf( $ext );
 223         if ( $type ) {
 224             $c->_debug_msg( "as $type" )
 225                 if ( $c->config->{static}->{debug} );
 226             return ( ref $type ) ? $type->type : $type;
 227         }
 228         else {
 229             $c->_debug_msg( "as text/plain (unknown extension $ext)" )
 230                 if ( $c->config->{static}->{debug} );
 231             return 'text/plain';
 232         }
 233     }
 234     else {
 235         $c->_debug_msg( 'as text/plain (no extension)' )
 236             if ( $c->config->{static}->{debug} );
 237         return 'text/plain';
 238     }
 239 }
 240
 241 sub _debug_msg {
 242     my ( $c, $msg ) = @_;
 243
 244     if ( !defined $c->_static_debug_message ) {
 245         $c->_static_debug_message( [] );
 246     }
 247
 248     if ( $msg ) {
 249         push @{ $c->_static_debug_message }, $msg;
 250     }
 251
 252     return $c->_static_debug_message;
 253 }
 254
 255 1;
 256 __END__
 257
 258 =head1 NAME
 259
 260 Catalyst::Plugin::Static::Simple - Make serving static pages painless.
 261
 262 =head1 SYNOPSIS
 263
 264     use Catalyst;
 265     MyApp->setup( qw/Static::Simple/ );
 266
 267 =head1 DESCRIPTION
 268
 269 The Static::Simple plugin is designed to make serving static content in your
 270 application during development quick and easy, without requiring a single
 271 line of code from you.
 272
 273 It will detect static files used in your application by looking for file
 274 extensions in the URI.  By default, you can simply load this plugin and it
 275 will immediately begin serving your static files with the correct MIME type.
 276 The light-weight MIME::Types module is used to map file extensions to
 277 IANA-registered MIME types.
 278
 279 Note that actions mapped to paths using periods (.) will still operate
 280 properly.
 281
 282 You may further tweak the operation by adding configuration options, described
 283 below.
 284
 285 =head1 ADVANCED CONFIGURATION
 286
 287 Configuration is completely optional and is specified within
 288 MyApp->config->{static}.  If you use any of these options, the module will
 289 probably feel less "simple" to you!
 290
 291 =head2 Aborting request logging
 292
 293 Since Catalyst 5.50, there has been added support for dropping logging for a
 294 request. This is enabled by default for static files, as static requests tend
 295 to clutter the log output.  However, if you want logging of static requests,
 296 you can enable it by setting MyApp->config->{static}->{no_logs} to 0.
 297
 298 =head2 Forcing directories into static mode
 299
 300 Define a list of top-level directories beneath your 'root' directory that
 301 should always be served in static mode.  Regular expressions may be
 302 specified using qr//.
 303
 304     MyApp->config->{static}->{dirs} = [
 305         'static',
 306         qr/^(images|css)/,
 307     ];
 308
 309 =head2 Including additional directories
 310
 311 You may specify a list of directories in which to search for your static
 312 files.  The directories will be searched in order and will return the first
 313 file found.  Note that your root directory is B<not> automatically added to
 314 the search path when you specify an include_path.  You should use
 315 MyApp->config->{root} to add it.
 316
 317     MyApp->config->{static}->{include_path} = [
 318         '/path/to/overlay',
 319         \&incpath_generator,
 320         MyApp->config->{root}
 321     ];
 322
 323 With the above setting, a request for the file /images/logo.jpg will search
 324 for the following files, returning the first one found:
 325
 326     /path/to/overlay/images/logo.jpg
 327     /dynamic/path/images/logo.jpg
 328     /your/app/home/root/images/logo.jpg
 329
 330 The include path can contain a subroutine reference to dynamically return a
 331 list of available directories.  This method will receive the $c object as a
 332 parameter and should return a reference to a list of directories.  Errors can
 333 be reported using die().  This method will be called every time a file is
 334 requested that appears to be a static file (i.e. it has an extension).
 335
 336 For example:
 337
 338     sub incpath_generator {
 339         my $c = shift;
 340
 341         if ( $c->session->{customer_dir} ) {
 342             return [ $c->session->{customer_dir} ];
 343         } else {
 344             die "No customer dir defined.";
 345         }
 346     }
 347
 348 =head2 Ignoring certain types of files
 349
 350 There are some file types you may not wish to serve as static files.  Most
 351 important in this category are your raw template files.  By default, files
 352 with the extensions tt, tt2, html, and xhtml will be ignored by Static::Simple
 353 in the interest of security.  If you wish to define your own extensions to
 354 ignore, use the ignore_extensions option:
 355
 356     MyApp->config->{static}->{ignore_extensions} = [ qw/tt tt2 html xhtml/ ];
 357
 358 =head2 Ignoring entire directories
 359
 360 To prevent an entire directory from being served statically, you can use the
 361 ignore_dirs option.  This option contains a list of relative directory paths
 362 to ignore.  If using include_path, the path will be checked against every
 363 included path.
 364
 365     MyApp->config->{static}->{ignore_dirs} = [ qw/tmpl css/ ];
 366
 367 For example, if combined with the above include_path setting, this
 368 ignore_dirs value will ignore the following directories if they exist:
 369
 370     /path/to/overlay/tmpl
 371     /path/to/overlay/css
 372     /dynamic/path/tmpl
 373     /dynamic/path/css
 374     /your/app/home/root/tmpl
 375     /your/app/home/root/css
 376
 377 =head2 Custom MIME types
 378
 379 To override or add to the default MIME types set by the MIME::Types module,
 380 you may enter your own extension to MIME type mapping.
 381
 382     MyApp->config->{static}->{mime_types} = {
 383         jpg => 'image/jpg',
 384         png => 'image/png',
 385     };
 386
 387 =head2 Bypassing other plugins
 388
 389 This plugin checks for a static file in the prepare_action stage.  If the
 390 request is for a static file, it will bypass all remaining prepare_action
 391 steps.  This means that by placing Static::Simple before all other plugins,
 392 they will not execute when a static file is found.  This can be helpful by
 393 skipping session cookie checks for example.  Or, if you want some plugins
 394 to run even on static files, list them before Static::Simple.
 395
 396 Currently, work done by plugins in any other prepare method will execute
 397 normally.
 398
 399 =head2 Debugging information
 400
 401 Enable additional debugging information printed in the Catalyst log.  This
 402 is automatically enabled when running Catalyst in -Debug mode.
 403
 404     MyApp->config->{static}->{debug} = 1;
 405
 406 =head1 USING WITH APACHE
 407
 408 While Static::Simple will work just fine serving files through Catalyst in
 409 mod_perl, for increased performance, you may wish to have Apache handle the
 410 serving of your static files.  To do this, simply use a dedicated directory
 411 for your static files and configure an Apache Location block for that
 412 directory.  This approach is recommended for production installations.
 413
 414     <Location /static>
 415         SetHandler default-handler
 416     </Location>
 417
 418 =head1 SEE ALSO
 419
 420 L<Catalyst>, L<Catalyst::Plugin::Static>,
 421 L<http://www.iana.org/assignments/media-types/>
 422
 423 =head1 AUTHOR
 424
 425 Andy Grundman, <andy@hybridized.org>
 426
 427 =head1 CONTRIBUTORS
 428
 429 Marcus Ramberg, <mramberg@cpan.org>
 430
 431 =head1 THANKS
 432
 433 The authors of Catalyst::Plugin::Static:
 434
 435     Sebastian Riedel
 436     Christian Hansen
 437     Marcus Ramberg
 438
 439 For the include_path code from Template Toolkit:
 440
 441     Andy Wardley
 442
 443 =head1 COPYRIGHT
 444
 445 This program is free software, you can redistribute it and/or modify it under
 446 the same terms as Perl itself.
 447
 448 =cut