Session handler for Kemal kemal session session-storage-engine
1.0.0 Latest release released
53 29 4


Build Status

Session support for Kemal :rocket:


Add this to your application's shard.yml:

    github: kemalcr/kemal-session


Basic Usage

require "kemal"
require "kemal-session"

get "/set" do |env|"number", rand(100)) # set the value of "number"
  "Random number set."

get "/get" do |env|
  num  ="number") # get the value of "number""hello") # get value or nil, like []?
  "Value of random number is #{num}."

Available Types

The session can save many different types but the method names differ from the type.

| Type | Access Method | |------|---------------| | Int32 | | | Int64 | session.bigint | | String | session.string | | Float64 | session.float | | Bool | session.bool | | StorableObject | session.object |

You can also access the underyling hash directly by appending s to the name: session.ints. This way you can use hash functions like

session.ints.each do |k, v|
  puts "#{k} => #{v}"

BUT: This should only be used for reading and analyzing values, never for changing them. Because otherwise the session won't automatically save the changes and you may produce really weird bugs...


kemal-session has the ability to save objects to session storage. By saving objects to session storage, this opens up the ability to have more advanced data types that aren't supported by the base types (Int32, Int64, Float64, String, Bool). Any object that you want to save to session storage needs to include the Kemal::Session::StorableObject module. The class must respond to to_json and from_json. NOTE The module must be included after the definition of to_json and from_json. Otherwise the compiler will not know that those methods have been defined on the class. Here's an example implementation:

class UserStorableObject
  include JSON::Serializable
  include Kemal::Session::StorableObject

  def initialize(@id : Int32, @name : String); end

Once a Kemal::Session::StorableObject has been defined, you can save that in session storage just like the base types. Here's an example using the UserStorableObject implementation:

require "kemal"
require "kemal-session"

get "/set" do |env|
  user =, "charlie")
  env.session.object("user", user)

get "/get" do |env|
  user = env.session.object("user").as(UserStorableObject)
  "The user stored in session is #{}"

Serialization is up to you. You can define how you want that to happen so long as the resulting type is a String. If you need recommendations or advice, check with the underlying session storage implementation.


The Session can be configured in the same way as Kemal itself:

Kemal::Session.config do |config|
  config.cookie_name = "session_id"
  config.secret = "some_secret"
  config.gc_interval = 2.minutes # 2 minutes


Kemal::Session.config.cookie_name = "session_id"
Kemal::Session.config.secret = "some_secret"
Kemal::Session.config.gc_interval = 2.minutes # 2 minutes

| Option | explanation | default | |---|---|---| | timeout | How long is the session valid after last user interaction? |, 0, 0) (1 hour) | | cookie_name | Name of the cookie that holds the session_id on the client | "kemal_sessid" | | engine | How are the sessions saved on the server? (see section below) | | | gc_interval | In which interval should the garbage collector find and delete expired sessions from the server? |, 4, 0) (4 minutes) | | secret | Used to sign the session ids before theyre saved in the cookie. Strongly encouraged to create your own secret | "" | | secure | The cookie used for session management should only be transmitted over encrypted connections. | false | | domain | Domain to use to scope cookie | nil | | path | Scope cookie to a particular path | "/" |

Setting the Engine

The standard engine is the MemoryEngine

The engine you use has a huge impact on performance and can enable you to share sessions between different servers, make them available to any other application or whatever you can imagine. So the choice of engine is very important.

Kemal::Session.config.engine ={:sessions_dir => "/var/foobar/sessions/"})

You can also write your own engine if you like. Take a look at the wiki page. If you think it might also be helpful for others just let me know about it and I will include it in a list of known engines or something.

Creating a new secret

crystal eval 'require "random/secure"; puts Random::Secure.hex(64)'

Once this has been generated, it's very important that you keep this in a safe place. Environment variables tend to be a good place for that. If the secret is lost all of the sessions will get reset.

Logout and managing sessions

If you want to log a user out, simply call destroy on the session object:

get "/logout" do |env|
  "You have been logged out."

It is also possible to manage other users' sessions if you want to build an administrator's interface, for example:

  • Kemal::Session.get(session_id) returns the session object identified by the given id
  • Kemal::Session.each { |session| … } executes the given block on every session
  • Kemal::Session.all returns an array containing all sessions
  • Kemal::Session.destroy(session_id) destroys the session identified by the given id (logs the user out)
  • Kemal::Session.destroy_all destroys all sessions (logs everyone out including you)

You should be very careful with those, though. These functions enable you to access and modify all information that is stored in all sessions, also in those that do not belong to the current user. So take extra care of security when using them. Additionally, depending on the engine used and on how many active sessions there are, Kemal::Session.all and Kemal::Session.each might be memory intensive as they have to load all the sessions into memory at once, in the worst case. It is best to check/ask how your engine handles that when in doubt.

Securing the cookies

You can use the samesite parameter like the following

Kemal::Session.config do |config|
  config.samesite = HTTP::Cookie::SameSite::Strict

Compatible Engines


Special thanks to Thyra for initial efforts.

  github: kemalcr/kemal-session
  version: ~> 1.0.0
Crystal >= 0.36.0


Dependencies 0

Development Dependencies 1

  • kemal
    {'github' => 'kemalcr/kemal'}
Last synced .
search fire star recently