/ 
Punk-0.02
/ Punk::Session

NAME

Punk::Session - signed cookie sessions

SYNOPSIS

package MyApp;
use Punk;

session
    secret   => secret('session_key'),   # from the secrets system
    expires  => '7d',
    samesite => 'Lax';

post '/login' => sub {
    my ($c) = @_;
    $c->session->{user_id} = $user->id;   # signed into the cookie
    $c->redirect('/');
};

get '/me' => sub {
    my ($c) = @_;
    my $id = $c->session->{user_id} or return $c->redirect('/login');
    $c->json({ id => $id });
};

post '/logout' => sub { my ($c) = @_; $c->session_expire; $c->redirect('/') };

DESCRIPTION

A session is a hashref carried in a cookie: the handler reads and writes $c->session, and at the end of the request Punk serializes it (JSON), signs it with HMAC-SHA256 and the configured secret, and sets the cookie - only when it actually changed. The client can read the contents but cannot forge them, so do not put secrets in a session; a tampered cookie is rejected and the session comes up empty.

There is no server-side store in this cut: the whole session lives in the cookie. A session that serializes over ~4KB croaks, pointing at where a server-side store would go.

THE KEYWORD

session secret => secret('key'), expires => '7d', secure => 1;

Enables sessions for the application. Options:

  • secret - the signing key (required for a real deployment); source it from the secrets system so it never sits in the code.

  • cookie - the cookie name (default punk.sid).

  • expires - a lifetime like '7d' / '12h' / '30m' / seconds; omitted means a session cookie (gone when the browser closes).

  • path (default /), domain, secure, httponly (default on), samesite (default Lax) - the cookie attributes.

It also reads from config/punk.yml under a session: block.

CONTEXT METHODS

session

The session hashref. 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 the cookie.

SEE ALSO

Punk, "cookie" in Punk::Context, "secret" in Punk.

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)