mccs/lib/Plack/App/MCCS.pm
package Plack::App::MCCS;
use v5.36;
our $VERSION = "2.002000";
$VERSION = eval $VERSION;
use parent qw/Plack::Component/;
use autodie;
use Cwd ();
use Fcntl qw/:flock/;
use File::Spec;
use HTTP::Date;
use IO::Compress::Gzip;
use IO::Compress::Deflate;
use Module::Load::Conditional qw/can_load/;
use Plack::MIME;
use Plack::Util;
use Plack::Util::Accessor qw/
root
minify
compress
etag
types
charset
index_files
ignore_file
default_valid_for
default_cache_control
min_cache_dir
vhost_mode
_minifiers
_compressors
_ignore_matchers
/;
use Text::Gitignore qw/build_gitignore_matcher/;
=head1 NAME
Plack::App::MCCS - Use mccs in Plack applications.
=head1 EXTENDS
L<Plack::Component>
=head1 SYNOPSIS
# in your app.psgi:
use Plack::Builder;
use Plack::App::MCCS;
my $app = sub { ... };
# be happy with the defaults:
builder {
mount '/static' => Plack::App::MCCS->new(root => '/path/to/static_files')->to_app;
mount '/' => $app;
};
# or tweak the app to suit your needs:
builder {
mount '/static' => Plack::App::MCCS->new(
root => '/path/to/static_files',
min_cache_dir => 'min_cache',
default_valid_for => 86400,
default_cache_control => ['private'],
types => {
'.htc' => {
content_type => 'text/x-component',
valid_for => 360,
cache_control => ['no-cache', 'must-revalidate'],
},
},
)->to_app;
mount '/' => $app;
};
=head1 DESCRIPTION
C<Plack::App::MCCS> is a L<Plack> fully-featured static file server. Refer to
L<mccs> for more information. This package allows embedding C<mccs> in a PSGI
application.
=head1 CLASS METHODS
=head2 new( %opts )
Creates a new instance of this module. The following options are supported, all
are optional:
=over
=item * B<root>: The path to the root directory where static files reside.
Defaults to the current working directory.
=item * B<charset>: the character set to append to content-type headers when
text files are returned. Defaults to "UTF-8".
=item * B<minify>: boolean value indicating whether C<mccs> should automatically
minify CSS/JS files (or search for pre-minified files). Defaults to true.
=item * B<compress>: boolean value indicating whether C<mccs> should
automatically compress files (or search for pre-compressed files). Defaults to
true.
=item * B<etag>: boolean value indicating whether C<mccs> should automatically
create and save ETags for files. Defaults to true. If false, C<mccs> will NOT
handle ETags at all (so if the client sends the C<If-None-Match> header,
C<mccs> will ignore it).
=item * B<vhost_mode>: boolean value indicating whether to enable virtual-hosts
mode. When enabled, multiple websites can be served based on the HTTP Host
header. HTTP/1.0 requests will not be supported in this mode. The root directory
must contain subdirectories named after each host/domain to serve in this mode.
Defaults to false.
=item * B<min_cache_dir>: by default, minified files are generated in the same
directory as the original file. If this attribute is specified they
are instead generated within the provided subdirectory, and minified files
outside that directory are ignored, unless requested directly.
=item * B<default_valid_for>: the default number of seconds caches are allowed
to save a response. Defaults to 86400 seconds (one day).
=item * B<default_cache_control>: an array-ref of options for the
C<Cache-Control> header (all options are accepted except for C<max-age>, which
is automatically calculated from the resource's C<valid_for> setting). Defaults
to C<['public']>.
=item * B<index_files>: a list of file names to search for when a directory is
requested. Defaults to C<['index.html']>.
=item * B<ignore_file>: path to a file in the format of the L<Gitignore|https://git-scm.com/docs/gitignore>
file. Any request that matches rules in this file will not be served by C<mccs>
and instead return a 404 Not Found response. Defaults to C<'.mccsignore'>. In
vhost_mode, every host may have its own file, and there can also be a global
file for all hosts. Both the host-specific file and the global file will be used
if they exist.
=item * B<types>: a hash-ref to supply options specific to file extensions.
Keys are extensions (beginning with a dot). Values can be B<valid_for> (for
the cache validity interval in seconds); B<cache_control> (for an array-ref
of Cache-Control options); B<content_type> to provide a Content-Type when
C<mccs> can't accurately guess it.
=back
If you don't want something to be cached, give the global B<default_valid_for>
or the extension-specific B<valid_for> options a value of either zero, or
preferably any number lower than zero, which will cause C<mccs> to set an
C<Expires> header way in the past. You should also pass the B<cache_control>
option C<no_store> and probably C<no_cache>. When C<mccs> encounteres the
C<no_store> option, it does not automatically add the C<max-age> option
to the C<Cache-Control> header.
=cut
our $DEFAULT_VALID_FOR = 86400;
our $DEFAULT_CHARSET = "UTF-8";
sub new ( $class, %opts ) {
$opts{root} ||= Cwd::getcwd();
$opts{charset} ||= $DEFAULT_CHARSET;
$opts{default_valid_for} = $DEFAULT_VALID_FOR
if !exists $opts{default_valid_for};
$opts{default_cache_control} ||= ['public'];
$opts{index_files} ||= ['index.html'];
$opts{minify} = 1 if !defined $opts{minify};
$opts{compress} = 1 if !defined $opts{compress};
$opts{etag} = 1 if !defined $opts{etag};
$opts{vhost_mode} = 0 if !defined $opts{vhost_mode};
$opts{ignore_file} ||= '.mccsignore';
$opts{types} ||= {};
my $self = $class->SUPER::new(%opts);
$self->{_minifiers} = {};
$self->{_compressors} = {};
$self->{_ignore_matchers} = {};
# Are we minifying files? If so, which types do we support?
if ( $self->minify ) {
if ( can_load( modules => { 'JavaScript::Minifier::XS' => 0.15 } ) ) {
$self->{_minifiers}->{js} = 1;
}
if ( can_load( modules => { 'CSS::Minifier::XS' => 0.13 } ) ) {
$self->{_minifiers}->{css} = 1;
}
}
# Are we compressing files? if so, which algorithms do we support?
if ( $self->compress ) {
if ( can_load( modules => { 'IO::Compress::Gzip' => undef } ) ) {
$self->{_compressors}->{gzip} = 1;
}
if ( can_load( modules => { 'IO::Compress::Deflate' => undef } ) ) {
$self->{_compressors}->{deflate} = 1;
}
if ( can_load( modules => { 'IO::Compress::Zstd' => undef } ) ) {
$self->{_compressors}->{zstd} = 1;
}
}
# load and parse ignore files, if they exist
$self->_load_ignore_files();
return $self;
}
=head1 OBJECT METHODS
=head2 call( \%env )
L<Plack> automatically calls this method to handle a request. This is where
the magic (or disaster) happens.
=cut
sub call ( $self, $env ) {
my $path_info =
$self->vhost_mode
? $env->{HTTP_HOST} . $env->{PATH_INFO}
: $env->{PATH_INFO};
# check if path is ignored by any relevant ignore files
if (
(
$self->vhost_mode
&& $self->_ignore_matchers->{ $env->{HTTP_HOST} }
&& $self->_ignore_matchers->{ $env->{HTTP_HOST} }
->( $env->{PATH_INFO} )
)
|| ( $self->_ignore_matchers->{__global__}
&& $self->_ignore_matchers->{__global__}->( $env->{PATH_INFO} ) )
)
{
return $self->_not_found_404;
}
# find the request file (or return error if occured)
my $file = $self->_locate_file($path_info);
return $file if ref $file && ref $file eq 'ARRAY'; # error occured
# determine the content type and extension of the file
my ( $content_type, $ext ) = $self->_determine_content_type($file);
# determine cache control for this extension
my ( $valid_for, $cache_control, $should_etag ) =
$self->_determine_cache_control($ext);
undef $should_etag if !$self->etag;
# if this is a CSS/JS file, see if a minified representation of
# it exists, unless the file name already has .min.css/.min.js,
# in which case we assume it's already minified
if (
$self->minify
&& $file !~ m/\.min\.(css|js)$/
&& ( $content_type eq 'text/css'
|| $content_type eq 'application/javascript' )
)
{
$file = $self->_minify_file( $file, $content_type );
}
# search for a compressed version of this file if the client supports
# compression
my $content_encoding;
if ( $self->compress && $env->{HTTP_ACCEPT_ENCODING} ) {
( $file, $content_encoding ) =
$self->_compress_file( $file, $env->{HTTP_ACCEPT_ENCODING} );
}
# okay, time to serve the file (or not, depending on whether cache
# validations exist in the request and are fulfilled)
return $self->_serve_file( $env, $file, $content_type, $content_encoding,
$valid_for, $cache_control, $should_etag );
}
sub _minify_file ( $self, $file, $content_type ) {
my $new = $file;
$new =~ s/\.(css|js)$/.min.$1/;
$new = $self->_filename_in_min_cache_dir($new) if $self->min_cache_dir;
my $min = $self->_locate_file($new);
my $try_to_minify;
if ( $min && !ref $min ) {
# yes, we found it, but is it still fresh? let's see
# when was the source file modified and compare them
# $slm is the source file's last modification date
my $slm = ( stat( ( $self->_full_path($file) )[0] ) )[9];
# $mlm is the minified file's last modification date
my $mlm = ( stat( ( $self->_full_path($min) )[0] ) )[9];
# if source file is newer than minified version,
# we need to remove the minified version and try
# to minify again, otherwise we can simply set the
# minified version is the version to serve
if ( $slm > $mlm ) {
unlink( ( $self->_full_path($min) )[0] );
$try_to_minify = 1;
} else {
return $min;
}
} else {
# minified version does not exist, let's try to
# minify ourselves
$try_to_minify = 1;
}
if ($try_to_minify) {
# can we minify ourselves?
if (
( $content_type eq 'text/css' && $self->_minifiers->{css} )
|| ( $content_type eq 'application/javascript'
&& $self->_minifiers->{js} )
)
{
# open the original file
my $orig = $self->_full_path($file);
open( my $ifh, '<:raw', $orig )
|| return $self->return_403;
# add ->path attribute to the file handle
Plack::Util::set_io_path( $ifh, Cwd::realpath($orig) );
# read the file's contents into $css
my $body;
Plack::Util::foreach( $ifh, sub { $body .= $_[0] } );
# minify contents
my $min =
$content_type eq 'text/css'
? CSS::Minifier::XS::minify($body)
: JavaScript::Minifier::XS::minify($body);
# save contents to another file
if ($min) {
my $out = $self->_full_path($new);
open( my $ofh, '>:raw', $out );
flock( $ofh, LOCK_EX );
if ($ofh) {
print $ofh $min;
close $ofh;
return $new;
}
}
}
}
return $file;
}
sub _priority ($val) {
my ( $name, $priority ) =
( $val =~ m/^([^;\s]+)(?:\s*;q=(\d+(?:\.\d+)?))?$/ );
$priority ||= 1;
return [ $name, $priority ];
}
sub _compress_file ( $self, $file, $accept_header ) {
my @accept_enc =
sort { $b->[1] <=> $a->[1] }
map { _priority($_) } split( /\s*,\s*/, $accept_header );
for my $enc (@accept_enc) {
next unless $self->_compressors->{ $enc->[0] };
my ( $ext, $fnc, $err );
if ( $enc->[0] eq 'gzip' ) {
$ext = '.gz';
$fnc = *IO::Compress::Gzip::gzip;
$err = $IO::Compress::Gzip::GzipError;
} elsif ( $enc->[0] eq 'deflate' ) {
$ext = '.zip';
$fnc = *IO::Compress::Deflate::deflate;
$err = $IO::Compress::Deflate::DeflateError;
} elsif ( $enc->[0] eq 'zstd' ) {
$ext = '.zstd';
$fnc = *IO::Compress::Zstd::zstd;
$err = $IO::Compress::Zstd::ZstdError;
} else {
next;
}
my $comp = $self->_locate_file( $file . $ext );
my $try_to_compress;
if ( $comp && !ref $comp ) {
# good, we found a compressed version, but is it
# still fresh? like before let's compare its modification
# date with the current file marked for serving
# $slm is the source file's last modification date
my $slm = ( stat( ( $self->_full_path($file) )[0] ) )[9];
# $clm is compressed file's last modification date
my $clm = ( stat( ( $self->_full_path($comp) )[0] ) )[9];
# if source file is newer than compressed version,
# we need to remove the compressed version and try
# to compress again, otherwise we can simply set the
# compressed version is the version to serve
if ( $slm > $clm ) {
unlink( ( $self->_full_path($comp) )[0] );
$try_to_compress = 1;
} else {
return ( $comp, $enc->[0] );
}
} else {
# compressed version not found, so let's try to compress
$try_to_compress = 1;
}
if ($try_to_compress) {
# we need to create a gzipped version by ourselves
my $orig = $self->_full_path($file);
my $out = $self->_full_path( $file . $ext );
if ( $fnc->( $orig, $out ) ) {
return ( $file . $ext, $enc->[0] );
} else {
warn "Failed compressing ${file}: ${err}";
}
}
}
return ( $file, undef );
}
sub _locate_file ( $self, $path ) {
# does request have a sane path?
$path ||= '';
return $self->_bad_request_400
if $path =~ m/\0/;
my ( $full, $path_arr ) = $self->_full_path($path);
# do not allow traveling up in the directory chain
return $self->_forbidden_403
if grep { $_ eq '..' } @$path_arr;
if ( -f $full ) {
# this is a file, is it readable?
return -r $full ? $path : $self->_forbidden_403;
} elsif ( -d $full ) {
# this is a directory, look for an index file, and if not exists,
# return 403 Forbidden, as we do not do directory listings
for my $opt ( @{ $self->index_files } ) {
if ( -f -r File::Spec->catfile( $full, $opt ) ) {
return File::Spec->catfile( $path, $opt );
}
}
return $self->_forbidden_403;
} else {
# not found, return 404
return $self->_not_found_404;
}
}
sub _filename_in_min_cache_dir ( $self, $file ) {
my $min_cache_dir =
File::Spec->catfile( $self->root || ".", $self->min_cache_dir );
mkdir $min_cache_dir if !-d $min_cache_dir;
$file =~ s@/@%2F@g;
my $new = File::Spec->catfile( $self->min_cache_dir, $file );
return $new;
}
sub _determine_content_type ( $self, $file ) {
# determine extension of the file and see if application defines
# a content type for this extension (will even override known types)
my ($ext) = ( $file =~ m/(\.[^.]+)$/ );
if ( $ext
&& $self->types->{$ext}
&& $self->types->{$ext}->{content_type} )
{
return ( $self->types->{$ext}->{content_type}, $ext );
}
# okay, no specific mime defined, let's use Plack::MIME to find it
# or fall back to text/plain
return ( Plack::MIME->mime_type($file) || 'text/plain', $ext );
}
sub _determine_cache_control ( $self, $ext ) {
my $valid_for = $self->default_valid_for;
my @cache_control = @{ $self->default_cache_control };
# user provided extension specific settings
if ( $ext && $self->types->{$ext} ) {
if ( defined $self->{types}->{$ext}->{valid_for} ) {
$valid_for = $self->types->{$ext}->{valid_for};
}
if ( defined $self->{types}->{$ext}->{cache_control} ) {
@cache_control = @{ $self->types->{$ext}->{cache_control} };
}
}
# unless cache control has no-store, prepend max-age to it
my $cache = scalar( grep { $_ eq 'no-store' } @cache_control ) ? 0 : 1;
unshift( @cache_control, 'max-age=' . $valid_for )
if $cache;
return ( $valid_for, \@cache_control, $cache );
}
sub _serve_file ( $self, $env, $path, $content_type, $content_encoding,
$valid_for, $cache_control, $should_etag )
{
# if we are serving a text file (including JSON/XML/JavaScript), append
# character set to the content type
$content_type .= '; charset=' . $self->charset
if $content_type =~ m!^(text/|application/(json|xml|javascript))!;
# get the full path of the file
my $file = $self->_full_path($path);
# get file statistics
my @stat = stat $file;
# try to find the file's etag, unless no-store is on so we don't
# care about it
my $etag;
if ($should_etag) {
if ( -f "${file}.etag" && -r "${file}.etag" ) {
# we've found an etag file, and we can read it, but is it
# still fresh? let's make sure its last modified date is
# later than that of the file itself
if ( $stat[9] > ( stat("${file}.etag") )[9] ) {
# etag is stale, try to delete it
unlink "${file}.etag";
} else {
# read the etag file
if ( open( ETag, '<', "${file}.etag" ) ) {
flock( ETag, LOCK_SH );
$etag = <ETag>;
chomp($etag);
close ETag;
} else {
warn "Can't open ${file}.etag for reading";
}
}
} elsif ( -f "${file}.etag" ) {
warn "Can't open ${file}.etag for reading";
}
}
# did the client send cache validations?
if ( $env->{HTTP_IF_MODIFIED_SINCE} ) {
# okay, client wants to see if resource was modified. IE sends wrong
# formatted value (i.e. "Thu, 03 Dec 2009 01:46:32 GMT; length=17936")
# - taken from Plack::Middleware::ConditionalGET
$env->{HTTP_IF_MODIFIED_SINCE} =~ s/;.*$//;
my $since = HTTP::Date::str2time( $env->{HTTP_IF_MODIFIED_SINCE} );
# if file was modified on or before $since, return 304 Not Modified
return $self->_not_modified_304
if $stat[9] <= $since;
}
if ( $etag
&& $env->{HTTP_IF_NONE_MATCH}
&& $etag eq $env->{HTTP_IF_NONE_MATCH} )
{
return $self->_not_modified_304;
}
# okay, we need to serve the file
# open it first
open my $fh, '<:raw', $file
|| return $self->return_403;
# add ->path attribute to the file handle
Plack::Util::set_io_path( $fh, Cwd::realpath($file) );
# did we find an ETag file earlier? if not, let's create one (unless
# we shouldn't due to no-store)
if ( $should_etag && !$etag ) {
# following code based on Plack::Middleware::ETag by Franck Cuny
# P::M::ETag creates weak ETag if it sees the resource was
# modified less than a second before the request. It seems
# like it does that because there's a good chance the resource
# will be modified again soon afterwards. I'm not gonna do
# that because if MCCS minified/compressed by itself, it will
# pretty much always mean the ETag will be created less than a
# second after the file was modified, and I know it's not gonna
# be modified again soon, so I see no reason to do that here
# add inode to etag
$etag .= join( '-',
sprintf( "%x", $stat[2] ),
sprintf( "%x", $stat[9] ),
sprintf( "%x", $stat[7] ) );
# save etag to a file
if ( open( ETag, '>', "${file}.etag" ) ) {
flock( ETag, LOCK_EX );
print ETag $etag;
close ETag;
} else {
undef $etag;
warn "Can't open ETag file ${file}.etag for writing";
}
}
# set response headers
my $headers = [];
push( @$headers, 'Content-Encoding' => $content_encoding )
if $content_encoding;
push( @$headers, 'Content-Length' => $stat[7] );
push( @$headers, 'Content-Type' => $content_type );
push( @$headers, 'Last-Modified' => HTTP::Date::time2str( $stat[9] ) );
push( @$headers,
'Expires' => $valid_for >= 0
? HTTP::Date::time2str( $stat[9] + $valid_for )
: HTTP::Date::time2str(0) );
push( @$headers, 'Cache-Control' => join( ', ', @$cache_control ) );
push( @$headers, 'ETag' => $etag ) if $etag;
push( @$headers, 'Vary' => 'Accept-Encoding' );
# respond
return [ 200, $headers, $fh ];
}
sub _full_path ( $self, $path ) {
my $docroot = $self->root || '.';
# break path into chain
my @path = split( '/', $path );
if (@path) {
shift @path if $path[0] eq '';
} else {
@path = ('.');
}
my $full = File::Spec->catfile( $docroot, @path );
return wantarray ? ( $full, \@path ) : $full;
}
sub _load_ignore_files ($self) {
$self->{_ignore_matchers}->{'__global__'} =
$self->_load_ignore_file( $self->ignore_file, undef );
if ( $self->vhost_mode ) {
# look for ignore files in all subdirectories
opendir( my $dir, $self->root );
my @dirs =
grep { !/^\.\.?$/ && -d File::Spec->catfile( $self->root, $_ ) }
readdir $dir;
closedir $dir;
for my $dir (@dirs) {
$self->{_ignore_matchers}->{$dir} =
$self->_load_ignore_file( $self->ignore_file, $dir );
}
}
}
sub _load_ignore_file ( $self, $path, $host ) {
my $fullpath =
$host
? $self->_full_path( File::Spec->catfile( $host, $path ) )
: $self->_full_path($path);
if ( !-f $fullpath ) {
return;
}
open( my $file, '<', $fullpath );
my @rules;
while ( my $line = <$file> ) {
chomp($line);
push( @rules, $line );
}
close $file;
# add the ignore file itself to the rules
push( @rules, $path );
return build_gitignore_matcher( \@rules );
}
sub _not_modified_304 {
[ 304, [], [] ];
}
sub _bad_request_400 {
[
400, [ 'Content-Type' => 'text/plain', 'Content-Length' => 11 ],
['Bad Request']
];
}
sub _forbidden_403 {
[
403, [ 'Content-Type' => 'text/plain', 'Content-Length' => 9 ],
['Forbidden']
];
}
sub _not_found_404 {
[
404, [ 'Content-Type' => 'text/plain', 'Content-Length' => 9 ],
['Not Found']
];
}
=head1 BUGS AND LIMITATIONS
Please report any bugs or feature requests to
C<bug-Plack-App-MCCS@rt.cpan.org>, or through the web interface at
L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Plack-App-MCCS>.
=head1 SEE ALSO
L<Plack::Middleware::MCCS>, L<Plack::Middleware::Static>, L<Plack::App::File>,
L<Plack::Builder>.
=head1 AUTHOR
Ido Perlmuter <ido@ido50.net>
=head1 LICENSE AND COPYRIGHT
Copyright (c) 2011-2023, Ido Perlmuter C<< ido@ido50.net >>.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
=cut
1;
__END__