NAME

Plack::App::MCCS - Use mccs in Plack applications.

EXTENDS

Plack::Component

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;
        };

DESCRIPTION

Plack::App::MCCS is a Plack fully-featured static file server. Refer to mccs for more information. This package allows embedding mccs in a PSGI application.

CLASS METHODS

new( %opts )

Creates a new instance of this module. The following options are supported, all are optional:

• root: The path to the root directory where static files reside. Defaults to the current working directory.

• charset: the character set to append to content-type headers when text files are returned. Defaults to "UTF-8".

• minify: boolean value indicating whether mccs should automatically minify CSS/JS files (or search for pre-minified files). Defaults to true.

• compress: boolean value indicating whether mccs should automatically compress files (or search for pre-compressed files). Defaults to true.

• etag: boolean value indicating whether mccs should automatically create and save ETags for files. Defaults to true. If false, mccs will NOT handle ETags at all (so if the client sends the If-None-Match header, mccs will ignore it).

• 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.

• 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.

• default_valid_for: the default number of seconds caches are allowed to save a response. Defaults to 86400 seconds (one day).

• default_cache_control: an array-ref of options for the Cache-Control header (all options are accepted except for max-age, which is automatically calculated from the resource's valid_for setting). Defaults to ['public'].

• index_files: a list of file names to search for when a directory is requested. Defaults to ['index.html'].

• ignore_file: path to a file in the format of the Gitignore file. Any request that matches rules in this file will not be served by mccs and instead return a 404 Not Found response. Defaults to '.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.

• types: a hash-ref to supply options specific to file extensions. Keys are extensions (beginning with a dot). Values can be valid_for (for the cache validity interval in seconds); cache_control (for an array-ref of Cache-Control options); content_type to provide a Content-Type when mccs can't accurately guess it.

If you don't want something to be cached, give the global default_valid_for or the extension-specific valid_for options a value of either zero, or preferably any number lower than zero, which will cause mccs to set an Expires header way in the past. You should also pass the cache_control option no_store and probably no_cache. When mccs encounteres the no_store option, it does not automatically add the max-age option to the Cache-Control header.

OBJECT METHODS

call( \%env )

Plack automatically calls this method to handle a request. This is where the magic (or disaster) happens.

BUGS AND LIMITATIONS

Please report any bugs or feature requests to bug-Plack-App-MCCS@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Plack-App-MCCS.

SEE ALSO

Plack::Middleware::MCCS, Plack::Middleware::Static, Plack::App::File, Plack::Builder.

AUTHOR

Ido Perlmuter <ido@ido50.net>

LICENSE AND COPYRIGHT

Copyright (c) 2011-2023, Ido Perlmuter 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.