Session Framework: Revised Scope

[SeanTAllen]

The previous session framework design was built on the premise that pyrois had to own its own request pipeline. Hobby couldn't do async work in handlers, couldn't buffer responses, and couldn't let after-middleware inject headers. All three of those were required for server-side sessions. So the plan was: pyrois builds directly on stallion, reimplements routing, middleware, context, and chain execution, and implements sessions on top of its own pipeline. Hobby becomes a peer project sharing stallion as a foundation, not a dependency.

Hobby 0.4.0 eliminates every gap that forced that fork.

What changed in Hobby

Hobby's actor-per-request redesign rewrote the handler model from the ground up. The three specific problems:

Async handlers. Hobby now spawns an actor per request. The handler factory creates a handler actor that can do arbitrary async work — query a database, call an external service, wait for callbacks — and respond when it's ready. The connection waits. This is just how Pony works, and the framework finally stopped fighting it.

Response buffering. Responses are held in a _BufferedResponse until after-middleware completes. ctx.respond() no longer sends bytes to the wire immediately. The connection controls when the response goes out.

After-middleware header injection. AfterContext exposes set_header() and add_header() on the buffered response. Session middleware can inject Set-Cookie after the handler runs. This was the specific thing that made sessions impossible in old Hobby.

Hobby's Discussion #41 goes further. It explicitly designs for async session loading at the connection level. The connection reads the session cookie, sends load to the session store, buffers incoming pipelined requests while waiting for the callback, and creates the handler actor only after the session arrives. From the handler's perspective, the session is just there.

Discussion #41 also states the conclusion directly: "Sessions belong in hobby. Sessions aren't a 'Phoenix-like framework' feature. They're a web framework feature."

What this means for pyrois

The session framework doesn't belong here. The entire request pipeline that Discussion #8 designed — Handler, Middleware, Context, Application, Router, ChainRunner, Connection, Listener — is Hobby's job. The session types — SessionData, SessionEditor, MemorySessionStore, SessionMiddleware, SessionConfig — also belong in Hobby.

The signed cookie code already in pyrois (cookie_signing_key.pony, signed_cookie.pony, signed_cookie_error.pony) needs to move to Hobby. Sessions need signed cookies, and sessions are a Hobby feature.

The design work in Discussion #8 isn't wasted. The session architecture is sound and transfers directly to Hobby's implementation: immutable SessionData val snapshots, mutable SessionEditor ref wrappers, MemorySessionStore actor with fire-and-forget saves using causal messaging, cookie security defaults (__Host- prefix, Secure, HttpOnly, SameSite=Lax), session fixation prevention via regenerate_id(). All of that was good work. It just goes in the wrong repo now.

Revised scope

The build plan described pyrois as the connective tissue that ties the Pony web ecosystem together. That hasn't changed. What's changed is where the boundary falls between Hobby and pyrois.

Hobby handles the web framework layer: routing, middleware, async handlers, response buffering, sessions, CSRF protection. Everything a server-side web application needs for request/response HTTP.

Pyrois handles the real-time layer and the integration between HTTP and WebSocket worlds:

• LiveView session bridge. A user logs in over HTTP, gets a session cookie, then opens a LiveView connection. Pyrois embeds a signed session token in the SSR page and validates it on WebSocket upgrade. This is pyrois's core integration job, and it depends on Hobby having sessions.
• WebSocket transport. Integration between mare's WebSocket handling and Hobby's HTTP pipeline. Upgrade negotiation, connection lifecycle.
• Auth middleware. Load-session, require-auth, redirect-if-authenticated — standard patterns built on Hobby's session and middleware system. These might live in Hobby or pyrois depending on how tightly they couple to the session implementation.
• JSON API layer. Body parsing, content negotiation, error response conventions. Small pieces that build on Hobby.

What needs to happen

1. Move signed cookies to Hobby. The code is already written and tested. It needs to move repos. This unblocks session implementation in Hobby.
2. Implement sessions in Hobby. Following the design from Discussion Session Framework Design v2 #8 (adapted to Hobby's new context types) and Discussion #41's architectural integration. Tracked on the Hobby side.
3. Update pyrois's build plan. Discussion #2 needs to reflect the revised scope. Several items it lists (cookie parsing, session framework, session middleware) are now Hobby work.
4. Pyrois starts on the LiveView session bridge once Hobby has sessions. This is the first thing pyrois builds that requires the session integration to exist.

Pyrois's corral.json will depend on Hobby rather than stallion directly. Hobby is the framework layer; pyrois builds on it.

[SeanTAllen]

Review

The core argument is sound. Hobby 0.4.0 closes all three gaps that forced the fork. Async handlers, response buffering, after-middleware header injection — all verified in the 0.4.0 source and PR #42. Sessions belonging in hobby follows universal precedent (Plug, Rack, Django middleware, Express). The dependency direction reversal is well-motivated and the revised scope boundary is clean.

That said, there are several things the discussion doesn't address that will matter during implementation.

Hobby gains an ssl dependency

Moving signed cookies means hobby needs ponylang/ssl (for ssl/crypto). Hobby currently depends only on stallion. This is probably fine — sessions are core enough to justify it — but it's a footprint increase for all hobby users, including those not using sessions. Worth stating explicitly so it's a deliberate choice, not a surprise.

_bytes() is package-private — pyrois can't use it

CookieSigningKey._bytes() is the only way to get the raw key material for HMAC computation. When both SignedCookie and CookieSigningKey move to hobby, that's fine — same package, access works. But the LiveView session bridge in pyrois will need to sign tokens. Pyrois code can't call _bytes() on a key that lives in hobby's package.

Three options: (1) hobby exposes a public signing API that pyrois calls, (2) pyrois has its own separate signing key, (3) CookieSigningKey gets a public method. This is an API design decision that affects the hobby/pyrois boundary and should be settled before implementation starts.

Livery depends on hobby 0.2.1, not 0.4.0

Livery 0.1.1's corral.json pins hobby at 0.2.1. The actor-per-request redesign in 0.4.0 is a major API change. If pyrois depends on hobby 0.4.0 and also needs livery (for the LiveView bridge), that's a version conflict. Livery needs to be updated to hobby 0.4.0 before pyrois can depend on both. This is a prerequisite that action item 4 implicitly requires but doesn't state.

LiveView bridge token security

The bridge embeds a signed session token in the SSR page and validates it on WebSocket upgrade. That token is a bearer credential sitting in the page body. The discussion should note at minimum:

• Token lifetime. Tokens need a short validity window. A page rendered an hour ago shouldn't produce a valid WebSocket upgrade.
• Replay protection. Whether tokens need to be single-use (nonce) or whether the short validity window is sufficient.
• WebSocket upgrade and CSRF. If hobby's middleware chain runs before upgrade, CSRF validation works naturally. If pyrois handles upgrade at a lower level (via stallion/mare), CSRF on the upgrade falls to pyrois. Which path it takes determines where the CSRF boundary sits.

These don't need to be solved here, but they should be flagged as design constraints for the bridge work.

Session store eviction is a security requirement

Hobby's Discussion #41 mentions eviction as part of the session store API design. Discussion #10 doesn't mention it at all. Without bounded storage, every cookieless request (bots, health checks, curl) creates a new session and the store grows without bound. That's a DoS vector. This should be called out as a security requirement that transfers with the session design, not as an optional feature.

Discussion #8 design details that need to transfer

The discussion correctly says the session architecture transfers. Some specifics worth explicitly noting so they don't get lost:

• regenerate_id() race condition under concurrent requests (Discussion Session Framework Design v2 #8 documents this)
• Streaming + session ID regeneration limitation (regenerate_id() is partial during streaming)
• CSPRNG failure = 500 policy (RandBytes failure propagation)
• The 52 tests from Discussion Session Framework Design v2 #8's design — the test strategy should transfer too

Items from Discussion #2 not accounted for

Discussion #2's build plan includes items that Discussion #10 doesn't mention or place:

• Password hashing. Listed in Discussion What Needs to Happen in Pyrois #2 comment 3 as step 5. Not mentioned in the revised scope at all. Does it go to hobby (session-adjacent) or stay in pyrois?
• Typed JSON serialization/deserialization. Listed as step 9. Not mentioned in the revised scope's JSON API layer section.
• Email delivery. Listed under "What Comes Later." Not mentioned.

These might be intentional omissions, but Discussion #10 is replacing the build plan, so anything not placed here falls through the cracks.

Discussion #2 comment 3 superseded without acknowledgment

Discussion #2's third comment (March 16) laid out a detailed 9-step build order. Discussion #10 fundamentally changes the first 6 steps of that plan. The discussion should note that it supersedes the comment 3 ordering, so readers of Discussion #2 know to look here.

Similarly, the project memory records "Pyrois is the framework — it does not have to use hobby." Discussion #10 reverses this by making pyrois depend on hobby. That principle was correct when it was recorded (Discussion #8 era). It's now outdated. Worth acknowledging the change explicitly so the reasoning is traceable.

No tracking on the Hobby side

Action item 2 says session implementation is "Tracked on the Hobby side" but hobby has no open issue or discussion for it. Action item 1 (signed cookie move) also has no tracking. The action items should include creating those tracking artifacts.

Auth middleware deferral is right

The hedge about auth middleware living in hobby or pyrois is the correct call. Per "design for changeability" — defer until sessions exist and the coupling is visible. The key question will be whether auth middleware needs only hobby's public session API (could live in either project) or package-private internals (must be hobby). That's unanswerable until hobby's session API is designed.

Action item 3 needs specifics

"Update pyrois's build plan" doesn't say how. Edit Discussion #2's body? Add a comment? Create a new discussion? Given how much has changed, a new discussion replacing #2 (with #2 updated to point to it) would be cleaner than trying to patch the existing one.

One thing to think about

Once signed cookies move out, pyrois has zero public API. It stays that way until the LiveView bridge lands, which is blocked on hobby implementing sessions. The JSON API layer items (body parsing, error conventions) don't depend on sessions and could proceed in parallel, keeping the project from going dormant. Might be worth calling that out as an option.