lib/Catalyst/Plugin/Static/Simple.pm

   1 package Catalyst::Plugin::Static::Simple;
   2
   3 use Moose::Role;
   4 use File::stat;
   5 use File::Spec ();
   6 use IO::File ();
   7 use MIME::Types ();
   8 use MooseX::Types::Moose qw/ArrayRef Str/;
   9 use Catalyst::Utils;
  10 use namespace::autoclean;
  11
  12 our $VERSION = '0.30';
  13
  14 has _static_file => ( is => 'rw' );
  15 has _static_debug_message => ( is => 'rw', isa => ArrayRef[Str] );
  16
  17 before prepare_action => sub {
  18     my $c = shift;
  19     my $path = $c->req->path;
  20     my $config = $c->config->{'Plugin::Static::Simple'};
  21
  22     $path =~ s/%([0-9A-Fa-f]{2})/chr(hex($1))/eg;
  23
  24     # is the URI in a static-defined path?
  25     foreach my $dir ( @{ $config->{dirs} } ) {
  26         my $dir_re = quotemeta $dir;
  27
  28         # strip trailing slashes, they'll be added in our regex
  29         $dir_re =~ s{/$}{};
  30
  31         my $re;
  32
  33         if ( $dir =~ m{^qr/}xms ) {
  34             $re = eval $dir;
  35
  36             if ($@) {
  37                 $c->error( "Error compiling static dir regex '$dir': $@" );
  38             }
  39         }
  40         else {
  41             $re = qr{^${dir_re}/};
  42         }
  43
  44         if ( $path =~ $re ) {
  45             if ( $c->_locate_static_file( $path, 1 ) ) {
  46                 $c->_debug_msg( 'from static directory' )
  47                     if $config->{debug};
  48             } else {
  49                 $c->_debug_msg( "404: file not found: $path" )
  50                     if $config->{debug};
  51                 $c->res->status( 404 );
  52                 $c->res->content_type( 'text/html' );
  53             }
  54         }
  55     }
  56
  57     # Does the path have an extension?
  58     if ( $path =~ /.*\.(\S{1,})$/xms ) {
  59         # and does it exist?
  60         $c->_locate_static_file( $path );
  61     }
  62 };
  63
  64 around dispatch => sub {
  65     my $orig = shift;
  66     my $c = shift;
  67
  68     return if ( $c->res->status != 200 );
  69
  70     if ( $c->_static_file ) {
  71         if ( $c->config->{'Plugin::Static::Simple'}->{no_logs} && $c->log->can('abort') ) {
  72            $c->log->abort( 1 );
  73         }
  74         return $c->_serve_static;
  75     }
  76     else {
  77         return $c->$orig(@_);
  78     }
  79 };
  80
  81 before finalize => sub {
  82     my $c = shift;
  83
  84     # display all log messages
  85     if ( $c->config->{'Plugin::Static::Simple'}->{debug} && scalar @{$c->_debug_msg} ) {
  86         $c->log->debug( 'Static::Simple: ' . join q{ }, @{$c->_debug_msg} );
  87     }
  88 };
  89
  90 before setup_finalize => sub {
  91     my $c = shift;
  92
  93     $c->log->warn("Deprecated 'static' config key used, please use the key 'Plugin::Static::Simple' instead")
  94         if exists $c->config->{static};
  95     my $config
  96         = $c->config->{'Plugin::Static::Simple'}
  97         = $c->config->{'static'}
  98         = Catalyst::Utils::merge_hashes(
  99             $c->config->{'Plugin::Static::Simple'} || {},
 100             $c->config->{static} || {}
 101         );
 102
 103     $config->{dirs} ||= [];
 104     $config->{include_path} ||= [ $c->config->{root} ];
 105     $config->{mime_types} ||= {};
 106     $config->{ignore_extensions} ||= [ qw/tmpl tt tt2 html xhtml/ ];
 107     $config->{ignore_dirs} ||= [];
 108     $config->{debug} ||= $c->debug;
 109     $config->{no_logs} = 1 unless defined $config->{no_logs};
 110     $config->{no_logs} = 0 if $config->{logging};
 111
 112     # load up a MIME::Types object, only loading types with
 113     # at least 1 file extension
 114     $config->{mime_types_obj} = MIME::Types->new( only_complete => 1 );
 115
 116     # preload the type index hash so it's not built on the first request
 117     $config->{mime_types_obj}->create_type_index;
 118 };
 119
 120 # Search through all included directories for the static file
 121 # Based on Template Toolkit INCLUDE_PATH code
 122 sub _locate_static_file {
 123     my ( $c, $path, $in_static_dir ) = @_;
 124
 125     $path = File::Spec->catdir(
 126         File::Spec->no_upwards( File::Spec->splitdir( $path ) )
 127     );
 128
 129     my $config = $c->config->{'Plugin::Static::Simple'};
 130     my @ipaths = @{ $config->{include_path} };
 131     my $dpaths;
 132     my $count = 64; # maximum number of directories to search
 133
 134     DIR_CHECK:
 135     while ( @ipaths && --$count) {
 136         my $dir = shift @ipaths || next DIR_CHECK;
 137
 138         if ( ref $dir eq 'CODE' ) {
 139             eval { $dpaths = &$dir( $c ) };
 140             if ($@) {
 141                 $c->log->error( 'Static::Simple: include_path error: ' . $@ );
 142             } else {
 143                 unshift @ipaths, @$dpaths;
 144                 next DIR_CHECK;
 145             }
 146         } else {
 147             $dir =~ s/(\/|\\)$//xms;
 148             if ( -d $dir && -f $dir . '/' . $path ) {
 149
 150                 # Don't ignore any files in static dirs defined with 'dirs'
 151                 unless ( $in_static_dir ) {
 152                     # do we need to ignore the file?
 153                     for my $ignore ( @{ $config->{ignore_dirs} } ) {
 154                         $ignore =~ s{(/|\\)$}{};
 155                         if ( $path =~ /^$ignore(\/|\\)/ ) {
 156                             $c->_debug_msg( "Ignoring directory `$ignore`" )
 157                                 if $config->{debug};
 158                             next DIR_CHECK;
 159                         }
 160                     }
 161
 162                     # do we need to ignore based on extension?
 163                     for my $ignore_ext ( @{ $config->{ignore_extensions} } ) {
 164                         if ( $path =~ /.*\.${ignore_ext}$/ixms ) {
 165                             $c->_debug_msg( "Ignoring extension `$ignore_ext`" )
 166                                 if $config->{debug};
 167                             next DIR_CHECK;
 168                         }
 169                     }
 170                 }
 171
 172                 $c->_debug_msg( 'Serving ' . $dir . '/' . $path )
 173                     if $config->{debug};
 174                 return $c->_static_file( $dir . '/' . $path );
 175             }
 176         }
 177     }
 178
 179     return;
 180 }
 181
 182 sub _serve_static {
 183     my $c = shift;
 184     my $config = $c->config->{'Plugin::Static::Simple'};
 185
 186     my $full_path = shift || $c->_static_file;
 187     my $type      = $c->_ext_to_type( $full_path );
 188     my $stat      = stat $full_path;
 189
 190     $c->res->headers->content_type( $type );
 191     $c->res->headers->content_length( $stat->size );
 192     $c->res->headers->last_modified( $stat->mtime );
 193     # Tell Firefox & friends its OK to cache, even over SSL:
 194     $c->res->headers->header('Cache-control' => 'public');
 195     # Optionally, set a fixed expiry time:
 196     if ($config->{expires}) {
 197         $c->res->headers->expires(time() + $config->{expires});
 198     }
 199
 200     my $fh = IO::File->new( $full_path, 'r' );
 201     if ( defined $fh ) {
 202         binmode $fh;
 203         $c->res->body( $fh );
 204     }
 205     else {
 206         Catalyst::Exception->throw(
 207             message => "Unable to open $full_path for reading" );
 208     }
 209
 210     return 1;
 211 }
 212
 213 sub serve_static_file {
 214     my ( $c, $full_path ) = @_;
 215
 216     my $config = $c->config->{'Plugin::Static::Simple'};
 217
 218     if ( -e $full_path ) {
 219         $c->_debug_msg( "Serving static file: $full_path" )
 220             if $config->{debug};
 221     }
 222     else {
 223         $c->_debug_msg( "404: file not found: $full_path" )
 224             if $config->{debug};
 225         $c->res->status( 404 );
 226         $c->res->content_type( 'text/html' );
 227         return;
 228     }
 229
 230     $c->_serve_static( $full_path );
 231 }
 232
 233 # looks up the correct MIME type for the current file extension
 234 sub _ext_to_type {
 235     my ( $c, $full_path ) = @_;
 236
 237     my $config = $c->config->{'Plugin::Static::Simple'};
 238
 239     if ( $full_path =~ /.*\.(\S{1,})$/xms ) {
 240         my $ext = $1;
 241         my $type = $config->{mime_types}{$ext}
 242             || $config->{mime_types_obj}->mimeTypeOf( $ext );
 243         if ( $type ) {
 244             $c->_debug_msg( "as $type" ) if $config->{debug};
 245             return ( ref $type ) ? $type->type : $type;
 246         }
 247         else {
 248             $c->_debug_msg( "as text/plain (unknown extension $ext)" )
 249                 if $config->{debug};
 250             return 'text/plain';
 251         }
 252     }
 253     else {
 254         $c->_debug_msg( 'as text/plain (no extension)' )
 255             if $config->{debug};
 256         return 'text/plain';
 257     }
 258 }
 259
 260 sub _debug_msg {
 261     my ( $c, $msg ) = @_;
 262
 263     if ( !defined $c->_static_debug_message ) {
 264         $c->_static_debug_message( [] );
 265     }
 266
 267     if ( $msg ) {
 268         push @{ $c->_static_debug_message }, $msg;
 269     }
 270
 271     return $c->_static_debug_message;
 272 }
 273
 274 1;
 275 __END__
 276
 277 =head1 NAME
 278
 279 Catalyst::Plugin::Static::Simple - Make serving static pages painless.
 280
 281 =head1 SYNOPSIS
 282
 283     package MyApp;
 284     use Catalyst qw/ Static::Simple /;
 285     MyApp->setup;
 286     # that's it; static content is automatically served by Catalyst
 287     # from the application's root directory, though you can configure
 288     # things or bypass Catalyst entirely in a production environment
 289     #
 290     # one caveat: the files must be served from an absolute path
 291     # (i.e. /images/foo.png)
 292
 293 =head1 DESCRIPTION
 294
 295 The Static::Simple plugin is designed to make serving static content in
 296 your application during development quick and easy, without requiring a
 297 single line of code from you.
 298
 299 This plugin detects static files by looking at the file extension in the
 300 URL (such as B<.css> or B<.png> or B<.js>). The plugin uses the
 301 lightweight L<MIME::Types> module to map file extensions to
 302 IANA-registered MIME types, and will serve your static files with the
 303 correct MIME type directly to the browser, without being processed
 304 through Catalyst.
 305
 306 Note that actions mapped to paths using periods (.) will still operate
 307 properly.
 308
 309 If the plugin can not find the file, the request is dispatched to your
 310 application instead. This means you are responsible for generating a
 311 C<404> error if your applicaton can not process the request:
 312
 313    # handled by static::simple, not dispatched to your application
 314    /images/exists.png
 315
 316    # static::simple will not find the file and let your application
 317    # handle the request. You are responsible for generating a file
 318    # or returning a 404 error
 319    /images/does_not_exist.png
 320
 321 Though Static::Simple is designed to work out-of-the-box, you can tweak
 322 the operation by adding various configuration options. In a production
 323 environment, you will probably want to use your webserver to deliver
 324 static content; for an example see L<USING WITH APACHE>, below.
 325
 326 =head1 DEFAULT BEHAVIOUR
 327
 328 By default, Static::Simple will deliver all files having extensions
 329 (that is, bits of text following a period (C<.>)), I<except> files
 330 having the extensions C<tmpl>, C<tt>, C<tt2>, C<html>, and
 331 C<xhtml>. These files, and all files without extensions, will be
 332 processed through Catalyst. If L<MIME::Types> doesn't recognize an
 333 extension, it will be served as C<text/plain>.
 334
 335 To restate: files having the extensions C<tmpl>, C<tt>, C<tt2>, C<html>,
 336 and C<xhtml> I<will not> be served statically by default, they will be
 337 processed by Catalyst. Thus if you want to use C<.html> files from
 338 within a Catalyst app as static files, you need to change the
 339 configuration of Static::Simple. Note also that files having any other
 340 extension I<will> be served statically, so if you're using any other
 341 extension for template files, you should also change the configuration.
 342
 343 Logging of static files is turned off by default.
 344
 345 =head1 ADVANCED CONFIGURATION
 346
 347 Configuration is completely optional and is specified within
 348 C<MyApp-E<gt>config-E<gt>{static}>.  If you use any of these options,
 349 this module will probably feel less "simple" to you!
 350
 351 =head2 Enabling request logging
 352
 353 Since Catalyst 5.50, logging of static requests is turned off by
 354 default; static requests tend to clutter the log output and rarely
 355 reveal anything useful. However, if you want to enable logging of static
 356 requests, you can do so by setting
 357 C<MyApp-E<gt>config-E<gt>{static}-E<gt>{logging}> to 1.
 358
 359 =head2 Forcing directories into static mode
 360
 361 Define a list of top-level directories beneath your 'root' directory
 362 that should always be served in static mode.  Regular expressions may be
 363 specified using C<qr//>.
 364
 365     MyApp->config(
 366         static => {
 367             dirs => [
 368                 'static',
 369                 qr/^(images|css)/,
 370             ],
 371         }
 372     );
 373
 374 =head2 Including additional directories
 375
 376 You may specify a list of directories in which to search for your static
 377 files. The directories will be searched in order and will return the
 378 first file found. Note that your root directory is B<not> automatically
 379 added to the search path when you specify an C<include_path>. You should
 380 use C<MyApp-E<gt>config-E<gt>{root}> to add it.
 381
 382     MyApp->config(
 383         static => {
 384             include_path => [
 385                 '/path/to/overlay',
 386                 \&incpath_generator,
 387                 MyApp->config->{root},
 388             ],
 389         },
 390     );
 391
 392 With the above setting, a request for the file C</images/logo.jpg> will search
 393 for the following files, returning the first one found:
 394
 395     /path/to/overlay/images/logo.jpg
 396     /dynamic/path/images/logo.jpg
 397     /your/app/home/root/images/logo.jpg
 398
 399 The include path can contain a subroutine reference to dynamically return a
 400 list of available directories.  This method will receive the C<$c> object as a
 401 parameter and should return a reference to a list of directories.  Errors can
 402 be reported using C<die()>.  This method will be called every time a file is
 403 requested that appears to be a static file (i.e. it has an extension).
 404
 405 For example:
 406
 407     sub incpath_generator {
 408         my $c = shift;
 409
 410         if ( $c->session->{customer_dir} ) {
 411             return [ $c->session->{customer_dir} ];
 412         } else {
 413             die "No customer dir defined.";
 414         }
 415     }
 416
 417 =head2 Ignoring certain types of files
 418
 419 There are some file types you may not wish to serve as static files.
 420 Most important in this category are your raw template files.  By
 421 default, files with the extensions C<tmpl>, C<tt>, C<tt2>, C<html>, and
 422 C<xhtml> will be ignored by Static::Simple in the interest of security.
 423 If you wish to define your own extensions to ignore, use the
 424 C<ignore_extensions> option:
 425
 426     MyApp->config(
 427         static => {
 428             ignore_extensions => [ qw/html asp php/ ],
 429         },
 430     );
 431
 432 =head2 Ignoring entire directories
 433
 434 To prevent an entire directory from being served statically, you can use
 435 the C<ignore_dirs> option.  This option contains a list of relative
 436 directory paths to ignore.  If using C<include_path>, the path will be
 437 checked against every included path.
 438
 439     MyApp->config(
 440         static => {
 441             ignore_dirs => [ qw/tmpl css/ ],
 442         },
 443     );
 444
 445 For example, if combined with the above C<include_path> setting, this
 446 C<ignore_dirs> value will ignore the following directories if they exist:
 447
 448     /path/to/overlay/tmpl
 449     /path/to/overlay/css
 450     /dynamic/path/tmpl
 451     /dynamic/path/css
 452     /your/app/home/root/tmpl
 453     /your/app/home/root/css
 454
 455 =head2 Custom MIME types
 456
 457 To override or add to the default MIME types set by the L<MIME::Types>
 458 module, you may enter your own extension to MIME type mapping.
 459
 460     MyApp->config(
 461         static => {
 462             mime_types => {
 463                 jpg => 'image/jpg',
 464                 png => 'image/png',
 465             },
 466         },
 467     );
 468
 469 =head2 Controlling caching with Expires header
 470
 471 The files served by Static::Simple will have a Last-Modified header set,
 472 which allows some browsers to cache them for a while. However if you want
 473 to explicitly set an Expires header, such as to allow proxies to cache your
 474 static content, then you can do so by setting the "expires" config option.
 475
 476 The value indicates the number of seconds after access time to allow caching.
 477 So a value of zero really means "don't cache at all", and any higher values
 478 will keep the file around for that long.
 479
 480     MyApp->config(
 481         static => {
 482             expires => 3600, # Caching allowed for one hour.
 483         },
 484     );
 485
 486 =head2 Compatibility with other plugins
 487
 488 Since version 0.12, Static::Simple plays nice with other plugins.  It no
 489 longer short-circuits the C<prepare_action> stage as it was causing too
 490 many compatibility issues with other plugins.
 491
 492 =head2 Debugging information
 493
 494 Enable additional debugging information printed in the Catalyst log.  This
 495 is automatically enabled when running Catalyst in -Debug mode.
 496
 497     MyApp->config(
 498         static => {
 499             debug => 1,
 500         },
 501     );
 502
 503 =head1 USING WITH APACHE
 504
 505 While Static::Simple will work just fine serving files through Catalyst
 506 in mod_perl, for increased performance you may wish to have Apache
 507 handle the serving of your static files directly. To do this, simply use
 508 a dedicated directory for your static files and configure an Apache
 509 Location block for that directory  This approach is recommended for
 510 production installations.
 511
 512     <Location /myapp/static>
 513         SetHandler default-handler
 514     </Location>
 515
 516 Using this approach Apache will bypass any handling of these directories
 517 through Catalyst. You can leave Static::Simple as part of your
 518 application, and it will continue to function on a development server,
 519 or using Catalyst's built-in server.
 520
 521 In practice, your Catalyst application is probably (i.e. should be)
 522 structured in the recommended way (i.e., that generated by bootstrapping
 523 the application with the C<catalyst.pl> script, with a main directory
 524 under which is a C<lib/> directory for module files and a C<root/>
 525 directory for templates and static files). Thus, unless you break up
 526 this structure when deploying your app by moving the static files to a
 527 different location in your filesystem, you will need to use an Alias
 528 directive in Apache to point to the right place. You will then need to
 529 add a Directory block to give permission for Apache to serve these
 530 files. The final configuration will look something like this:
 531
 532     Alias /myapp/static /filesystem/path/to/MyApp/root/static
 533     <Directory /filesystem/path/to/MyApp/root/static>
 534         allow from all
 535     </Directory>
 536     <Location /myapp/static>
 537         SetHandler default-handler
 538     </Location>
 539
 540 If you are running in a VirtualHost, you can just set the DocumentRoot
 541 location to the location of your root directory; see
 542 L<Catalyst::Engine::Apache2::MP20>.
 543
 544 =head1 PUBLIC METHODS
 545
 546 =head2 serve_static_file $file_path
 547
 548 Will serve the file located in $file_path statically. This is useful when
 549 you need to  autogenerate them if they don't exist, or they are stored in a model.
 550
 551     package MyApp::Controller::User;
 552
 553     sub curr_user_thumb : PathPart("my_thumbnail.png") {
 554         my ( $self, $c ) = @_;
 555         my $file_path = $c->user->picture_thumbnail_path;
 556         $c->serve_static_file($file_path);
 557     }
 558
 559 =head1 INTERNAL EXTENDED METHODS
 560
 561 Static::Simple extends the following steps in the Catalyst process.
 562
 563 =head2 prepare_action
 564
 565 C<prepare_action> is used to first check if the request path is a static
 566 file.  If so, we skip all other C<prepare_action> steps to improve
 567 performance.
 568
 569 =head2 dispatch
 570
 571 C<dispatch> takes the file found during C<prepare_action> and writes it
 572 to the output.
 573
 574 =head2 finalize
 575
 576 C<finalize> serves up final header information and displays any log
 577 messages.
 578
 579 =head2 setup
 580
 581 C<setup> initializes all default values.
 582
 583 =head1 SEE ALSO
 584
 585 L<Catalyst>, L<Catalyst::Plugin::Static>,
 586 L<http://www.iana.org/assignments/media-types/>
 587
 588 =head1 AUTHOR
 589
 590 Andy Grundman, <andy@hybridized.org>
 591
 592 =head1 CONTRIBUTORS
 593
 594 Marcus Ramberg, <mramberg@cpan.org>
 595
 596 Jesse Sheidlower, <jester@panix.com>
 597
 598 Guillermo Roditi, <groditi@cpan.org>
 599
 600 Florian Ragwitz, <rafl@debian.org>
 601
 602 Tomas Doran, <bobtfish@bobtfish.net>
 603
 604 Justin Wheeler (dnm)
 605
 606 Matt S Trout, <mst@shadowcat.co.uk>
 607
 608 Toby Corkindale, <tjc@wintrmute.net>
 609
 610 =head1 THANKS
 611
 612 The authors of Catalyst::Plugin::Static:
 613
 614     Sebastian Riedel
 615     Christian Hansen
 616     Marcus Ramberg
 617
 618 For the include_path code from Template Toolkit:
 619
 620     Andy Wardley
 621
 622 =head1 COPYRIGHT
 623
 624 Copyright (c) 2005 - 2011
 625 the Catalyst::Plugin::Static::Simple L</AUTHOR> and L</CONTRIBUTORS>
 626 as listed above.
 627
 628 =head1 LICENSE
 629
 630 This program is free software, you can redistribute it and/or modify it under
 631 the same terms as Perl itself.
 632
 633 =cut