/ 
Dancer2-Plugin-ContentCache-1.0000
/ README.mkdn

NAME

Dancer2::Plugin::ContentCache - Cache HTML/JSON responses for later use.

VERSION

version 1.0000

SYNOPSIS

# In config.yml:
#
plugins:
  ContentCache:
     # REQUIRED, unless you supply your own 'driver' (see DRIVERS, below).
     cache_result_set: ContentCache

     # Optional, with defaults
     driver: DBIx::Class
     schema: default
     create_redirect_route: 1
     redirect_route: '/recall'
     require_login: 0
     cache_aging: 1
     default_life: 86400

# In your Dancer2 application
#
package MyApp;
use Dancer2 appname => 'MyApp';
use Dancer2::Plugin::ContentCache;

post '/this_route' => sub {
  # This route is supposed to return HTML

  my $html = template 'Foo',
             { param1 => 'bar' },
             { layout => 'some_layout'};

  cache_and_redirect $html,
             { life => 6000, created_by => 'baz' };
             # metadata; note 'life'
};

post '/this_other_route' => sub {
  # do some processing
  # This route is supposed to return JSON

  cache_and_send $results, { created_by => 'baz' };
  # $results is a hashref or arrayref.
};

#
# Example of custom cache handler:
#
get '/retrieve_privileged/:uuid' => sub {

   my $cache = retrieve_cache route_parameters->get('uuid');
   my $all_good = 0;

   # Use the stuff in $cache->metadata to decide if you want to send this
   # to the user, and set $all_good as appropriate.

   if ($all_good) {
      send_as $cache->data_format => $cache->data;
   }
   else {
      return send_error('Not Found', 404);
   }
};

DESCRIPTION

This plugin for Dancer2 implements a response-content cache and optionally issues a redirect to that content. In particular, this is useful after a POST route; if the network times out (as can happen on wonky connections), you don't want the user to re-POST. By redirecting them to the now-cached content as a GET, you prevent re-POSTing.

Storage is never touched directly by this plugin; every read and write goes through a small driver object, so you are not locked into DBIx::Class. See "DRIVERS", below.

CONFIGURATION

In your config.yml for your Dancer2 application, use these configuration parameters:

DANCER2 KEYWORDS

THE CACHE OBJECT

The cache object, Dancer2::Plugin::ContentCache::CacheEntry, is a simple Moo object containing the following field/methods:

DRIVERS

Dancer2::Plugin::ContentCache never touches a database (or anything else) directly; all storage happens through a driver class that consumes the Dancer2::Plugin::ContentCache::Driver role. The bundled default, Dancer2::Plugin::ContentCache::Driver::DBIC, stores entries with DBIx::Class via Dancer2::Plugin::DBIx::Class or Dancer2::Plugin::DBIC, whichever your application is using..

To use a different backend, write a class that consumes Dancer2::Plugin::ContentCache::Driver and set the driver configuration option to its full package name:

plugins:
  ContentCache:
    driver: MyApp::ContentCache::Driver::Redis

See Dancer2::Plugin::ContentCache::Driver for the small set of methods your driver needs to implement.

SUGGESTED SCHEMA

Here's the sort of schema you'll need for the default DBIx::Class driver (this one, for PostgreSQL). If you're using more-recent versions of PostgreSQL that have a UUID type, you could use that, but this is the lowest-common-denominator form of the schema:

CREATE TABLE IF NOT EXISTS content_cache (
  uuid TEXT NOT NULL PRIMARY KEY,         -- Or "id", your choice.
  metadata TEXT NOT NULL,                 -- REQUIRED
  data TEXT NOT NULL,                     -- REQUIRED
  created_dt TIMESTAMP WITHOUT TIME ZONE, -- Plugin will always assume "local"
                                          -- unless you store it WITH TIMEZONE
                                          -- Only needed if cache_aging is on.
  expiry_dt TIMESTAMP WITHOUT TIME ZONE   -- Same here as with created_dt
);

DEPENDENCIES

BUGS AND LIMITATIONS

ACKNOWLEDGEMENTS

The idea for this plugin comes from Mike Weisenborn of Clearbuilt. Clearbuilt graciously sponsored the development of this work.

SEE ALSO

AUTHOR

D Ruth Holloway ruth@hiruthie.me

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by D Ruth Holloway.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.