Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Lighting Feature Parity & Roadmap

This document provides a gap analysis comparing Lighting against Go’s standard net/http library and outlines the roadmap for future development.

1. Current State vs. Go net/http

Lighting provides a solid foundation for HTTP/1.1 services:

  • Go 1.22+ Pattern Routing: Method constraints, zero-copy path parameters ({id}), wildcards ({filepath...}), exact match (/{$}), and automatic 405 Method Not Allowed.
  • Structured Concurrency: Native std.Io.Group.concurrent task dispatching (paralleling Go’s go c.serve()) with user-space Fiber execution.
  • Zero-Copy Protocol Parser: In-place header and path extraction directly from the socket buffer.
  • Dual-Mode ResponseWriter: Automatic Content-Length buffering (< 4KB) and streaming chunked transfer encoding for larger bodies.
  • Production Hardening: Slowloris defense via monotonic header deadlines, Keep-Alive connection reuse, RFC 9112 request smuggling prevention, and connection-scoped Arena reuse with high-water mark protection (request_arena_retain_limit).

2. Feature Parity Matrix

The following table summarizes the status of Lighting’s phased features:

CapabilityGo net/httpLighting CurrentImpact / Notes
http.Flusherw.(http.Flusher).Flush()✅ ResponseWriter.flush()Immediate output in Server-Sent Events (SSE) and LLM token streaming.
http.Hijackerw.(http.Hijacker).Hijack()✅ ResponseWriter.hijack()Raw TCP socket handoff for protocol upgrades.
WebSocketgolang.org/x/net/websocket✅ lighting.extra.wsFull RFC 6455 handshake, frame parsing, XOR unmasking, Ping/Pong, and echo.
Static File Serverhttp.FileServer(http.Dir)✅ lighting.extra.fs.FileServerRFC 7233 Range requests (audio/video seek), ETag / If-Modified-Since (304), MIME detection, and responsive directory browser.
Query Parametersreq.URL.Query() multi-value map✅ req.url.query() / queryParam()Multi-value parsed query map (QueryParams), single-key zero-copy lookup, and key existence checks.
Cookiesreq.Cookie(), http.SetCookie()✅ lighting.Cookie, req.cookie(), w.setCookie()RFC 6265 typed cookie parser, iterator, and Set-Cookie builder supporting SameSite, HttpOnly, Secure, Expires, and Max-Age.
Multipart Formreq.ParseMultipartForm()✅ lighting.MultipartForm, req.multipartForm()Streaming parser for RFC 7578 multipart/form-data with disk spilling for file uploads exceeding memory thresholds.
Reverse Proxyhttputil.ReverseProxy✅ lighting.extra.proxy.ReverseProxyReverse proxy forwarding requests, stripping RFC 9110 hop-by-hop headers, injecting X-Forwarded-*, and streaming bodies.
Route Timeoutshttp.TimeoutHandler✅ lighting.timeoutHandler()Route-level timeout middleware canceling handler execution and returning 504 Gateway Timeout on overrun.
HTTP Clienthttp.Client, Transport pool✅ lighting.ClientHigh-level HTTP client with get, post, postForm, do, CookieJar, ConnPool, and redirect following.
Panic Recoverydefer recover() per connection⚠️ Errors caught, @panic fatalHandler panics crash the task/process instead of returning HTTP 500; anyerror gracefully handled as 500.
TLS / HTTPSListenAndServeTLS❌ Not implementedRequires an external reverse proxy (e.g. Nginx, Caddy) for SSL termination.
HTTP/2 SupportBuilt-in via ALPN negotiation❌ HTTP/1.1 onlyNo multiplexing over a single TCP connection.

3. Phased Roadmap

Phase 1: Real-Time & Streaming Primitives (Completed)

  • ResponseWriter.flush(): Allow handlers to immediately push buffered chunks to the TCP socket without closing the connection. Enables Server-Sent Events (SSE) and generative AI chat streaming.
  • ResponseWriter.hijack(): Allow handlers to take ownership of the underlying std.Io.net.Stream. Enables WebSocket servers and protocol upgrade handshakes.
  • Handler Fault Isolation: Add graceful error reporting and stack recovery if handler code triggers unexpected failures.
  • WebSocket Support (lighting.extra.ws): RFC 6455 compliance with frame parsing, control frames, and interactive echo clients.

Phase 2: Enhanced Request Parsing & Utilities (Completed)

  • Cookie Support: Add a zero-copy Cookie parser and Set-Cookie builder supporting RFC 6265 attributes (HttpOnly, Secure, SameSite, Max-Age).
  • Comprehensive URL Query Parameter Decoder: Extend URL.queryParam into full multi-value iterator and helper to decode percent-encoded query parameters.
  • Multipart Form Data Parser: Streamed parser for multipart/form-data with configurable memory and file size limits for file uploads.

Phase 3: Ecosystem Handlers & Middleware (Completed)

  • Static File Server (lighting.extra.fs.FileServer): Serve directory trees with automatic Content-Type deduction, RFC 7233 Range requests, and If-Modified-Since / ETag 304 caching.
  • Reverse Proxy Handler (lighting.extra.proxy.ReverseProxy): Built-in reverse proxy with Director callback to rewrite request headers, strip hop-by-hop headers, and stream responses back.
  • Route-Level Timeout Middleware (lighting.timeoutHandler): Middleware to cancel or abort specific handler executions exceeding an allotted duration.

Phase 4: Protocol Expansion

  • Native TLS / HTTPS Support: Integrate with Zig TLS implementations or OS-native TLS facilities to serve HTTPS directly on port 443.
  • HTTP/2 Protocol Support: Support HTTP/2 framing, header compression (HPACK), and frame-level stream multiplexing.