Add cookie parsing and serialization (#80)

Stallion users can now read cookies from requests and build validated
Set-Cookie response headers without pulling in a web framework. Cookie
signing (HMAC) stays in pyrois.

Request cookies are automatically parsed from Cookie headers and
available via request'.cookies.get("name") or .values(). ParseCookies
provides direct parsing for use outside the request lifecycle.

SetCookieBuilder constructs Set-Cookie headers with secure defaults
(Secure, HttpOnly, SameSite=Lax). It validates names (RFC 2616 token),
values (RFC 6265 cookie-octets), path and domain attributes (US-ASCII
0x20-0x7E, no semicolons), __Host-/__Secure- prefix rules (case-sensitive
per RFC 6265bis), and SameSite=None + Secure consistency, returning typed
errors on failure.

Headers.values() now yields Header val objects instead of (String, String)
tuples — a breaking change for code that destructures header values.

Design: #74

Closes #79

Author: SeanTAllen

.release-notes/next-release.md

@@ -0,0 +1,55 @@
+## Added cookie parsing and serialization
+
+Stallion now provides built-in cookie support in two directions: reading cookies from requests and building `Set-Cookie` response headers.
+
+Cookies are automatically parsed from `Cookie` request headers and available on the `Request` object. Use `request'.cookies.get("name")` to look up a cookie by name, or `request'.cookies.values()` to iterate over all parsed cookies:
+
+```pony
+fun ref on_request_complete(request': stallion.Request val,
+  responder: stallion.Responder)
+=>
+  match request'.cookies.get("session")
+  | let token: String val =>
+    // Use the session token
+  end
+```
+
+For direct parsing outside the request lifecycle, `ParseCookies` accepts a raw `Cookie` header value string or a `Headers val` collection.
+
+To build `Set-Cookie` response headers, use `SetCookieBuilder`. It defaults to `Secure`, `HttpOnly`, and `SameSite=Lax` — override explicitly when needed:
+
+```pony
+match stallion.SetCookieBuilder("session", token)
+  .with_path("/")
+  .with_max_age(3600)
+  .build()
+| let sc: stallion.SetCookie val =>
+  // Add to response: .add_header("Set-Cookie", sc.header_value())
+| let err: stallion.SetCookieBuildError =>
+  // Handle validation error
+end
+```
+
+The builder validates cookie names (RFC 2616 token), values (RFC 6265 cookie-octets), and path/domain attributes (no CTLs or semicolons), enforces `__Host-` and `__Secure-` prefix rules, and checks `SameSite=None` + `Secure` consistency.
+
+New types: `Header`, `RequestCookie`, `RequestCookies`, `ParseCookies`, `SetCookie`, `SetCookieBuilder`, `SetCookieBuildError`, `SameSite` (`SameSiteStrict`, `SameSiteLax`, `SameSiteNone`).
+
+## Changed Headers.values() to yield Header val instead of tuples
+
+`Headers.values()` now yields `Header val` objects instead of `(String, String)` tuples. Code that destructures header values needs to change from field access on tuples to field access on the `Header` class:
+
+Before:
+
+```pony
+for (name, value) in headers.values() do
+  env.out.print(name + ": " + value)
+end
+```
+
+After:
+
+```pony
+for hdr in headers.values() do
+  env.out.print(hdr.name + ": " + hdr.value)
+end
+```

CHANGELOG.md

@@ -9,9 +9,12 @@ All notable changes to this project will be documented in this file. This projec
 
 ### Added
 
+- Add cookie parsing and serialization ([PR #80](https://github.com/ponylang/stallion/pull/80))
 
 ### Changed
 
+- Change Headers.values() to yield Header val instead of tuples ([PR #80](https://github.com/ponylang/stallion/pull/80))
+
 
 ## [0.4.0] - 2026-03-03
 

CLAUDE.md

@@ -55,15 +55,16 @@ Follow the standard ponylang release notes conventions. Create individual `.md`
   - `method.pony` — HTTP method types (`Method` interface, 9 primitives, `Methods` parse/enumerate)
   - `version.pony` — HTTP version types (`HTTP10`, `HTTP11`, `Version` closed union)
   - `status.pony` — HTTP status codes (`Status` interface, 35 standard primitives)
-  - `headers.pony` — Case-insensitive header collection (`Headers` class)
+  - `header.pony` — Single HTTP header name-value pair (`Header val` class)
+  - `headers.pony` — Case-insensitive header collection (`Headers` class, stores `Array[Header val]`)
   - `_response_serializer.pony` — Response wire-format serializer (package-private)
   - `_mort.pony` — Runtime enforcement primitives (`_IllegalState`, `_Unreachable`)
   - `parse_error.pony` — Parse error types (`ParseError` union, 8 error primitives)
   - `_parser_config.pony` — Parser size limit configuration
   - `_request_parser_notify.pony` — Parser callback trait (synchronous `ref` methods)
   - `_parser_state.pony` — Parser state machine (state interface, 6 state classes, `_BufferScan`)
   - `_request_parser.pony` — Request parser class (entry point, buffer management)
-  - `request.pony` — Immutable request metadata bundle (`Request val`: method, URI, version, headers)
+  - `request.pony` — Immutable request metadata bundle (`Request val`: method, URI, version, headers, cookies)
   - `chunk_send_token.pony` — Opaque chunk send token (`ChunkSendToken val`, `Equatable`, private constructor)
   - `http_server_lifecycle_event_receiver.pony` — HTTP callback trait (`HTTPServerLifecycleEventReceiver`: on_request, on_body_chunk, on_request_complete, on_chunk_sent, on_closed, on_throttled, on_unthrottled)
   - `http_server_actor.pony` — Server actor trait (`HTTPServerActor`: extends `TCPConnectionActor` and `HTTPServerLifecycleEventReceiver`, provides `_connection()` default)
@@ -79,10 +80,20 @@ Follow the standard ponylang release notes conventions. Create individual `.md`
   - `server_config.pony` — Server configuration (`ServerConfig` class with `max_requests_per_connection: (MaxRequestsPerConnection | None)`, `DefaultIdleTimeout` primitive)
   - `_error_response.pony` — Pre-built error response strings (`_ErrorResponse` primitive)
   - `_connection_state.pony` — Connection lifecycle states (`_Active`, `_Closed`; routes `on_sent` for chunk token delivery)
+  - `request_cookie.pony` — Single parsed cookie name-value pair (`RequestCookie val`, private constructor)
+  - `request_cookies.pony` — Immutable collection of parsed request cookies (`RequestCookies val`, `get()`, `values()`, `size()`)
+  - `parse_cookies.pony` — Cookie parser (`ParseCookies` primitive: `from_headers()`, `apply()`, lenient RFC 6265 §5.4 parsing)
+  - `same_site.pony` — SameSite attribute types (`SameSiteStrict`, `SameSiteLax`, `SameSiteNone`, `SameSite` union)
+  - `set_cookie_build_error.pony` — Build error types (`InvalidCookieName`, `InvalidCookieValue`, `InvalidCookiePath`, `InvalidCookieDomain`, `CookiePrefixViolation`, `SameSiteRequiresSecure`, `SetCookieBuildError` union)
+  - `set_cookie.pony` — Validated, pre-serialized `Set-Cookie` header (`SetCookie val`, `header_value()`, private constructor)
+  - `set_cookie_builder.pony` — `Set-Cookie` header builder (`SetCookieBuilder ref`, secure defaults, chaining, prefix rules)
+  - `_cookie_validator.pony` — Cookie name/value/attribute validation (RFC 2616 token, RFC 6265 cookie-octet, path/domain safety)
+  - `_http_date.pony` — IMF-fixdate formatter for `Expires` attribute (`_HTTPDate` primitive)
 - `assets/` — test assets
   - `cert.pem` — Self-signed test certificate for SSL examples
   - `key.pem` — Test private key for SSL examples
 - `examples/` — example programs
+  - `cookies/main.pony` — Visit counter demonstrating `Request.cookies` and `SetCookieBuilder`
   - `hello/main.pony` — Greeting server with URI parsing and query parameter extraction
   - `ssl/main.pony` — HTTPS server using SSL/TLS
   - `streaming/main.pony` — Flow-controlled chunked transfer encoding streaming response using `on_chunk_sent()` callbacks

examples/README.md

@@ -6,6 +6,10 @@ Each subdirectory is a self-contained Pony program demonstrating a different par
 
 Greeting server that responds with "Hello, World!" by default, or "Hello, {name}!" when a `?name=X` query parameter is provided. Demonstrates the core API: a listener actor implements `lori.TCPListenerActor`, creates connection actors in `_on_accept`, and each connection actor uses `HTTPServerActor`, `HTTPServer`, `Request`, `Responder`, `ResponseBuilder`, and `ServerConfig`. Start here if you're new to the library.
 
+## [cookies](cookies/)
+
+Visit counter that reads the `visits` cookie from incoming requests, increments it, and sets it back via `Set-Cookie`. Demonstrates both `Request.cookies` for reading cookies parsed from request headers and `SetCookieBuilder` for building validated `Set-Cookie` response headers with secure defaults.
+
 ## [ssl](ssl/)
 
 HTTPS server using SSL/TLS. Demonstrates creating an `SSLContext`, loading certificate and key files, and passing the context to connection actors via `_on_accept`. Actors use `HTTPServer.ssl` instead of `HTTPServer` to create an HTTPS connection.

examples/cookies/main.pony

@@ -0,0 +1,109 @@
+"""
+Visit counter using cookies. Reads the `visits` cookie from the request,
+increments it, and sets it back via `Set-Cookie`. Demonstrates both
+`Request.cookies` for reading and `SetCookieBuilder` for writing cookies.
+
+First visit returns "Visit #1", subsequent visits increment the counter.
+"""
+use stallion = "../../stallion"
+use lori = "lori"
+
+actor Main
+  new create(env: Env) =>
+    let auth = lori.TCPListenAuth(env.root)
+    Listener(auth, "0.0.0.0", "8080", env.out)
+
+actor Listener is lori.TCPListenerActor
+  var _tcp_listener: lori.TCPListener = lori.TCPListener.none()
+  let _out: OutStream
+  let _config: stallion.ServerConfig
+  let _server_auth: lori.TCPServerAuth
+
+  new create(
+    auth: lori.TCPListenAuth,
+    host: String,
+    port: String,
+    out: OutStream)
+  =>
+    _out = out
+    _server_auth = lori.TCPServerAuth(auth)
+    _config = stallion.ServerConfig(host, port)
+    _tcp_listener = lori.TCPListener(auth, host, port, this)
+
+  fun ref _listener(): lori.TCPListener => _tcp_listener
+
+  fun ref _on_accept(fd: U32): lori.TCPConnectionActor =>
+    CookieServer(_server_auth, fd, _config)
+
+  fun ref _on_listening() =>
+    try
+      (let host, let port) = _tcp_listener.local_address().name()?
+      _out.print("Server listening on " + host + ":" + port)
+    else
+      _out.print("Server listening")
+    end
+
+  fun ref _on_listen_failure() =>
+    _out.print("Failed to start server")
+
+  fun ref _on_closed() =>
+    _out.print("Server closed")
+
+actor CookieServer is stallion.HTTPServerActor
+  var _http: stallion.HTTPServer = stallion.HTTPServer.none()
+
+  new create(
+    auth: lori.TCPServerAuth,
+    fd: U32,
+    config: stallion.ServerConfig)
+  =>
+    _http = stallion.HTTPServer(auth, fd, this, config)
+
+  fun ref _http_connection(): stallion.HTTPServer => _http
+
+  fun ref on_request_complete(request': stallion.Request val,
+    responder: stallion.Responder)
+  =>
+    // Read the visits cookie, defaulting to "0"
+    var visits: U64 = 0
+    match request'.cookies.get("visits")
+    | let v: String val =>
+      try visits = v.u64()? end
+    end
+    visits = visits + 1
+
+    let resp_body: String val = "Visit #" + visits.string()
+
+    // Build a Set-Cookie header to store the updated count
+    let set_cookie = match stallion.SetCookieBuilder("visits",
+        visits.string())
+      .with_path("/")
+      .with_http_only(false)
+      .with_secure(false)
+      .with_same_site(stallion.SameSiteLax)
+      .build()
+    | let sc: stallion.SetCookie val => sc
+    | let err: stallion.SetCookieBuildError =>
+      // Cookie name/value are always valid here, so this is unreachable
+      _respond_error(responder)
+      return
+    end
+
+    let response = stallion.ResponseBuilder(stallion.StatusOK)
+      .add_header("Content-Type", "text/plain")
+      .add_header("Content-Length", resp_body.size().string())
+      .add_header("Set-Cookie", set_cookie.header_value())
+      .finish_headers()
+      .add_chunk(resp_body)
+      .build()
+    responder.respond(response)
+
+  fun _respond_error(responder: stallion.Responder ref) =>
+    let body: String val = "Internal Server Error"
+    let response = stallion.ResponseBuilder(
+        stallion.StatusInternalServerError)
+      .add_header("Content-Length", body.size().string())
+      .finish_headers()
+      .add_chunk(body)
+      .build()
+    responder.respond(response)

stallion/_cookie_validator.pony

@@ -0,0 +1,69 @@
+primitive _CookieValidator
+  """
+  Validate cookie names and values per RFC 6265 and RFC 2616.
+
+  Cookie names must be RFC 2616 tokens: ASCII 33–126 excluding
+  separators `( ) < > @ , ; : \\ " / [ ] ? = { }`.
+
+  Cookie values must be RFC 6265 cookie-octets: 0x21, 0x23–0x2B,
+  0x2D–0x3A, 0x3C–0x5B, 0x5D–0x7E.
+  """
+
+  fun valid_name(name: String box): Bool =>
+    """Return true if `name` is a valid cookie name (RFC 2616 token)."""
+    if name.size() == 0 then return false end
+    for byte in name.values() do
+      if not _is_token_char(byte) then return false end
+    end
+    true
+
+  fun valid_value(value: String box): Bool =>
+    """Return true if `value` contains only valid cookie-octets."""
+    for byte in value.values() do
+      if not _is_cookie_octet(byte) then return false end
+    end
+    true
+
+  fun _is_token_char(b: U8): Bool =>
+    """
+    RFC 2616 token character: ASCII 33–126 minus separators.
+
+    Separators: ( ) < > @ , ; : \\ " / [ ] ? = { }
+    """
+    if (b < 33) or (b > 126) then return false end
+    // Check separators
+    match b
+    | '(' | ')' | '<' | '>' | '@'
+    | ',' | ';' | ':' | '\\' | '"'
+    | '/' | '[' | ']' | '?' | '='
+    | '{' | '}' => false
+    else
+      true
+    end
+
+  fun _is_cookie_octet(b: U8): Bool =>
+    """
+    RFC 6265 cookie-octet: 0x21, 0x23–0x2B, 0x2D–0x3A, 0x3C–0x5B, 0x5D–0x7E.
+    """
+    if b == 0x21 then return true end
+    if (b >= 0x23) and (b <= 0x2B) then return true end
+    if (b >= 0x2D) and (b <= 0x3A) then return true end
+    if (b >= 0x3C) and (b <= 0x5B) then return true end
+    if (b >= 0x5D) and (b <= 0x7E) then return true end
+    false
+
+  fun valid_attr_value(value: String box): Bool =>
+    """
+    Return true if `value` is safe as a Set-Cookie attribute value.
+
+    RFC 6265 section 4.1.1 defines path-value as any US-ASCII character
+    (0x20–0x7E) except semicolons. Control characters (0x00–0x1F, 0x7F)
+    and non-ASCII bytes (0x80–0xFF) are rejected. The same constraint
+    prevents attribute injection in domain values.
+    """
+    for byte in value.values() do
+      if (byte < 0x20) or (byte > 0x7E) or (byte == ';') then
+        return false
+      end
+    end
+    true

stallion/_http_date.pony

@@ -0,0 +1,62 @@
+use "time"
+
+primitive _HTTPDate
+  """
+  Format epoch seconds as an IMF-fixdate string (RFC 7231 §7.1.1.1).
+
+  Example: `Thu, 01 Jan 1970 00:00:00 GMT`
+
+  Used by `SetCookieBuilder` for the `Expires` attribute.
+  """
+
+  fun apply(epoch_seconds: I64): String val =>
+    """Format epoch seconds as an IMF-fixdate string."""
+    let d = PosixDate(epoch_seconds)
+
+    // PosixDate.day_of_week uses C's tm_wday: 0=Sunday through 6=Saturday
+    let day_names = [as String val:
+      "Sun"; "Mon"; "Tue"; "Wed"; "Thu"; "Fri"; "Sat"]
+    let month_names = [as String val:
+      "Jan"; "Feb"; "Mar"; "Apr"; "May"; "Jun"
+      "Jul"; "Aug"; "Sep"; "Oct"; "Nov"; "Dec"]
+
+    let day_name = try
+      day_names(d.day_of_week.usize())?
+    else
+      _Unreachable()
+      "Thu"
+    end
+
+    let month_name = try
+      month_names((d.month - 1).usize())?
+    else
+      _Unreachable()
+      "Jan"
+    end
+
+    let buf = recover val
+      String(29)
+        .>append(day_name)
+        .>append(", ")
+        .>append(_pad2(d.day_of_month))
+        .>append(" ")
+        .>append(month_name)
+        .>append(" ")
+        .>append(d.year.string())
+        .>append(" ")
+        .>append(_pad2(d.hour))
+        .>append(":")
+        .>append(_pad2(d.min))
+        .>append(":")
+        .>append(_pad2(d.sec))
+        .>append(" GMT")
+    end
+    buf
+
+  fun _pad2(n: I32): String val =>
+    """Zero-pad an integer to two digits."""
+    if n < 10 then
+      "0" + n.string()
+    else
+      n.string()
+    end

stallion/_response_serializer.pony

@@ -31,10 +31,10 @@ primitive _ResponseSerializer
         .>append("\r\n")
 
       // Headers
-      for (name, value) in headers.values() do
-        buf.>append(name)
+      for hdr in headers.values() do
+        buf.>append(hdr.name)
           .>append(": ")
-          .>append(value)
+          .>append(hdr.value)
           .>append("\r\n")
       end