Skip to content

Athena::Framework::Bundle::Schema::Session#

Configures sessions, which store data about the client across requests, such as flash messages.

ATH.configure({
  framework: {
    session: {
      enabled: true,
    },
  },
})

The session of the current request is available via AHTTP::Request#session, or by typing an action parameter as AHTTP::Session. See AHK::Listeners::Session for more information on how it is persisted.

Configuration Properties

enabled#

type:

Bool

default:

false

If false, sessions are disabled and the related types are not included in the resulting binary.

handler_id#

type:

String | ::Nil

default:

nil

The ID of the service used to persist sessions, which must implement AHTTP::Session::Storage::Handler::Interface. If nil, an AHTTP::Session::Storage::Handler::File storing sessions in the #save_path directory is used.

save_path#

type:

String | ::Nil

default:

nil

The directory the default AHTTP::Session::Storage::Handler::File stores sessions in, which is created if it does not exist. If nil, a directory called athena_sessions within the system's tempdir is used. It must be owned by the user running the application, without permissions for its group and others.

name#

type:

String

default:

athena_session_id

The name of the session cookie. Prefixing it with __Host- keeps other subdomains from setting a cookie with the same name, which browsers only accept if it is secure, its #cookie_path is /, and it has no #cookie_domain.

cookie_lifetime#

type:

Int32

default:

0

The lifetime of the session cookie in seconds, 0 meaning until the browser is closed.

cookie_path#

type:

String

default:

/

The path the session cookie is sent for.

cookie_domain#

type:

String | ::Nil

default:

nil

The domain the session cookie is sent to. If nil, only the host that set it.

cookie_secure#

type:

Bool | ::Nil

default:

nil

If the session cookie is only sent over HTTPS. If nil, only if the request that set it was made over HTTPS, as determined by AHTTP::Request#secure?. Behind a reverse proxy, this requires trusted proxies to be configured.

cookie_httponly#

type:

Bool

default:

true

If the session cookie is inaccessible to JavaScript.

cookie_samesite#

type:

::HTTP::Cookie::SameSite

default:

lax

If the session cookie is sent along with cross-site requests.

gc_maxlifetime#

type:

Int32

default:

1440

How many seconds a session may go unused before it expires.

gc_probability#

type:

Int32

default:

1

Expired sessions are removed on #gc_probability / #gc_divisor of the requests starting a session.

gc_divisor#

type:

Int32

default:

100

See #gc_probability. Must be greater than 0.

metadata_update_threshold#

type:

Int32

default:

60

How many seconds to wait before updating when the session was last used. Otherwise each request using the session would write it, even if its data did not change.