Server-Side Sessions Design — v3

[SeanTAllen]

Philosophy

The framework manages session identity — ID generation, cookie
signing/verification, the async load state machine, Set-Cookie injection.
The framework does NOT manage session data. What gets stored, in what shape,
is the user's domain. The store is a user-implemented trait.

---

Public Types

SessionStore (trait tag) — session_store.pony

trait tag SessionStore
  """
  User-implemented session data store.

  The framework calls `load` when a request arrives with a valid session
  cookie. The store looks up the session ID and calls the callback with the
  result: the stored data as `Any val`, or `None` if the session doesn't
  exist. `save` and `delete` are fire-and-forget.

  Implementations are actors. A trivial in-memory store is ~20 lines.
  Multiple stores can coexist — the framework only interacts with the one
  passed to `SessionConfig`.
  """
  be load(session_id: String val,
    callback: {((Any val | None))} val)
  be save(session_id: String val, data: Any val)
  be delete(session_id: String val)

The callback lambda is created by _Connection inside the hobby package,
so it can call _session_loaded (package-private) on the connection actor.
This keeps internal types hidden from store implementations.

SessionConfig (class val) — session_config.pony

use stallion = "stallion"

class val SessionConfig
  """
  Configuration for server-side sessions.

  Validates at construction time by building a test cookie with the exact
  same attributes that `_SessionCookieWriter` uses. Errors if the cookie
  name is invalid or violates prefix constraints.

  Security attributes are hardcoded: `Secure`, `HttpOnly`, `SameSite=Lax`.
  The default cookie name uses the `__Host-` prefix, which locks the cookie
  to the exact origin and requires HTTPS.
  """
  let _key: CookieSigningKey
  let _store: SessionStore tag
  let _cookie_name: String val
  let _max_age: (I64 | None)

  new val create(
    key': CookieSigningKey,
    store': SessionStore tag,
    cookie_name': String val = "__Host-_hobby_session",
    max_age': (I64 | None) = None) ?
  =>
    // COUPLING: Validate by building the exact same cookie that
    // _SessionCookieWriter builds. If either side changes attributes,
    // update the other.
    let builder = stallion.SetCookieBuilder(cookie_name', "test")
      .with_path("/")
      .with_secure(true)
      .with_http_only(true)
      .with_same_site(stallion.SameSiteLax)
    match max_age'
    | let ma: I64 => builder.with_max_age(ma)
    end
    match builder.build()
    | let _: stallion.SetCookieBuildError => error
    end
    _key = key'
    _store = store'
    _cookie_name = cookie_name'
    _max_age = max_age'

  fun _get_key(): CookieSigningKey => _key
  fun _get_store(): SessionStore tag => _store
  fun _get_cookie_name(): String val => _cookie_name
  fun _get_max_age(): (I64 | None) => _max_age

Application — add with_sessions

var _session_config: (SessionConfig val | None) = None

fun ref with_sessions(config: SessionConfig val) =>
  """
  Enable server-side sessions.

  When enabled, every routed request loads a session before the handler
  runs. The handler sees the loaded data via `session_data()` and controls
  the session lifecycle via `save_session()`, `delete_session()`, and
  `regenerate_session_id()` on `RequestHandler`.
  """
  _session_config = config

serve() passes _session_config to _Listener. _Listener threads it
to each _Connection.

RequestHandler — session lifecycle methods

New fields:

let _session_data: (Any val | None)
let _session_id: (String val | None)
var _session_save_data: (Any val | None) = None
var _session_regenerated: Bool = false
var _session_deleted: Bool = false

New constructor extraction (consume-first pattern):

new create(ctx: HandlerContext iso) =>
  let c: HandlerContext ref = consume ctx
  _request = c.request
  _params = c.params
  _body = c.body
  _data = c.data
  _conn = c._get_conn()
  _token = c._get_token()
  _is_head = c._get_is_head()
  _session_data = c._get_session_data()
  _session_id = c._get_session_id()

New methods:

fun box session_data(): (Any val | None) =>
  """
  The data loaded from the session store for this request.

  Returns `None` if sessions are not configured or the session is new
  (no data in the store). Cast to your application's session type.
  """
  _session_data

fun box session_id(): (String val | None) =>
  """
  The session ID for this request, or `None` if sessions are not configured.
  """
  _session_id

fun ref save_session(data: Any val) =>
  """
  Save data to the session store when the handler responds.

  The framework saves this data under the current session ID. For new
  sessions (no existing cookie), a Set-Cookie header is injected
  automatically. Call this with your application's session type — the
  framework stores it as `Any val` and passes it through to your store.

  If called multiple times, the last call wins. If `delete_session()` is
  also called, deletion takes priority regardless of call order.
  """
  _session_save_data = data

fun ref delete_session() =>
  """
  Delete the session from the store and clear the cookie.

  Takes effect when the handler responds. Takes priority over
  `save_session()` regardless of call order.
  """
  _session_deleted = true

fun ref regenerate_session_id() ? =>
  """
  Replace the session ID to prevent session fixation.

  Call after authentication state changes. Errors if streaming has started
  (the new cookie can't be sent after headers are on the wire).
  """
  if _streaming then error end
  _session_regenerated = true

Modified response methods — all include _build_session_outcome():

fun ref respond(status: stallion.Status, body': ByteSeq) =>
  if not _responded then
    _responded = true
    _conn._handler_respond(_token, status, None, body',
      _build_session_outcome())
  end

fun ref respond_with_headers(status: stallion.Status,
  headers: stallion.Headers val, body': ByteSeq)
=>
  if not _responded then
    _responded = true
    _conn._handler_respond(_token, status, headers, body',
      _build_session_outcome())
  end

fun ref start_streaming(status: stallion.Status,
  headers: (stallion.Headers val | None) = None)
  : (StreamingStarted | stallion.ChunkedNotSupported | BodyNotNeeded)
=>
  if _responded then return BodyNotNeeded end
  if _is_head then
    _responded = true
    _conn._handler_respond(_token, status, headers, "",
      _build_session_outcome())
    return BodyNotNeeded
  end
  if _request.version is stallion.HTTP10 then
    return stallion.ChunkedNotSupported
  end
  _responded = true
  _streaming = true
  _conn._handler_start_streaming(_token, status, headers,
    _build_session_outcome())
  StreamingStarted

fun ref finish() =>
  if _streaming then
    _streaming = false
    _conn._handler_finish(_token, _build_session_outcome())
  end

Session outcome builder:

fun ref _build_session_outcome(): (_SessionOutcome | None) =>
  """
  Build the session outcome and reset mutation flags.

  Flags are cleared after building so that a second call (streaming:
  `start_streaming()` then `finish()`) only captures changes made since
  the previous call. Since `regenerate_session_id()` errors during
  streaming, the `finish()` outcome will never be `_SessionSaveWithNewId`.

  `delete_session()` takes priority over `save_session()` regardless of
  call order.
  """
  let outcome: (_SessionOutcome | None) = match _session_id
  | let id: String val =>
    if _session_deleted then
      _SessionDeleted(id)
    elseif _session_regenerated then
      match _session_save_data
      | let data: Any val =>
        _SessionSaveWithNewId(data, id)
      else
        // Regenerated but no new data — preserve existing session data
        _SessionSaveWithNewId(_session_data, id)
      end
    else
      match _session_save_data
      | let data: Any val => _SessionSave(data)
      else
        _SessionUnchanged
      end
    end
  else
    None  // sessions not configured
  end
  // Clear flags so finish() only captures changes made during streaming
  _session_save_data = None
  _session_regenerated = false
  _session_deleted = false
  outcome

BeforeContext — read-only session access

let _session_data: (Any val | None)

fun box session_data(): (Any val | None) =>
  """
  The data loaded from the session store for this request.

  Returns `None` if sessions are not configured or the session is new.
  Cast to your application's session type. Read-only — modifications
  require `save_session()` on `RequestHandler`.
  """
  _session_data

HandlerContext — carry session data

let _session_data: (Any val | None)
let _session_id: (String val | None)

new iso _create(request': stallion.Request val,
  params': Map[String, String] val, body': Array[U8] val,
  data': Map[String, Any val] val, conn': _ConnectionProtocol tag,
  token': U64, is_head': Bool,
  session_data': (Any val | None) = None,
  session_id': (String val | None) = None)
=>
  // ... existing field init ...
  _session_data = session_data'
  _session_id = session_id'

fun _get_session_data(): (Any val | None) => _session_data
fun _get_session_id(): (String val | None) => _session_id

---

Internal Types

_SessionOutcome (union type) — _session_outcome.pony

4 variants. Each carries only the data it needs.

type _SessionOutcome is
  (_SessionUnchanged | _SessionSave | _SessionSaveWithNewId
   | _SessionDeleted)

primitive _SessionUnchanged
  """No save, no cookie change."""

class val _SessionSave
  """Save data under the current session ID."""
  let data: (Any val | None)
  new val create(data': (Any val | None)) => data = data'

class val _SessionSaveWithNewId
  """Save data under a new session ID. Delete the old one."""
  let data: (Any val | None)
  let old_id: String val
  new val create(data': (Any val | None), old_id': String val) =>
    data = data'
    old_id = old_id'

class val _SessionDeleted
  """Delete the session and clear the cookie."""
  let id: String val
  new val create(id': String val) => id = id'

_SessionId (primitive) — _session_id.pony

use crypto = "ssl/crypto"

primitive _SessionId
  """
  Generate cryptographically random session identifiers.

  32 bytes from CSPRNG, hex-encoded to 64 lowercase characters.
  256 bits of entropy.
  """
  fun generate(): String val ? =>
    let bytes: Array[U8] val = crypto.RandBytes(32)?
    let hex: String iso = recover iso String(64) end
    for b in bytes.values() do
      let hi = (b >> 4) and 0x0F
      let lo = b and 0x0F
      hex.push(if hi < 10 then hi + '0' else (hi - 10) + 'a' end)
      hex.push(if lo < 10 then lo + '0' else (lo - 10) + 'a' end)
    end
    consume hex

_CsprngFailure (primitive) — _csprng_failure.pony

primitive _CsprngFailure
  """CSPRNG failed to produce random bytes."""

_SessionCookieWriter (primitive) — _session_cookie_writer.pony

use stallion = "stallion"

primitive _SessionCookieWriter
  """
  Build Set-Cookie header values for session cookies.

  // COUPLING: Attributes here must match SessionConfig.create() validation.
  // If either side changes, update the other.
  """
  fun set_cookie(config: SessionConfig, session_id: String val)
    : String val
  =>
    let signed = SignedCookie.sign(config._get_key(), session_id)
    let builder = stallion.SetCookieBuilder(
        config._get_cookie_name(), signed)
      .with_path("/")
      .with_secure(true)
      .with_http_only(true)
      .with_same_site(stallion.SameSiteLax)
    match config._get_max_age()
    | let ma: I64 => builder.with_max_age(ma)
    end
    match builder.build()
    | let sc: stallion.SetCookie val => sc.header_value()
    | let _: stallion.SetCookieBuildError =>
      _Unreachable(); ""
    end

  fun clear_cookie(config: SessionConfig): String val =>
    match stallion.SetCookieBuilder(config._get_cookie_name(), "")
      .with_path("/")
      .with_secure(true)
      .with_http_only(true)
      .with_same_site(stallion.SameSiteLax)
      .with_max_age(0)
      .build()
    | let sc: stallion.SetCookie val => sc.header_value()
    | let _: stallion.SetCookieBuildError =>
      _Unreachable(); ""
    end

---

_ConnectionProtocol Changes

trait tag _ConnectionProtocol
  be _handler_respond(token: U64, status: stallion.Status,
    headers: (stallion.Headers val | None), body: ByteSeq,
    session_outcome: (_SessionOutcome | None) = None)
  be _handler_start_streaming(token: U64, status: stallion.Status,
    headers: (stallion.Headers val | None),
    session_outcome: (_SessionOutcome | None) = None)
  be _handler_send_chunk(token: U64, data: ByteSeq)
  be _handler_finish(token: U64,
    session_outcome: (_SessionOutcome | None) = None)

Default = None means existing callers (ServeFiles, _ServeFilesHandler,
test mocks) need zero changes.

---

_Connection Changes

New state and fields

primitive _LoadingSession

var _state: (_Idle | _LoadingSession | _HandlerInProgress | _Streaming)
  = _Idle

let _session_config: (SessionConfig val | None)

// Session data for the current request
var _session_id: (String val | None) = None
var _is_new_session: Bool = false

// Stashed request during async session load.
// Top-level type alias (same scope as _PendingRequest).
type _StashedRequest is
  (stallion.Request val, stallion.Responder, Array[U8] val,
   _RouteMatch, Bool)
  // (request, responder, body, match, is_head)

var _stashed: (_StashedRequest | None) = None

Actor declaration:

actor _Connection is (stallion.HTTPServerActor & _ConnectionProtocol)

No new traits — the store callback uses a lambda, not a trait on
_Connection.

Session loading timer

Only used for the _LoadingSession phase. Covers the async wait for the
store callback. When _session_loaded calls _dispatch, _dispatch bumps
_current_token again (making this timer's token stale), then starts its
own timer for the handler phase. This means the loading timer is
automatically invalidated when dispatch begins.

_dispatch keeps its existing inline token bump + timer start unchanged.
No _begin_request_lifecycle() extraction — that would start the timer
even for before-middleware short-circuits (a behavioral regression).

fun ref _start_loading_timer() =>
  """Start a timeout timer for the session loading phase."""
  _current_token = _current_token + 1
  _last_handler_activity = Time.nanos()
  if _timeout_ns > 0 then
    let timer = Timer(
      _HandlerTimeoutNotify(this, _current_token),
      _timeout_ns, _timeout_ns)
    let timer_tag: Timer tag = timer
    _handler_timer = timer_tag
    _timers(consume timer)
  end

Modified _process_request

fun ref _process_request(request': stallion.Request val,
  responder: stallion.Responder, body: Array[U8] val)
=>
  let path = request'.uri.path
  let is_head = request'.method is stallion.HEAD

  let route_match = match _router.lookup(request'.method, path)
  | let m: _RouteMatch => m
  else
    if is_head then
      _router.lookup(stallion.GET, path)
    end
  end

  match route_match
  | let m: _RouteMatch =>
    match _session_config
    | let config: SessionConfig val =>
      // Read session cookie
      let cookie_value = request'.cookies.get(config._get_cookie_name())

      match cookie_value
      | let raw: String val =>
        // Verify signature
        match SignedCookie.verify(config._get_key(), raw)
        | let session_id: String val =>
          // Valid cookie — load from store (async)
          _start_loading_timer()
          _stashed = (request', responder, body, m, is_head)
          _session_id = session_id
          _is_new_session = false
          _state = _LoadingSession
          let conn: _Connection tag = this
          config._get_store().load(session_id,
            {(data: (Any val | None))(conn) =>
              conn._session_loaded(data)
            } val)
        | let _: SignedCookieError =>
          // Invalid cookie — new session
          _start_new_session(request', responder, body, m, is_head,
            config)
        end
      else
        // No cookie — new session
        _start_new_session(request', responder, body, m, is_head, config)
      end
    else
      // No sessions configured — dispatch directly (timer starts in _dispatch)
      _dispatch(request', responder, body, m, is_head, None, None)
    end
  else
    // No route match — 404 (existing code, unchanged)
    if is_head then
      let response = stallion.ResponseBuilder(stallion.StatusNotFound)
        .add_header("Content-Length", "9")
        .finish_headers()
        .build()
      responder.respond(response)
    else
      let response = stallion.ResponseBuilder(stallion.StatusNotFound)
        .add_header("Content-Length", "9")
        .finish_headers()
        .add_chunk("Not Found")
        .build()
      responder.respond(response)
    end
  end

fun ref _start_new_session(request': stallion.Request val,
  responder: stallion.Responder, body: Array[U8] val,
  m: _RouteMatch, is_head: Bool, config: SessionConfig val)
=>
  """
  Generate a fresh session ID and dispatch. No store lookup needed.
  Timer starts in _dispatch on the not-handled path (existing behavior).
  """
  try
    let session_id = _SessionId.generate()?
    _session_id = session_id
    _is_new_session = true
    _dispatch(request', responder, body, m, is_head, None, session_id)
  else
    // CSPRNG failure — 500
    let response = stallion.ResponseBuilder(
        stallion.StatusInternalServerError)
      .add_header("Content-Length", "21")
      .finish_headers()
      .add_chunk("Internal Server Error")
      .build()
    responder.respond(response)
    // No timer was started (we never entered _LoadingSession)
  end

_session_loaded behavior

be _session_loaded(data: (Any val | None)) =>
  if _state isnt _LoadingSession then return end
  // Refresh so the handler gets its full timeout budget
  _last_handler_activity = Time.nanos()

  match _stashed
  | (let req: stallion.Request val, let resp: stallion.Responder,
     let body: Array[U8] val, let m: _RouteMatch, let is_head: Bool)
  =>
    _stashed = None
    _dispatch(req, resp, body, m, is_head, data, _session_id)
  else
    _Unreachable()
  end

Modified _dispatch

Gains two parameters for session data. No longer bumps token or starts
timer (that's in _begin_request_lifecycle).

fun ref _dispatch(request': stallion.Request val,
  responder: stallion.Responder, body: Array[U8] val,
  m: _RouteMatch, is_head: Bool,
  session_data: (Any val | None),
  session_id: (String val | None))
=>
  // Run before-middleware synchronously
  let before_ctx = BeforeContext._create(request', m.params, body,
    session_data)
  let invoked = _RunBeforeMiddleware(before_ctx, m.middleware)

  if before_ctx.is_handled() then
    // Before-middleware short-circuited — no session persistence
    let buf = // ... existing buffered response construction ...
    let after_ctx = AfterContext._create(buf, request')
    _RunAfterMiddleware(after_ctx, m.middleware, invoked)
    responder.respond(buf._build())
    _cancel_timer()
    _cleanup_session_state()
    _state = _Idle
    _drain_pending()
  else
    // Not handled — create HandlerContext and call factory
    // Token bump + timer start (existing code, unchanged)
    _current_token = _current_token + 1
    let token = _current_token
    _current_middleware = m.middleware
    _current_request = request'
    _current_responder = responder
    _before_invoked = invoked
    _is_head = is_head

    let data_val = before_ctx._freeze_data()
    let conn_tag: _ConnectionProtocol tag = this

    let handler_ctx: HandlerContext iso = recover iso
      HandlerContext._create(request', m.params, body, data_val,
        conn_tag, token, is_head, session_data, session_id)
    end

    let handler_receiver = m.factory(consume handler_ctx)
    _handler = handler_receiver
    _state = _HandlerInProgress
    _last_handler_activity = Time.nanos()

    // Start timeout timer (if timeouts enabled)
    if _timeout_ns > 0 then
      let timer = Timer(
        _HandlerTimeoutNotify(this, token), _timeout_ns, _timeout_ns)
      let timer_tag: Timer tag = timer
      _handler_timer = timer_tag
      _timers(consume timer)
    end
  end

session_data is (Any val | None) — sendable into the recover iso
block. session_id is (String val | None) — also sendable.

Session persistence

Called by _run_after_and_send AFTER after-middleware, BEFORE wire send.

fun ref _persist_session(buf: _BufferedResponse ref,
  outcome: (_SessionOutcome | None))
=>
  match (_session_config, outcome)
  | (let config: SessionConfig val, _SessionUnchanged) =>
    if _is_new_session then
      // New session but handler didn't save — no persistence, no cookie
      None
    end
  | (let config: SessionConfig val, let o: _SessionSave) =>
    match _session_id
    | let id: String val =>
      config._get_store().save(id, o.data)
      if _is_new_session then
        if not buf.is_streaming then
          buf.headers.push(("set-cookie",
            _SessionCookieWriter.set_cookie(config, id)))
        end
      end
    end
  | (let config: SessionConfig val, let o: _SessionSaveWithNewId) =>
    // Delete old session, generate new ID, save under new ID
    config._get_store().delete(o.old_id)
    try
      let new_id = _SessionId.generate()?
      config._get_store().save(new_id, o.data)
      if not buf.is_streaming then
        buf.headers.push(("set-cookie",
          _SessionCookieWriter.set_cookie(config, new_id)))
      end
    else
      // CSPRNG failure at this point means the OS entropy source is broken.
      // Continuing to serve with predictable session IDs is a security
      // hazard. Crash to prevent silent degradation.
      _Unreachable()
    end
  | (let config: SessionConfig val, let o: _SessionDeleted) =>
    config._get_store().delete(o.id)
    if not buf.is_streaming then
      buf.headers.push(("set-cookie",
        _SessionCookieWriter.clear_cookie(config)))
    end
  end
  _cleanup_session_state()

Wait — regenerate_session_id() on RequestHandler sets a flag, but the
new ID is generated here in _persist_session. This means the handler
doesn't know its new session ID. That's fine — the handler doesn't need it.
The framework generates the new ID at persistence time and sends the cookie.

Streaming + sessions

At _handler_start_streaming: cookie injection AND store persistence.
Since _build_session_outcome() clears handler-side flags after building,
the finish() outcome only reflects changes made DURING streaming (e.g.,
a save_session() call between start_streaming() and finish()).
regenerate_session_id() errors during streaming, so finish() will
never see _SessionSaveWithNewId.

be _handler_start_streaming(token: U64, status: stallion.Status,
  headers: (stallion.Headers val | None),
  session_outcome: (_SessionOutcome | None) = None)
=>
  if (_state isnt _HandlerInProgress) or (token != _current_token) then
    return
  end

  // Cookie injection + store persistence at streaming start
  let final_headers = match (_session_config, session_outcome)
  | (let config: SessionConfig val, let o: _SessionSave) =>
    match _session_id
    | let id: String val =>
      config._get_store().save(id, o.data)
      if _is_new_session then
        _inject_set_cookie(headers,
          _SessionCookieWriter.set_cookie(config, id))
      else
        headers
      end
    else
      headers
    end
  | (let config: SessionConfig val, let o: _SessionSaveWithNewId) =>
    config._get_store().delete(o.old_id)
    try
      let new_id = _SessionId.generate()?
      _session_id = new_id
      config._get_store().save(new_id, o.data)
      _inject_set_cookie(headers,
        _SessionCookieWriter.set_cookie(config, new_id))
    else
      _Unreachable()
      headers
    end
  | (let config: SessionConfig val, let o: _SessionDeleted) =>
    config._get_store().delete(o.id)
    _inject_set_cookie(headers,
      _SessionCookieWriter.clear_cookie(config))
  else
    headers  // _SessionUnchanged or no sessions
  end

  match _current_responder
  | let responder: stallion.Responder =>
    match \exhaustive\ responder.start_chunked_response(status,
      final_headers)
    | stallion.StreamingStarted =>
      _state = _Streaming
      _streaming_status = status
      _last_handler_activity = Time.nanos()
    | stallion.ChunkedNotSupported =>
      let buf = _BufferedResponse._standard(
        stallion.StatusInternalServerError, "Internal Server Error",
        _is_head)
      _run_after_and_send(buf)
    | stallion.AlreadyResponded => None
    end
  end

At _handler_finish: store persistence via _persist_session (cookie
injection is no-op since buf.is_streaming is true).

Modified _run_after_and_send

fun ref _run_after_and_send(buf: _BufferedResponse ref,
  session_outcome: (_SessionOutcome | None) = None)
=>
  match _current_request
  | let req: stallion.Request val =>
    let after_ctx = AfterContext._create(buf, req)
    _RunAfterMiddleware(after_ctx, _current_middleware, _before_invoked)
  end
  // Session persistence AFTER after-middleware, BEFORE wire send
  _persist_session(buf, session_outcome)
  if not buf.is_streaming then
    match _current_responder
    | let responder: stallion.Responder =>
      responder.respond(buf._build())
    end
  end
  _cancel_timer()
  _handler = None
  _current_middleware = None
  _current_request = None
  _current_responder = None
  _streaming_status = None
  _before_invoked = 0
  _is_head = false
  _state = _Idle
  _drain_pending()

fun ref _cleanup_session_state() =>
  _session_id = None
  _is_new_session = false
  _stashed = None

Updated _handler_respond and _handler_finish

be _handler_respond(token: U64, status: stallion.Status,
  headers: (stallion.Headers val | None), body': ByteSeq,
  session_outcome: (_SessionOutcome | None) = None)
=>
  if (_state isnt _HandlerInProgress) or (token != _current_token) then
    return
  end
  let buf = match headers
  | let h: stallion.Headers val =>
    _BufferedResponse._with_headers(status, h, body', _is_head)
  else
    _BufferedResponse._standard(status, body', _is_head)
  end
  _run_after_and_send(buf, session_outcome)

be _handler_finish(token: U64,
  session_outcome: (_SessionOutcome | None) = None)
=>
  if (_state isnt _Streaming) or (token != _current_token) then return end
  match _current_responder
  | let responder: stallion.Responder =>
    responder.finish_response()
  end
  let status = match _streaming_status
  | let s: stallion.Status => s
  else stallion.StatusOK
  end
  let buf = _BufferedResponse._streaming_complete(status, _is_head)
  _run_after_and_send(buf, session_outcome)

State machine edge cases

Updated _handler_timeout guard and new _LoadingSession arm:

be _handler_timeout(token: U64) =>
  if token != _current_token then return end
  if (_state isnt _HandlerInProgress) and (_state isnt _Streaming)
    and (_state isnt _LoadingSession) then
    return
  end
  let now = Time.nanos()
  if (now - _last_handler_activity) < _timeout_ns then return end

  match _state
  | _LoadingSession =>
    // Session store didn't respond in time.
    // Before-middleware hasn't run yet, so no after-middleware to run.
    match _stashed
    | (let _: stallion.Request val, let resp: stallion.Responder,
       let _: Array[U8] val, let _: _RouteMatch, let is_head: Bool)
    =>
      let buf = _BufferedResponse._standard(
        stallion.StatusGatewayTimeout, "Gateway Timeout", is_head)
      resp.respond(buf._build())
    end
    _cleanup_session_state()
    _cancel_timer()
    _state = _Idle
    _drain_pending()
  | _HandlerInProgress =>
    // ... existing code ...
  | _Streaming =>
    // ... existing code ...
  end

Updated on_closed:

fun ref on_closed() =>
  // ... existing cleanup ...
  _cleanup_session_state()

_inject_set_cookie helper

fun _inject_set_cookie(
  existing: (stallion.Headers val | None),
  cookie_header: String val)
  : stallion.Headers val
=>
  recover val
    let h = stallion.Headers
    match existing
    | let hdrs: stallion.Headers val =>
      for hdr in hdrs.values() do
        h.add(hdr.name, hdr.value)
      end
    end
    h.add("set-cookie", cookie_header)
    h
  end

---

Capability Flow

Store actor                  _Connection actor                    Handler actor
───────────                  ────────────────                     ─────────────
                             reads cookie, verifies signature
                             │
                             │  store.load(id, {(data) =>
                             │    conn._session_loaded(data)
                             │  } val)
                             │
Any val | None ◄─────────────┤  _session_loaded(data)
  (val: sendable)            │
                             ├─ recover iso {
                             │    HandlerContext._create(
                             │      ..., data, session_id)
                             │    // data is Any val — sendable
                             │    // session_id is String val — sendable
                             │  }
                             │  factory(consume HandlerContext iso)
                             │  ──────────────────────────────────►
                             │                                     consume ctx → ref
                             │                                     session_data() → Any val
                             │                                     save_session(data)
                             │                                     _build_session_outcome()
                             │  ◄─────────────────────────────────
                             │  _handler_respond(..., outcome val)
                             │
                             ├─ _persist_session(buf, outcome)
store.save(id, data) ◄──────┤    (fire-and-forget)
store.delete(old_id) ◄──────┤    (if regenerated/deleted)
                             │
                             ├─ inject Set-Cookie on buf.headers
                             └─ send to wire

All actor boundary crossings use val types. No ref data crosses
boundaries. No SessionEditor. No framework-prescribed data shape.

---

Security Properties

• Session ID: 256 bits CSPRNG, hex-encoded (64 chars)
• Cookie integrity: HMAC-SHA256 via existing SignedCookie
• Cookie transport: Secure, HttpOnly, SameSite=Lax, __Host-
  prefix — all hardcoded
• Session fixation: regenerate_session_id() rotates ID, deletes old
  from store. Streaming guard prevents rotation when cookie can't be sent.
• CSPRNG failure: Typed as _CsprngFailure, connection sends 500
• Store exhaustion: New sessions that don't call save_session() are
  never persisted — no cookie, no store entry
• Cookie size: Signed session ID is ~120 bytes total

---

File Layout

New files:

hobby/
  session_store.pony               - SessionStore trait (public)
  session_config.pony              - SessionConfig class (public)
  _session_id.pony                 - Session ID generation (internal)
  _session_outcome.pony            - _SessionOutcome union (internal)
  _session_cookie_writer.pony      - Cookie header builder (internal)
  _csprng_failure.pony             - _CsprngFailure primitive (internal)
  _test_session_id.pony            - Session ID tests
  _test_session_config.pony        - SessionConfig validation tests
  _test_session_cookie_writer.pony - Cookie writer tests
  _test_session_integration.pony   - Session round-trip integration tests
examples/
  sessions/
    main.pony                      - Session example with in-memory store

Modified files:

hobby/
  application.pony               - with_sessions()
  handler_context.pony           - session_data, session_id fields
  request_handler.pony           - session lifecycle methods
  before_context.pony            - session_data() read-only access
  _connection_protocol.pony      - session_outcome default params
  _connection.pony               - _LoadingSession, session loading, persistence
  _listener.pony                 - thread session_config
  hobby.pony                     - package docstring update
  _test.pony                     - register new test lists
  _test_request_handler.pony     - update mock for new protocol params
  _test_serve_files.pony         - update mock for new protocol params
examples/
  README.md                      - add sessions example
CLAUDE.md                        - architecture, file layout, API updates

---

Build Order

Phase 1: Pure types (independently testable):

1. _SessionId + tests
2. SessionStore trait (no tests — it's a trait)
3. _SessionOutcome + _CsprngFailure (no tests — primitives/classes)
4. SessionConfig + tests (validation)
5. _SessionCookieWriter + tests

Phase 2: Integration (modifies existing code):
6. _ConnectionProtocol (add session_outcome default params)
7. HandlerContext (add session fields)
8. RequestHandler (consume-first constructor, session methods)
9. BeforeContext (session_data read access)
10. _Connection + _LoadingSession (state machine, loading, persistence)
11. _Listener (thread config)
12. Application (with_sessions)
13. Update test mocks for new protocol params
14. Session integration tests

Phase 3: Polish:
15. Example program
16. Package docstring, examples README
17. CLAUDE.md updates

Build/test: make test ssl=3.0.x, make test-one t=TestName ssl=3.0.x

Counterfactual testing: after each new test passes, temporarily break each
assertion to confirm it fires.

---

Example Program

use hobby = "hobby"
use stallion = "stallion"
use lori = "lori"
use "collections"

// Application-defined session type
class val MySession
  let user_id: String val
  let login_time: String val

  new val create(user_id': String val, login_time': String val) =>
    user_id = user_id'
    login_time = login_time'

// Application-defined store
actor MyStore is hobby.SessionStore
  embed _sessions: Map[String, Any val]

  new create() =>
    _sessions = Map[String, Any val]

  be load(session_id: String val,
    callback: {((Any val | None))} val)
  =>
    try callback(_sessions(session_id)?)
    else callback(None)
    end

  be save(session_id: String val, data: Any val) =>
    _sessions(session_id) = data

  be delete(session_id: String val) =>
    try _sessions.remove(session_id)? end

actor Main
  new create(env: Env) =>
    let auth = lori.TCPListenAuth(env.root)
    let key = try hobby.CookieSigningKey.generate()?
    else env.err.print("Key generation failed"); return end
    let store = MyStore
    let config = try hobby.SessionConfig(key, store)?
    else env.err.print("Invalid session config"); return end

    hobby.Application
      .>with_sessions(config)
      .>get("/", {(ctx) =>
        let handler = hobby.RequestHandler(consume ctx)
        match handler.session_data()
        | let s: MySession =>
          handler.respond(stallion.StatusOK,
            "Hello " + s.user_id + "!")
        else
          handler.respond(stallion.StatusOK, "Not logged in")
        end
      } val)
      .>post("/login", {(ctx) =>
        let handler = hobby.RequestHandler(consume ctx)
        try
          handler.regenerate_session_id()?
          handler.save_session(
            MySession("alice", "2026-03-25T12:00:00Z"))
          handler.respond(stallion.StatusOK, "Logged in")
        else
          handler.respond(stallion.StatusInternalServerError,
            "Session error")
        end
      } val)
      .>post("/logout", {(ctx) =>
        let handler = hobby.RequestHandler(consume ctx)
        handler.delete_session()
        handler.respond(stallion.StatusOK, "Logged out")
      } val)
      .serve(auth, stallion.ServerConfig(
        ifdef linux then "127.0.0.2" else "localhost" end,
        "8080"), env.out)

---

Verify Empirically

1. Default parameter values on _ConnectionProtocol trait behaviors
2. session_data: (Any val | None) passing into recover iso block for
   HandlerContext construction
3. Lambda capture of _Connection tag in store load callback
4. _inject_set_cookie recover block with Headers iteration

---

Known Limitations

• No built-in store — user brings their own actor
• No key rotation — manual for v1
• No sliding cookie expiry
• regenerate_session_id() errors during streaming
• Server restart loses sessions (inherent to in-memory stores)
• __Host- prefix requires HTTPS; use a non-prefixed cookie name for
  local HTTP dev

[SeanTAllen]

Design decisions from further discussion

The v3 design above is already partially outdated. Working through the session design surfaced deeper questions about middleware and context that change the architecture. Documenting the decisions here.

No SessionStore trait in the framework

Session data storage is entirely an application concern. The framework doesn't know what session data looks like, doesn't store it, doesn't load it. The handler actor talks to its own typed store directly — fully type-safe, no Any val, no runtime casting.

The framework's session responsibility is cookie identity management only: verify the signed cookie on the way in (extract session ID), inject Set-Cookie on the way out (new session, rotated ID, cleared session).

Middleware becomes in-filter / out-filter

The current Middleware interface with BeforeContext and AfterContext is over-designed for what it actually does in an actor-per-request framework.

Before-middleware can't do async work. It can't query a database, validate tokens against an external service, or load session data. All of that requires actor messages, which means it belongs in the handler. What before-middleware CAN do is cheap synchronous rejection — is the header present? Is the content-type valid? Is the request too large? That's a request filter: request in, pass or reject out.

After-middleware modifies the outgoing response — add CORS headers, security headers, cache-control. It operates on the response status and headers (and the original request for things like reading the Origin header for CORS). That's a response filter: response in, modified response out.

Neither needs a context object with a data map.

BeforeContext data map goes away

The Map[String, Any val] pattern for passing data from middleware to handlers is type-unsafe ("this isn't Ruby") and solves a problem that mostly doesn't exist. The one example (AuthMiddleware storing AuthenticatedUser) doesn't actually work for real auth — verifying credentials requires async work that before-middleware can't do. The handler loads what it needs from its own typed stores.

Auth/Admin middleware move to handler composition

AuthMiddleware and AdminMiddleware as they exist today can only check if a header is present — they can't verify the user is actually authorized. Real auth moves to the handler actor, which can do async lookups.

The "apply auth to all these routes" problem is solved by handler factory composition, not middleware. A factory wrapper like WithAuth captures an auth service and wraps any handler — the handler actor runs the auth check first, then delegates to business logic. Route groups can capture shared factory wrappers.

// Instead of middleware:
// .>get("/dashboard", handler where middleware = auth_mw)

// Factory composition:
// .>get("/dashboard", WithAuth(auth_service, dashboard_handler))

The wrapped handler actor does the async auth work, rejects with 401 if needed, or proceeds with the verified user — fully typed, no Any val.

What remains

• In-filter (before): synchronous request filter. Sees the request, passes or rejects. No context, no data map. Used for cheap rejection (missing headers, blocked IPs, content-type checks).
• Out-filter (after): synchronous response filter. Sees the response status/headers and the original request. Can modify response headers. Used for CORS, security headers, cache-control.
• Handler actor: where real work happens. Async, typed, composes via factory wrappers. Auth, session loading, database queries — all here.
• Session cookie management: framework verifies signed cookies on the way in, injects Set-Cookie on the way out. Session ID is a typed field on the handler context, not a string-keyed map entry.

[SeanTAllen]

Handler composition replaces before-middleware

The handler actor is the composition unit. Instead of middleware injecting data through a type-unsafe context map, the handler embeds its dependencies and calls them directly with full type safety.

actor MyDashboardHandler is hobby.HandlerReceiver
  embed _handler: hobby.RequestHandler

  new create(ctx: hobby.HandlerContext iso,
    auth: AuthService tag, db: Database tag)
  =>
    _handler = hobby.RequestHandler(consume ctx)
    auth.verify(_handler.request().headers.get("authorization"), this)

  be auth_verified(user: User val) =>
    db.query(user.id, this)

  be auth_failed() =>
    _handler.respond(stallion.StatusUnauthorized, "Unauthorized")

  be query_result(data: String val) =>
    _handler.respond(stallion.StatusOK, data)

The handler factory captures whatever services the handler needs:

.>get("/dashboard", {(ctx)(auth, db) =>
  MyDashboardHandler(consume ctx, auth, db)
} val)

The trade-off is boilerplate for power. With middleware, the framework dictates the protocol — before(ctx) and after(ctx). With handler composition, the user defines the protocol. The auth service returns a typed User val, not Any val from a string-keyed map. The handler decides what auth failure looks like — a redirect, a JSON error, a retry. That's application logic, not boilerplate.

A wrapper actor that does auth and then delegates to a business-logic handler is possible but doesn't really save complexity — it's just an extra actor hop. The auth actor needs the HandlerContext iso to pass along, making it basically a handler itself.

What remains as framework concerns:

• In-filters: cheap synchronous request rejection (missing headers, blocked IPs) — saves handler actor creation
• Out-filters: synchronous response header modification (CORS, security headers)
• Session cookie identity management: verify signed cookie in, inject Set-Cookie out

[SeanTAllen]

Response headers and cookies

Handlers need to set headers incrementally, not all-or-nothing. Currently respond() gives no header control and respond_with_headers() requires building a complete Headers val upfront. The handler should be able to set headers one at a time before responding:

handler.set_header("X-Request-Id", request_id)
handler.add_header("Set-Cookie", cookie.header_value())
handler.respond(status, body)

With this, cookies aren't a special case. The handler builds cookies with Stallion's SetCookieBuilder (which already has secure defaults, validation, and chaining), gets the header value string, and adds it like any other header. No framework cookie helper needed.

This also means session cookie management doesn't require framework plumbing for the response side — the handler sets the Set-Cookie header directly. Combined with the earlier decision that session data storage is the handler's responsibility, the framework's session role shrinks to: verifying signed cookies on the request (synchronous crypto) and providing session ID generation.

[SeanTAllen]

Middleware classification for in-filter / out-filter / handler composition

Went through every middleware implementation in the codebase (examples + tests) and classified them against the design from the comments above.

Becomes in-filter (synchronous request rejection)

Middleware	Location	Reason
AuthMiddleware	examples/route-groups	Checks for Authorization header, rejects 401. Pure presence check.
_ShortCircuitMiddleware	tests	Rejects with 401.
_RespondWithHeadersMiddleware	tests	Rejects with 403 + custom headers.
_ErrorMiddleware	tests	Before-phase error without responding.

Becomes out-filter (synchronous response header modification)

Middleware	Location	Reason
LogMiddleware	examples/middleware, examples/route-groups	Reads request method+path after handling. Side-effect only (logging), no header mutation.
_AddHeaderMiddleware	tests	Adds X-Custom header to response.
_AddMultiHeaderMiddleware	tests	Adds multiple Set-Cookie headers.
_StreamingAfterHeaderMiddleware	tests	Sets header on streaming response (no-op).

Becomes handler composition

Middleware	Location	Reason
AuthMiddleware	examples/middleware	Stores AuthenticatedUser in data map via ctx.set(). Real auth needs async token verification → handler actor.
AdminMiddleware	examples/route-groups	Placeholder today, but real admin checks need async work.

Goes away (tests the data map, which is being removed)

Middleware	Location	Reason
_SetDataMiddleware	tests	Exists solely to test ctx.set() / ctx.get() on the data map.

Test infrastructure (adapts to whatever replaces Middleware)

Middleware	Location	Reason
_NoOpMiddleware	tests	No-op, used for route group structure tests.
_MarkerMiddleware	tests	Label carrier for middleware ordering tests.

Note

The private middlewares (_ShortCircuitMiddleware, _ErrorMiddleware, etc.) are test doubles in the integration tests. Each exercises a specific middleware behavior path in _Connection. They'll need to be rewritten to exercise the in-filter/out-filter interfaces, but the behaviors they test are still valid — except _SetDataMiddleware, which tests a feature being removed.

LogMiddleware is an out-filter that doesn't modify headers — it's a read-only side effect. Worth considering whether the out-filter interface needs to support that, or whether logging belongs somewhere else (e.g., connection/listener level).