Bond.cookies(conn) reads the Cookie header into a Map[String, String], with std/cookie. The first value of a name wins, and the values are as the client sent them: not decoded or unquoted. More than one Cookie header is read as one. Bond.cookie(conn, "sid") gives one value as a Result.

A cookie that is not there is a plain error, like Bond.param and Bond.request_header (a first visit has no cookie, which is no mistake of the client), unlike Bond.query, where a missing name is a 400. So try Bond.cookie(conn, "sid") on a first visit is a 500: use unwrap_or or case, for example with a redirect to the login page.

Neither the readers nor Bond.set_cookie (nor std/cookie) encode or decode a value: use URI.encode_www_form_component (std/uri) before you set it, and URI.decode_www_form_component when you read it back.

Bond.set_cookie(conn, "sid", value) adds a Set-Cookie header with these defaults:

  • Path=/.
  • HttpOnly, so scripts on the page cannot read it.
  • SameSite=Lax, so the browser does not send it with a cross-site POST.
  • No Secure and no Max-Age: Bond cannot tell if the site is served over HTTPS, and a Secure cookie is dropped over plain HTTP, which would break development. The cookie lasts until the browser closes. Set Secure yourself in production, with set_cookie_with.

Bond.set_cookie_with(conn, cookie) takes a Cookie.Cookie of std/cookie (import Cookie from "std/cookie") with the attributes you give: path, domain, max_age, expires, secure, http_only and same_site. Bond adds none of its own there, so write http_only: true and same_site: "Lax" when you want them.

Both give a Result[Conn]: use try. A name that is not a token, or a value with a space, a comma, a semicolon, a quote, a control or a non-ASCII character, is an error (a 500 when it is passed on), and no cookie is set. A cookie of a year, over HTTPS, is:

import Cookie from "std/cookie"
import Bond from "pkg/bond/bond"

def remember(conn: Bond.Conn, id: String) -> Result[Bond.Conn]
  year = Cookie.Cookie(
    name: "sid",
    value: id,
    path: "/",
    max_age: 31_536_000,
    secure: true,
    http_only: true,
    same_site: "Lax",
  )
  return Bond.set_cookie_with(conn, year)
end

A name that starts with __Host- or __Secure- needs secure: true, so set_cookie always fails for it: use set_cookie_with. __Host- also needs path: "/" and no domain.

Each cookie is a header of its own: Bond never joins two Set-Cookie headers with a comma. Bond.header(conn, "Set-Cookie", value) adds a header too, instead of replacing the one of the same name, so it never wipes the cookies set before it. Set a cookie once per answer, since the headers are not merged by name. A before filter can set a cookie and a later Bond.redirect keeps it. A 500 does not: it is a new answer with no header of the failed one.

Bond.delete_cookie(conn, "sid") writes a Set-Cookie with Max-Age=0 and a date in the past. The browser matches a cookie by name, path and domain, so pass the path and domain it was set with: Bond.delete_cookie(conn, "sid", "/app", "example.com") (set_cookie uses / and no domain, the defaults). A name that starts with __Host- or __Secure- is deleted with Secure, which browsers need for those names.

import Cookie from "std/cookie"
import HTTP from "std/http"
import Bond from "pkg/bond/bond"
import Testing from "pkg/bond/testing"

def login(conn: Bond.Conn) -> Result[Bond.Conn]
  with_sid = try Bond.set_cookie(conn, "sid", "abc123")
  theme = Cookie.Cookie(name: "theme", value: "dark", max_age: 3600, secure: true, same_site: "Strict")
  with_theme = try Bond.set_cookie_with(with_sid, theme)
  return ok(Bond.text(with_theme, 200, "welcome"))
end

def whoami(conn: Bond.Conn) -> Result[Bond.Conn]
  sid = Bond.cookie(conn, "sid").unwrap_or("nobody")
  return ok(Bond.text(conn, 200, "hello #{sid}"))
end

def logout(conn: Bond.Conn) -> Result[Bond.Conn]
  gone = try Bond.delete_cookie(conn, "sid")
  return ok(Bond.text(gone, 200, "bye"))
end

def main() -> Void
  app = (
    Bond.app()
    |> Bond.get("/login", &login)
    |> Bond.get("/whoami", &whoami)
    |> Bond.get("/logout", &logout)
  )
  for path in ["/login", "/logout"]
    response = Testing.request(app, "GET", path)
    for line in HTTP.header_values(response.headers, "set-cookie")
      puts(line)
    end
  end
  headers = [HTTP.Header(name: "Cookie", value: "sid=abc123; theme=dark")]
  puts(Testing.text(Testing.request(app, "GET", "/whoami", headers)).unwrap!)
  puts(Testing.text(Testing.request(app, "GET", "/whoami")).unwrap!)
end
Output
sid=abc123; Path=/; HttpOnly; SameSite=Lax
theme=dark; Max-Age=3600; Secure; SameSite=Strict
sid=; Path=/; Max-Age=0; Expires=Thu, 01 Jan 1970 00:00:00 GMT
hello abc123
hello nobody