NAME

Mojolicious::Plugin::CHI::Route - Cache renderings based on routes

SYNOPSIS

# Mojolicious
$app->plugin('CHI::Route');
$app->routes->get('/foo')->requires('chi')->to(
  cb => sub {
    shift->render(
      text => 'This will be served from cache next time!'
    );
  }
)

# Mojolicious::Lite
use Mojolicious::Lite;

plugin 'CHI::Route';

get '/foo' => (chi => { expires_in => '5 hours' }) => sub {
  shift->render(
    text => 'This will be served from cache next time!'
  );
}

DESCRIPTION

Mojolicious::Plugin::CHI::Route enables caching on the router level by using Mojolicious::Plugin::CHI.

METHODS

register

plugin CHI => {
  routes => {
    driver => 'Memory',
    global => 1
  }
};

plugin 'CHI::Route' => {
  namespace => 'routes',
  expires_in => '4 hours'
};

Called when registering the plugin.

The registration accepts the following parameters:

key

The default key callback for all routes. Defaults to the absolute URL of the request.

expires_in

The default lifetime of route cache entries. Can be either a number of seconds or a duration expression. Defaults to 6 hours.

namespace

Define the CHI namespace for the cached renderings. Defaults to default. It is beneficial to use a separate namespace to easily purge or clear just the route cache on updates.

All parameters can be set as part of the configuration file with the key CHI-Route or on registration (that can be overwritten by configuration).

CONDITIONS

chi

get('/example')->requires(
  chi => {
    key => 'example',
    expires_in => '3 min'
  }
)->to( ... );

The caching works by adding a condition to the route, that will either render from cache or cache a dynamic rendering. The condition will always succeed. Only successfull GET requests will be cached. ETag and Last-Modified headers will be set and recognized on further requests by the same client.

key

The key for the cache. Accepts either a callback to dynamically define the key or a string (e.g. for non-dynamic routes without placeholders). In case of a callback, the first parameter passed is the controller object. Be aware that the state of the controller may not be finished yet and not all stash values may be accessible at this point! Returning undef won't cache the route. This overrides the default key configuration value.

In case the defined key is found in the cache, the cache content will be returned.

expires_in

The lifetime of the route cache entry. Can be either a number of seconds or a duration expression. This overrides the default expires_in configuration value.

TROUBLESHOOTING

The cached results will contain an X-Cache-CHI header. This is experimental and may change in the future.

CAVEAT

Note that the defined cache key must be chosen wisely to avoid cache poisoning.

AVAILABILITY

https://github.com/Akron/Mojolicious-Plugin-CHI-Route

COPYRIGHT AND LICENSE

Copyright (C) 2021, Nils Diewald.

This program is free software, you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.