What Needs to Happen in Pyrois

[SeanTAllen]

Pyrois is meant to be the web framework that ties the Pony web ecosystem together. Not another library — the thing you actually reach for when you want to build a web application. It sits on top of hobby (HTTP), livery (LiveView), mare (WebSocket), stallion (HTTP server), and the stdlib json package, and provides the integration and higher-level pieces that make them work as a coherent whole.

The good news is that the hardest parts are already done. Livery handles LiveView — the diff engine, the JS client, PubSub, forms, server-rendered first paint, stateful components. The stdlib json package handles serialization. What's left is the connective tissue and the things that don't make sense as standalone libraries.

Here's what needs to happen in pyrois, roughly in the order it should happen.

Prerequisite: livery 0.1.0

Pyrois depends on livery via corral, which means livery needs a released version to depend on. All the core phases are merged to main. Time to cut 0.1.0.

Session and Authentication

This is the critical path. Every real application needs authentication, and the session framework is the bridge between hobby's HTTP world and livery's WebSocket world. A user logs in over HTTP, gets a session cookie, then opens a LiveView connection — pyrois needs to make that handoff seamless.

The pieces, in build order:

Cookie parsing and serialization. Parse Cookie headers, build Set-Cookie headers with the right attributes (Path, Secure, HttpOnly, SameSite, expiry). The crypto primitives for signing cookies (HMAC-SHA256, Base64) already exist in ponyc — this is string parsing and formatting.

Session framework. Session ID generation, storage (in-memory actor to start, database-backed later), middleware that loads the session on every request and writes it back on response. The design work here is more interesting than the implementation — the primitives are all present.

LiveView session bridge. This is pyrois's core integration responsibility. Livery already exposes HTTP headers on WebSocket upgrade via mare.UpgradeRequest. Pyrois needs to embed a signed session token in the SSR page and validate it when the WebSocket connects. The plumbing is there; the convention and token handling are what's missing.

CSRF protection. Random token per session, embedded in forms, validated on state-changing requests. Needs to cover the WebSocket upgrade path too.

Password hashing. PBKDF2-SHA256 is in the stdlib and is fine to start with (Django uses it). Argon2 or bcrypt via FFI can come later if there's demand.

Auth middleware. Load-session, require-auth, redirect-if-authenticated — the standard patterns, built on hobby's existing middleware system.

JSON API Layer

Most real applications serve both LiveView UIs and JSON APIs (mobile clients, third-party integrations, webhooks). These are all small pieces that build on hobby and stdlib json.

JSON body parsing middleware. Read the request body, parse it as JSON, make it available to the handler. A thin middleware wrapping the stdlib json parser.

Content negotiation. Read Accept headers, match against supported types, 406 if nothing matches.

Error response conventions. A pattern for mapping handler return types to structured JSON error responses. More of a convention than a library.

Typed JSON serialization/deserialization. Manual encode/decode functions per type to start. Code generation can come later if the boilerplate gets painful.

Form body parsing. URL-encoded parsing for OAuth token endpoints and webhook receivers. Multipart for file uploads eventually, but that's more involved.

What Comes Later

Some things will probably end up in pyrois but the details depend on how the earlier phases play out.

Standalone PubSub. Livery has an internal PubSub that works for LiveView. A general-purpose version with wildcard topics, sender exclusion, and the fastlane optimization (serialize once, send to many connections) could live in pyrois or get extracted into its own library.

General-purpose channels. Multiplexed topic subscriptions over WebSocket, beyond LiveView's render-focused protocol. Chat, notifications, collaborative editing. The design question is how channels coexist with livery's LiveView protocol on the same connection.

Cluster communication. Multi-node PubSub, distributed sessions. This is the hardest remaining piece in the whole Pony web story — building something equivalent to distributed Erlang on top of lori and msgpack. Not a pyrois-specific problem, but pyrois will be the primary consumer.

Email delivery. Needed for magic-link auth, email confirmation, password reset. Either an SMTP client or (more likely to start) HTTP calls to a transactional email API like SendGrid or Postmark via courier.

Background

This plan comes out of the Phoenix gap analysis that mapped what Pony needs for Phoenix-equivalent capabilities. Livery closed the three largest gaps (diff engine, JS client, template integration). What remains is mostly small-to-medium library work that composes into a framework — and that's what pyrois is for.

[SeanTAllen]

Cookie parsing and serialization is moving to stallion. It's HTTP-level functionality: parsing Cookie request headers and building Set-Cookie response headers. That belongs in the HTTP server, not the framework. Any stallion user should be able to work with cookies without pulling in pyrois.

What stays in pyrois: signed cookies (HMAC-SHA256 sign/verify using ponylang/ssl). That's the application-level concern that needs crypto.

The design plan is posted as a research discussion on stallion, and there's a tracking issue there for the work.

[SeanTAllen]

PR for this: ponylang/stallion#80

[SeanTAllen]

Three more items moving to stallion for the same reason as cookies — they're HTTP-level functionality, not framework logic. No new dependencies for stallion in any case.

• Content negotiation — Accept header parsing and media type matching (RFC 7231). Tracking: Add content negotiation stallion#76
• URL-encoded form body parsing — application/x-www-form-urlencoded key-value parsing. Tracking: Add URL-encoded form body parsing stallion#77
• Multipart form data parsing — multipart/form-data MIME boundary parsing (RFC 7578). Tracking: Add multipart form data parsing stallion#78

What remains in pyrois from the JSON API Layer section: JSON body parsing middleware (thin wrapper over stdlib json + error handling + context storage), error response conventions, and typed JSON serialization/deserialization. Those are framework integration, not HTTP plumbing.

[SeanTAllen]

URL encoding is in ponylang/uri version 0.3.0

[SeanTAllen]

content-negotiation is in stallion 0.5.0

[SeanTAllen]

multipart form handling will be in ponylang/multipart_mime 0.1.0

[SeanTAllen]

Status update and build ordering for the remaining work

The prerequisites are all in place. livery 0.1.0 shipped March 14. stallion 0.5.1 has cookie parsing/serialization and content negotiation. uri 0.3.0 has URL-encoded form parsing. multipart_mime 0.1.0 handles multipart form data. Everything that moved out of pyrois into lower-level libraries is released and available.

Time to build the actual framework. Here's the proposed ordering for what's left.

Session and auth — the critical path

The original build order still holds, minus the pieces that already shipped in other libraries:

1. Signed cookies. HMAC-SHA256 sign/verify on top of stallion's cookie parsing, using ponylang/ssl for the crypto. This is the foundation everything else sits on and the first thing that adds a real dependency to pyrois.

2. Session framework. ID generation (crypto-random), in-memory storage actor, and middleware that loads the session on every request and writes it back on response. The middleware hooks into hobby's before/after system and stores the session in ctx so downstream handlers can access it. Database-backed storage is a future concern — in-memory actor gets things working.

3. LiveView session bridge. Embed a signed session token in the SSR page, validate it when the WebSocket connects. This is the core integration that justifies pyrois existing as a separate project. livery already exposes HTTP headers on WebSocket upgrade via mare.UpgradeRequest, so the plumbing is there. Pyrois adds the token convention and validation.

4. CSRF protection. Per-session random token, embedded in forms, validated on state-changing requests. Needs to coordinate with livery's form support for embedding tokens in LiveView forms, and needs to cover the WebSocket upgrade path. Comes after the LiveView bridge because the bridge defines the upgrade flow that CSRF has to integrate with.

5. Password hashing. PBKDF2-SHA256 from the stdlib. Technically standalone, but it makes the most sense to land once the session and CSRF pieces exist so there's an auth story to use it in.

6. Auth middleware. load-session, require-auth, redirect-if-authenticated. The standard patterns, built on hobby's middleware system. This is the capstone of the session/auth chain — it's where all the earlier pieces come together into something an application author actually touches.

JSON API layer — after the critical path

These are all independent of session/auth and could theoretically be interleaved, but session/auth is what unlocks "build a real app with pyrois." Ship that first.

7. JSON body parsing middleware. Thin middleware wrapping the stdlib json parser. Reads the request body, parses it, stores the result in hobby's context data map.

8. Error response conventions. A pattern for mapping handler return types to structured JSON error responses.

9. Typed JSON serialization/deserialization. Manual encode/decode per type to start. Code generation can come later if the boilerplate gets painful.

"What Comes Later" stays later

Standalone PubSub, general-purpose channels, cluster communication, and email delivery all depend on how the earlier pieces shake out. No point ordering those until sessions and the LiveView bridge are working and we can see what patterns emerge.

[SeanTAllen]

Revised scope — Discussion #10 supersedes the build ordering above

Discussion #10 moves sessions, signed cookies, and CSRF protection to hobby. Hobby 0.4.0's actor-per-request redesign closed the async handler, response buffering, and after-middleware header injection gaps that originally required pyrois to own its own request pipeline.

The build ordering from the previous comment no longer applies. Here's what stays in pyrois:

What moved to hobby:

• Signed cookies (Move signed cookies from pyrois to hobby hobby#44)
• Session framework (Implement server-side sessions hobby#45)
• CSRF protection

What stays in pyrois, in build order:

1. LiveView session bridge. Blocked on hobby implementing sessions. This is the core integration that justifies pyrois — embed a signed session token in the SSR page, validate it on WebSocket upgrade.

2. Password hashing. PBKDF2-SHA256 from the stdlib. Auth concern, not a session concern.

3. Auth middleware. load-session, require-auth, redirect-if-authenticated. Built on hobby's public session API.

4. JSON body parsing middleware. Thin middleware wrapping the stdlib json parser.

5. Error response conventions. Mapping handler return types to structured JSON error responses.

6. Typed JSON serialization/deserialization. Manual encode/decode per type to start.

Dependency change: pyrois will depend on hobby (not stallion directly). Hobby is the web framework layer; pyrois builds on it.

Prerequisite not in Discussion #10: livery 0.1.1 pins hobby at 0.2.1. Livery needs updating to hobby 0.4.0 before pyrois can depend on both hobby and livery for the LiveView bridge.

"What Comes Later" is unchanged. Standalone PubSub, general-purpose channels, cluster communication, email delivery.