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