/ 
Hypersonic-0.11
/ Hypersonic::Session

NAME

Hypersonic::Session - JIT-compiled session management for Hypersonic

SYNOPSIS

use Hypersonic;

my $server = Hypersonic->new();

# Enable sessions
$server->session_config(
    secret      => 'your-secret-key-at-least-16-chars',
    cookie_name => 'sid',
    max_age     => 86400,      # 1 day
    httponly    => 1,
    secure      => 1,          # HTTPS only
    samesite    => 'Strict',
);

# Use sessions in handlers
$server->get('/profile' => sub {
    my ($req) = @_;
    my $user = $req->session('user');
    return res->json({ user => $user });
}, { dynamic => 1 });

$server->post('/login' => sub {
    my ($req) = @_;
    my $data = $req->json;

    # Set session data
    $req->session(user => $data->{username});
    $req->session(logged_in => 1);

    return res->json({ success => 1 });
}, { dynamic => 1, parse_json => 1 });

$server->post('/logout' => sub {
    my ($req) = @_;
    $req->session_clear;
    return res->json({ logged_out => 1 });
}, { dynamic => 1 });

DESCRIPTION

Hypersonic::Session provides fast, secure session management using signed cookies for session IDs and in-memory storage for session data.

JIT-Compiled Cryptography

When OpenSSL is available, cryptographic operations are JIT-compiled to native C code for maximum performance:

  • HMAC-SHA256 signing - Direct OpenSSL calls (~3-5x faster)

  • Session ID generation - Direct /dev/urandom read (~5-10x faster)

  • Constant-time comparison - C-level timing attack resistance

  • Combined verification - Single C function for parse+verify

Falls back to pure Perl (Digest::SHA) when OpenSSL is unavailable.

Security Features

  • HMAC-SHA256 signed session IDs (tamper-proof)

  • Secure random session ID generation

  • Constant-time signature verification (timing attack resistant)

  • HttpOnly and Secure cookie flags

  • SameSite cookie attribute

JIT Philosophy

Session middleware is only injected when session_config() is called. No session code runs for routes that don't use sessions.

CONFIGURATION OPTIONS

secret (required)

Secret key for HMAC signing. Must be at least 16 characters.

Session cookie name. Default: hsid

max_age

Session lifetime in seconds. Default: 86400 (1 day)

path

Cookie path. Default: /

httponly

Set HttpOnly flag. Default: 1

secure

Set Secure flag (HTTPS only). Default: 0

samesite

SameSite attribute. Default: Lax

CLASS METHODS

compile_session_ops

Hypersonic::Session->compile_session_ops(
    cache_dir => '_session_cache',
);

Compile the JIT cryptographic operations. Called automatically when configure() is first called.

Returns true if JIT compilation succeeded, false otherwise.

is_jit_compiled

if (Hypersonic::Session->is_jit_compiled) {
    # Using native C crypto
}

Returns true if JIT compilation succeeded.

SEE ALSO

Hypersonic, Hypersonic::Request, Hypersonic::Response, Hypersonic::TLS

AUTHOR

LNATION <email@lnation.org>

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.