class Athena::HTTP::Session
inherits Reference
#
Stores data about the client across requests, such as the logged in user or flash messages.
The session is only loaded from its AHTTP::Session::Storage::Interface once it is used, and the data of each request using it is persisted once the request is done.
Attributes are stored as JSON, so any type that can be serialized via #to_json and deserialized via .from_json can be stored.
E.g. scalars, arrays, hashes, or types that include JSON::Serializable.
session.set "cart", [1, 2, 3]
session.get "cart", Array(Int32) # => [1, 2, 3]
session.get? "user_id", Int64 # => nil
session.flash_bag.add "notice", "Your changes were saved!"
Constructors#
.new(storage : AHTTP::Session::Storage::Interface, attributes : AHTTP::Session::AttributeBag = AHTTP::Session::AttributeBag.new, flashes : AHTTP::Session::FlashBag = AHTTP::Session::FlashBag.new, usage_reporter : Proc(Nil) | Nil = nil)#
Creates a new session, stored via the provided storage.
The optional usage_reporter is called each time the session is used, see #usage_index.
Methods#
#all : Hash(String, String)#
Returns all attributes, with their values serialized as JSON.
#bag(name : String) : AHTTP::Session::BagInterface#
Returns the bag registered with the provided name, starting the session if needed.
#flash_bag : AHTTP::Session::FlashBag#
Returns the bag storing the session's flash messages.
#get(name : String, type : T.class) : T forall T#
Returns the value of the attribute with the provided name, deserialized as the provided type.
Raises a KeyError if no attribute with that name exists.
#get?(name : String, type : T.class) : T | Nil forall T#
Returns the value of the attribute with the provided name, deserialized as the provided type, or nil if it does not exist.
#has?(name : String) : Bool#
Returns true if an attribute with the provided name exists, otherwise false.
#id : String#
Returns the ID of the session, or an empty string if it does not have one yet.
Until the session is started, this is the ID sent by the client, which is only validated once the session starts.
#invalidate(lifetime : Int32 | Nil = nil) : Bool#
Clears all session data and gives the session a new ID, removing the data of the current ID.
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.
#metadata_bag : AHTTP::Session::Storage::MetadataBag#
Returns the bag storing the session's metadata, such as when it was created.
#migrate(destroy : Bool = false, lifetime : Int32 | Nil = nil) : Bool#
Gives the session a new ID while keeping its data, optionally removing the 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.
Should be used with destroy set to true whenever the privileges of the client change, such as when logging in, to prevent session fixation.
Otherwise the current ID keeps a copy of the session's data, e.g. the logged in user, which anyone knowing the current ID could then use.
Returns true if the session was given a new ID, otherwise false.
#register_bag(bag : AHTTP::Session::BagInterface) : Nil#
Registers the provided bag, whose data is loaded and persisted along with the session.
#remove(name : String) : Nil#
Removes the attribute with the provided name, if it exists.
#save : Nil#
Persists the session data and closes the session.
The session is automatically saved once the request is done.
#set(name : String, value : _) : Nil#
Sets the attribute with the provided name to the provided value.
#start : Bool#
Starts the session, loading its data.
Returns true once the session is started.
The session is automatically started once its data is accessed.
#usage_index : Int32#
Returns how many times the session was used, e.g. by accessing its bags or checking if it is empty.
Used to determine if a request used the session, e.g. to mark its response as private.