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