lori_http_server — Phased Implementation Plan

[SeanTAllen]

Context

We're building an HTTP/1.1 server library on top of lori (v0.8.1). Lori provides raw TCP I/O with a connection-actor model: data arrives as Array[U8] iso chunks via _on_received(), and we send via TCPConnection.send(data): (SendToken | SendError). Lori also provides backpressure notifications and SSL support.

The existing ponylang/http_server is built on the stdlib net package and has actor-interaction issues we want to avoid. We may borrow internal logic (e.g., parsing techniques) but will design the architecture fresh around lori's model.

This plan covers the phases of building the server. API details are deferred to each phase's design work — this is about what components we need, in what order, and how we verify each phase.

Cross-cutting: Trait-based state machines

State machines in this project should follow the pattern used in ponylang/postgres: states are classes implementing trait hierarchies. The trait hierarchy provides categorized default behaviors — traits for state categories (e.g., "not yet connected", "authenticated") supply default implementations that trap on invalid operations, so new states get correct behavior for their category without manually implementing every method. Each state class owns its per-state data (buffers, accumulators), which is automatically cleaned up when the state transitions out. This applies "make illegal states unrepresentable" to per-state data — a state that doesn't need a buffer doesn't have one — while invalid operations are enforced at runtime through the trait defaults.

The postgres pattern uses a wide interface (~40 methods) because the Postgres protocol has many message types. Our state machines will be narrower — the HTTP parser and connection lifecycle have fewer distinct operations — so the interface width should be adapted to each use case rather than copying postgres's scale.

This pattern applies in two places:

1. The parser (Phase 2) — states like "expecting request line" vs "reading fixed-length body" have different legal operations and own different accumulation data
2. The connection lifecycle (Phases 3-4) — states like "awaiting request" vs "handler processing" vs "sending response" determine what operations are valid (e.g., can't start reading a new request while sending a response)

---

Phase 1: HTTP Data Types and Response Serialization

What we build: The foundational value types that the rest of the library operates on. Plain classes and primitives — no actors, no lori dependency.

Components:

• HTTP method type (union of primitives: GET, POST, etc., plus a parse function)
• HTTP version type (HTTP10, HTTP11)
• HTTP status codes (primitives with numeric code and reason phrase)
• Headers collection (case-insensitive storage and retrieval)
• Response serializer (takes status + headers + optional body, produces Array[U8] val in HTTP wire format)

Testing:

• Property-based tests for method parsing: valid methods always parse correctly, invalid strings always fail, mixed generator tests the exact boundary
• Property-based tests for headers: case-insensitive retrieval, add vs set semantics, ordering
• Property-based tests for response serialization: generate random status/headers/body, serialize, verify wire format structure (status line, CRLF headers, blank line, body)
• Example-based tests for known-good serializations against expected byte sequences
• Run: make test

Why first: Everything downstream depends on these types. Testing them in isolation means the rest of the library operates on trusted data.

---

Phase 2: HTTP Request Parser

What we build: A plain class implementing an HTTP/1.1 request parser as a state machine. Data is fed in as chunks (matching what lori delivers), and parsed requests are delivered via a callback interface.

Components:

• Parser state machine using the trait-based state pattern (see cross-cutting section). States for: request line, headers, fixed-length body, chunked body (chunk header, chunk data, chunk trailer). Each state is a class that owns its accumulation data (e.g., the headers state owns the partial header buffer, the body state owns the accumulated body bytes). Traits provide default behaviors defining which parser operations are valid in each state
• Parse error types as a union of primitives (too large, invalid method, bad version, malformed headers, invalid content-length, invalid chunk, etc.)
• Parser callback interface — a ref trait with fun ref methods (not tag/be). This is a key difference from the existing http_server: since the parser runs inside the connection actor, callbacks can be synchronous ref calls, avoiding unnecessary actor messaging
• Configurable size limits (max request line, max headers, max chunk header, max body size) to prevent DoS

Testing:

• Property-based tests for request line parsing: generate valid (method, path, version) triples, serialize to wire format, parse, verify
• Property-based tests for header parsing: generate header lists, serialize, feed after valid request line, verify callback receives correct headers
• Property-based tests for body handling: generate requests with Content-Length and matching body, verify complete delivery; test chunked encoding with valid chunk structure
• Incremental delivery tests: feed a complete request one byte at a time to verify the parser handles arbitrary chunk boundaries (critical since TCP delivers arbitrary-sized chunks)
• Pipelining tests: feed two complete requests back-to-back in one buffer, verify both are parsed in order
• Error boundary tests: exceed configured limits, verify correct error types
• Example-based tests for known HTTP requests (RFC examples, real-world captures)
• Run: make test

Why second: Parsing depends on Phase 1 types. Parsing must exist before we can do anything useful with TCP data. Testing independently of networking gives us confidence without flaky network tests.

---

Phase 3: Lori Integration — Connection Actor and Minimal Server

What we build: The actor layer connecting lori's TCP primitives to the parser and delivering parsed requests to application code. This produces a minimal functional HTTP server.

Components:

• HTTP connection actor — implements TCPConnectionActor & ServerLifecycleEventReceiver. Owns a TCPConnection, a parser, and a handler. In _on_received, feeds data to the parser. Parser callbacks forward to the handler. Response sending uses TCPConnection.send(). The connection lifecycle uses the trait-based state pattern (see cross-cutting section) to track where the connection is in the request/response cycle — states like "awaiting request", "handler processing", "sending response" enforce what operations are valid at each point
• HTTP listener actor — implements TCPListenerActor. On _on_accept, creates a new connection actor. Holds a handler factory and passes it to each connection
• Handler interface — the application-facing trait. Handler methods are ref (run synchronously inside the connection actor). The handler receives parsed requests and has access to a response-sending capability
• Handler factory — a val interface for creating per-connection handlers

Key architectural decision — single-actor connection model:
Unlike the existing http_server (which uses two actors per connection with message-passing between them), our connection actor owns everything: TCP I/O, parsing, handler dispatch, and response sending. No unnecessary actor boundaries. If an application needs async processing, the handler can delegate to its own actors and respond later, but the simple synchronous path has zero extra actor hops.

Testing:

• Integration test with loopback: start listener on random port, connect with lori TCP client, send raw HTTP request bytes, verify HTTP response. Use 127.0.0.2 on Linux / localhost on macOS (WSL2 workaround)
• Minimal handler test: handler returns fixed "Hello, World!", verify correct HTTP/1.1 200 OK response
• Parse error test: send malformed data, verify 400 Bad Request response
• Update examples/basic/main.pony to be a working "Hello, World!" HTTP server
• Run: make test

Why third: Needs both data types and parser. This phase produces the minimum viable HTTP server — accepts connections, parses requests, dispatches to handler, sends responses.

---

Phase 4: Connection Management

What we build: Correct HTTP/1.1 connection semantics: persistent connections, backpressure propagation, error responses, and timeouts.

Components:

• Keep-alive — after request/response, keep connection open for next request (HTTP/1.1 default). Close on Connection: close, HTTP/1.0 without Connection: keep-alive, or server decision
• Backpressure integration — wire lori's _on_throttled()/_on_unthrottled() through to the handler so it knows when to stop generating response data. Use mute()/unmute() for read-side pressure when handler processing falls behind
• HTTP error responses — when parser encounters errors, send appropriate status (400, 413, 505) before closing. Pre-serialize common error responses as val byte arrays
• Connection timeouts — idle timeout to close connections that aren't sending requests
• Server configuration — a val config type with host, port, timeouts, max concurrent connections (maps to lori's TCPListener limit), parser size limits

Testing:

• Keep-alive test: send two requests on one connection without closing, verify both get responses. Then send Connection: close, verify connection closes after response
• Backpressure test: flood a connection, verify throttle/unthrottle propagation
• Error response tests: various malformed requests → correct HTTP error status codes
• Timeout test: short timeout config, connect, send nothing, verify connection closes
• Property-based: generate request sequences with varying Connection headers and HTTP versions, verify open/close behavior matches protocol spec
• Run: make test

Why fourth: The Phase 3 server works but handles only single requests per connection and ignores backpressure. This phase makes it correct for real HTTP/1.1 usage.

---

Phase 5: Pipelining and Streaming Responses

What we build: Full HTTP pipelining support and chunked/streaming response capability.

Components:

• Request ID tracking — monotonically increasing ID per connection, so responses can be matched to requests even if handlers complete out of order
• Pending response queue — when response for request N+1 arrives before request N's response, buffer it. Flush in order. This is the core pipelining mechanism
• Chunked response encoding — handler indicates chunked mode, sends body chunks, connection actor wraps in chunked transfer encoding before sending via lori
• Streaming response support — allow handlers to send response headers first, then body chunks incrementally, then signal completion. This enables large responses without buffering everything in memory

Testing:

• Pipelining correctness: send N requests rapidly, handler responds in reverse order (via delayed behaviors), verify client receives responses in request order
• Property-based pipelining: random request sequences with random handler response delays, verify response ordering invariant
• Pending response queue unit tests: test queue class directly with generated out-of-order insertions and in-order pops
• Chunked response test: handler responds with chunked encoding, verify client receives valid chunked transfer-encoded data
• Streaming response test: handler sends headers, then multiple body chunks, then finishes — verify correct wire format
• Update example to demonstrate keep-alive
• Run: make test

Why last: Pipelining adds significant complexity (response queue, request ID tracking) and most real-world clients rarely pipeline. A server with keep-alive (Phase 4) is useful without pipelining. Deferring this also lets us refine the handler API based on experience from earlier phases.

---

What's NOT in this plan

• SSL/TLS: Lori handles this transparently — just use ssl_server() instead of server(). Adding HTTPS is a configuration concern, not architectural. Follow-up work.
• URL parsing: The parser extracts the raw request-target string. Full RFC 3986 parsing can be a separate package.
• HTTP/2, WebSockets: Fundamentally different protocols requiring different framing. Future projects.
• Routing/middleware: Application-level concerns above the server library. The library provides the handler interface; routing builds on top.
• Release notes: This is a 0.0.0 project with no prior release. Release notes will be added starting with the first PR that ships user-facing functionality (Phase 1 onward), following the standard ponylang release notes process.

[SeanTAllen]

Phase 4 note: Server needs listen failure notification

Server doesn't override _on_listen_failure(), so if the port is already in use or permissions are wrong, the failure is silently swallowed. Applications have no way to know their server failed to start.

Phase 4 should add a mechanism for the application to be notified of listen failures (callback, promise, or similar).

[SeanTAllen]

this was done.

[SeanTAllen]

Note: send() return values are currently discarded

Both Responder.respond() and _Connection.parse_error() ignore the (SendToken | SendError) return from _tcp_connection.send(). This is fine for Phase 3 (close after every response), but will need handling when keep-alive is added — a send failure on a kept-alive connection should trigger connection close or error recovery rather than being silently ignored.

[SeanTAllen]

this was done.