Skip to content

class Athena::HTTP::Session::Storage
inherits Reference #

Manages the lifecycle of an AHTTP::Session, persisting its data via the provided AHTTP::Session::Storage::Handler::Interface.

  • The session is only loaded once it is started, and is identified by a random 128 bit ID
  • Unknown or expired session IDs are replaced by a new ID, so a client can't choose its own session ID
  • The session data is only written if it changed, otherwise only the session's timestamp is updated
  • Empty sessions are not persisted, and are removed if they were
  • Expired sessions are removed via the handler's #gc method on gc_probability / gc_divisor of the started sessions

The session data is persisted as a JSON object, with the data of each bag under its storage key.

Included modules

Athena::HTTP::Session::Storage::Interface

Constants#

VALID_ID = /\A[a-zA-Z0-9,-]{22,250}\z/#

The session IDs that are accepted from the client. Only allows characters that are safe to use in e.g. file names.

Constructors#

.new(handler : AHTTP::Session::Storage::Handler::Interface, metadata_bag : AHTTP::Session::Storage::MetadataBag = AHTTP::Session::Storage::MetadataBag.new, name : String = "athena_session_id", gc_max_lifetime : Int32 = 1440, gc_probability : Int32 = 1, gc_divisor : Int32 = 100)#

Creates a new storage, persisting the session via the provided handler.

The name is the name of the session, i.e. its cookie. The gc_max_lifetime is how many seconds a session may be unused for before the handler removes it.

View source

Methods#

#bag(name : String) : AHTTP::Session::BagInterface#

Returns the bag registered with the provided name, starting the session if needed.

Raises an AHTTP::Exception::InvalidArgument if no bag with the provided name is registered.

View source

#clear : Nil#

Clears all session data.

View source

#id : String#

Returns the ID of the session, or an empty string if it does not have one yet.

View source

#id=(id : String)#

Sets the ID of the session to load once it is started.

Raises an AHTTP::Exception::Logic if the session is already started.

View source

#metadata_bag : AHTTP::Session::Storage::MetadataBag#

Returns the bag storing the session's metadata.

View source

#name : String#

Returns the name of the session, i.e. the name of its cookie.

View source

#name=(name : String)#

Sets the name of the session.

Raises an AHTTP::Exception::Logic if the session is already started.

View source

#regenerate(destroy : Bool = false, lifetime : Int32 | Nil = nil) : Bool#

Gives the session a new ID while keeping its data, optionally removing the persisted data of the current ID if destroy is true. Optionally sets the lifetime of its cookie in seconds, 0 meaning until the browser is closed.

Returns true if the session was given a new ID, otherwise false.

Starts the session if needed, so that a session that was not used yet still gets a new ID. If destroy is false, the current ID keeps the current data, so requests still using it keep working.

View source

#register_bag(bag : AHTTP::Session::BagInterface) : Nil#

Registers the provided bag, whose data is loaded and persisted along with the session.

Raises an AHTTP::Exception::Logic if the session is already started.

View source

#save : Nil#

Persists the session data and closes the session.

View source

#start : Bool#

Starts the session, loading its data. Returns true once the session is started.

View source

#started? : Bool#

Returns true if the session is started, otherwise false.

View source