Cookies
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.
Setting a cookie #
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-sitePOST.- No
Secureand noMax-Age: Bond cannot tell if the site is served over HTTPS, and aSecurecookie is dropped over plain HTTP, which would break development. The cookie lasts until the browser closes. SetSecureyourself in production, withset_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)
endA 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.
Deleting a cookie #
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!)
endsid=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