Skip to main content
Version: Next

Sessions

Sessions can be used to store small amounts of data that will be persisted between requests, on a per-visitor basis. This data is usually stored on the backend side (depending on the chosen session storage), and it is associated with a session ID that is persisted on the client through the use of a dedicated cookie.

Configuration​

In order to use sessions, you need to make sure that the Marten::Middleware::Session middleware is part of your project's middleware chain, which can be configured in the middleware setting. Note that the session middleware class is automatically added to this setting when initializing new projects.

If your project does not require the use of sessions, you can simply ensure that the middleware setting does not include the Marten::Middleware::Session middleware class.

How the session ID cookie is generated can also be tweaked by leveraging the following settings:

Session stores​

How session data is actually persisted can be defined by configuring the right session store backend, which can be done through the use of the sessions.store setting.

By default, sessions are encrypted and stored within a single cookie (:cookie session store). Cookies have a 4K size limit, which is usually sufficient in order to persist things like a user ID and flash messages. :cookie is the only store that is built in the Marten web framework presently.

info

The cookie store leverages a Marten::Core::Encryptor encryptor object in order to encrypt and sign session data. This means that session data is encrypted with an aes-256-cbc cipher and signed with HMAC signatures that use the SHA256 hash algorithm.

Other session stores can be installed as separate shards. For example, the marten-db-session shard can be leveraged to persist session data in the database while the marten-redis-session shard can be used for persisting session data using Redis.

Using sessions​

Setting and retrieving session values​

When the Marten::Middleware::Session middleware is used, each HTTP request object will have a #session method returning the session store for the current request. The session store is an instance of Marten::HTTP::Session::Store::Base and provides a hash-like interface:

# Persisting values:
request.session[:foo] = "bar"

# Accessing values:
request.session[:foo]
request.session[:foo]?

# Deleting values:
request.session.delete(:foo)

# Checking emptiness:
request.session.empty?

Both symbol and string keys can be used when trying to interact with the session store, but only string values can be stored.

tip

If you are trying to access the session store from within a handler, it should be noted that you can leverage the #session method instead of using the request object:

class MyHandler < Marten::Handler
  def get
    session[:foo] = "bar"
    respond "Hello World!"
  end
end

Customizing session expiry times​

By default, most session stores will expire session entries based on the value of the sessions.cookie_max_age setting. That being said, it is possible to customize when a specific session is set to expire by using one of the following methods:

For example:

request.session[:foo] = "bar"

# Set the session to expire on a specific date time:
request.session.expires_at = 2.days.from_now

# Set the session to expire in a specific duration:
request.session.expires_in = 2.hours

# Set the session to expire when the browser is closed:
request.session.expires_at_browser_close = true