Punk: a MVC framework

Every web framework does a certain amount of thinking on every request. It
looks at the path and decides which route matched. It works out which chain of
before filters are applied. It resolves 'Web::Book#view' into an actual coderef.
It checks whether this action wants JSON. None of that work depends on the
request in any interesting way, the answers are the same on request one and
request one million, yet most frameworks compute them again every time,
because that is the natural way to write a framework and because the cost is
invisible until it isn't.

Punk is a Perl MVC framework built on the opposite instinct: do all of that
once, at startup, and freeze the result. By the time your application is
serving traffic there is no routing table to interpret, no filter chain to
assemble, no string to resolve. Dispatch is a hash lookup or a short bucket
scan. Guards are a walk over a frozen array. The handler is a plain coderef
call that receives exactly one argument, the context object.

It looks like a normal framework:

package MyApp;
use Punk;

get  '/'          => 'Web::Book#home';
get  '/books/:id' => 'Web::Book#view';
post '/books'     => 'Web::Book#create';

my $admin = under '/admin' => sub {
    my ($c) = @_;
    return $c->redirect('/') unless $c->req->header('authorization');
    return;
};
$admin->get('/books' => 'Web::Book#admin_list');

static '/static' => 'root/static';

1;

# app.psgi
use MyApp;
MyApp->to_app;

The interesting moment is to_app. That is where Punk walks everything you
declared, resolves it, and builds the compiled form. 'Web::Book#view' becomes
the actual coderef it names. /admin merges its guard into every route beneath
it. The static mount becomes a C closure. After that the declaration is
finished with, and what serves your traffic is a frozen structure that nothing
interprets.

---

What that buys, and what it costs

The obvious payoff is that per request work goes down. The less obvious one is
that errors move to boot time. A controller method that does not exist, a
view engine that will not accept an option, a security scheme the spec requires
but no checker was supplied for, a docs path that collides with a real route -
all of these fail when the application starts, with a message naming the thing,
rather than on the unlucky request that first reaches them. An application that
starts is an application whose wiring is known to be sound.

The cost is the honest one: you cannot add a route at runtime. There is no
live structure to patch. If that is a thing you need, Punk is the wrong shape
and I would rather say so plainly than pretend otherwise.

It also has a consequence I did not anticipate when I started, which is that a
compiled at boot application is opaque from the outside. Everything is
resolved and frozen inside one coderef, so you cannot read the routing table by
eyeballing the source - the source is the declaration, not the result. That is
what the command line is for, and I will come back to it.

---

The keywords

The DSL is small and each keyword does one thing.

Routing. get, post, put, patch, del, any, and under for
scopes. A scope carries a prefix and a guard, nests, and returns a handle you
hang routes off. A guard that returns a response short circuits; a guard that
returns nothing lets the request through.

Realtime. websocket routes like a GET (upgrade requests are GETs), so
it sits under the same scopes and guards as anything else and a guard can
refuse a client with an ordinary HTTP response before the handshake happens.
Once validated, the handler gets the context and the connection, wires the
events it wants, and returns; the connection then lives on the server's event
loop. sse is the same idea for Server-Sent Events, with a heartbeat.

Sessions and security. session gives you signed cookie sessions -
$c->session is a hashref, HMAC-SHA256-signed, written back only when it
actually changes. csrf layers single use tokens on top: every unsafe request
must carry a live token, and using one spends it. cors is handled inside the
dispatcher rather than as middleware, which matters more than it sounds:
preflights are answered before routing, so no OPTIONS route is needed, and
the headers reach the 404s and 405s that never build a context.
Access-Control-Allow-Methods is answered from the router itself, so it cannot
promise a method the application does not actually serve.

Configuration and secrets. config loads layered YAML - punk.yml, then
punk.$PUNK_ENV.yml, then a gitignored punk.local.yml. Blocks that mirror a
DSL keyword register for real, so a views: or database: block in the file
is exactly equivalent to the keyword, and deployment configuration needs no
code change. Secrets are deliberately not in the file: a value written
{ $env: NAME }, { $file: PATH } or { $exec: [...] } is resolved at boot
from outside it, $app->config shows [redacted] in its place, and
$app->secret('database.password') reaches the real value. A plaintext value
under a secret shaped key warns, and secrets => 'strict' refuses to start.

Everything else. static, mount, views, database and model, hook,
middleware, on_error, plugin, helper.

---

OpenAPI as a first class mount

my $api = api 'openapi.json';
docs '/docs';

api mounts an OpenAPI 3.1 document. Each operation dispatches to the
controller method named after its operationId, and request validation,
security as guards and per prefix guards are all resolved at boot alongside
everything else. Under a scope it inherits that scope's prefix and guards, so a
spec can live behind the same authentication as the rest of the site without
restating it.

This is the part where the compile at boot idea earns the most. A spec is a
large pile of declarative facts - paths, parameters, schemas, security
requirements - and every one of them is knowable before the first request. So
Punk turns the document into the same frozen structures as everything else, and
a spec driven route costs what a hand written one costs.

---

The stack underneath

Punk sits on top of a set of modules I have been building for a while, and the
way they connect is the part I am most pleased with.

• Hyperman is the server: a preforking, event-loop PSGI server with its hot path in C.
• Open::API does OpenAPI routing and validation.
• Template::Stencil is the view engine, a {% %} template compiler.
• File::Raw::JSON does JSON.
• JSON::Schema::Fast validates against JSON Schema.

Each of those exposes a C ABI: a versioned table of function pointers,
resolved at runtime through a _abi_ptr lookup. So when Punk renders a
template, the path from the dispatcher to the template VM is C calling C, with
no Perl frame in the middle. Same for JSON encoding a response, same for
validating a request against a spec.

The runtime resolution matters. There is no link time coupling between these
distributions: each one checks the table's version at boot and falls back, or
refuses to start with a message naming the version it needed. They can be
released independently, and a consumer compiled against an older table keeps
working against a newer one because the tables only ever grow at the end. It is
the DBI driver pattern, applied to a web stack.

Punk vendors none of those headers. All four arrive through
ExtUtils::Depends, so each contract has exactly one copy and it is the one
its provider ships.

---

The command line

Because the compiled application is opaque from outside, punk exists to open
it up.

punk new MyApp
punk new MyApp --api ./openapi.json

punk new writes a running application, not a stub: routes, a controller,
Stencil views with a wrapper, config/punk.yml, a psgi entry point, a README,
and a test that builds the app and requests a page. Point it at an OpenAPI
document and it mounts that too, generating one controller of operation stubs
per tag, each answering 501 until you implement it. Generation is deterministic

• operations arrive in hash order, which perl randomises per process, so they are sorted before anything is written. Without that, regenerating the same spec shuffled subs between files and every diff was noise.

The rest of the commands report on a live application:

• punk routes prints the whole table: routes, spec operations, websocket routes, mounted apps, guard counts. Targets are recovered from the compiled coderef rather than the declaration, so what it prints is where a request actually lands.
• punk doctor reports versions and, the part no version number answers, which C ABI tables resolved and at what version.
• punk config check resolves every $env, $file and $exec reference in every layer independently, so one missing secret does not hide the rest. Non-zero exit on failure, which makes it a deployment gate. Secret values never reach the output.
• punk console is a REPL with $app, $psgi and a throwaway context.
• punk dev serves under Hyperman and restarts on change. A compiled at boot application cannot hot reload - there is no live structure to patch - so restarting is the implementation.
• punk api sync adds a stub for every operation the document declares and the controllers do not implement, and touches nothing else. An operation the spec no longer declares is reported, never removed.

---

Async

A handler can return a future instead of a response, and Punk awaits anything
future-shaped (then / on_ready / get).

get '/slow' => sub {
    my ($c) = @_;
    $c->timer(2)->then(sub { $c->json({ waited => 2 }) });
};

On a Hyperman worker that runs on the event loop and the worker serves other
requests while it is pending, so the two second wait costs no capacity.
Anywhere else it blocks, which is the correct fallback rather than a broken
one.

---

A note on speed

This is not a benchmark post, so: one table, and the honest reading of it. Every
app below is the same app shape, hosted on the same server, driven by the same
wrk harness, on my Mac with client and Hyperman server sharing the box.

App	req/s
bare PSGI coderef, no framework	205,461
Punk, hello	205,967
Punk, JSON	205,797
Punk, dynamic route	205,339
Punk, OpenAPI mount with validation	202,105
Punk, dynamic Template Stencil render	155,752
Mojolicious, hello	22,835
Catalyst, hello	6,691

---

Where it is

Punk needs Perl 5.10 or later and a C compiler. Currently it is not supported on
Windows but it may be in the future. It is young and the shape of it is settled
but the edges are not. If you try it and something is wrong or missing I would
like to hear from you about it below.