NAME

Klonk::Routes - define routes and dispatch requests

SYNOPSIS

use Klonk::Routes;  # no exports

Klonk::Routes::on_init sub () {
    ...
};

Klonk::Routes::mkroute '/widget/*', (
    GET => sub ($env, $arg) {
        ...
    },
);

# in your app.psgi
Klonk::Routes::boot;

DESCRIPTION

This module lets you define routes and dispatch requests. It is the main module to use and contains the most serviceable parts. It does not export anything, so all calls to functions in this module have to use their fully-qualified names.

Functions

Klonk::Routes::on_init $subroutine

Arranges for $subroutine (a coderef) to be called once, before any requests are dispatched. This is useful if you want your application modules to be preloaded in a separate process, but still perform initialization "globally" in each worker process. This can be used e.g. to connect to a database outside of any particular request, but without accidentally sharing a connection handle across multiple processes.

Klonk::Routes::mkroute $pattern, %handlers

Defines a resource by specifying a path pattern. This can be a simple path like / or /app/index.php, but it can also include wildcards like /widget/*/chapter/*.

Pattern matching details: The * wildcard matches any sequence of non-/ characters in the request path. The ** wildcard matches any sequence of any characters, but can only be used at the end of a pattern. Both wildcards only match full path components, i.e. they can only be used after (and in the case of *, followed by) a /. It is possible to match a literal * in the request path by putting `*` in the pattern; similarly, a literal ` in the request path can be specified as ``.

The %handlers argument (a hash initializer) maps request methods (or "HTTP verbs") such as GET or POST to handler functions. Each handler function is called with the request environment (a Klonk::Env object) as its first argument followed by all request path segments matched by wildcards in the pattern.

A HEAD handler (unless explicitly specified) is automatically synthesized from a GET handler.

Handlers must return a reference to an array of 2 to 4 elements:

[ $status_opt, $type, $body, $headers_opt ]

$status_opt

Optional (detaults to 200). If specified, must be a three-digit HTTP response status code (like 200 or 404).

$type

Response type. Must be a text type (css, csv, html, js, json, jsonld, text), image type (jpeg, png, webp), or the generic bin binary type (maps to application/octet-stream).

Text types are always encoded as UTF-8.

$body

Response body. Must be either a string or an open filehandle.

$headers_opt

Optional (defaults to {}). A reference to a hash of additional reponse headers. Values must be either strings or array references; the latter are expanded to multiple headers with the same key:

{
    'Set-Cookie' => ['foo=1', 'bar=2'],
    # sends two response headers:
    #   Set-Cookie: foo=1
    #   Set-Cookie: bar=2
}

Content-Type and Content-Length headers should not be set here as they are calculated automatically based on $type and $body.

Klonk::Routes::boot

This should be called once at the end of your main script. It initializes the system and returns a PSGI application for all routes previously defined.