Hobby Plan - No Route Groups

[SeanTAllen]

Hobby Framework Implementation Plan

Design: #2

Context

Hobby is a new HTTP web framework for Pony with no implementation code yet — just scaffolding (empty hobby.pony, placeholder _test.pony, placeholder example). The design document (Discussion #2) establishes the framework's principles and identifies five open questions. This plan resolves those open questions and lays out the implementation.

Open Question Resolutions

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 plan, 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.

Design Decisions

Context is ref, not iso

Unlike Jennet which passed Context as iso (consumed and returned by each middleware), Hobby uses ref. The Context lives as a local variable in _Connection's behavior. Middleware and handlers receive it as ref.

Rationale: Stallion's Responder is class ref. Storing it in Context requires Context to be ref. More importantly, ref avoids the iso consumption problem — if middleware errors after consuming an iso Context, the Context is lost and after phases can't access it. With ref, the Context survives errors.

Chain execution model

Forward phase:
  For each middleware:
    Increment invoked counter BEFORE calling apply
    try: call middleware.before(ctx)
    else: if not handled, ctx.respond(500)
    If ctx.is_handled(), break

  If not handled:
    try: call handler.apply(ctx)
    If still not handled: ctx.respond(500)

After phase (ALWAYS runs):
  For i = invoked-1 down to 0:
    middleware(i).after(ctx)

Key invariant: after phases run for ALL middleware whose before was invoked — whether the chain completed normally, short-circuited via respond, or errored. The counter is incremented BEFORE calling before so that even a middleware that errors gets its after called.

Application iso builder pattern

class iso Application
  fun iso get(path: String, handler: Handler,
    middleware: (Array[Middleware val] val | None) = None): Application iso^
  fun iso serve(auth: TCPListenAuth, config: ServerConfig, out: OutStream)

Each route method is fun iso, consuming and returning the receiver for chaining:

Application
  .get("/", HelloHandler)
  .get("/greet/:name", GreetHandler)
  .serve(auth, ServerConfig("localhost", "8080"), env.out)

Or with variable reassignment:

var app = Application
app = app.get("/", HelloHandler)
app.serve(auth, config, env.out)

serve() consumes the Application permanently — routes are frozen.

Middleware parameter syntax

Middleware arrays must be val for storage in the immutable router:

.get("/private", PrivateHandler where middleware =
  recover val [as Middleware val: AuthMiddleware; LogMiddleware] end)

The recover val [...] end is standard Pony. No helper is provided in v1 — keep the API minimal.

404 handling

When the router returns no match, _Connection responds with 404 directly — no middleware chain runs. This is minimal and can be extended later (e.g., global middleware, custom 404 handler).

User imports

Users import hobby and stallion. Hobby provides the framework machinery (Application, Context, Handler, Middleware). Stallion provides HTTP vocabulary (Status codes, Method, Headers, ServerConfig). Both are available via corral (Stallion as a direct dependency of Hobby).

Users also need lori to create TCPListenAuth(env.root). An alternative would be having Application.serve() accept AmbientAuth and handle auth derivation internally. This would hide lori from users but is less explicit about the capability being granted. We go with explicit for v1:

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

Transitive dependencies

Hobby accesses request'.uri.path where uri is a URI val from the uri package. This type is already parsed and stored in Stallion's Request val — Hobby doesn't construct URIs, just reads fields. The uri package is a transitive dependency (via Stallion) and doesn't need to be declared as a direct dependency in Hobby's corral.json. Similarly, lori types are used for auth tokens but come transitively through Stallion.

Context data map type

The data map is Map[String, Any val]. Pony's Any is interface tag Any (in builtin). Any val is a capability override — it means "any type at val capability." This enables storing different domain types in the map and recovering them via match. The get signature is fun box get(key: String): Any val ? (partial — errors on missing key).

Trailing slashes

Normalize paths by stripping trailing slashes before lookup (except root /). /users/ and /users match the same route.

File Structure

hobby/
  hobby.pony              - Package docstring (modify existing)
  context.pony            - Context class
  handler.pony            - Handler interface
  middleware.pony          - Middleware interface
  application.pony        - Application class (public API)
  _connection.pony        - Internal connection actor
  _listener.pony          - Internal listener actor
  _router.pony            - Router + radix tree
  _route_match.pony       - Route match result type
  _route_definition.pony  - Route definition for building
  _chain_runner.pony      - Middleware chain execution
  _mort.pony              - _Unreachable primitive
  _test.pony              - Test runner (modify existing)
  _test_router.pony       - Router property-based tests
  _test_integration.pony  - Integration tests

Implementation Phases

This is a single PR — the framework is not functional until all pieces connect.

Phase 1: Dependencies and Foundation

Step 1.1: Add Stallion dependency to corral.json. Run corral fetch.

Step 1.2: Create _mort.pony — _Unreachable primitive following Stallion's pattern but with Hobby's issue URL (https://github.com/ponylang/hobby/issues).

Step 1.3: Create handler.pony — Handler interface (val, fun apply(ctx: Context ref) ?). Include docstring explaining the contract: handlers are val/shareable, call ctx.respond() to send a response, ? is for genuine errors only.

Step 1.4: Create middleware.pony — Middleware interface (val, fun before(ctx: Context ref) ?, fun after(ctx: Context ref) => None). Include docstring explaining the two-phase model: before for forward processing (short-circuit via ctx.respond()), after for post-processing (always runs, not partial).

Step 1.5: Create context.pony — Context class with request, params, body, data map, respond methods, is_handled. Capability split: mutation methods (respond, respond_with_headers, set) are fun ref; read-only methods (get, is_handled) are fun box. This matters because the typed accessor convention from the design document receives Context box.

Step 1.6: Create _chain_runner.pony — _ChainRunner primitive implementing the forward/after execution model. Note: dedicated unit tests for _ChainRunner would be ideal (the counter-before-before invariant, reverse-order after phases, error handling are all worth testing directly), but Context requires a Stallion Responder which can't be constructed outside the stallion package. The chain runner is tested through integration tests (Step 4.2) instead. If this becomes a pain point, we can add a test seam (e.g., a test-only Context constructor) later.

Phase 2: Radix Tree Router

Step 2.1: Create _route_match.pony — _RouteMatch val (handler, middleware, params).

Step 2.2: Create _route_definition.pony — _RouteDefinition (method, path, handler, middleware).

Step 2.3: Create _router.pony — radix tree implementation.

• _RouterBuilder ref: Mutable builder. add(method, path, handler, middleware), build(): _Router ref^.
• _Router val: Immutable lookup. One tree per HTTP method. lookup(method, path): (_RouteMatch | None).
• Radix tree nodes with prefix, static children, optional param child, optional wildcard leaf.
• Static children have priority over param child during lookup.
• Paths normalized: strip trailing slash, must start with /.

Phase 3: Application, Listener, and Connection

Step 3.1: Create application.pony — Application iso class. Embeds Array[_RouteDefinition] to accumulate route registrations. Route methods (get, post, put, delete, patch, head, options, generic route) push to this array. serve() iterates the array calling _RouterBuilder.add() for each, then calls _RouterBuilder.build() inside a recover val block to produce _Router val, then creates _Listener with the frozen router.

Step 3.2: Create _listener.pony — _Listener actor. Implements lori.TCPListenerActor. Receives TCPListenAuth from Server.serve(), creates TCPServerAuth from it (stored as a field), and passes TCPServerAuth to each _Connection in _on_accept. Passes the _Router val and ServerConfig to each _Connection. Passes max_concurrent_connections from ServerConfig through to lori.TCPListener's limit parameter (this is new — Stallion's examples don't do this passthrough, but the types align: both are (U32 | None)). Note: _on_accept is partial (?) per lori's trait, but _Connection construction is infallible, so the ? satisfies the trait without ever erroring.

Step 3.3: Create _connection.pony — _Connection actor. Implements stallion.HTTPServerActor. Fields: _http: HTTPServer (initialized via none() then set in constructor), _router: _Router val, _body: Array[U8] iso (for body accumulation), _has_body: Bool. Overrides on_body_chunk(data: Array[U8] val) to append data to _body and set _has_body = true. Overrides on_request_complete to: harvest accumulated body via destructive read (let body: Array[U8] val = (_body = recover iso Array[U8] end)), look up route via _router.lookup(), create Context, run _ChainRunner, respond with 404 directly if no route matches. Does NOT override on_request — the default no-op is correct for the buffered model.

Phase 4: Tests

Step 4.1: Create _test_router.pony — property-based tests using PonyCheck.

Generators (derived from validation rules):

• _GenPathSegment: Alphanumeric + -_ characters, length 1-20. No /, :, *.
• _GenStaticPath: Join 1-5 _GenPathSegments with / prefix. Produces paths like /foo/bar/baz.
• _GenParamName: Same charset as _GenPathSegment but shorter (1-10). For :name and *name segments.
• _GenMethod: One of [stallion.GET; stallion.POST; stallion.PUT; stallion.DELETE; stallion.PATCH; stallion.HEAD; stallion.OPTIONS].

Properties:

• Static route always matches after registration
• Unregistered path returns None
• Parameter extraction: :name segments captured correctly
• Wildcard capture: *name captures remainder
• Static priority over param: /users/new matches static before /users/:id
• Method isolation: GET route doesn't match POST
• Multiple params: /users/:id/posts/:post_id extracts both

Example-based tests:

• Root path /
• Multiple overlapping prefixes (/api/v1/users, /api/v2/users)
• Wildcard with empty remainder
• Trailing slash normalization

Step 4.2: Create _test_integration.pony — HTTP round-trip tests.

Tests:

• Basic GET returns 200 + body
• Unknown path returns 404
• Named params delivered to handler
• POST with body: handler receives body bytes
• Middleware sets context data, handler reads it
• Middleware short-circuits with 401, handler NOT invoked, after phase runs
• Handler error produces 500
• Multiple routes dispatch correctly

Use ifdef linux then "127.0.0.2" else "localhost" end for WSL2 compatibility. Different ports per test to avoid conflicts. Tag integration tests for --exclude=integration.

Step 4.3: Update _test.pony — add all test classes to the runner.

Test command: make test (unit tests + examples build). The Makefile already passes --exclude=integration --sequential to the test binary, so integration tests are excluded from the default run. Integration tests can be run directly via ./build/release/hobby --only=integration.

Phase 5: Examples and Documentation

Step 5.1: Update examples/basic/main.pony — hello world with routing (GET / and GET /greet/:name).

Step 5.2: Create examples/middleware/main.pony — logging middleware with after phase, auth middleware with typed context data and short-circuiting.

Step 5.3: Create examples/README.md.

Step 5.4: Update hobby/hobby.pony package docstring — purpose, minimal example, middleware pattern, typed data convention.

Step 5.5: Update CLAUDE.md — architecture, file layout, dependencies, testing approach.

Step 5.6: Post open question resolutions as a comment on Discussion #2, then remove DESIGN.md from the repo (it duplicates the Discussion content and would become stale).

Step 5.7: Create release notes (.release-notes/ file). Classification: added. Label: changelog - added.

Key References

• Stallion API: /home/sean/code/ponylang/stallion/stallion/ (HTTPServerActor, HTTPServer, Responder, ResponseBuilder, Request, ServerConfig, Status, Method, Headers)
• Stallion hello example: /home/sean/code/ponylang/stallion/examples/hello/main.pony (listener + connection actor pattern)
• Stallion body accumulation: /home/sean/code/ponylang/stallion/stallion/_test_server.pony (destructive read pattern for iso body)
• Stallion _mort pattern: /home/sean/code/ponylang/stallion/stallion/_mort.pony
• Lori listener: /home/sean/code/ponylang/lori/lori/tcp_listener_actor.pony (_on_accept signature)
• Lori auth chain: /home/sean/code/ponylang/lori/lori/auth.pony (TCPListenAuth -> TCPServerAuth)
• PonyCheck: /home/sean/code/ponylang/ponyc/packages/pony_check/

What's Deferred

• Route groups
• Streaming request bodies (opt-in)
• Streaming responses (escape hatch to Stallion's chunked encoding)
• Built-in middleware (logging, auth, CORS, etc.)
• Static file serving
• SSL/TLS passthrough
• Custom 404 handler
• HEAD auto-response for GET routes
• 405 Method Not Allowed (vs 404 for wrong method)

Verification

Build and run tests:

make clean && make           # build + unit tests + examples
make config=debug            # debug build

Manual verification:

./build/release/basic        # start basic example
curl http://localhost:8080/   # should get "Hello from Hobby!"
curl http://localhost:8080/greet/World  # should get "Hello, World!"

[SeanTAllen]

This has been implemented.