view release on metacpan or  search on metacpan

lib/Concierge/Sessions/Session.pm  view on Meta::CPAN

This method:

=over 4

=item * Replaces the entire data field (not a merge)

=item * Marks the session as dirty (unsaved changes exist)

=item * Does NOT persist to backend (call save() for that)

=back

Example:

    my $data = $session->get_data()->{value};
    $data->{username} = 'alice';
    $data->{items} = [1, 2, 3];
    $session->set_data($data);  # Data replaced, session now dirty
    $session->save();            # Persist to backend

=head3 save

Persists dirty session data to the backend storage.

    my $result = $session->save();

Parameters:

None.

Returns:

    {
        success => 1,
    }

Or on error:

    {
        success => 0,
        message => "Error description",
    }

This method:

=over 4

=item * Is a no-op if the session is not dirty (returns success immediately)

=item * Writes the entire data field to backend storage

=item * Updates the last_updated timestamp

=item * Extends the session expiration (sliding window)

=item * Clears the dirty flag on success

=back

The save() method also implements sliding window expiration. Each save() extends
the session timeout from the current time, keeping active sessions alive.

For indefinite sessions (session_timeout set to 'indefinite'), save() still
persists data but does not modify expiration (session never expires).

=head2 Status Check Methods

=head3 is_valid

Returns true if the session is both active and not expired.

    my $valid = $session->is_valid();

This is a convenience method that combines is_active() and is_expired():

    return ($session->is_active() && !$session->is_expired()) ? 1 : 0;

Returns: 1 if valid, 0 if invalid.

Use this to check if a session can be used before accessing its data.

=head3 is_active

Returns true if the session state is 'active'.

    my $active = $session->is_active();

Returns: 1 if active, 0 if inactive.

Currently, all sessions are created in the 'active' state and there is no
API to change the state to inactive. This method is provided for future
extensibility.

=head3 is_expired

Returns true if the session has passed its expiration time.

    my $expired = $session->is_expired();

Returns: 1 if expired, 0 if not expired.

For indefinite sessions (session_timeout set to 'indefinite'), this method
always returns 0 (never expires).

Example:

    if ($session->is_expired()) {
        # Session has expired, user must re-authenticate
    } else {
        # Session is still valid
    }

=head3 is_dirty

Returns true if the session has unsaved changes.

    my $dirty = $session->is_dirty();

Returns: 1 if dirty (unsaved changes), 0 if clean.

A session becomes dirty when set_data() is called. The dirty flag is cleared