NAME
Punk::Context - the per-request object
DESCRIPTION
Every guard, hook, plugin helper and controller receives one argument: the context. It wraps the PSGI environment lazily and carries the response builders. See Punk for the framework overview.
The class is entirely XS: storage is array slots and every method is an XSUB reading them directly, so the context costs nothing per request beyond its construction.
METHODS
env
The raw PSGI environment hashref.
app
The compiled Punk::App.
req
The lazy Punk::Request.
res
The lazy Punk::Response builder - only constructed when used.
stash
A per-request hashref for passing values between guards, hooks and the controller.
param($name)
Validated OpenAPI parameters first (path, then query), then web route captures, then the request (query, then form body).
openapi
The validated parameter hash from "validate_request" in Open::API on API routes; undef elsewhere.
model($name)
The registered Punk::Model instance (per-worker, built on first access).
render($template, \%data, %options)
Render through the app's view engines; returns a finished response. See Punk::Views.
json($data, $status?)
text($body, $status?)
html($body, $status?)
redirect($url, $status?)
not_found
Finished responses. Status and headers previously set through "status" and "header" are folded in.
status($code)
header($name => $value)
Set response status / add a response header; chainable. With no arguments status returns the pending status.
cookie($name)
cookie($name => $value, %opts)
With one argument, read a request cookie. With a value, set a Set-Cookie on the response (an undef value deletes it); options path (default /), domain, max_age, secure, httponly, samesite. The set form chains.
session
The signed cookie-backed session hashref (see Punk::Session); requires the session keyword. Read and write it; it is written back to the cookie at the end of the request if it changed.
session_expire
Log out: empty the session and delete its cookie. Chainable.
upload($name)
The Punk::Upload for a multipart/form-data file field (the first if several), via $c->req->upload.
log
The request Punk::Logger (cached for the request): $c->log->info(...), debug, warn, error, fatal. Its lines carry the request's method and path, and are delivered to the server's psgix.logger when one is present. Configure with the logging keyword. See Punk::Logger.
match
Routing information for the matched route (captures, route record).
promise
A new pending Punk::Future - loop-backed on a live Hyperman worker, self-contained (blocking) otherwise. Return it (or a then of it) from a handler to defer the response; settle it later from whatever wakes it.
get '/wait' => sub {
my ($c) = @_;
my $p = $c->promise;
$c->timer(1)->on_done(sub { $p->done($c->json({ ready => 1 })) });
return $p; # answered when $p is settled
};timer($secs)
after($secs)
A Punk::Future that settles after $secs: a loop timer on a worker, a sleep off it. $c->timer(2)->then(sub { ... }) answers the request two seconds later without pinning the worker.
await($future)
Block until $future is ready and return its values (rethrowing a failure) - pumping the loop re-entrantly on a worker, blocking off it. The imperative escape hatch; return $future is the non-blocking way.
stash_hv
openapi_params
The raw storage slots behind "stash" and "openapi", read or written directly (the accessor pair the class is built from). Prefer stash and openapi, which lazily build and coerce; these exist for the framework and for code that wants the slot untouched.
AUTHOR
LNATION <email@lnation.org>
LICENSE AND COPYRIGHT
This software is Copyright (c) 2026 by LNATION <email@lnation.org>.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)