File Coverage

blib/lib/PAGI/Middleware/Session.pm

Criterion	Covered	Total	%
statement	90	92	97.8
branch	20	22	90.9
condition	11	21	52.3
subroutine	15	15	100.0
pod	1	2	50.0
total	137	152	90.1

package PAGI::Middleware::Session;

use strict;
use warnings;
use parent 'PAGI::Middleware';
use Future::AsyncAwait;
use Digest::SHA qw(sha256_hex);
use PAGI::Utils::Random qw(secure_random_bytes);

=head1 NAME

PAGI::Middleware::Session - Session management middleware with pluggable State/Store

=head1 SYNOPSIS

    use PAGI::Middleware::Builder;

    # Default (cookie-based, in-memory store)
    my $app = builder {
        enable 'Session', secret => 'your-secret-key';
        $my_app;
    };

    # Explicit state and store
    use PAGI::Middleware::Session::State::Header;
    use PAGI::Middleware::Session::Store::Memory;

    my $app = builder {
        enable 'Session',
            secret => 'your-secret-key',
            state  => PAGI::Middleware::Session::State::Header->new(
                header_name => 'X-Session-ID',
            ),
            store  => PAGI::Middleware::Session::Store::Memory->new;
        $my_app;
    };

    # In your app:
    async sub app {
        my ($scope, $receive, $send) = @_;

        # Raw hashref access
        my $session = $scope->{'pagi.session'};
        $session->{user_id} = 123;

        # Or use the PAGI::Session helper
        use PAGI::Session;
        my $s = PAGI::Session->new($scope->{'pagi.session'});
        $s->set('user_id', 123);
        my $uid = $s->get('user_id');  # dies if key missing
    }

=head1 DESCRIPTION

PAGI::Middleware::Session provides server-side session management with a
pluggable architecture for session ID transport (State) and session data
storage (Store).

The B layer controls how the session ID travels between client and
server (cookies, headers, bearer tokens, or custom logic). The B
layer controls where session data is persisted (memory, Redis, database).

By default, sessions use cookie-based IDs and in-memory storage.

B The default in-memory store is suitable for development and
single-process deployments only. Sessions are not shared between workers
and are lost on restart. For production multi-worker deployments, provide
a C object backed by Redis, a database, or another shared storage.

=head1 CONFIGURATION

=over 4

=item * secret (required)

Secret key used for session ID generation.

=item * expire (default: 3600)

Session expiration time in seconds.

=item * state (optional)

A L object that implements C
and C. If not provided, a
L instance is created using
C, C, and C.

=item * store (optional)

A L object that implements async C,
C, and C. If not provided, a
L instance is created.

=item * cookie_name (default: 'pagi_session')

Name of the session cookie. Only used when C defaults to
L.

=item * cookie_options (default: { httponly => 1, path => '/', samesite => 'Lax' })

Options for the session cookie. Only used when C defaults to
L. For production HTTPS
deployments, add C<< secure => 1 >>.

=back

=head1 STATE CLASSES

State classes control how the session ID is extracted from requests and
injected into responses. All implement the L
interface.

=over 4

=item L

Default. Reads the session ID from a request cookie and sets it via
C on the response. Suitable for browser-based web applications.

=item L

Reads the session ID from a custom HTTP header. Requires C;
accepts an optional C regex with a capture group. Injection is a
no-op (the client manages header-based transport).

    PAGI::Middleware::Session::State::Header->new(
        header_name => 'X-Session-ID',
    );

=item L

Convenience subclass of State::Header that reads an opaque bearer token from
the CtokenE> header. Intended for opaque
session tokens, B JWTs. For JWT authentication, use
L instead.

    PAGI::Middleware::Session::State::Bearer->new();

=item L

Custom session ID transport using coderefs. Requires an C coderef;
accepts an optional C coderef (defaults to no-op).

    PAGI::Middleware::Session::State::Callback->new(
        extract => sub { my ($scope) = @_; ... },
        inject  => sub { my ($headers, $id, $options) = @_; ... },
    );

=back

=head1 STORE CLASSES

Store classes control where session data is persisted. All implement the
L interface; methods return L
objects for async compatibility.

=over 4

=item L

Default. In-memory hash storage. Not shared across workers or restarts.
Suitable for development and testing only.

=item External stores

Redis, database, and other shared stores are available as separate CPAN
distributions. Any object implementing C, C,
and C (returning Futures) can be used.

=back

=head1 PAGI::Session HELPER

L is a standalone helper object that wraps the raw session
data hashref with a clean accessor interface.

    use PAGI::Session;
    my $session = PAGI::Session->new($scope->{'pagi.session'});

Key methods:

=over 4

=item * C - Dies if the key does not exist (catches typos).

=item * C - Returns C<$default> for missing keys.

=item * C - Sets a session value.

=item * C - Checks key existence.

=item * C - Removes a key.

=item * C - Lists user keys (excludes internal C<_>-prefixed keys).

=item * C - Returns the session ID.

=item * C - Requests session ID regeneration on next response.

=item * C - Marks the session for deletion.

=back

The helper stores a reference to the underlying hash, so mutations are
visible to the middleware.

=head1 IDEMPOTENCY

The middleware skips processing if C<< $scope-E{'pagi.session'} >>
already exists. This prevents double-initialization when the middleware
appears more than once in a stack.

For mixed auth patterns (e.g. web cookies for browsers, bearer tokens for
APIs), use L with fallback
logic instead of stacking multiple Session middleware instances:

    use PAGI::Middleware::Session::State::Callback;
    use PAGI::Middleware::Session::State::Cookie;
    use PAGI::Middleware::Session::State::Bearer;

    my $cookie_state = PAGI::Middleware::Session::State::Cookie->new(
        cookie_name => 'pagi_session',
        expire      => 3600,
    );
    my $bearer_state = PAGI::Middleware::Session::State::Bearer->new();

    enable 'Session',
        secret => $ENV{SESSION_SECRET},
        state  => PAGI::Middleware::Session::State::Callback->new(
            extract => sub {
                my ($scope) = @_;
                return $bearer_state->extract($scope)
                    // $cookie_state->extract($scope);
            },
            inject => sub {
                my ($headers, $id, $options) = @_;
                $cookie_state->inject($headers, $id, $options);
            },
        );

=cut

sub _init {
    my ($self, $config) = @_;

    $self->{secret} = $config->{secret}
        // die "Session middleware requires 'secret' option";
    $self->{expire} = $config->{expire} // 3600;

    # State: pluggable session ID transport
    if ($config->{state}) {
        $self->{state} = $config->{state};
    } else {
        require PAGI::Middleware::Session::State::Cookie;
        $self->{state} = PAGI::Middleware::Session::State::Cookie->new(
            cookie_name    => $config->{cookie_name} // 'pagi_session',
            cookie_options => $config->{cookie_options} // {
                httponly => 1,
                path     => '/',
                samesite => 'Lax',
            },
            expire => $self->{expire},
        );
    }

    # Store: pluggable async session storage
    if ($config->{store}) {
        $self->{store} = $config->{store};
    } else {
        require PAGI::Middleware::Session::Store::Memory;
        $self->{store} = PAGI::Middleware::Session::Store::Memory->new();
    }
}

sub wrap {
    my ($self, $app) = @_;

    return async sub  {
        my ($scope, $receive, $send) = @_;
        if ($scope->{type} ne 'http') {
            await $app->($scope, $receive, $send);
            return;
        }

        # Idempotency: skip if session already exists in scope
        if (exists $scope->{'pagi.session'}) {
            warn "Session middleware: pagi.session already in scope, skipping\n"
                if $ENV{PAGI_DEBUG};
            await $app->($scope, $receive, $send);
            return;
        }

        # Extract session ID via state handler
        my $session_id = $self->{state}->extract($scope);

        # Validate and load session
        my ($session, $is_new) = await $self->_load_or_create_session($session_id);
        $session_id = $session->{_id};

        # Add session to scope
        my $new_scope = {
            %$scope,
            'pagi.session'    => $session,
            'pagi.session_id' => $session_id,
        };

        # Wrap send to save session and inject state
        my $wrapped_send = async sub {
            my ($event) = @_;
            if ($event->{type} eq 'http.response.start') {
                my @headers = @{$event->{headers} // []};

                if ($session->{_destroyed}) {
                    # Destroy: delete from store, clear client state
                    await $self->{store}->delete($session_id);
                    $self->{state}->clear(\@headers);
                }
                elsif ($session->{_regenerated}) {
                    # Regenerate: new ID, delete old, save under new
                    my $old_id = $session_id;
                    $session_id = $self->_generate_session_id();
                    $session->{_id} = $session_id;
                    delete $session->{_regenerated};
                    await $self->{store}->delete($old_id);
                    my $transport = await $self->_save_session($session_id, $session);
                    $self->{state}->inject(\@headers, $transport, {});
                }
                else {
                    # Normal: save and inject if new
                    my $transport = await $self->_save_session($session_id, $session);
                    if ($is_new) {
                        $self->{state}->inject(\@headers, $transport, {});
                    }
                }

                await $send->({ %$event, headers => \@headers });
                return;
            }
            await $send->($event);
        };

        await $app->($new_scope, $receive, $wrapped_send);
    };
}

async sub _load_or_create_session {
    my ($self, $session_id) = @_;

    # Try to load existing session. The store handles validation —
    # server-side stores return undef for unknown IDs, cookie stores
    # return undef if decoding/verification fails.
    if (defined $session_id && length $session_id) {
        my $session = await $self->_get_session($session_id);
        if ($session && !$self->_is_expired($session)) {
            $session->{_last_access} = time();
            return ($session, 0);
        }
    }

    # Create new session
    $session_id = $self->_generate_session_id();
    my $session = {
        _id          => $session_id,
        _created     => time(),
        _last_access => time(),
    };

    return ($session, 1);
}

sub _generate_session_id {
    my ($self) = @_;

    # Use cryptographically secure random bytes
    my $random = unpack('H*', secure_random_bytes(16));
    my $time = time();
    return sha256_hex("$random-$time-$self->{secret}");
}

async sub _get_session {
    my ($self, $id) = @_;
    return await $self->{store}->get($id);
}

async sub _save_session {
    my ($self, $id, $session) = @_;
    return await $self->{store}->set($id, $session);
}

sub _is_expired {
    my ($self, $session) = @_;

    my $last_access = $session->{_last_access} // $session->{_created} // 0;
    return (time() - $last_access) > $self->{expire};
}

# Class method to clear all sessions (useful for testing)
sub clear_sessions {
    require PAGI::Middleware::Session::Store::Memory;
    PAGI::Middleware::Session::Store::Memory::clear_all();
}

1;

__END__