Cookie (std)

std/cookie is written in Agentica and has the behaviour of Rack’s parse_cookies_header and set_cookie_header: import Cookie from "std/cookie". It reads a Cookie request header and writes a Set-Cookie response header. Nothing in it halts, whatever the input.

Cookie.parse(header: String) -> Map[String, String]
Cookie.set_header(cookie: Cookie.Cookie) -> Result[String]

Cookie.Cookie(name: String, value: String, ...) is a cookie to send. The other fields have defaults, and an attribute left at its default is not written.

struct Cookie.Cookie
  name: String
  value: String
  path: String = ""
  domain: String = ""
  max_age: Int = Cookie.NO_MAX_AGE  # no Max-Age; 0 or less writes Max-Age=0, which deletes the cookie
  expires: String = ""              # written as it is: "Wed, 21 Oct 2015 07:28:00 GMT"
  secure: Bool = false
  http_only: Bool = false
  same_site: String = ""            # "Strict", "Lax" or "None"
end
import Cookie from "std/cookie"

def main() -> Void
  puts(Cookie.parse("sid=abc123; theme=dark; sid=other"))
  cookie = Cookie.Cookie(
    name: "sid",
    value: "abc123",
    path: "/",
    max_age: 3600,
    secure: true,
    http_only: true,
    same_site: "Lax",
  )

  puts(Cookie.set_header(cookie))
  puts(Cookie.set_header(Cookie.Cookie(name: "sid", value: "a b")))
end
Output
{"sid": "abc123", "theme": "dark"}
ok("sid=abc123; Path=/; Max-Age=3600; Secure; HttpOnly; SameSite=Lax")
error("invalid cookie value (byte 1)", kind: "argument")

parse splits the header on ;, drops spaces around each piece, and splits a piece on its first =. A piece without = or with an empty name is skipped, and the first value of a repeated name wins, as in Rack’s parse_cookies_header. The map keeps the order of the first appearance.

set_header writes name=value and then the attributes in Rack’s order: Domain, Path, Max-Age, Expires, Secure, HttpOnly, SameSite (Rack 3 writes the attribute names in lowercase; this writes them capitalized). There is no date type, so expires is text you format. max_age is Cookie.NO_MAX_AGE, the smallest Int, when there is no Max-Age, so a computed negative number is never taken for it: it writes Max-Age=0 and the browser deletes the cookie. It returns an error that names the field when:

  • name is empty or is not an RFC 7230 token (letters, digits and !#$%&'*+-.^_`|~),
  • value has a byte that RFC 6265 does not allow: a space, ", ,, ;, \, a control or a non-ASCII byte; the error gives the position of the byte (invalid cookie value (byte 3)) and never the value, which may be a secret,
  • path, domain or expires has a control, a non-ASCII byte or ;, domain has a space, or path or expires starts or ends with a space,
  • same_site is not Strict, Lax or None, or is None without secure: true,
  • the name starts with __Secure- and secure is false, or starts with __Host- and secure is false, path is not / or domain is set (the prefix is matched without regard to case, as browsers do).

The text of an error about a name or an attribute has its control bytes removed, so it is safe in a log line.

Unlike Ruby’s CGI::Cookie and Rack, which escape the value when writing it and decode it when reading, the cookie functions never percent-encode, decode or quote, and this is final. The value is written as it is and read as the client sent it, so a caller that needs a value with a space, a comma or non-ASCII text encodes it before set_header and decodes it after parse. A %41 in a header stays %41.

A program that has its own name Cookie imports the module under another alias, such as import C from "std/cookie", because import Cookie would clash with it (CHECK-REDEFINED-NAME).