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