Hobby Design

[SeanTAllen]

Hobby is an HTTP web framework for Pony, inspired by Jennet and powered by Stallion.

Background

Jennet was a pioneering Pony web framework that established good patterns for route registration, radix tree routing, and middleware composition. Hobby builds on what Jennet established while evolving the design in areas where we see opportunities for improvement — particularly around control flow in middleware chains, type safety for inter-middleware communication, and leveraging Stallion's more capable HTTP server layer.

Stallion is a protocol-level HTTP/1.x server built on lori. Its "your actor IS the connection" architecture eliminates the hidden-actor and factory patterns of earlier Pony HTTP libraries, giving frameworks direct ref access inside the connection actor with synchronous callbacks.

Design Principles

Separate "handled" from "errored" in the middleware chain

Jennet used Pony's error mechanism for middleware short-circuiting (e.g., auth middleware rejecting a request with 401). This conflates normal control flow with actual errors, and has the side effect of skipping middleware after phases — which is exactly when you most want logging and cleanup to run.

Hobby distinguishes two cases:

• Handled: the middleware has responded to the request and the chain should stop. This is normal control flow (auth rejection, cache hit, rate limit). The after phases of all preceding middleware still run.
• Errored: something unexpected went wrong. This is Pony's error and indicates a genuine failure.

The concrete representation (return type, flag, etc.) is an implementation detail to be determined, but the principle is firm: normal control flow decisions must not use the error channel.

Context data uses typed wrappers with domain types

Middleware needs to communicate with handlers — for example, auth middleware tells the handler who the authenticated user is. The underlying storage is Map[String, Any val], but raw string keys and as casts are not the intended usage pattern.

Middleware authors provide:

1. Domain types that represent outcomes, not primitives. Auth middleware defines AuthenticatedUser and NotAuthenticated, not String.
2. Typed accessor functions that use match to extract values from the context, returning a union of the domain types. Wiring errors (missing key, wrong type) surface as error, clearly distinct from domain outcomes.

// Middleware author provides this alongside the middleware
primitive BasicAuthData
  fun result(ctx: Context box): (AuthenticatedUser | NotAuthenticated) ?
    let v = ctx.get("basic_auth")?  // missing key = wiring bug, error
    match v
    | let u: AuthenticatedUser => u
    | let n: NotAuthenticated => n
    else
      error  // wrong type stored = wiring bug
    end

This gives three clearly distinct outcomes:

• Authenticated: AuthenticatedUser returned
• Not authenticated: NotAuthenticated returned
• Wiring bug: loud error (key missing or wrong type in map)

This convention is established through documentation, examples, and the built-in middleware Hobby ships with. The Map[String, Any val] mechanism is pragmatic; the typed wrapper pattern makes it safe in practice.

Routing

Radix tree with standard parameter syntax

Hobby uses a radix tree router, following the approach established by httprouter and adopted by Jennet. Route matching is exact — each request matches at most one route.

Two kinds of dynamic segments:

• Named parameters (:name): match a single path segment. /users/:id matches /users/42 but not /users/42/posts.
• Wildcard parameters (*name): match everything from that point forward, must be the last segment. /files/*path matches /files/css/style.css.

Route groups (desired)

Expressing shared middleware once for a set of routes rather than attaching it to each route individually reduces the chance of accidentally leaving a route unprotected. For example, all routes under /api sharing auth middleware.

This is a desired feature, not a guaranteed one. The API design is tricky in Pony — it requires either a way to enter/exit a group context or a group that takes a collection of route definitions. We'll pursue this if we find an API that's genuinely less error-prone than per-route middleware, but won't force an awkward API just to have the feature.

Request and Response Handling

Buffered by default, streaming opt-in

For both request bodies and responses, the default is buffered:

• Request bodies: Hobby accumulates the full request body from Stallion's incremental on_body_chunk() callbacks before invoking the handler. Most handlers want the complete body and shouldn't need to think about chunked arrival. Routes that need to handle large uploads or streaming input can opt into receiving body data incrementally.

• Responses: Most handlers return a complete response (status, headers, body). For cases that need it — server-sent events, large file downloads — an escape hatch provides access to Stallion's chunked transfer encoding with flow-controlled streaming.

Open Questions

The following are implementation-level decisions deferred until design work begins:

• Handler signature: What does a handler look like? Likely val (shareable, stateless across connections), but the exact interface — return type, how it interacts with the handled/errored distinction — needs design work.
• Integration architecture: Hobby likely owns the connection actor (users never implement HTTPServerActor directly), but the exact boundary between Hobby's internal actor and user-visible types needs design work.
• Post-processing mechanism: The design commits to post-processing (like logging) running even when middleware short-circuits a request. The open question is the mechanism — Jennet-style after methods on the middleware interface, a separate type, or something else.
• Route group API: If pursued, what the Pony API looks like.
• Concrete handled-vs-errored representation: Return type, context flag, or other mechanism.

[SeanTAllen]

Open Question Resolutions

The initial implementation (PR #4) resolves the five open questions from the design document:

1. Handler Signature

interface val Handler
  fun apply(ctx: Context ref) ?

Handlers are val (shareable, stateless across connections). They receive ref access to Context because they execute synchronously inside the connection actor's behavior. Call ctx.respond() to send a response. The ? allows genuine errors to propagate — if the handler errors without responding, the framework sends 500.

2. Integration Architecture

Three internal layers, one public type:

• Application (class iso): Public API. Route registration via .> method chaining (get, post, etc.). serve() consumes the Application, builds an immutable router, and creates the listener.
• _Listener (actor): Implements lori.TCPListenerActor. Accepts TCP connections and spawns _Connection actors.
• _Connection (actor): Implements stallion.HTTPServerActor. Accumulates body chunks, runs route lookup, executes middleware chain + handler.

Users never implement HTTPServerActor or interact with Stallion's connection lifecycle directly.

3. Post-Processing Mechanism

Jennet-style after method on the Middleware interface with a default no-op:

interface val Middleware
  fun before(ctx: Context ref) ?
  fun after(ctx: Context ref) => None

after is NOT partial — middleware authors handle errors internally if needed. This guarantees after phases cannot fail, simplifying the chain runner.

4. Concrete Handled-vs-Errored Representation

Context has respond() which sends the response and sets _handled = true. The chain runner checks ctx.is_handled() after each middleware. No return value needed from middleware — the truth lives in one place (the Context).

5. Route Groups

Deferred. Not part of this implementation, as the design document states it should only be pursued if we find an API that's genuinely less error-prone than per-route middleware.

Additional Design Decisions

• Context is ref, not iso: Unlike Jennet which passed Context as iso, Hobby uses ref. The Context lives as a local variable in _Connection's behavior. With ref, the Context survives errors and after phases always have access.
• Chain execution: Forward phase runs before for each middleware (incrementing a counter BEFORE calling before so erroring middleware gets its after called), then runs the handler if not handled, then always runs after in reverse order for all invoked middleware.
• 404 handling: When the router returns no match, _Connection responds with 404 directly — no middleware chain runs.

[SeanTAllen]

Route groups design: #7