Sessions
Bond.sessions(app, options) keeps a small session in a cookie that Bond signs with HMAC-SHA256. There is no store on the server: the signature lets Bond see that the client did not change the cookie. A handler reads and changes the session as a map of text:
Bond.session(conn)is the session as aMap[String, String], empty for a visitor with none.Bond.get_session(conn, "user")is one value, a plainerrorwhen it is not there (useunwrap_ororcase, as withBond.cookie).Bond.set_session(conn, "user", "ana"),Bond.delete_session(conn, "user")andBond.clear_session(conn)give a newConnwith the session changed, asBond.statusdoes. Keep theConnthey return.
The answer carries the new session in a Set-Cookie, and only when a handler changed it: a request that only reads sets no cookie. An empty session after a change (clear_session, or the last value deleted) deletes the cookie.
The options #
Bond.app() |> Bond.sessions(Bond.SessionOptions(secret: secret)) is the whole setup. secret is the only option you must give: at least 32 bytes (Bond checks the length, not that it is random). Make it once with OpenSSL.Random.hex(32), keep it in the environment or a file, and never put it in the source. The program stops at the call of sessions when an option is wrong (a short secret, an empty name, a max_age below 1, a same_site that is not Strict, Lax or None, or None without secure).
| Option | Default | |
|---|---|---|
secret | the key that signs the cookie | |
old_secrets | [] | keys that signed cookies before (see the rotation below) |
name | _bond_session | the name of the cookie |
max_age | 1_209_600 | seconds that a session lasts (two weeks) |
secure | false | adds Secure: set it in production, over HTTPS |
same_site | "Lax" | "Strict", "Lax" or "None" |
path, domain | "/", "" | those of the cookie |
The cookie is always HttpOnly. In production use name: "__Host-session" with secure: true, the default path and no domain: a browser accepts a __Host- cookie only from a secure page for the exact host, so a sibling subdomain cannot plant a signed cookie with its own session (the first cookie of a name wins). Secure is off by default because a Secure cookie is dropped over plain HTTP, which breaks development.
The end date is inside the signed data, so a client that keeps an old cookie does not get a longer session. Every change writes a cookie that lasts max_age from then; a read does not extend it.
What is signed, and what is not #
The cookie is payload.signature, both in base64url. The signature covers the name of the cookie and the payload, with the secret. A cookie that is missing, malformed, changed, expired, or signed with a secret that Bond does not know is an empty session, never a 4xx.
The payload is not encrypted: anyone who has the cookie can read it. Keep an id or a name there, not a secret, and look up the rest on the server. A cookie over 3800 bytes would be dropped by browsers, so Bond makes that answer a 500 (through on_error) instead of sending it.
Log in with a new session: call clear_session before you set the user, so nothing of the earlier session is kept. A signed cookie cannot be revoked on the server before it expires: a logout deletes it in the visitor’s browser, but a copy stays valid until its max_age. Use a short max_age for what must end soon.
Rotating the secret #
Put the new secret in secret and the old one in old_secrets. Bond reads a cookie signed with any of them and writes it again with secret (and a new max_age) on the first request that has it, so a session in use outlives the rotation. Remove the old secret after max_age seconds.
Testing #
Testing.session_cookie(options, data) gives the name=value of a cookie signed as sessions would sign it, so a test of a route for logged-in users needs no login. It does not check the options as sessions does (a short secret, or a negative max_age, which gives an expired cookie, are accepted).
import HTTP from "std/http"
import Bond from "pkg/bond/bond"
import Testing from "pkg/bond/testing"
OPTIONS = Bond.SessionOptions(secret: "a-secret-of-at-least-32-bytes-ok")
def login(conn: Bond.Conn) -> Result[Bond.Conn]
signed_in = Bond.set_session(Bond.clear_session(conn), "user", "ana")
return ok(Bond.text(signed_in, 200, "welcome"))
end
def me(conn: Bond.Conn) -> Result[Bond.Conn]
user = Bond.get_session(conn, "user").unwrap_or("nobody")
return ok(Bond.text(conn, 200, "hello #{user}"))
end
def logout(conn: Bond.Conn) -> Result[Bond.Conn]
return ok(Bond.text(Bond.clear_session(conn), 200, "bye"))
end
def main() -> Void
app = (
Bond.app()
|> Bond.sessions(OPTIONS)
|> Bond.get("/login", &login)
|> Bond.get("/me", &me)
|> Bond.get("/logout", &logout)
)
puts(Testing.text(Testing.request(app, "GET", "/me")).unwrap!)
# The cookie of the answer goes back in the next request, as a browser does.
answer = Testing.request(app, "GET", "/login")
cookie = HTTP.header_values(answer.headers, "set-cookie").first.split(";").first
headers = [HTTP.Header(name: "Cookie", value: cookie)]
puts(Testing.text(Testing.request(app, "GET", "/me", headers)).unwrap!)
# A visitor who is logged in, with no login in the test.
made = Testing.session_cookie(OPTIONS, {"user": "bo"}).unwrap!
puts(Testing.text(Testing.request(app, "GET", "/me", [HTTP.Header(name: "Cookie", value: made)])).unwrap!)
# A changed cookie is an empty session.
changed = "_bond_session=A" + cookie.split("=")[1].slice(1, 40) + ".AAAA"
puts(Testing.text(Testing.request(app, "GET", "/me", [HTTP.Header(name: "Cookie", value: changed)])).unwrap!)
gone = Testing.request(app, "GET", "/logout", headers)
puts(HTTP.header_values(gone.headers, "set-cookie").first)
endhello nobody
hello ana
hello bo
hello nobody
_bond_session=; Path=/; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMTsessions adds a before and an after filter (see Filters), so call it before the filters that read the session. Without it, set_session changes the Conn and nothing is sent.