Sloop::Static::Cache

DESCRIPTION

This non-OO module contains a few functions for caching dynamically generated content based on the timestamp of a source file.

SUBROUTINES

page()

Takes a client object and calls its reply() method with a cached copy of a dynamically generated page. If the copy does not exist, or is older than its source (see below), it is (re)generated and saved first.

 Sloop::Static::Cache::page (
        $client,
        $cachedPath,
        $srcPath,
        $generateFunc
 );

$client

A Sloop::Client object.

$cachedPath

Path to the cached copy; it does not have to exist, but the directory should (and be writable -- if it or the file is not so, $client will receive a 500 error). The suffix determines the mime type used with $client->reply(), via Sloop::Static::MimeType::get(), defaulting to "text/plain".

$srcPath

Path to a file which will be submitted to the $generateFunc if there is no cached copy, or if it has a modification time more recent than $cachedPath. This file doesn't have to contain anything; it is not examined for anything other than the timestamp.

If the file does not exist but $cachedPath does, it will be used. Otherwise, you will need to deal with this in $generateFunc.

$generateFunc

A sub ref which will be called when $cachedPath needs to be (re)generated. It will be passed one argument, $srcPath, and should return a scalar containing whatever you want sent to the client and saved in $cachePath. If this function returns a false value, $client->generic(404) will be called. If it returns only a string consisting of an HTTP status code (e.g., "500"), $client-generic(status code)> will be called.

hierarchy()

Much like page(), but used to deal with a potential hierarchy of URLs starting with a base path; this hierarchy should correspond with a directory of source files used to generate cached pages, but you have the opportunity to transform the URL before it is used to search the tree.

 Sloop::Static::Cache::hierarchy (
        $client,
        srcroot => string,
        cache => string,
        suffixMap => hashref,
        transform => sub { },
        create => sub { }
 );

All fields except suffixMap are required.

$client

A Sloop::Client object which will receive a reply().

srcroot

The top level directory to search for the source file provided to the 'create' function. The relative subpath used is whatever is returned by the 'transform' function.

cache

The top level directory to use for caching copies of generated pages. It may be empty, and should be writable by the Sloop process. It will end up with a tree paralleling that of the source files in 'srcroot'.

suffixMap

A hash reference containing a list of suffixes from 'srcroot' with what they should become in 'cache'. It should also contain a "default" key which will be used if a path returned by the 'transform' function does not have a suffix, or one which is not in the hash. For example:

 suffixMap => {
        md => 'html',
        svg => 'jpg'
        default => 'txt'
 }

You do not have to provide this, in which case suffixMap => { default => 'html' } is used. Note that the suffix here doesn't have to be part of the URL, but it is used to determine the mime type for $client->reply() (see the $cachedPath parameter to page(), above). It should correspond to paths returned by the 'transform' function.

transform

A subrountine which will receive the remainder of the URL left in $client->{request}->pathFromLevel; for example, if hierarchy() is being used to handle URLs beginning with "/foo/bar" and the actual URL is "/foo/bar/whiskey/bravo", then 'transform' will recieve "/whiskey/bravo". This function should then return a subpath relative to 'srcroot', above, used to find the source file whose path is handed to the 'create' function. For example, sub { $_[0].'txt' } would end up returning, e.g., "/whiskey/bravo.txt", and hierarchy() would then look for "[srcroot]/whiskey/bravo.txt". This file should actually exist, and the name, as returned, must include a suffix.

If the file does not exist (as readable and regular), then a debug error is logged and the client receives a 404.

create

A sub ref which will be called when a cached file needs to be (re)generated, either because it doesn't exist or its corresponding source file has a newer modification time. It will be passed one argument, the path returned by 'transform', and should return a scalar containing whatever you want sent to the client and saved in the cache (do not save it yourself). If this function returns undef, $client->generic(404) will be called and an error logged with $client->err_log().

updateTree()

This is intended to be used in conjunction with hierarchy(), above, but not as an actual client handler. Instead, it uses File::Find to examine the entire source file tree and update the corresponding cache file if required. This allows you to generate the cache tree at startup to make sure everything happens properely.

 Sloop::Static::Cache::updateTree (
        srcroot => scalar,
        cache => scalar,
        suffixMap => hash ref,
        create => sub { },
        logger => Sloop::Logger object
 );

All are required.

srcroot
cache
create: Are the same as for hierarchy(), above.
suffixMap: This functions the same way as 'suffixMap' for hierarchy, except no 'default' key is used. If a file is found in 'srcroot' with no suffix, or its suffix is not in this hash, it is ignored.
logger: This will be used to indicate errors.