Use signed cookies to store the session for a client.

Sessions stored this way are signed to ensure that they have not been tampered. The secret given to config must be kept secure to prevent sessions being tampered

NOTE: the session is not encrypted so a user can read any value from the session, they are just unable to modify it.

Configuring sessions

Configuration is required to use signed cookies a session store. The most important value is the secret that is used when signing and verifying. To set up an new configuration use config/1.

It often makes sense to keep your session config in the application state

def handle_request(request, %{sessions: session_config})

Working with sessions

A session can be any term. Use embed/3 to set a new session value for a client. Embedding a new session value will override any previouse value.

iex> config = SignedCookie.config(secret: "eggplant")
...> Raxx.response(:no_content)
...> |> SignedCookie.embed({:user, 25}, config)
...> |> Raxx.get_header("set-cookie")
"raxx.session=g2gCZAAEdXNlcmEZ--gpW5K8Pgle9isXR5Qymz4m2VEU1DuEosNfgpLTQuRn0=; path=/; HttpOnly"

A client that has received a session should send it with all subequent requests. A session can be retrieved using extract/2. This step will also verify that the session has not been tampered with.

iex> config = SignedCookie.config(secret: "eggplant")
...> Raxx.request(:GET, "/")
...> |> Raxx.set_header("cookie", "raxx.session=g2gCZAAEdXNlcmEZ--gpW5K8Pgle9isXR5Qymz4m2VEU1DuEosNfgpLTQuRn0=")
...> |> SignedCookie.extract(config)
{:ok, {:user, 25}}

iex> config = SignedCookie.config(secret: "eggplant")
...> Raxx.request(:GET, "/")
...> |> Raxx.set_header("cookie", "raxx.session=g2gCZAAEdXNlcmEZ--sfbxaB-IEgUt_NwdmmZpJny9OzOx15D-6uwusW6X1ZY=")
...> |> SignedCookie.extract(config)
{:error, :could_not_verify_signature}

A session can be concluded by marking as expired. For example in response to a users sign out request.

iex> config = SignedCookie.config(secret: "eggplant")
...> Raxx.response(:no_content)
...> |> SignedCookie.expire(config)
...> |> Raxx.get_header("set-cookie")
"raxx.session=; path=/; expires=Thu, 01 Jan 1970 00:00:00 GMT; max-age=0; HttpOnly"

NOTE

• This module will be extracted from the Raxx project before 1.0 release.
• The Rack.Session.Cookie module was the inspiration for this functionality. https://github.com/rack/rack/blob/master/lib/rack/session/cookie.rb