initial commit

.beads/.gitignore

···
+# SQLite databases
+*.db
+*.db?*
+*.db-journal
+*.db-wal
+*.db-shm
+
+# Daemon runtime files
+daemon.lock
+daemon.log
+daemon.pid
+bd.sock
+
+# Legacy database files
+db.sqlite
+bd.db
+
+# Merge artifacts (temporary files from 3-way merge)
+beads.base.jsonl
+beads.base.meta.json
+beads.left.jsonl
+beads.left.meta.json
+beads.right.jsonl
+beads.right.meta.json
+
+# Keep JSONL exports and config (source of truth for git)
+!issues.jsonl
+!metadata.json
+!config.json

.beads/.local_version

···
+0.29.0

.beads/README.md

···
+# Beads - AI-Native Issue Tracking
+
+Welcome to Beads! This repository uses **Beads** for issue tracking - a modern, AI-native tool designed to live directly in your codebase alongside your code.
+
+## What is Beads?
+
+Beads is issue tracking that lives in your repo, making it perfect for AI coding agents and developers who want their issues close to their code. No web UI required - everything works through the CLI and integrates seamlessly with git.
+
+**Learn more:** [github.com/steveyegge/beads](https://github.com/steveyegge/beads)
+
+## Quick Start
+
+### Essential Commands
+
+```bash
+# Create new issues
+bd create "Add user authentication"
+
+# View all issues
+bd list
+
+# View issue details
+bd show <issue-id>
+
+# Update issue status
+bd update <issue-id> --status in_progress
+bd update <issue-id> --status done
+
+# Sync with git remote
+bd sync
+```
+
+### Working with Issues
+
+Issues in Beads are:
+- **Git-native**: Stored in `.beads/issues.jsonl` and synced like code
+- **AI-friendly**: CLI-first design works perfectly with AI coding agents
+- **Branch-aware**: Issues can follow your branch workflow
+- **Always in sync**: Auto-syncs with your commits
+
+## Why Beads?
+
+✨ **AI-Native Design**
+- Built specifically for AI-assisted development workflows
+- CLI-first interface works seamlessly with AI coding agents
+- No context switching to web UIs
+
+🚀 **Developer Focused**
+- Issues live in your repo, right next to your code
+- Works offline, syncs when you push
+- Fast, lightweight, and stays out of your way
+
+🔧 **Git Integration**
+- Automatic sync with git commits
+- Branch-aware issue tracking
+- Intelligent JSONL merge resolution
+
+## Get Started with Beads
+
+Try Beads in your own projects:
+
+```bash
+# Install Beads
+curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
+
+# Initialize in your repo
+bd init
+
+# Create your first issue
+bd create "Try out Beads"
+```
+
+## Learn More
+
+- **Documentation**: [github.com/steveyegge/beads/docs](https://github.com/steveyegge/beads/tree/main/docs)
+- **Quick Start Guide**: Run `bd quickstart`
+- **Examples**: [github.com/steveyegge/beads/examples](https://github.com/steveyegge/beads/tree/main/examples)
+
+---
+
+*Beads: Issue tracking that moves at the speed of thought* ⚡

.beads/config.yaml

···
+# Beads Configuration File
+# This file configures default behavior for all bd commands in this repository
+# All settings can also be set via environment variables (BD_* prefix)
+# or overridden with command-line flags
+
+# Issue prefix for this repository (used by bd init)
+# If not set, bd init will auto-detect from directory name
+# Example: issue-prefix: "myproject" creates issues like "myproject-1", "myproject-2", etc.
+# issue-prefix: ""
+
+# Use no-db mode: load from JSONL, no SQLite, write back after each command
+# When true, bd will use .beads/issues.jsonl as the source of truth
+# instead of SQLite database
+# no-db: false
+
+# Disable daemon for RPC communication (forces direct database access)
+# no-daemon: false
+
+# Disable auto-flush of database to JSONL after mutations
+# no-auto-flush: false
+
+# Disable auto-import from JSONL when it's newer than database
+# no-auto-import: false
+
+# Enable JSON output by default
+# json: false
+
+# Default actor for audit trails (overridden by BD_ACTOR or --actor)
+# actor: ""
+
+# Path to database (overridden by BEADS_DB or --db)
+# db: ""
+
+# Auto-start daemon if not running (can also use BEADS_AUTO_START_DAEMON)
+# auto-start-daemon: true
+
+# Debounce interval for auto-flush (can also use BEADS_FLUSH_DEBOUNCE)
+# flush-debounce: "5s"
+
+# Git branch for beads commits (bd sync will commit to this branch)
+# IMPORTANT: Set this for team projects so all clones use the same sync branch.
+# This setting persists across clones (unlike database config which is gitignored).
+# Can also use BEADS_SYNC_BRANCH env var for local override.
+# If not set, bd sync will require you to run 'bd config set sync.branch <branch>'.
+# sync-branch: "beads-sync"
+
+# Multi-repo configuration (experimental - bd-307)
+# Allows hydrating from multiple repositories and routing writes to the correct JSONL
+# repos:
+#   primary: "."  # Primary repo (where this database lives)
+#   additional:   # Additional repos to hydrate from (read-only)
+#     - ~/beads-planning  # Personal planning repo
+#     - ~/work-planning   # Work planning repo
+
+# Integration settings (access with 'bd config get/set')
+# These are stored in the database, not in this file:
+# - jira.url
+# - jira.project
+# - linear.url
+# - linear.api-key
+# - github.org
+# - github.repo

.beads/issues.jsonl

···
+{"id":"hcs-0ro","title":"Implement WebSocket frame types and parsing","description":"Implement WebSocket wire format in hcs-core/ws_frame.ml:\n\n```ocaml\ntype frame =\n  | Text of string\n  | Binary of Cstruct.t\n  | Ping of Cstruct.t\n  | Pong of Cstruct.t\n  | Close of int option * string option\n\ntype parse_result =\n  | Complete of frame * int  (* frame and bytes consumed *)\n  | Incomplete of int        (* need more bytes *)\n  | Error of string\n\nval parse_frame : Cstruct.t -\u003e parse_result\nval serialize_frame : ?mask:bool -\u003e frame -\u003e Cstruct.t\n\n(* Handshake *)\nval make_handshake_request : Uri.t -\u003e ?protocols:string list -\u003e Headers.t -\u003e request\nval validate_handshake_response : response -\u003e (string option, string) result  (* selected protocol *)\nval make_handshake_response : request -\u003e ?protocol:string -\u003e (response, string) result\n```\n\nPure parsing/serialization.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-29T14:34:32.864373772+01:00","updated_at":"2025-12-29T16:00:43.877842667+01:00","closed_at":"2025-12-29T16:00:43.877842667+01:00","dependencies":[{"issue_id":"hcs-0ro","depends_on_id":"hcs-lhr","type":"parent-child","created_at":"2025-12-29T14:34:52.111489961+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-0zq","title":"Testing Infrastructure and Compliance","description":"Set up testing infrastructure including unit tests, integration tests, and HTTP compliance test suites for both client and server implementations.","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-29T14:35:43.905080385+01:00","updated_at":"2025-12-29T17:57:31.987947689+01:00","closed_at":"2025-12-29T17:57:31.987947689+01:00","dependencies":[{"issue_id":"hcs-0zq","depends_on_id":"hcs-zba","type":"parent-child","created_at":"2025-12-29T14:35:55.080432801+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-1h7","title":"Create Go WebSocket benchmark server","description":"Go server using gorilla/websocket or nhooyr.io/websocket. Same interface as HCS: accept connections, keep alive, report count.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-30T09:59:59.144195314+01:00","updated_at":"2025-12-30T10:08:50.856707182+01:00","closed_at":"2025-12-30T10:08:50.856707182+01:00","dependencies":[{"issue_id":"hcs-1h7","depends_on_id":"hcs-jk8","type":"parent-child","created_at":"2025-12-30T10:00:30.601603816+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-1uy","title":"HTTP/2 Specific Features","description":"Implement H2 module with server push, stream priority, and HTTP/2 detection.","status":"closed","priority":3,"issue_type":"epic","created_at":"2025-12-29T14:25:37.55760677+01:00","updated_at":"2025-12-29T17:40:54.000014455+01:00","closed_at":"2025-12-29T17:40:54.000014455+01:00","dependencies":[{"issue_id":"hcs-1uy","depends_on_id":"hcs-zba","type":"parent-child","created_at":"2025-12-29T14:26:20.914923161+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-1vt","title":"Implement HTTP/2 server (Eio)","description":"Implement HTTP/2 server for Eio in hcs-eio/h2_server.ml:\n\n```ocaml\nval handle_connection :\n  flow:Eio.Flow.two_way -\u003e\n  clock:Eio.Time.clock -\u003e\n  config:Server.config -\u003e\n  handler:(request -\u003e (response, error) result) -\u003e\n  unit\n```\n\nFeatures:\n- HPACK header compression\n- Stream multiplexing (concurrent requests)\n- Flow control\n- Server push support\n- GOAWAY for graceful shutdown\n- Priority handling\n\nDepends on hpack package.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-29T14:33:25.282940788+01:00","updated_at":"2025-12-29T16:00:42.340368477+01:00","closed_at":"2025-12-29T16:00:42.340368477+01:00","dependencies":[{"issue_id":"hcs-1vt","depends_on_id":"hcs-rw6","type":"parent-child","created_at":"2025-12-29T14:33:42.729783837+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-23f","title":"Implement synchronous Stream module (core)","description":"Implement the synchronous Stream module in hcs-core/stream.ml:\n\nProducers:\n- empty, singleton, of_list, of_seq\n- unfold : ('s -\u003e ('a * 's) option) -\u003e 's -\u003e 'a t\n\nTransformers:\n- map, filter, filter_map\n- take, drop, chunks\n\nConsumers:\n- fold, iter, drain\n- to_string (for Cstruct.t streams)\n\nCombinators:\n- concat, zip\n\nThis is the pure, synchronous implementation. Runtime-specific async streams will wrap this.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-29T14:28:01.435958367+01:00","updated_at":"2025-12-29T14:51:05.189865738+01:00","closed_at":"2025-12-29T14:51:05.189865738+01:00","labels":["core"],"dependencies":[{"issue_id":"hcs-23f","depends_on_id":"hcs-czm","type":"parent-child","created_at":"2025-12-29T14:28:16.036236675+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-2ca","title":"Implement Eio TLS integration","description":"Implement TLS context creation for Eio runtime in hcs-eio/tls.ml:\n\n- Convert Tls_config.client to Tls.Config.client\n- Convert Tls_config.server to Tls.Config.server  \n- Load system certificates using ca-certs\n- Handle ALPN negotiation for HTTP/2\n- Wrap Eio flows with TLS\n\nDepends on tls-eio, ca-certs, x509 packages.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-29T14:30:34.350512358+01:00","updated_at":"2025-12-29T15:24:43.224163622+01:00","closed_at":"2025-12-29T15:24:43.224163622+01:00","dependencies":[{"issue_id":"hcs-2ca","depends_on_id":"hcs-y9w","type":"parent-child","created_at":"2025-12-29T14:30:47.016262637+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-2ca","depends_on_id":"hcs-cyb","type":"blocks","created_at":"2025-12-29T14:30:47.870432453+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-2ie","title":"Router Implementation","description":"Implement Path DSL for type-safe extraction and Router module with trie-based route lookup, scoping, and middleware support.","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-29T14:25:30.896190732+01:00","updated_at":"2025-12-29T15:41:48.160193387+01:00","closed_at":"2025-12-29T15:41:48.160193387+01:00","dependencies":[{"issue_id":"hcs-2ie","depends_on_id":"hcs-zba","type":"parent-child","created_at":"2025-12-29T14:26:15.462426699+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-320","title":"Create benchmark client for load generation","description":"Create a benchmark client (bin/hcs_bench_client.ml) that generates load and measures performance:\n- Configurable concurrency (number of parallel connections)\n- Configurable duration or request count\n- Support for HTTP/1.1 and HTTP/2\n- Measures: requests/second, latency (min/max/avg/p50/p99), errors\n- Reports results in human-readable and JSON formats\n\nShould use Eio fibers for concurrent requests.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-29T18:03:53.28432088+01:00","updated_at":"2025-12-29T18:15:36.842283087+01:00","closed_at":"2025-12-29T18:15:36.842283087+01:00","dependencies":[{"issue_id":"hcs-320","depends_on_id":"hcs-jtz","type":"parent-child","created_at":"2025-12-29T18:04:20.175343889+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-320","depends_on_id":"hcs-40d","type":"blocks","created_at":"2025-12-29T18:04:35.617524274+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-3dn","title":"Create HCS-based benchmark client for testing all servers","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-30T22:21:41.677601767+01:00","updated_at":"2025-12-30T22:31:12.664814017+01:00","closed_at":"2025-12-30T22:31:12.664814017+01:00"}
+{"id":"hcs-3ww","title":"Middleware System","description":"Implement Middleware module with composition, logging, security (CORS, auth), rate limiting, compression, caching, and static files.","status":"closed","priority":2,"issue_type":"epic","created_at":"2025-12-29T14:25:34.907454455+01:00","updated_at":"2025-12-29T17:40:52.182994384+01:00","closed_at":"2025-12-29T17:40:52.182994384+01:00","dependencies":[{"issue_id":"hcs-3ww","depends_on_id":"hcs-zba","type":"parent-child","created_at":"2025-12-29T14:26:19.080036903+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-40d","title":"Implement latency histogram and percentile calculations","description":"Create a statistics module (lib/bench_stats.ml or in the benchmark binary) for accurate latency measurements:\n- HDR histogram or simple sorted array for percentiles\n- Calculate min, max, mean, stddev\n- Calculate p50, p90, p95, p99, p99.9 percentiles\n- Track request count, error count, bytes transferred\n- Support for merging stats from multiple workers","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-29T18:03:57.696657065+01:00","updated_at":"2025-12-29T18:15:29.902324683+01:00","closed_at":"2025-12-29T18:15:29.902324683+01:00","dependencies":[{"issue_id":"hcs-40d","depends_on_id":"hcs-jtz","type":"parent-child","created_at":"2025-12-29T18:04:22.619809769+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-42q","title":"Implement runtime-parameterized async Stream","description":"Design async stream interface that works with both Eio and Lwt:\n\n```ocaml\nmodule type ASYNC_STREAM = sig\n  type 'a io\n  type 'a t\n  \n  val from_flow : ... -\u003e Cstruct.t t\n  val from_file : ... -\u003e Cstruct.t t\n  val to_sink : ... -\u003e Cstruct.t t -\u003e unit io\nend\n\nmodule Make_stream (R : RUNTIME) : ASYNC_STREAM with type 'a io = 'a R.t\n```\n\nThe Eio implementation uses Eio.Flow, the future Lwt version will use Lwt_io.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-29T14:28:05.317935403+01:00","updated_at":"2025-12-29T17:08:13.483830721+01:00","closed_at":"2025-12-29T17:08:13.483830721+01:00","labels":["architecture","core"],"dependencies":[{"issue_id":"hcs-42q","depends_on_id":"hcs-czm","type":"parent-child","created_at":"2025-12-29T14:28:16.763534695+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-42q","depends_on_id":"hcs-23f","type":"blocks","created_at":"2025-12-29T14:28:17.658557754+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-42q","depends_on_id":"hcs-6bi","type":"blocks","created_at":"2025-12-29T14:28:18.52508237+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-4w8","title":"Create benchmark server with configurable endpoints","description":"Create a dedicated benchmark server (bin/hcs_bench_server.ml) with endpoints optimized for benchmarking:\n- GET /ping - minimal response (measures raw throughput)\n- GET /bytes/:n - returns n bytes (measures payload handling)\n- POST /echo - echoes request body (measures request body parsing)\n- GET /delay/:ms - adds artificial delay (measures concurrency)\n- GET /headers/:n - returns n headers (measures header handling)\n\nServer should support both HTTP/1.1 and HTTP/2, with configurable port and worker count.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-29T18:03:49.541780606+01:00","updated_at":"2025-12-29T18:15:27.763639409+01:00","closed_at":"2025-12-29T18:15:27.763639409+01:00","dependencies":[{"issue_id":"hcs-4w8","depends_on_id":"hcs-jtz","type":"parent-child","created_at":"2025-12-29T18:04:17.563056726+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-505","title":"Add HTTP/2 benchmark endpoints and comparison scripts","description":"","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-30T00:14:16.705365323+01:00","updated_at":"2025-12-30T00:28:18.304877441+01:00","closed_at":"2025-12-30T00:28:18.304877441+01:00"}
+{"id":"hcs-56z","title":"Implement HTTP/1.1 server parser/serializer","description":"Implement HTTP/1.1 server wire format in hcs-core/h1.ml (extend existing):\n\n```ocaml\n(* Request parsing *)\ntype request_parse_result =\n  | Complete of request * int  (* request and bytes consumed *)\n  | Incomplete of int          (* need more bytes *)\n  | Error of string\n\nval parse_request_head : Cstruct.t -\u003e request_parse_result\n\n(* Response serialization *)\nval serialize_response : response -\u003e Cstruct.t\nval serialize_response_head : response -\u003e Cstruct.t\n```\n\nPure parsing, zero-copy with Cstruct views.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-29T14:33:19.050407222+01:00","updated_at":"2025-12-29T14:56:39.076056919+01:00","closed_at":"2025-12-29T14:56:39.076056919+01:00","dependencies":[{"issue_id":"hcs-56z","depends_on_id":"hcs-rw6","type":"parent-child","created_at":"2025-12-29T14:33:41.058840522+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-5eu","title":"Implement Log module","description":"Implement logging in hcs-core/log.ml:\n\n```ocaml\ntype level = Debug | Info | Warn | Error\n\ntype event =\n  | Request_start of { id: string; meth: method_; uri: Uri.t }\n  | Request_end of { id: string; status: status; duration_ms: float }\n  | Connection_open of { host: string; port: int }\n  | Connection_close of { host: string; port: int; reason: string }\n  | Connection_reuse of { host: string; port: int }\n  | Tls_handshake of { host: string; protocol: string }\n  | Retry of { id: string; attempt: int; reason: error }\n  | Error of { id: string; error: error }\n\ntype logger = level -\u003e event -\u003e unit\n\n(* Built-in loggers *)\nval null : logger\nval stderr : ?min_level:level -\u003e unit -\u003e logger\nval custom : (level -\u003e string -\u003e unit) -\u003e logger\n\n(* Format event as string *)\nval event_to_string : event -\u003e string\nval level_to_string : level -\u003e string\n```\n\nPure OCaml, no runtime dependency.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-29T14:30:26.138649492+01:00","updated_at":"2025-12-29T17:06:37.134220488+01:00","closed_at":"2025-12-29T17:06:37.134220488+01:00","dependencies":[{"issue_id":"hcs-5eu","depends_on_id":"hcs-fgd","type":"parent-child","created_at":"2025-12-29T14:30:45.51204607+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-5eu","depends_on_id":"hcs-gmb","type":"blocks","created_at":"2025-12-29T14:30:48.61530863+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-5wp","title":"Epic: Unified multi-protocol server + comprehensive benchmark suite","description":"Create unified servers (HCS, Hyper, Go) supporting HTTP/1.1, HTTP/2 h2c upgrade, and WebSocket. Build comprehensive benchmark client and automated benchmark runner.","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-31T14:13:14.360303024+01:00","updated_at":"2025-12-31T14:47:54.828065477+01:00","closed_at":"2025-12-31T14:47:54.828065477+01:00"}
+{"id":"hcs-6bi","title":"Design Runtime Abstraction Layer","description":"Design and implement a runtime abstraction layer that allows the library to work with both Eio and Lwt (future). This should include:\n\n1. Define a RUNTIME module signature abstracting:\n   - Promise/fiber types ('a t)\n   - Concurrency primitives (bind, return, map, both, all)\n   - Cancellation tokens\n   - Clock/time operations\n   - Network operations (connect, listen, read, write)\n   - Flow/stream abstractions\n\n2. Structure the library as:\n   - `hcs-core`: Pure types, parsers, router trie, codec signatures (no IO)\n   - `hcs-eio`: Eio runtime implementation\n   - `hcs-lwt`: (future) Lwt runtime implementation\n\n3. Use functors where IO is needed:\n   ```ocaml\n   module type RUNTIME = sig\n     type +'a t\n     val return : 'a -\u003e 'a t\n     val bind : 'a t -\u003e ('a -\u003e 'b t) -\u003e 'b t\n     val both : 'a t -\u003e 'b t -\u003e ('a * 'b) t\n     \n     module Net : sig ... end\n     module Time : sig ... end\n     module Cancel : sig ... end\n   end\n   \n   module Make_client (R : RUNTIME) : CLIENT with type 'a io = 'a R.t\n   module Make_server (R : RUNTIME) : SERVER with type 'a io = 'a R.t\n   ```\n\n4. Keep the core types (request, response, headers, body) runtime-agnostic where possible.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-29T14:26:44.115541536+01:00","updated_at":"2025-12-29T15:18:00.901135582+01:00","closed_at":"2025-12-29T15:18:00.901135582+01:00","labels":["architecture","design"],"dependencies":[{"issue_id":"hcs-6bi","depends_on_id":"hcs-zba","type":"parent-child","created_at":"2025-12-29T14:26:55.24314139+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-6hx","title":"Create WebSocket benchmark client","description":"Tool to open N concurrent WebSocket connections. Ramp up gradually, keep alive, report success/failure rates. Can target any server.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-30T10:00:01.720658703+01:00","updated_at":"2025-12-30T10:13:10.676804856+01:00","closed_at":"2025-12-30T10:13:10.676804856+01:00","dependencies":[{"issue_id":"hcs-6hx","depends_on_id":"hcs-jk8","type":"parent-child","created_at":"2025-12-30T10:00:40.686385073+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-6ki","title":"Create Rust WebSocket benchmark server","description":"Rust server using tokio-tungstenite. Same interface as HCS: accept connections, keep alive, report count.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-30T09:59:59.970998267+01:00","updated_at":"2025-12-30T10:08:50.863660424+01:00","closed_at":"2025-12-30T10:08:50.863660424+01:00","dependencies":[{"issue_id":"hcs-6ki","depends_on_id":"hcs-jk8","type":"parent-child","created_at":"2025-12-30T10:00:35.642901603+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-6yl","title":"Implement method_ type and helpers","description":"Implement the HTTP method type in types.ml:\n- GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS, CONNECT, TRACE variants\n- to_string/of_string functions\n- Comparison and equality\n\nThis is pure OCaml with no runtime dependency.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-29T14:27:08.798345263+01:00","updated_at":"2025-12-29T14:50:42.057204391+01:00","closed_at":"2025-12-29T14:50:42.057204391+01:00","labels":["core"],"dependencies":[{"issue_id":"hcs-6yl","depends_on_id":"hcs-ugs","type":"parent-child","created_at":"2025-12-29T14:27:38.28650235+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-763","title":"Create HTTP/1.1 server compliance tests","description":"Create comprehensive HTTP/1.1 server tests using curl and custom test client:\n\nTest categories (based on RFC 7230-7235):\n\n1. **Request parsing:**\n   - Valid/invalid request lines\n   - Header field parsing (folding, whitespace)\n   - Host header requirement\n   - Content-Length handling\n   - Transfer-Encoding: chunked\n\n2. **Response generation:**\n   - Status line format\n   - Required headers (Date, Content-Length/Transfer-Encoding)\n   - Connection: close/keep-alive\n\n3. **Methods:**\n   - HEAD returns no body\n   - OPTIONS with Allow header\n   - TRACE (if supported)\n   - Unknown methods\n\n4. **Connection management:**\n   - Keep-alive (HTTP/1.1 default)\n   - Pipelining support\n   - Connection: close handling\n   - Timeout behavior\n\n5. **Error handling:**\n   - 400 Bad Request (malformed)\n   - 405 Method Not Allowed\n   - 411 Length Required\n   - 413 Payload Too Large\n   - 414 URI Too Long\n   - 431 Request Header Fields Too Large\n   - 501 Not Implemented\n\n6. **Edge cases:**\n   - Empty body vs no body\n   - Zero Content-Length\n   - Multiple Content-Length headers (reject)\n   - LF vs CRLF tolerance","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-29T14:36:24.121658164+01:00","updated_at":"2025-12-29T17:52:19.19217344+01:00","closed_at":"2025-12-29T17:52:19.19217344+01:00","dependencies":[{"issue_id":"hcs-763","depends_on_id":"hcs-0zq","type":"parent-child","created_at":"2025-12-29T14:36:50.138423904+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-763","depends_on_id":"hcs-cyk","type":"blocks","created_at":"2025-12-29T14:36:59.919859607+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-7dw","title":"Run benchmarks after optimizations","description":"Re-run single-CPU benchmarks with run_h2_comparison.sh --single-cpu to measure improvement.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-30T08:57:27.925408893+01:00","updated_at":"2025-12-30T09:01:48.794721842+01:00","closed_at":"2025-12-30T09:01:48.794721842+01:00","dependencies":[{"issue_id":"hcs-7dw","depends_on_id":"hcs-cq4","type":"parent-child","created_at":"2025-12-30T08:57:54.882328415+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-7dw","depends_on_id":"hcs-f2r","type":"blocks","created_at":"2025-12-30T08:57:59.924301728+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-7dw","depends_on_id":"hcs-jqx","type":"blocks","created_at":"2025-12-30T08:58:04.960054323+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-7my","title":"Implement zero-copy optimizations in H2_server (Body_bigstring, Body_prebuilt)","description":"","status":"closed","priority":1,"issue_type":"feature","created_at":"2025-12-30T00:14:14.612100017+01:00","updated_at":"2025-12-30T00:19:21.483563727+01:00","closed_at":"2025-12-30T00:19:21.483563727+01:00"}
+{"id":"hcs-7n9","title":"Implement HTTP/1.1 client (Eio)","description":"Implement HTTP/1.1 client for Eio in hcs-eio/h1_client.ml:\n\n```ocaml\nval request :\n  flow:Eio.Flow.two_way -\u003e\n  clock:Eio.Time.clock -\u003e\n  config:Client.config -\u003e\n  ?cancel:Cancel.t -\u003e\n  request -\u003e\n  (response, error) result\n```\n\nFeatures:\n- Send request, read response using h1 parser\n- Handle Content-Length and chunked bodies\n- Support streaming response body\n- Respect timeouts from config\n- Handle keep-alive\n- Integrate with logging","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-29T14:31:20.182355085+01:00","updated_at":"2025-12-29T15:03:26.826860172+01:00","closed_at":"2025-12-29T15:03:26.826860172+01:00","dependencies":[{"issue_id":"hcs-7n9","depends_on_id":"hcs-qnb","type":"parent-child","created_at":"2025-12-29T14:31:48.505518121+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-7n9","depends_on_id":"hcs-8zr","type":"blocks","created_at":"2025-12-29T14:31:52.981022505+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-7n9","depends_on_id":"hcs-kg1","type":"blocks","created_at":"2025-12-29T14:31:53.49623941+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-82y","title":"HTTP/2 Performance Comparison: HCS vs Rust vs Go","description":"Compare HTTP/2 server performance across HCS (OCaml), Rust (hyper/axum), and Go (net/http). Focus on throughput, latency, and resource usage under various workloads.","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-30T08:21:37.583365059+01:00","updated_at":"2025-12-30T08:49:54.887556286+01:00","closed_at":"2025-12-30T08:49:54.887556286+01:00"}
+{"id":"hcs-8br","title":"Implement Cancel module","description":"Implement cooperative cancellation in hcs-core/cancel.ml:\n\n```ocaml\nmodule Cancel : sig\n  type t\n  \n  val create : unit -\u003e t\n  val cancel : t -\u003e unit\n  val is_cancelled : t -\u003e bool\n  val check : t -\u003e (unit, error) result  (* Returns Error Cancelled if cancelled *)\n  \n  (* Combine multiple tokens - cancelled if any is cancelled *)\n  val any : t list -\u003e t\nend\n```\n\nImplementation: Use an Atomic.t bool internally for thread-safety. The `any` combinator creates a new token that polls children.\n\nThis is the core, runtime-agnostic cancellation. Runtime-specific implementations (Eio.Cancel, Lwt.cancel) will wrap this or provide their own.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-29T14:29:20.005246967+01:00","updated_at":"2025-12-29T14:56:31.063102088+01:00","closed_at":"2025-12-29T14:56:31.063102088+01:00","labels":["core"],"dependencies":[{"issue_id":"hcs-8br","depends_on_id":"hcs-pnc","type":"parent-child","created_at":"2025-12-29T14:30:09.074639524+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-8zr","title":"Implement HTTP/1.1 client parser/serializer","description":"Implement HTTP/1.1 wire format in hcs-core/h1.ml:\n\n```ocaml\n(* Request serialization *)\nval serialize_request : request -\u003e Cstruct.t\nval serialize_request_head : request -\u003e Cstruct.t  (* without body *)\n\n(* Response parsing *)\ntype parse_result = \n  | Complete of response * int  (* response and bytes consumed *)\n  | Incomplete of int           (* need more bytes, minimum *)\n  | Error of string\n\nval parse_response_head : Cstruct.t -\u003e parse_result\n\n(* Chunked transfer encoding *)\nval parse_chunk_header : Cstruct.t -\u003e (int * int, string) result  (* size, header_len *)\nval serialize_chunk : Cstruct.t -\u003e Cstruct.t\nval serialize_last_chunk : Cstruct.t\n```\n\nPure parsing/serialization, no IO. Use zero-copy where possible with Cstruct views.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-29T14:31:17.431899471+01:00","updated_at":"2025-12-29T14:56:37.246977449+01:00","closed_at":"2025-12-29T14:56:37.246977449+01:00","dependencies":[{"issue_id":"hcs-8zr","depends_on_id":"hcs-qnb","type":"parent-child","created_at":"2025-12-29T14:31:46.61571522+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-9dz","title":"Clean up duplicate implementations: remove non-optimized functions and rename optimized ones","description":"","status":"closed","priority":1,"issue_type":"chore","created_at":"2025-12-30T21:00:09.361966265+01:00","updated_at":"2025-12-30T21:08:48.343581414+01:00","closed_at":"2025-12-30T21:08:48.343581414+01:00"}
+{"id":"hcs-9y1","title":"Implement Client.config type","description":"Implement client configuration in hcs-core/client_config.ml:\n\n```ocaml\ntype config = {\n  (* Connection pooling *)\n  max_connections_per_host : int;    (* default: 100 *)\n  max_total_connections : int;       (* default: 1000 *)\n  idle_timeout : float;              (* seconds, default: 60.0 *)\n\n  (* Timeouts *)\n  connect_timeout : float;           (* default: 30.0 *)\n  read_timeout : float;              (* default: 30.0 *)\n  write_timeout : float;             (* default: 30.0 *)\n\n  (* Behavior *)\n  follow_redirects : int option;     (* None = don't follow, default: Some 10 *)\n  http2_prior_knowledge : bool;      (* default: false *)\n\n  (* Buffers *)\n  buffer_size : int;                 (* default: 16384 *)\n  max_response_body : int64 option;  (* None = unlimited *)\n\n  (* TLS *)\n  tls : Tls_config.client option;\n\n  (* Compression *)\n  accept_compression : bool;         (* default: true *)\n  decompress_response : bool;        (* default: true *)\n\n  (* Logging *)\n  logger : Log.logger;               (* default: Log.null *)\n}\n\nval default : config\nval with_timeout : float -\u003e config -\u003e config\nval with_max_connections : int -\u003e config -\u003e config\n(* ... other builders ... *)\n```\n\nPure configuration, no IO.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-29T14:31:05.431230385+01:00","updated_at":"2025-12-29T15:40:22.434194947+01:00","closed_at":"2025-12-29T15:40:22.434194947+01:00","dependencies":[{"issue_id":"hcs-9y1","depends_on_id":"hcs-qnb","type":"parent-child","created_at":"2025-12-29T14:31:42.307867928+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-9yc","title":"Go: Unified server with HTTP/1.1 + h2c + WebSocket","description":"Update Go net/http server to handle HTTP/1.1, h2c, and WebSocket on single port.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-31T14:13:36.193925748+01:00","updated_at":"2025-12-31T14:26:13.33110701+01:00","closed_at":"2025-12-31T14:26:13.33110701+01:00","dependencies":[{"issue_id":"hcs-9yc","depends_on_id":"hcs-5wp","type":"parent-child","created_at":"2025-12-31T14:14:30.935375958+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-ag6","title":"Implement H2 module (HTTP/2 specific features)","description":"Implement HTTP/2 specific features in hcs-eio/h2.ml:\n\n```ocaml\n(* Server push *)\nval push : request -\u003e Uri.t -\u003e (unit, error) result\n\n(* Stream priority *)\ntype priority = {\n  dependency : int32;\n  weight : int;       (* 1-256 *)\n  exclusive : bool;\n}\n\nval set_priority : priority -\u003e (unit, error) result\n\n(* Check protocol *)\nval is_h2 : request -\u003e bool\n```\n\nLower priority - can be added after basic HTTP/2 works.","status":"closed","priority":3,"issue_type":"task","created_at":"2025-12-29T14:34:36.59579057+01:00","updated_at":"2025-12-29T17:39:24.986755909+01:00","closed_at":"2025-12-29T17:39:24.986755909+01:00","dependencies":[{"issue_id":"hcs-ag6","depends_on_id":"hcs-1uy","type":"parent-child","created_at":"2025-12-29T14:34:53.890566238+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-ag6","depends_on_id":"hcs-d5s","type":"blocks","created_at":"2025-12-29T14:34:58.997623679+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-ajr","title":"Compare HCS performance against external tools (wrk, hey)","description":"Validate HCS benchmark results by comparing against established tools:\n- Use wrk or hey to benchmark HCS server\n- Compare results with HCS benchmark client\n- Document any discrepancies\n- This validates both our server performance and benchmark accuracy\n\nOptional: Add script to run comparison benchmarks.","status":"closed","priority":3,"issue_type":"task","created_at":"2025-12-29T18:04:05.806924896+01:00","updated_at":"2025-12-29T18:18:13.778810608+01:00","closed_at":"2025-12-29T18:18:13.778810608+01:00","dependencies":[{"issue_id":"hcs-ajr","depends_on_id":"hcs-jtz","type":"parent-child","created_at":"2025-12-29T18:04:25.893845517+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-ajr","depends_on_id":"hcs-4w8","type":"blocks","created_at":"2025-12-29T18:04:39.385790421+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-ax6","title":"Implement With_codec functor","description":"Implement the With_codec functor in hcs-core/codec.ml:\n\n```ocaml\nmodule With_codec (C : CODEC) : sig\n  val encode_body : 'a C.encoder -\u003e 'a -\u003e (body, error) result\n  val decode_body : 'a C.decoder -\u003e body -\u003e ('a, error) result\n\n  (* Request helpers *)\n  val set_body : 'a C.encoder -\u003e 'a -\u003e request -\u003e (request, error) result\n\n  (* Response helpers *)  \n  val read_body : 'a C.decoder -\u003e response -\u003e ('a, error) result\n  val make_response : ?status:status -\u003e 'a C.encoder -\u003e 'a -\u003e (response, error) result\nend\n```\n\nThe functor should:\n- Handle body type variants (Empty, Fixed, Stream, File)\n- Set appropriate Content-Type header from C.content_type\n- Convert between Cstruct.t and body types\n- Propagate codec errors as Codec_error\n\nPure OCaml, depends on types.ml and error.ml.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-29T14:28:47.94509919+01:00","updated_at":"2025-12-29T17:04:35.621002337+01:00","closed_at":"2025-12-29T17:04:35.621002337+01:00","labels":["core"],"dependencies":[{"issue_id":"hcs-ax6","depends_on_id":"hcs-m4r","type":"parent-child","created_at":"2025-12-29T14:29:00.595372107+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-ax6","depends_on_id":"hcs-pwc","type":"blocks","created_at":"2025-12-29T14:29:02.656963585+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-bea","title":"Implement core middleware combinators","description":"Implement middleware composition in hcs-core/middleware.ml:\n\n```ocaml\ntype middleware = (request -\u003e (response, error) result) -\u003e request -\u003e (response, error) result\n\n(* Composition *)\nval ( @\u003e ) : middleware -\u003e middleware -\u003e middleware\nval compose : middleware list -\u003e middleware\nval identity : middleware\n\n(* Pure middleware (no IO needed) *)\nval default_headers : (string * string) list -\u003e middleware\nval catch_errors : (error -\u003e response) -\u003e middleware\nval body_limit : int64 -\u003e middleware\nval request_id : ?header:string -\u003e ?generator:(unit -\u003e string) -\u003e unit -\u003e middleware\n\n(* Security headers *)\nval security_headers : middleware\nval cors :\n  ?origins:[ `All | `List of string list ] -\u003e\n  ?methods:method_ list -\u003e\n  ?headers:string list -\u003e\n  ?max_age:int -\u003e\n  ?credentials:bool -\u003e\n  unit -\u003e\n  middleware\n\n(* Auth - validation functions are pure *)\nval basic_auth : realm:string -\u003e validate:(user:string -\u003e pass:string -\u003e bool) -\u003e middleware\nval bearer_auth : validate:(token:string -\u003e bool) -\u003e middleware\n```\n\nPure OCaml.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-29T14:34:27.663177003+01:00","updated_at":"2025-12-29T15:18:06.262737908+01:00","closed_at":"2025-12-29T15:18:06.262737908+01:00","dependencies":[{"issue_id":"hcs-bea","depends_on_id":"hcs-3ww","type":"parent-child","created_at":"2025-12-29T14:34:50.365242865+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-chm","title":"Implement body type","description":"Implement the body type in types.ml:\n- Empty variant\n- Fixed of string variant\n- Stream of (unit -\u003e Cstruct.t option) - pull-based streaming\n- File of string * int64 * int64 (path, offset, length)\n\nNote: The Stream variant uses a function type that is runtime-agnostic. For async streaming, we'll need a runtime-parameterized body type in the IO layer.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-29T14:27:16.560667848+01:00","updated_at":"2025-12-29T14:50:45.579783806+01:00","closed_at":"2025-12-29T14:50:45.579783806+01:00","labels":["core"],"dependencies":[{"issue_id":"hcs-chm","depends_on_id":"hcs-ugs","type":"parent-child","created_at":"2025-12-29T14:27:40.664331169+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-cks","title":"Implement Headers module","description":"Implement case-insensitive header map in headers.ml:\n- type t (backed by Map with lowercase keys)\n- empty, singleton, add, add_list\n- find, find_all, remove, mem\n- fold, to_list, of_list\n- Consider using a more efficient representation (e.g., sorted list for small headers)\n\nPure OCaml, no runtime dependency.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-29T14:27:12.768404369+01:00","updated_at":"2025-12-29T14:50:44.414829218+01:00","closed_at":"2025-12-29T14:50:44.414829218+01:00","labels":["core"],"dependencies":[{"issue_id":"hcs-cks","depends_on_id":"hcs-ugs","type":"parent-child","created_at":"2025-12-29T14:27:39.839372964+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-cmg","title":"Implement version type","description":"Implement the HTTP version type:\n- HTTP_1_1, HTTP_2 variants\n- to_string/of_string functions\n\nPure OCaml, no runtime dependency.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-29T14:27:10.081239709+01:00","updated_at":"2025-12-29T14:50:42.943845373+01:00","closed_at":"2025-12-29T14:50:42.943845373+01:00","labels":["core"],"dependencies":[{"issue_id":"hcs-cmg","depends_on_id":"hcs-ugs","type":"parent-child","created_at":"2025-12-29T14:27:39.140549859+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-cq4","title":"HTTP/2 Server Performance Optimizations","description":"Implement optimizations identified from benchmarking: skip body reading for GET, optimize path extraction, reduce allocations","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-30T08:57:10.907204503+01:00","updated_at":"2025-12-30T09:02:03.611661211+01:00","closed_at":"2025-12-30T09:02:03.611661211+01:00"}
+{"id":"hcs-cwz","title":"Set up httpbin for client compliance testing","description":"Set up httpbin (or go-httpbin) for testing the HTTP client:\n\n1. Add Docker Compose file with go-httpbin service\n2. Create test suite covering:\n   - All HTTP methods (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS)\n   - Request headers sent correctly\n   - Query parameters encoding\n   - Request body (form, JSON-like, binary)\n   - Response status codes (1xx-5xx)\n   - Redirects (301, 302, 303, 307, 308) with redirect limits\n   - Basic auth, Bearer auth\n   - Cookies (send and receive)\n   - Compression (gzip, deflate)\n   - Chunked transfer encoding\n   - Connection keep-alive\n   - Timeouts (delayed responses)\n   - Large responses / streaming\n\n3. Integrate into `dune runtest` or separate compliance target","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-29T14:36:08.700591408+01:00","updated_at":"2025-12-29T17:56:36.02148206+01:00","closed_at":"2025-12-29T17:56:36.02148206+01:00","dependencies":[{"issue_id":"hcs-cwz","depends_on_id":"hcs-0zq","type":"parent-child","created_at":"2025-12-29T14:36:44.727305222+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-cwz","depends_on_id":"hcs-j2z","type":"blocks","created_at":"2025-12-29T14:36:54.844910505+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-cxj","title":"Add domain_count to server config","description":"Add domain_count field to H1_server.config and H2_server to specify max CPUs. Default to 1 for backward compatibility.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-30T09:05:52.544967921+01:00","updated_at":"2025-12-30T09:10:47.510063908+01:00","closed_at":"2025-12-30T09:10:47.510063908+01:00","dependencies":[{"issue_id":"hcs-cxj","depends_on_id":"hcs-zq3","type":"parent-child","created_at":"2025-12-30T09:06:14.106250303+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-cyb","title":"Implement Tls_config module","description":"Implement TLS configuration in hcs-core/tls_config.ml:\n\n```ocaml\ntype client\ntype server\n\ntype verification =\n  | System_certificates\n  | Custom_certificates of string list  (* PEM file paths *)\n  | Fingerprint of string\n  | Insecure_no_verify\n\n(* Client config builder - returns config, actual TLS context created by runtime *)\nval client :\n  ?verification:verification -\u003e\n  ?alpn_protocols:string list -\u003e\n  ?hostname:string -\u003e\n  unit -\u003e\n  client\n\n(* Server config builder *)\nval server :\n  cert_file:string -\u003e\n  key_file:string -\u003e\n  ?alpn_protocols:string list -\u003e\n  ?client_auth:[ `None | `Optional | `Required ] -\u003e\n  ?ca_file:string -\u003e\n  unit -\u003e\n  server\n```\n\nThe actual TLS context creation (using tls-eio or tls-lwt) happens in the runtime layer. This module just holds configuration.\n\nPure OCaml, configuration types only.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-29T14:30:31.480806804+01:00","updated_at":"2025-12-29T15:24:40.571579433+01:00","closed_at":"2025-12-29T15:24:40.571579433+01:00","dependencies":[{"issue_id":"hcs-cyb","depends_on_id":"hcs-y9w","type":"parent-child","created_at":"2025-12-29T14:30:46.125231092+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-cyk","title":"Implement unified Server module (Eio)","description":"Implement unified server API in hcs-eio/server.ml:\n\n```ocaml\ntype t\n\nval create :\n  sw:Eio.Switch.t -\u003e\n  net:Eio.Net.t -\u003e\n  clock:Eio.Time.clock -\u003e\n  ?config:config -\u003e\n  Router.compiled -\u003e\n  t\n\nval run : t -\u003e unit  (* Blocks until shutdown *)\nval shutdown : ?timeout:float -\u003e t -\u003e unit\nval listening_on : t -\u003e (string * int)\nval connection_count : t -\u003e int\n```\n\nFeatures:\n- Accept connections, spawn fibers\n- Protocol detection (ALPN for TLS, prior knowledge)\n- Dispatch to H1 or H2 handler\n- Connection limiting\n- Graceful shutdown with drain timeout\n- TLS support","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-29T14:33:29.304626659+01:00","updated_at":"2025-12-29T17:00:22.652965066+01:00","closed_at":"2025-12-29T17:00:22.652965066+01:00","dependencies":[{"issue_id":"hcs-cyk","depends_on_id":"hcs-rw6","type":"parent-child","created_at":"2025-12-29T14:33:43.591242696+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-cyk","depends_on_id":"hcs-lqi","type":"blocks","created_at":"2025-12-29T14:33:45.174337222+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-cyk","depends_on_id":"hcs-1vt","type":"blocks","created_at":"2025-12-29T14:33:46.071365575+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-cyk","depends_on_id":"hcs-sny","type":"blocks","created_at":"2025-12-29T14:33:46.914541815+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-cyk","depends_on_id":"hcs-2ca","type":"blocks","created_at":"2025-12-29T14:33:47.760104216+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-czm","title":"Streaming Abstraction","description":"Implement the Stream module with producers, transformers, consumers, and combinators for lazy, backpressure-aware streaming.","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-29T14:25:20.968837055+01:00","updated_at":"2025-12-29T17:41:32.374046501+01:00","closed_at":"2025-12-29T17:41:32.374046501+01:00","dependencies":[{"issue_id":"hcs-czm","depends_on_id":"hcs-zba","type":"parent-child","created_at":"2025-12-29T14:25:57.77315075+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-d3q","title":"Set up Autobahn for WebSocket compliance testing","description":"Integrate Autobahn|Testsuite for WebSocket compliance:\n\n1. Add Autobahn to CI via Docker (crossbario/autobahn-testsuite)\n2. Test both client and server modes:\n\n**Server testing** (Autobahn as client):\n```\ndocker run -it --rm \\\n  -v \"${PWD}/reports:/reports\" \\\n  crossbario/autobahn-testsuite \\\n  wstest -m fuzzingclient -s /config/fuzzingclient.json\n```\n\n**Client testing** (Autobahn as server):\n```\ndocker run -it --rm \\\n  -v \"${PWD}/reports:/reports\" \\\n  crossbario/autobahn-testsuite \\\n  wstest -m fuzzingserver -s /config/fuzzingserver.json\n```\n\nTest cases cover:\n- Framing (text, binary, fragmentation)\n- Ping/Pong\n- Close handshake\n- Reserved bits\n- Opcodes\n- UTF-8 validation\n- Compression (permessage-deflate)\n- Limits and performance\n\nTarget: Pass all non-optional Autobahn test cases","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-29T14:36:18.251422099+01:00","updated_at":"2025-12-29T17:57:13.521624023+01:00","closed_at":"2025-12-29T17:57:13.521624023+01:00","dependencies":[{"issue_id":"hcs-d3q","depends_on_id":"hcs-0zq","type":"parent-child","created_at":"2025-12-29T14:36:48.059495592+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-d3q","depends_on_id":"hcs-nad","type":"blocks","created_at":"2025-12-29T14:36:58.909180795+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-d5s","title":"Implement HTTP/2 client (Eio)","description":"Implement HTTP/2 client for Eio in hcs-eio/h2_client.ml:\n\n```ocaml\ntype t  (* HTTP/2 connection with multiplexed streams *)\n\nval create : flow:Eio.Flow.two_way -\u003e clock:Eio.Time.clock -\u003e config:Client.config -\u003e t\nval request : t -\u003e ?cancel:Cancel.t -\u003e request -\u003e (response, error) result\nval close : t -\u003e unit\n```\n\nFeatures:\n- HPACK header compression\n- Stream multiplexing\n- Flow control per stream and connection\n- SETTINGS frame handling\n- Priority hints (optional)\n- GOAWAY handling\n\nDepends on hpack package.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-29T14:31:23.240487001+01:00","updated_at":"2025-12-29T16:00:40.891022027+01:00","closed_at":"2025-12-29T16:00:40.891022027+01:00","dependencies":[{"issue_id":"hcs-d5s","depends_on_id":"hcs-qnb","type":"parent-child","created_at":"2025-12-29T14:31:50.019661778+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-dd4","title":"Set up h2spec for HTTP/2 compliance testing","description":"Integrate h2spec for HTTP/2 server compliance:\n\n1. Add h2spec to CI (available as binary or Docker)\n2. Create test harness that:\n   - Starts hcs HTTP/2 server on test port\n   - Runs h2spec against it\n   - Parses results\n\nh2spec tests:\n- HPACK header compression\n- Stream states and transitions\n- Flow control (window updates)\n- Error handling (RST_STREAM, GOAWAY)\n- SETTINGS frames\n- PRIORITY frames\n- CONTINUATION frames\n- Frame size limits\n- Connection preface\n\nTarget: Pass all h2spec generic tests\n\nCommand: `h2spec -h localhost -p 8080 --strict`","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-29T14:36:13.071332042+01:00","updated_at":"2025-12-29T17:57:10.493059681+01:00","closed_at":"2025-12-29T17:57:10.493059681+01:00","dependencies":[{"issue_id":"hcs-dd4","depends_on_id":"hcs-0zq","type":"parent-child","created_at":"2025-12-29T14:36:46.491278695+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-dd4","depends_on_id":"hcs-cyk","type":"blocks","created_at":"2025-12-29T14:36:57.517342388+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-ddd","title":"Create HTTP/2 cross-language benchmark script","description":"Create run_h2_comparison.sh that starts all three servers (HCS, Rust, Go) and runs h2load benchmarks against each. Test /ping, /bytes/1024, /bytes/10240 endpoints. Output structured results for comparison.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-30T08:21:57.169092148+01:00","updated_at":"2025-12-30T08:48:51.028339202+01:00","closed_at":"2025-12-30T08:48:51.028339202+01:00","dependencies":[{"issue_id":"hcs-ddd","depends_on_id":"hcs-osg","type":"blocks","created_at":"2025-12-30T08:22:14.06532517+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-ddd","depends_on_id":"hcs-l9p","type":"blocks","created_at":"2025-12-30T08:22:16.71293984+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-ddd","depends_on_id":"hcs-82y","type":"parent-child","created_at":"2025-12-30T08:22:25.823611037+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-dle","title":"Request/Response Helpers","description":"Implement Request and Response helper modules with body handling, status shortcuts, and codec integration.","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-29T14:25:33.481216228+01:00","updated_at":"2025-12-29T15:40:53.163093449+01:00","closed_at":"2025-12-29T15:40:53.163093449+01:00","dependencies":[{"issue_id":"hcs-dle","depends_on_id":"hcs-zba","type":"parent-child","created_at":"2025-12-29T14:26:17.959259297+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-dsf","title":"Set up project structure and dune build","description":"Set up the OCaml project structure with dune:\n\n```\nhcs/\n├── dune-project\n├── hcs-core/           # Pure, runtime-agnostic\n│   ├── dune\n│   ├── types.ml\n│   ├── error.ml\n│   ├── headers.ml\n│   ├── stream.ml       # Synchronous stream operations\n│   ├── codec.ml\n│   └── hcs_core.ml     # Public API re-exports\n├── hcs-eio/            # Eio runtime\n│   ├── dune\n│   ├── runtime.ml      # RUNTIME implementation for Eio\n│   ├── client.ml\n│   ├── server.ml\n│   └── hcs_eio.ml\n└── hcs/                # Convenience package (re-exports hcs-eio)\n    ├── dune\n    └── hcs.ml\n```\n\nConfigure opam dependencies.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-29T14:27:26.717322855+01:00","updated_at":"2025-12-29T14:50:39.789609025+01:00","closed_at":"2025-12-29T14:50:39.789609025+01:00","labels":["infrastructure"],"dependencies":[{"issue_id":"hcs-dsf","depends_on_id":"hcs-ugs","type":"parent-child","created_at":"2025-12-29T14:27:43.02614445+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-dzr","title":"Create TechEmpower-style benchmark suite with hyper, fasthttp, and HCS servers","description":"","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-30T22:21:05.455078159+01:00","updated_at":"2025-12-30T22:33:15.399922114+01:00","closed_at":"2025-12-30T22:33:15.399922114+01:00"}
+{"id":"hcs-f2r","title":"Skip body reading for bodiless methods (GET/HEAD/DELETE)","description":"In h2_server.ml, skip Buffer.create, Promise.create, and body reading for GET/HEAD/DELETE methods. These have no body but currently allocate a buffer and promise.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-30T08:57:23.954431824+01:00","updated_at":"2025-12-30T09:01:38.714453571+01:00","closed_at":"2025-12-30T09:01:38.714453571+01:00","dependencies":[{"issue_id":"hcs-f2r","depends_on_id":"hcs-cq4","type":"parent-child","created_at":"2025-12-30T08:57:44.799141738+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-fgd","title":"Logging System","description":"Implement Log module with level, event types, built-in loggers (null, stderr, custom), and event formatting.","status":"closed","priority":2,"issue_type":"epic","created_at":"2025-12-29T14:25:26.517303879+01:00","updated_at":"2025-12-29T17:40:48.765669075+01:00","closed_at":"2025-12-29T17:40:48.765669075+01:00","dependencies":[{"issue_id":"hcs-fgd","depends_on_id":"hcs-zba","type":"parent-child","created_at":"2025-12-29T14:26:08.827592455+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-fsc","title":"Implement Request helper module","description":"Implement request helpers in hcs-core/request.ml:\n\n```ocaml\nval path : request -\u003e string\nval query : string -\u003e request -\u003e string option\nval query_all : string -\u003e request -\u003e string list\nval header : string -\u003e request -\u003e string option\nval header_all : string -\u003e request -\u003e string list\nval content_type : request -\u003e string option\nval content_length : request -\u003e int64 option\nval is_keep_alive : request -\u003e bool\n\n(* Body consumption - sync versions *)\nval body_string : request -\u003e (string, error) result\nval body_to_cstruct : request -\u003e (Cstruct.t, error) result\n\n(* Form data parsing *)\nval form : request -\u003e ((string * string) list, error) result\n```\n\nPure OCaml + uri package.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-29T14:34:09.842512086+01:00","updated_at":"2025-12-29T15:40:29.136273489+01:00","closed_at":"2025-12-29T15:40:29.136273489+01:00","dependencies":[{"issue_id":"hcs-fsc","depends_on_id":"hcs-dle","type":"parent-child","created_at":"2025-12-29T14:34:47.838799048+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-fsc","depends_on_id":"hcs-lpr","type":"blocks","created_at":"2025-12-29T14:34:54.851316989+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-g2y","title":"Research HTTP compliance test suites","description":"Research and document available HTTP compliance testing tools and servers:\n\n**For Client Testing (test servers):**\n\n1. **httpbin** (https://httpbin.org / kennethreitz/httpbin)\n   - Returns request info as JSON\n   - Tests: methods, headers, redirects, auth, cookies, response codes\n   - Can run locally via Docker\n\n2. **go-httpbin** (mccutchen/go-httpbin)\n   - Go reimplementation, faster and more features\n   - Better for local testing\n\n3. **h2spec** (summerwind/h2spec)\n   - HTTP/2 conformance testing tool\n   - Tests HPACK, streams, flow control, error handling\n   - Essential for HTTP/2 compliance\n\n4. **curl test suite**\n   - curl's own test servers have extensive edge cases\n\n**For Server Testing (test clients):**\n\n1. **h2load** (nghttp2)\n   - HTTP/2 benchmarking and testing\n   - Tests multiplexing, flow control\n\n2. **curl** with verbose options\n   - Good for basic HTTP/1.1 compliance\n\n3. **nghttp** (nghttp2)\n   - HTTP/2 client for testing server responses\n\n4. **Autobahn|Testsuite** (for WebSocket)\n   - Comprehensive WebSocket protocol compliance\n   - https://github.com/crossbario/autobahn-testsuite\n\n**RFC Compliance:**\n- RFC 7230-7235 (HTTP/1.1)\n- RFC 7540 (HTTP/2)\n- RFC 6455 (WebSocket)\n- RFC 7541 (HPACK)\n\nEvaluate which tools to integrate into CI.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-29T14:36:03.601972706+01:00","updated_at":"2025-12-29T17:31:46.947022974+01:00","closed_at":"2025-12-29T17:31:46.947022974+01:00","dependencies":[{"issue_id":"hcs-g2y","depends_on_id":"hcs-0zq","type":"parent-child","created_at":"2025-12-29T14:36:42.697870585+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-gmb","title":"Implement error type","description":"Implement comprehensive error type in error.ml:\n- Connection_failed, Connection_closed\n- Timeout variants (Connect, Read, Write, Total)\n- Cancelled\n- Invalid_url, Invalid_response\n- Too_many_redirects\n- Protocol_error, Tls_error, Codec_error\n- Body_too_large, IO_error\n\nInclude to_string for debugging. Pure OCaml.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-29T14:27:22.136715155+01:00","updated_at":"2025-12-29T14:50:40.75088559+01:00","closed_at":"2025-12-29T14:50:40.75088559+01:00","labels":["core"],"dependencies":[{"issue_id":"hcs-gmb","depends_on_id":"hcs-ugs","type":"parent-child","created_at":"2025-12-29T14:27:42.239579889+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-h2a","title":"Benchmark runner script with memory profiling","description":"Create benchmark runner that tests all servers across all protocols, measures req/s, msg/s, memory/connection, and produces summary report.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-31T14:13:51.31059033+01:00","updated_at":"2025-12-31T14:47:32.444742919+01:00","closed_at":"2025-12-31T14:47:32.444742919+01:00","dependencies":[{"issue_id":"hcs-h2a","depends_on_id":"hcs-rzc","type":"blocks","created_at":"2025-12-31T14:14:05.717334469+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-h2a","depends_on_id":"hcs-9yc","type":"blocks","created_at":"2025-12-31T14:14:10.761462149+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-h2a","depends_on_id":"hcs-s94","type":"blocks","created_at":"2025-12-31T14:14:15.805316293+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-h2a","depends_on_id":"hcs-peu","type":"blocks","created_at":"2025-12-31T14:14:20.849391195+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-h2a","depends_on_id":"hcs-5wp","type":"parent-child","created_at":"2025-12-31T14:14:46.066127034+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-hkf","title":"Add benchmark runner script with standard scenarios","description":"Create a benchmark runner script (bench/run_benchmarks.sh) that runs standard benchmark scenarios:\n1. Minimal GET (/ping) - pure overhead measurement\n2. Small payload (1KB) - typical API response\n3. Medium payload (10KB) - larger JSON responses  \n4. Large payload (100KB) - file downloads\n5. POST with body - request body handling\n6. Varying concurrency (1, 10, 50, 100, 200 connections)\n7. HTTP/1.1 vs HTTP/2 comparison\n\nOutput results to bench/results/ with timestamps for tracking over time.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-29T18:04:02.294539956+01:00","updated_at":"2025-12-29T18:17:10.742622288+01:00","closed_at":"2025-12-29T18:17:10.742622288+01:00","dependencies":[{"issue_id":"hcs-hkf","depends_on_id":"hcs-jtz","type":"parent-child","created_at":"2025-12-29T18:04:24.660841757+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-hkf","depends_on_id":"hcs-4w8","type":"blocks","created_at":"2025-12-29T18:04:36.967445707+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-hkf","depends_on_id":"hcs-320","type":"blocks","created_at":"2025-12-29T18:04:38.425355179+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-i4f","title":"Setup bench/ directory structure with .gitignore","description":"","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-30T22:21:21.51511238+01:00","updated_at":"2025-12-30T22:23:03.029513364+01:00","closed_at":"2025-12-30T22:23:03.029513364+01:00"}
+{"id":"hcs-i8j","title":"Implement OCaml/HCS benchmark server (plaintext + json, HTTP/1+2, CPU scaling)","description":"","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-30T22:21:36.638072425+01:00","updated_at":"2025-12-30T22:28:28.339092129+01:00","closed_at":"2025-12-30T22:28:28.339092129+01:00"}
+{"id":"hcs-j2z","title":"Implement unified Client module (Eio)","description":"Implement unified client API in hcs-eio/client.ml:\n\n```ocaml\ntype t\n\nval create :\n  sw:Eio.Switch.t -\u003e\n  net:Eio.Net.t -\u003e\n  clock:Eio.Time.clock -\u003e\n  ?config:config -\u003e\n  unit -\u003e\n  t\n\nval request : ?cancel:Cancel.t -\u003e t -\u003e request -\u003e (response, error) result\nval fetch : ?cancel:Cancel.t -\u003e t -\u003e request -\u003e (status * Headers.t * string, error) result\nval stream : ?cancel:Cancel.t -\u003e t -\u003e request -\u003e (status * Headers.t * Cstruct.t Stream.t, error) result\n\nval close_idle : t -\u003e unit\nval pool_stats : t -\u003e { active: int; idle: int; total: int }\n```\n\nFeatures:\n- Protocol selection (HTTP/1.1 vs HTTP/2) via ALPN or config\n- Connection pooling\n- Automatic redirect following\n- Compression handling\n- TLS with system certs by default","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-29T14:31:27.67982735+01:00","updated_at":"2025-12-29T17:00:20.730823454+01:00","closed_at":"2025-12-29T17:00:20.730823454+01:00","dependencies":[{"issue_id":"hcs-j2z","depends_on_id":"hcs-qnb","type":"parent-child","created_at":"2025-12-29T14:31:51.749045471+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-j2z","depends_on_id":"hcs-7n9","type":"blocks","created_at":"2025-12-29T14:31:54.365652586+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-j2z","depends_on_id":"hcs-d5s","type":"blocks","created_at":"2025-12-29T14:31:55.246269371+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-j2z","depends_on_id":"hcs-2ca","type":"blocks","created_at":"2025-12-29T14:31:55.835151512+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-j5q","title":"Move Go benchmark server to dedicated folder (bench/comparison/go_fasthttp/)","description":"","status":"closed","priority":2,"issue_type":"chore","created_at":"2025-12-30T00:14:15.760072799+01:00","updated_at":"2025-12-30T00:17:18.571463212+01:00","closed_at":"2025-12-30T00:17:18.571463212+01:00"}
+{"id":"hcs-j7j","title":"Implement Go/fasthttp benchmark server (plaintext + json, HTTP/1+2, CPU scaling)","description":"","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-30T22:21:31.597229058+01:00","updated_at":"2025-12-30T22:28:28.338758567+01:00","closed_at":"2025-12-30T22:28:28.338758567+01:00"}
+{"id":"hcs-jk8","title":"WebSocket Benchmark: Memory and Connection Scaling","description":"Compare HCS (OCaml) vs Go vs Rust WebSocket implementations. Metrics: memory per connection, max connections per CPU.","status":"closed","priority":2,"issue_type":"epic","created_at":"2025-12-30T09:59:44.349580383+01:00","updated_at":"2025-12-30T10:23:00.707208406+01:00","closed_at":"2025-12-30T10:23:00.707208406+01:00"}
+{"id":"hcs-jqx","title":"Cache :path header extraction in request_handler","description":"H2.Headers.get is O(n). For the :path pseudo-header which is always present and accessed for every request, consider direct access or caching.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-30T08:57:26.215703677+01:00","updated_at":"2025-12-30T09:01:43.754321197+01:00","closed_at":"2025-12-30T09:01:43.754321197+01:00","dependencies":[{"issue_id":"hcs-jqx","depends_on_id":"hcs-cq4","type":"parent-child","created_at":"2025-12-30T08:57:49.840282561+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-jsl","title":"Implement Path DSL","description":"Implement type-safe path DSL in hcs-core/path.ml:\n\n```ocaml\ntype 'a t\n\n(* Combinators *)\nval root : unit t                     (* / *)\nval const : string -\u003e unit t          (* /literal *)\nval str : string t                    (* /:param - captures string *)\nval int : int t                       (* /:param - captures int *)\nval int32 : int32 t\nval int64 : int64 t\nval uuid : string t                   (* validates UUID format *)\nval rest : string list t              (* /** - captures remaining *)\n\nval ( / ) : 'a t -\u003e 'b t -\u003e ('a * 'b) t\nval ( /: ) : unit t -\u003e 'a t -\u003e 'a t   (* const / capture shorthand *)\n\nval trailing_slash : 'a t -\u003e 'a t\n\n(* For router compilation *)\ntype segment =\n  | Literal of string\n  | Param_string\n  | Param_int\n  | Param_int32\n  | Param_int64  \n  | Param_uuid\n  | Wildcard\n\nval to_segments : 'a t -\u003e segment list\nval parse : 'a t -\u003e string list -\u003e ('a, string) result\n```\n\nPure OCaml, uses GADTs for type safety.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-29T14:32:24.842727479+01:00","updated_at":"2025-12-29T14:56:33.544162475+01:00","closed_at":"2025-12-29T14:56:33.544162475+01:00","dependencies":[{"issue_id":"hcs-jsl","depends_on_id":"hcs-2ie","type":"parent-child","created_at":"2025-12-29T14:32:55.556666992+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-jtz","title":"Benchmark Suite for HCS HTTP Library","description":"Create a comprehensive benchmark suite to measure HCS HTTP library performance. Focus on requests/second for both HTTP/1.1 and HTTP/2, comparing client and server performance under various conditions.","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-29T18:03:37.371206713+01:00","updated_at":"2025-12-29T18:18:17.12058364+01:00","closed_at":"2025-12-29T18:18:17.12058364+01:00"}
+{"id":"hcs-k8f","title":"Implement multi-domain server run functions","description":"Create run_parallel and run_parallel_opt functions that spawn N domains, each with their own accept loop using SO_REUSEPORT.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-30T09:05:54.711085855+01:00","updated_at":"2025-12-30T09:10:52.550223218+01:00","closed_at":"2025-12-30T09:10:52.550223218+01:00","dependencies":[{"issue_id":"hcs-k8f","depends_on_id":"hcs-zq3","type":"parent-child","created_at":"2025-12-30T09:06:19.149511092+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-k8f","depends_on_id":"hcs-cxj","type":"blocks","created_at":"2025-12-30T09:06:34.264044099+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-kfm","title":"Set up property-based testing for parsers","description":"Use property-based testing (QCheck or Crowbar) for parsers and router:\n\n1. **HTTP/1.1 parser properties:**\n   - parse(serialize(request)) = request (roundtrip)\n   - parse partial input = Incomplete\n   - parse garbage = Error (no crashes)\n   - parse valid + garbage = Complete with correct consumed bytes\n\n2. **Router properties:**\n   - All registered routes are matchable\n   - More specific routes match before less specific\n   - No path matches multiple routes (deterministic)\n   - Captured params have correct types\n\n3. **Headers properties:**\n   - Case-insensitive lookup\n   - add then find = Some value\n   - remove then find = None\n   - of_list(to_list(h)) preserves all values\n\n4. **WebSocket frame properties:**\n   - parse(serialize(frame)) = frame\n   - Masked frames unmask correctly\n   - Fragmented messages reassemble correctly\n\nAdd to dune test configuration with reasonable iteration counts.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-29T14:36:30.160273757+01:00","updated_at":"2025-12-29T17:52:17.694190669+01:00","closed_at":"2025-12-29T17:52:17.694190669+01:00","dependencies":[{"issue_id":"hcs-kfm","depends_on_id":"hcs-0zq","type":"parent-child","created_at":"2025-12-29T14:36:52.71433591+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-kfm","depends_on_id":"hcs-8zr","type":"blocks","created_at":"2025-12-29T14:37:00.796778902+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-kfm","depends_on_id":"hcs-sny","type":"blocks","created_at":"2025-12-29T14:37:01.737277561+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-kg1","title":"Implement connection pool","description":"Implement connection pooling with runtime abstraction:\n\nhcs-core/pool.ml (data structures):\n```ocaml\ntype key = { host: string; port: int; is_tls: bool }\ntype 'conn entry = { conn: 'conn; last_used: float; created: float }\ntype 'conn t\n\nval create : max_per_host:int -\u003e max_total:int -\u003e 'conn t\nval get : 'conn t -\u003e key -\u003e 'conn entry option\nval put : 'conn t -\u003e key -\u003e 'conn -\u003e now:float -\u003e unit\nval remove : 'conn t -\u003e key -\u003e 'conn -\u003e unit\nval close_idle : 'conn t -\u003e older_than:float -\u003e 'conn list\nval stats : 'conn t -\u003e { active: int; idle: int; total: int }\n```\n\nhcs-eio/pool.ml (Eio-specific):\n```ocaml\nmodule Eio_pool : sig\n  type t\n  val create : config:Client.config -\u003e t\n  val acquire : t -\u003e key -\u003e (Eio.Flow.two_way, error) result\n  val release : t -\u003e key -\u003e Eio.Flow.two_way -\u003e unit\n  val with_connection : t -\u003e key -\u003e (Eio.Flow.two_way -\u003e 'a) -\u003e ('a, error) result\nend\n```\n\nUse LRU eviction, health checks on reuse.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-29T14:31:11.052080452+01:00","updated_at":"2025-12-29T15:18:04.471112737+01:00","closed_at":"2025-12-29T15:18:04.471112737+01:00","dependencies":[{"issue_id":"hcs-kg1","depends_on_id":"hcs-qnb","type":"parent-child","created_at":"2025-12-29T14:31:44.252516545+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-l23","title":"HTTP Client DSL","description":"Implement the Http module with request builder DSL for fluent API including headers, query params, body, and codec integration.","status":"closed","priority":2,"issue_type":"epic","created_at":"2025-12-29T14:25:29.533679497+01:00","updated_at":"2025-12-29T17:40:50.224704889+01:00","closed_at":"2025-12-29T17:40:50.224704889+01:00","dependencies":[{"issue_id":"hcs-l23","depends_on_id":"hcs-zba","type":"parent-child","created_at":"2025-12-29T14:26:13.135112824+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-l9p","title":"Create Go HTTP/2 benchmark server (net/http)","description":"Implement a Go HTTP/2 server using net/http with h2c support. Match endpoints: /ping, /bytes/:n, /json. Use golang.org/x/net/http2/h2c for cleartext HTTP/2. Pre-allocate response buffers.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-30T08:21:53.967258404+01:00","updated_at":"2025-12-30T08:48:32.173036222+01:00","closed_at":"2025-12-30T08:48:32.173036222+01:00","dependencies":[{"issue_id":"hcs-l9p","depends_on_id":"hcs-82y","type":"parent-child","created_at":"2025-12-30T08:22:23.072848194+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-lhr","title":"WebSocket Support","description":"Implement Ws module with frame types, connection management, send/recv operations, server upgrade handler, and client connect.","status":"closed","priority":2,"issue_type":"epic","created_at":"2025-12-29T14:25:36.29066838+01:00","updated_at":"2025-12-29T16:01:05.272490486+01:00","closed_at":"2025-12-29T16:01:05.272490486+01:00","dependencies":[{"issue_id":"hcs-lhr","depends_on_id":"hcs-zba","type":"parent-child","created_at":"2025-12-29T14:26:20.036599039+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-llr","title":"Implement Rust/hyper benchmark server (plaintext + json, HTTP/1+2, CPU scaling)","description":"","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-30T22:21:26.556966252+01:00","updated_at":"2025-12-30T22:28:28.337697653+01:00","closed_at":"2025-12-30T22:28:28.337697653+01:00"}
+{"id":"hcs-lpr","title":"Implement request and response record types","description":"Implement request and response records in types.ml:\n\n```ocaml\ntype request = {\n  meth : method_;\n  uri : Uri.t;\n  version : version;\n  headers : Headers.t;\n  body : body;\n}\n\ntype response = {\n  status : status;\n  version : version;\n  headers : Headers.t;\n  body : body;\n}\n```\n\nInclude smart constructors and accessors. Pure OCaml + uri package.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-29T14:27:19.295375903+01:00","updated_at":"2025-12-29T14:50:46.801981182+01:00","closed_at":"2025-12-29T14:50:46.801981182+01:00","labels":["core"],"dependencies":[{"issue_id":"hcs-lpr","depends_on_id":"hcs-ugs","type":"blocks","created_at":"2025-12-29T14:27:19.300960037+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-lpr","depends_on_id":"hcs-6yl","type":"blocks","created_at":"2025-12-29T14:27:43.920564401+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-lpr","depends_on_id":"hcs-cmg","type":"blocks","created_at":"2025-12-29T14:27:44.815114113+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-lpr","depends_on_id":"hcs-cks","type":"blocks","created_at":"2025-12-29T14:27:45.656483969+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-lpr","depends_on_id":"hcs-chm","type":"blocks","created_at":"2025-12-29T14:27:46.481924426+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-lqi","title":"Implement HTTP/1.1 server (Eio)","description":"Implement HTTP/1.1 server for Eio in hcs-eio/h1_server.ml:\n\n```ocaml\nval handle_connection :\n  flow:Eio.Flow.two_way -\u003e\n  clock:Eio.Time.clock -\u003e\n  config:Server.config -\u003e\n  handler:(request -\u003e (response, error) result) -\u003e\n  unit\n```\n\nFeatures:\n- Parse requests using h1 parser\n- Handle keep-alive connections\n- Support chunked and fixed-length bodies\n- Respect timeouts\n- Handle pipelining (optional)\n- Integrate with logging","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-29T14:33:22.560229088+01:00","updated_at":"2025-12-29T15:03:24.765221644+01:00","closed_at":"2025-12-29T15:03:24.765221644+01:00","dependencies":[{"issue_id":"hcs-lqi","depends_on_id":"hcs-rw6","type":"parent-child","created_at":"2025-12-29T14:33:42.102983428+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-lqi","depends_on_id":"hcs-56z","type":"blocks","created_at":"2025-12-29T14:33:44.325287786+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-m4r","title":"Codec System","description":"Implement the functor-based CODEC signature and With_codec functor for type-safe serialization/deserialization. Use Cstruct.t (buffers) instead of strings to properly support binary formats like MessagePack, Protobuf, and CBOR.","status":"closed","priority":2,"issue_type":"epic","created_at":"2025-12-29T14:25:22.203715886+01:00","updated_at":"2025-12-29T17:40:46.982752973+01:00","closed_at":"2025-12-29T17:40:46.982752973+01:00","dependencies":[{"issue_id":"hcs-m4r","depends_on_id":"hcs-zba","type":"parent-child","created_at":"2025-12-29T14:26:00.496780385+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-mip","title":"Implement Http request builder DSL","description":"Implement high-level client DSL in hcs-core/http.ml:\n\n```ocaml\ntype builder\n\nval get : string -\u003e (builder, error) result\nval post : string -\u003e (builder, error) result\nval put : string -\u003e (builder, error) result\nval delete : string -\u003e (builder, error) result\n(* ... other methods ... *)\n\nval of_uri : method_ -\u003e Uri.t -\u003e builder\n\n(* Headers *)\nval header : string -\u003e string -\u003e builder -\u003e builder\nval headers : (string * string) list -\u003e builder -\u003e builder\nval content_type : string -\u003e builder -\u003e builder\nval accept : string -\u003e builder -\u003e builder\nval bearer : string -\u003e builder -\u003e builder\nval basic_auth : user:string -\u003e pass:string -\u003e builder -\u003e builder\nval user_agent : string -\u003e builder -\u003e builder\n\n(* Query parameters *)\nval query : string -\u003e string -\u003e builder -\u003e builder\nval queries : (string * string) list -\u003e builder -\u003e builder\n\n(* Body *)\nval body : body -\u003e builder -\u003e builder\nval body_string : ?content_type:string -\u003e string -\u003e builder -\u003e builder\nval form : (string * string) list -\u003e builder -\u003e builder\n\n(* Build final request *)\nval build : builder -\u003e request\n```\n\nPure OCaml, no IO.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-29T14:34:22.698743046+01:00","updated_at":"2025-12-29T17:10:04.149286655+01:00","closed_at":"2025-12-29T17:10:04.149286655+01:00","dependencies":[{"issue_id":"hcs-mip","depends_on_id":"hcs-l23","type":"parent-child","created_at":"2025-12-29T14:34:49.5612417+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-mip","depends_on_id":"hcs-lpr","type":"blocks","created_at":"2025-12-29T14:34:56.47577088+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-mli","title":"Run multi-CPU benchmarks (4, 8, 16 CPUs)","description":"Run benchmarks with 4, 8, and 16 domains for HCS, compare with Rust and Go multi-threaded.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-30T09:05:59.450548339+01:00","updated_at":"2025-12-30T09:16:49.37792589+01:00","closed_at":"2025-12-30T09:16:49.37792589+01:00","dependencies":[{"issue_id":"hcs-mli","depends_on_id":"hcs-zq3","type":"parent-child","created_at":"2025-12-30T09:06:29.226366436+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-mli","depends_on_id":"hcs-zln","type":"blocks","created_at":"2025-12-30T09:06:44.348550935+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-nad","title":"Implement WebSocket connection (Eio)","description":"Implement WebSocket for Eio in hcs-eio/websocket.ml:\n\n```ocaml\ntype conn\n\nval is_open : conn -\u003e bool\n\n(* Receive *)\nval recv : conn -\u003e (frame option, error) result\nval recv_timeout : Eio.Time.clock -\u003e float -\u003e conn -\u003e (frame option, error) result\n\n(* Send *)\nval send : conn -\u003e frame -\u003e (unit, error) result\nval close : ?code:int -\u003e ?reason:string -\u003e conn -\u003e (unit, error) result\n\n(* Stream interface *)\nval recv_stream : conn -\u003e frame Stream.t\nval send_stream : conn -\u003e frame Stream.t -\u003e (unit, error) result\n\n(* Server: upgrade handler *)\nval upgrade :\n  ?protocols:string list -\u003e\n  ?on_close:(int option -\u003e string option -\u003e unit) -\u003e\n  (conn -\u003e (unit, error) result) -\u003e\n  unit handler\n\n(* Client: connect *)\nval connect :\n  sw:Eio.Switch.t -\u003e\n  net:Eio.Net.t -\u003e\n  clock:Eio.Time.clock -\u003e\n  ?tls:Tls_config.client -\u003e\n  ?headers:Headers.t -\u003e\n  ?protocols:string list -\u003e\n  string -\u003e\n  (conn, error) result\n```","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-29T14:34:33.686889707+01:00","updated_at":"2025-12-29T16:00:45.086724651+01:00","closed_at":"2025-12-29T16:00:45.086724651+01:00","dependencies":[{"issue_id":"hcs-nad","depends_on_id":"hcs-lhr","type":"parent-child","created_at":"2025-12-29T14:34:52.929848888+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-nad","depends_on_id":"hcs-0ro","type":"blocks","created_at":"2025-12-29T14:34:58.053806421+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-njk","title":"Run HTTP/2 comparison benchmarks and analyze results","description":"Execute the HTTP/2 benchmarks across all three implementations. Collect req/s, latency (p50/p99), memory usage. Document results in BENCHMARKS.md with analysis of performance characteristics.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-30T08:21:59.417171367+01:00","updated_at":"2025-12-30T08:48:51.035410704+01:00","closed_at":"2025-12-30T08:48:51.035410704+01:00","dependencies":[{"issue_id":"hcs-njk","depends_on_id":"hcs-ddd","type":"blocks","created_at":"2025-12-30T08:22:17.716250574+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-njk","depends_on_id":"hcs-82y","type":"parent-child","created_at":"2025-12-30T08:22:28.307104582+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-oo5","title":"Benchmark suite: single-CPU comparison of HCS, hyper, fasthttp","description":"","notes":"## Benchmark Results (Dec 31, 2025)\n\n### HCS vs Eio Native (c=1000, 100k requests)\n\n| Domains | HCS run_parallel | Eio run_server | Winner |\n|---------|------------------|----------------|--------|\n| 1 | 142k | 136k | HCS +4% |\n| 2 | 196k | 200k | Eio +2% |\n| 4 | 264k | 259k | HCS +2% |\n| 8 | 259k | 267k | Eio +3% |\n\n**Key Finding**: Both approaches perform similarly. The 2-domain regression previously observed was a measurement artifact.\n\n### HCS vs Fasthttp (c=1000, 100k requests)\n\n| Domains | HCS | Fasthttp | Winner |\n|---------|-----|----------|--------|\n| 1 | 137k | 181k | Fasthttp +32% |\n| 4 | 242k | 186k | **HCS +30%** |\n| 8 | 228k | 204k | **HCS +12%** |\n\n**Key Finding**: HCS scales BETTER than Fasthttp and beats it at 4+ domains!\n\n### Conclusions\n\n1. The nested `Eio_main.run` is NOT a problem - Eio's Domain_manager.run does the same thing internally\n2. SO_REUSEPORT (HCS) vs shared socket (Eio native) perform similarly - no clear winner\n3. HCS multi-core scaling is actually quite good - beats Fasthttp at higher core counts\n4. Earlier \"2-domain regression\" was likely a measurement artifact (port reuse, warmup, etc.)\n\n### Remaining Optimization Opportunities\n\n1. Single-core performance still lags Fasthttp by ~32% - room for improvement in request parsing/response writing\n2. 8-domain shows slight regression from 4-domain for HCS - could investigate GC tuning\n3. Hyper benchmark failed to run - need to fix for comparison","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-30T22:41:13.187711389+01:00","updated_at":"2025-12-31T09:33:51.051037492+01:00","closed_at":"2025-12-31T09:33:51.051037492+01:00"}
+{"id":"hcs-osg","title":"Create Rust HTTP/2 benchmark server (hyper)","description":"Implement a Rust HTTP/2 server using hyper with h2c (cleartext HTTP/2) support. Match endpoints: /ping, /bytes/:n, /json. Use tokio runtime, pre-allocate response buffers for zero-copy.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-30T08:21:52.194368992+01:00","updated_at":"2025-12-30T08:48:32.166538953+01:00","closed_at":"2025-12-30T08:48:32.166538953+01:00","dependencies":[{"issue_id":"hcs-osg","depends_on_id":"hcs-82y","type":"parent-child","created_at":"2025-12-30T08:22:20.416305094+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-peu","title":"HCS benchmark client: HTTP/1.1 + HTTP/2 + WebSocket support","description":"Create comprehensive benchmark client supporting all protocols with connection reuse, multiplexing, and WebSocket message throughput.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-31T14:13:46.273123556+01:00","updated_at":"2025-12-31T14:37:50.862757453+01:00","closed_at":"2025-12-31T14:37:50.862757453+01:00","dependencies":[{"issue_id":"hcs-peu","depends_on_id":"hcs-5wp","type":"parent-child","created_at":"2025-12-31T14:14:41.0222415+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-pnc","title":"Control Flow and Cancellation","description":"Implement Cancel module for cooperative cancellation and Control module for timeout, retry, deadline, and circuit breaker patterns.","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-29T14:25:23.840150584+01:00","updated_at":"2025-12-29T15:41:49.225247023+01:00","closed_at":"2025-12-29T15:41:49.225247023+01:00","dependencies":[{"issue_id":"hcs-pnc","depends_on_id":"hcs-zba","type":"parent-child","created_at":"2025-12-29T14:26:03.266144948+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-pwc","title":"Implement CODEC module signature","description":"Implement the CODEC module signature in hcs-core/codec.ml using buffers:\n\n```ocaml\nmodule type CODEC = sig\n  type 'a encoder\n  type 'a decoder\n\n  val content_type : string  (* e.g., \"application/json\", \"application/msgpack\" *)\n\n  (* Use Cstruct.t for buffer-based encoding/decoding *)\n  val encode : 'a encoder -\u003e 'a -\u003e (Cstruct.t, string) result\n  val decode : 'a decoder -\u003e Cstruct.t -\u003e ('a, string) result\n  \n  (* Optional: streaming encode/decode for large payloads *)\n  val encode_stream : 'a encoder -\u003e 'a -\u003e Cstruct.t Stream.t option\n  val decode_stream : 'a decoder -\u003e Cstruct.t Stream.t -\u003e ('a, string) result option\nend\n```\n\nBenefits of buffer-based approach:\n- Zero-copy for binary formats (msgpack, protobuf, cbor)\n- Efficient for large payloads\n- Can still handle text formats (JSON) by converting at boundaries\n- Consistent with body type which uses Cstruct.t for streaming\n\nPure OCaml + cstruct, no runtime dependency.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-29T14:28:42.177976816+01:00","updated_at":"2025-12-29T17:04:22.669690697+01:00","closed_at":"2025-12-29T17:04:22.669690697+01:00","labels":["core"],"dependencies":[{"issue_id":"hcs-pwc","depends_on_id":"hcs-m4r","type":"parent-child","created_at":"2025-12-29T14:28:59.747767828+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-pwc","depends_on_id":"hcs-23f","type":"blocks","created_at":"2025-12-29T14:29:04.083986956+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-qf7","title":"Implement radix trie for routing","description":"Implement radix trie in hcs-core/trie.ml:\n\n```ocaml\ntype 'a t\n\nval empty : 'a t\nval insert : Path.segment list -\u003e method_ -\u003e 'a -\u003e 'a t -\u003e 'a t\nval lookup : string list -\u003e method_ -\u003e 'a t -\u003e ('a * string list, string) result\n  (* Returns handler and captured params *)\n\nval compile : 'a t -\u003e 'a t  (* Optimize: compress edges, sort by priority *)\n```\n\nImplementation notes:\n- Radix trie with compressed edges for static segments\n- Parameter nodes stored separately for O(1) lookup\n- Method dispatch at leaf nodes (small array)\n- Priority: static \u003e typed param \u003e string param \u003e wildcard\n- Pre-compile regex for uuid validation\n\nPure OCaml, O(path_length) lookup.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-29T14:32:37.659665672+01:00","updated_at":"2025-12-29T15:18:02.267050922+01:00","closed_at":"2025-12-29T15:18:02.267050922+01:00","dependencies":[{"issue_id":"hcs-qf7","depends_on_id":"hcs-2ie","type":"parent-child","created_at":"2025-12-29T14:32:56.840281975+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-qf7","depends_on_id":"hcs-jsl","type":"blocks","created_at":"2025-12-29T14:32:57.708007508+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-qnb","title":"HTTP Client Implementation","description":"Implement the Client module with connection pooling, HTTP/1.1 and HTTP/2 support, request/fetch/stream methods, and configuration.","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-29T14:25:28.006219271+01:00","updated_at":"2025-12-29T17:41:34.620441464+01:00","closed_at":"2025-12-29T17:41:34.620441464+01:00","dependencies":[{"issue_id":"hcs-qnb","depends_on_id":"hcs-zba","type":"parent-child","created_at":"2025-12-29T14:26:11.475056322+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-rw6","title":"HTTP Server Implementation","description":"Implement Server module with HTTP/1.1 and HTTP/2 support, configuration, graceful shutdown, and connection management.","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-29T14:25:32.173329865+01:00","updated_at":"2025-12-29T17:41:35.435456001+01:00","closed_at":"2025-12-29T17:41:35.435456001+01:00","dependencies":[{"issue_id":"hcs-rw6","depends_on_id":"hcs-zba","type":"parent-child","created_at":"2025-12-29T14:26:17.069517446+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-rzc","title":"HCS: Unified server with HTTP/1.1 + h2c upgrade + WebSocket","description":"Create single HCS server that detects protocol and routes to H1/H2/WS handlers. Support h2c upgrade from HTTP/1.1.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-31T14:13:31.15150333+01:00","updated_at":"2025-12-31T14:24:25.878899607+01:00","closed_at":"2025-12-31T14:24:25.878899607+01:00","dependencies":[{"issue_id":"hcs-rzc","depends_on_id":"hcs-5wp","type":"parent-child","created_at":"2025-12-31T14:14:25.89281292+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-s3a","title":"Implement runtime-specific middleware (Eio)","description":"Implement Eio-specific middleware in hcs-eio/middleware.ml:\n\n```ocaml\n(* Logging - needs clock for timing *)\nval logging : Eio.Time.clock -\u003e Log.logger -\u003e middleware\n\n(* Timeout *)\nval timeout : Eio.Time.clock -\u003e float -\u003e middleware\n\n(* Rate limiting - needs clock and mutable state *)\nval rate_limit :\n  clock:Eio.Time.clock -\u003e\n  key:(request -\u003e string) -\u003e\n  requests:int -\u003e\n  per:float -\u003e\n  middleware\n\n(* Compression - CPU bound but may benefit from async *)\nval compress : ?level:int -\u003e ?min_size:int -\u003e unit -\u003e middleware\nval decompress : middleware\n\n(* Static files - needs filesystem *)\nval static :\n  fs:Eio.Fs.dir_ty Eio.Path.t -\u003e\n  ?index:string list -\u003e\n  ?etag:bool -\u003e\n  string -\u003e\n  middleware\n\n(* ETag generation *)\nval etag : middleware\nval cache_control : string -\u003e middleware\n```","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-29T14:34:31.955254986+01:00","updated_at":"2025-12-29T17:14:15.252061602+01:00","closed_at":"2025-12-29T17:14:15.252061602+01:00","dependencies":[{"issue_id":"hcs-s3a","depends_on_id":"hcs-3ww","type":"parent-child","created_at":"2025-12-29T14:34:51.261233247+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-s3a","depends_on_id":"hcs-bea","type":"blocks","created_at":"2025-12-29T14:34:57.261423006+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-s94","title":"Rust: Unified Hyper server with HTTP/1.1 + h2c + WebSocket","description":"Update Hyper server to handle HTTP/1.1, h2c, and WebSocket on single port.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-31T14:13:41.231763861+01:00","updated_at":"2025-12-31T14:31:18.83450995+01:00","closed_at":"2025-12-31T14:31:18.83450995+01:00","dependencies":[{"issue_id":"hcs-s94","depends_on_id":"hcs-5wp","type":"parent-child","created_at":"2025-12-31T14:14:35.978086083+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-sny","title":"Implement Router module","description":"Implement router API in hcs-core/router.ml:\n\n```ocaml\ntype 'a handler = 'a -\u003e request -\u003e (response, error) result\ntype middleware = (request -\u003e (response, error) result) -\u003e request -\u003e (response, error) result\n\ntype t\n\n(* Route registration *)\nval get : 'a Path.t -\u003e 'a handler -\u003e t\nval post : 'a Path.t -\u003e 'a handler -\u003e t\nval put : 'a Path.t -\u003e 'a handler -\u003e t\nval delete : 'a Path.t -\u003e 'a handler -\u003e t\nval patch : 'a Path.t -\u003e 'a handler -\u003e t\nval head : 'a Path.t -\u003e 'a handler -\u003e t\nval options : 'a Path.t -\u003e 'a handler -\u003e t\nval any : method_ list -\u003e 'a Path.t -\u003e 'a handler -\u003e t\n\n(* Composition *)\nval routes : t list -\u003e t\nval scope : string -\u003e t list -\u003e t\nval scope_with : string -\u003e middleware list -\u003e t list -\u003e t\nval with_middleware : middleware list -\u003e t -\u003e t\n\n(* Compilation *)\ntype compiled\nval compile : t -\u003e compiled\nval match_ : compiled -\u003e request -\u003e (response, error) result\n```\n\nPure OCaml, builds on Path and Trie.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-29T14:32:43.527248631+01:00","updated_at":"2025-12-29T15:18:03.419090442+01:00","closed_at":"2025-12-29T15:18:03.419090442+01:00","dependencies":[{"issue_id":"hcs-sny","depends_on_id":"hcs-2ie","type":"parent-child","created_at":"2025-12-29T14:32:57.378211329+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-sny","depends_on_id":"hcs-qf7","type":"blocks","created_at":"2025-12-29T14:32:58.327421433+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-sny","depends_on_id":"hcs-lpr","type":"blocks","created_at":"2025-12-29T14:32:59.27491603+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-tn3","title":"Run WebSocket benchmarks and collect results","description":"Execute the benchmark suite, collect memory and connection data, document findings.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-30T10:00:04.76879529+01:00","updated_at":"2025-12-30T10:22:46.346637622+01:00","closed_at":"2025-12-30T10:22:46.346637622+01:00","dependencies":[{"issue_id":"hcs-tn3","depends_on_id":"hcs-jk8","type":"parent-child","created_at":"2025-12-30T10:00:50.758778716+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-tn3","depends_on_id":"hcs-wkv","type":"blocks","created_at":"2025-12-30T10:01:15.964007648+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-tzc","title":"Implement Server.config type","description":"Implement server configuration in hcs-core/server_config.ml:\n\n```ocaml\ntype config = {\n  host : string;                     (* default: \"0.0.0.0\" *)\n  port : int;                        (* default: 8080 *)\n  backlog : int;                     (* default: 2048 *)\n  max_connections : int;             (* default: 10000 *)\n\n  (* Timeouts *)\n  read_timeout : float;              (* default: 60.0 *)\n  write_timeout : float;             (* default: 60.0 *)\n  idle_timeout : float;              (* default: 120.0 *)\n  request_timeout : float;           (* default: 30.0 *)\n\n  (* Limits *)\n  max_header_size : int;             (* default: 8192 *)\n  max_body_size : int64 option;      (* None = unlimited *)\n\n  (* Protocol *)\n  http2 : bool;                      (* default: true *)\n  buffer_size : int;                 (* default: 16384 *)\n\n  (* TLS *)\n  tls : Tls_config.server option;\n\n  (* Compression *)\n  compress_response : bool;          (* default: true *)\n  compression_min_size : int;        (* default: 1024 *)\n  compression_level : int;           (* default: 6 *)\n\n  (* Logging *)\n  logger : Log.logger;\n}\n\nval default : config\n```\n\nPure configuration, no IO.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-29T14:33:15.561446445+01:00","updated_at":"2025-12-29T15:40:25.769211668+01:00","closed_at":"2025-12-29T15:40:25.769211668+01:00","dependencies":[{"issue_id":"hcs-tzc","depends_on_id":"hcs-rw6","type":"parent-child","created_at":"2025-12-29T14:33:40.219574299+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-ucw","title":"Implement Response helper module","description":"Implement response helpers in hcs-core/response.ml:\n\n```ocaml\nval make : ?version:version -\u003e ?headers:Headers.t -\u003e ?body:body -\u003e status -\u003e response\n\n(* Status shortcuts *)\nval ok : ?headers:Headers.t -\u003e body -\u003e response\nval created : ?headers:Headers.t -\u003e ?location:string -\u003e body -\u003e response\nval no_content : unit -\u003e response\nval bad_request : ?body:body -\u003e unit -\u003e response\nval unauthorized : ?www_authenticate:string -\u003e unit -\u003e response\nval forbidden : ?body:body -\u003e unit -\u003e response\nval not_found : ?body:body -\u003e unit -\u003e response\nval method_not_allowed : allowed:method_ list -\u003e unit -\u003e response\nval internal_error : ?body:body -\u003e unit -\u003e response\n(* ... all status helpers from spec ... *)\n\n(* Body helpers *)\nval text : string -\u003e response\nval html : string -\u003e response\nval redirect : ?permanent:bool -\u003e string -\u003e response\n\n(* Modify response *)\nval with_header : string -\u003e string -\u003e response -\u003e response\nval with_headers : (string * string) list -\u003e response -\u003e response\nval with_body : body -\u003e response -\u003e response\n```\n\nPure OCaml.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-29T14:34:17.870074295+01:00","updated_at":"2025-12-29T15:40:30.579234447+01:00","closed_at":"2025-12-29T15:40:30.579234447+01:00","dependencies":[{"issue_id":"hcs-ucw","depends_on_id":"hcs-dle","type":"parent-child","created_at":"2025-12-29T14:34:48.628725792+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-ucw","depends_on_id":"hcs-lpr","type":"blocks","created_at":"2025-12-29T14:34:55.629240942+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-ugs","title":"Core Types and Foundations","description":"Implement core type foundations: method_, version, status, Headers module, body type, request/response records, and error types.","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-29T14:25:19.301411166+01:00","updated_at":"2025-12-29T15:42:11.485073934+01:00","closed_at":"2025-12-29T15:42:11.485073934+01:00","dependencies":[{"issue_id":"hcs-ugs","depends_on_id":"hcs-zba","type":"parent-child","created_at":"2025-12-29T14:25:54.989012647+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-w1c","title":"Create HCS WebSocket benchmark server","description":"OCaml server using lib/websocket.ml. Accept connections, keep alive with ping/pong, report connection count. Port configurable via CLI.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-30T09:59:57.95619465+01:00","updated_at":"2025-12-30T10:03:58.03114584+01:00","closed_at":"2025-12-30T10:03:58.03114584+01:00","dependencies":[{"issue_id":"hcs-w1c","depends_on_id":"hcs-jk8","type":"parent-child","created_at":"2025-12-30T10:00:25.560665813+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-wkv","title":"Create WebSocket benchmark runner script","description":"Script like run_h2_comparison.sh. Start servers, run tests at 1k/10k/50k/100k connections, measure memory via /proc/[pid]/status VmRSS, report results.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-30T10:00:03.612055281+01:00","updated_at":"2025-12-30T10:14:42.952379356+01:00","closed_at":"2025-12-30T10:14:42.952379356+01:00","dependencies":[{"issue_id":"hcs-wkv","depends_on_id":"hcs-jk8","type":"parent-child","created_at":"2025-12-30T10:00:45.722495633+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-wkv","depends_on_id":"hcs-w1c","type":"blocks","created_at":"2025-12-30T10:00:55.80122372+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-wkv","depends_on_id":"hcs-1h7","type":"blocks","created_at":"2025-12-30T10:01:00.843226486+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-wkv","depends_on_id":"hcs-6ki","type":"blocks","created_at":"2025-12-30T10:01:05.885715216+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-wkv","depends_on_id":"hcs-6hx","type":"blocks","created_at":"2025-12-30T10:01:10.922318474+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-x1l","title":"Create benchmark runner script for standardized testing","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-30T22:21:46.718118939+01:00","updated_at":"2025-12-30T22:33:10.362379965+01:00","closed_at":"2025-12-30T22:33:10.362379965+01:00"}
+{"id":"hcs-y9w","title":"TLS Configuration","description":"Implement Tls_config module for client and server TLS configuration with verification modes and system certificate loading.","status":"closed","priority":2,"issue_type":"epic","created_at":"2025-12-29T14:25:24.911800471+01:00","updated_at":"2025-12-29T15:25:06.384359847+01:00","closed_at":"2025-12-29T15:25:06.384359847+01:00","dependencies":[{"issue_id":"hcs-y9w","depends_on_id":"hcs-zba","type":"parent-child","created_at":"2025-12-29T14:26:05.906211432+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-zba","title":"HCS HTTP Library Implementation","description":"Implement the hcs HTTP library for OCaml 5+ supporting HTTP/1.1, HTTP/2, and WebSockets. Built with a runtime-agnostic core to support Eio initially with Lwt support planned for the future. Features zero-copy streaming and minimal allocations.\n\nDesign Principle: The library should have a pure functional core with IO effects abstracted behind a runtime interface, allowing future Lwt integration without major rewrites.","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-29T14:25:07.01892354+01:00","updated_at":"2025-12-29T17:57:35.070502613+01:00","closed_at":"2025-12-29T17:57:35.070502613+01:00"}
+{"id":"hcs-zft","title":"Document CODEC implementation examples","description":"Document how users can implement their own CODEC for various formats. Include examples in documentation/comments showing the pattern:\n\n```ocaml\n(* Example: User implements JSON codec with their preferred library *)\nmodule My_json_codec : Hcs.CODEC = struct\n  type 'a encoder = 'a -\u003e Yojson.Safe.t  (* or Jsonm, Jsoo, etc. *)\n  type 'a decoder = Yojson.Safe.t -\u003e ('a, string) result\n  \n  let content_type = \"application/json\"\n  \n  let encode enc value =\n    try Ok (Cstruct.of_string (Yojson.Safe.to_string (enc value)))\n    with exn -\u003e Error (Printexc.to_string exn)\n    \n  let decode dec buf =\n    try \n      let json = Yojson.Safe.from_string (Cstruct.to_string buf) in\n      dec json\n    with exn -\u003e Error (Printexc.to_string exn)\n    \n  let encode_stream _ _ = None  (* Optional streaming *)\n  let decode_stream _ _ = None\nend\n\n(* Example: MessagePack codec *)\nmodule My_msgpack_codec : Hcs.CODEC = struct\n  (* Similar pattern with msgpck library *)\nend\n```\n\nThis is documentation only - no actual JSON library dependency in hcs. Users choose their own serialization libraries.","status":"closed","priority":3,"issue_type":"task","created_at":"2025-12-29T14:28:49.108715641+01:00","updated_at":"2025-12-29T17:32:45.942298931+01:00","closed_at":"2025-12-29T17:32:45.942298931+01:00","labels":["codec","optional"],"dependencies":[{"issue_id":"hcs-zft","depends_on_id":"hcs-m4r","type":"parent-child","created_at":"2025-12-29T14:29:01.540146453+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-zft","depends_on_id":"hcs-pwc","type":"blocks","created_at":"2025-12-29T14:29:03.003001157+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-zln","title":"Update benchmark server with --domains flag","description":"Add --domains N flag to bench_server_h2.exe to test with configurable domain count.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-30T09:05:56.907974106+01:00","updated_at":"2025-12-30T09:16:33.434469675+01:00","closed_at":"2025-12-30T09:16:33.434469675+01:00","dependencies":[{"issue_id":"hcs-zln","depends_on_id":"hcs-zq3","type":"parent-child","created_at":"2025-12-30T09:06:24.184829345+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-zln","depends_on_id":"hcs-k8f","type":"blocks","created_at":"2025-12-30T09:06:39.306344162+01:00","created_by":"gdiazlo"}]}
+{"id":"hcs-zq3","title":"Multi-CPU Support for HTTP/2 Server","description":"Add configurable multi-CPU support using Eio domain pools. Allow users to specify max CPU count.","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-30T09:04:59.162003477+01:00","updated_at":"2025-12-30T09:16:54.412371508+01:00","closed_at":"2025-12-30T09:16:54.412371508+01:00"}
+{"id":"hcs-zum","title":"Make zero-copy responses the default in high-level Server API","description":"","status":"closed","priority":1,"issue_type":"feature","created_at":"2025-12-30T00:14:13.733230476+01:00","updated_at":"2025-12-30T00:21:07.346540362+01:00","closed_at":"2025-12-30T00:21:07.346540362+01:00"}
+{"id":"hcs-zya","title":"Implement Control module","description":"Implement control flow combinators. Split into core (pure) and runtime-specific parts:\n\nhcs-core/control.ml (pure combinators):\n```ocaml\n(* Retry logic - pure, takes a \"sleep\" function *)\nval with_retry :\n  sleep:(float -\u003e unit) -\u003e\n  max_attempts:int -\u003e\n  backoff:(int -\u003e float) -\u003e\n  should_retry:(error -\u003e bool) -\u003e\n  (unit -\u003e ('a, error) result) -\u003e\n  ('a, error) result\n\n(* Circuit breaker state machine - pure *)\ntype circuit_state = Closed | Open of float | HalfOpen\ntype circuit_breaker\nval create_breaker : failure_threshold:int -\u003e reset_timeout:float -\u003e circuit_breaker\nval breaker_allow : circuit_breaker -\u003e now:float -\u003e bool\nval breaker_record_success : circuit_breaker -\u003e unit\nval breaker_record_failure : circuit_breaker -\u003e now:float -\u003e unit\n```\n\nRuntime-specific (hcs-eio/control.ml):\n```ocaml\nval with_timeout : Eio.Time.clock -\u003e float -\u003e (unit -\u003e ('a, error) result) -\u003e ('a, error) result\nval with_cancel : Cancel.t -\u003e (unit -\u003e ('a, error) result) -\u003e ('a, error) result\nval with_deadline : Eio.Time.clock -\u003e float -\u003e (unit -\u003e ('a, error) result) -\u003e ('a, error) result\n```","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-29T14:29:29.643574962+01:00","updated_at":"2025-12-29T15:18:05.295780311+01:00","closed_at":"2025-12-29T15:18:05.295780311+01:00","labels":["core"],"dependencies":[{"issue_id":"hcs-zya","depends_on_id":"hcs-pnc","type":"parent-child","created_at":"2025-12-29T14:30:10.213773459+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-zya","depends_on_id":"hcs-8br","type":"blocks","created_at":"2025-12-29T14:30:10.494720544+01:00","created_by":"gdiazlo"},{"issue_id":"hcs-zya","depends_on_id":"hcs-gmb","type":"blocks","created_at":"2025-12-29T14:30:10.704956596+01:00","created_by":"gdiazlo"}]}

.beads/metadata.json

···
+{
+  "database": "beads.db",
+  "jsonl_export": "issues.jsonl"
+}

.gitignore

···
+# OCaml compiled artifacts
+*.annot
+*.cmo
+*.cma
+*.cmi
+*.a
+*.o
+*.cmx
+*.cmxs
+*.cmxa
+*.cmt
+*.cmti
+*.byte
+*.native
+*.install
+
+# Build directories
+_build/
+_opam/
+
+# Editor/IDE
+.vscode/
+.idea/
+.merlin
+
+# Node.js
+node_modules/
+
+# OpenCode
+.opencode/
+
+# Beads
+.beads/*.log
+.beads/*.lock
+
+# Benchmark results and artifacts
+results/
+**/results/*.txt
+bench/certs/
+bench/fasthttp/
+bench/hcs/alloc_*.ml
+bench/nethttp/bench-nethttp
+perf.data
+perf*.data
+
+# Misc
+setup.data
+setup.log
+*.sh

.ocamlformat

···
+version = 0.28.1
+profile = default

LICENSE

···
+ISC License
+
+Copyright (c) 2026 Gabriel Díaz López de la Llave
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

README.md

···
+# hcs
+
+HTTP library for OCaml 5+ built on [Eio](https://github.com/ocaml-multicore/eio). Supports HTTP/1.1, HTTP/2, and WebSocket.
+
+## Modules
+
+| Module | Description |
+|--------|-------------|
+| [Client](lib/client.ml) | HTTP client with auto-protocol selection |
+| [Server](lib/server.ml) | HTTP server with multi-domain parallelism |
+| [Router](lib/router.ml) | Radix trie router with path parameters |
+| [Middleware](lib/middleware.ml) | Composable middleware |
+| [Middleware_eio](lib/middleware_eio.ml) | Eio-specific middleware (logging, timeout, rate limiting, static files) |
+| [Websocket](lib/websocket.ml) | WebSocket client and server (RFC 6455) |
+| [Pool](lib/pool.ml) | Connection pooling |
+| [Pooled_client](lib/pooled_client.ml) | Client with connection pooling |
+| [Control](lib/control.ml) | Retry, circuit breaker, backoff strategies |
+| [Stream](lib/stream.ml) | Sync and async streaming |
+| [Codec](lib/codec.ml) | Codec signature for serialization |
+| [Tls_config](lib/tls_config.ml) | TLS configuration |
+| [Log](lib/log.ml) | Structured logging |
+| [Request](lib/request.ml) | Request helpers |
+| [Response](lib/response.ml) | Response helpers |
+| [Http](lib/http.ml) | Request builder DSL |
+| [H1_client](lib/h1_client.ml) | HTTP/1.1 client |
+| [H2_client](lib/h2_client.ml) | HTTP/2 client |
+| [H1_server](lib/h1_server.ml) | HTTP/1.1 server |
+| [H2_server](lib/h2_server.ml) | HTTP/2 server |
+
+## CLI Tools
+
+### hc - HTTP Client
+
+```
+hc [OPTIONS] <URL>
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `-X, --request METHOD` | HTTP method (GET, POST, PUT, DELETE, etc.) |
+| `-H, --header "Name: Value"` | Add header (can be repeated) |
+| `-d, --data DATA` | Request body |
+| `-2, --http2` | Force HTTP/2 |
+| `-1, --http1` | Force HTTP/1.1 |
+| `-k, --insecure` | Skip TLS verification |
+| `-v, --verbose` | Show headers |
+| `-I, --head` | HEAD request only |
+| `-L, --location` | Follow redirects (default) |
+| `--no-location` | Don't follow redirects |
+| `-o, --output FILE` | Write to file |
+| `-w, --websocket` | WebSocket mode |
+| `--ws-message MSG` | Message to send in WebSocket mode |
+
+**Examples:**
+
+```bash
+# GET request
+hc https://httpbin.org/get
+
+# POST with data
+hc -d '{"key":"value"}' -H "Content-Type: application/json" https://httpbin.org/post
+
+# Force HTTP/2
+hc -2 https://nghttp2.org/httpbin/get
+
+# WebSocket
+hc -w wss://echo.websocket.org --ws-message "hello"
+
+# Download file
+hc -o image.png https://example.com/image.png
+```
+
+### hs - HTTP File Server
+
+```
+hs [OPTIONS] [DIRECTORY]
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `-p, --port PORT` | Port (default: 8080) |
+| `-b, --bind ADDRESS` | Bind address (default: 0.0.0.0) |
+| `-d, --domains N` | Worker domains (default: CPU count) |
+| `-1, --http1` | HTTP/1.1 only |
+| `-2, --http2` | HTTP/2 only |
+| `--index FILE` | Index file (default: index.html) |
+| `--no-index` | Disable index file |
+| `--list` | Enable directory listing |
+| `--cors` | Enable CORS headers |
+| `-v, --verbose` | Log requests |
+
+**Examples:**
+
+```bash
+# Serve current directory
+hs
+
+# Serve specific directory on port 3000
+hs -p 3000 ./public
+
+# With directory listing and CORS
+hs --list --cors ./dist
+
+# Verbose logging
+hs -v -p 8000 .
+```
+
+## Building
+
+```bash
+opam install . --deps-only
+dune build
+```
+
+## Running Tests
+
+```bash
+dune test
+```
+
+## Dependencies
+
+- [eio](https://github.com/ocaml-multicore/eio) - Structured concurrency
+- [h1](https://github.com/anmonteiro/http-protocols) - HTTP/1.1 parsing
+- [h2](https://github.com/anmonteiro/http-protocols) - HTTP/2 parsing
+- [tls-eio](https://github.com/mirleft/ocaml-tls) - TLS with Eio
+- [ca-certs](https://github.com/mirage/ca-certs) - System CA certificates
+- [uri](https://github.com/mirage/ocaml-uri) - URI parsing
+- [climate](https://github.com/gridbugs/climate) - CLI parsing

bench/.gitignore

···
+# Rust build artifacts
+hyper/target/
+
+# Go build artifacts
+fasthttp/bench-server
+
+# Results and logs
+results/
+*.log
+
+# Editor/IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS files
+.DS_Store
+Thumbs.db

bench/client/bench_client.ml

···
+module Stats = struct
+  type t = {
+    mutable total_requests : int;
+    mutable successful : int;
+    mutable failed : int;
+    latencies : float Queue.t;
+    start_time : float;
+    mutable end_time : float;
+  }
+
+  let create () =
+    {
+      total_requests = 0;
+      successful = 0;
+      failed = 0;
+      latencies = Queue.create ();
+      start_time = Unix.gettimeofday ();
+      end_time = 0.0;
+    }
+
+  let record_success stats latency_ms =
+    stats.total_requests <- stats.total_requests + 1;
+    stats.successful <- stats.successful + 1;
+    Queue.push latency_ms stats.latencies
+
+  let record_failure stats =
+    stats.total_requests <- stats.total_requests + 1;
+    stats.failed <- stats.failed + 1
+
+  let finish stats = stats.end_time <- Unix.gettimeofday ()
+
+  let percentile arr p =
+    let n = Array.length arr in
+    if n = 0 then 0.0
+    else
+      let idx = int_of_float (float_of_int (n - 1) *. p) in
+      arr.(idx)
+
+  let report stats ~json ~protocol =
+    finish stats;
+    let duration = stats.end_time -. stats.start_time in
+    let rps = float_of_int stats.successful /. duration in
+
+    let latencies = Queue.to_seq stats.latencies |> Array.of_seq in
+    Array.sort compare latencies;
+
+    let p50 = percentile latencies 0.50 in
+    let p90 = percentile latencies 0.90 in
+    let p99 = percentile latencies 0.99 in
+    let p999 = percentile latencies 0.999 in
+    let avg =
+      if Array.length latencies > 0 then
+        Array.fold_left ( +. ) 0.0 latencies
+        /. float_of_int (Array.length latencies)
+      else 0.0
+    in
+
+    if json then
+      Printf.printf
+        {|{"protocol":"%s","duration":%.2f,"total":%d,"successful":%d,"failed":%d,"rps":%.2f,"latency_avg":%.3f,"latency_p50":%.3f,"latency_p90":%.3f,"latency_p99":%.3f,"latency_p999":%.3f}
+|}
+        protocol duration stats.total_requests stats.successful stats.failed rps
+        avg p50 p90 p99 p999
+    else begin
+      Printf.printf "\n=== Benchmark Results (%s) ===\n" protocol;
+      Printf.printf "Duration:     %.2f seconds\n" duration;
+      Printf.printf "Requests:     %d total, %d successful, %d failed\n"
+        stats.total_requests stats.successful stats.failed;
+      Printf.printf "Throughput:   %.2f req/s\n" rps;
+      Printf.printf "\nLatency (ms):\n";
+      Printf.printf "  avg:        %.3f\n" avg;
+      Printf.printf "  p50:        %.3f\n" p50;
+      Printf.printf "  p90:        %.3f\n" p90;
+      Printf.printf "  p99:        %.3f\n" p99;
+      Printf.printf "  p99.9:      %.3f\n" p999
+    end
+end
+
+module H1_benchmark = struct
+  let worker ~sw ~net ~url ~stats ~stop_flag =
+    let uri = Uri.of_string url in
+    let host = Uri.host uri |> Option.value ~default:"localhost" in
+    let port = Uri.port uri |> Option.value ~default:8080 in
+    let path = Uri.path uri in
+    let path = if path = "" then "/" else path in
+
+    let request_line =
+      Printf.sprintf
+        "GET %s HTTP/1.1\r\nHost: %s\r\nConnection: keep-alive\r\n\r\n" path
+        host
+    in
+    let request_bytes = Bytes.of_string request_line in
+    let buf = Cstruct.create 4096 in
+    let addr = `Tcp (Eio.Net.Ipaddr.V4.loopback, port) in
+
+    try
+      let flow = Eio.Net.connect ~sw net addr in
+
+      while not !stop_flag do
+        let start = Unix.gettimeofday () in
+        try
+          Eio.Flow.write flow [ Cstruct.of_bytes request_bytes ];
+          let _ = Eio.Flow.single_read flow buf in
+          let elapsed = (Unix.gettimeofday () -. start) *. 1000.0 in
+          Stats.record_success stats elapsed
+        with _ -> Stats.record_failure stats
+      done;
+
+      Eio.Flow.close flow
+    with _ -> ()
+
+  let run ~net ~clock ~sw ~url ~concurrency ~duration ~json =
+    if not json then begin
+      Printf.printf "Benchmarking %s (HTTP/1.1)\n" url;
+      Printf.printf "Concurrency: %d, Duration: %d seconds\n%!" concurrency
+        duration
+    end;
+
+    let stats = Stats.create () in
+    let stop_flag = ref false in
+
+    for _ = 1 to concurrency do
+      Eio.Fiber.fork ~sw (fun () -> worker ~sw ~net ~url ~stats ~stop_flag)
+    done;
+
+    Eio.Time.sleep clock (float_of_int duration);
+    stop_flag := true;
+    Eio.Time.sleep clock 0.1;
+
+    Stats.report stats ~json ~protocol:"HTTP/1.1"
+end
+
+module Ws_benchmark = struct
+  let worker ~sw ~net ~url ~stats ~stop_flag ~msg_size =
+    let message = String.make msg_size 'x' in
+
+    match Hcs.Websocket.connect ~sw ~net url with
+    | Error e ->
+        let err_msg =
+          match e with
+          | Hcs.Websocket.Connection_closed -> "Connection closed"
+          | Hcs.Websocket.Protocol_error s -> "Protocol error: " ^ s
+          | Hcs.Websocket.Io_error s -> "IO error: " ^ s
+        in
+        Printf.eprintf "WebSocket connect error: %s\n%!" err_msg
+    | Ok ws ->
+        while not !stop_flag do
+          let start = Unix.gettimeofday () in
+          match Hcs.Websocket.send_text ws message with
+          | Error _ -> Stats.record_failure stats
+          | Ok () -> (
+              match Hcs.Websocket.recv_message ws with
+              | Error _ -> Stats.record_failure stats
+              | Ok (_, _response) ->
+                  let elapsed = (Unix.gettimeofday () -. start) *. 1000.0 in
+                  Stats.record_success stats elapsed)
+        done;
+        Hcs.Websocket.close ws
+
+  let run ~net ~clock ~sw ~url ~concurrency ~duration ~json ~msg_size =
+    if not json then begin
+      Printf.printf "Benchmarking %s (WebSocket)\n" url;
+      Printf.printf
+        "Concurrency: %d, Duration: %d seconds, Message size: %d\n%!"
+        concurrency duration msg_size
+    end;
+
+    let stats = Stats.create () in
+    let stop_flag = ref false in
+
+    for _ = 1 to concurrency do
+      Eio.Fiber.fork ~sw (fun () ->
+          worker ~sw ~net ~url ~stats ~stop_flag ~msg_size)
+    done;
+
+    Eio.Time.sleep clock (float_of_int duration);
+    stop_flag := true;
+    Eio.Time.sleep clock 0.1;
+
+    Stats.report stats ~json ~protocol:"WebSocket"
+end
+
+let run_benchmark protocol url concurrency duration json msg_size =
+  Eio_main.run @@ fun env ->
+  Eio.Switch.run @@ fun sw ->
+  let net = Eio.Stdenv.net env in
+  let clock = Eio.Stdenv.clock env in
+
+  match protocol with
+  | "h1" | "http1" | "http/1.1" ->
+      H1_benchmark.run ~net ~clock ~sw ~url ~concurrency ~duration ~json
+  | "h2" | "http2" | "http/2" | "h2c" ->
+      Printf.eprintf
+        "HTTP/2 benchmarks: use h2load from nghttp2\n\
+         Example: h2load -n 100000 -c %d -t 1 %s\n"
+        concurrency url;
+      exit 0
+  | "ws" | "websocket" ->
+      Ws_benchmark.run ~net ~clock ~sw ~url ~concurrency ~duration ~json
+        ~msg_size
+  | _ ->
+      Printf.eprintf "Unknown protocol: %s (use h1, h2, or ws)\n" protocol;
+      exit 1
+
+let command =
+  Climate.Command.singleton
+    ~doc:
+      "HCS multi-protocol benchmark client (HTTP/1.1 native, WebSocket native, \
+       HTTP/2 via h2load)"
+  @@
+  let open Climate.Arg_parser in
+  let+ protocol =
+    named_with_default [ "p"; "protocol" ] string ~default:"h1"
+      ~doc:
+        "Protocol to use: h1 (HTTP/1.1), h2 (HTTP/2 - prints h2load command), \
+         ws (WebSocket)"
+  and+ url = named_req [ "u"; "url" ] string ~doc:"Target URL to benchmark"
+  and+ concurrency =
+    named_with_default [ "c"; "concurrency" ] int ~default:10
+      ~doc:"Number of concurrent connections"
+  and+ duration =
+    named_with_default [ "d"; "duration" ] int ~default:10
+      ~doc:"Test duration in seconds"
+  and+ json = flag [ "json" ] ~doc:"Output results as JSON"
+  and+ msg_size =
+    named_with_default [ "m"; "msg-size" ] int ~default:32
+      ~doc:"WebSocket message size in bytes"
+  in
+
+  run_benchmark protocol url concurrency duration json msg_size
+
+let () = Climate.Command.run command

bench/client/dune

···
+(executable
+ (name bench_client)
+ (public_name bench-client)
+ (libraries hcs eio_main uri climate unix cstruct tls-eio))

bench/dream/bench_server_dream.ml

···
+type json_message = { message : string }
+
+let serialize_json () =
+  let msg = { message = "Hello, World!" } in
+  let json = `Assoc [ ("message", `String msg.message) ] in
+  Yojson.Basic.to_string json
+
+let plaintext_body = "Hello, World!"
+
+let plaintext_handler _req =
+  Dream.respond
+    ~headers:[ ("Content-Type", "text/plain"); ("Server", "dream") ]
+    plaintext_body
+
+let json_handler _req =
+  let body = serialize_json () in
+  Dream.respond
+    ~headers:[ ("Content-Type", "application/json"); ("Server", "dream") ]
+    body
+
+let command =
+  Climate.Command.singleton ~doc:"TechEmpower benchmark server using Dream"
+  @@
+  let open Climate.Arg_parser in
+  let+ port =
+    named_with_default [ "p"; "port" ] int ~default:8080
+      ~doc:"Port to listen on"
+  in
+
+  Printf.printf "Starting Dream server on port %d\n%!" port;
+  Dream.run ~port ~interface:"0.0.0.0"
+  @@ Dream.router
+       [
+         Dream.get "/plaintext" plaintext_handler;
+         Dream.get "/json" json_handler;
+       ]
+
+let () = Climate.Command.run command

bench/dream/dune

···
+(executable
+ (name bench_server_dream)
+ (public_name bench-dream)
+ (libraries dream yojson climate))

bench/fasthttp/go.mod

···
+module bench-fasthttp
+
+go 1.21
+
+require github.com/valyala/fasthttp v1.51.0
+
+require (
+	github.com/andybalholm/brotli v1.0.5 // indirect
+	github.com/klauspost/compress v1.17.0 // indirect
+	github.com/valyala/bytebufferpool v1.0.0 // indirect
+	github.com/valyala/tcplisten v1.0.0 // indirect
+	golang.org/x/sys v0.13.0 // indirect
+)

bench/fasthttp/go.sum

···
+github.com/andybalholm/brotli v1.0.5 h1:8uQZIdzKmjc/iuPu7O2ioW48L81FgatrcpfFmiq/cCs=
+github.com/andybalholm/brotli v1.0.5/go.mod h1:fO7iG3H7G2nSZ7m0zPUDn85XEX2GTukHGRSepvi9Eig=
+github.com/klauspost/compress v1.17.0 h1:Rnbp4K9EjcDuVuHtd0dgA4qNuv9yKDYKK1ulpJwgrqM=
+github.com/klauspost/compress v1.17.0/go.mod h1:ntbaceVETuRiXiv4DpjP66DpAtAGkEQskQzEyD//IeE=
+github.com/valyala/bytebufferpool v1.0.0 h1:GqA5TC/0021Y/b9FG4Oi9Mr3q7XYx6KllzawFIhcdPw=
+github.com/valyala/bytebufferpool v1.0.0/go.mod h1:6bBcMArwyJ5K/AmCkWv1jt77kVWyCJ6HpOuEn7z0Csc=
+github.com/valyala/fasthttp v1.51.0 h1:8b30A5JlZ6C7AS81RsWjYMQmrZG6feChmgAolCl1SqA=
+github.com/valyala/fasthttp v1.51.0/go.mod h1:oI2XroL+lI7vdXyYoQk03bXBThfFl2cVdIA3Xl7cH8g=
+github.com/valyala/tcplisten v1.0.0 h1:rBHj/Xf+E1tRGZyWIWwJDiRY0zc1Js+CV5DqwacVSA8=
+github.com/valyala/tcplisten v1.0.0/go.mod h1:T0xQ8SeCZGxckz9qRXTfG43PvQ/mcWh7FwZEA7Ioqkc=
+golang.org/x/sys v0.13.0 h1:Af8nKPmuFypiUBjVoU9V20FiaFXOcuZI21p0ycVYYGE=
+golang.org/x/sys v0.13.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=

bench/fasthttp/main.go

···
+// TechEmpower-style benchmark server using fasthttp
+//
+// Implements:
+// - /plaintext - Returns "Hello, World!" as text/plain
+// - /json - Returns {"message":"Hello, World!"} as application/json
+//
+// Supports HTTP/1.1 with prefork for CPU scaling.
+// Usage: ./bench-fasthttp -port 8080 -prefork -threads 4
+
+package main
+
+import (
+	"encoding/json"
+	"flag"
+	"fmt"
+	"log"
+	"runtime"
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"github.com/valyala/fasthttp"
+	"github.com/valyala/fasthttp/prefork"
+)
+
+const (
+	helloWorldStr   = "Hello, World!"
+	contentTypeJSON = "application/json"
+	contentTypeText = "text/plain"
+	serverName      = "fasthttp"
+)
+
+// Message for JSON response
+type Message struct {
+	Message string `json:"message"`
+}
+
+var (
+	port       int
+	threads    int
+	usePrefork bool
+)
+
+var (
+	dateCacheMu   sync.RWMutex
+	dateCacheTime int64
+	dateCacheVal  []byte
+)
+
+func getCachedDate() []byte {
+	now := time.Now().Unix()
+	cached := atomic.LoadInt64(&dateCacheTime)
+
+	if now != cached {
+		dateCacheMu.Lock()
+		if atomic.LoadInt64(&dateCacheTime) != now {
+			dateCacheVal = []byte(time.Now().UTC().Format(time.RFC1123))
+			atomic.StoreInt64(&dateCacheTime, now)
+		}
+		dateCacheMu.Unlock()
+	}
+
+	dateCacheMu.RLock()
+	defer dateCacheMu.RUnlock()
+	return dateCacheVal
+}
+
+func init() {
+	flag.IntVar(&port, "port", 8080, "Port to listen on")
+	flag.IntVar(&threads, "threads", 1, "Number of threads (GOMAXPROCS)")
+	flag.BoolVar(&usePrefork, "prefork", false, "Use prefork mode for multi-process scaling")
+	flag.Parse()
+}
+
+func main() {
+	// Set GOMAXPROCS
+	runtime.GOMAXPROCS(threads)
+
+	addr := fmt.Sprintf(":%d", port)
+
+	server := &fasthttp.Server{
+		Name:                          serverName,
+		Handler:                       router,
+		DisableHeaderNamesNormalizing: true,
+	}
+
+	fmt.Printf("Starting fasthttp server on port %d with %d threads (prefork=%v)\n", port, threads, usePrefork)
+
+	var err error
+	if usePrefork {
+		err = prefork.New(server).ListenAndServe(addr)
+	} else {
+		err = server.ListenAndServe(addr)
+	}
+
+	if err != nil {
+		log.Fatalf("Error starting server: %v", err)
+	}
+}
+
+func router(ctx *fasthttp.RequestCtx) {
+	path := string(ctx.Path())
+	switch path {
+	case "/plaintext":
+		plaintext(ctx)
+	case "/json":
+		jsonHandler(ctx)
+	default:
+		ctx.Error(fasthttp.StatusMessage(fasthttp.StatusNotFound), fasthttp.StatusNotFound)
+	}
+}
+
+func plaintext(ctx *fasthttp.RequestCtx) {
+	ctx.Response.Header.SetServer(serverName)
+	ctx.Response.Header.SetBytesV("Date", getCachedDate())
+	ctx.Response.Header.SetContentType(contentTypeText)
+	ctx.Response.SetBodyString(helloWorldStr)
+}
+
+func jsonHandler(ctx *fasthttp.RequestCtx) {
+	msg := Message{Message: helloWorldStr}
+	data, _ := json.Marshal(msg)
+
+	ctx.Response.Header.SetServer(serverName)
+	ctx.Response.Header.SetBytesV("Date", getCachedDate())
+	ctx.Response.Header.SetContentType(contentTypeJSON)
+	ctx.Response.SetBody(data)
+}

bench/hcs/bench_server.ml

···
+type json_message = { message : string }
+
+let serialize_json () =
+  let msg = { message = "Hello, World!" } in
+  let json = `Assoc [ ("message", `String msg.message) ] in
+  Yojson.Basic.to_string json
+
+let plaintext_body = "Hello, World!"
+
+let plaintext_body_bstr =
+  Bigstringaf.of_string ~off:0
+    ~len:(String.length plaintext_body)
+    plaintext_body
+
+let plaintext_headers =
+  Hcs.H1_server.make_h1_headers
+    [
+      ("Content-Type", "text/plain"); ("Server", "hcs"); ("Content-Length", "13");
+    ]
+
+let plaintext_h1_response =
+  Hcs.H1_server.make_h1_response ~status:`OK plaintext_headers
+
+let notfound_body_bstr = Bigstringaf.of_string ~off:0 ~len:9 "Not Found"
+
+let notfound_headers =
+  Hcs.H1_server.make_h1_headers [ ("Server", "hcs"); ("Content-Length", "9") ]
+
+let notfound_h1_response =
+  Hcs.H1_server.make_h1_response ~status:`Not_found notfound_headers
+
+let handler (req : Hcs.H1_server.request) : Hcs.H1_server.response =
+  match req.target with
+  | "/plaintext" ->
+      Hcs.H1_server.respond_prebuilt plaintext_h1_response plaintext_body_bstr
+  | "/json" ->
+      let body = serialize_json () in
+      Hcs.H1_server.respond ~status:`OK
+        ~headers:[ ("Content-Type", "application/json"); ("Server", "hcs") ]
+        body
+  | _ -> Hcs.H1_server.respond_prebuilt notfound_h1_response notfound_body_bstr
+
+let command =
+  Climate.Command.singleton ~doc:"TechEmpower benchmark server using HCS"
+  @@
+  let open Climate.Arg_parser in
+  let+ port =
+    named_with_default [ "p"; "port" ] int ~default:8080
+      ~doc:"Port to listen on"
+  and+ domains =
+    named_with_default [ "d"; "domains" ] int ~default:1
+      ~doc:"Number of domains (CPUs) to use"
+  in
+
+  Printf.printf "Starting HCS server on port %d with %d domains\n%!" port
+    domains;
+
+  Eio_main.run @@ fun env ->
+  Eio.Switch.run @@ fun sw ->
+  let config =
+    Hcs.H1_server.
+      {
+        default_config with
+        port;
+        domain_count = domains;
+        backlog = 4096;
+        max_connections = 100000;
+        buffer_size = 16384;
+      }
+  in
+  Hcs.H1_server.run_parallel ~sw ~net:(Eio.Stdenv.net env)
+    ~domain_mgr:(Eio.Stdenv.domain_mgr env)
+    ~config handler
+
+let () = Climate.Command.run command

bench/hcs/bench_server_fast.ml

···
+type json_message = { message : string }
+
+let serialize_json () =
+  let msg = { message = "Hello, World!" } in
+  let json = `Assoc [ ("message", `String msg.message) ] in
+  Yojson.Basic.to_string json
+
+let plaintext_response =
+  Hcs.Server.Prebuilt.create ~status:`OK
+    ~headers:[ ("content-type", "text/plain"); ("server", "hcs") ]
+    "Hello, World!"
+
+let notfound_response =
+  Hcs.Server.Prebuilt.create ~status:`Not_found
+    ~headers:[ ("server", "hcs") ]
+    "Not Found"
+
+let handler (req : Hcs.Server.request) : Hcs.Server.response =
+  match req.target with
+  | "/plaintext" -> Hcs.Server.respond_prebuilt plaintext_response
+  | "/json" ->
+      let body = serialize_json () in
+      Hcs.Server.respond ~status:`OK
+        ~headers:[ ("content-type", "application/json"); ("server", "hcs") ]
+        body
+  | _ -> Hcs.Server.respond_prebuilt notfound_response
+
+let command =
+  Climate.Command.singleton
+    ~doc:"TechEmpower benchmark server using Server (Http1_only mode)"
+  @@
+  let open Climate.Arg_parser in
+  let+ port =
+    named_with_default [ "p"; "port" ] int ~default:8080
+      ~doc:"Port to listen on"
+  and+ domains =
+    named_with_default [ "d"; "domains" ] int ~default:1
+      ~doc:"Number of domains (CPUs) to use"
+  in
+
+  Printf.printf
+    "Starting HCS Server (Http1_only mode) on port %d with %d domains\n%!" port
+    domains;
+
+  Eio_main.run @@ fun env ->
+  Eio.Switch.run @@ fun sw ->
+  let config =
+    Hcs.Server.
+      {
+        default_config with
+        port;
+        domain_count = domains;
+        protocol = Http1_only;
+        backlog = 4096;
+        max_connections = 100000;
+      }
+  in
+  Hcs.Server.run_parallel ~sw ~net:(Eio.Stdenv.net env)
+    ~domain_mgr:(Eio.Stdenv.domain_mgr env)
+    ~config handler
+
+let () = Climate.Command.run command

bench/hcs/bench_server_h2.ml

···
+(** HCS HTTP/2 Benchmark Server
+
+    TechEmpower-style benchmark server using HCS H2_server for HTTP/2 h2c
+    (cleartext). Supports multi-domain (multi-CPU) operation via SO_REUSEPORT.
+*)
+
+(* TechEmpower-compliant JSON message type *)
+type json_message = { message : string }
+
+(* Serialize JSON per-request as required by TechEmpower spec *)
+let serialize_json () =
+  let msg = { message = "Hello, World!" } in
+  let json = `Assoc [ ("message", `String msg.message) ] in
+  Yojson.Basic.to_string json
+
+(* Pre-built plaintext response *)
+let plaintext_body = Bigstringaf.of_string ~off:0 ~len:13 "Hello, World!"
+
+let plaintext_headers =
+  Hcs.H2_server.make_h2_headers
+    [
+      ("content-type", "text/plain");
+      ("server", "hcs-h2");
+      ("content-length", "13");
+    ]
+
+let plaintext_response =
+  Hcs.H2_server.make_h2_response ~status:`OK plaintext_headers
+
+(* Pre-built not found response *)
+let notfound_body = Bigstringaf.of_string ~off:0 ~len:9 "Not Found"
+
+let notfound_headers =
+  Hcs.H2_server.make_h2_headers
+    [ ("server", "hcs-h2"); ("content-length", "9") ]
+
+let notfound_response =
+  Hcs.H2_server.make_h2_response ~status:`Not_found notfound_headers
+
+let handler (req : Hcs.H2_server.request) : Hcs.H2_server.response =
+  match req.target with
+  | "/plaintext" ->
+      Hcs.H2_server.respond_prebuilt plaintext_response plaintext_body
+  | "/json" ->
+      (* TechEmpower requires JSON serialization per-request *)
+      let body = serialize_json () in
+      Hcs.H2_server.respond_opt ~status:`OK
+        ~headers:[ ("content-type", "application/json"); ("server", "hcs-h2") ]
+        body
+  | _ -> Hcs.H2_server.respond_prebuilt notfound_response notfound_body
+
+let command =
+  Climate.Command.singleton
+    ~doc:"TechEmpower benchmark server using HCS HTTP/2 (h2c)"
+  @@
+  let open Climate.Arg_parser in
+  let+ port =
+    named_with_default [ "p"; "port" ] int ~default:8080
+      ~doc:"Port to listen on"
+  and+ domains =
+    named_with_default [ "d"; "domains" ] int ~default:1
+      ~doc:"Number of domains (CPUs) to use"
+  in
+
+  Printf.printf
+    "Starting HCS HTTP/2 (h2c) server on port %d with %d domains\n%!" port
+    domains;
+
+  Eio_main.run @@ fun env ->
+  Eio.Switch.run @@ fun sw ->
+  let config =
+    Hcs.H1_server.
+      {
+        default_config with
+        port;
+        domain_count = domains;
+        backlog = 4096;
+        max_connections = 100000;
+        reuse_port = true;
+        tcp_nodelay = true;
+      }
+  in
+  Hcs.H2_server.run_parallel ~sw ~net:(Eio.Stdenv.net env)
+    ~domain_mgr:(Eio.Stdenv.domain_mgr env)
+    ~config handler
+
+let () = Climate.Command.run command

bench/hcs/bench_server_unified.ml

···
+type json_message = { message : string }
+
+let serialize_json () =
+  let msg = { message = "Hello, World!" } in
+  let json = `Assoc [ ("message", `String msg.message) ] in
+  Yojson.Basic.to_string json
+
+let plaintext_body = "Hello, World!"
+
+let handler (req : Hcs.Server.request) : Hcs.Server.response =
+  match req.target with
+  | "/plaintext" ->
+      Hcs.Server.respond ~status:`OK
+        ~headers:[ ("content-type", "text/plain"); ("server", "hcs-unified") ]
+        plaintext_body
+  | "/json" ->
+      let body = serialize_json () in
+      Hcs.Server.respond ~status:`OK
+        ~headers:
+          [ ("content-type", "application/json"); ("server", "hcs-unified") ]
+        body
+  | _ ->
+      Hcs.Server.respond ~status:`Not_found
+        ~headers:[ ("server", "hcs-unified") ]
+        "Not Found"
+
+let ws_handler (ws : Hcs.Websocket.t) =
+  let rec loop () =
+    match Hcs.Websocket.recv_message ws with
+    | Ok (Hcs.Websocket.Opcode.Text, msg) -> (
+        match Hcs.Websocket.send_text ws msg with
+        | Ok () -> loop ()
+        | Error _ -> ())
+    | Ok (Hcs.Websocket.Opcode.Binary, msg) -> (
+        match Hcs.Websocket.send_binary ws msg with
+        | Ok () -> loop ()
+        | Error _ -> ())
+    | Ok _ -> loop ()
+    | Error Hcs.Websocket.Connection_closed -> ()
+    | Error _ -> ()
+  in
+  loop ()
+
+let command =
+  Climate.Command.singleton
+    ~doc:"Unified benchmark server (HTTP/1.1 + HTTP/2 h2c + WebSocket)"
+  @@
+  let open Climate.Arg_parser in
+  let+ port =
+    named_with_default [ "p"; "port" ] int ~default:8080
+      ~doc:"Port to listen on"
+  and+ domains =
+    named_with_default [ "d"; "domains" ] int ~default:1
+      ~doc:"Number of domains (CPUs) to use"
+  in
+
+  Printf.printf
+    "Starting HCS Server (Auto_websocket mode) on port %d with %d domains\n%!"
+    port domains;
+  Printf.printf "Supports: HTTP/1.1, HTTP/2 h2c, WebSocket\n%!";
+  Printf.printf "Endpoints:\n%!";
+  Printf.printf "  GET /plaintext - Plain text response\n%!";
+  Printf.printf "  GET /json      - JSON response\n%!";
+  Printf.printf "  WS  /          - WebSocket echo\n%!";
+
+  Eio_main.run @@ fun env ->
+  Eio.Switch.run @@ fun sw ->
+  let config =
+    Hcs.Server.
+      {
+        default_config with
+        port;
+        domain_count = domains;
+        protocol = Auto_websocket;
+        backlog = 4096;
+        max_connections = 100000;
+      }
+  in
+  Hcs.Server.run_parallel ~sw ~net:(Eio.Stdenv.net env)
+    ~domain_mgr:(Eio.Stdenv.domain_mgr env)
+    ~config ~ws_handler handler
+
+let () = Climate.Command.run command

bench/hcs/dune

···
+(executable
+ (name bench_server)
+ (public_name bench-hcs)
+ (libraries hcs eio_main yojson climate))
+
+(executable
+ (name bench_server_fast)
+ (public_name bench-hcs-fast)
+ (libraries hcs eio_main yojson climate))
+
+(executable
+ (name bench_server_h2)
+ (public_name bench-hcs-h2)
+ (libraries hcs eio_main yojson climate bigstringaf))
+
+(executable
+ (name bench_server_unified)
+ (public_name bench-hcs-unified)
+ (libraries hcs eio_main yojson climate bigstringaf))

bench/hyper/Cargo.lock

···
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "anstream"
+version = "0.6.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "43d5b281e737544384e969a5ccad3f1cdd24b48086a0fc1b2a5262a26b8f4f4a"
+dependencies = [
+ "anstyle",
+ "anstyle-parse",
+ "anstyle-query",
+ "anstyle-wincon",
+ "colorchoice",
+ "is_terminal_polyfill",
+ "utf8parse",
+]
+
+[[package]]
+name = "anstyle"
+version = "1.0.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5192cca8006f1fd4f7237516f40fa183bb07f8fbdfedaa0036de5ea9b0b45e78"
+
+[[package]]
+name = "anstyle-parse"
+version = "0.2.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4e7644824f0aa2c7b9384579234ef10eb7efb6a0deb83f9630a49594dd9c15c2"
+dependencies = [
+ "utf8parse",
+]
+
+[[package]]
+name = "anstyle-query"
+version = "1.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc"
+dependencies = [
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "anstyle-wincon"
+version = "3.0.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d"
+dependencies = [
+ "anstyle",
+ "once_cell_polyfill",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "atomic-waker"
+version = "1.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1505bd5d3d116872e7271a6d4e16d81d0c8570876c8de68093a09ac269d8aac0"
+
+[[package]]
+name = "base64"
+version = "0.21.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9d297deb1925b89f2ccc13d7635fa0714f12c87adce1c75356b39ca9b7178567"
+
+[[package]]
+name = "bench-hyper"
+version = "0.1.0"
+dependencies = [
+ "clap",
+ "fastwebsockets",
+ "http-body-util",
+ "httpdate",
+ "hyper",
+ "hyper-util",
+ "serde",
+ "serde_json",
+ "socket2 0.5.10",
+ "tokio",
+]
+
+[[package]]
+name = "bitflags"
+version = "2.10.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "812e12b5285cc515a9c72a5c1d3b6d46a19dac5acfef5265968c166106e31dd3"
+
+[[package]]
+name = "block-buffer"
+version = "0.10.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71"
+dependencies = [
+ "generic-array",
+]
+
+[[package]]
+name = "bytes"
+version = "1.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b35204fbdc0b3f4446b89fc1ac2cf84a8a68971995d0bf2e925ec7cd960f9cb3"
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "clap"
+version = "4.5.53"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c9e340e012a1bf4935f5282ed1436d1489548e8f72308207ea5df0e23d2d03f8"
+dependencies = [
+ "clap_builder",
+ "clap_derive",
+]
+
+[[package]]
+name = "clap_builder"
+version = "4.5.53"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d76b5d13eaa18c901fd2f7fca939fefe3a0727a953561fefdf3b2922b8569d00"
+dependencies = [
+ "anstream",
+ "anstyle",
+ "clap_lex",
+ "strsim",
+]
+
+[[package]]
+name = "clap_derive"
+version = "4.5.49"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2a0b5487afeab2deb2ff4e03a807ad1a03ac532ff5a2cee5d86884440c7f7671"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "clap_lex"
+version = "0.7.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a1d728cc89cf3aee9ff92b05e62b19ee65a02b5702cff7d5a377e32c6ae29d8d"
+
+[[package]]
+name = "colorchoice"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b05b61dc5112cbb17e4b6cd61790d9845d13888356391624cbe7e41efeac1e75"
+
+[[package]]
+name = "cpufeatures"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "crypto-common"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a"
+dependencies = [
+ "generic-array",
+ "typenum",
+]
+
+[[package]]
+name = "digest"
+version = "0.10.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
+dependencies = [
+ "block-buffer",
+ "crypto-common",
+]
+
+[[package]]
+name = "equivalent"
+version = "1.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
+
+[[package]]
+name = "errno"
+version = "0.3.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
+dependencies = [
+ "libc",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "fastwebsockets"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "26da0c7b5cef45c521a6f9cdfffdfeb6c9f5804fbac332deb5ae254634c7a6be"
+dependencies = [
+ "base64",
+ "bytes",
+ "http-body-util",
+ "hyper",
+ "hyper-util",
+ "pin-project",
+ "rand",
+ "sha1",
+ "simdutf8",
+ "thiserror",
+ "tokio",
+ "utf-8",
+]
+
+[[package]]
+name = "fnv"
+version = "1.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f9eec918d3f24069decb9af1554cad7c880e2da24a9afd88aca000531ab82c1"
+
+[[package]]
+name = "futures-channel"
+version = "0.3.31"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2dff15bf788c671c1934e366d07e30c1814a8ef514e1af724a602e8a2fbe1b10"
+dependencies = [
+ "futures-core",
+]
+
+[[package]]
+name = "futures-core"
+version = "0.3.31"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05f29059c0c2090612e8d742178b0580d2dc940c837851ad723096f87af6663e"
+
+[[package]]
+name = "futures-sink"
+version = "0.3.31"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e575fab7d1e0dcb8d0c7bcf9a63ee213816ab51902e6d244a95819acacf1d4f7"
+
+[[package]]
+name = "generic-array"
+version = "0.14.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a"
+dependencies = [
+ "typenum",
+ "version_check",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.2.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "335ff9f135e4384c8150d6f27c6daed433577f86b4750418338c01a1a2528592"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "wasi",
+]
+
+[[package]]
+name = "h2"
+version = "0.4.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f3c0b69cfcb4e1b9f1bf2f53f95f766e4661169728ec61cd3fe5a0166f2d1386"
+dependencies = [
+ "atomic-waker",
+ "bytes",
+ "fnv",
+ "futures-core",
+ "futures-sink",
+ "http",
+ "indexmap",
+ "slab",
+ "tokio",
+ "tokio-util",
+ "tracing",
+]
+
+[[package]]
+name = "hashbrown"
+version = "0.16.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "841d1cc9bed7f9236f321df977030373f4a4163ae1a7dbfe1a51a2c1a51d9100"
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "http"
+version = "1.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e3ba2a386d7f85a81f119ad7498ebe444d2e22c2af0b86b069416ace48b3311a"
+dependencies = [
+ "bytes",
+ "itoa",
+]
+
+[[package]]
+name = "http-body"
+version = "1.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1efedce1fb8e6913f23e0c92de8e62cd5b772a67e7b3946df930a62566c93184"
+dependencies = [
+ "bytes",
+ "http",
+]
+
+[[package]]
+name = "http-body-util"
+version = "0.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b021d93e26becf5dc7e1b75b1bed1fd93124b374ceb73f43d4d4eafec896a64a"
+dependencies = [
+ "bytes",
+ "futures-core",
+ "http",
+ "http-body",
+ "pin-project-lite",
+]
+
+[[package]]
+name = "httparse"
+version = "1.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6dbf3de79e51f3d586ab4cb9d5c3e2c14aa28ed23d180cf89b4df0454a69cc87"
+
+[[package]]
+name = "httpdate"
+version = "1.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df3b46402a9d5adb4c86a0cf463f42e19994e3ee891101b1841f30a545cb49a9"
+
+[[package]]
+name = "hyper"
+version = "1.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2ab2d4f250c3d7b1c9fcdff1cece94ea4e2dfbec68614f7b87cb205f24ca9d11"
+dependencies = [
+ "atomic-waker",
+ "bytes",
+ "futures-channel",
+ "futures-core",
+ "h2",
+ "http",
+ "http-body",
+ "httparse",
+ "httpdate",
+ "itoa",
+ "pin-project-lite",
+ "pin-utils",
+ "smallvec",
+ "tokio",
+ "want",
+]
+
+[[package]]
+name = "hyper-util"
+version = "0.1.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "727805d60e7938b76b826a6ef209eb70eaa1812794f9424d4a4e2d740662df5f"
+dependencies = [
+ "bytes",
+ "futures-core",
+ "http",
+ "http-body",
+ "hyper",
+ "pin-project-lite",
+ "tokio",
+]
+
+[[package]]
+name = "indexmap"
+version = "2.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ad4bb2b565bca0645f4d68c5c9af97fba094e9791da685bf83cb5f3ce74acf2"
+dependencies = [
+ "equivalent",
+ "hashbrown",
+]
+
+[[package]]
+name = "is_terminal_polyfill"
+version = "1.70.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695"
+
+[[package]]
+name = "itoa"
+version = "1.0.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92ecc6618181def0457392ccd0ee51198e065e016d1d527a7ac1b6dc7c1f09d2"
+
+[[package]]
+name = "libc"
+version = "0.2.178"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "37c93d8daa9d8a012fd8ab92f088405fb202ea0b6ab73ee2482ae66af4f42091"
+
+[[package]]
+name = "lock_api"
+version = "0.4.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "224399e74b87b5f3557511d98dff8b14089b3dadafcab6bb93eab67d3aace965"
+dependencies = [
+ "scopeguard",
+]
+
+[[package]]
+name = "memchr"
+version = "2.7.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f52b00d39961fc5b2736ea853c9cc86238e165017a493d1d5c8eac6bdc4cc273"
+
+[[package]]
+name = "mio"
+version = "1.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a69bcab0ad47271a0234d9422b131806bf3968021e5dc9328caf2d4cd58557fc"
+dependencies = [
+ "libc",
+ "wasi",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "42f5e15c9953c5e4ccceeb2e7382a716482c34515315f7b03532b8b4e8393d2d"
+
+[[package]]
+name = "once_cell_polyfill"
+version = "1.70.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
+
+[[package]]
+name = "parking_lot"
+version = "0.12.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "93857453250e3077bd71ff98b6a65ea6621a19bb0f559a85248955ac12c45a1a"
+dependencies = [
+ "lock_api",
+ "parking_lot_core",
+]
+
+[[package]]
+name = "parking_lot_core"
+version = "0.9.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2621685985a2ebf1c516881c026032ac7deafcda1a2c9b7850dc81e3dfcb64c1"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "redox_syscall",
+ "smallvec",
+ "windows-link",
+]
+
+[[package]]
+name = "pin-project"
+version = "1.1.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "677f1add503faace112b9f1373e43e9e054bfdd22ff1a63c1bc485eaec6a6a8a"
+dependencies = [
+ "pin-project-internal",
+]
+
+[[package]]
+name = "pin-project-internal"
+version = "1.1.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e918e4ff8c4549eb882f14b3a4bc8c8bc93de829416eacf579f1207a8fbf861"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "pin-project-lite"
+version = "0.2.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3b3cff922bd51709b605d9ead9aa71031d81447142d828eb4a6eba76fe619f9b"
+
+[[package]]
+name = "pin-utils"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8b870d8c151b6f2fb93e84a13146138f05d02ed11c7e7c54f8826aaaf7c9f184"
+
+[[package]]
+name = "ppv-lite86"
+version = "0.2.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85eae3c4ed2f50dcfe72643da4befc30deadb458a9b590d720cde2f2b1e97da9"
+dependencies = [
+ "zerocopy",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.104"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9695f8df41bb4f3d222c95a67532365f569318332d03d5f3f67f37b20e6ebdf0"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.42"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a338cc41d27e6cc6dce6cefc13a0729dfbb81c262b1f519331575dd80ef3067f"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "rand"
+version = "0.8.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "34af8d1a0e25924bc5b7c43c079c942339d8f0a8b57c39049bef581b46327404"
+dependencies = [
+ "libc",
+ "rand_chacha",
+ "rand_core",
+]
+
+[[package]]
+name = "rand_chacha"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6c10a63a0fa32252be49d21e7709d4d4baf8d231c2dbce1eaa8141b9b127d88"
+dependencies = [
+ "ppv-lite86",
+ "rand_core",
+]
+
+[[package]]
+name = "rand_core"
+version = "0.6.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ec0be4795e2f6a28069bec0b5ff3e2ac9bafc99e6a9a7dc3547996c5c816922c"
+dependencies = [
+ "getrandom",
+]
+
+[[package]]
+name = "redox_syscall"
+version = "0.5.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed2bf2547551a7053d6fdfafda3f938979645c44812fbfcda098faae3f1a362d"
+dependencies = [
+ "bitflags",
+]
+
+[[package]]
+name = "scopeguard"
+version = "1.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
+
+[[package]]
+name = "serde"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.148"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3084b546a1dd6289475996f182a22aba973866ea8e8b02c51d9f46b1336a22da"
+dependencies = [
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
+[[package]]
+name = "sha1"
+version = "0.10.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e3bf829a2d51ab4a5ddf1352d8470c140cadc8301b2ae1789db023f01cedd6ba"
+dependencies = [
+ "cfg-if",
+ "cpufeatures",
+ "digest",
+]
+
+[[package]]
+name = "signal-hook-registry"
+version = "1.4.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c4db69cba1110affc0e9f7bcd48bbf87b3f4fc7c61fc9155afd4c469eb3d6c1b"
+dependencies = [
+ "errno",
+ "libc",
+]
+
+[[package]]
+name = "simdutf8"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e3a9fe34e3e7a50316060351f37187a3f546bce95496156754b601a5fa71b76e"
+
+[[package]]
+name = "slab"
+version = "0.4.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7a2ae44ef20feb57a68b23d846850f861394c2e02dc425a50098ae8c90267589"
+
+[[package]]
+name = "smallvec"
+version = "1.15.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67b1b7a3b5fe4f1376887184045fcf45c69e92af734b7aaddc05fb777b6fbd03"
+
+[[package]]
+name = "socket2"
+version = "0.5.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e22376abed350d73dd1cd119b57ffccad95b4e585a7cda43e286245ce23c0678"
+dependencies = [
+ "libc",
+ "windows-sys 0.52.0",
+]
+
+[[package]]
+name = "socket2"
+version = "0.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "17129e116933cf371d018bb80ae557e889637989d8638274fb25622827b03881"
+dependencies = [
+ "libc",
+ "windows-sys 0.60.2",
+]
+
+[[package]]
+name = "strsim"
+version = "0.11.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"
+
+[[package]]
+name = "syn"
+version = "2.0.112"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "21f182278bf2d2bcb3c88b1b08a37df029d71ce3d3ae26168e3c653b213b99d4"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "thiserror"
+version = "1.0.69"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6aaf5339b578ea85b50e080feb250a3e8ae8cfcdff9a461c9ec2904bc923f52"
+dependencies = [
+ "thiserror-impl",
+]
+
+[[package]]
+name = "thiserror-impl"
+version = "1.0.69"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4fee6c4efc90059e10f81e6d42c60a18f76588c3d74cb83a0b242a2b6c7504c1"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "tokio"
+version = "1.48.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ff360e02eab121e0bc37a2d3b4d4dc622e6eda3a8e5253d5435ecf5bd4c68408"
+dependencies = [
+ "bytes",
+ "libc",
+ "mio",
+ "parking_lot",
+ "pin-project-lite",
+ "signal-hook-registry",
+ "socket2 0.6.1",
+ "tokio-macros",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "tokio-macros"
+version = "2.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "af407857209536a95c8e56f8231ef2c2e2aff839b22e07a1ffcbc617e9db9fa5"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "tokio-util"
+version = "0.7.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2efa149fe76073d6e8fd97ef4f4eca7b67f599660115591483572e406e165594"
+dependencies = [
+ "bytes",
+ "futures-core",
+ "futures-sink",
+ "pin-project-lite",
+ "tokio",
+]
+
+[[package]]
+name = "tracing"
+version = "0.1.44"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100"
+dependencies = [
+ "pin-project-lite",
+ "tracing-core",
+]
+
+[[package]]
+name = "tracing-core"
+version = "0.1.36"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "db97caf9d906fbde555dd62fa95ddba9eecfd14cb388e4f491a66d74cd5fb79a"
+dependencies = [
+ "once_cell",
+]
+
+[[package]]
+name = "try-lock"
+version = "0.2.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e421abadd41a4225275504ea4d6566923418b7f05506fbc9c0fe86ba7396114b"
+
+[[package]]
+name = "typenum"
+version = "1.19.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "562d481066bde0658276a35467c4af00bdc6ee726305698a55b86e61d7ad82bb"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.22"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9312f7c4f6ff9069b165498234ce8be658059c6728633667c526e27dc2cf1df5"
+
+[[package]]
+name = "utf-8"
+version = "0.7.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09cc8ee72d2a9becf2f2febe0205bbed8fc6615b7cb429ad062dc7b7ddd036a9"
+
+[[package]]
+name = "utf8parse"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
+
+[[package]]
+name = "version_check"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
+
+[[package]]
+name = "want"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bfa7760aed19e106de2c7c0b581b509f2f25d3dacaf737cb82ac61bc6d760b0e"
+dependencies = [
+ "try-lock",
+]
+
+[[package]]
+name = "wasi"
+version = "0.11.1+wasi-snapshot-preview1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+
+[[package]]
+name = "windows-sys"
+version = "0.52.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "282be5f36a8ce781fad8c8ae18fa3f9beff57ec1b52cb3de0789201425d9a33d"
+dependencies = [
+ "windows-targets 0.52.6",
+]
+
+[[package]]
+name = "windows-sys"
+version = "0.60.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2f500e4d28234f72040990ec9d39e3a6b950f9f22d3dba18416c35882612bcb"
+dependencies = [
+ "windows-targets 0.53.5",
+]
+
+[[package]]
+name = "windows-sys"
+version = "0.61.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
+dependencies = [
+ "windows-link",
+]
+
+[[package]]
+name = "windows-targets"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973"
+dependencies = [
+ "windows_aarch64_gnullvm 0.52.6",
+ "windows_aarch64_msvc 0.52.6",
+ "windows_i686_gnu 0.52.6",
+ "windows_i686_gnullvm 0.52.6",
+ "windows_i686_msvc 0.52.6",
+ "windows_x86_64_gnu 0.52.6",
+ "windows_x86_64_gnullvm 0.52.6",
+ "windows_x86_64_msvc 0.52.6",
+]
+
+[[package]]
+name = "windows-targets"
+version = "0.53.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4945f9f551b88e0d65f3db0bc25c33b8acea4d9e41163edf90dcd0b19f9069f3"
+dependencies = [
+ "windows-link",
+ "windows_aarch64_gnullvm 0.53.1",
+ "windows_aarch64_msvc 0.53.1",
+ "windows_i686_gnu 0.53.1",
+ "windows_i686_gnullvm 0.53.1",
+ "windows_i686_msvc 0.53.1",
+ "windows_x86_64_gnu 0.53.1",
+ "windows_x86_64_gnullvm 0.53.1",
+ "windows_x86_64_msvc 0.53.1",
+]
+
+[[package]]
+name = "windows_aarch64_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3"
+
+[[package]]
+name = "windows_aarch64_gnullvm"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a9d8416fa8b42f5c947f8482c43e7d89e73a173cead56d044f6a56104a6d1b53"
+
+[[package]]
+name = "windows_aarch64_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469"
+
+[[package]]
+name = "windows_aarch64_msvc"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b9d782e804c2f632e395708e99a94275910eb9100b2114651e04744e9b125006"
+
+[[package]]
+name = "windows_i686_gnu"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b"
+
+[[package]]
+name = "windows_i686_gnu"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "960e6da069d81e09becb0ca57a65220ddff016ff2d6af6a223cf372a506593a3"
+
+[[package]]
+name = "windows_i686_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66"
+
+[[package]]
+name = "windows_i686_gnullvm"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fa7359d10048f68ab8b09fa71c3daccfb0e9b559aed648a8f95469c27057180c"
+
+[[package]]
+name = "windows_i686_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66"
+
+[[package]]
+name = "windows_i686_msvc"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e7ac75179f18232fe9c285163565a57ef8d3c89254a30685b57d83a38d326c2"
+
+[[package]]
+name = "windows_x86_64_gnu"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78"
+
+[[package]]
+name = "windows_x86_64_gnu"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9c3842cdd74a865a8066ab39c8a7a473c0778a3f29370b5fd6b4b9aa7df4a499"
+
+[[package]]
+name = "windows_x86_64_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d"
+
+[[package]]
+name = "windows_x86_64_gnullvm"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ffa179e2d07eee8ad8f57493436566c7cc30ac536a3379fdf008f47f6bb7ae1"
+
+[[package]]
+name = "windows_x86_64_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
+
+[[package]]
+name = "windows_x86_64_msvc"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d6bbff5f0aada427a1e5a6da5f1f98158182f26556f345ac9e04d36d0ebed650"
+
+[[package]]
+name = "zerocopy"
+version = "0.8.31"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fd74ec98b9250adb3ca554bdde269adf631549f51d8a8f8f0a10b50f1cb298c3"
+dependencies = [
+ "zerocopy-derive",
+]
+
+[[package]]
+name = "zerocopy-derive"
+version = "0.8.31"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d8a8d209fdf45cf5138cbb5a506f6b52522a25afccc534d1475dad8e31105c6a"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "zmij"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "77cc0158b0d3103d58e9e82bdbe9cf9289d80dbcf4e686ff16730eb9e5814d1a"

bench/hyper/Cargo.toml

···
+[package]
+name = "bench-hyper"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+hyper = { version = "1.0", features = ["server", "http1", "http2"] }
+hyper-util = { version = "0.1", features = ["tokio", "server-auto"] }
+http-body-util = "0.1"
+httpdate = "1"
+tokio = { version = "1", features = ["full"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+clap = { version = "4", features = ["derive"] }
+socket2 = { version = "0.5", features = ["all"] }
+fastwebsockets = { version = "0.8", features = ["upgrade"] }
+
+[profile.release]
+opt-level = 3
+lto = true
+codegen-units = 1

bench/hyper/src/main.rs

···
+use std::convert::Infallible;
+use std::net::{Ipv4Addr, SocketAddr};
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::RwLock;
+use std::{io, thread};
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use clap::Parser;
+use fastwebsockets::{upgrade, FragmentCollector, Frame, OpCode};
+use httpdate::HttpDate;
+use http_body_util::combinators::BoxBody;
+use http_body_util::{BodyExt, Empty, Full};
+use hyper::body::Bytes;
+use hyper::header::{HeaderValue, CONTENT_LENGTH, CONTENT_TYPE, DATE, SERVER};
+use hyper::service::service_fn;
+use hyper::{Request, Response, StatusCode};
+use hyper_util::rt::{TokioExecutor, TokioIo};
+use hyper_util::server::conn::auto::Builder;
+use serde::Serialize;
+use socket2::{Domain, SockAddr, Socket, Type};
+use tokio::net::TcpListener;
+use tokio::runtime;
+
+static SERVER_HEADER: HeaderValue = HeaderValue::from_static("hyper");
+static TEXT_PLAIN: HeaderValue = HeaderValue::from_static("text/plain");
+static APPLICATION_JSON: HeaderValue = HeaderValue::from_static("application/json");
+static PLAINTEXT_BODY: &[u8] = b"Hello, World!";
+
+static DATE_CACHE_SECS: AtomicU64 = AtomicU64::new(0);
+static DATE_CACHE: RwLock<String> = RwLock::new(String::new());
+
+fn get_cached_date() -> HeaderValue {
+    let now = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap()
+        .as_secs();
+    let cached_secs = DATE_CACHE_SECS.load(Ordering::Relaxed);
+    
+    if now != cached_secs {
+        let date_str = HttpDate::from(SystemTime::now()).to_string();
+        if let Ok(mut cache) = DATE_CACHE.write() {
+            *cache = date_str;
+            DATE_CACHE_SECS.store(now, Ordering::Relaxed);
+        }
+    }
+    
+    let cache = DATE_CACHE.read().unwrap();
+    HeaderValue::from_str(&cache).unwrap_or_else(|_| HeaderValue::from_static(""))
+}
+
+#[derive(Serialize)]
+struct JsonMessage {
+    message: &'static str,
+}
+
+#[derive(Debug, Parser)]
+#[command(name = "bench-hyper")]
+#[command(about = "TechEmpower benchmark server using Hyper (HTTP/1.1 + HTTP/2 h2c + WebSocket)")]
+struct Args {
+    #[arg(short, long, default_value_t = 8080)]
+    port: u16,
+
+    #[arg(short, long, default_value_t = 1)]
+    threads: usize,
+}
+
+fn main() -> io::Result<()> {
+    let args = Args::parse();
+    
+    println!("Starting Hyper server on port {} with {} threads (HTTP/1.1 + h2c + WebSocket)", args.port, args.threads);
+
+    let handles: Vec<_> = (0..args.threads)
+        .map(|_| {
+            let port = args.port;
+            thread::spawn(move || {
+                let rt = runtime::Builder::new_current_thread()
+                    .enable_all()
+                    .build()
+                    .expect("Failed to create runtime");
+                rt.block_on(run_server(port)).expect("Server error");
+            })
+        })
+        .collect();
+
+    for handle in handles {
+        handle.join().expect("Worker thread panicked");
+    }
+
+    Ok(())
+}
+
+async fn run_server(port: u16) -> io::Result<()> {
+    let addr = SocketAddr::from((Ipv4Addr::UNSPECIFIED, port));
+    let socket = create_reusable_socket(addr)?;
+    let listener = TcpListener::from_std(socket.into())?;
+
+    loop {
+        let (stream, _) = listener.accept().await?;
+        let io = TokioIo::new(stream);
+
+        tokio::spawn(async move {
+            let builder = Builder::new(TokioExecutor::new());
+            let service = service_fn(router);
+            let _ = builder.serve_connection_with_upgrades(io, service).await;
+        });
+    }
+}
+
+fn create_reusable_socket(addr: SocketAddr) -> io::Result<Socket> {
+    let domain = match addr {
+        SocketAddr::V4(_) => Domain::IPV4,
+        SocketAddr::V6(_) => Domain::IPV6,
+    };
+    
+    let socket = Socket::new(domain, Type::STREAM, None)?;
+    
+    #[cfg(unix)]
+    socket.set_reuse_port(true)?;
+    socket.set_reuse_address(true)?;
+    socket.set_nodelay(true)?;
+    socket.set_nonblocking(true)?;
+    
+    socket.bind(&SockAddr::from(addr))?;
+    socket.listen(4096)?;
+    
+    Ok(socket)
+}
+
+async fn router(req: Request<hyper::body::Incoming>) -> Result<Response<BoxBody<Bytes, Infallible>>, Infallible> {
+    match req.uri().path() {
+        "/plaintext" => Ok(plaintext()),
+        "/json" => Ok(json()),
+        "/ws" => Ok(websocket_upgrade(req).await),
+        _ => Ok(not_found()),
+    }
+}
+
+fn plaintext() -> Response<BoxBody<Bytes, Infallible>> {
+    Response::builder()
+        .header(SERVER, SERVER_HEADER.clone())
+        .header(DATE, get_cached_date())
+        .header(CONTENT_TYPE, TEXT_PLAIN.clone())
+        .header(CONTENT_LENGTH, PLAINTEXT_BODY.len())
+        .body(Full::from(PLAINTEXT_BODY).boxed())
+        .unwrap()
+}
+
+fn json() -> Response<BoxBody<Bytes, Infallible>> {
+    let msg = JsonMessage { message: "Hello, World!" };
+    let body = serde_json::to_vec(&msg).unwrap();
+    let len = body.len();
+    
+    Response::builder()
+        .header(SERVER, SERVER_HEADER.clone())
+        .header(DATE, get_cached_date())
+        .header(CONTENT_TYPE, APPLICATION_JSON.clone())
+        .header(CONTENT_LENGTH, len)
+        .body(Full::from(body).boxed())
+        .unwrap()
+}
+
+fn not_found() -> Response<BoxBody<Bytes, Infallible>> {
+    Response::builder()
+        .status(StatusCode::NOT_FOUND)
+        .header(SERVER, SERVER_HEADER.clone())
+        .header(DATE, get_cached_date())
+        .body(Empty::new().boxed())
+        .unwrap()
+}
+
+async fn websocket_upgrade(mut req: Request<hyper::body::Incoming>) -> Response<BoxBody<Bytes, Infallible>> {
+    if !upgrade::is_upgrade_request(&req) {
+        return Response::builder()
+            .status(StatusCode::BAD_REQUEST)
+            .header(SERVER, SERVER_HEADER.clone())
+            .header(DATE, get_cached_date())
+            .body(Full::from("Not a WebSocket upgrade request").boxed())
+            .unwrap();
+    }
+
+    let (response, fut) = match upgrade::upgrade(&mut req) {
+        Ok(r) => r,
+        Err(_) => {
+            return Response::builder()
+                .status(StatusCode::BAD_REQUEST)
+                .header(SERVER, SERVER_HEADER.clone())
+                .header(DATE, get_cached_date())
+                .body(Full::from("WebSocket upgrade failed").boxed())
+                .unwrap();
+        }
+    };
+
+    tokio::spawn(async move {
+        if let Err(e) = handle_websocket(fut).await {
+            eprintln!("WebSocket error: {}", e);
+        }
+    });
+
+    let (parts, _) = response.into_parts();
+    Response::from_parts(parts, Empty::new().boxed())
+}
+
+async fn handle_websocket(fut: upgrade::UpgradeFut) -> Result<(), fastwebsockets::WebSocketError> {
+    let mut ws = fut.await?;
+    ws.set_auto_pong(true);
+    ws.set_auto_close(true);
+    let mut ws = FragmentCollector::new(ws);
+
+    loop {
+        let frame = ws.read_frame().await?;
+        
+        match frame.opcode {
+            OpCode::Close => break,
+            OpCode::Text | OpCode::Binary => {
+                let echo_frame = Frame::new(true, frame.opcode, None, frame.payload);
+                ws.write_frame(echo_frame).await?;
+            }
+            _ => {}
+        }
+    }
+
+    Ok(())
+}

bench/nethttp/go.mod

···
+module github.com/hcs/bench-nethttp
+
+go 1.21
+
+require golang.org/x/net v0.34.0
+
+require (
+	github.com/gorilla/websocket v1.5.3 // indirect
+	golang.org/x/text v0.21.0 // indirect
+)

bench/nethttp/go.sum

···
+github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg=
+github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
+golang.org/x/net v0.34.0 h1:Mb7Mrk043xzHgnRM88suvJFwzVrRfHEHJEl5/71CKw0=
+golang.org/x/net v0.34.0/go.mod h1:di0qlW3YNM5oh6GqDGQr92MyTozJPmybPK4Ev/Gm31k=
+golang.org/x/text v0.21.0 h1:zyQAAkrwaneQ066sspRyJaG9VNi/YJ1NfzcGB3hZ/qo=
+golang.org/x/text v0.21.0/go.mod h1:4IBbMaMmOPCJ8SecivzSH54+73PCFmPWxNTLm+vZkEQ=

bench/nethttp/main.go

···
+package main
+
+import (
+	"encoding/json"
+	"flag"
+	"fmt"
+	"log"
+	"net"
+	"net/http"
+	"runtime"
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"github.com/gorilla/websocket"
+	"golang.org/x/net/http2"
+	"golang.org/x/net/http2/h2c"
+)
+
+const (
+	helloWorldStr   = "Hello, World!"
+	contentTypeJSON = "application/json"
+	contentTypeText = "text/plain"
+	serverName      = "go-nethttp"
+)
+
+type Message struct {
+	Message string `json:"message"`
+}
+
+var (
+	port    int
+	threads int
+)
+
+var (
+	dateCacheMu   sync.RWMutex
+	dateCacheTime int64
+	dateCacheVal  string
+)
+
+func getCachedDate() string {
+	now := time.Now().Unix()
+	cached := atomic.LoadInt64(&dateCacheTime)
+
+	if now != cached {
+		dateCacheMu.Lock()
+		if atomic.LoadInt64(&dateCacheTime) != now {
+			dateCacheVal = time.Now().UTC().Format(http.TimeFormat)
+			atomic.StoreInt64(&dateCacheTime, now)
+		}
+		dateCacheMu.Unlock()
+	}
+
+	dateCacheMu.RLock()
+	defer dateCacheMu.RUnlock()
+	return dateCacheVal
+}
+
+var jsonBody []byte
+
+func init() {
+	flag.IntVar(&port, "port", 8080, "Port to listen on")
+	flag.IntVar(&threads, "threads", 1, "Number of threads (GOMAXPROCS)")
+
+	msg := Message{Message: helloWorldStr}
+	jsonBody, _ = json.Marshal(msg)
+}
+
+func main() {
+	flag.Parse()
+	runtime.GOMAXPROCS(threads)
+
+	mux := http.NewServeMux()
+	mux.HandleFunc("/plaintext", plaintextHandler)
+	mux.HandleFunc("/json", jsonHandler)
+	mux.HandleFunc("/ws", wsHandler)
+
+	h2s := &http2.Server{}
+	handler := h2c.NewHandler(mux, h2s)
+
+	server := &http.Server{
+		Addr:    fmt.Sprintf(":%d", port),
+		Handler: handler,
+	}
+
+	ln, err := net.Listen("tcp", server.Addr)
+	if err != nil {
+		log.Fatalf("Failed to listen: %v", err)
+	}
+
+	fmt.Printf("Starting Go net/http server on port %d with %d threads (HTTP/1.1 + h2c + WebSocket)\n", port, threads)
+
+	if err := server.Serve(ln); err != nil {
+		log.Fatalf("Server error: %v", err)
+	}
+}
+
+func plaintextHandler(w http.ResponseWriter, r *http.Request) {
+	h := w.Header()
+	h.Set("Server", serverName)
+	h.Set("Date", getCachedDate())
+	h.Set("Content-Type", contentTypeText)
+	w.Write([]byte(helloWorldStr))
+}
+
+func jsonHandler(w http.ResponseWriter, r *http.Request) {
+	h := w.Header()
+	h.Set("Server", serverName)
+	h.Set("Date", getCachedDate())
+	h.Set("Content-Type", contentTypeJSON)
+	w.Write(jsonBody)
+}
+
+var upgrader = websocket.Upgrader{
+	ReadBufferSize:  1024,
+	WriteBufferSize: 1024,
+	CheckOrigin:     func(r *http.Request) bool { return true },
+}
+
+func wsHandler(w http.ResponseWriter, r *http.Request) {
+	conn, err := upgrader.Upgrade(w, r, nil)
+	if err != nil {
+		log.Printf("WebSocket upgrade error: %v", err)
+		return
+	}
+	defer conn.Close()
+
+	for {
+		messageType, message, err := conn.ReadMessage()
+		if err != nil {
+			break
+		}
+		if err := conn.WriteMessage(messageType, message); err != nil {
+			break
+		}
+	}
+}

bench/piaf/bench_server_piaf.ml

···
+module Date_cache = struct
+  let day_names = [| "Sun"; "Mon"; "Tue"; "Wed"; "Thu"; "Fri"; "Sat" |]
+
+  let month_names =
+    [|
+      "Jan";
+      "Feb";
+      "Mar";
+      "Apr";
+      "May";
+      "Jun";
+      "Jul";
+      "Aug";
+      "Sep";
+      "Oct";
+      "Nov";
+      "Dec";
+    |]
+
+  let cached_date = Atomic.make ""
+  let cached_time = Atomic.make 0.
+
+  let format_date () =
+    let t = Unix.gettimeofday () in
+    let tm = Unix.gmtime t in
+    Printf.sprintf "%s, %02d %s %04d %02d:%02d:%02d GMT"
+      day_names.(tm.Unix.tm_wday)
+      tm.Unix.tm_mday
+      month_names.(tm.Unix.tm_mon)
+      (1900 + tm.Unix.tm_year) tm.Unix.tm_hour tm.Unix.tm_min tm.Unix.tm_sec
+
+  let[@inline] get () =
+    let now = Unix.gettimeofday () in
+    let last = Atomic.get cached_time in
+    if now -. last >= 1.0 then begin
+      let date = format_date () in
+      Atomic.set cached_date date;
+      Atomic.set cached_time now;
+      date
+    end
+    else Atomic.get cached_date
+end
+
+type json_message = { message : string }
+
+let serialize_json () =
+  let msg = { message = "Hello, World!" } in
+  let json = `Assoc [ ("message", `String msg.message) ] in
+  Yojson.Basic.to_string json
+
+let plaintext_body = "Hello, World!"
+
+let plaintext_headers () =
+  Piaf.Headers.of_list
+    [
+      ("content-type", "text/plain");
+      ("server", "piaf");
+      ("date", Date_cache.get ());
+      ("content-length", string_of_int (String.length plaintext_body));
+    ]
+
+let notfound_headers () =
+  Piaf.Headers.of_list
+    [ ("server", "piaf"); ("date", Date_cache.get ()); ("content-length", "9") ]
+
+let request_handler (ctx : Piaf.Request_info.t Piaf.Server.ctx) =
+  let target = ctx.request.target in
+  match target with
+  | "/plaintext" ->
+      Piaf.Response.create ~headers:(plaintext_headers ())
+        ~body:(Piaf.Body.of_string plaintext_body)
+        `OK
+  | "/json" ->
+      let body = serialize_json () in
+      let json_headers =
+        Piaf.Headers.of_list
+          [
+            ("content-type", "application/json");
+            ("server", "piaf");
+            ("date", Date_cache.get ());
+            ("content-length", string_of_int (String.length body));
+          ]
+      in
+      Piaf.Response.create ~headers:json_headers
+        ~body:(Piaf.Body.of_string body) `OK
+  | _ ->
+      Piaf.Response.create ~headers:(notfound_headers ())
+        ~body:(Piaf.Body.of_string "Not Found")
+        `Not_found
+
+let command =
+  Climate.Command.singleton ~doc:"TechEmpower benchmark server using Piaf"
+  @@
+  let open Climate.Arg_parser in
+  let+ port =
+    named_with_default [ "p"; "port" ] int ~default:8080
+      ~doc:"Port to listen on"
+  and+ domains =
+    named_with_default [ "d"; "domains" ] int ~default:1
+      ~doc:"Number of domains (CPUs) to use"
+  in
+
+  Printf.printf "Starting Piaf server on port %d with %d domains\n%!" port
+    domains;
+
+  Eio_main.run @@ fun env ->
+  Eio.Switch.run @@ fun sw ->
+  let address = `Tcp (Eio.Net.Ipaddr.V4.any, port) in
+  (* Optimize: higher backlog (default is 128), larger buffers *)
+  let config =
+    Piaf.Server.Config.create ~domains ~backlog:4096 ~buffer_size:16384
+      ~body_buffer_size:16384 address
+  in
+  let server = Piaf.Server.create ~config request_handler in
+  let _command = Piaf.Server.Command.start ~sw env server in
+  ()
+
+let () = Climate.Command.run command

bench/piaf/dune

···
+(executable
+ (name bench_server_piaf)
+ (public_name bench-piaf)
+ (libraries piaf eio_main yojson climate))

bench/scripts/run_benchmark.sh

···
+#!/usr/bin/env bash
+# Multi-Protocol Benchmark Runner
+#
+# Benchmarks all servers: HCS (OCaml), Hyper (Rust), Go net/http
+# Tests HTTP/1.1, HTTP/2 (h2c), and WebSocket protocols
+# Includes memory profiling (RSS per server)
+#
+# Usage: ./run_benchmark.sh [options]
+#   -d, --duration    Test duration in seconds (default: 10)
+#   -c, --concurrency Number of concurrent connections (default: 50)
+#   -w, --warmup      Warmup duration in seconds (default: 2)
+#   -o, --output      Output directory for results (default: ./results)
+#   -s, --server      Run only specific server: hcs|hyper|go (default: all)
+#   -p, --protocol    Run only specific protocol: h1|h2|ws (default: all)
+#   -t, --threads     Number of server threads/domains (default: 4)
+#   -h, --help        Show this help message
+#
+# Requirements:
+#   - h2load (from nghttp2) for HTTP/2 benchmarks
+#   - curl for health checks
+#   - Built servers in expected locations
+
+set -euo pipefail
+
+# Default configuration
+DURATION=10
+CONCURRENCY=50
+WARMUP=2
+OUTPUT_DIR="./results"
+SERVER_FILTER="all"
+PROTOCOL_FILTER="all"
+THREADS=4
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+CYAN='\033[0;36m'
+BOLD='\033[1m'
+NC='\033[0m' # No Color
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        -d|--duration) DURATION="$2"; shift 2 ;;
+        -c|--concurrency) CONCURRENCY="$2"; shift 2 ;;
+        -w|--warmup) WARMUP="$2"; shift 2 ;;
+        -o|--output) OUTPUT_DIR="$2"; shift 2 ;;
+        -s|--server) SERVER_FILTER="$2"; shift 2 ;;
+        -p|--protocol) PROTOCOL_FILTER="$2"; shift 2 ;;
+        -t|--threads) THREADS="$2"; shift 2 ;;
+        -h|--help)
+            head -20 "$0" | tail -16
+            exit 0
+            ;;
+        *) echo "Unknown option: $1"; exit 1 ;;
+    esac
+done
+
+# Directory setup
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+BENCH_DIR="$(dirname "$SCRIPT_DIR")"
+PROJECT_DIR="$(dirname "$BENCH_DIR")"
+TIMESTAMP=$(date +%Y%m%d_%H%M%S)
+RESULT_FILE="$OUTPUT_DIR/benchmark_$TIMESTAMP.txt"
+JSON_FILE="$OUTPUT_DIR/benchmark_$TIMESTAMP.json"
+
+mkdir -p "$OUTPUT_DIR"
+
+# Server configurations
+declare -A SERVER_CMDS
+declare -A SERVER_PORTS
+declare -A SERVER_WS_PATHS
+
+SERVER_CMDS["hcs"]="$PROJECT_DIR/_build/default/bench/hcs/bench_server_unified.exe -p PORT -d $THREADS"
+SERVER_PORTS["hcs"]=8080
+SERVER_WS_PATHS["hcs"]="/"
+
+SERVER_CMDS["hyper"]="$BENCH_DIR/hyper/target/release/bench-hyper -p PORT -t $THREADS"
+SERVER_PORTS["hyper"]=8081
+SERVER_WS_PATHS["hyper"]="/ws"
+
+SERVER_CMDS["go"]="$BENCH_DIR/nethttp/bench-nethttp -port PORT -threads $THREADS"
+SERVER_PORTS["go"]=8082
+SERVER_WS_PATHS["go"]="/ws"
+
+SERVER_CMDS["piaf"]="$PROJECT_DIR/_build/default/bench/piaf/bench_server_piaf.exe -p PORT -d $THREADS"
+SERVER_PORTS["piaf"]=8083
+SERVER_WS_PATHS["piaf"]=""
+
+SERVER_CMDS["fasthttp"]="$BENCH_DIR/fasthttp/bench-fasthttp -port PORT"
+SERVER_PORTS["fasthttp"]=8084
+SERVER_WS_PATHS["fasthttp"]=""
+
+# Logging functions
+log() { echo -e "${BLUE}[INFO]${NC} $1"; }
+success() { echo -e "${GREEN}[OK]${NC} $1"; }
+warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
+error() { echo -e "${RED}[ERROR]${NC} $1"; }
+header() { echo -e "\n${BOLD}${CYAN}=== $1 ===${NC}"; }
+
+# Check dependencies
+check_deps() {
+    local missing=()
+    
+    if ! command -v h2load &> /dev/null; then
+        missing+=("h2load (install nghttp2)")
+    fi
+    
+    if ! command -v curl &> /dev/null; then
+        missing+=("curl")
+    fi
+    
+    if [[ ${#missing[@]} -gt 0 ]]; then
+        error "Missing dependencies: ${missing[*]}"
+        exit 1
+    fi
+}
+
+# Build all servers
+build_servers() {
+    header "Building servers"
+    
+    if [[ "$SERVER_FILTER" == "all" || "$SERVER_FILTER" == "hcs" ]]; then
+        log "Building HCS server..."
+        if (cd "$PROJECT_DIR" && dune build bench/hcs/bench_server_unified.exe bench/client/bench_client.exe 2>&1); then
+            success "HCS built"
+        else
+            error "HCS build failed"
+            return 1
+        fi
+    fi
+    
+    if [[ "$SERVER_FILTER" == "all" || "$SERVER_FILTER" == "hyper" ]]; then
+        log "Building Hyper server..."
+        if (cd "$BENCH_DIR/hyper" && cargo build --release 2>&1 | tail -5); then
+            success "Hyper built"
+        else
+            error "Hyper build failed"
+            return 1
+        fi
+    fi
+    
+    if [[ "$SERVER_FILTER" == "all" || "$SERVER_FILTER" == "go" ]]; then
+        log "Building Go net/http server..."
+        if (cd "$BENCH_DIR/nethttp" && go build -o bench-nethttp . 2>&1); then
+            success "Go server built"
+        else
+            error "Go build failed"
+            return 1
+        fi
+    fi
+    
+    if [[ "$SERVER_FILTER" == "all" || "$SERVER_FILTER" == "piaf" ]]; then
+        log "Building Piaf server..."
+        if (cd "$PROJECT_DIR" && dune build bench/piaf/bench_server_piaf.exe 2>&1); then
+            success "Piaf built"
+        else
+            error "Piaf build failed"
+            return 1
+        fi
+    fi
+    
+    if [[ "$SERVER_FILTER" == "all" || "$SERVER_FILTER" == "fasthttp" ]]; then
+        log "Building fasthttp server..."
+        if (cd "$BENCH_DIR/fasthttp" && go build -o bench-fasthttp . 2>&1); then
+            success "fasthttp built"
+        else
+            error "fasthttp build failed"
+            return 1
+        fi
+    fi
+}
+
+# Get memory usage (RSS in KB) for a PID
+get_rss_kb() {
+    local pid=$1
+    if [[ -f "/proc/$pid/status" ]]; then
+        grep VmRSS "/proc/$pid/status" 2>/dev/null | awk '{print $2}' || echo "0"
+    else
+        # macOS fallback
+        ps -o rss= -p "$pid" 2>/dev/null | tr -d ' ' || echo "0"
+    fi
+}
+
+# Check if systemd-run with cgroup memory tracking is available
+CGROUP_AVAILABLE=false
+# Disabled: systemd-run --scope has issues in non-interactive shells
+# if command -v systemd-run &> /dev/null; then
+#     if systemd-run --user --scope -p MemoryAccounting=yes true 2>/dev/null; then
+#         CGROUP_AVAILABLE=true
+#     fi
+# fi
+
+# Get cgroup path for a scope
+get_cgroup_path() {
+    local scope_name=$1
+    echo "/sys/fs/cgroup/user.slice/user-$(id -u).slice/user@$(id -u).service/app.slice/${scope_name}.scope"
+}
+
+# Get peak memory from cgroup (in KB)
+get_peak_memory_kb() {
+    local cgroup_path=$1
+    if [[ -f "$cgroup_path/memory.peak" ]]; then
+        local bytes=$(cat "$cgroup_path/memory.peak" 2>/dev/null || echo "0")
+        echo $((bytes / 1024))
+    else
+        echo "0"
+    fi
+}
+
+# Get current memory from cgroup (in KB)
+get_current_memory_kb() {
+    local cgroup_path=$1
+    if [[ -f "$cgroup_path/memory.current" ]]; then
+        local bytes=$(cat "$cgroup_path/memory.current" 2>/dev/null || echo "0")
+        echo $((bytes / 1024))
+    else
+        echo "0"
+    fi
+}
+
+start_memory_tracker() {
+    local pid=$1
+    local output_file=$2
+    local pid_file=$3
+    local interval=${4:-0.1}
+    
+    echo "0" > "$output_file"
+    
+    (
+        peak=0
+        while kill -0 "$pid" 2>/dev/null; do
+            if [[ -f "/proc/$pid/status" ]]; then
+                current=$(grep VmRSS "/proc/$pid/status" 2>/dev/null | awk '{print $2}')
+                if [[ -n "$current" && "$current" -gt "$peak" ]] 2>/dev/null; then
+                    peak=$current
+                    echo "$peak" > "$output_file"
+                fi
+            fi
+            sleep "$interval"
+        done
+        echo "$peak" > "$output_file"
+    ) &
+    echo $! > "$pid_file"
+}
+
+stop_memory_tracker() {
+    local pid_file=$1
+    local output_file=$2
+    
+    if [[ -f "$pid_file" ]]; then
+        local tracker_pid=$(cat "$pid_file")
+        rm -f "$pid_file"
+        sleep 0.2
+        kill "$tracker_pid" 2>/dev/null || true
+        wait "$tracker_pid" 2>/dev/null || true
+    fi
+    
+    if [[ -f "$output_file" ]]; then
+        cat "$output_file"
+        rm -f "$output_file"
+    else
+        echo "0"
+    fi
+}
+
+# Wait for server to be ready
+wait_for_server() {
+    local port=$1
+    local max_attempts=50
+    local attempt=0
+    
+    while ! curl -s "http://127.0.0.1:$port/plaintext" > /dev/null 2>&1; do
+        attempt=$((attempt + 1))
+        if [[ $attempt -ge $max_attempts ]]; then
+            error "Server on port $port failed to start"
+            return 1
+        fi
+        sleep 0.1
+    done
+    return 0
+}
+
+cleanup_ports() {
+    for port in 8080 8081 8082 8083 8084; do
+        pkill -9 -f "port.*$port" 2>/dev/null || true
+        pkill -9 -f "\-p.*$port" 2>/dev/null || true
+    done
+    sleep 0.5
+}
+
+strip_ansi() {
+    sed 's/\x1b\[[0-9;]*m//g'
+}
+
+benchmark_h1() {
+    local name=$1
+    local port=$2
+    local endpoint=$3
+    
+    log "HTTP/1.1 $endpoint..."
+    "$PROJECT_DIR/_build/default/bench/client/bench_client.exe" \
+        -p h1 \
+        -u "http://127.0.0.1:$port$endpoint" \
+        -c "$CONCURRENCY" \
+        -d "$DURATION" 2>&1 || true
+}
+
+# Run HTTP/2 benchmark using h2load
+benchmark_h2() {
+    local name=$1
+    local port=$2
+    local endpoint=$3
+    local requests=$((CONCURRENCY * DURATION * 1000))  # Estimate based on expected throughput
+    
+    log "HTTP/2 (h2c) $endpoint..."
+    h2load -n "$requests" -c "$CONCURRENCY" -t 4 \
+        "http://127.0.0.1:$port$endpoint" 2>&1 || true
+}
+
+# Run WebSocket benchmark
+benchmark_ws() {
+    local name=$1
+    local port=$2
+    local ws_path=$3
+    local ws_timeout=$((DURATION + 5))
+    
+    log "WebSocket $ws_path..."
+    # Use timeout to prevent hanging (known issue with some WS servers)
+    timeout "$ws_timeout" "$PROJECT_DIR/_build/default/bench/client/bench_client.exe" \
+        -p ws \
+        -u "ws://127.0.0.1:$port$ws_path" \
+        -c 10 \
+        -d "$DURATION" \
+        --msg-size 128 2>&1 || {
+            local exit_code=$?
+            if [[ $exit_code -eq 124 ]]; then
+                warn "WebSocket benchmark timed out (known issue with HCS server)"
+            fi
+            true
+        }
+}
+
+# Run all benchmarks for a server
+benchmark_server() {
+    local name=$1
+    local cmd_template=${SERVER_CMDS[$name]}
+    local port=${SERVER_PORTS[$name]}
+    local ws_path=${SERVER_WS_PATHS[$name]}
+    
+    local cmd="${cmd_template//PORT/$port}"
+    
+    header "$name (port $port)"
+    
+    log "Starting $name server..."
+    eval "$cmd" &
+    local server_pid=$!
+    
+    if ! wait_for_server "$port"; then
+        kill "$server_pid" 2>/dev/null || true
+        return 1
+    fi
+    
+    success "$name server ready (PID: $server_pid)"
+    
+    local rss_start=$(get_rss_kb "$server_pid")
+    log "Initial RSS: ${rss_start} KB"
+    
+    local peak_tracker_file="/tmp/bench_peak_${name}_$$.txt"
+    local tracker_pid_file="/tmp/bench_tracker_pid_${name}_$$.txt"
+    start_memory_tracker "$server_pid" "$peak_tracker_file" "$tracker_pid_file" 0.05
+    
+    log "Warming up for ${WARMUP}s..."
+    "$PROJECT_DIR/_build/default/bench/client/bench_client.exe" \
+        -p h1 \
+        -u "http://127.0.0.1:$port/plaintext" \
+        -c "$CONCURRENCY" \
+        -d "$WARMUP" > /dev/null 2>&1 || true
+    
+    {
+        echo ""
+        echo "=========================================="
+        echo "  $name"
+        echo "=========================================="
+        echo "Port: $port, Threads: $THREADS"
+        echo ""
+    } >> "$RESULT_FILE"
+    
+    local tmp_out="/tmp/bench_out_$$.txt"
+    
+    if [[ "$PROTOCOL_FILTER" == "all" || "$PROTOCOL_FILTER" == "h1" ]]; then
+        echo "--- HTTP/1.1 ---" >> "$RESULT_FILE"
+        benchmark_h1 "$name" "$port" "/plaintext" > "$tmp_out" 2>&1
+        cat "$tmp_out"
+        strip_ansi < "$tmp_out" >> "$RESULT_FILE"
+        echo "" >> "$RESULT_FILE"
+        benchmark_h1 "$name" "$port" "/json" > "$tmp_out" 2>&1
+        cat "$tmp_out"
+        strip_ansi < "$tmp_out" >> "$RESULT_FILE"
+        echo "" >> "$RESULT_FILE"
+    fi
+    
+    if [[ "$PROTOCOL_FILTER" == "all" || "$PROTOCOL_FILTER" == "h2" ]]; then
+        echo "--- HTTP/2 (h2c) ---" >> "$RESULT_FILE"
+        benchmark_h2 "$name" "$port" "/plaintext" > "$tmp_out" 2>&1
+        cat "$tmp_out"
+        strip_ansi < "$tmp_out" >> "$RESULT_FILE"
+        echo "" >> "$RESULT_FILE"
+        benchmark_h2 "$name" "$port" "/json" > "$tmp_out" 2>&1
+        cat "$tmp_out"
+        strip_ansi < "$tmp_out" >> "$RESULT_FILE"
+        echo "" >> "$RESULT_FILE"
+    fi
+    
+    if [[ "$PROTOCOL_FILTER" == "all" || "$PROTOCOL_FILTER" == "ws" ]]; then
+        echo "--- WebSocket ---" >> "$RESULT_FILE"
+        benchmark_ws "$name" "$port" "$ws_path" > "$tmp_out" 2>&1
+        cat "$tmp_out"
+        strip_ansi < "$tmp_out" >> "$RESULT_FILE"
+        echo "" >> "$RESULT_FILE"
+    fi
+    
+    rm -f "$tmp_out"
+    
+    local rss_end=$(get_rss_kb "$server_pid")
+    
+    kill "$server_pid" 2>/dev/null || true
+    wait "$server_pid" 2>/dev/null || true
+    
+    local peak_rss=$(stop_memory_tracker "$tracker_pid_file" "$peak_tracker_file")
+    
+    log "Memory - Initial: ${rss_start} KB, Final: ${rss_end} KB, Peak: ${peak_rss} KB"
+    
+    {
+        echo "--- Memory ---"
+        echo "Initial RSS: ${rss_start} KB"
+        echo "Final RSS: ${rss_end} KB"
+        echo "Peak RSS: ${peak_rss} KB"
+        echo "Peak RSS (MB): $((peak_rss / 1024)) MB"
+        echo ""
+    } >> "$RESULT_FILE"
+    
+    success "$name benchmark complete"
+    sleep 1
+}
+
+# Generate summary comparison
+generate_summary() {
+    header "Summary"
+    
+    {
+        echo ""
+        echo "=========================================="
+        echo "  BENCHMARK SUMMARY"
+        echo "=========================================="
+        echo "Date: $(date)"
+        echo "Duration: ${DURATION}s per test"
+        echo "Concurrency: $CONCURRENCY connections"
+        echo "Threads: $THREADS per server"
+        echo ""
+        echo "For detailed req/s and latency metrics,"
+        echo "see individual server sections above."
+        echo ""
+        echo "Note: HTTP/2 uses h2load, HTTP/1.1 and WS use bench-client"
+        echo ""
+    } >> "$RESULT_FILE"
+    
+    log "Results saved to: $RESULT_FILE"
+}
+
+# Main execution
+main() {
+    echo ""
+    echo -e "${BOLD}╔════════════════════════════════════════════╗${NC}"
+    echo -e "${BOLD}║   Multi-Protocol Benchmark Suite           ║${NC}"
+    echo -e "${BOLD}╚════════════════════════════════════════════╝${NC}"
+    echo ""
+    echo "  Duration:    ${DURATION}s"
+    echo "  Concurrency: $CONCURRENCY"
+    echo "  Warmup:      ${WARMUP}s"
+    echo "  Threads:     $THREADS"
+    echo "  Servers:     $SERVER_FILTER"
+    echo "  Protocols:   $PROTOCOL_FILTER"
+    echo "  Output:      $RESULT_FILE"
+    echo -e "  Memory:      ${GREEN}peak RSS tracking enabled${NC}"
+    echo ""
+    
+    check_deps
+    
+    # Write header to results file
+    {
+        echo "Multi-Protocol Benchmark Results"
+        echo "================================"
+        echo "Date: $(date)"
+        echo "Duration: ${DURATION}s, Concurrency: $CONCURRENCY, Threads: $THREADS"
+        echo "System: $(uname -a)"
+        echo "CPU: $(grep 'model name' /proc/cpuinfo 2>/dev/null | head -1 | cut -d: -f2 | xargs || sysctl -n machdep.cpu.brand_string 2>/dev/null || echo 'unknown')"
+        echo ""
+    } > "$RESULT_FILE"
+    
+    build_servers
+    cleanup_ports
+    
+    # Run benchmarks for selected servers
+    local servers=()
+    if [[ "$SERVER_FILTER" == "all" ]]; then
+        servers=("hcs" "piaf" "hyper" "go" "fasthttp")
+    else
+        servers=("$SERVER_FILTER")
+    fi
+    
+    for server in "${servers[@]}"; do
+        if [[ -n "${SERVER_CMDS[$server]:-}" ]]; then
+            benchmark_server "$server"
+        else
+            warn "Unknown server: $server"
+        fi
+    done
+    
+    generate_summary
+    cleanup_ports
+    
+    echo ""
+    echo -e "${BOLD}${GREEN}✓ All benchmarks complete!${NC}"
+    echo "  Results: $RESULT_FILE"
+    echo ""
+}
+
+main "$@"

bin/dune

···
+(executable
+ (public_name hc)
+ (package hcs)
+ (name hc)
+ (libraries hcs eio_main mirage-crypto-rng.unix climate))
+
+(executable
+ (public_name hs)
+ (package hcs)
+ (name hs)
+ (libraries hcs eio_main climate))

bin/hc.ml

···
+(** hc - HTTP client using HCS.
+
+    Supports HTTP/1.1, HTTP/2, WebSocket, TLS verification, and common HTTP
+    methods. *)
+
+open Hcs
+
+(** Parse a header string "Name: Value" into a tuple *)
+let parse_header s =
+  match String.index_opt s ':' with
+  | Some i ->
+      let name = String.trim (String.sub s 0 i) in
+      let value =
+        String.trim (String.sub s (i + 1) (String.length s - i - 1))
+      in
+      (name, value)
+  | None -> failwith (Printf.sprintf "Invalid header format: %s" s)
+
+(** Protocol to string *)
+let protocol_to_string = function
+  | Client.HTTP_1_1 -> "HTTP/1.1"
+  | Client.HTTP_2 -> "HTTP/2"
+
+(** Print response headers *)
+let print_headers status protocol headers =
+  Printf.printf "< %s %d\n" (protocol_to_string protocol) status;
+  List.iter (fun (name, value) -> Printf.printf "< %s: %s\n" name value) headers;
+  print_newline ()
+
+(** Handle WebSocket connection *)
+let handle_websocket ~sw ~net ~tls_config ~url ~ws_message ~verbose:_ =
+  Printf.printf "> Connecting to WebSocket: %s\n%!" url;
+  match Websocket.connect ~sw ~net ~tls_config url with
+  | Error err ->
+      let msg =
+        match err with
+        | Websocket.Connection_closed -> "Connection closed"
+        | Websocket.Protocol_error s -> "Protocol error: " ^ s
+        | Websocket.Io_error s -> "IO error: " ^ s
+      in
+      Printf.eprintf "WebSocket error: %s\n" msg;
+      exit 1
+  | Ok ws ->
+      Printf.printf "< Connected!\n%!";
+      (* Send message if provided *)
+      (match ws_message with
+      | Some msg -> (
+          Printf.printf "> Sending: %s\n%!" msg;
+          match Websocket.send_text ws msg with
+          | Ok () -> ()
+          | Error _ ->
+              Printf.eprintf "Failed to send message\n";
+              exit 1)
+      | None -> ());
+      (* Receive messages *)
+      let rec recv_loop () =
+        match Websocket.recv_message ws with
+        | Ok (Websocket.Opcode.Text, content) ->
+            Printf.printf "< Text: %s\n%!" content;
+            recv_loop ()
+        | Ok (Websocket.Opcode.Binary, content) ->
+            Printf.printf "< Binary: %d bytes\n%!" (String.length content);
+            recv_loop ()
+        | Ok _ -> recv_loop ()
+        | Error Websocket.Connection_closed ->
+            Printf.printf "< Connection closed\n%!"
+        | Error (Websocket.Protocol_error s) ->
+            Printf.eprintf "Protocol error: %s\n" s
+        | Error (Websocket.Io_error s) -> Printf.eprintf "IO error: %s\n" s
+      in
+      (* Only enter receive loop if we sent a message (otherwise just test connection) *)
+      if Option.is_some ws_message then recv_loop ();
+      Websocket.close ws
+
+(** Handle HTTP request *)
+let handle_http ~sw ~net ~clock ~url ~method_ ~headers ~data ~http2 ~http1
+    ~insecure ~verbose ~head_only ~follow_redirects ~output_file =
+  (* Build client config *)
+  let config =
+    let base = Client.default_config in
+    let config = if insecure then Client.with_insecure_tls base else base in
+    let config =
+      if http2 then Client.with_http2 config
+      else if http1 then Client.with_http11 config
+      else config
+    in
+    if follow_redirects then config else Client.without_redirects config
+  in
+
+  (* Determine actual method *)
+  let method_ = if head_only then "HEAD" else method_ in
+  let method_ =
+    if Option.is_some data && method_ = "GET" then "POST" else method_
+  in
+
+  (* Print request info in verbose mode *)
+  if verbose then begin
+    Printf.printf "> %s %s\n" method_ url;
+    List.iter
+      (fun (name, value) -> Printf.printf "> %s: %s\n" name value)
+      headers;
+    (match data with Some d -> Printf.printf "> Body: %s\n" d | None -> ());
+    print_newline ()
+  end;
+
+  (* Make request based on method *)
+  let result =
+    match (method_, data) with
+    | "GET", None -> Client.get ~sw ~net ~clock ~config url
+    | "HEAD", None -> Client.get ~sw ~net ~clock ~config url
+    | "POST", Some body -> Client.post ~sw ~net ~clock ~config url ~body
+    | "POST", None -> Client.post ~sw ~net ~clock ~config url ~body:""
+    | "PUT", Some body -> Client.post ~sw ~net ~clock ~config url ~body
+    | "PUT", None -> Client.post ~sw ~net ~clock ~config url ~body:""
+    | "DELETE", _ -> Client.get ~sw ~net ~clock ~config url
+    | "OPTIONS", _ -> Client.get ~sw ~net ~clock ~config url
+    | meth, _ ->
+        Printf.eprintf "Method %s not fully supported yet, using GET\n" meth;
+        Client.get ~sw ~net ~clock ~config url
+  in
+
+  match result with
+  | Error err ->
+      let msg =
+        match err with
+        | Client.Connection_failed s -> "Connection failed: " ^ s
+        | Client.Tls_error s -> "TLS error: " ^ s
+        | Client.Protocol_error s -> "Protocol error: " ^ s
+        | Client.Timeout -> "Request timed out"
+        | Client.Invalid_response s -> "Invalid response: " ^ s
+        | Client.Too_many_redirects -> "Too many redirects"
+      in
+      Printf.eprintf "Error: %s\n" msg;
+      exit 1
+  | Ok resp ->
+      (* Print headers in verbose mode or for HEAD requests *)
+      if verbose || head_only then
+        print_headers resp.status resp.protocol resp.headers;
+
+      (* Output body *)
+      if not head_only then begin
+        match output_file with
+        | Some file ->
+            let oc = open_out file in
+            output_string oc resp.body;
+            close_out oc;
+            if verbose then
+              Printf.printf "Wrote %d bytes to %s\n" (String.length resp.body)
+                file
+        | None -> print_string resp.body
+      end
+
+let command =
+  let open Climate in
+  Command.singleton
+    ~doc:"HTTP client supporting HTTP/1.1, HTTP/2, WebSocket, and TLS"
+  @@
+  let open Arg_parser in
+  let+ url = pos_req 0 string ~doc:"URL to request"
+  and+ method_ =
+    named_opt [ "X"; "request" ] string ~doc:"HTTP method" ~value_name:"METHOD"
+  and+ header_strs =
+    named_multi [ "H"; "header" ] string
+      ~doc:"Add header (format: \"Name: Value\")"
+  and+ data =
+    named_opt [ "d"; "data" ] string ~doc:"Request body data" ~value_name:"DATA"
+  and+ http2 = flag [ "2"; "http2" ] ~doc:"Force HTTP/2"
+  and+ http1 = flag [ "1"; "http1" ] ~doc:"Force HTTP/1.1"
+  and+ insecure =
+    flag [ "k"; "insecure" ] ~doc:"Skip TLS certificate verification"
+  and+ verbose = flag [ "v"; "verbose" ] ~doc:"Verbose output (show headers)"
+  and+ head_only = flag [ "I"; "head" ] ~doc:"HEAD request (show headers only)"
+  and+ follow_redirects_flag =
+    flag [ "L"; "location" ] ~doc:"Follow redirects (default: enabled)"
+  and+ no_follow_redirects =
+    flag [ "no-location" ] ~doc:"Do not follow redirects"
+  and+ output_file =
+    named_opt [ "o"; "output" ] string ~doc:"Write output to file"
+      ~value_name:"FILE"
+  and+ websocket = flag [ "w"; "websocket" ] ~doc:"WebSocket mode"
+  and+ ws_message =
+    named_opt [ "ws-message" ] string ~doc:"Message to send in WebSocket mode"
+      ~value_name:"MSG"
+  in
+
+  (* Parse headers from strings *)
+  let headers = List.map parse_header header_strs in
+
+  (* Compute actual values *)
+  let method_ = Option.value method_ ~default:"GET" |> String.uppercase_ascii in
+  let follow_redirects =
+    if no_follow_redirects then false
+    else if follow_redirects_flag then true
+    else true (* default *)
+  in
+
+  (* Initialize RNG for TLS *)
+  Mirage_crypto_rng_unix.use_default ();
+
+  Eio_main.run @@ fun env ->
+  Eio.Switch.run @@ fun sw ->
+  let net = Eio.Stdenv.net env in
+  let clock = Eio.Stdenv.clock env in
+
+  (* Determine if this is a WebSocket URL *)
+  let is_ws =
+    websocket
+    || String.length url >= 5
+       && (String.sub url 0 5 = "ws://"
+          || (String.length url >= 6 && String.sub url 0 6 = "wss://"))
+  in
+
+  if is_ws then begin
+    let tls_config =
+      if insecure then Tls_config.Client.insecure else Tls_config.Client.default
+    in
+    handle_websocket ~sw ~net ~tls_config ~url ~ws_message ~verbose
+  end
+  else
+    handle_http ~sw ~net ~clock ~url ~method_ ~headers ~data ~http2 ~http1
+      ~insecure ~verbose ~head_only ~follow_redirects ~output_file
+
+let () = Climate.Command.run command

bin/hs.ml

···
+(** hs - HTTP file server using HCS.
+
+    Serves files from a directory over HTTP/1.1 and HTTP/2. *)
+
+open Hcs
+
+(** MIME type mapping *)
+let mime_type_of_extension ext =
+  match String.lowercase_ascii ext with
+  | ".html" | ".htm" -> "text/html; charset=utf-8"
+  | ".css" -> "text/css; charset=utf-8"
+  | ".js" | ".mjs" -> "application/javascript; charset=utf-8"
+  | ".json" -> "application/json"
+  | ".xml" -> "application/xml"
+  | ".txt" -> "text/plain; charset=utf-8"
+  | ".md" -> "text/markdown; charset=utf-8"
+  | ".png" -> "image/png"
+  | ".jpg" | ".jpeg" -> "image/jpeg"
+  | ".gif" -> "image/gif"
+  | ".svg" -> "image/svg+xml"
+  | ".ico" -> "image/x-icon"
+  | ".webp" -> "image/webp"
+  | ".avif" -> "image/avif"
+  | ".woff" -> "font/woff"
+  | ".woff2" -> "font/woff2"
+  | ".ttf" -> "font/ttf"
+  | ".otf" -> "font/otf"
+  | ".eot" -> "application/vnd.ms-fontobject"
+  | ".pdf" -> "application/pdf"
+  | ".zip" -> "application/zip"
+  | ".gz" -> "application/gzip"
+  | ".tar" -> "application/x-tar"
+  | ".mp3" -> "audio/mpeg"
+  | ".ogg" -> "audio/ogg"
+  | ".wav" -> "audio/wav"
+  | ".mp4" -> "video/mp4"
+  | ".webm" -> "video/webm"
+  | ".avi" -> "video/x-msvideo"
+  | ".wasm" -> "application/wasm"
+  | ".map" -> "application/json"
+  | _ -> "application/octet-stream"
+
+(** Get file extension from path *)
+let extension path =
+  match String.rindex_opt path '.' with
+  | Some i -> String.sub path i (String.length path - i)
+  | None -> ""
+
+(** Normalize and validate path to prevent directory traversal *)
+let normalize_path path =
+  (* Remove leading slash *)
+  let path =
+    if String.length path > 0 && path.[0] = '/' then
+      String.sub path 1 (String.length path - 1)
+    else path
+  in
+  (* Remove query string *)
+  let path =
+    match String.index_opt path '?' with
+    | Some i -> String.sub path 0 i
+    | None -> path
+  in
+  (* Remove fragment *)
+  let path =
+    match String.index_opt path '#' with
+    | Some i -> String.sub path 0 i
+    | None -> path
+  in
+  (* Check for directory traversal attempts *)
+  let segments = String.split_on_char '/' path in
+  let rec check_segments acc = function
+    | [] -> Some (String.concat "/" (List.rev acc))
+    | ".." :: _ -> None (* Reject any path with .. *)
+    | "." :: rest -> check_segments acc rest
+    | "" :: rest -> check_segments acc rest
+    | seg :: rest ->
+        if String.contains seg '\x00' then None
+        else check_segments (seg :: acc) rest
+  in
+  check_segments [] segments
+
+(** HTML escape for directory listing *)
+let html_escape s =
+  let buf = Buffer.create (String.length s) in
+  String.iter
+    (function
+      | '<' -> Buffer.add_string buf "&lt;"
+      | '>' -> Buffer.add_string buf "&gt;"
+      | '&' -> Buffer.add_string buf "&amp;"
+      | '"' -> Buffer.add_string buf "&quot;"
+      | c -> Buffer.add_char buf c)
+    s;
+  Buffer.contents buf
+
+(** Generate directory listing HTML *)
+let directory_listing ~path entries =
+  let buf = Buffer.create 4096 in
+  Buffer.add_string buf "<!DOCTYPE html>\n<html>\n<head>\n";
+  Buffer.add_string buf "<meta charset=\"utf-8\">\n";
+  Buffer.add_string buf
+    "<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n";
+  Printf.bprintf buf "<title>Index of /%s</title>\n" (html_escape path);
+  Buffer.add_string buf "<style>\n";
+  Buffer.add_string buf
+    "body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', \
+     Roboto, sans-serif; margin: 2em; }\n";
+  Buffer.add_string buf "h1 { font-weight: normal; }\n";
+  Buffer.add_string buf
+    "table { border-collapse: collapse; width: 100%; max-width: 800px; }\n";
+  Buffer.add_string buf "th, td { text-align: left; padding: 0.5em 1em; }\n";
+  Buffer.add_string buf "th { border-bottom: 2px solid #333; }\n";
+  Buffer.add_string buf "tr:hover { background: #f5f5f5; }\n";
+  Buffer.add_string buf "a { color: #0066cc; text-decoration: none; }\n";
+  Buffer.add_string buf "a:hover { text-decoration: underline; }\n";
+  Buffer.add_string buf ".size { color: #666; }\n";
+  Buffer.add_string buf "</style>\n</head>\n<body>\n";
+  Printf.bprintf buf "<h1>Index of /%s</h1>\n" (html_escape path);
+  Buffer.add_string buf "<table>\n<thead>\n<tr>";
+  Buffer.add_string buf "<th>Name</th><th>Size</th>";
+  Buffer.add_string buf "</tr>\n</thead>\n<tbody>\n";
+
+  (* Parent directory link *)
+  if path <> "" then begin
+    Buffer.add_string buf "<tr><td><a href=\"../\">..</a></td><td>-</td></tr>\n"
+  end;
+
+  (* Sort entries: directories first, then files *)
+  let sorted =
+    List.sort
+      (fun (a, a_is_dir) (b, b_is_dir) ->
+        match (a_is_dir, b_is_dir) with
+        | true, false -> -1
+        | false, true -> 1
+        | _ -> String.compare a b)
+      entries
+  in
+
+  List.iter
+    (fun (name, is_dir) ->
+      let display_name = if is_dir then name ^ "/" else name in
+      let href = if is_dir then name ^ "/" else name in
+      let size = if is_dir then "-" else "" in
+      Printf.bprintf buf
+        "<tr><td><a href=\"%s\">%s</a></td><td class=\"size\">%s</td></tr>\n"
+        (html_escape href) (html_escape display_name) size)
+    sorted;
+
+  Buffer.add_string buf "</tbody>\n</table>\n";
+  Buffer.add_string buf "<hr>\n<p><em>Served by hs (HCS)</em></p>\n";
+  Buffer.add_string buf "</body>\n</html>\n";
+  Buffer.contents buf
+
+(** Create the file server handler *)
+let make_handler ~fs ~root ~index_file ~enable_listing ~enable_cors ~verbose =
+ fun (req : Server.request) ->
+  let start_time = Unix.gettimeofday () in
+  let target = req.target in
+
+  (* Normalize path *)
+  let path = normalize_path target in
+
+  let response =
+    match path with
+    | None ->
+        (* Invalid path (directory traversal attempt) *)
+        Server.respond ~status:`Forbidden "Forbidden"
+    | Some path -> (
+        let full_path = Eio.Path.(fs / root / path) in
+        try
+          (* Try to get file info *)
+          let stat = Eio.Path.stat ~follow:true full_path in
+          match stat.kind with
+          | `Directory -> (
+              (* Try index file first *)
+              let index_result =
+                match index_file with
+                | Some idx -> (
+                    try
+                      let idx_path = Eio.Path.(full_path / idx) in
+                      let content = Eio.Path.load idx_path in
+                      let content_type =
+                        mime_type_of_extension (extension idx)
+                      in
+                      Some
+                        {
+                          Server.status = `OK;
+                          headers =
+                            [
+                              ("Content-Type", content_type);
+                              ( "Content-Length",
+                                string_of_int (String.length content) );
+                            ];
+                          body = Server.Body_string content;
+                        }
+                    with _ -> None)
+                | None -> None
+              in
+              match index_result with
+              | Some resp -> resp
+              | None ->
+                  if enable_listing then begin
+                    (* Generate directory listing *)
+                    let entries =
+                      Eio.Path.read_dir full_path
+                      |> List.filter_map (fun name ->
+                          try
+                            let child_path = Eio.Path.(full_path / name) in
+                            let child_stat =
+                              Eio.Path.stat ~follow:true child_path
+                            in
+                            let is_dir = child_stat.kind = `Directory in
+                            Some (name, is_dir)
+                          with _ -> None)
+                    in
+                    let html = directory_listing ~path entries in
+                    {
+                      Server.status = `OK;
+                      headers =
+                        [
+                          ("Content-Type", "text/html; charset=utf-8");
+                          ("Content-Length", string_of_int (String.length html));
+                        ];
+                      body = Server.Body_string html;
+                    }
+                  end
+                  else
+                    Server.respond ~status:`Forbidden
+                      "Directory listing disabled")
+          | `Regular_file ->
+              (* Serve the file *)
+              let content = Eio.Path.load full_path in
+              let content_type = mime_type_of_extension (extension path) in
+              {
+                Server.status = `OK;
+                headers =
+                  [
+                    ("Content-Type", content_type);
+                    ("Content-Length", string_of_int (String.length content));
+                  ];
+                body = Server.Body_string content;
+              }
+          | _ -> Server.respond ~status:`Forbidden "Not a file"
+        with
+        | Eio.Io (Eio.Fs.E (Eio.Fs.Not_found _), _) ->
+            Server.respond ~status:`Not_found "Not Found"
+        | Eio.Io (Eio.Fs.E (Eio.Fs.Permission_denied _), _) ->
+            Server.respond ~status:`Forbidden "Permission Denied"
+        | exn ->
+            if verbose then
+              Printf.eprintf "Error serving %s: %s\n%!" target
+                (Printexc.to_string exn);
+            Server.respond ~status:`Internal_server_error
+              "Internal Server Error")
+  in
+
+  (* Add CORS headers if enabled *)
+  let response =
+    if enable_cors then
+      {
+        response with
+        headers =
+          ("Access-Control-Allow-Origin", "*")
+          :: ("Access-Control-Allow-Methods", "GET, HEAD, OPTIONS")
+          :: ("Access-Control-Allow-Headers", "*")
+          :: response.headers;
+      }
+    else response
+  in
+
+  (* Log request if verbose *)
+  if verbose then begin
+    let duration = (Unix.gettimeofday () -. start_time) *. 1000.0 in
+    let status_code = H1.Status.to_code response.status in
+    Printf.printf "%s %s -> %d (%.2fms)\n%!"
+      (H1.Method.to_string req.meth)
+      target status_code duration
+  end;
+
+  response
+
+let command =
+  Climate.Command.singleton
+    ~doc:"HTTP file server using HCS - serves files over HTTP/1.1 and HTTP/2"
+  @@
+  let open Climate.Arg_parser in
+  let+ directory =
+    pos_with_default 0 string ~default:"." ~value_name:"DIRECTORY"
+      ~doc:"Directory to serve"
+  and+ port =
+    named_opt [ "p"; "port" ] int ~value_name:"PORT"
+      ~doc:"Port to listen on (default: 8080)"
+  and+ bind_address =
+    named_opt [ "b"; "bind" ] string ~value_name:"ADDRESS"
+      ~doc:"Address to bind to (default: 0.0.0.0)"
+  and+ domains =
+    named_opt [ "d"; "domains" ] int ~value_name:"N"
+      ~doc:"Number of domains/threads (default: CPU count)"
+  and+ http1 = flag [ "1"; "http1" ] ~doc:"HTTP/1.1 only (fastest)"
+  and+ http2 = flag [ "2"; "http2" ] ~doc:"HTTP/2 only"
+  and+ index_opt =
+    named_opt [ "index" ] string ~value_name:"FILE"
+      ~doc:"Index file for directories (default: index.html)"
+  and+ no_index = flag [ "no-index" ] ~doc:"Disable index file lookup"
+  and+ enable_listing = flag [ "list" ] ~doc:"Enable directory listing"
+  and+ enable_cors = flag [ "cors" ] ~doc:"Enable CORS headers"
+  and+ verbose = flag [ "v"; "verbose" ] ~doc:"Verbose logging" in
+
+  let port = Option.value port ~default:8080 in
+  let bind_address = Option.value bind_address ~default:"0.0.0.0" in
+  let domains =
+    Option.value domains ~default:(Domain.recommended_domain_count ())
+  in
+  let index_file =
+    if no_index then None
+    else Some (Option.value index_opt ~default:"index.html")
+  in
+
+  if not (Sys.file_exists directory && Sys.is_directory directory) then begin
+    Printf.eprintf "Error: Directory '%s' does not exist\n" directory;
+    exit 1
+  end;
+
+  let protocol =
+    if http1 then Server.Http1_only
+    else if http2 then Server.Http2_only
+    else Server.Http1_only
+  in
+
+  Printf.printf "Serving %s on http://%s:%d\n%!"
+    (if directory = "." then "current directory" else directory)
+    bind_address port;
+  Printf.printf "Protocol: %s, Domains: %d\n%!"
+    (match protocol with
+    | Server.Http1_only -> "HTTP/1.1"
+    | Server.Http2_only -> "HTTP/2"
+    | Server.Auto -> "Auto"
+    | Server.Auto_websocket -> "Auto+WebSocket")
+    domains;
+  if enable_listing then Printf.printf "Directory listing: enabled\n%!";
+  if enable_cors then Printf.printf "CORS: enabled\n%!";
+  Printf.printf "Press Ctrl+C to stop\n%!\n";
+
+  Eio_main.run @@ fun env ->
+  Eio.Switch.run @@ fun sw ->
+  let net = Eio.Stdenv.net env in
+  let fs = Eio.Stdenv.fs env in
+  let domain_mgr = Eio.Stdenv.domain_mgr env in
+
+  let handler =
+    make_handler ~fs ~root:directory ~index_file ~enable_listing ~enable_cors
+      ~verbose
+  in
+
+  let config =
+    { Server.default_config with port; domain_count = domains; protocol }
+  in
+
+  Server.run_parallel ~sw ~net ~domain_mgr ~config handler
+
+let () = Climate.Command.run command

dune-project

···
+(lang dune 3.20)
+
+(name hcs)
+
+(generate_opam_files true)
+
+(source
+ ; (tangled @gdiazlo.tngl.sh/hcs)
+ (uri https://tangled.org/gdiazlo.tngl.sh/hcs))
+
+(authors "Gabriel Díaz")
+
+(maintainers "Gabriel Díaz")
+
+(license ISC)
+(homepage https://tangled.org/gdiazlo.tngl.sh/hcs)
+(bug_reports https://tangled.org/gdiazlo.tngl.sh/hcs/issues)
+(documentation https://tangled.org/gdiazlo.tngl.sh/hcs)
+
+(package
+ (name hcs)
+ (synopsis "Eio based HTTP client/server library for OCaml 5+")
+ (description
+  "HCS is a HTTP client/server library for OCaml 5+ supporting HTTP/1.1, HTTP/2, and WebSocket. Built on Eio.")
+ (depends
+  (ocaml (>= 5.4))
+  (dune (>= 3.20))
+  (eio (>= 1.2))
+  (eio_main (>= 1.2))
+  (h1 (>= 1.0))
+  (h2 (>= 0.13))
+  (tls (>= 2.0))
+  (tls-eio (>= 2.0))
+  (ca-certs (>= 1.0))
+  (x509 (>= 1.0))
+  (mirage-crypto-rng (>= 1.0))
+  (uri (>= 4.4))
+  (ptime (>= 1.2))
+  (cstruct (>= 6.2))
+  (digestif (>= 1.2))
+  (base64 (>= 3.5))
+  (bigstringaf (>= 0.10))
+  (faraday (>= 0.8))
+  (climate (>= 0.9))
+  (alcotest (and (>= 1.9) :with-test))
+  (qcheck (and (>= 0.21) :with-test))
+  (qcheck-alcotest (and (>= 0.21) :with-test))
+  (yojson :with-test)))

hcs.opam

···
+# This file is generated by dune, edit dune-project instead
+opam-version: "2.0"
+synopsis: "Eio based HTTP client/server library for OCaml 5+"
+description:
+  "HCS is a HTTP client/server library for OCaml 5+ supporting HTTP/1.1, HTTP/2, and WebSocket. Built on Eio."
+maintainer: ["Gabriel Díaz"]
+authors: ["Gabriel Díaz"]
+license: "ISC"
+depends: [
+  "ocaml" {>= "5.4"}
+  "dune" {>= "3.20" & >= "3.20"}
+  "eio" {>= "1.2"}
+  "eio_main" {>= "1.2"}
+  "h1" {>= "1.0"}
+  "h2" {>= "0.13"}
+  "tls" {>= "2.0"}
+  "tls-eio" {>= "2.0"}
+  "ca-certs" {>= "1.0"}
+  "x509" {>= "1.0"}
+  "mirage-crypto-rng" {>= "1.0"}
+  "uri" {>= "4.4"}
+  "ptime" {>= "1.2"}
+  "cstruct" {>= "6.2"}
+  "digestif" {>= "1.2"}
+  "base64" {>= "3.5"}
+  "bigstringaf" {>= "0.10"}
+  "faraday" {>= "0.8"}
+  "climate" {>= "0.9"}
+  "alcotest" {>= "1.9" & with-test}
+  "qcheck" {>= "0.21" & with-test}
+  "qcheck-alcotest" {>= "0.21" & with-test}
+  "yojson" {with-test}
+  "odoc" {with-doc}
+]
+build: [
+  ["dune" "subst"] {dev}
+  [
+    "dune"
+    "build"
+    "-p"
+    name
+    "-j"
+    jobs
+    "@install"
+    "@runtest" {with-test}
+    "@doc" {with-doc}
+  ]
+]
+dev-repo: "https://tangled.org/gdiazlo.tngl.sh/hcs"
+x-maintenance-intent: ["(latest)"]

lib/client.ml

···
+(** Unified HTTP Client supporting HTTP/1.1 and HTTP/2.
+
+    This module provides a high-level HTTP client that automatically selects the
+    appropriate protocol based on ALPN negotiation or configuration. *)
+
+(** {1 Types} *)
+
+(** Protocol version *)
+type protocol = HTTP_1_1 | HTTP_2
+
+type config = {
+  (* Timeouts *)
+  connect_timeout : float;  (** Connection timeout in seconds. Default: 30.0 *)
+  read_timeout : float;  (** Read timeout in seconds. Default: 30.0 *)
+  write_timeout : float;  (** Write timeout in seconds. Default: 30.0 *)
+  (* Behavior *)
+  follow_redirects : int option;
+      (** Max redirects to follow. None = don't follow. Default: Some 10 *)
+  preferred_protocol : protocol option;
+      (** Preferred protocol. None = auto-detect via ALPN. Default: None *)
+  (* Buffers *)
+  buffer_size : int;  (** Read buffer size. Default: 16384 *)
+  max_response_body : int64 option;
+      (** Max response body size. None = unlimited. Default: None *)
+  (* TLS *)
+  tls : Tls_config.Client.t;  (** TLS configuration for HTTP/1.1 *)
+  (* Headers *)
+  default_headers : (string * string) list;
+      (** Headers to add to every request *)
+}
+(** Client configuration *)
+
+let default_config =
+  {
+    connect_timeout = 30.0;
+    read_timeout = 30.0;
+    write_timeout = 30.0;
+    follow_redirects = Some 10;
+    preferred_protocol = Some HTTP_1_1;
+    (* Default to HTTP/1.1 for broader compatibility *)
+    buffer_size = 16384;
+    max_response_body = None;
+    tls = Tls_config.Client.default;
+    (* HTTP/1.1 ALPN *)
+    default_headers = [ ("User-Agent", "hcs/0.1.0") ];
+  }
+
+(** {2 Config builders} *)
+
+let with_timeout timeout config =
+  { config with connect_timeout = timeout; read_timeout = timeout }
+
+let with_connect_timeout timeout config =
+  { config with connect_timeout = timeout }
+
+let with_read_timeout timeout config = { config with read_timeout = timeout }
+let with_write_timeout timeout config = { config with write_timeout = timeout }
+
+let with_redirects max_redirects config =
+  { config with follow_redirects = Some max_redirects }
+
+let without_redirects config = { config with follow_redirects = None }
+let with_buffer_size size config = { config with buffer_size = size }
+
+let with_max_response_body max_size config =
+  { config with max_response_body = Some max_size }
+
+let with_tls tls config = { config with tls }
+let with_insecure_tls config = { config with tls = Tls_config.Client.insecure }
+
+let with_http2 config =
+  { config with preferred_protocol = Some HTTP_2; tls = Tls_config.Client.h2 }
+
+let with_http11 config =
+  {
+    config with
+    preferred_protocol = Some HTTP_1_1;
+    tls = Tls_config.Client.default;
+  }
+
+let with_default_header name value config =
+  { config with default_headers = (name, value) :: config.default_headers }
+
+let with_default_headers headers config =
+  { config with default_headers = headers @ config.default_headers }
+
+(** Error type for client operations *)
+type error =
+  | Connection_failed of string
+  | Tls_error of string
+  | Protocol_error of string
+  | Timeout
+  | Invalid_response of string
+  | Too_many_redirects
+
+type response = {
+  status : int;
+  headers : (string * string) list;
+  body : string;
+  protocol : protocol;
+}
+(** Response type - unified across protocols *)
+
+(** {1 Internal helpers} *)
+
+let h1_status_to_int status = H1.Status.to_code status
+let h2_status_to_int status = H2.Status.to_code status
+
+let h1_headers_to_list headers =
+  let result = ref [] in
+  H1.Headers.iter
+    ~f:(fun name value -> result := (name, value) :: !result)
+    headers;
+  List.rev !result
+
+let h2_headers_to_list headers =
+  let result = ref [] in
+  H2.Headers.iter
+    ~f:(fun name value -> result := (name, value) :: !result)
+    headers;
+  List.rev !result
+
+(** {1 Public API} *)
+
+(** Perform an HTTP GET request. The protocol is selected based on: 1.
+    config.preferred_protocol if set 2. ALPN negotiation if using HTTPS 3.
+    HTTP/1.1 for plain HTTP *)
+let get ~sw ~net ~clock ?(config = default_config) url =
+  let uri = Uri.of_string url in
+  let scheme = Uri.scheme uri |> Option.value ~default:"http" in
+  let is_https = String.equal scheme "https" in
+
+  let use_h2 =
+    match config.preferred_protocol with
+    | Some HTTP_2 -> true
+    | Some HTTP_1_1 -> false
+    | None -> (
+        is_https
+        &&
+        match config.tls.alpn_protocols with
+        | Some protos -> List.mem Tls_config.alpn_h2 protos
+        | None -> false)
+  in
+
+  if use_h2 then
+    (* Use HTTP/2 *)
+    match H2_client.get ~sw ~net ~clock url with
+    | Ok resp ->
+        Ok
+          {
+            status = h2_status_to_int resp.H2_client.status;
+            headers = h2_headers_to_list resp.headers;
+            body = resp.body;
+            protocol = HTTP_2;
+          }
+    | Error (H2_client.Connection_failed msg) -> Error (Connection_failed msg)
+    | Error (H2_client.Tls_error msg) -> Error (Tls_error msg)
+    | Error (H2_client.Protocol_error msg) -> Error (Protocol_error msg)
+    | Error H2_client.Timeout -> Error Timeout
+    | Error (H2_client.Invalid_response msg) -> Error (Invalid_response msg)
+  else
+    (* Use HTTP/1.1 *)
+    let h1_config : H1_client.config =
+      {
+        connect_timeout = config.connect_timeout;
+        read_timeout = config.read_timeout;
+        write_timeout = config.write_timeout;
+        follow_redirects = config.follow_redirects;
+        buffer_size = config.buffer_size;
+        max_response_body = config.max_response_body;
+        tls = config.tls;
+        default_headers = config.default_headers;
+      }
+    in
+    match H1_client.get ~sw ~net ~clock ~config:h1_config url with
+    | Ok resp ->
+        Ok
+          {
+            status = h1_status_to_int resp.H1_client.status;
+            headers = h1_headers_to_list resp.headers;
+            body = resp.body;
+            protocol = HTTP_1_1;
+          }
+    | Error (H1_client.Connection_failed msg) -> Error (Connection_failed msg)
+    | Error (H1_client.Tls_error msg) -> Error (Tls_error msg)
+    | Error H1_client.Timeout -> Error Timeout
+    | Error (H1_client.Invalid_response msg) -> Error (Invalid_response msg)
+    | Error H1_client.Too_many_redirects -> Error Too_many_redirects
+
+(** Perform an HTTP POST request *)
+let post ~sw ~net ~clock ?(config = default_config) url ~body:request_body =
+  (* For now, POST only uses HTTP/1.1 - H2 POST can be added later *)
+  let h1_config : H1_client.config =
+    {
+      connect_timeout = config.connect_timeout;
+      read_timeout = config.read_timeout;
+      write_timeout = config.write_timeout;
+      follow_redirects = config.follow_redirects;
+      buffer_size = config.buffer_size;
+      max_response_body = config.max_response_body;
+      tls = config.tls;
+      default_headers = config.default_headers;
+    }
+  in
+  match
+    H1_client.post ~sw ~net ~clock ~config:h1_config url ~body:request_body
+  with
+  | Ok resp ->
+      Ok
+        {
+          status = h1_status_to_int resp.H1_client.status;
+          headers = h1_headers_to_list resp.headers;
+          body = resp.body;
+          protocol = HTTP_1_1;
+        }
+  | Error (H1_client.Connection_failed msg) -> Error (Connection_failed msg)
+  | Error (H1_client.Tls_error msg) -> Error (Tls_error msg)
+  | Error H1_client.Timeout -> Error Timeout
+  | Error (H1_client.Invalid_response msg) -> Error (Invalid_response msg)
+  | Error H1_client.Too_many_redirects -> Error Too_many_redirects

lib/codec.ml

···
+(** CODEC module for type-safe serialization/deserialization.
+
+    This module provides a signature for codecs that can encode and decode
+    values to/from binary buffers. Users implement this signature with their
+    preferred serialization library (yojson, jsonm, msgpck, etc.).
+
+    The library itself does not depend on any specific serialization library. *)
+
+(** {1 CODEC Signature} *)
+
+(** Module signature for codecs.
+
+    Codecs provide encoding/decoding between OCaml values and binary buffers.
+    The Cstruct.t type is used for efficient zero-copy binary handling. *)
+module type CODEC = sig
+  type 'a encoder
+  (** Encoder for type 'a - converts values to binary format *)
+
+  type 'a decoder
+  (** Decoder for type 'a - parses values from binary format *)
+
+  val content_type : string
+  (** Content-Type header value for this codec. Examples: "application/json",
+      "application/msgpack", "application/cbor" *)
+
+  val encode : 'a encoder -> 'a -> (Cstruct.t, string) result
+  (** Encode a value to a buffer. Returns Error with message on encoding
+      failure. *)
+
+  val decode : 'a decoder -> Cstruct.t -> ('a, string) result
+  (** Decode a value from a buffer. Returns Error with message on decoding
+      failure. *)
+
+  val encode_stream : 'a encoder -> 'a -> Cstruct.t Seq.t option
+  (** Optional: Streaming encode for large payloads. Returns None if streaming
+      is not supported. *)
+
+  val decode_stream :
+    'a decoder -> Cstruct.t Seq.t -> ('a, string) result option
+  (** Optional: Streaming decode for large payloads. Returns None if streaming
+      is not supported. *)
+end
+
+(** {1 With_codec Functor} *)
+
+(** Error type for codec operations *)
+type codec_error =
+  | Encode_error of string
+  | Decode_error of string
+  | Unsupported_body_type
+
+let codec_error_to_string = function
+  | Encode_error msg -> "Encode error: " ^ msg
+  | Decode_error msg -> "Decode error: " ^ msg
+  | Unsupported_body_type -> "Unsupported body type for codec operation"
+
+(** Functor that provides helpers for working with a specific codec.
+
+    This functor generates request/response helpers that automatically set
+    Content-Type headers and handle encoding/decoding. *)
+module With_codec (C : CODEC) = struct
+  (** Encode a value to a string body *)
+  let encode_body encoder value =
+    match C.encode encoder value with
+    | Ok buf -> Ok (Cstruct.to_string buf)
+    | Error msg -> Error (Encode_error msg)
+
+  (** Decode a string body to a value *)
+  let decode_body decoder body_str =
+    let buf = Cstruct.of_string body_str in
+    match C.decode decoder buf with
+    | Ok value -> Ok value
+    | Error msg -> Error (Decode_error msg)
+
+  (** Encode a value directly to Cstruct *)
+  let encode encoder value =
+    match C.encode encoder value with
+    | Ok buf -> Ok buf
+    | Error msg -> Error (Encode_error msg)
+
+  (** Decode a Cstruct to a value *)
+  let decode decoder buf =
+    match C.decode decoder buf with
+    | Ok value -> Ok value
+    | Error msg -> Error (Decode_error msg)
+
+  (** Get the content type for this codec *)
+  let content_type = C.content_type
+end
+
+(** {1 Example Implementations}
+
+    These are examples showing how to implement codecs. Users should implement
+    their own codecs with their preferred libraries.
+
+    {2 JSON Example}
+
+    {[
+      module Json_codec : Hcs.Codec.CODEC = struct
+        (* Using yojson as an example *)
+        type 'a encoder = 'a -> Yojson.Safe.t
+        type 'a decoder = Yojson.Safe.t -> ('a, string) result
+
+        let content_type = "application/json"
+
+        let encode enc value =
+          try Ok (Cstruct.of_string (Yojson.Safe.to_string (enc value)))
+          with exn -> Error (Printexc.to_string exn)
+
+        let decode dec buf =
+          try
+            let json = Yojson.Safe.from_string (Cstruct.to_string buf) in
+            dec json
+          with exn -> Error (Printexc.to_string exn)
+
+        let encode_stream _ _ = None
+        let decode_stream _ _ = None
+      end
+    ]}
+
+    {2 MessagePack Example}
+
+    {[
+      module Msgpack_codec : Hcs.Codec.CODEC = struct
+        type 'a encoder = 'a -> Msgpck.t
+        type 'a decoder = Msgpck.t -> ('a, string) result
+
+        let content_type = "application/msgpack"
+
+        let encode enc value =
+          try
+            let packed =
+              Msgpck.Bytes.to_string (Msgpck.Bytes.of_msgpck (enc value))
+            in
+            Ok (Cstruct.of_string packed)
+          with exn -> Error (Printexc.to_string exn)
+
+        let decode dec buf =
+          try
+            match
+              Msgpck.Bytes.read (Bytes.of_string (Cstruct.to_string buf))
+            with
+            | Some (msgpack, _) -> dec msgpack
+            | None -> Error "Failed to parse msgpack"
+          with exn -> Error (Printexc.to_string exn)
+
+        let encode_stream _ _ = None
+        let decode_stream _ _ = None
+      end
+    ]}
+
+    {2 Plain Text Codec}
+
+    {[
+      module Text_codec : Hcs.Codec.CODEC = struct
+        type 'a encoder = 'a -> string
+        type 'a decoder = string -> ('a, string) result
+
+        let content_type = "text/plain; charset=utf-8"
+        let encode enc value = Ok (Cstruct.of_string (enc value))
+        let decode dec buf = dec (Cstruct.to_string buf)
+        let encode_stream _ _ = None
+        let decode_stream _ _ = None
+      end
+    ]} *)
+
+(** {1 Built-in Identity Codec}
+
+    A simple pass-through codec for raw binary data. *)
+module Identity_codec :
+  CODEC
+    with type 'a encoder = 'a -> Cstruct.t
+     and type 'a decoder = Cstruct.t -> ('a, string) result = struct
+  type 'a encoder = 'a -> Cstruct.t
+  type 'a decoder = Cstruct.t -> ('a, string) result
+
+  let content_type = "application/octet-stream"
+
+  let encode enc value =
+    try Ok (enc value) with exn -> Error (Printexc.to_string exn)
+
+  let decode dec buf = dec buf
+  let encode_stream _ _ = None
+  let decode_stream _ _ = None
+end
+
+(** {1 Built-in String Codec}
+
+    A simple codec for UTF-8 text. *)
+module String_codec :
+  CODEC
+    with type 'a encoder = 'a -> string
+     and type 'a decoder = string -> ('a, string) result = struct
+  type 'a encoder = 'a -> string
+  type 'a decoder = string -> ('a, string) result
+
+  let content_type = "text/plain; charset=utf-8"
+
+  let encode enc value =
+    try Ok (Cstruct.of_string (enc value))
+    with exn -> Error (Printexc.to_string exn)
+
+  let decode dec buf = dec (Cstruct.to_string buf)
+  let encode_stream _ _ = None
+  let decode_stream _ _ = None
+end

lib/control.ml

···
+(** Control flow combinators for HCS.
+
+    This module provides runtime-agnostic control flow patterns:
+    - Retry with backoff
+    - Circuit breaker
+    - Rate limiting state
+
+    Time and sleep operations are passed as parameters to keep this module pure
+    and compatible with any runtime (Eio, Lwt). *)
+
+(** Backoff strategies *)
+module Backoff = struct
+  (** Constant delay between retries *)
+  let constant delay _attempt = delay
+
+  (** Exponential backoff: base * 2^attempt *)
+  let exponential ~base attempt = base *. Float.pow 2.0 (Float.of_int attempt)
+
+  (** Exponential backoff with jitter *)
+  let exponential_jitter ~base ~jitter attempt =
+    let delay = exponential ~base attempt in
+    let jitter_amount = delay *. jitter *. (Random.float 2.0 -. 1.0) in
+    max 0.0 (delay +. jitter_amount)
+
+  (** Linear backoff: base * attempt *)
+  let linear ~base attempt = base *. Float.of_int (attempt + 1)
+
+  (** Capped backoff: applies cap to any strategy *)
+  let capped ~max_delay strategy attempt = min max_delay (strategy attempt)
+end
+
+type retry_config = {
+  max_attempts : int;
+  backoff : int -> float;  (** attempt -> delay in seconds *)
+  should_retry : exn -> bool;  (** Which exceptions to retry *)
+}
+(** Retry configuration *)
+
+let default_retry_config =
+  {
+    max_attempts = 3;
+    backoff = Backoff.exponential ~base:1.0;
+    should_retry = (fun _ -> true);
+  }
+
+(** Retry with backoff. [sleep] is provided by the runtime (e.g.,
+    Eio.Time.sleep) *)
+let with_retry ~sleep ~config f =
+  let rec loop attempt =
+    match f () with
+    | result -> Ok result
+    | exception exn
+      when config.should_retry exn && attempt < config.max_attempts ->
+        let delay = config.backoff attempt in
+        sleep delay;
+        loop (attempt + 1)
+    | exception exn -> Error exn
+  in
+  loop 0
+
+(** Circuit breaker states *)
+type circuit_state =
+  | Closed  (** Normal operation *)
+  | Open of float  (** Failing, timestamp when opened *)
+  | Half_open  (** Testing if recovered *)
+
+type circuit_breaker = {
+  mutable state : circuit_state;
+  mutable failure_count : int;
+  failure_threshold : int;
+  reset_timeout : float;  (** Seconds before trying again *)
+  mutable success_count : int;  (** Successes needed to close from half-open *)
+  success_threshold : int;
+}
+(** Circuit breaker *)
+
+(** Create a circuit breaker *)
+let create_breaker ?(failure_threshold = 5) ?(reset_timeout = 30.0)
+    ?(success_threshold = 2) () =
+  {
+    state = Closed;
+    failure_count = 0;
+    failure_threshold;
+    reset_timeout;
+    success_count = 0;
+    success_threshold;
+  }
+
+(** Check if circuit allows requests. [now] is current time in seconds (provided
+    by runtime) *)
+let circuit_allow breaker ~now =
+  match breaker.state with
+  | Closed -> true
+  | Open opened_at ->
+      if now -. opened_at >= breaker.reset_timeout then begin
+        breaker.state <- Half_open;
+        breaker.success_count <- 0;
+        true
+      end
+      else false
+  | Half_open -> true
+
+(** Record a successful call *)
+let circuit_success breaker =
+  match breaker.state with
+  | Closed -> breaker.failure_count <- 0
+  | Half_open ->
+      breaker.success_count <- breaker.success_count + 1;
+      if breaker.success_count >= breaker.success_threshold then begin
+        breaker.state <- Closed;
+        breaker.failure_count <- 0
+      end
+  | Open _ -> ()
+
+(** Record a failed call. [now] is current time (provided by runtime) *)
+let circuit_failure breaker ~now =
+  match breaker.state with
+  | Closed ->
+      breaker.failure_count <- breaker.failure_count + 1;
+      if breaker.failure_count >= breaker.failure_threshold then
+        breaker.state <- Open now
+  | Half_open -> breaker.state <- Open now
+  | Open _ -> ()
+
+(** Execute with circuit breaker. [now] provides current time, [on_open] called
+    when circuit is open *)
+let with_circuit_breaker ~now ~on_open breaker f =
+  if not (circuit_allow breaker ~now) then on_open ()
+  else
+    match f () with
+    | result ->
+        circuit_success breaker;
+        Ok result
+    | exception exn ->
+        circuit_failure breaker ~now;
+        Error exn
+
+type rate_limiter = {
+  mutable tokens : float;
+  mutable last_update : float;
+  rate : float;  (** Tokens per second *)
+  capacity : float;  (** Max tokens *)
+}
+(** Rate limiter state (token bucket) *)
+
+(** Create a rate limiter *)
+let create_rate_limiter ~rate ~capacity =
+  { tokens = capacity; last_update = 0.0; rate; capacity }
+
+(** Try to acquire a token. [now] is current time in seconds *)
+let rate_limit_acquire limiter ~now =
+  (* Refill tokens based on elapsed time *)
+  let elapsed = now -. limiter.last_update in
+  limiter.tokens <-
+    min limiter.capacity (limiter.tokens +. (elapsed *. limiter.rate));
+  limiter.last_update <- now;
+
+  if limiter.tokens >= 1.0 then begin
+    limiter.tokens <- limiter.tokens -. 1.0;
+    true
+  end
+  else false
+
+(** Calculate wait time until a token is available *)
+let rate_limit_wait_time limiter =
+  if limiter.tokens >= 1.0 then 0.0 else (1.0 -. limiter.tokens) /. limiter.rate

lib/dune

···
+(library
+ (name hcs)
+ (public_name hcs)
+ (libraries eio eio.unix h1 h2 tls-eio tls ca-certs x509 ptime ptime.clock.os cstruct uri digestif base64 bigstringaf faraday))

lib/h1_client.ml

···
+(** HTTP/1.1 Client implementation using h1.
+
+    This module provides HTTP/1.1 client functionality built on Eio. *)
+
+(** {1 Configuration} *)
+
+type config = {
+  (* Timeouts *)
+  connect_timeout : float;  (** Connection timeout in seconds. Default: 30.0 *)
+  read_timeout : float;  (** Read timeout in seconds. Default: 30.0 *)
+  write_timeout : float;  (** Write timeout in seconds. Default: 30.0 *)
+  (* Behavior *)
+  follow_redirects : int option;
+      (** Max redirects to follow. None = don't follow. Default: Some 10 *)
+  (* Buffers *)
+  buffer_size : int;  (** Read buffer size. Default: 16384 *)
+  max_response_body : int64 option;
+      (** Max response body size. None = unlimited. Default: None *)
+  (* TLS *)
+  tls : Tls_config.Client.t;  (** TLS configuration *)
+  (* Headers *)
+  default_headers : (string * string) list;
+      (** Headers to add to every request *)
+}
+(** Client configuration *)
+
+let default_config =
+  {
+    connect_timeout = 30.0;
+    read_timeout = 30.0;
+    write_timeout = 30.0;
+    follow_redirects = Some 10;
+    buffer_size = 16384;
+    max_response_body = None;
+    tls = Tls_config.Client.default;
+    default_headers = [ ("User-Agent", "hcs/0.1.0") ];
+  }
+
+(** {2 Config builders} *)
+
+let with_timeout timeout config =
+  { config with connect_timeout = timeout; read_timeout = timeout }
+
+let with_connect_timeout timeout config =
+  { config with connect_timeout = timeout }
+
+let with_read_timeout timeout config = { config with read_timeout = timeout }
+let with_write_timeout timeout config = { config with write_timeout = timeout }
+
+let with_redirects max_redirects config =
+  { config with follow_redirects = Some max_redirects }
+
+let without_redirects config = { config with follow_redirects = None }
+let with_buffer_size size config = { config with buffer_size = size }
+
+let with_max_response_body max_size config =
+  { config with max_response_body = Some max_size }
+
+let with_tls tls config = { config with tls }
+let with_insecure_tls config = { config with tls = Tls_config.Client.insecure }
+
+let with_default_header name value config =
+  { config with default_headers = (name, value) :: config.default_headers }
+
+let with_default_headers headers config =
+  { config with default_headers = headers @ config.default_headers }
+
+(** Error type for client operations *)
+type error =
+  | Connection_failed of string
+  | Tls_error of string
+  | Timeout
+  | Invalid_response of string
+  | Too_many_redirects
+
+type response = { status : H1.Status.t; headers : H1.Headers.t; body : string }
+(** Response type *)
+
+(** Write all IOVecs to the flow *)
+let write_iovecs flow iovecs =
+  let cstructs =
+    List.map
+      (fun iov ->
+        Cstruct.of_bigarray ~off:iov.Httpun_types.IOVec.off
+          ~len:iov.Httpun_types.IOVec.len iov.Httpun_types.IOVec.buffer)
+      iovecs
+  in
+  Eio.Flow.write flow cstructs
+
+(** Read from flow into bigstring buffer *)
+let read_into_bigstring flow buf ~off ~len =
+  let cs = Cstruct.of_bigarray ~off ~len buf in
+  try
+    let n = Eio.Flow.single_read flow cs in
+    `Ok n
+  with End_of_file -> `Eof
+
+(** Resolve hostname to IP address *)
+let resolve_host net host =
+  let addrs = Eio.Net.getaddrinfo_stream net host in
+  match addrs with addr :: _ -> Some addr | [] -> None
+
+(** Perform an HTTP/1.1 request on a connected flow *)
+let do_request ?(request_body = "") flow req =
+  (* Set up response handling *)
+  let response_received = Eio.Promise.create () in
+  let body_buffer = Buffer.create 4096 in
+  let resolved = ref false in
+
+  let resolve_once result =
+    if not !resolved then begin
+      resolved := true;
+      Eio.Promise.resolve (snd response_received) result
+    end
+  in
+
+  let response_handler resp body_reader =
+    let rec read_body () =
+      H1.Body.Reader.schedule_read body_reader
+        ~on_eof:(fun () ->
+          let body = Buffer.contents body_buffer in
+          resolve_once
+            (Ok
+               {
+                 status = resp.H1.Response.status;
+                 headers = resp.headers;
+                 body;
+               }))
+        ~on_read:(fun buf ~off ~len ->
+          Buffer.add_string body_buffer (Bigstringaf.substring buf ~off ~len);
+          read_body ())
+    in
+    read_body ()
+  in
+
+  let error_handler err =
+    let msg =
+      match err with
+      | `Malformed_response s -> s
+      | `Invalid_response_body_length _ -> "Invalid response body length"
+      | `Exn exn -> Printexc.to_string exn
+    in
+    resolve_once (Error (Invalid_response msg))
+  in
+
+  (* Create the client connection *)
+  let body_writer, conn =
+    H1.Client_connection.request req ~error_handler ~response_handler
+  in
+
+  (* Write request body if provided, then close *)
+  if String.length request_body > 0 then begin
+    H1.Body.Writer.write_string body_writer request_body;
+    H1.Body.Writer.flush body_writer (fun () -> ())
+  end;
+  H1.Body.Writer.close body_writer;
+
+  (* Buffer for reading - track unconsumed bytes between reads *)
+  let read_buffer_size = 0x4000 in
+  let read_buffer = Bigstringaf.create read_buffer_size in
+  let unconsumed = ref 0 in
+
+  (* Connection loop - handle both read and write operations *)
+  let rec loop () =
+    (* First, handle any pending writes *)
+    let write_done =
+      match H1.Client_connection.next_write_operation conn with
+      | `Write iovecs ->
+          write_iovecs flow iovecs;
+          let len =
+            List.fold_left
+              (fun acc iov -> acc + iov.Httpun_types.IOVec.len)
+              0 iovecs
+          in
+          H1.Client_connection.report_write_result conn (`Ok len);
+          false
+      | `Yield -> true
+      | `Close _ -> true
+    in
+
+    (* Then handle reads *)
+    let read_done =
+      match H1.Client_connection.next_read_operation conn with
+      | `Read -> (
+          let available = read_buffer_size - !unconsumed in
+          match
+            read_into_bigstring flow read_buffer ~off:!unconsumed ~len:available
+          with
+          | `Ok n ->
+              let total = !unconsumed + n in
+              let consumed =
+                H1.Client_connection.read conn read_buffer ~off:0 ~len:total
+              in
+              (* Shift unconsumed bytes to start of buffer *)
+              let remaining = total - consumed in
+              if remaining > 0 && consumed > 0 then
+                Bigstringaf.blit read_buffer ~src_off:consumed read_buffer
+                  ~dst_off:0 ~len:remaining;
+              unconsumed := remaining;
+              false
+          | `Eof ->
+              let _ =
+                H1.Client_connection.read_eof conn read_buffer ~off:0
+                  ~len:!unconsumed
+              in
+              true)
+      | `Close -> true
+    in
+
+    (* Continue until both read and write are done *)
+    if not (write_done && read_done) then loop ()
+  in
+
+  loop ();
+  Eio.Promise.await (fst response_received)
+
+(** Wrap flow with TLS if needed, returns the flow to use *)
+let maybe_wrap_tls ~config ~host ~is_https flow =
+  if is_https then
+    match Tls_config.Client.to_tls_config config.tls ~host with
+    | Error msg -> Error (Tls_error msg)
+    | Ok tls_config -> (
+        try
+          (* Parse host as domain name for SNI *)
+          let host_domain =
+            match Domain_name.of_string host with
+            | Ok dn -> (
+                match Domain_name.host dn with
+                | Ok h -> Some h
+                | Error _ -> None)
+            | Error _ -> None
+          in
+          let tls_flow =
+            Tls_eio.client_of_flow tls_config ?host:host_domain flow
+          in
+          Ok (tls_flow :> Eio.Flow.two_way_ty Eio.Std.r)
+        with
+        | Tls_eio.Tls_failure failure ->
+            Error (Tls_error (Tls_config.failure_to_string failure))
+        | exn -> Error (Tls_error (Printexc.to_string exn)))
+  else Ok (flow :> Eio.Flow.two_way_ty Eio.Std.r)
+
+(** Perform a GET request *)
+let get ~sw ~net ~clock ?(config = default_config) url =
+  let uri = Uri.of_string url in
+  let scheme = Uri.scheme uri |> Option.value ~default:"http" in
+  let is_https = String.equal scheme "https" in
+  let host = Uri.host uri |> Option.value ~default:"localhost" in
+  let default_port = if is_https then 443 else 80 in
+  let port = Uri.port uri |> Option.value ~default:default_port in
+  let path = Uri.path_and_query uri in
+  let path = if path = "" then "/" else path in
+
+  (* Wrap in timeout - use with_timeout_exn and catch the exception *)
+  let total_timeout = config.connect_timeout +. config.read_timeout in
+  try
+    Eio.Time.with_timeout_exn clock total_timeout @@ fun () ->
+    match resolve_host net host with
+    | None -> Error (Connection_failed ("Cannot resolve host: " ^ host))
+    | Some addr_info -> (
+        let addr =
+          match addr_info with
+          | `Tcp (ip, _) -> `Tcp (ip, port)
+          | `Unix _ -> failwith "Unix sockets not supported"
+        in
+        let tcp_flow = Eio.Net.connect ~sw net addr in
+
+        (* Wrap with TLS if HTTPS *)
+        match maybe_wrap_tls ~config ~host ~is_https tcp_flow with
+        | Error e -> Error e
+        | Ok flow ->
+            let req =
+              H1.Request.create
+                ~headers:
+                  (H1.Headers.of_list
+                     [ ("Host", host); ("Connection", "keep-alive") ])
+                `GET path
+            in
+            do_request flow req)
+  with Eio.Time.Timeout -> Error Timeout
+
+(** Perform a POST request with body *)
+let post ~sw ~net ~clock ?(config = default_config) url ~body:request_body =
+  let uri = Uri.of_string url in
+  let scheme = Uri.scheme uri |> Option.value ~default:"http" in
+  let is_https = String.equal scheme "https" in
+  let host = Uri.host uri |> Option.value ~default:"localhost" in
+  let default_port = if is_https then 443 else 80 in
+  let port = Uri.port uri |> Option.value ~default:default_port in
+  let path = Uri.path_and_query uri in
+  let path = if path = "" then "/" else path in
+
+  (* Wrap in timeout *)
+  let total_timeout = config.connect_timeout +. config.read_timeout in
+  try
+    Eio.Time.with_timeout_exn clock total_timeout @@ fun () ->
+    match resolve_host net host with
+    | None -> Error (Connection_failed ("Cannot resolve host: " ^ host))
+    | Some addr_info -> (
+        let addr =
+          match addr_info with
+          | `Tcp (ip, _) -> `Tcp (ip, port)
+          | `Unix _ -> failwith "Unix sockets not supported"
+        in
+        let tcp_flow = Eio.Net.connect ~sw net addr in
+
+        (* Wrap with TLS if HTTPS *)
+        match maybe_wrap_tls ~config ~host ~is_https tcp_flow with
+        | Error e -> Error e
+        | Ok flow ->
+            let content_length = String.length request_body in
+            let req =
+              H1.Request.create
+                ~headers:
+                  (H1.Headers.of_list
+                     [
+                       ("Host", host);
+                       ("Connection", "keep-alive");
+                       ("Content-Length", string_of_int content_length);
+                     ])
+                `POST path
+            in
+            do_request ~request_body flow req)
+  with Eio.Time.Timeout -> Error Timeout

lib/h1_server.ml

···
+(** HTTP/1.1 Server implementation using h1.
+
+    This module provides HTTP/1.1 server functionality built on Eio.
+
+    Features:
+    - Lazy body reading: request body is not read until accessed
+    - Zero-copy responses: bigstring bodies avoid copying
+    - Streaming responses: write large responses without buffering
+    - Connection pooling via buffer reuse *)
+
+open Eio.Std
+
+(** {1 Read Buffer Pool} *)
+
+module Read_buffer_pool : sig
+  val acquire : unit -> Bigstringaf.t * Cstruct.t
+  val release : Bigstringaf.t -> unit
+end = struct
+  let buffer_size = 0x4000
+
+  let acquire () =
+    let buf = Bigstringaf.create buffer_size in
+    (buf, Cstruct.of_bigarray buf ~off:0 ~len:buffer_size)
+
+  let release _ = ()
+end
+
+(** {1 Configuration} *)
+
+type config = {
+  (* Network *)
+  host : string;  (** Bind address. Default: "0.0.0.0" *)
+  port : int;  (** Listen port. Default: 8080 *)
+  backlog : int;  (** Listen backlog. Default: 2048 *)
+  max_connections : int;  (** Max concurrent connections. Default: 10000 *)
+  (* Parallelism *)
+  domain_count : int;  (** Number of domains (CPUs) to use. Default: 1 *)
+  (* Timeouts *)
+  read_timeout : float;  (** Read timeout in seconds. Default: 60.0 *)
+  write_timeout : float;  (** Write timeout in seconds. Default: 60.0 *)
+  idle_timeout : float;  (** Idle connection timeout. Default: 120.0 *)
+  request_timeout : float;  (** Request processing timeout. Default: 30.0 *)
+  (* Limits *)
+  max_header_size : int;  (** Max header size in bytes. Default: 8192 *)
+  max_body_size : int64 option;
+      (** Max body size. None = unlimited. Default: None *)
+  (* Buffers *)
+  buffer_size : int;  (** Read buffer size. Default: 16384 *)
+  (* TLS *)
+  tls : Tls_config.Server.t option;  (** TLS config. None = plain HTTP *)
+  (* Socket options *)
+  tcp_nodelay : bool;  (** Enable TCP_NODELAY (disable Nagle). Default: true *)
+  reuse_addr : bool;  (** Enable SO_REUSEADDR. Default: true *)
+  reuse_port : bool;
+      (** Enable SO_REUSEPORT for multi-process scaling. Default: true *)
+}
+(** Server configuration *)
+
+let default_config =
+  {
+    host = "0.0.0.0";
+    port = 8080;
+    backlog = 2048;
+    max_connections = 10000;
+    domain_count = 1;
+    read_timeout = 60.0;
+    write_timeout = 60.0;
+    idle_timeout = 120.0;
+    request_timeout = 30.0;
+    max_header_size = 8192;
+    max_body_size = None;
+    buffer_size = 16384;
+    tls = None;
+    tcp_nodelay = true;
+    reuse_addr = true;
+    reuse_port = true;
+  }
+
+(** {2 Config builders} *)
+
+let with_port port config = { config with port }
+let with_host host config = { config with host }
+let with_backlog backlog config = { config with backlog }
+let with_max_connections max config = { config with max_connections = max }
+let with_read_timeout timeout config = { config with read_timeout = timeout }
+let with_write_timeout timeout config = { config with write_timeout = timeout }
+let with_idle_timeout timeout config = { config with idle_timeout = timeout }
+
+let with_request_timeout timeout config =
+  { config with request_timeout = timeout }
+
+let with_domain_count count config = { config with domain_count = count }
+let with_max_header_size size config = { config with max_header_size = size }
+let with_max_body_size size config = { config with max_body_size = Some size }
+let with_buffer_size size config = { config with buffer_size = size }
+let with_tls tls config = { config with tls = Some tls }
+let with_tcp_nodelay enabled config = { config with tcp_nodelay = enabled }
+let with_reuse_addr enabled config = { config with reuse_addr = enabled }
+let with_reuse_port enabled config = { config with reuse_port = enabled }
+
+(** {1 GC Tuning} *)
+
+type gc_config = {
+  minor_heap_size : int;
+  major_heap_increment : int;
+  space_overhead : int;
+  max_overhead : int;
+}
+
+let default_gc_config =
+  {
+    minor_heap_size = 64 * 1024 * 1024;
+    major_heap_increment = 16 * 1024 * 1024;
+    space_overhead = 120;
+    max_overhead = 500;
+  }
+
+let tune_gc ?(config = default_gc_config) () =
+  let ctrl = Gc.get () in
+  Gc.set
+    {
+      ctrl with
+      minor_heap_size = config.minor_heap_size / (Sys.word_size / 8);
+      major_heap_increment = config.major_heap_increment / (Sys.word_size / 8);
+      space_overhead = config.space_overhead;
+      max_overhead = config.max_overhead;
+    }
+
+let gc_tuned = ref false
+
+let ensure_gc_tuned () =
+  if not !gc_tuned then begin
+    tune_gc ();
+    gc_tuned := true
+  end
+
+(** {1 Cached Date Header} *)
+
+module Date_cache : sig
+  val get : unit -> string
+end = struct
+  let day_names = [| "Sun"; "Mon"; "Tue"; "Wed"; "Thu"; "Fri"; "Sat" |]
+
+  let month_names =
+    [|
+      "Jan";
+      "Feb";
+      "Mar";
+      "Apr";
+      "May";
+      "Jun";
+      "Jul";
+      "Aug";
+      "Sep";
+      "Oct";
+      "Nov";
+      "Dec";
+    |]
+
+  let cached_date = Atomic.make ""
+  let cached_time = Atomic.make 0.
+
+  let format_date () =
+    let t = Unix.gettimeofday () in
+    let tm = Unix.gmtime t in
+    Printf.sprintf "%s, %02d %s %04d %02d:%02d:%02d GMT"
+      day_names.(tm.Unix.tm_wday)
+      tm.Unix.tm_mday
+      month_names.(tm.Unix.tm_mon)
+      (1900 + tm.Unix.tm_year) tm.Unix.tm_hour tm.Unix.tm_min tm.Unix.tm_sec
+
+  let get () =
+    let now = Unix.gettimeofday () in
+    let last = Atomic.get cached_time in
+    if now -. last >= 1.0 then begin
+      let date = format_date () in
+      Atomic.set cached_date date;
+      Atomic.set cached_time now;
+      date
+    end
+    else Atomic.get cached_date
+end
+
+(** {1 Cached Prebuilt Response} *)
+
+type cached_prebuilt = {
+  base_response : H1.Response.t;
+  body : Bigstringaf.t;
+  cached_response : H1.Response.t Atomic.t;
+  cached_second : int Atomic.t;
+}
+
+let make_cached_prebuilt h1_response body =
+  let now = int_of_float (Unix.gettimeofday ()) in
+  let headers =
+    H1.Headers.add h1_response.H1.Response.headers "Date" (Date_cache.get ())
+  in
+  let resp = H1.Response.create ~headers h1_response.H1.Response.status in
+  {
+    base_response = h1_response;
+    body;
+    cached_response = Atomic.make resp;
+    cached_second = Atomic.make now;
+  }
+
+let[@inline] get_cached_response cached =
+  let now = int_of_float (Unix.gettimeofday ()) in
+  let last = Atomic.get cached.cached_second in
+  if now <> last then begin
+    let headers =
+      H1.Headers.add cached.base_response.H1.Response.headers "Date"
+        (Date_cache.get ())
+    in
+    let resp =
+      H1.Response.create ~headers cached.base_response.H1.Response.status
+    in
+    Atomic.set cached.cached_response resp;
+    Atomic.set cached.cached_second now
+  end;
+  Atomic.get cached.cached_response
+
+(** {1 Socket Helpers} *)
+
+let set_tcp_nodelay flow =
+  match Eio_unix.Resource.fd_opt flow with
+  | None -> ()
+  | Some fd ->
+      Eio_unix.Fd.use_exn "set_tcp_nodelay" fd (fun unix_fd ->
+          Unix.setsockopt unix_fd Unix.TCP_NODELAY true)
+
+(** {1 Body Types} *)
+
+type body_reader = {
+  read : unit -> string;
+      (** Read the entire body as a string. Can only be called once. *)
+  read_stream : unit -> Cstruct.t option;
+      (** Read body in chunks. Returns None when done. *)
+  close : unit -> unit;  (** Close the body reader without reading. *)
+}
+(** Lazy body reader - body is only read when [read] is called *)
+
+(** Response body - supports string, bigstring, streaming, and pre-built *)
+type response_body =
+  | Body_string of string
+  | Body_bigstring of Bigstringaf.t
+  | Body_prebuilt of { h1_response : H1.Response.t; body : Bigstringaf.t }
+  | Body_cached_prebuilt of cached_prebuilt
+  | Body_stream of {
+      content_length : int64 option;
+      next : unit -> Cstruct.t option;
+    }
+
+(** {1 Request and Response Types} *)
+
+type request = {
+  meth : H1.Method.t;
+  target : string;
+  headers : H1.Headers.t;
+  body_reader : body_reader;
+      (** Lazy body reader - call [body_reader.read ()] to get the body *)
+}
+(** Request type with lazy body reading *)
+
+(** Read the request body as a string (convenience function) *)
+let read_body req = req.body_reader.read ()
+
+(** Read the request body as a stream (for large bodies) *)
+let read_body_stream req = req.body_reader.read_stream
+
+(** Close the request body without reading (for ignored bodies) *)
+let close_body req = req.body_reader.close ()
+
+type response = {
+  status : H1.Status.t;
+  headers : (string * string) list;
+  response_body : response_body;
+}
+(** Response type with optimized body variants *)
+
+type handler = request -> response
+(** Handler type *)
+
+let respond ?(status = `OK) ?(headers = []) body =
+  { status; headers; response_body = Body_string body }
+
+let respond_bigstring ?(status = `OK) ?(headers = []) bstr =
+  { status; headers; response_body = Body_bigstring bstr }
+
+let respond_stream ?(status = `OK) ?(headers = []) ?content_length next =
+  { status; headers; response_body = Body_stream { content_length; next } }
+
+let respond_prebuilt h1_response body =
+  {
+    status = `OK;
+    headers = [];
+    response_body = Body_prebuilt { h1_response; body };
+  }
+
+let respond_cached_prebuilt cached =
+  { status = `OK; headers = []; response_body = Body_cached_prebuilt cached }
+
+type static_response = response
+
+let make_static_response cached : static_response =
+  { status = `OK; headers = []; response_body = Body_cached_prebuilt cached }
+
+let[@inline always] respond_static (r : static_response) : response = r
+let make_h1_headers headers_list = H1.Headers.of_list headers_list
+
+let make_h1_response ?(status = `OK) headers =
+  H1.Response.create ~headers status
+
+(** {1 Internal Helpers} *)
+
+(** Write all IOVecs to the flow - optimized version *)
+let write_iovecs flow iovecs =
+  match iovecs with
+  | [] -> ()
+  | [ iov ] ->
+      (* Fast path for single iovec - common case *)
+      let cs =
+        Cstruct.of_bigarray ~off:iov.Httpun_types.IOVec.off
+          ~len:iov.Httpun_types.IOVec.len iov.Httpun_types.IOVec.buffer
+      in
+      Eio.Flow.write flow [ cs ]
+  | _ ->
+      (* Multiple iovecs - build list directly *)
+      let cstructs =
+        List.map
+          (fun iov ->
+            Cstruct.of_bigarray ~off:iov.Httpun_types.IOVec.off
+              ~len:iov.Httpun_types.IOVec.len iov.Httpun_types.IOVec.buffer)
+          iovecs
+      in
+      Eio.Flow.write flow cstructs
+
+(** Check if method typically has no body *)
+let[@inline] method_has_no_body = function
+  | `GET | `HEAD | `DELETE | `OPTIONS | `CONNECT | `TRACE -> true
+  | `POST | `PUT | `PATCH | `Other _ -> false
+
+(** Create a lazy body reader from H1's body reader *)
+let make_body_reader (h1_body : H1.Body.Reader.t) : body_reader =
+  let read_called = ref false in
+  let closed = ref false in
+  let chunks = ref [] in
+  let done_promise, done_resolver = Eio.Promise.create () in
+
+  (* Start reading in background - will block until first chunk or EOF *)
+  let rec schedule_read () =
+    if not !closed then
+      H1.Body.Reader.schedule_read h1_body
+        ~on_eof:(fun () -> Eio.Promise.resolve done_resolver ())
+        ~on_read:(fun buf ~off ~len ->
+          (* Store chunk as Cstruct to avoid copying bigstring *)
+          let chunk = Cstruct.of_bigarray ~off ~len buf |> Cstruct.to_string in
+          chunks := chunk :: !chunks;
+          schedule_read ())
+  in
+
+  {
+    read =
+      (fun () ->
+        if !read_called then failwith "Body already read"
+        else begin
+          read_called := true;
+          if !closed then ""
+          else begin
+            schedule_read ();
+            Eio.Promise.await done_promise;
+            String.concat "" (List.rev !chunks)
+          end
+        end);
+    read_stream =
+      (fun () ->
+        (* For streaming, we read one chunk at a time *)
+        if !closed then None
+        else begin
+          let chunk_promise, chunk_resolver = Eio.Promise.create () in
+          let got_chunk = ref false in
+          H1.Body.Reader.schedule_read h1_body
+            ~on_eof:(fun () ->
+              if not !got_chunk then Eio.Promise.resolve chunk_resolver None)
+            ~on_read:(fun buf ~off ~len ->
+              got_chunk := true;
+              let cs = Cstruct.of_bigarray ~off ~len buf in
+              Eio.Promise.resolve chunk_resolver (Some cs));
+          Eio.Promise.await chunk_promise
+        end);
+    close =
+      (fun () ->
+        if not !closed then begin
+          closed := true;
+          H1.Body.Reader.close h1_body
+        end);
+  }
+
+(** Create a no-op body reader for methods without bodies *)
+let empty_body_reader () : body_reader =
+  {
+    read = (fun () -> "");
+    read_stream = (fun () -> None);
+    close = (fun () -> ());
+  }
+
+let handle_connection handler flow =
+  let read_buffer, read_cstruct = Read_buffer_pool.acquire () in
+  Fun.protect ~finally:(fun () -> Read_buffer_pool.release read_buffer)
+  @@ fun () ->
+  let request_handler reqd =
+    let req = H1.Reqd.request reqd in
+    let h1_body = H1.Reqd.request_body reqd in
+
+    (* Create lazy body reader *)
+    let body_reader =
+      if method_has_no_body req.H1.Request.meth then begin
+        H1.Body.Reader.close h1_body;
+        empty_body_reader ()
+      end
+      else make_body_reader h1_body
+    in
+
+    (* Build request with lazy body *)
+    let request =
+      {
+        meth = req.H1.Request.meth;
+        target = req.target;
+        headers = req.headers;
+        body_reader;
+      }
+    in
+
+    (* Call user handler *)
+    let response = handler request in
+
+    (* Ensure body is closed if not read *)
+    body_reader.close ();
+
+    let date_header = ("Date", Date_cache.get ()) in
+    let filter_reserved headers =
+      List.filter
+        (fun (k, _) ->
+          let lk = String.lowercase_ascii k in
+          lk <> "content-length" && lk <> "date")
+        headers
+    in
+
+    match response.response_body with
+    | Body_string body ->
+        let content_length = String.length body in
+        let headers =
+          H1.Headers.of_list
+            (date_header
+            :: ("Content-Length", string_of_int content_length)
+            :: filter_reserved response.headers)
+        in
+        let resp = H1.Response.create ~headers response.status in
+        H1.Reqd.respond_with_string reqd resp body
+    | Body_bigstring bstr ->
+        let content_length = Bigstringaf.length bstr in
+        let headers =
+          H1.Headers.of_list
+            (date_header
+            :: ("Content-Length", string_of_int content_length)
+            :: filter_reserved response.headers)
+        in
+        let resp = H1.Response.create ~headers response.status in
+        H1.Reqd.respond_with_bigstring reqd resp bstr
+    | Body_prebuilt { h1_response; body } ->
+        let headers =
+          H1.Headers.add h1_response.headers "Date" (Date_cache.get ())
+        in
+        let resp = { h1_response with H1.Response.headers } in
+        H1.Reqd.respond_with_bigstring reqd resp body
+    | Body_cached_prebuilt cached ->
+        let resp = get_cached_response cached in
+        H1.Reqd.respond_with_bigstring reqd resp cached.body
+    | Body_stream { content_length; next } ->
+        let headers =
+          match content_length with
+          | Some len ->
+              H1.Headers.of_list
+                (date_header
+                :: ("Content-Length", Int64.to_string len)
+                :: filter_reserved response.headers)
+          | None ->
+              H1.Headers.of_list
+                (date_header
+                :: ("Transfer-Encoding", "chunked")
+                :: filter_reserved response.headers)
+        in
+        let resp = H1.Response.create ~headers response.status in
+        let body_writer = H1.Reqd.respond_with_streaming reqd resp in
+        (* Write chunks *)
+        let rec write_chunks () =
+          match next () with
+          | None -> H1.Body.Writer.close body_writer
+          | Some cs ->
+              H1.Body.Writer.write_bigstring body_writer ~off:0
+                ~len:(Cstruct.length cs) (Cstruct.to_bigarray cs);
+              write_chunks ()
+        in
+        write_chunks ()
+  in
+
+  let error_handler ?request:_ _error start_response =
+    let resp_body = start_response H1.Headers.empty in
+    H1.Body.Writer.write_string resp_body "Internal Server Error";
+    H1.Body.Writer.close resp_body
+  in
+
+  let conn = H1.Server_connection.create ~error_handler request_handler in
+
+  let shutdown = ref false in
+
+  let rec read_loop () =
+    if not !shutdown then
+      match H1.Server_connection.next_read_operation conn with
+      | `Read -> (
+          try
+            let n = Eio.Flow.single_read flow read_cstruct in
+            let _ = H1.Server_connection.read conn read_buffer ~off:0 ~len:n in
+            read_loop ()
+          with End_of_file ->
+            let _ =
+              H1.Server_connection.read_eof conn read_buffer ~off:0 ~len:0
+            in
+            shutdown := true)
+      | `Yield -> H1.Server_connection.yield_reader conn read_loop
+      | `Close | `Upgrade -> shutdown := true
+  in
+
+  let rec write_loop () =
+    if not !shutdown then
+      match H1.Server_connection.next_write_operation conn with
+      | `Write iovecs ->
+          write_iovecs flow iovecs;
+          let len =
+            List.fold_left
+              (fun acc iov -> acc + iov.Httpun_types.IOVec.len)
+              0 iovecs
+          in
+          H1.Server_connection.report_write_result conn (`Ok len);
+          write_loop ()
+      | `Yield -> H1.Server_connection.yield_writer conn write_loop
+      | `Upgrade -> shutdown := true
+      | `Close _ -> shutdown := true
+  in
+
+  Fiber.both read_loop write_loop
+
+let run ~sw ~net ?(config = default_config) handler =
+  ensure_gc_tuned ();
+  let addr = `Tcp (Eio.Net.Ipaddr.V4.any, config.port) in
+  let socket =
+    Eio.Net.listen ~sw ~backlog:config.backlog ~reuse_addr:config.reuse_addr
+      ~reuse_port:config.reuse_port net addr
+  in
+  traceln "Server listening on port %d" config.port;
+  let connection_handler flow _addr =
+    if config.tcp_nodelay then set_tcp_nodelay flow;
+    handle_connection handler flow
+  in
+  let on_error exn = traceln "Connection error: %s" (Printexc.to_string exn) in
+  Eio.Net.run_server socket connection_handler
+    ~max_connections:config.max_connections ~on_error
+
+let run_parallel ~sw ~net ~domain_mgr ?(config = default_config) handler =
+  ensure_gc_tuned ();
+  let domain_count = max 1 config.domain_count in
+  let addr = `Tcp (Eio.Net.Ipaddr.V4.any, config.port) in
+  let socket =
+    Eio.Net.listen ~sw ~backlog:config.backlog ~reuse_addr:config.reuse_addr
+      ~reuse_port:config.reuse_port net addr
+  in
+  traceln "Server listening on port %d (%d domains)" config.port domain_count;
+  let connection_handler flow _addr =
+    if config.tcp_nodelay then set_tcp_nodelay flow;
+    handle_connection handler flow
+  in
+  let on_error exn = traceln "Connection error: %s" (Printexc.to_string exn) in
+  if domain_count <= 1 then
+    Eio.Net.run_server socket connection_handler
+      ~max_connections:config.max_connections ~on_error
+  else
+    Eio.Net.run_server socket connection_handler
+      ~max_connections:config.max_connections ~on_error
+      ~additional_domains:(domain_mgr, domain_count - 1)

lib/h2_client.ml

···
+(** HTTP/2 Client implementation using h2.
+
+    This module provides HTTP/2 client functionality built on the h2 library
+    with Eio for structured concurrency. *)
+
+open Eio.Std
+
+(** {1 Types} *)
+
+type error =
+  | Connection_failed of string
+  | Tls_error of string
+  | Protocol_error of string
+  | Timeout
+  | Invalid_response of string
+
+type response = { status : H2.Status.t; headers : H2.Headers.t; body : string }
+
+(** {1 Internal helpers} *)
+
+(** Write IOVecs to the flow, returns bytes written or `Closed *)
+let writev flow iovecs =
+  let lenv, cstructs =
+    List.fold_left_map
+      (fun acc iov ->
+        let len = iov.H2.IOVec.len in
+        let cs =
+          Cstruct.of_bigarray ~off:iov.H2.IOVec.off ~len iov.H2.IOVec.buffer
+        in
+        (acc + len, cs))
+      0 iovecs
+  in
+  match Eio.Flow.write flow cstructs with
+  | () -> `Ok lenv
+  | exception End_of_file -> `Closed
+
+(** Shutdown flow in specified direction *)
+let shutdown flow cmd =
+  try Eio.Flow.shutdown flow cmd with
+  | Unix.Unix_error (Unix.ENOTCONN, _, _) -> ()
+  | Eio.Io (Eio.Net.E (Eio.Net.Connection_reset _), _) -> ()
+
+(** Simple read buffer that tracks unconsumed data. This is necessary because
+    angstrom (used by h2) tracks uncommitted bytes and will fail if the buffer
+    appears to shrink. Based on Gluten.Buffer pattern. *)
+module Read_buffer : sig
+  type t
+
+  val create : int -> t
+
+  val read : t -> _ Eio.Flow.source -> int
+  (** Read data from flow into the buffer. Returns bytes read. *)
+
+  val get : t -> f:(Bigstringaf.t -> off:int -> len:int -> int) -> int
+  (** Feed buffered data to consumer. Returns bytes consumed. *)
+end = struct
+  type t = {
+    buffer : Bigstringaf.t;
+    mutable off : int; (* Start of unconsumed data *)
+    mutable len : int; (* Length of unconsumed data *)
+    cap : int;
+  }
+
+  let create size =
+    { buffer = Bigstringaf.create size; off = 0; len = 0; cap = size }
+
+  let compress t =
+    if t.len = 0 then begin
+      t.off <- 0;
+      t.len <- 0
+    end
+    else if t.off > 0 then begin
+      Bigstringaf.blit t.buffer ~src_off:t.off t.buffer ~dst_off:0 ~len:t.len;
+      t.off <- 0
+    end
+
+  let read t flow =
+    compress t;
+    let off = t.off + t.len in
+    let available = t.cap - t.len - t.off in
+    if available > 0 then begin
+      let cs = Cstruct.of_bigarray t.buffer ~off ~len:available in
+      let n = Eio.Flow.single_read flow cs in
+      t.len <- t.len + n;
+      n
+    end
+    else 0
+
+  let get t ~f =
+    let n = f t.buffer ~off:t.off ~len:t.len in
+    t.off <- t.off + n;
+    t.len <- t.len - n;
+    if t.len = 0 then t.off <- 0;
+    n
+end
+
+(** {1 Connection handling} *)
+
+(** Perform an HTTP/2 request on a connected flow.
+
+    HTTP/2 requires interleaved read/write handling because: 1. The server may
+    send SETTINGS frames immediately after connection 2. We need to send the
+    client preface and request while receiving 3. Flow control (WINDOW_UPDATE)
+    must be processed promptly
+
+    Note: We use a single-threaded interleaved approach rather than Fiber.both
+    because TLS flows are not safe for concurrent read/write operations. *)
+let do_request flow req =
+  let response_received = Eio.Promise.create () in
+  let body_buffer = Buffer.create 4096 in
+  let resolved = ref false in
+
+  let resolve_once result =
+    if not !resolved then begin
+      resolved := true;
+      Eio.Promise.resolve (snd response_received) result
+    end
+  in
+
+  let response_handler resp body_reader =
+    let rec read_body () =
+      H2.Body.Reader.schedule_read body_reader
+        ~on_eof:(fun () ->
+          let body = Buffer.contents body_buffer in
+          resolve_once
+            (Ok
+               {
+                 status = resp.H2.Response.status;
+                 headers = resp.headers;
+                 body;
+               }))
+        ~on_read:(fun buf ~off ~len ->
+          Buffer.add_string body_buffer (Bigstringaf.substring buf ~off ~len);
+          read_body ())
+    in
+    read_body ()
+  in
+
+  let error_handler err =
+    let msg =
+      match err with
+      | `Malformed_response s -> "Malformed response: " ^ s
+      | `Invalid_response_body_length _ -> "Invalid response body length"
+      | `Protocol_error (code, msg) ->
+          Printf.sprintf "Protocol error %s: %s"
+            (H2.Error_code.to_string code)
+            msg
+      | `Exn exn -> Printexc.to_string exn
+    in
+    resolve_once (Error (Invalid_response msg))
+  in
+
+  (* Create the HTTP/2 client connection *)
+  let conn = H2.Client_connection.create ~error_handler () in
+
+  (* We'll queue the request after writing the connection preface *)
+  let request_sent = ref false in
+  let send_request () =
+    if not !request_sent then begin
+      request_sent := true;
+      (* Send the request and immediately close the body to signal END_STREAM.
+         For GET requests, the body writer should be closed immediately which
+         sets the END_STREAM flag on the HEADERS frame. *)
+      let body_writer =
+        H2.Client_connection.request conn req
+          ~flush_headers_immediately:true (* Send HEADERS right away *)
+          ~error_handler ~response_handler
+      in
+      (* Close immediately for requests with no body *)
+      H2.Body.Writer.close body_writer
+    end
+  in
+
+  (* Buffer for reading - tracks unconsumed data properly *)
+  let read_buffer = Read_buffer.create 0x4000 in
+
+  (* Flag to track if we've sent the request *)
+  let request_queued = ref false in
+
+  (* Read loop - runs concurrently with write loop.
+     Uses the gluten pattern: read from network first, then feed to h2. *)
+  let read_loop () =
+    let rec read_loop_step () =
+      match H2.Client_connection.next_read_operation conn with
+      | `Read -> (
+          match Read_buffer.read read_buffer flow with
+          | _n ->
+              (* Feed buffered data to h2 - separate from network read *)
+              let _consumed =
+                Read_buffer.get read_buffer ~f:(fun buf ~off ~len ->
+                    H2.Client_connection.read conn buf ~off ~len)
+              in
+              read_loop_step ()
+          | exception End_of_file ->
+              (* Feed any remaining buffered data as EOF *)
+              let _ =
+                Read_buffer.get read_buffer ~f:(fun buf ~off ~len ->
+                    H2.Client_connection.read_eof conn buf ~off ~len)
+              in
+              ())
+      | `Yield ->
+          let p, u = Eio.Promise.create () in
+          H2.Client_connection.yield_reader conn (fun () ->
+              Eio.Promise.resolve u ());
+          Eio.Promise.await p;
+          read_loop_step ()
+      | `Close -> shutdown flow `Receive
+    in
+    try read_loop_step () with exn -> H2.Client_connection.report_exn conn exn
+  in
+
+  (* Write loop - runs concurrently with read loop *)
+  let write_loop () =
+    let rec loop () =
+      match H2.Client_connection.next_write_operation conn with
+      | `Write iovecs -> (
+          match writev flow iovecs with
+          | `Ok len ->
+              H2.Client_connection.report_write_result conn (`Ok len);
+              (* After first write (connection preface), queue the request *)
+              if not !request_queued then begin
+                request_queued := true;
+                send_request ()
+              end;
+              loop ()
+          | `Closed -> H2.Client_connection.report_write_result conn `Closed)
+      | `Yield ->
+          let p, u = Eio.Promise.create () in
+          H2.Client_connection.yield_writer conn (fun () ->
+              Eio.Promise.resolve u ());
+          Eio.Promise.await p;
+          loop ()
+      | `Close _ -> shutdown flow `Send
+    in
+    try loop () with exn -> H2.Client_connection.report_exn conn exn
+  in
+
+  (* Run read and write loops concurrently until response is received.
+     For a single request, we use Fiber.any to exit when response arrives. *)
+  let io_loops () =
+    Eio.Fiber.both read_loop write_loop;
+    (* If loops exit naturally (connection closed), return error *)
+    Error (Protocol_error "Connection closed before response")
+  in
+
+  let wait_for_response () =
+    let result = Eio.Promise.await (fst response_received) in
+    (* After getting response, shutdown the connection to exit loops *)
+    H2.Client_connection.shutdown conn;
+    result
+  in
+
+  Eio.Fiber.any [ io_loops; wait_for_response ]
+
+(** {1 Public API} *)
+
+(** Perform an HTTP/2 GET request. Note: HTTP/2 requires TLS with ALPN
+    negotiation in most cases. *)
+let get ~sw ~net ~clock:_ ?config:_ url =
+  let uri = Uri.of_string url in
+  let scheme = Uri.scheme uri |> Option.value ~default:"https" in
+  let is_https = String.equal scheme "https" in
+  let host = Uri.host uri |> Option.value ~default:"localhost" in
+  let default_port = if is_https then 443 else 80 in
+  let port = Uri.port uri |> Option.value ~default:default_port in
+  let path = Uri.path_and_query uri in
+  let path = if path = "" then "/" else path in
+
+  (* Resolve and connect *)
+  let addrs = Eio.Net.getaddrinfo_stream net host in
+  match addrs with
+  | [] -> Error (Connection_failed ("Cannot resolve host: " ^ host))
+  | addr_info :: _ ->
+      let addr =
+        match addr_info with
+        | `Tcp (ip, _) -> `Tcp (ip, port)
+        | `Unix _ -> failwith "Unix sockets not supported"
+      in
+      let tcp_flow = Eio.Net.connect ~sw net addr in
+
+      (* HTTP/2 requires TLS with ALPN advertising h2 *)
+      if is_https then
+        (* Force h2 ALPN for HTTP/2 *)
+        let h2_tls = Tls_config.Client.h2 in
+        match Tls_config.Client.to_tls_config h2_tls ~host with
+        | Error msg -> Error (Tls_error msg)
+        | Ok tls_config -> (
+            try
+              let host_domain =
+                match Domain_name.of_string host with
+                | Ok dn -> (
+                    match Domain_name.host dn with
+                    | Ok h -> Some h
+                    | Error _ -> None)
+                | Error _ -> None
+              in
+              let tls_flow =
+                Tls_eio.client_of_flow tls_config ?host:host_domain tcp_flow
+              in
+              let flow = (tls_flow :> Eio.Flow.two_way_ty r) in
+
+              (* Build HTTP/2 request - h2 handles pseudo-headers automatically *)
+              let headers = H2.Headers.of_list [ (":authority", host) ] in
+              let req = H2.Request.create ~headers ~scheme `GET path in
+
+              do_request flow req
+            with
+            | Tls_eio.Tls_failure failure ->
+                Error (Tls_error (Tls_config.failure_to_string failure))
+            | exn -> Error (Tls_error (Printexc.to_string exn)))
+      else
+        (* HTTP/2 over cleartext (h2c) - less common *)
+        let flow = (tcp_flow :> Eio.Flow.two_way_ty r) in
+        let headers = H2.Headers.of_list [ (":authority", host) ] in
+        let req = H2.Request.create ~headers ~scheme `GET path in
+        do_request flow req

lib/h2_server.ml

···
+(** HTTP/2 Server implementation using h2.
+
+    This module provides HTTP/2 server functionality built on the h2 library
+    with Eio for structured concurrency. *)
+
+open Eio.Std
+
+(** {1 Types} *)
+
+type request = {
+  meth : H2.Method.t;
+  target : string;
+  headers : H2.Headers.t;
+  body : string;
+}
+(** Request type exposed to handlers - same as Server.request for compatibility
+*)
+
+(** {1 Response Types} *)
+
+(** Response body - supports string, bigstring, streaming, and pre-built *)
+type response_body =
+  | Body_string of string
+  | Body_bigstring of Bigstringaf.t
+  | Body_prebuilt of { h2_response : H2.Response.t; body : Bigstringaf.t }
+  | Body_stream of {
+      content_length : int64 option;
+      next : unit -> Cstruct.t option;
+    }
+
+type response = {
+  status : H2.Status.t;
+  headers : (string * string) list;
+  response_body : response_body;
+}
+(** Response type with body variants *)
+
+type handler = request -> response
+
+(** {2 Optimized Response Constructors} *)
+
+let respond_opt ?(status = `OK) ?(headers = []) body =
+  { status; headers; response_body = Body_string body }
+
+let respond_bigstring ?(status = `OK) ?(headers = []) bstr =
+  { status; headers; response_body = Body_bigstring bstr }
+
+let respond_stream ?(status = `OK) ?(headers = []) ?content_length next =
+  { status; headers; response_body = Body_stream { content_length; next } }
+
+let respond_prebuilt h2_response body =
+  {
+    status = `OK;
+    headers = [];
+    response_body = Body_prebuilt { h2_response; body };
+  }
+
+let make_h2_headers headers_list = H2.Headers.of_list headers_list
+
+let make_h2_response ?(status = `OK) headers =
+  H2.Response.create ~headers status
+
+(** {1 Internal helpers} *)
+
+let set_tcp_nodelay flow =
+  match Eio_unix.Resource.fd_opt flow with
+  | None -> ()
+  | Some fd ->
+      Eio_unix.Fd.use_exn "set_tcp_nodelay" fd (fun unix_fd ->
+          Unix.setsockopt unix_fd Unix.TCP_NODELAY true)
+
+let write_iovecs flow iovecs =
+  let cstructs =
+    List.map
+      (fun iov ->
+        Cstruct.of_bigarray ~off:iov.H2.IOVec.off ~len:iov.H2.IOVec.len
+          iov.H2.IOVec.buffer)
+      iovecs
+  in
+  Eio.Flow.write flow cstructs
+
+(** {1 Connection handling} *)
+
+let handle_connection handler flow =
+  let read_buffer_size = 0x4000 in
+  let read_buffer = Bigstringaf.create read_buffer_size in
+
+  let request_handler reqd =
+    let req = H2.Reqd.request reqd in
+    let body_reader = H2.Reqd.request_body reqd in
+
+    let body =
+      match req.meth with
+      | `GET | `HEAD ->
+          H2.Body.Reader.close body_reader;
+          ""
+      | `POST | `PUT | `DELETE | `CONNECT | `OPTIONS | `TRACE | `Other _ ->
+          let body_buffer = Buffer.create 4096 in
+          let body_done_promise, body_done_resolver = Eio.Promise.create () in
+          let rec read_body () =
+            H2.Body.Reader.schedule_read body_reader
+              ~on_eof:(fun () -> Eio.Promise.resolve body_done_resolver ())
+              ~on_read:(fun buf ~off ~len ->
+                Buffer.add_string body_buffer
+                  (Bigstringaf.substring buf ~off ~len);
+                read_body ())
+          in
+          read_body ();
+          Eio.Promise.await body_done_promise;
+          Buffer.contents body_buffer
+    in
+
+    let target =
+      match H2.Headers.get req.headers ":path" with Some p -> p | None -> "/"
+    in
+
+    let request = { meth = req.meth; target; headers = req.headers; body } in
+    let response = handler request in
+
+    match response.response_body with
+    | Body_string body ->
+        let headers =
+          H2.Headers.of_list
+            (("content-length", string_of_int (String.length body))
+            :: response.headers)
+        in
+        let resp = H2.Response.create ~headers response.status in
+        H2.Reqd.respond_with_string reqd resp body
+    | Body_bigstring bstr ->
+        let headers =
+          H2.Headers.of_list
+            (("content-length", string_of_int (Bigstringaf.length bstr))
+            :: response.headers)
+        in
+        let resp = H2.Response.create ~headers response.status in
+        H2.Reqd.respond_with_bigstring reqd resp bstr
+    | Body_prebuilt { h2_response; body } ->
+        H2.Reqd.respond_with_bigstring reqd h2_response body
+    | Body_stream { content_length; next } ->
+        let headers =
+          match content_length with
+          | Some len ->
+              H2.Headers.of_list
+                (("content-length", Int64.to_string len) :: response.headers)
+          | None -> H2.Headers.of_list response.headers
+        in
+        let resp = H2.Response.create ~headers response.status in
+        let body_writer = H2.Reqd.respond_with_streaming reqd resp in
+        let rec write_chunks () =
+          match next () with
+          | None -> H2.Body.Writer.close body_writer
+          | Some cs ->
+              H2.Body.Writer.write_bigstring body_writer ~off:0
+                ~len:(Cstruct.length cs) (Cstruct.to_bigarray cs);
+              write_chunks ()
+        in
+        write_chunks ()
+  in
+
+  let error_handler ?request:_ _error start_response =
+    let resp_body = start_response H2.Headers.empty in
+    H2.Body.Writer.write_string resp_body "Internal Server Error";
+    H2.Body.Writer.close resp_body
+  in
+
+  let conn = H2.Server_connection.create ~error_handler request_handler in
+
+  let shutdown = ref false in
+
+  let read_loop () =
+    let rec loop () =
+      if not !shutdown then
+        match H2.Server_connection.next_read_operation conn with
+        | `Read -> (
+            let cs =
+              Cstruct.of_bigarray read_buffer ~off:0 ~len:read_buffer_size
+            in
+            try
+              let n = Eio.Flow.single_read flow cs in
+              let _ =
+                H2.Server_connection.read conn read_buffer ~off:0 ~len:n
+              in
+              loop ()
+            with End_of_file ->
+              let _ =
+                H2.Server_connection.read_eof conn read_buffer ~off:0 ~len:0
+              in
+              shutdown := true)
+        | `Close -> shutdown := true
+    in
+    loop ()
+  in
+
+  let write_loop () =
+    let rec loop () =
+      if not !shutdown then
+        match H2.Server_connection.next_write_operation conn with
+        | `Write iovecs ->
+            write_iovecs flow iovecs;
+            let len =
+              List.fold_left (fun acc iov -> acc + iov.H2.IOVec.len) 0 iovecs
+            in
+            H2.Server_connection.report_write_result conn (`Ok len);
+            loop ()
+        | `Yield ->
+            let continue = Eio.Promise.create () in
+            H2.Server_connection.yield_writer conn (fun () ->
+                Eio.Promise.resolve (snd continue) ());
+            Eio.Promise.await (fst continue);
+            loop ()
+        | `Close _ -> shutdown := true
+    in
+    loop ()
+  in
+
+  Fiber.both read_loop write_loop
+
+(** {1 Public API} *)
+
+let run ~sw ~net ?(config = H1_server.default_config) handler =
+  let addr = `Tcp (Eio.Net.Ipaddr.V4.any, config.port) in
+  let socket =
+    Eio.Net.listen ~sw ~backlog:config.backlog ~reuse_addr:config.reuse_addr
+      ~reuse_port:config.reuse_port net addr
+  in
+  traceln "HTTP/2 Server listening on port %d" config.port;
+  let connection_handler flow _addr =
+    if config.tcp_nodelay then set_tcp_nodelay flow;
+    handle_connection handler flow
+  in
+  let on_error exn = traceln "Connection error: %s" (Printexc.to_string exn) in
+  Eio.Net.run_server socket connection_handler
+    ~max_connections:config.max_connections ~on_error
+
+let run_tls ~sw ~net ?(config = H1_server.default_config) ~tls_config handler =
+  let addr = `Tcp (Eio.Net.Ipaddr.V4.any, config.port) in
+  let socket =
+    Eio.Net.listen ~sw ~backlog:config.backlog ~reuse_addr:config.reuse_addr
+      ~reuse_port:config.reuse_port net addr
+  in
+  traceln "HTTP/2 Server (TLS) listening on port %d" config.port;
+  let connection_handler flow _addr =
+    if config.tcp_nodelay then set_tcp_nodelay flow;
+    match Tls_config.Server.to_tls_config tls_config with
+    | Error (`Msg msg) -> traceln "TLS config error: %s" msg
+    | Ok tls_cfg -> (
+        try
+          let tls_flow = Tls_eio.server_of_flow tls_cfg flow in
+          handle_connection handler tls_flow
+        with
+        | Tls_eio.Tls_failure failure ->
+            traceln "TLS error: %s" (Tls_config.failure_to_string failure)
+        | exn -> traceln "TLS error: %s" (Printexc.to_string exn))
+  in
+  let on_error exn = traceln "Connection error: %s" (Printexc.to_string exn) in
+  Eio.Net.run_server socket connection_handler
+    ~max_connections:config.max_connections ~on_error
+
+let run_parallel ~sw ~net ~domain_mgr ?(config = H1_server.default_config)
+    handler =
+  let domain_count = max 1 config.domain_count in
+  let addr = `Tcp (Eio.Net.Ipaddr.V4.any, config.port) in
+  let socket =
+    Eio.Net.listen ~sw ~backlog:config.backlog ~reuse_addr:config.reuse_addr
+      ~reuse_port:config.reuse_port net addr
+  in
+  traceln "HTTP/2 Server listening on port %d (%d domains)" config.port
+    domain_count;
+  let connection_handler flow _addr =
+    if config.tcp_nodelay then set_tcp_nodelay flow;
+    handle_connection handler flow
+  in
+  let on_error exn = traceln "Connection error: %s" (Printexc.to_string exn) in
+  if domain_count <= 1 then
+    Eio.Net.run_server socket connection_handler
+      ~max_connections:config.max_connections ~on_error
+  else
+    Eio.Net.run_server socket connection_handler
+      ~max_connections:config.max_connections ~on_error
+      ~additional_domains:(domain_mgr, domain_count - 1)

lib/hcs.ml

···
+(** HCS - High-performance HTTP library for OCaml 5+.
+
+    Built on Eio for structured concurrency, using h1 for HTTP/1.1 and h2 for
+    HTTP/2 protocol handling.
+
+    The library is designed with runtime abstraction in mind, making future Lwt
+    support possible without major rewrites. *)
+
+module Client = Client
+(** HTTP Client *)
+
+module Server = Server
+(** HTTP Server *)
+
+module Router = Router
+(** Router with radix trie *)
+
+module Middleware = Middleware
+(** Middleware combinators *)
+
+module Middleware_eio = Middleware_eio
+(** Eio-specific middleware (logging, timeout, rate limiting, static files) *)
+
+module Control = Control
+(** Control flow: retry, circuit breaker, rate limiting *)
+
+module Pool = Pool
+(** Connection pool *)
+
+module Pooled_client = Pooled_client
+(** HTTP Client with connection pooling *)
+
+module Tls_config = Tls_config
+(** TLS configuration *)
+
+module Request = Request
+(** Request helpers *)
+
+module Response = Response
+(** Response helpers *)
+
+module H1_client = H1_client
+(** HTTP/1.1 Client *)
+
+module H2_client = H2_client
+(** HTTP/2 Client *)
+
+module H1_server = H1_server
+(** HTTP/1.1 Server (low-level, optimized) *)
+
+module H2_server = H2_server
+(** HTTP/2 Server *)
+
+module Websocket = Websocket
+(** WebSocket support *)
+
+module Codec = Codec
+(** Codec system for serialization/deserialization *)
+
+module Log = Log
+(** Logging system *)
+
+module Stream = Stream
+(** Streaming abstractions *)
+
+module Http = Http
+(** HTTP Request builder DSL *)
+
+module Method = H1.Method
+(** Re-exports for convenience *)
+
+module Status = H1.Status
+module Headers = H1.Headers

lib/http.ml

···
+(** HTTP Request Builder DSL.
+
+    This module provides a fluent API for building HTTP requests. It's designed
+    to be used with the Client module for a high-level HTTP client experience.
+
+    {1 Usage}
+
+    {[
+      open Hcs.Http
+
+      (* Simple GET request *)
+      let req = get "https://api.example.com/users" |> build
+
+      (* POST with JSON body *)
+      let req =
+        post "https://api.example.com/users"
+        |> content_type "application/json"
+        |> body_string {|{"name": "Alice"}|}
+        |> build
+
+      (* GET with query params and auth *)
+      let req =
+        get "https://api.example.com/search"
+        |> query "q" "ocaml" |> query "limit" "10" |> bearer "my-token" |> build
+    ]} *)
+
+(** {1 Types} *)
+
+(** HTTP method *)
+type meth =
+  | GET
+  | POST
+  | PUT
+  | DELETE
+  | PATCH
+  | HEAD
+  | OPTIONS
+  | CONNECT
+  | TRACE
+  | Other of string
+
+(** Body content *)
+type body = Empty | String of string | Form of (string * string) list
+
+type builder = {
+  meth : meth;
+  uri : Uri.t;
+  headers : (string * string) list;
+  body : body;
+}
+(** Request builder - accumulates request parameters *)
+
+type request = {
+  req_meth : meth;
+  req_uri : Uri.t;
+  req_headers : (string * string) list;
+  req_body : body;
+}
+(** Built request ready for execution *)
+
+(** {1 Method to H1.Method conversion} *)
+
+let meth_to_h1 = function
+  | GET -> `GET
+  | POST -> `POST
+  | PUT -> `PUT
+  | DELETE -> `DELETE
+  | PATCH -> `Other "PATCH"
+  | HEAD -> `HEAD
+  | OPTIONS -> `OPTIONS
+  | CONNECT -> `CONNECT
+  | TRACE -> `TRACE
+  | Other s -> `Other s
+
+let meth_of_string = function
+  | "GET" -> GET
+  | "POST" -> POST
+  | "PUT" -> PUT
+  | "DELETE" -> DELETE
+  | "PATCH" -> PATCH
+  | "HEAD" -> HEAD
+  | "OPTIONS" -> OPTIONS
+  | "CONNECT" -> CONNECT
+  | "TRACE" -> TRACE
+  | s -> Other s
+
+let meth_to_string = function
+  | GET -> "GET"
+  | POST -> "POST"
+  | PUT -> "PUT"
+  | DELETE -> "DELETE"
+  | PATCH -> "PATCH"
+  | HEAD -> "HEAD"
+  | OPTIONS -> "OPTIONS"
+  | CONNECT -> "CONNECT"
+  | TRACE -> "TRACE"
+  | Other s -> s
+
+(** {1 Request Builders} *)
+
+(** Create a builder with the given method and URL *)
+let create meth url =
+  let uri = Uri.of_string url in
+  { meth; uri; headers = []; body = Empty }
+
+(** Create a GET request builder *)
+let get url = create GET url
+
+(** Create a POST request builder *)
+let post url = create POST url
+
+(** Create a PUT request builder *)
+let put url = create PUT url
+
+(** Create a DELETE request builder *)
+let delete url = create DELETE url
+
+(** Create a PATCH request builder *)
+let patch url = create PATCH url
+
+(** Create a HEAD request builder *)
+let head url = create HEAD url
+
+(** Create an OPTIONS request builder *)
+let options url = create OPTIONS url
+
+(** Create a request builder from a Uri *)
+let of_uri meth uri = { meth; uri; headers = []; body = Empty }
+
+(** {2 Headers} *)
+
+(** Add a header to the request *)
+let header name value builder =
+  { builder with headers = (name, value) :: builder.headers }
+
+(** Add multiple headers to the request *)
+let headers hdrs builder =
+  { builder with headers = List.rev_append hdrs builder.headers }
+
+(** Set the Content-Type header *)
+let content_type ct builder = header "Content-Type" ct builder
+
+(** Set the Accept header *)
+let accept ct builder = header "Accept" ct builder
+
+(** Set the User-Agent header *)
+let user_agent ua builder = header "User-Agent" ua builder
+
+(** Set Bearer authentication *)
+let bearer token builder = header "Authorization" ("Bearer " ^ token) builder
+
+(** Set Basic authentication *)
+let basic_auth ~user ~pass builder =
+  let credentials = Base64.encode_string (user ^ ":" ^ pass) in
+  header "Authorization" ("Basic " ^ credentials) builder
+
+(** Set a cookie header *)
+let cookie name value builder =
+  let existing =
+    List.find_opt (fun (n, _) -> String.equal n "Cookie") builder.headers
+  in
+  let new_cookie =
+    match existing with
+    | Some (_, v) -> v ^ "; " ^ name ^ "=" ^ value
+    | None -> name ^ "=" ^ value
+  in
+  let headers =
+    List.filter (fun (n, _) -> not (String.equal n "Cookie")) builder.headers
+  in
+  { builder with headers = ("Cookie", new_cookie) :: headers }
+
+(** Set cookies from a list *)
+let cookies cs builder =
+  List.fold_left (fun b (n, v) -> cookie n v b) builder cs
+
+(** {2 Query Parameters} *)
+
+(** Add a query parameter *)
+let query name value builder =
+  let uri = Uri.add_query_param' builder.uri (name, value) in
+  { builder with uri }
+
+(** Add multiple query parameters *)
+let queries qs builder =
+  let uri =
+    List.fold_left
+      (fun u (n, v) -> Uri.add_query_param' u (n, v))
+      builder.uri qs
+  in
+  { builder with uri }
+
+(** {2 Body} *)
+
+(** Set the request body *)
+let body b builder = { builder with body = b }
+
+(** Set the body as a string with optional content type *)
+let body_string ?content_type:ct str builder =
+  let builder = { builder with body = String str } in
+  match ct with Some ct -> content_type ct builder | None -> builder
+
+(** Set the body as a JSON string *)
+let body_json json builder =
+  builder |> body_string ~content_type:"application/json" json
+
+(** Set the body as form data *)
+let form fields builder =
+  { builder with body = Form fields }
+  |> content_type "application/x-www-form-urlencoded"
+
+(** {1 Building} *)
+
+(** Build the final request *)
+let build builder =
+  {
+    req_meth = builder.meth;
+    req_uri = builder.uri;
+    req_headers = List.rev builder.headers;
+    req_body = builder.body;
+  }
+
+(** Get the URL as a string *)
+let url request = Uri.to_string request.req_uri
+
+(** Get the host from the request *)
+let host request = Uri.host request.req_uri |> Option.value ~default:"localhost"
+
+(** Get the port from the request *)
+let port request =
+  match Uri.port request.req_uri with
+  | Some p -> p
+  | None -> (
+      match Uri.scheme request.req_uri with Some "https" -> 443 | _ -> 80)
+
+(** Get the path from the request *)
+let path request =
+  let p = Uri.path request.req_uri in
+  if p = "" then "/" else p
+
+(** Get the path and query from the request *)
+let path_and_query request = Uri.path_and_query request.req_uri
+
+(** Check if the request is HTTPS *)
+let is_https request =
+  match Uri.scheme request.req_uri with Some "https" -> true | _ -> false
+
+(** {1 Body Encoding} *)
+
+(** Encode form data as URL-encoded string *)
+let encode_form fields =
+  String.concat "&"
+    (List.map (fun (k, v) -> Uri.pct_encode k ^ "=" ^ Uri.pct_encode v) fields)
+
+(** Get the body as a string *)
+let body_to_string = function
+  | Empty -> ""
+  | String s -> s
+  | Form fields -> encode_form fields
+
+(** Get the Content-Length for the body *)
+let body_length body = String.length (body_to_string body)

lib/log.ml

···
+(** Logging module for HCS HTTP library.
+
+    Provides structured logging for HTTP events including requests, responses,
+    connections, and errors. The module is runtime-agnostic and uses a
+    callback-based approach for flexibility.
+
+    {1 Usage}
+
+    {[
+      (* Use built-in stderr logger *)
+      let logger = Hcs.Log.stderr ()
+
+      (* Use null logger (no output) *)
+      let logger = Hcs.Log.null
+
+      (* Use custom logger *)
+      let logger =
+        Hcs.Log.custom (fun level msg ->
+            match level with
+            | Hcs.Log.Error -> Printf.eprintf "[ERROR] %s\n%!" msg
+            | _ ->
+                Printf.printf "[%s] %s\n%!" (Hcs.Log.level_to_string level) msg)
+    ]} *)
+
+(** {1 Types} *)
+
+(** Log levels *)
+type level =
+  | Debug  (** Detailed debugging information *)
+  | Info  (** General information about operations *)
+  | Warn  (** Warning conditions *)
+  | Error  (** Error conditions *)
+
+(** HTTP method for logging (simplified) *)
+type http_method =
+  | GET
+  | POST
+  | PUT
+  | DELETE
+  | PATCH
+  | HEAD
+  | OPTIONS
+  | CONNECT
+  | TRACE
+  | Other of string
+
+(** Log events - structured events that can be logged *)
+type event =
+  | Request_start of {
+      id : string;
+      meth : http_method;
+      uri : string;
+      headers : (string * string) list;
+    }  (** Request started *)
+  | Request_end of {
+      id : string;
+      status : int;
+      duration_ms : float;
+      body_size : int option;
+    }  (** Request completed *)
+  | Connection_open of {
+      host : string;
+      port : int;
+      protocol : string;  (** "http/1.1" or "h2" *)
+    }  (** Connection opened *)
+  | Connection_close of { host : string; port : int; reason : string }
+      (** Connection closed *)
+  | Connection_reuse of { host : string; port : int }
+      (** Connection reused from pool *)
+  | Tls_handshake of {
+      host : string;
+      protocol : string;  (** TLS version *)
+      cipher : string option;
+    }  (** TLS handshake completed *)
+  | Retry of {
+      id : string;
+      attempt : int;
+      reason : string;
+      delay_ms : float option;
+    }  (** Request retry *)
+  | Redirect of {
+      id : string;
+      from_uri : string;
+      to_uri : string;
+      status : int;
+    }  (** Following redirect *)
+  | Error of { id : string option; error : string; context : string option }
+      (** Error occurred *)
+  | Custom of { name : string; data : (string * string) list }
+      (** Custom event *)
+
+type logger = level -> event -> unit
+(** Logger function type *)
+
+(** {1 Level operations} *)
+
+(** Convert level to string *)
+let level_to_string = function
+  | Debug -> "DEBUG"
+  | Info -> "INFO"
+  | Warn -> "WARN"
+  | Error -> "ERROR"
+
+(** Parse level from string *)
+let level_of_string = function
+  | "DEBUG" | "debug" -> Some Debug
+  | "INFO" | "info" -> Some Info
+  | "WARN" | "warn" | "WARNING" | "warning" -> Some Warn
+  | "ERROR" | "error" -> Some Error
+  | _ -> None
+
+(** Compare log levels (for filtering) *)
+let level_to_int = function Debug -> 0 | Info -> 1 | Warn -> 2 | Error -> 3
+
+let level_gte l1 l2 = level_to_int l1 >= level_to_int l2
+
+(** {1 HTTP method operations} *)
+
+let method_to_string = function
+  | GET -> "GET"
+  | POST -> "POST"
+  | PUT -> "PUT"
+  | DELETE -> "DELETE"
+  | PATCH -> "PATCH"
+  | HEAD -> "HEAD"
+  | OPTIONS -> "OPTIONS"
+  | CONNECT -> "CONNECT"
+  | TRACE -> "TRACE"
+  | Other s -> s
+
+let method_of_h1 (m : Httpun_types.Method.t) : http_method =
+  match m with
+  | `GET -> GET
+  | `POST -> POST
+  | `PUT -> PUT
+  | `DELETE -> DELETE
+  | `HEAD -> HEAD
+  | `OPTIONS -> OPTIONS
+  | `CONNECT -> CONNECT
+  | `TRACE -> TRACE
+  | `Other s -> Other s
+
+(** {1 Event formatting} *)
+
+(** Format event as a human-readable string *)
+let event_to_string = function
+  | Request_start { id; meth; uri; headers = _ } ->
+      Printf.sprintf "Request[%s] %s %s" id (method_to_string meth) uri
+  | Request_end { id; status; duration_ms; body_size } ->
+      let size_str =
+        match body_size with
+        | Some s -> Printf.sprintf ", %d bytes" s
+        | None -> ""
+      in
+      Printf.sprintf "Request[%s] completed: status=%d, duration=%.2fms%s" id
+        status duration_ms size_str
+  | Connection_open { host; port; protocol } ->
+      Printf.sprintf "Connection opened: %s:%d (%s)" host port protocol
+  | Connection_close { host; port; reason } ->
+      Printf.sprintf "Connection closed: %s:%d (%s)" host port reason
+  | Connection_reuse { host; port } ->
+      Printf.sprintf "Connection reused: %s:%d" host port
+  | Tls_handshake { host; protocol; cipher } ->
+      let cipher_str =
+        match cipher with Some c -> ", cipher=" ^ c | None -> ""
+      in
+      Printf.sprintf "TLS handshake: %s (%s%s)" host protocol cipher_str
+  | Retry { id; attempt; reason; delay_ms } ->
+      let delay_str =
+        match delay_ms with
+        | Some d -> Printf.sprintf ", delay=%.0fms" d
+        | None -> ""
+      in
+      Printf.sprintf "Request[%s] retry #%d: %s%s" id attempt reason delay_str
+  | Redirect { id; from_uri; to_uri; status } ->
+      Printf.sprintf "Request[%s] redirect %d: %s -> %s" id status from_uri
+        to_uri
+  | Error { id; error; context } ->
+      let id_str =
+        match id with Some i -> Printf.sprintf "[%s] " i | None -> ""
+      in
+      let ctx_str =
+        match context with Some c -> " (" ^ c ^ ")" | None -> ""
+      in
+      Printf.sprintf "Error%s: %s%s" id_str error ctx_str
+  | Custom { name; data } ->
+      let data_str =
+        String.concat ", "
+          (List.map (fun (k, v) -> Printf.sprintf "%s=%s" k v) data)
+      in
+      Printf.sprintf "Custom[%s]: %s" name data_str
+
+(** Format event as JSON string *)
+let event_to_json = function
+  | Request_start { id; meth; uri; headers } ->
+      let headers_json =
+        String.concat ","
+          (List.map (fun (k, v) -> Printf.sprintf {|"%s":"%s"|} k v) headers)
+      in
+      Printf.sprintf
+        {|{"event":"request_start","id":"%s","method":"%s","uri":"%s","headers":{%s}}|}
+        id (method_to_string meth) uri headers_json
+  | Request_end { id; status; duration_ms; body_size } ->
+      let size_json =
+        match body_size with
+        | Some s -> Printf.sprintf {|,"body_size":%d|} s
+        | None -> ""
+      in
+      Printf.sprintf
+        {|{"event":"request_end","id":"%s","status":%d,"duration_ms":%.2f%s}|}
+        id status duration_ms size_json
+  | Connection_open { host; port; protocol } ->
+      Printf.sprintf
+        {|{"event":"connection_open","host":"%s","port":%d,"protocol":"%s"}|}
+        host port protocol
+  | Connection_close { host; port; reason } ->
+      Printf.sprintf
+        {|{"event":"connection_close","host":"%s","port":%d,"reason":"%s"}|}
+        host port reason
+  | Connection_reuse { host; port } ->
+      Printf.sprintf {|{"event":"connection_reuse","host":"%s","port":%d}|} host
+        port
+  | Tls_handshake { host; protocol; cipher } ->
+      let cipher_json =
+        match cipher with
+        | Some c -> Printf.sprintf {|,"cipher":"%s"|} c
+        | None -> ""
+      in
+      Printf.sprintf {|{"event":"tls_handshake","host":"%s","protocol":"%s"%s}|}
+        host protocol cipher_json
+  | Retry { id; attempt; reason; delay_ms } ->
+      let delay_json =
+        match delay_ms with
+        | Some d -> Printf.sprintf {|,"delay_ms":%.0f|} d
+        | None -> ""
+      in
+      Printf.sprintf
+        {|{"event":"retry","id":"%s","attempt":%d,"reason":"%s"%s}|} id attempt
+        reason delay_json
+  | Redirect { id; from_uri; to_uri; status } ->
+      Printf.sprintf
+        {|{"event":"redirect","id":"%s","from":"%s","to":"%s","status":%d}|} id
+        from_uri to_uri status
+  | Error { id; error; context } ->
+      let id_json =
+        match id with Some i -> Printf.sprintf {|"id":"%s",|} i | None -> ""
+      in
+      let ctx_json =
+        match context with
+        | Some c -> Printf.sprintf {|,"context":"%s"|} c
+        | None -> ""
+      in
+      Printf.sprintf {|{"event":"error",%s"error":"%s"%s}|} id_json error
+        ctx_json
+  | Custom { name; data } ->
+      let data_json =
+        String.concat ","
+          (List.map (fun (k, v) -> Printf.sprintf {|"%s":"%s"|} k v) data)
+      in
+      Printf.sprintf {|{"event":"custom","name":"%s","data":{%s}}|} name
+        data_json
+
+(** {1 Built-in Loggers} *)
+
+(** Null logger - discards all events *)
+let null : logger = fun _ _ -> ()
+
+(** Stderr logger with optional minimum level filter *)
+let stderr ?(min_level = Debug) ?(json = false) () : logger =
+ fun level event ->
+  if level_gte level min_level then
+    let formatted =
+      if json then event_to_json event else event_to_string event
+    in
+    Printf.eprintf "[%s] %s\n%!" (level_to_string level) formatted
+
+(** Stdout logger with optional minimum level filter *)
+let stdout ?(min_level = Debug) ?(json = false) () : logger =
+ fun level event ->
+  if level_gte level min_level then
+    let formatted =
+      if json then event_to_json event else event_to_string event
+    in
+    Printf.printf "[%s] %s\n%!" (level_to_string level) formatted
+
+(** Custom logger from a simple callback *)
+let custom (f : level -> string -> unit) : logger =
+ fun level event -> f level (event_to_string event)
+
+(** Custom logger with JSON output *)
+let custom_json (f : level -> string -> unit) : logger =
+ fun level event -> f level (event_to_json event)
+
+(** Combine multiple loggers *)
+let combine (loggers : logger list) : logger =
+ fun level event -> List.iter (fun logger -> logger level event) loggers
+
+(** Filter logger by minimum level *)
+let with_min_level (min_level : level) (logger : logger) : logger =
+ fun level event -> if level_gte level min_level then logger level event
+
+(** {1 Request ID generation} *)
+
+(** Counter for unique request IDs *)
+let request_id_counter = ref 0
+
+(** Generate a unique request ID *)
+let generate_request_id () =
+  incr request_id_counter;
+  let random = Random.int 0xFFFF in
+  Printf.sprintf "req-%06d-%04x" !request_id_counter random

lib/middleware.ml

···
+(** Middleware support for HCS HTTP server.
+
+    Middleware wraps request handlers to add cross-cutting concerns like
+    logging, authentication, CORS, etc. *)
+
+type ('req, 'resp) t = ('req -> 'resp) -> 'req -> 'resp
+(** Middleware type - wraps a handler *)
+
+(** Identity middleware - does nothing *)
+let identity : ('req, 'resp) t = fun handler req -> handler req
+
+(** Compose two middleware: m1 runs before m2 *)
+let compose (m1 : ('req, 'resp) t) (m2 : ('req, 'resp) t) : ('req, 'resp) t =
+ fun handler -> m1 (m2 handler)
+
+(** Compose a list of middleware *)
+let compose_all middlewares = List.fold_right compose middlewares identity
+
+(** Infix operator for middleware composition *)
+let ( @> ) = compose
+
+(** Apply middleware to a handler *)
+let apply middleware handler = middleware handler
+
+(** Logging middleware - logs requests (generic version) *)
+let logging ~log : ('req, 'resp) t =
+ fun handler req ->
+  log "Request received";
+  let resp = handler req in
+  log "Response sent";
+  resp
+
+(** Timing middleware - measures request duration *)
+let timing ~on_complete : ('req, 'resp) t =
+ fun handler req ->
+  let start = Unix.gettimeofday () in
+  let resp = handler req in
+  let duration = Unix.gettimeofday () -. start in
+  on_complete duration;
+  resp
+
+(** Exception recovery middleware *)
+let recover ~on_error : ('req, 'resp) t =
+ fun handler req -> try handler req with exn -> on_error exn
+
+(** Conditional middleware - only applies if predicate is true *)
+let when_ predicate middleware : ('req, 'resp) t =
+ fun handler req ->
+  if predicate req then middleware handler req else handler req
+
+(** Skip middleware for certain requests *)
+let unless predicate middleware =
+  when_ (fun req -> not (predicate req)) middleware

lib/middleware_eio.ml

···
+(** Eio-specific middleware implementations.
+
+    These middleware require Eio runtime features like clocks, filesystem
+    access, and structured concurrency.
+
+    {1 Usage}
+
+    {[
+      open Hcs.Middleware_eio
+
+      (* Add logging with timing *)
+      let handler =
+        handler
+        |> Middleware.apply (logging ~clock (Log.stderr ()))
+        |> Middleware.apply (timeout ~clock 30.0)
+    ]} *)
+
+(** {1 String Helpers} *)
+
+(** Check if string starts with prefix *)
+let string_starts_with ~prefix s =
+  let plen = String.length prefix in
+  let slen = String.length s in
+  plen <= slen && String.sub s 0 plen = prefix
+
+(** Check if substring exists in string *)
+let string_contains_substring ~substring s =
+  let rec check i =
+    if i + String.length substring > String.length s then false
+    else if String.sub s i (String.length substring) = substring then true
+    else check (i + 1)
+  in
+  check 0
+
+(** {1 Types} *)
+
+type request = Server.request
+(** Server request type (simplified for middleware) *)
+
+type response = Server.response
+(** Server response type *)
+
+type middleware = (request -> response) -> request -> response
+(** Middleware type matching Server.handler *)
+
+(** {1 Response Helpers} *)
+
+(** Get the body size from a response, if known *)
+let response_body_size (resp : response) : int option =
+  match resp.Server.body with
+  | Server.Body_empty -> Some 0
+  | Server.Body_string s -> Some (String.length s)
+  | Server.Body_bigstring b -> Some (Bigstringaf.length b)
+  | Server.Body_prebuilt p -> Some (Bigstringaf.length p.Server.Prebuilt.body)
+  | Server.Body_stream _ -> None
+
+let response_body_string (resp : response) : string =
+  match resp.Server.body with
+  | Server.Body_empty -> ""
+  | Server.Body_string s -> s
+  | Server.Body_bigstring b -> Bigstringaf.to_string b
+  | Server.Body_prebuilt p -> Bigstringaf.to_string p.Server.Prebuilt.body
+  | Server.Body_stream _ -> ""
+
+(** {1 Logging Middleware} *)
+
+(** Logging middleware that records request timing and details.
+
+    Uses the Log module for structured event logging. *)
+let logging ~(clock : _ Eio.Time.clock) (logger : Log.logger) : middleware =
+ fun handler req ->
+  let id = Log.generate_request_id () in
+  let start = Eio.Time.now clock in
+  let meth = Log.method_of_h1 req.Server.meth in
+  logger Log.Info
+    (Log.Request_start { id; meth; uri = req.target; headers = req.headers });
+  let resp = handler req in
+  let duration_ms = (Eio.Time.now clock -. start) *. 1000.0 in
+  let status = H1.Status.to_code resp.Server.status in
+  let body_size = response_body_size resp in
+  logger Log.Info (Log.Request_end { id; status; duration_ms; body_size });
+  resp
+
+(** {1 Timeout Middleware} *)
+
+(** Timeout middleware that cancels requests exceeding the time limit.
+
+    Returns a 504 Gateway Timeout response if the handler takes too long. *)
+let timeout ~(clock : _ Eio.Time.clock) (seconds : float) : middleware =
+ fun handler req ->
+  let timeout_response () =
+    Eio.Time.sleep clock seconds;
+    Server.respond ~status:`Gateway_timeout "Request timed out"
+  in
+  Eio.Fiber.first (fun () -> handler req) timeout_response
+
+(** {1 Rate Limiting} *)
+
+(** Simple in-memory rate limiter state *)
+module Rate_limit_state = struct
+  type t = {
+    mutable requests : int;
+    mutable window_start : float;
+    window_seconds : float;
+    max_requests : int;
+  }
+
+  let create ~max_requests ~window_seconds =
+    { requests = 0; window_start = 0.0; window_seconds; max_requests }
+
+  let check_and_increment t now =
+    if now -. t.window_start >= t.window_seconds then begin
+      t.window_start <- now;
+      t.requests <- 1;
+      true
+    end
+    else if t.requests < t.max_requests then begin
+      t.requests <- t.requests + 1;
+      true
+    end
+    else false
+
+  let remaining t = max 0 (t.max_requests - t.requests)
+  let reset_at t = t.window_start +. t.window_seconds
+end
+
+(** Rate limiting middleware.
+
+    Limits requests per time window, keyed by a function (e.g., by IP, by user).
+    Returns 429 Too Many Requests when the limit is exceeded. *)
+let rate_limit ~(clock : _ Eio.Time.clock) ~(key : request -> string)
+    ~(requests : int) ~(per : float) : middleware =
+  let states : (string, Rate_limit_state.t) Hashtbl.t = Hashtbl.create 256 in
+  let mutex = Eio.Mutex.create () in
+  fun handler req ->
+    let k = key req in
+    let now = Eio.Time.now clock in
+    let allowed, remaining, reset_at =
+      Eio.Mutex.use_rw ~protect:true mutex (fun () ->
+          let state =
+            match Hashtbl.find_opt states k with
+            | Some s -> s
+            | None ->
+                let s =
+                  Rate_limit_state.create ~max_requests:requests
+                    ~window_seconds:per
+                in
+                Hashtbl.add states k s;
+                s
+          in
+          let allowed = Rate_limit_state.check_and_increment state now in
+          ( allowed,
+            Rate_limit_state.remaining state,
+            Rate_limit_state.reset_at state ))
+    in
+    if allowed then handler req
+    else
+      let headers =
+        [
+          ("X-RateLimit-Limit", string_of_int requests);
+          ("X-RateLimit-Remaining", string_of_int remaining);
+          ("X-RateLimit-Reset", string_of_int (int_of_float reset_at));
+          ("Retry-After", string_of_int (int_of_float (reset_at -. now)));
+        ]
+      in
+      {
+        Server.status = `Code 429;
+        headers;
+        body = Server.Body_string "Too Many Requests";
+      }
+
+(** {1 ETag and Caching} *)
+
+(** Generate ETag from response body using MD5 hash *)
+let generate_etag body =
+  let hash = Digestif.MD5.digest_string body in
+  "\"" ^ Digestif.MD5.to_hex hash ^ "\""
+
+let etag : middleware =
+ fun handler req ->
+  let resp = handler req in
+  let body_str = response_body_string resp in
+  let etag_value = generate_etag body_str in
+  let if_none_match =
+    List.find_opt
+      (fun (n, _) -> String.lowercase_ascii n = "if-none-match")
+      req.headers
+    |> Option.map snd
+  in
+  match if_none_match with
+  | Some client_etag when String.equal client_etag etag_value ->
+      {
+        status = `Code 304;
+        headers = [ ("ETag", etag_value) ];
+        body = Server.Body_empty;
+      }
+  | _ -> { resp with headers = ("ETag", etag_value) :: resp.headers }
+
+(** Cache-Control middleware - adds Cache-Control header *)
+let cache_control (directive : string) : middleware =
+ fun handler req ->
+  let resp = handler req in
+  { resp with headers = ("Cache-Control", directive) :: resp.headers }
+
+(** {1 Static Files} *)
+
+(** MIME type mapping for common file extensions *)
+let mime_type_of_extension ext =
+  match String.lowercase_ascii ext with
+  | ".html" | ".htm" -> "text/html; charset=utf-8"
+  | ".css" -> "text/css; charset=utf-8"
+  | ".js" -> "application/javascript; charset=utf-8"
+  | ".json" -> "application/json"
+  | ".xml" -> "application/xml"
+  | ".txt" -> "text/plain; charset=utf-8"
+  | ".png" -> "image/png"
+  | ".jpg" | ".jpeg" -> "image/jpeg"
+  | ".gif" -> "image/gif"
+  | ".svg" -> "image/svg+xml"
+  | ".ico" -> "image/x-icon"
+  | ".webp" -> "image/webp"
+  | ".woff" -> "font/woff"
+  | ".woff2" -> "font/woff2"
+  | ".ttf" -> "font/ttf"
+  | ".otf" -> "font/otf"
+  | ".pdf" -> "application/pdf"
+  | ".zip" -> "application/zip"
+  | ".gz" -> "application/gzip"
+  | ".mp3" -> "audio/mpeg"
+  | ".mp4" -> "video/mp4"
+  | ".webm" -> "video/webm"
+  | _ -> "application/octet-stream"
+
+(** Get file extension from path *)
+let extension path =
+  match String.rindex_opt path '.' with
+  | Some i -> String.sub path i (String.length path - i)
+  | None -> ""
+
+(** Static file middleware - serves files from a directory.
+
+    @param fs The Eio filesystem to use
+    @param root The root directory path for static files
+    @param index
+      Index files to try for directory requests (default: ["index.html"])
+    @param with_etag Whether to add ETag headers (default: true) *)
+let static ~(fs : _ Eio.Path.t) ?(index = [ "index.html" ]) ?(with_etag = true)
+    (root : string) : middleware =
+ fun handler req ->
+  (* Only handle GET and HEAD *)
+  match req.meth with
+  | `GET | `HEAD -> (
+      (* Normalize and validate path to prevent directory traversal *)
+      let path = req.target in
+      let path =
+        if String.length path > 0 && path.[0] = '/' then
+          String.sub path 1 (String.length path - 1)
+        else path
+      in
+      (* Remove query string *)
+      let path =
+        match String.index_opt path '?' with
+        | Some i -> String.sub path 0 i
+        | None -> path
+      in
+      (* Check for directory traversal *)
+      if String.contains path '\x00' || string_starts_with ~prefix:".." path
+      then handler req (* Pass to next handler *)
+      else
+        let full_path = Eio.Path.(fs / root / path) in
+        try
+          (* Try to read the file *)
+          let content = Eio.Path.load full_path in
+          let content_type = mime_type_of_extension (extension path) in
+          let headers =
+            [
+              ("Content-Type", content_type);
+              ("Content-Length", string_of_int (String.length content));
+            ]
+          in
+          let headers =
+            if with_etag then ("ETag", generate_etag content) :: headers
+            else headers
+          in
+          (* Handle If-None-Match *)
+          let if_none_match =
+            List.find_opt
+              (fun (n, _) -> String.lowercase_ascii n = "if-none-match")
+              req.headers
+            |> Option.map snd
+          in
+          let etag_value = generate_etag content in
+          match if_none_match with
+          | Some client_etag when String.equal client_etag etag_value ->
+              {
+                status = `Code 304;
+                headers = [ ("ETag", etag_value) ];
+                body = Server.Body_empty;
+              }
+          | _ ->
+              let body =
+                if req.meth = `HEAD then Server.Body_empty
+                else Server.Body_string content
+              in
+              { status = `OK; headers; body }
+        with
+        | Eio.Io (Eio.Fs.E (Eio.Fs.Not_found _), _) -> (
+            (* Try index files if path looks like a directory *)
+            let try_index () =
+              List.find_map
+                (fun idx ->
+                  try
+                    let idx_path = Eio.Path.(fs / root / path / idx) in
+                    let content = Eio.Path.load idx_path in
+                    Some (idx, content)
+                  with _ -> None)
+                index
+            in
+            match try_index () with
+            | Some (idx, content) ->
+                let content_type = mime_type_of_extension (extension idx) in
+                let headers =
+                  [
+                    ("Content-Type", content_type);
+                    ("Content-Length", string_of_int (String.length content));
+                  ]
+                in
+                let body =
+                  if req.meth = `HEAD then Server.Body_empty
+                  else Server.Body_string content
+                in
+                { status = `OK; headers; body }
+            | None -> handler req)
+        | _ -> handler req)
+  | _ -> handler req
+
+(** {1 Compression} *)
+
+(** Note: Compression middleware would require a compression library like
+    camlzip or decompress. For now, we provide a placeholder that can be
+    implemented when those dependencies are available. *)
+
+(** Check if client accepts gzip encoding *)
+let accepts_gzip (req : request) =
+  List.exists
+    (fun (n, v) ->
+      String.lowercase_ascii n = "accept-encoding"
+      && string_contains_substring ~substring:"gzip" v)
+    req.headers

lib/pool.ml

···
+(** Connection pool for HTTP client.
+
+    This module provides a runtime-agnostic connection pool structure. The
+    actual connection management is done by the runtime-specific code. *)
+
+type config = {
+  max_connections_per_host : int;  (** Max connections per host:port *)
+  max_total_connections : int;  (** Max total connections *)
+  idle_timeout : float;  (** Seconds before closing idle connection *)
+  connection_timeout : float;  (** Seconds to wait for connection *)
+}
+(** Pool configuration *)
+
+let default_config =
+  {
+    max_connections_per_host = 10;
+    max_total_connections = 100;
+    idle_timeout = 60.0;
+    connection_timeout = 30.0;
+  }
+
+type key = { host : string; port : int; tls : bool }
+(** Connection key - identifies a connection target *)
+
+let make_key ~host ~port ~tls = { host; port; tls }
+
+type 'conn entry = {
+  conn : 'conn;
+  created_at : float;
+  mutable last_used : float;
+  mutable in_use : bool;
+}
+(** Connection state *)
+
+type 'conn t = {
+  config : config;
+  mutable connections : (key * 'conn entry list) list;
+  mutable total_count : int;
+}
+(** Connection pool - parameterized by connection type *)
+
+(** Create a new pool *)
+let create ?(config = default_config) () =
+  { config; connections = []; total_count = 0 }
+
+(** Get connections for a key *)
+let get_entries pool key =
+  List.assoc_opt key pool.connections |> Option.value ~default:[]
+
+(** Update connections for a key *)
+let set_entries pool key entries =
+  let others = List.remove_assoc key pool.connections in
+  if entries = [] then pool.connections <- others
+  else pool.connections <- (key, entries) :: others
+
+(** Count connections for a key *)
+let count_for_key pool key = get_entries pool key |> List.length
+
+(** Try to acquire an idle connection. [now] is current time in seconds *)
+let acquire pool key ~now =
+  let entries = get_entries pool key in
+  let rec find_idle = function
+    | [] -> None
+    | entry :: rest ->
+        if
+          (not entry.in_use)
+          && now -. entry.last_used < pool.config.idle_timeout
+        then begin
+          entry.in_use <- true;
+          entry.last_used <- now;
+          Some entry.conn
+        end
+        else find_idle rest
+  in
+  find_idle entries
+
+(** Release a connection back to the pool. [now] is current time *)
+let release pool key conn ~now =
+  let entries = get_entries pool key in
+  let entries =
+    List.map
+      (fun entry ->
+        if entry.conn == conn then
+          { entry with in_use = false; last_used = now }
+        else entry)
+      entries
+  in
+  set_entries pool key entries
+
+(** Add a new connection to the pool. Returns false if pool is at capacity *)
+let add pool key conn ~now =
+  if pool.total_count >= pool.config.max_total_connections then false
+  else if count_for_key pool key >= pool.config.max_connections_per_host then
+    false
+  else begin
+    let entry = { conn; created_at = now; last_used = now; in_use = true } in
+    let entries = get_entries pool key in
+    set_entries pool key (entry :: entries);
+    pool.total_count <- pool.total_count + 1;
+    true
+  end
+
+(** Remove a connection from the pool *)
+let remove pool key conn =
+  let entries = get_entries pool key in
+  let entries = List.filter (fun entry -> entry.conn != conn) entries in
+  let removed = List.length (get_entries pool key) - List.length entries in
+  set_entries pool key entries;
+  pool.total_count <- pool.total_count - removed
+
+(** Close idle connections older than idle_timeout. [now] is current time,
+    [close] is the connection close function *)
+let evict_idle pool ~now ~close =
+  pool.connections <-
+    List.filter_map
+      (fun (key, entries) ->
+        let kept, evicted =
+          List.partition
+            (fun entry ->
+              entry.in_use || now -. entry.last_used < pool.config.idle_timeout)
+            entries
+        in
+        List.iter (fun entry -> close entry.conn) evicted;
+        pool.total_count <- pool.total_count - List.length evicted;
+        if kept = [] then None else Some (key, kept))
+      pool.connections
+
+(** Close all connections *)
+let close_all pool ~close =
+  List.iter
+    (fun (_, entries) -> List.iter (fun entry -> close entry.conn) entries)
+    pool.connections;
+  pool.connections <- [];
+  pool.total_count <- 0
+
+type stats = {
+  total_connections : int;
+  idle_connections : int;
+  in_use_connections : int;
+  hosts : int;
+}
+(** Get pool statistics *)
+
+let stats pool =
+  let idle, in_use =
+    List.fold_left
+      (fun (idle, in_use) (_, entries) ->
+        List.fold_left
+          (fun (idle, in_use) entry ->
+            if entry.in_use then (idle, in_use + 1) else (idle + 1, in_use))
+          (idle, in_use) entries)
+      (0, 0) pool.connections
+  in
+  {
+    total_connections = pool.total_count;
+    idle_connections = idle;
+    in_use_connections = in_use;
+    hosts = List.length pool.connections;
+  }

lib/pooled_client.ml

···
+(** High-performance HTTP client with connection pooling.
+
+    This module provides an HTTP client optimized for making many requests to
+    the same host. For best performance:
+
+    1. Parse the URI once and reuse it 2. Create a pool for the target host and
+    pass it to requests
+
+    Example:
+    {[
+      let uri = Uri.of_string "http://localhost:8080/api" in
+      let pool = Pooled_client.create_pool ~sw ~net ~clock uri in
+      (* All requests reuse the same connection *)
+      for _ = 1 to 1000 do
+        let _ = Pooled_client.get ~sw ~net ~clock ~pool uri in
+        ()
+      done
+    ]}
+
+    For one-off requests, omit the pool:
+    {[
+      let uri = Uri.of_string "http://example.com/api" in
+      let _ = Pooled_client.get ~sw ~net ~clock uri in
+      ()
+    ]} *)
+
+(** {1 Types} *)
+
+(** Read buffer size for HTTP responses *)
+let read_buffer_size = 0x1000
+
+type conn = {
+  flow : Eio.Flow.two_way_ty Eio.Std.r;
+  mutable alive : bool;
+  read_buffer : Bigstringaf.t;
+}
+(** Internal connection state *)
+
+type pool = {
+  host : string;
+  port : int;
+  path : string; (* Pre-extracted path for fast access *)
+  is_https : bool;
+  tls_config : Tls.Config.client option;
+  addr : Eio.Net.Sockaddr.stream option; (* Cached resolved address *)
+  mutable conn : conn option;
+  mutex : Eio.Mutex.t;
+}
+(** Connection pool for a single host. Thread-safe via mutex. *)
+
+type error = H1_client.error
+(** Error type alias *)
+
+(** {1 Connection Management} *)
+
+(** Close a connection safely *)
+let close_conn c =
+  if c.alive then begin
+    c.alive <- false;
+    try Eio.Resource.close (Obj.magic c.flow) with _ -> ()
+  end
+
+(** Resolve hostname to IP address *)
+let resolve_host ~net host =
+  match Eio.Net.getaddrinfo_stream net host with
+  | addr :: _ -> Some addr
+  | [] -> None
+
+(** Create a new TCP connection using cached or resolved address *)
+let connect_tcp pool ~sw ~net =
+  let addr =
+    match pool.addr with
+    | Some a -> Some a
+    | None -> (
+        (* Resolve if not cached *)
+        match resolve_host ~net pool.host with
+        | Some (`Tcp (ip, _)) -> Some (`Tcp (ip, pool.port))
+        | _ -> None)
+  in
+  match addr with
+  | None ->
+      Error (H1_client.Connection_failed ("Cannot resolve host: " ^ pool.host))
+  | Some a -> Ok (Eio.Net.connect ~sw net a)
+
+(** Create a new connection to the pool's target *)
+let create_conn pool ~sw ~net =
+  match connect_tcp pool ~sw ~net with
+  | Error e -> Error e
+  | Ok tcp_flow ->
+      if pool.is_https then
+        match pool.tls_config with
+        | None -> Error (H1_client.Tls_error "TLS not configured")
+        | Some tls_config -> (
+            try
+              let host_domain =
+                match Domain_name.of_string pool.host with
+                | Ok dn -> (
+                    match Domain_name.host dn with
+                    | Ok h -> Some h
+                    | Error _ -> None)
+                | Error _ -> None
+              in
+              let tls_flow =
+                Tls_eio.client_of_flow tls_config ?host:host_domain tcp_flow
+              in
+              Ok
+                {
+                  flow = (tls_flow :> Eio.Flow.two_way_ty Eio.Std.r);
+                  alive = true;
+                  read_buffer = Bigstringaf.create read_buffer_size;
+                }
+            with
+            | Tls_eio.Tls_failure failure ->
+                Error
+                  (H1_client.Tls_error (Tls_config.failure_to_string failure))
+            | exn -> Error (H1_client.Tls_error (Printexc.to_string exn)))
+      else
+        Ok
+          {
+            flow = (tcp_flow :> Eio.Flow.two_way_ty Eio.Std.r);
+            alive = true;
+            read_buffer = Bigstringaf.create read_buffer_size;
+          }
+
+(** {1 Pool Creation} *)
+
+(** Create a connection pool for a URI.
+
+    The pool maintains a single persistent connection to the target host. Pass
+    this pool to [get] and [post] to reuse the connection.
+
+    @param net
+      Network for DNS resolution (optional, resolves lazily if not provided)
+    @param tls
+      TLS configuration for HTTPS. Uses system defaults if not provided. *)
+let create_pool ?net ?(tls = Tls_config.Client.default) uri =
+  let scheme = Uri.scheme uri |> Option.value ~default:"http" in
+  let is_https = String.equal scheme "https" in
+  let host = Uri.host uri |> Option.value ~default:"localhost" in
+  let port =
+    match Uri.port uri with Some p -> p | None -> if is_https then 443 else 80
+  in
+  let path =
+    let p = Uri.path_and_query uri in
+    if p = "" then "/" else p
+  in
+  let tls_config =
+    if is_https then
+      match Tls_config.Client.to_tls_config tls ~host with
+      | Ok c -> Some c
+      | Error _ -> None
+    else None
+  in
+  (* Pre-resolve DNS if net is provided *)
+  let addr =
+    match net with
+    | Some n -> (
+        match Eio.Net.getaddrinfo_stream n host with
+        | addr_info :: _ -> (
+            match addr_info with
+            | `Tcp (ip, _) -> Some (`Tcp (ip, port))
+            | `Unix _ -> None)
+        | [] -> None)
+    | None -> None
+  in
+  {
+    host;
+    port;
+    path;
+    is_https;
+    tls_config;
+    addr;
+    conn = None;
+    mutex = Eio.Mutex.create ();
+  }
+
+(** Close all connections in the pool *)
+let close_pool pool =
+  Eio.Mutex.use_rw ~protect:true pool.mutex (fun () ->
+      Option.iter close_conn pool.conn;
+      pool.conn <- None)
+
+(** {1 Internal Request Handling} *)
+
+(** Write IOVecs to flow *)
+let write_iovecs flow iovecs =
+  let cstructs =
+    List.map
+      (fun iov ->
+        Cstruct.of_bigarray ~off:iov.Httpun_types.IOVec.off
+          ~len:iov.Httpun_types.IOVec.len iov.Httpun_types.IOVec.buffer)
+      iovecs
+  in
+  Eio.Flow.write flow cstructs
+
+(** Read into bigstring *)
+let read_into flow buf ~off ~len =
+  let cs = Cstruct.of_bigarray ~off ~len buf in
+  try `Ok (Eio.Flow.single_read flow cs) with End_of_file -> `Eof
+
+(** Perform HTTP request on connection. Returns (response, keep_alive) *)
+let do_request ?(body = "") conn req =
+  let flow = conn.flow in
+  let read_buffer = conn.read_buffer in
+  let response_received = Eio.Promise.create () in
+  let body_chunks = ref [] in
+  (* Collect chunks, concat at end - faster than Buffer *)
+  let resolved = ref false in
+  let keep_alive = ref true in
+
+  let resolve_once result =
+    if not !resolved then begin
+      resolved := true;
+      Eio.Promise.resolve (snd response_received) result
+    end
+  in
+
+  let response_handler resp body_reader =
+    (* Check Connection header *)
+    (match H1.Headers.get resp.H1.Response.headers "connection" with
+    | Some v when String.lowercase_ascii v = "close" -> keep_alive := false
+    | _ -> ());
+
+    let rec read_body () =
+      H1.Body.Reader.schedule_read body_reader
+        ~on_eof:(fun () ->
+          let response_body = String.concat "" (List.rev !body_chunks) in
+          resolve_once
+            (Ok
+               ( {
+                   H1_client.status = resp.H1.Response.status;
+                   headers = resp.headers;
+                   body = response_body;
+                 },
+                 !keep_alive )))
+        ~on_read:(fun buf ~off ~len ->
+          body_chunks := Bigstringaf.substring buf ~off ~len :: !body_chunks;
+          read_body ())
+    in
+    read_body ()
+  in
+
+  let error_handler err =
+    keep_alive := false;
+    conn.alive <- false;
+    let msg =
+      match err with
+      | `Malformed_response s -> s
+      | `Invalid_response_body_length _ -> "Invalid body length"
+      | `Exn exn -> Printexc.to_string exn
+    in
+    resolve_once (Error (H1_client.Invalid_response msg))
+  in
+
+  let body_writer, h1_conn =
+    H1.Client_connection.request req ~error_handler ~response_handler
+  in
+
+  if String.length body > 0 then begin
+    H1.Body.Writer.write_string body_writer body;
+    H1.Body.Writer.flush body_writer (fun () -> ())
+  end;
+  H1.Body.Writer.close body_writer;
+
+  (* I/O loop *)
+  let rec loop () =
+    let write_done =
+      match H1.Client_connection.next_write_operation h1_conn with
+      | `Write iovecs ->
+          write_iovecs flow iovecs;
+          let len =
+            List.fold_left
+              (fun acc iov -> acc + iov.Httpun_types.IOVec.len)
+              0 iovecs
+          in
+          H1.Client_connection.report_write_result h1_conn (`Ok len);
+          false
+      | `Yield -> true
+      | `Close _ -> true
+    in
+    let read_done =
+      match H1.Client_connection.next_read_operation h1_conn with
+      | `Read -> (
+          match read_into flow read_buffer ~off:0 ~len:read_buffer_size with
+          | `Ok n ->
+              let _ =
+                H1.Client_connection.read h1_conn read_buffer ~off:0 ~len:n
+              in
+              false
+          | `Eof ->
+              conn.alive <- false;
+              let _ =
+                H1.Client_connection.read_eof h1_conn read_buffer ~off:0 ~len:0
+              in
+              true)
+      | `Close -> true
+    in
+    if not (write_done && read_done) then loop ()
+  in
+
+  (try loop () with _ -> conn.alive <- false);
+  Eio.Promise.await (fst response_received)
+
+(** Acquire connection from pool or create new *)
+let acquire_conn pool ~sw ~net =
+  Eio.Mutex.use_rw ~protect:true pool.mutex (fun () ->
+      match pool.conn with
+      | Some c when c.alive -> Ok c
+      | _ -> (
+          (* Create new connection *)
+          match create_conn pool ~sw ~net with
+          | Ok c ->
+              pool.conn <- Some c;
+              Ok c
+          | Error e -> Error e))
+
+(** Release connection back to pool *)
+let release_conn pool conn ~keep_alive =
+  if not keep_alive then
+    Eio.Mutex.use_rw ~protect:true pool.mutex (fun () ->
+        close_conn conn;
+        pool.conn <- None)
+
+(** {1 HTTP Methods} *)
+
+(** Perform a GET request.
+
+    @param pool
+      Optional connection pool. If provided, reuses connections (fast path). If
+      omitted, creates a one-shot connection. *)
+let get ?pool ~sw ~net ~clock:_ uri =
+  match pool with
+  | Some p -> (
+      (* Fast path: use cached host/path from pool *)
+      let headers =
+        H1.Headers.of_list [ ("Host", p.host); ("Connection", "keep-alive") ]
+      in
+      let req = H1.Request.create ~headers `GET p.path in
+      match acquire_conn p ~sw ~net with
+      | Error e -> Error e
+      | Ok conn -> (
+          let result = do_request conn req in
+          match result with
+          | Ok (resp, keep_alive) ->
+              release_conn p conn ~keep_alive;
+              Ok resp
+          | Error e ->
+              release_conn p conn ~keep_alive:false;
+              Error e))
+  | None -> (
+      (* Slow path: parse URI for one-shot connection *)
+      let host = Uri.host uri |> Option.value ~default:"localhost" in
+      let path =
+        let p = Uri.path_and_query uri in
+        if p = "" then "/" else p
+      in
+      let headers =
+        H1.Headers.of_list [ ("Host", host); ("Connection", "close") ]
+      in
+      let req = H1.Request.create ~headers `GET path in
+      let temp_pool = create_pool uri in
+      match acquire_conn temp_pool ~sw ~net with
+      | Error e -> Error e
+      | Ok conn ->
+          let result = do_request conn req in
+          close_conn conn;
+          Result.map fst result)
+
+(** Perform a POST request.
+
+    @param pool
+      Optional connection pool. If provided, reuses connections (fast path). If
+      omitted, creates a one-shot connection.
+    @param body Request body *)
+let post ?pool ~sw ~net ~clock:_ uri ~body =
+  let content_length = String.length body in
+  match pool with
+  | Some p -> (
+      (* Fast path: use cached host/path from pool *)
+      let headers =
+        H1.Headers.of_list
+          [
+            ("Host", p.host);
+            ("Connection", "keep-alive");
+            ("Content-Length", string_of_int content_length);
+          ]
+      in
+      let req = H1.Request.create ~headers `POST p.path in
+      match acquire_conn p ~sw ~net with
+      | Error e -> Error e
+      | Ok conn -> (
+          let result = do_request ~body conn req in
+          match result with
+          | Ok (resp, keep_alive) ->
+              release_conn p conn ~keep_alive;
+              Ok resp
+          | Error e ->
+              release_conn p conn ~keep_alive:false;
+              Error e))
+  | None -> (
+      (* Slow path: parse URI for one-shot connection *)
+      let host = Uri.host uri |> Option.value ~default:"localhost" in
+      let path =
+        let p = Uri.path_and_query uri in
+        if p = "" then "/" else p
+      in
+      let headers =
+        H1.Headers.of_list
+          [
+            ("Host", host);
+            ("Connection", "close");
+            ("Content-Length", string_of_int content_length);
+          ]
+      in
+      let req = H1.Request.create ~headers `POST path in
+      let temp_pool = create_pool uri in
+      match acquire_conn temp_pool ~sw ~net with
+      | Error e -> Error e
+      | Ok conn ->
+          let result = do_request ~body conn req in
+          close_conn conn;
+          Result.map fst result)

lib/request.ml

···
+(** Request helper functions.
+
+    This module provides utility functions for working with HTTP requests,
+    including header access, query parameter parsing, and body handling. *)
+
+(** {1 Internal helpers} *)
+
+let string_contains haystack pattern =
+  let plen = String.length pattern in
+  let hlen = String.length haystack in
+  if plen > hlen then false
+  else
+    let rec check i =
+      if i > hlen - plen then false
+      else if String.sub haystack i plen = pattern then true
+      else check (i + 1)
+    in
+    check 0
+
+(** {1 Types} *)
+
+type t = H1_server.request
+(** Request type - re-exported from H1_server for convenience *)
+
+(** {1 Basic accessors} *)
+
+let meth (req : t) = req.meth
+let target (req : t) = req.target
+let headers (req : t) = req.headers
+
+(** Read the request body as a string (reads lazily on first call) *)
+let body (req : t) = H1_server.read_body req
+
+(** Get the body reader for streaming access *)
+let body_reader (req : t) = req.body_reader
+
+(** {1 Path and Query} *)
+
+(** Get the path component (without query string) *)
+let path (req : t) =
+  match String.index_opt req.target '?' with
+  | Some i -> String.sub req.target 0 i
+  | None -> req.target
+
+(** Get the query string (without leading ?) *)
+let query_string (req : t) =
+  match String.index_opt req.target '?' with
+  | Some i ->
+      Some (String.sub req.target (i + 1) (String.length req.target - i - 1))
+  | None -> None
+
+(** Parse query string into key-value pairs *)
+let query_params (req : t) =
+  match query_string req with
+  | None -> []
+  | Some qs ->
+      let pairs = String.split_on_char '&' qs in
+      List.filter_map
+        (fun pair ->
+          match String.index_opt pair '=' with
+          | Some i ->
+              let key = String.sub pair 0 i in
+              let value =
+                String.sub pair (i + 1) (String.length pair - i - 1)
+              in
+              (* URL decode *)
+              Some (Uri.pct_decode key, Uri.pct_decode value)
+          | None -> Some (Uri.pct_decode pair, ""))
+        pairs
+
+(** Get a single query parameter value *)
+let query key req = List.assoc_opt key (query_params req)
+
+(** Get all values for a query parameter *)
+let query_all key req =
+  List.filter_map
+    (fun (k, v) -> if String.equal k key then Some v else None)
+    (query_params req)
+
+(** {1 Header accessors} *)
+
+(** Get a header value (case-insensitive) *)
+let header name (req : t) = H1.Headers.get req.headers name
+
+(** Get all values for a header *)
+let header_all name (req : t) = H1.Headers.get_multi req.headers name
+
+(** Check if header exists *)
+let has_header name (req : t) =
+  match H1.Headers.get req.headers name with Some _ -> true | None -> false
+
+(** {1 Common header helpers} *)
+
+(** Get Content-Type header *)
+let content_type req = header "content-type" req
+
+(** Get Content-Length header as int64 *)
+let content_length req =
+  match header "content-length" req with
+  | Some s -> Int64.of_string_opt s
+  | None -> None
+
+(** Check if request is keep-alive *)
+let is_keep_alive (req : t) =
+  match header "connection" req with
+  | Some v -> String.lowercase_ascii v = "keep-alive"
+  | None -> true (* HTTP/1.1 default is keep-alive *)
+
+(** Get Host header *)
+let host req = header "host" req
+
+(** Get Accept header *)
+let accept req = header "accept" req
+
+(** Get Authorization header *)
+let authorization req = header "authorization" req
+
+(** Check if request accepts JSON *)
+let accepts_json req =
+  match accept req with
+  | Some v -> string_contains v "application/json" || string_contains v "*/*"
+  | None -> false
+
+(** Check if request accepts HTML *)
+let accepts_html req =
+  match accept req with
+  | Some v -> string_contains v "text/html" || string_contains v "*/*"
+  | None -> false
+
+(** {1 Method helpers} *)
+
+let is_get (req : t) = req.meth = `GET
+let is_post (req : t) = req.meth = `POST
+let is_put (req : t) = req.meth = `PUT
+let is_delete (req : t) = req.meth = `DELETE
+let is_patch (req : t) = req.meth = `Other "PATCH"
+let is_head (req : t) = req.meth = `HEAD
+let is_options (req : t) = req.meth = `OPTIONS
+
+(** Check if method is safe (GET, HEAD, OPTIONS) *)
+let is_safe (req : t) =
+  match req.meth with `GET | `HEAD | `OPTIONS -> true | _ -> false
+
+(** Check if method is idempotent (GET, HEAD, PUT, DELETE, OPTIONS) *)
+let is_idempotent (req : t) =
+  match req.meth with
+  | `GET | `HEAD | `PUT | `DELETE | `OPTIONS -> true
+  | _ -> false
+
+(** {1 Body helpers} *)
+
+let body_string (req : t) = body req
+let body_length (req : t) = String.length (body req)
+let has_body (req : t) = String.length (body req) > 0
+
+(** {1 Form data parsing} *)
+
+let form_data (req : t) =
+  let b = body req in
+  if String.length b = 0 then []
+  else
+    let pairs = String.split_on_char '&' b in
+    List.filter_map
+      (fun pair ->
+        match String.index_opt pair '=' with
+        | Some i ->
+            let key = String.sub pair 0 i in
+            let value = String.sub pair (i + 1) (String.length pair - i - 1) in
+            Some (Uri.pct_decode key, Uri.pct_decode value)
+        | None -> Some (Uri.pct_decode pair, ""))
+      pairs
+
+let form_field key req = List.assoc_opt key (form_data req)

lib/response.ml

···
+(** Response helper functions.
+
+    This module provides utility functions for creating and modifying HTTP
+    responses, including status shortcuts, body helpers, and header
+    manipulation. *)
+
+(** {1 Types} *)
+
+type t = H1_server.response
+
+let make ?(status = `OK) ?(headers = []) body : t =
+  { status; headers; response_body = H1_server.Body_string body }
+
+let empty ?(status = `OK) ?(headers = []) () : t =
+  { status; headers; response_body = H1_server.Body_string "" }
+
+(** {1 Status shortcuts - 2xx Success} *)
+
+let ok ?(headers = []) body : t =
+  { status = `OK; headers; response_body = H1_server.Body_string body }
+
+let created ?(headers = []) ?location body : t =
+  let headers =
+    match location with
+    | Some loc -> ("Location", loc) :: headers
+    | None -> headers
+  in
+  { status = `Created; headers; response_body = H1_server.Body_string body }
+
+let accepted ?(headers = []) body : t =
+  { status = `Accepted; headers; response_body = H1_server.Body_string body }
+
+let no_content ?(headers = []) () : t =
+  { status = `No_content; headers; response_body = H1_server.Body_string "" }
+
+(** {1 Status shortcuts - 3xx Redirection} *)
+
+let redirect ?(permanent = false) ?(headers = []) location : t =
+  let status = if permanent then `Moved_permanently else `Found in
+  {
+    status;
+    headers = ("Location", location) :: headers;
+    response_body = H1_server.Body_string "";
+  }
+
+let moved_permanently ?(headers = []) location : t =
+  redirect ~permanent:true ~headers location
+
+let found ?(headers = []) location : t =
+  redirect ~permanent:false ~headers location
+
+let see_other ?(headers = []) location : t =
+  {
+    status = `See_other;
+    headers = ("Location", location) :: headers;
+    response_body = H1_server.Body_string "";
+  }
+
+let temporary_redirect ?(headers = []) location : t =
+  {
+    status = `Temporary_redirect;
+    headers = ("Location", location) :: headers;
+    response_body = H1_server.Body_string "";
+  }
+
+let not_modified ?(headers = []) () : t =
+  { status = `Not_modified; headers; response_body = H1_server.Body_string "" }
+
+(** {1 Status shortcuts - 4xx Client Errors} *)
+
+let bad_request ?(headers = []) ?(body = "Bad Request") () : t =
+  { status = `Bad_request; headers; response_body = H1_server.Body_string body }
+
+let unauthorized ?(headers = []) ?www_authenticate () : t =
+  let headers =
+    match www_authenticate with
+    | Some auth -> ("WWW-Authenticate", auth) :: headers
+    | None -> headers
+  in
+  {
+    status = `Unauthorized;
+    headers;
+    response_body = H1_server.Body_string "Unauthorized";
+  }
+
+let forbidden ?(headers = []) ?(body = "Forbidden") () : t =
+  { status = `Forbidden; headers; response_body = H1_server.Body_string body }
+
+let not_found ?(headers = []) ?(body = "Not Found") () : t =
+  { status = `Not_found; headers; response_body = H1_server.Body_string body }
+
+let method_not_allowed ?(headers = []) ~allowed () : t =
+  let allow_header =
+    String.concat ", " (List.map H1.Method.to_string allowed)
+  in
+  {
+    status = `Method_not_allowed;
+    headers = ("Allow", allow_header) :: headers;
+    response_body = H1_server.Body_string "Method Not Allowed";
+  }
+
+let conflict ?(headers = []) ?(body = "Conflict") () : t =
+  { status = `Conflict; headers; response_body = H1_server.Body_string body }
+
+let gone ?(headers = []) ?(body = "Gone") () : t =
+  { status = `Gone; headers; response_body = H1_server.Body_string body }
+
+let unprocessable_entity ?(headers = []) ?(body = "Unprocessable Entity") () : t
+    =
+  { status = `Code 422; headers; response_body = H1_server.Body_string body }
+
+let too_many_requests ?(headers = []) ?retry_after () : t =
+  let headers =
+    match retry_after with
+    | Some secs -> ("Retry-After", string_of_int secs) :: headers
+    | None -> headers
+  in
+  {
+    status = `Code 429;
+    headers;
+    response_body = H1_server.Body_string "Too Many Requests";
+  }
+
+(** {1 Status shortcuts - 5xx Server Errors} *)
+
+let internal_error ?(headers = []) ?(body = "Internal Server Error") () : t =
+  {
+    status = `Internal_server_error;
+    headers;
+    response_body = H1_server.Body_string body;
+  }
+
+let not_implemented ?(headers = []) ?(body = "Not Implemented") () : t =
+  {
+    status = `Not_implemented;
+    headers;
+    response_body = H1_server.Body_string body;
+  }
+
+let bad_gateway ?(headers = []) ?(body = "Bad Gateway") () : t =
+  { status = `Bad_gateway; headers; response_body = H1_server.Body_string body }
+
+let service_unavailable ?(headers = []) ?retry_after () : t =
+  let headers =
+    match retry_after with
+    | Some secs -> ("Retry-After", string_of_int secs) :: headers
+    | None -> headers
+  in
+  {
+    status = `Service_unavailable;
+    headers;
+    response_body = H1_server.Body_string "Service Unavailable";
+  }
+
+let gateway_timeout ?(headers = []) ?(body = "Gateway Timeout") () : t =
+  {
+    status = `Gateway_timeout;
+    headers;
+    response_body = H1_server.Body_string body;
+  }
+
+(** {1 Content-Type helpers} *)
+
+let text ?(status = `OK) body : t =
+  {
+    status;
+    headers = [ ("Content-Type", "text/plain; charset=utf-8") ];
+    response_body = H1_server.Body_string body;
+  }
+
+let html ?(status = `OK) body : t =
+  {
+    status;
+    headers = [ ("Content-Type", "text/html; charset=utf-8") ];
+    response_body = H1_server.Body_string body;
+  }
+
+let json ?(status = `OK) body : t =
+  {
+    status;
+    headers = [ ("Content-Type", "application/json; charset=utf-8") ];
+    response_body = H1_server.Body_string body;
+  }
+
+let xml ?(status = `OK) body : t =
+  {
+    status;
+    headers = [ ("Content-Type", "application/xml; charset=utf-8") ];
+    response_body = H1_server.Body_string body;
+  }
+
+(** {1 Response modifiers} *)
+
+(** Add a header to the response *)
+let with_header name value (resp : t) : t =
+  { resp with headers = (name, value) :: resp.headers }
+
+(** Add multiple headers to the response *)
+let with_headers headers (resp : t) : t =
+  { resp with headers = headers @ resp.headers }
+
+(** Replace the response body *)
+let with_body body (resp : t) : t =
+  { resp with response_body = H1_server.Body_string body }
+
+(** Replace the response status *)
+let with_status status (resp : t) : t = { resp with status }
+
+(** Set Content-Type header *)
+let with_content_type content_type resp =
+  with_header "Content-Type" content_type resp
+
+(** Set Cache-Control header *)
+let with_cache_control directive resp =
+  with_header "Cache-Control" directive resp
+
+(** Set no-cache headers *)
+let with_no_cache resp =
+  resp
+  |> with_header "Cache-Control" "no-store, no-cache, must-revalidate"
+  |> with_header "Pragma" "no-cache"
+
+(** Set CORS headers for all origins *)
+let with_cors ?(origin = "*") ?(methods = "GET, POST, PUT, DELETE, OPTIONS")
+    ?(headers = "Content-Type, Authorization") resp =
+  resp
+  |> with_header "Access-Control-Allow-Origin" origin
+  |> with_header "Access-Control-Allow-Methods" methods
+  |> with_header "Access-Control-Allow-Headers" headers
+
+(** {1 Cookie helpers} *)
+
+(** Set a cookie *)
+let with_cookie ?(path = "/") ?(http_only = true) ?(secure = false)
+    ?(same_site = "Lax") ?max_age name value resp =
+  let parts = [ Printf.sprintf "%s=%s" name value; "Path=" ^ path ] in
+  let parts = if http_only then parts @ [ "HttpOnly" ] else parts in
+  let parts = if secure then parts @ [ "Secure" ] else parts in
+  let parts = parts @ [ "SameSite=" ^ same_site ] in
+  let parts =
+    match max_age with
+    | Some age -> parts @ [ Printf.sprintf "Max-Age=%d" age ]
+    | None -> parts
+  in
+  with_header "Set-Cookie" (String.concat "; " parts) resp
+
+(** Clear a cookie *)
+let clear_cookie ?(path = "/") name resp =
+  with_cookie ~path ~max_age:0 name "" resp

lib/router.ml

···
+(** Type-safe router with radix trie for efficient path matching.
+
+    This module provides:
+    - Type-safe path patterns with parameter extraction
+    - Radix trie for O(path_length) route lookup
+    - Hashtbl for O(1) literal segment matching
+    - Middleware support
+    - Route scoping/grouping *)
+
+(** Path segment types *)
+type segment =
+  | Literal of string  (** Exact match *)
+  | Param of string  (** Named parameter capture *)
+  | Wildcard  (** Match rest of path *)
+
+type params = (string * string) list
+(** Parsed path parameters *)
+
+type 'a route = {
+  method_ : H1.Method.t option;  (** None = match any method *)
+  segments : segment list;
+  handler : 'a;
+}
+(** A route definition *)
+
+type 'a trie_node = {
+  mutable handlers : (H1.Method.t option * 'a) list;
+      (** Handlers at this node *)
+  literal_children : (string, 'a trie_node) Hashtbl.t;
+      (** O(1) lookup for literal segments *)
+  mutable param_child : (string * 'a trie_node) option;
+      (** Single param child (with param name) *)
+  mutable wildcard_child : 'a trie_node option;  (** Single wildcard child *)
+}
+(** Radix trie node with optimized child storage *)
+
+type 'a t = { root : 'a trie_node }
+(** Compiled router *)
+
+(** Create empty trie node *)
+let empty_node () =
+  {
+    handlers = [];
+    literal_children = Hashtbl.create 8;
+    param_child = None;
+    wildcard_child = None;
+  }
+
+(** Create empty router *)
+let empty () = { root = empty_node () }
+
+(** Parse path string into segments *)
+let parse_path path =
+  let path =
+    if String.length path > 0 && path.[0] = '/' then
+      String.sub path 1 (String.length path - 1)
+    else path
+  in
+  if path = "" then []
+  else
+    String.split_on_char '/' path
+    |> List.filter (fun s -> s <> "")
+    |> List.map (fun s ->
+        if String.length s > 0 && s.[0] = ':' then
+          Param (String.sub s 1 (String.length s - 1))
+        else if s = "*" then Wildcard
+        else Literal s)
+
+(** Find or create child node for segment *)
+let find_or_create_child node seg =
+  match seg with
+  | Literal s -> (
+      match Hashtbl.find_opt node.literal_children s with
+      | Some child -> child
+      | None ->
+          let child = empty_node () in
+          Hashtbl.add node.literal_children s child;
+          child)
+  | Param name -> (
+      match node.param_child with
+      | Some (_, child) -> child
+      | None ->
+          let child = empty_node () in
+          node.param_child <- Some (name, child);
+          child)
+  | Wildcard -> (
+      match node.wildcard_child with
+      | Some child -> child
+      | None ->
+          let child = empty_node () in
+          node.wildcard_child <- Some child;
+          child)
+
+(** Add a route to the trie *)
+let add_route router ~method_ ~path ~handler =
+  let segments = parse_path path in
+  let rec insert node = function
+    | [] -> node.handlers <- (method_, handler) :: node.handlers
+    | seg :: rest ->
+        let child = find_or_create_child node seg in
+        insert child rest
+  in
+  insert router.root segments
+
+(** Lookup a path in the trie - optimized with index-based parsing *)
+let lookup router ~method_ ~path =
+  let len = String.length path in
+  let start = if len > 0 && path.[0] = '/' then 1 else 0 in
+
+  let rec search node pos params =
+    if pos >= len then
+      List.find_opt
+        (fun (m, _) -> match m with None -> true | Some m' -> m' = method_)
+        node.handlers
+      |> Option.map (fun (_, handler) -> (handler, params))
+    else
+      let seg_end =
+        try String.index_from path pos '/' with Not_found -> len
+      in
+      if seg_end = pos then search node (pos + 1) params
+      else
+        let seg = String.sub path pos (seg_end - pos) in
+        let next_pos = if seg_end < len then seg_end + 1 else len in
+        match Hashtbl.find_opt node.literal_children seg with
+        | Some child -> search child next_pos params
+        | None -> (
+            match node.param_child with
+            | Some (name, child) -> search child next_pos ((name, seg) :: params)
+            | None -> (
+                match node.wildcard_child with
+                | Some child ->
+                    let rest_path = String.sub path pos (len - pos) in
+                    search child len (("*", rest_path) :: params)
+                | None -> None))
+  in
+  search router.root start []
+
+(** Route builder DSL *)
+module Route = struct
+  type 'a t = { method_ : H1.Method.t option; path : string; handler : 'a }
+
+  let get path handler = { method_ = Some `GET; path; handler }
+  let post path handler = { method_ = Some `POST; path; handler }
+  let put path handler = { method_ = Some `PUT; path; handler }
+  let delete path handler = { method_ = Some `DELETE; path; handler }
+  let patch path handler = { method_ = Some (`Other "PATCH"); path; handler }
+  let head path handler = { method_ = Some `HEAD; path; handler }
+  let options path handler = { method_ = Some `OPTIONS; path; handler }
+  let any path handler = { method_ = None; path; handler }
+end
+
+(** Compile routes into a router *)
+let compile routes =
+  let router = empty () in
+  List.iter
+    (fun r ->
+      add_route router ~method_:r.Route.method_ ~path:r.path ~handler:r.handler)
+    routes;
+  router
+
+(** Get parameter from params list *)
+let param name params = List.assoc_opt name params
+
+(** Get parameter with default *)
+let param_or name ~default params =
+  match List.assoc_opt name params with Some v -> v | None -> default
+
+(** Get parameter as int *)
+let param_int name params =
+  match List.assoc_opt name params with
+  | Some v -> int_of_string_opt v
+  | None -> None
+
+(** Get parameter as int with default *)
+let param_int_or name ~default params =
+  match param_int name params with Some v -> v | None -> default

lib/server.ml

···
+(** Unified HTTP Server - High-performance server supporting HTTP/1.1, HTTP/2,
+    and WebSocket.
+
+    This module consolidates all server functionality into a single,
+    high-performance implementation. Protocol detection overhead is optional and
+    controlled via the [protocol] configuration.
+
+    {2 Protocol Modes}
+
+    - [Http1_only]: Fastest path. No protocol detection, direct HTTP/1.1
+      handling.
+    - [Http2_only]: HTTP/2 only. h2c (cleartext) or h2 (over TLS).
+    - [Auto]: Auto-detect protocol via connection preface peek (h2c) or ALPN
+      (TLS).
+    - [Auto_websocket]: Auto-detect with WebSocket upgrade support.
+
+    {2 Performance Features}
+
+    - GC tuning for high-throughput scenarios
+    - Cached Date headers (1-second resolution)
+    - Pre-built responses for zero-allocation hot paths
+    - Zero-copy bigstring responses
+    - Streaming response support
+    - Multi-domain parallelism via Eio
+
+    {2 Example}
+
+    {[
+      (* Fastest HTTP/1.1 server *)
+      let handler req = Server.respond "Hello, World!" in
+      Server.run ~sw ~net handler
+
+      (* Multi-protocol with auto-detection *)
+      let config = Server.{ default_config with protocol = Auto } in
+      Server.run ~sw ~net ~config handler
+    ]} *)
+
+open Eio.Std
+
+(** {1 Protocol Configuration} *)
+
+(** Protocol mode controls detection overhead and supported protocols. *)
+type protocol =
+  | Http1_only
+      (** Fastest: No protocol detection, direct HTTP/1.1 handling. With TLS:
+          HTTP/1.1 over TLS (no ALPN negotiation). *)
+  | Http2_only
+      (** HTTP/2 only. Without TLS: h2c (HTTP/2 cleartext). With TLS: h2 with
+          ALPN advertising only "h2". *)
+  | Auto
+      (** Auto-detect protocol. Without TLS: Peek for "PRI " preface (h2c),
+          fallback to HTTP/1.1. With TLS: ALPN negotiation. *)
+  | Auto_websocket
+      (** Auto-detect with WebSocket support. Same as [Auto] but also handles
+          WebSocket upgrade requests in HTTP/1.1 mode. *)
+
+(** {1 GC Tuning} *)
+
+module Gc_tune = struct
+  type config = {
+    minor_heap_size : int;  (** Minor heap size in bytes. Default: 64MB *)
+    major_heap_increment : int;
+        (** Major heap increment in bytes. Default: 32MB *)
+    space_overhead : int;  (** Space overhead percentage. Default: 200 *)
+    max_overhead : int;  (** Max overhead percentage. Default: 500 *)
+  }
+
+  let default =
+    {
+      minor_heap_size = 64 * 1024 * 1024;
+      major_heap_increment = 32 * 1024 * 1024;
+      space_overhead = 200;
+      max_overhead = 500;
+    }
+
+  let aggressive =
+    {
+      minor_heap_size = 128 * 1024 * 1024;
+      major_heap_increment = 64 * 1024 * 1024;
+      space_overhead = 400;
+      max_overhead = 1000;
+    }
+
+  let tuned = ref false
+
+  let apply ?(config = default) () =
+    if not !tuned then begin
+      let ctrl = Gc.get () in
+      Gc.set
+        {
+          ctrl with
+          minor_heap_size = config.minor_heap_size / (Sys.word_size / 8);
+          major_heap_increment =
+            config.major_heap_increment / (Sys.word_size / 8);
+          space_overhead = config.space_overhead;
+          max_overhead = config.max_overhead;
+        };
+      tuned := true
+    end
+end
+
+(** {1 Date Header Cache} *)
+
+module Date_cache = struct
+  let day_names = [| "Sun"; "Mon"; "Tue"; "Wed"; "Thu"; "Fri"; "Sat" |]
+
+  let month_names =
+    [|
+      "Jan";
+      "Feb";
+      "Mar";
+      "Apr";
+      "May";
+      "Jun";
+      "Jul";
+      "Aug";
+      "Sep";
+      "Oct";
+      "Nov";
+      "Dec";
+    |]
+
+  let cached_date = Atomic.make ""
+  let cached_time = Atomic.make 0.
+
+  let format_date () =
+    let t = Unix.gettimeofday () in
+    let tm = Unix.gmtime t in
+    Printf.sprintf "%s, %02d %s %04d %02d:%02d:%02d GMT"
+      day_names.(tm.Unix.tm_wday)
+      tm.Unix.tm_mday
+      month_names.(tm.Unix.tm_mon)
+      (1900 + tm.Unix.tm_year) tm.Unix.tm_hour tm.Unix.tm_min tm.Unix.tm_sec
+
+  let[@inline] get () =
+    let now = Unix.gettimeofday () in
+    let last = Atomic.get cached_time in
+    if now -. last >= 1.0 then begin
+      let date = format_date () in
+      Atomic.set cached_date date;
+      Atomic.set cached_time now;
+      date
+    end
+    else Atomic.get cached_date
+end
+
+(** {1 Pre-built Responses} *)
+
+(** Pre-built response for zero-allocation hot paths. Create once at startup,
+    respond many times without allocation. *)
+module Prebuilt = struct
+  type t = {
+    status : H1.Status.t;
+    headers : H1.Headers.t;
+    body : Bigstringaf.t;
+    (* Cached H1 response with date header - regenerated per-second (thread-safe) *)
+    cached_h1_response : H1.Response.t Atomic.t;
+    cached_second : int Atomic.t;
+  }
+
+  (** Create a pre-built response from a string body. *)
+  let create ~status ?(headers = []) body =
+    let body_bstr =
+      Bigstringaf.of_string ~off:0 ~len:(String.length body) body
+    in
+    let body_len = Bigstringaf.length body_bstr in
+    let all_headers = ("content-length", string_of_int body_len) :: headers in
+    let h1_headers = H1.Headers.of_list all_headers in
+    let now = int_of_float (Unix.gettimeofday ()) in
+    let headers_with_date =
+      H1.Headers.add h1_headers "date" (Date_cache.get ())
+    in
+    let cached_resp = H1.Response.create ~headers:headers_with_date status in
+    {
+      status;
+      headers = h1_headers;
+      body = body_bstr;
+      cached_h1_response = Atomic.make cached_resp;
+      cached_second = Atomic.make now;
+    }
+
+  (** Create a pre-built response from a bigstring body. *)
+  let create_bigstring ~status ?(headers = []) body =
+    let body_len = Bigstringaf.length body in
+    let all_headers = ("content-length", string_of_int body_len) :: headers in
+    let h1_headers = H1.Headers.of_list all_headers in
+    let now = int_of_float (Unix.gettimeofday ()) in
+    let headers_with_date =
+      H1.Headers.add h1_headers "date" (Date_cache.get ())
+    in
+    let cached_resp = H1.Response.create ~headers:headers_with_date status in
+    {
+      status;
+      headers = h1_headers;
+      body;
+      cached_h1_response = Atomic.make cached_resp;
+      cached_second = Atomic.make now;
+    }
+
+  (** Get cached H1 response, regenerating if second has changed. *)
+  let[@inline] get_cached_h1_response t =
+    let now = int_of_float (Unix.gettimeofday ()) in
+    let last = Atomic.get t.cached_second in
+    if now <> last then begin
+      let headers = H1.Headers.add t.headers "date" (Date_cache.get ()) in
+      let resp = H1.Response.create ~headers t.status in
+      Atomic.set t.cached_h1_response resp;
+      Atomic.set t.cached_second now
+    end;
+    Atomic.get t.cached_h1_response
+
+  (** Respond to an H1 request descriptor with a pre-built response. Uses cached
+      response that only regenerates when the second changes. *)
+  let[@inline] respond_h1 reqd t =
+    let response = get_cached_h1_response t in
+    H1.Reqd.respond_with_bigstring reqd response t.body
+
+  (** Respond to an H2 request descriptor with a pre-built response. *)
+  let[@inline] respond_h2 reqd t =
+    let result = ref [] in
+    H1.Headers.iter
+      ~f:(fun name value -> result := (name, value) :: !result)
+      t.headers;
+    let h2_headers = H2.Headers.of_list (List.rev !result) in
+    let h2_status = (t.status :> H2.Status.t) in
+    let response = H2.Response.create ~headers:h2_headers h2_status in
+    H2.Reqd.respond_with_bigstring reqd response t.body
+end
+
+(** {1 Types} *)
+
+type config = {
+  (* Network *)
+  host : string;  (** Bind address. Default: "0.0.0.0" *)
+  port : int;  (** Listen port. Default: 8080 *)
+  backlog : int;  (** Listen backlog. Default: 4096 *)
+  max_connections : int;  (** Max concurrent connections. Default: 100000 *)
+  (* Parallelism *)
+  domain_count : int;  (** Number of domains (CPUs) to use. Default: 1 *)
+  (* Protocol *)
+  protocol : protocol;  (** Protocol mode. Default: Http1_only *)
+  (* Timeouts *)
+  read_timeout : float;  (** Read timeout in seconds. Default: 60.0 *)
+  write_timeout : float;  (** Write timeout in seconds. Default: 60.0 *)
+  idle_timeout : float;  (** Idle connection timeout. Default: 120.0 *)
+  request_timeout : float;  (** Request processing timeout. Default: 30.0 *)
+  (* Limits *)
+  max_header_size : int;  (** Max header size in bytes. Default: 8192 *)
+  max_body_size : int64 option;
+      (** Max body size. None = unlimited. Default: None *)
+  (* Buffers *)
+  buffer_size : int;  (** Read buffer size. Default: 16384 *)
+  (* Socket options *)
+  tcp_nodelay : bool;  (** Set TCP_NODELAY on connections. Default: true *)
+  reuse_addr : bool;  (** Set SO_REUSEADDR on listener. Default: true *)
+  reuse_port : bool;  (** Set SO_REUSEPORT on listener. Default: true *)
+  (* TLS *)
+  tls : Tls_config.Server.t option;  (** TLS config. None = plain HTTP *)
+  (* Performance *)
+  gc_tuning : Gc_tune.config option;
+      (** GC tuning config. Some = apply tuning. Default: Some Gc_tune.default
+      *)
+}
+(** Server configuration. *)
+
+(** Default configuration optimized for HTTP/1.1 performance. *)
+let default_config =
+  {
+    host = "0.0.0.0";
+    port = 8080;
+    backlog = 4096;
+    max_connections = 100000;
+    domain_count = 1;
+    protocol = Http1_only;
+    read_timeout = 60.0;
+    write_timeout = 60.0;
+    idle_timeout = 120.0;
+    request_timeout = 30.0;
+    max_header_size = 8192;
+    max_body_size = None;
+    buffer_size = 16384;
+    tcp_nodelay = true;
+    reuse_addr = true;
+    reuse_port = true;
+    tls = None;
+    gc_tuning = Some Gc_tune.default;
+  }
+
+(** Configuration for auto-detection mode. *)
+let auto_config = { default_config with protocol = Auto }
+
+(** Configuration for WebSocket support. *)
+let websocket_config = { default_config with protocol = Auto_websocket }
+
+(** {2 Config Builders} *)
+
+let with_port port config = { config with port }
+let with_host host config = { config with host }
+let with_backlog backlog config = { config with backlog }
+let with_max_connections max config = { config with max_connections = max }
+let with_domain_count count config = { config with domain_count = count }
+let with_protocol protocol config = { config with protocol }
+let with_read_timeout timeout config = { config with read_timeout = timeout }
+let with_write_timeout timeout config = { config with write_timeout = timeout }
+let with_idle_timeout timeout config = { config with idle_timeout = timeout }
+
+let with_request_timeout timeout config =
+  { config with request_timeout = timeout }
+
+let with_max_header_size size config = { config with max_header_size = size }
+let with_max_body_size size config = { config with max_body_size = Some size }
+let with_buffer_size size config = { config with buffer_size = size }
+let with_tcp_nodelay enabled config = { config with tcp_nodelay = enabled }
+let with_tls tls config = { config with tls = Some tls }
+let with_gc_tuning gc config = { config with gc_tuning = Some gc }
+let without_gc_tuning config = { config with gc_tuning = None }
+
+(** {1 Request/Response Types} *)
+
+(** Protocol version indicator. *)
+type protocol_version = HTTP_1_1 | HTTP_2
+
+type request = {
+  meth : H1.Method.t;  (** HTTP method *)
+  target : string;  (** Request target (path + query) *)
+  headers : (string * string) list;  (** Headers as association list *)
+  body : string;  (** Request body (empty for GET/HEAD) *)
+  version : protocol_version;  (** Protocol version *)
+}
+(** Request type exposed to handlers. *)
+
+(** Response body variants. *)
+type response_body =
+  | Body_empty  (** Empty body (for 204 No Content, etc.) *)
+  | Body_string of string  (** String body - will be copied *)
+  | Body_bigstring of Bigstringaf.t  (** Bigstring body - zero-copy *)
+  | Body_prebuilt of Prebuilt.t  (** Pre-built response - zero allocation *)
+  | Body_stream of {
+      content_length : int64 option;
+      next : unit -> Cstruct.t option;
+    }  (** Streaming body *)
+
+type response = {
+  status : H1.Status.t;
+  headers : (string * string) list;
+  body : response_body;
+}
+(** Response type. *)
+
+type handler = request -> response
+(** Handler type. *)
+
+type ws_handler = Websocket.t -> unit
+(** WebSocket handler type. *)
+
+(** {1 Response Helpers} *)
+
+(** Create a response with a string body. *)
+let respond ?(status = `OK) ?(headers = []) body =
+  { status; headers; body = Body_string body }
+
+(** Create a response with a bigstring body (zero-copy). *)
+let respond_bigstring ?(status = `OK) ?(headers = []) body =
+  { status; headers; body = Body_bigstring body }
+
+(** Create a response with a pre-built body (zero-allocation). *)
+let respond_prebuilt prebuilt =
+  {
+    status = prebuilt.Prebuilt.status;
+    headers = [];
+    body = Body_prebuilt prebuilt;
+  }
+
+(** Create an empty response. *)
+let respond_empty ?(status = `No_content) ?(headers = []) () =
+  { status; headers; body = Body_empty }
+
+(** Create a streaming response. *)
+let respond_stream ?(status = `OK) ?(headers = []) ?content_length next =
+  { status; headers; body = Body_stream { content_length; next } }
+
+(** Create a plain text response. *)
+let respond_text ?(status = `OK) body =
+  {
+    status;
+    headers = [ ("content-type", "text/plain; charset=utf-8") ];
+    body = Body_string body;
+  }
+
+(** Create an HTML response. *)
+let respond_html ?(status = `OK) body =
+  {
+    status;
+    headers = [ ("content-type", "text/html; charset=utf-8") ];
+    body = Body_string body;
+  }
+
+(** Create a JSON response. *)
+let respond_json ?(status = `OK) body =
+  {
+    status;
+    headers = [ ("content-type", "application/json") ];
+    body = Body_string body;
+  }
+
+(** {1 Internal: Socket Helpers} *)
+
+let set_tcp_nodelay flow =
+  match Eio_unix.Resource.fd_opt flow with
+  | None -> ()
+  | Some fd ->
+      Eio_unix.Fd.use_exn "set_tcp_nodelay" fd (fun unix_fd ->
+          Unix.setsockopt unix_fd Unix.TCP_NODELAY true)
+
+let shutdown_flow flow cmd =
+  try Eio.Flow.shutdown flow cmd with
+  | Unix.Unix_error (Unix.ENOTCONN, _, _) -> ()
+  | Eio.Io (Eio.Exn.X (Eio_unix.Unix_error (Unix.ENOTCONN, _, _)), _) -> ()
+
+let[@inline] writev flow iovecs =
+  match iovecs with
+  | [] -> `Ok 0
+  | [ { Httpun_types.IOVec.buffer; off; len } ] -> (
+      let cs = Cstruct.of_bigarray buffer ~off ~len in
+      match Eio.Flow.write flow [ cs ] with
+      | () -> `Ok len
+      | exception End_of_file -> `Closed)
+  | _ -> (
+      let lenv, cstructs =
+        List.fold_left_map
+          (fun acc { Httpun_types.IOVec.buffer; off; len } ->
+            (acc + len, Cstruct.of_bigarray buffer ~off ~len))
+          0 iovecs
+      in
+      match Eio.Flow.write flow cstructs with
+      | () -> `Ok lenv
+      | exception End_of_file -> `Closed)
+
+(** {1 Internal: Header Conversion} *)
+
+let h1_headers_to_list headers =
+  let result = ref [] in
+  H1.Headers.iter
+    ~f:(fun name value -> result := (name, value) :: !result)
+    headers;
+  List.rev !result
+
+let h2_headers_to_list headers =
+  let result = ref [] in
+  H2.Headers.iter
+    ~f:(fun name value -> result := (name, value) :: !result)
+    headers;
+  List.rev !result
+
+(** {1 Internal: Protocol Detection} *)
+
+(** HTTP/2 connection preface starts with "PRI " *)
+let h2_preface_prefix = "PRI "
+
+let h2_preface_prefix_len = 4
+
+let peek_bytes flow n =
+  let buf = Cstruct.create n in
+  try
+    let read = Eio.Flow.single_read flow buf in
+    Ok (Cstruct.to_string (Cstruct.sub buf 0 read))
+  with
+  | End_of_file -> Error `Eof
+  | exn -> Error (`Exn exn)
+
+let is_h2_preface data =
+  String.length data >= h2_preface_prefix_len
+  && String.sub data 0 h2_preface_prefix_len = h2_preface_prefix
+
+(** {1 Internal: HTTP/1.1 Connection Handler} *)
+
+module H1_handler = struct
+  let handle ~handler ~ws_handler ~initial_data flow =
+    let buffer_size = 16384 in
+    let read_buffer = Bigstringaf.create buffer_size in
+    let read_cstruct =
+      Cstruct.of_bigarray read_buffer ~off:0 ~len:buffer_size
+    in
+
+    let pending_data = ref initial_data in
+    let ws_upgrade = ref None in
+
+    let request_handler reqd =
+      let req = H1.Reqd.request reqd in
+      let h1_body = H1.Reqd.request_body reqd in
+
+      (* Check for WebSocket upgrade *)
+      if Option.is_some ws_handler && Websocket.is_upgrade_request req.headers
+      then begin
+        match Websocket.get_websocket_key req.headers with
+        | Some key ->
+            ws_upgrade := Some key;
+            H1.Body.Reader.close h1_body;
+            let accept = Websocket.compute_accept_key key in
+            let headers =
+              H1.Headers.of_list
+                [
+                  ("upgrade", "websocket");
+                  ("connection", "Upgrade");
+                  ("sec-websocket-accept", accept);
+                ]
+            in
+            H1.Reqd.respond_with_upgrade reqd headers
+        | None ->
+            H1.Body.Reader.close h1_body;
+            let headers =
+              H1.Headers.of_list
+                [ ("date", Date_cache.get ()); ("content-length", "11") ]
+            in
+            let resp = H1.Response.create ~headers `Bad_request in
+            H1.Reqd.respond_with_string reqd resp "Bad Request"
+      end
+      else begin
+        (* Regular HTTP/1.1 request *)
+        (* Read body for POST/PUT, skip for GET/HEAD *)
+        let body =
+          match req.meth with
+          | `GET | `HEAD | `DELETE | `OPTIONS | `CONNECT | `TRACE ->
+              H1.Body.Reader.close h1_body;
+              ""
+          | `POST | `PUT | `Other _ ->
+              let body_buffer = Buffer.create 4096 in
+              let body_done, resolver = Eio.Promise.create () in
+              let rec read_body () =
+                H1.Body.Reader.schedule_read h1_body
+                  ~on_eof:(fun () -> Eio.Promise.resolve resolver ())
+                  ~on_read:(fun buf ~off ~len ->
+                    Buffer.add_string body_buffer
+                      (Bigstringaf.substring buf ~off ~len);
+                    read_body ())
+              in
+              read_body ();
+              Eio.Promise.await body_done;
+              Buffer.contents body_buffer
+        in
+
+        let request =
+          {
+            meth = req.meth;
+            target = req.target;
+            headers = h1_headers_to_list req.headers;
+            body;
+            version = HTTP_1_1;
+          }
+        in
+        let response = handler request in
+
+        (* Send response *)
+        let date_header = ("date", Date_cache.get ()) in
+        match response.body with
+        | Body_prebuilt prebuilt -> Prebuilt.respond_h1 reqd prebuilt
+        | Body_empty ->
+            let headers =
+              H1.Headers.of_list
+                (date_header :: ("content-length", "0") :: response.headers)
+            in
+            let resp = H1.Response.create ~headers response.status in
+            H1.Reqd.respond_with_string reqd resp ""
+        | Body_string body ->
+            let headers =
+              H1.Headers.of_list
+                (date_header
+                :: ("content-length", string_of_int (String.length body))
+                :: response.headers)
+            in
+            let resp = H1.Response.create ~headers response.status in
+            H1.Reqd.respond_with_string reqd resp body
+        | Body_bigstring body ->
+            let headers =
+              H1.Headers.of_list
+                (date_header
+                :: ("content-length", string_of_int (Bigstringaf.length body))
+                :: response.headers)
+            in
+            let resp = H1.Response.create ~headers response.status in
+            H1.Reqd.respond_with_bigstring reqd resp body
+        | Body_stream { content_length; next } ->
+            let headers =
+              match content_length with
+              | Some len ->
+                  H1.Headers.of_list
+                    (date_header
+                    :: ("content-length", Int64.to_string len)
+                    :: response.headers)
+              | None ->
+                  H1.Headers.of_list
+                    (date_header
+                    :: ("transfer-encoding", "chunked")
+                    :: response.headers)
+            in
+            let resp = H1.Response.create ~headers response.status in
+            let body_writer = H1.Reqd.respond_with_streaming reqd resp in
+            let rec write_chunks () =
+              match next () with
+              | None -> H1.Body.Writer.close body_writer
+              | Some cs ->
+                  H1.Body.Writer.write_bigstring body_writer ~off:0
+                    ~len:(Cstruct.length cs) (Cstruct.to_bigarray cs);
+                  write_chunks ()
+            in
+            write_chunks ()
+      end
+    in
+
+    let error_handler ?request:_ _error start_response =
+      let resp_body = start_response H1.Headers.empty in
+      H1.Body.Writer.write_string resp_body "Internal Server Error";
+      H1.Body.Writer.close resp_body
+    in
+
+    let conn = H1.Server_connection.create ~error_handler request_handler in
+    let shutdown = ref false in
+
+    let rec read_loop () =
+      if not !shutdown then
+        match H1.Server_connection.next_read_operation conn with
+        | `Read ->
+            let socket_data =
+              match Eio.Flow.single_read flow read_cstruct with
+              | n -> Cstruct.to_string (Cstruct.sub read_cstruct 0 n)
+              | exception End_of_file -> ""
+            in
+            let data =
+              if String.length !pending_data > 0 then begin
+                let combined = !pending_data ^ socket_data in
+                pending_data := "";
+                combined
+              end
+              else socket_data
+            in
+            let len = String.length data in
+            if len = 0 then begin
+              let (_ : int) =
+                H1.Server_connection.read_eof conn read_buffer ~off:0 ~len:0
+              in
+              shutdown := true
+            end
+            else begin
+              Bigstringaf.blit_from_string data ~src_off:0 read_buffer
+                ~dst_off:0 ~len;
+              let (_ : int) =
+                H1.Server_connection.read conn read_buffer ~off:0 ~len
+              in
+              read_loop ()
+            end
+        | `Yield -> H1.Server_connection.yield_reader conn read_loop
+        | `Close -> shutdown := true
+        | `Upgrade -> shutdown := true
+    in
+
+    let rec write_loop () =
+      if not !shutdown then
+        match H1.Server_connection.next_write_operation conn with
+        | `Write iovecs ->
+            let write_result = writev flow iovecs in
+            H1.Server_connection.report_write_result conn write_result;
+            write_loop ()
+        | `Yield -> H1.Server_connection.yield_writer conn write_loop
+        | `Close _ ->
+            shutdown := true;
+            shutdown_flow flow `Send
+        | `Upgrade -> shutdown := true
+    in
+
+    Fiber.both read_loop write_loop;
+
+    (* Handle WebSocket upgrade if requested *)
+    match !ws_upgrade with
+    | Some _key -> (
+        match ws_handler with
+        | Some ws_h ->
+            let ws =
+              {
+                Websocket.flow :> Eio.Flow.two_way_ty Eio.Std.r;
+                closed = false;
+                is_client = false;
+                read_buf = Buffer.create 4096;
+              }
+            in
+            (try ws_h ws with _ -> ());
+            if Websocket.is_open ws then Websocket.close ws
+        | None -> ())
+    | None -> ()
+
+  (** Direct H1 handler - no protocol detection, no initial data buffering *)
+  let handle_direct ~handler flow =
+    let buffer_size = 16384 in
+    let read_buffer = Bigstringaf.create buffer_size in
+    let read_cstruct =
+      Cstruct.of_bigarray read_buffer ~off:0 ~len:buffer_size
+    in
+
+    let request_handler reqd =
+      let req = H1.Reqd.request reqd in
+      let h1_body = H1.Reqd.request_body reqd in
+
+      (* Read body for POST/PUT, skip for GET/HEAD *)
+      let body =
+        match req.meth with
+        | `GET | `HEAD | `DELETE | `OPTIONS | `CONNECT | `TRACE ->
+            H1.Body.Reader.close h1_body;
+            ""
+        | `POST | `PUT | `Other _ ->
+            let body_buffer = Buffer.create 4096 in
+            let body_done, resolver = Eio.Promise.create () in
+            let rec read_body () =
+              H1.Body.Reader.schedule_read h1_body
+                ~on_eof:(fun () -> Eio.Promise.resolve resolver ())
+                ~on_read:(fun buf ~off ~len ->
+                  Buffer.add_string body_buffer
+                    (Bigstringaf.substring buf ~off ~len);
+                  read_body ())
+            in
+            read_body ();
+            Eio.Promise.await body_done;
+            Buffer.contents body_buffer
+      in
+
+      let request =
+        {
+          meth = req.meth;
+          target = req.target;
+          headers = h1_headers_to_list req.headers;
+          body;
+          version = HTTP_1_1;
+        }
+      in
+      let response = handler request in
+
+      (* Send response *)
+      let date_header = ("date", Date_cache.get ()) in
+      match response.body with
+      | Body_prebuilt prebuilt -> Prebuilt.respond_h1 reqd prebuilt
+      | Body_empty ->
+          let headers =
+            H1.Headers.of_list
+              (date_header :: ("content-length", "0") :: response.headers)
+          in
+          let resp = H1.Response.create ~headers response.status in
+          H1.Reqd.respond_with_string reqd resp ""
+      | Body_string body ->
+          let headers =
+            H1.Headers.of_list
+              (date_header
+              :: ("content-length", string_of_int (String.length body))
+              :: response.headers)
+          in
+          let resp = H1.Response.create ~headers response.status in
+          H1.Reqd.respond_with_string reqd resp body
+      | Body_bigstring body ->
+          let headers =
+            H1.Headers.of_list
+              (date_header
+              :: ("content-length", string_of_int (Bigstringaf.length body))
+              :: response.headers)
+          in
+          let resp = H1.Response.create ~headers response.status in
+          H1.Reqd.respond_with_bigstring reqd resp body
+      | Body_stream { content_length; next } ->
+          let headers =
+            match content_length with
+            | Some len ->
+                H1.Headers.of_list
+                  (date_header
+                  :: ("content-length", Int64.to_string len)
+                  :: response.headers)
+            | None ->
+                H1.Headers.of_list
+                  (date_header
+                  :: ("transfer-encoding", "chunked")
+                  :: response.headers)
+          in
+          let resp = H1.Response.create ~headers response.status in
+          let body_writer = H1.Reqd.respond_with_streaming reqd resp in
+          let rec write_chunks () =
+            match next () with
+            | None -> H1.Body.Writer.close body_writer
+            | Some cs ->
+                H1.Body.Writer.write_bigstring body_writer ~off:0
+                  ~len:(Cstruct.length cs) (Cstruct.to_bigarray cs);
+                write_chunks ()
+          in
+          write_chunks ()
+    in
+
+    let error_handler ?request:_ _error start_response =
+      let resp_body = start_response H1.Headers.empty in
+      H1.Body.Writer.write_string resp_body "Internal Server Error";
+      H1.Body.Writer.close resp_body
+    in
+
+    let conn = H1.Server_connection.create ~error_handler request_handler in
+    let shutdown = ref false in
+
+    let rec read_loop () =
+      if not !shutdown then
+        match H1.Server_connection.next_read_operation conn with
+        | `Read -> (
+            match Eio.Flow.single_read flow read_cstruct with
+            | n ->
+                let (_ : int) =
+                  H1.Server_connection.read conn read_buffer ~off:0 ~len:n
+                in
+                read_loop ()
+            | exception End_of_file ->
+                let (_ : int) =
+                  H1.Server_connection.read_eof conn read_buffer ~off:0 ~len:0
+                in
+                shutdown := true)
+        | `Yield -> H1.Server_connection.yield_reader conn read_loop
+        | `Close | `Upgrade -> shutdown := true
+    in
+
+    let rec write_loop () =
+      if not !shutdown then
+        match H1.Server_connection.next_write_operation conn with
+        | `Write iovecs ->
+            let write_result = writev flow iovecs in
+            H1.Server_connection.report_write_result conn write_result;
+            write_loop ()
+        | `Yield -> H1.Server_connection.yield_writer conn write_loop
+        | `Close _ ->
+            shutdown := true;
+            shutdown_flow flow `Send
+        | `Upgrade -> shutdown := true
+    in
+
+    Fiber.both read_loop write_loop
+end
+
+(** {1 Internal: HTTP/2 Connection Handler} *)
+
+module H2_handler = struct
+  let handle ~handler ~initial_data flow =
+    let read_buffer_size = 0x4000 in
+    let read_buffer = Bigstringaf.create read_buffer_size in
+    let pending_data = ref initial_data in
+
+    let request_handler reqd =
+      let req = H2.Reqd.request reqd in
+      let body_reader = H2.Reqd.request_body reqd in
+
+      let body =
+        match req.meth with
+        | `GET | `HEAD ->
+            H2.Body.Reader.close body_reader;
+            ""
+        | _ ->
+            let body_buffer = Buffer.create 4096 in
+            let body_done, resolver = Eio.Promise.create () in
+            let rec read_body () =
+              H2.Body.Reader.schedule_read body_reader
+                ~on_eof:(fun () -> Eio.Promise.resolve resolver ())
+                ~on_read:(fun buf ~off ~len ->
+                  Buffer.add_string body_buffer
+                    (Bigstringaf.substring buf ~off ~len);
+                  read_body ())
+            in
+            read_body ();
+            Eio.Promise.await body_done;
+            Buffer.contents body_buffer
+      in
+
+      let target =
+        match H2.Headers.get req.headers ":path" with
+        | Some p -> p
+        | None -> "/"
+      in
+
+      let request =
+        {
+          meth = req.meth;
+          target;
+          headers = h2_headers_to_list req.headers;
+          body;
+          version = HTTP_2;
+        }
+      in
+      let response = handler request in
+
+      (* Convert H1.Status to H2.Status - they're compatible *)
+      let h2_status = (response.status :> H2.Status.t) in
+
+      match response.body with
+      | Body_prebuilt prebuilt -> Prebuilt.respond_h2 reqd prebuilt
+      | Body_empty ->
+          let headers =
+            H2.Headers.of_list (("content-length", "0") :: response.headers)
+          in
+          let resp = H2.Response.create ~headers h2_status in
+          H2.Reqd.respond_with_string reqd resp ""
+      | Body_string body ->
+          let headers =
+            H2.Headers.of_list
+              (("content-length", string_of_int (String.length body))
+              :: response.headers)
+          in
+          let resp = H2.Response.create ~headers h2_status in
+          H2.Reqd.respond_with_string reqd resp body
+      | Body_bigstring body ->
+          let headers =
+            H2.Headers.of_list
+              (("content-length", string_of_int (Bigstringaf.length body))
+              :: response.headers)
+          in
+          let resp = H2.Response.create ~headers h2_status in
+          H2.Reqd.respond_with_bigstring reqd resp body
+      | Body_stream { content_length; next } ->
+          let headers =
+            match content_length with
+            | Some len ->
+                H2.Headers.of_list
+                  (("content-length", Int64.to_string len) :: response.headers)
+            | None -> H2.Headers.of_list response.headers
+          in
+          let resp = H2.Response.create ~headers h2_status in
+          let body_writer = H2.Reqd.respond_with_streaming reqd resp in
+          let rec write_chunks () =
+            match next () with
+            | None -> H2.Body.Writer.close body_writer
+            | Some cs ->
+                H2.Body.Writer.write_bigstring body_writer ~off:0
+                  ~len:(Cstruct.length cs) (Cstruct.to_bigarray cs);
+                write_chunks ()
+          in
+          write_chunks ()
+    in
+
+    let error_handler ?request:_ _error start_response =
+      let resp_body = start_response H2.Headers.empty in
+      H2.Body.Writer.write_string resp_body "Internal Server Error";
+      H2.Body.Writer.close resp_body
+    in
+
+    let conn = H2.Server_connection.create ~error_handler request_handler in
+    let shutdown = ref false in
+
+    let read_loop () =
+      let rec loop () =
+        if not !shutdown then
+          match H2.Server_connection.next_read_operation conn with
+          | `Read ->
+              let cs =
+                Cstruct.of_bigarray read_buffer ~off:0 ~len:read_buffer_size
+              in
+              let socket_data =
+                try
+                  let n = Eio.Flow.single_read flow cs in
+                  Cstruct.to_string (Cstruct.sub cs 0 n)
+                with End_of_file -> ""
+              in
+              let data =
+                if String.length !pending_data > 0 then begin
+                  let combined = !pending_data ^ socket_data in
+                  pending_data := "";
+                  combined
+                end
+                else socket_data
+              in
+              let len = String.length data in
+              if len = 0 then begin
+                let _ =
+                  H2.Server_connection.read_eof conn read_buffer ~off:0 ~len:0
+                in
+                shutdown := true
+              end
+              else begin
+                Bigstringaf.blit_from_string data ~src_off:0 read_buffer
+                  ~dst_off:0 ~len;
+                let _ =
+                  H2.Server_connection.read conn read_buffer ~off:0 ~len
+                in
+                loop ()
+              end
+          | `Close -> shutdown := true
+      in
+      loop ()
+    in
+
+    let write_loop () =
+      let rec loop () =
+        if not !shutdown then
+          match H2.Server_connection.next_write_operation conn with
+          | `Write iovecs ->
+              let cstructs =
+                List.map
+                  (fun iov ->
+                    Cstruct.of_bigarray ~off:iov.H2.IOVec.off
+                      ~len:iov.H2.IOVec.len iov.H2.IOVec.buffer)
+                  iovecs
+              in
+              Eio.Flow.write flow cstructs;
+              let len =
+                List.fold_left (fun acc iov -> acc + iov.H2.IOVec.len) 0 iovecs
+              in
+              H2.Server_connection.report_write_result conn (`Ok len);
+              loop ()
+          | `Yield ->
+              let continue = Eio.Promise.create () in
+              H2.Server_connection.yield_writer conn (fun () ->
+                  Eio.Promise.resolve (snd continue) ());
+              Eio.Promise.await (fst continue);
+              loop ()
+          | `Close _ -> shutdown := true
+      in
+      loop ()
+    in
+
+    Fiber.both read_loop write_loop
+
+  (** Direct H2 handler - no protocol detection *)
+  let handle_direct ~handler flow = handle ~handler ~initial_data:"" flow
+end
+
+(** {1 Internal: TLS Connection Handler} *)
+
+module Tls_handler = struct
+  let handle ~config ~handler ~ws_handler tls_cfg flow =
+    try
+      let tls_flow = Tls_eio.server_of_flow tls_cfg flow in
+      match config.protocol with
+      | Http1_only ->
+          (* No ALPN check, direct H1 *)
+          H1_handler.handle_direct ~handler tls_flow
+      | Http2_only ->
+          (* No ALPN check, direct H2 *)
+          H2_handler.handle_direct ~handler tls_flow
+      | Auto | Auto_websocket -> (
+          (* Check ALPN negotiated protocol *)
+          match Tls_config.negotiated_protocol tls_flow with
+          | Some Tls_config.HTTP_2 -> H2_handler.handle_direct ~handler tls_flow
+          | Some Tls_config.HTTP_1_1 | None ->
+              if config.protocol = Auto_websocket then
+                H1_handler.handle ~handler ~ws_handler:(Some ws_handler)
+                  ~initial_data:"" tls_flow
+              else H1_handler.handle_direct ~handler tls_flow)
+    with
+    | Tls_eio.Tls_failure failure ->
+        traceln "TLS error: %s" (Tls_config.failure_to_string failure)
+    | exn -> traceln "Connection error: %s" (Printexc.to_string exn)
+end
+
+(** {1 Internal: Connection Handler} *)
+
+let handle_connection ~config ~handler ~ws_handler flow =
+  match config.protocol with
+  | Http1_only ->
+      (* Fastest path: direct H1, no detection *)
+      H1_handler.handle_direct ~handler flow
+  | Http2_only ->
+      (* Direct H2 (h2c) *)
+      H2_handler.handle_direct ~handler flow
+  | Auto | Auto_websocket -> (
+      (* Peek to detect protocol *)
+      match peek_bytes flow h2_preface_prefix_len with
+      | Error `Eof -> () (* Client disconnected immediately *)
+      | Error (`Exn exn) ->
+          traceln "Connection error: %s" (Printexc.to_string exn)
+      | Ok initial_data ->
+          if is_h2_preface initial_data then
+            H2_handler.handle ~handler ~initial_data flow
+          else if config.protocol = Auto_websocket then
+            H1_handler.handle ~handler ~ws_handler:(Some ws_handler)
+              ~initial_data flow
+          else H1_handler.handle ~handler ~ws_handler:None ~initial_data flow)
+
+(** {1 Public API} *)
+
+(** Run an HTTP server.
+
+    @param sw Switch for resource management
+    @param net Eio network capability
+    @param config Server configuration (default: [default_config])
+    @param ws_handler WebSocket handler (required for [Auto_websocket] mode)
+    @param handler Request handler *)
+let run ~sw ~net ?(config = default_config) ?ws_handler handler =
+  (* Apply GC tuning if configured *)
+  (match config.gc_tuning with
+  | Some gc_config -> Gc_tune.apply ~config:gc_config ()
+  | None -> ());
+
+  let addr = `Tcp (Eio.Net.Ipaddr.V4.any, config.port) in
+  let socket =
+    Eio.Net.listen ~sw ~backlog:config.backlog ~reuse_addr:config.reuse_addr
+      ~reuse_port:config.reuse_port net addr
+  in
+
+  let protocol_str =
+    match (config.protocol, config.tls) with
+    | Http1_only, None -> "HTTP/1.1"
+    | Http1_only, Some _ -> "HTTP/1.1 (TLS)"
+    | Http2_only, None -> "HTTP/2 h2c"
+    | Http2_only, Some _ -> "HTTP/2 (TLS)"
+    | Auto, None -> "HTTP/1.1 + HTTP/2 h2c"
+    | Auto, Some _ -> "HTTP/1.1 + HTTP/2 (TLS, ALPN)"
+    | Auto_websocket, None -> "HTTP/1.1 + HTTP/2 h2c + WebSocket"
+    | Auto_websocket, Some _ -> "HTTP/1.1 + HTTP/2 + WebSocket (TLS, ALPN)"
+  in
+  traceln "Server listening on port %d (%s)" config.port protocol_str;
+
+  (* Validate ws_handler for Auto_websocket mode *)
+  let ws_handler =
+    match (config.protocol, ws_handler) with
+    | Auto_websocket, None ->
+        failwith "WebSocket handler required for Auto_websocket mode"
+    | Auto_websocket, Some h -> h
+    | _, _ -> fun _ -> () (* Dummy handler for non-WS modes *)
+  in
+
+  let connection_handler flow _addr =
+    if config.tcp_nodelay then set_tcp_nodelay flow;
+    match config.tls with
+    | None -> handle_connection ~config ~handler ~ws_handler flow
+    | Some tls_config -> (
+        match Tls_config.Server.to_tls_config tls_config with
+        | Error (`Msg msg) -> traceln "TLS config error: %s" msg
+        | Ok tls_cfg ->
+            Tls_handler.handle ~config ~handler ~ws_handler tls_cfg flow)
+  in
+
+  let on_error exn = traceln "Connection error: %s" (Printexc.to_string exn) in
+
+  Eio.Net.run_server socket connection_handler
+    ~max_connections:config.max_connections ~on_error
+
+(** Run an HTTP server with multi-domain parallelism.
+
+    @param sw Switch for resource management
+    @param net Eio network capability
+    @param domain_mgr Eio domain manager
+    @param config Server configuration (default: [default_config])
+    @param ws_handler WebSocket handler (required for [Auto_websocket] mode)
+    @param handler Request handler *)
+let run_parallel ~sw ~net ~domain_mgr ?(config = default_config) ?ws_handler
+    handler =
+  (* Apply GC tuning if configured *)
+  (match config.gc_tuning with
+  | Some gc_config -> Gc_tune.apply ~config:gc_config ()
+  | None -> ());
+
+  let domain_count = max 1 config.domain_count in
+  let addr = `Tcp (Eio.Net.Ipaddr.V4.any, config.port) in
+  let socket =
+    Eio.Net.listen ~sw ~backlog:config.backlog ~reuse_addr:config.reuse_addr
+      ~reuse_port:config.reuse_port net addr
+  in
+
+  let protocol_str =
+    match (config.protocol, config.tls) with
+    | Http1_only, None -> "HTTP/1.1"
+    | Http1_only, Some _ -> "HTTP/1.1 (TLS)"
+    | Http2_only, None -> "HTTP/2 h2c"
+    | Http2_only, Some _ -> "HTTP/2 (TLS)"
+    | Auto, None -> "HTTP/1.1 + HTTP/2 h2c"
+    | Auto, Some _ -> "HTTP/1.1 + HTTP/2 (TLS, ALPN)"
+    | Auto_websocket, None -> "HTTP/1.1 + HTTP/2 h2c + WebSocket"
+    | Auto_websocket, Some _ -> "HTTP/1.1 + HTTP/2 + WebSocket (TLS, ALPN)"
+  in
+  traceln "Server listening on port %d (%s, %d domains)" config.port
+    protocol_str domain_count;
+
+  (* Validate ws_handler for Auto_websocket mode *)
+  let ws_handler =
+    match (config.protocol, ws_handler) with
+    | Auto_websocket, None ->
+        failwith "WebSocket handler required for Auto_websocket mode"
+    | Auto_websocket, Some h -> h
+    | _, _ -> fun _ -> ()
+  in
+
+  let connection_handler flow _addr =
+    if config.tcp_nodelay then set_tcp_nodelay flow;
+    match config.tls with
+    | None -> handle_connection ~config ~handler ~ws_handler flow
+    | Some tls_config -> (
+        match Tls_config.Server.to_tls_config tls_config with
+        | Error (`Msg msg) -> traceln "TLS config error: %s" msg
+        | Ok tls_cfg ->
+            Tls_handler.handle ~config ~handler ~ws_handler tls_cfg flow)
+  in
+
+  let on_error exn = traceln "Connection error: %s" (Printexc.to_string exn) in
+
+  if domain_count <= 1 then
+    Eio.Net.run_server socket connection_handler
+      ~max_connections:config.max_connections ~on_error
+  else
+    Eio.Net.run_server socket connection_handler
+      ~max_connections:config.max_connections ~on_error
+      ~additional_domains:(domain_mgr, domain_count - 1)

lib/stream.ml

···
+(** Streaming abstractions for HCS HTTP library.
+
+    This module provides both synchronous and asynchronous stream types for
+    handling large payloads efficiently with backpressure support.
+
+    {1 Synchronous Streams}
+
+    For simple, pull-based iteration without runtime dependencies.
+
+    {1 Asynchronous Streams (Eio)}
+
+    For streaming with Eio's structured concurrency, supporting flows, files,
+    and chunked transfer encoding. *)
+
+(** {1 Synchronous Stream}
+
+    A simple pull-based stream using OCaml's Seq. *)
+module Sync = struct
+  type 'a t = 'a Seq.t
+  (** A synchronous stream of values *)
+
+  (** {2 Producers} *)
+
+  let empty : 'a t = Seq.empty
+  let singleton x : 'a t = Seq.return x
+  let of_list l : 'a t = List.to_seq l
+  let of_array a : 'a t = Array.to_seq a
+
+  (** Create a stream from an unfolding function *)
+  let unfold (f : 's -> ('a * 's) option) (init : 's) : 'a t = Seq.unfold f init
+
+  (** Create a stream that repeats a value n times *)
+  let repeat n x : 'a t =
+    unfold (fun i -> if i > 0 then Some (x, i - 1) else None) n
+
+  (** Create a stream from a generator function *)
+  let generate (f : unit -> 'a option) : 'a t =
+    let rec next () =
+      match f () with Some x -> Seq.Cons (x, next) | None -> Seq.Nil
+    in
+    next
+
+  (** {2 Transformers} *)
+
+  let map f s : 'a t = Seq.map f s
+  let filter p s : 'a t = Seq.filter p s
+  let filter_map f s : 'a t = Seq.filter_map f s
+
+  (** Take the first n elements *)
+  let take n s : 'a t = Seq.take n s
+
+  (** Drop the first n elements *)
+  let drop n s : 'a t = Seq.drop n s
+
+  (** Split stream into chunks of size n *)
+  let chunks n s : 'a list t =
+    let rec next acc count seq () =
+      if count >= n then Seq.Cons (List.rev acc, next [] 0 seq)
+      else
+        match seq () with
+        | Seq.Nil ->
+            if acc = [] then Seq.Nil
+            else Seq.Cons (List.rev acc, fun () -> Seq.Nil)
+        | Seq.Cons (x, rest) -> next (x :: acc) (count + 1) rest ()
+    in
+    next [] 0 s
+
+  (** Flatten a stream of streams *)
+  let flatten s : 'a t = Seq.flat_map Fun.id s
+
+  (** Append two streams *)
+  let append s1 s2 : 'a t = Seq.append s1 s2
+
+  (** {2 Consumers} *)
+
+  (** Fold over the stream *)
+  let fold f init s = Seq.fold_left f init s
+
+  (** Iterate over the stream for side effects *)
+  let iter f s = Seq.iter f s
+
+  (** Drain the stream, discarding all values *)
+  let drain s = iter (fun _ -> ()) s
+
+  (** Collect stream into a list *)
+  let to_list s = List.of_seq s
+
+  (** Collect stream into an array *)
+  let to_array s = Array.of_seq s
+
+  (** {2 Cstruct-specific operations} *)
+
+  (** Concatenate a stream of Cstructs into a single string *)
+  let cstructs_to_string (s : Cstruct.t t) : string =
+    let bufs = to_list s in
+    let total = List.fold_left (fun acc cs -> acc + Cstruct.length cs) 0 bufs in
+    let result = Bytes.create total in
+    let _ =
+      List.fold_left
+        (fun off cs ->
+          let len = Cstruct.length cs in
+          Cstruct.blit_to_bytes cs 0 result off len;
+          off + len)
+        0 bufs
+    in
+    Bytes.to_string result
+
+  (** Split a string into chunks of Cstructs *)
+  let string_to_cstructs ?(chunk_size = 4096) (s : string) : Cstruct.t t =
+    let len = String.length s in
+    unfold
+      (fun off ->
+        if off >= len then None
+        else
+          let chunk_len = min chunk_size (len - off) in
+          Some (Cstruct.of_string ~off ~len:chunk_len s, off + chunk_len))
+      0
+end
+
+(** {1 Asynchronous Stream (Eio)}
+
+    Streams that integrate with Eio's structured concurrency. *)
+module Async = struct
+  type 'a t = unit -> 'a option
+  (** An asynchronous stream that can be pulled from *)
+
+  (** {2 Producers} *)
+
+  let empty : 'a t = fun () -> None
+
+  let singleton x : 'a t =
+    let taken = ref false in
+    fun () ->
+      if !taken then None
+      else begin
+        taken := true;
+        Some x
+      end
+
+  let of_list l : 'a t =
+    let r = ref l in
+    fun () ->
+      match !r with
+      | [] -> None
+      | x :: rest ->
+          r := rest;
+          Some x
+
+  let of_seq s : 'a t =
+    let r = ref s in
+    fun () ->
+      match !r () with
+      | Seq.Nil -> None
+      | Seq.Cons (x, rest) ->
+          r := rest;
+          Some x
+
+  (** Create a stream from an Eio flow (reads until EOF) *)
+  let of_flow ?(buf_size = 4096) (flow : _ Eio.Flow.source) : Cstruct.t t =
+    let buf = Cstruct.create buf_size in
+    let finished = ref false in
+    fun () ->
+      if !finished then None
+      else
+        try
+          let n = Eio.Flow.single_read flow buf in
+          Some (Cstruct.sub buf 0 n)
+        with End_of_file ->
+          finished := true;
+          None
+
+  (** Create a stream that reads a file in chunks *)
+  let of_file ?(buf_size = 4096) ~fs path : Cstruct.t t =
+    let file = Eio.Path.open_in ~sw:(Eio.Switch.run Fun.id) (fs, path) in
+    of_flow ~buf_size file
+
+  (** {2 Transformers} *)
+
+  let map f (s : 'a t) : 'b t = fun () -> Option.map f (s ())
+
+  let filter p (s : 'a t) : 'a t =
+    let rec next () =
+      match s () with None -> None | Some x -> if p x then Some x else next ()
+    in
+    next
+
+  let filter_map f (s : 'a t) : 'b t =
+    let rec next () =
+      match s () with
+      | None -> None
+      | Some x -> ( match f x with Some y -> Some y | None -> next ())
+    in
+    next
+
+  let take n (s : 'a t) : 'a t =
+    let count = ref 0 in
+    fun () ->
+      if !count >= n then None
+      else begin
+        incr count;
+        s ()
+      end
+
+  (** {2 Consumers} *)
+
+  (** Fold over the stream *)
+  let fold f init (s : 'a t) =
+    let rec loop acc =
+      match s () with None -> acc | Some x -> loop (f acc x)
+    in
+    loop init
+
+  (** Iterate over the stream *)
+  let iter f (s : 'a t) =
+    let rec loop () =
+      match s () with
+      | None -> ()
+      | Some x ->
+          f x;
+          loop ()
+    in
+    loop ()
+
+  (** Drain the stream *)
+  let drain s = iter (fun _ -> ()) s
+
+  (** Collect into a list *)
+  let to_list (s : 'a t) = List.rev (fold (fun acc x -> x :: acc) [] s)
+
+  (** Write stream to an Eio flow *)
+  let to_flow (flow : _ Eio.Flow.sink) (s : Cstruct.t t) =
+    iter (fun cs -> Eio.Flow.write flow [ cs ]) s
+
+  (** {2 Cstruct-specific operations} *)
+
+  (** Concatenate a stream of Cstructs into a single string *)
+  let cstructs_to_string (s : Cstruct.t t) : string =
+    let bufs = to_list s in
+    let total = List.fold_left (fun acc cs -> acc + Cstruct.length cs) 0 bufs in
+    let result = Bytes.create total in
+    let _ =
+      List.fold_left
+        (fun off cs ->
+          let len = Cstruct.length cs in
+          Cstruct.blit_to_bytes cs 0 result off len;
+          off + len)
+        0 bufs
+    in
+    Bytes.to_string result
+
+  (** Read entire stream into a Cstruct *)
+  let cstructs_to_cstruct (s : Cstruct.t t) : Cstruct.t =
+    let bufs = to_list s in
+    let total = List.fold_left (fun acc cs -> acc + Cstruct.length cs) 0 bufs in
+    let result = Cstruct.create total in
+    let _ =
+      List.fold_left
+        (fun off cs ->
+          let len = Cstruct.length cs in
+          Cstruct.blit cs 0 result off len;
+          off + len)
+        0 bufs
+    in
+    result
+end
+
+(** {1 Chunked Transfer Encoding} *)
+
+(** Helpers for HTTP chunked transfer encoding *)
+module Chunked = struct
+  (** Encode chunks for chunked transfer encoding *)
+  let encode (chunks : Cstruct.t Sync.t) : Cstruct.t Sync.t =
+    let encode_chunk cs =
+      let len = Cstruct.length cs in
+      if len = 0 then Cstruct.of_string "0\r\n\r\n"
+      else
+        let header = Printf.sprintf "%x\r\n" len in
+        let trailer = "\r\n" in
+        let total = String.length header + len + String.length trailer in
+        let buf = Cstruct.create total in
+        Cstruct.blit_from_string header 0 buf 0 (String.length header);
+        Cstruct.blit cs 0 buf (String.length header) len;
+        Cstruct.blit_from_string trailer 0 buf
+          (String.length header + len)
+          (String.length trailer);
+        buf
+    in
+    Seq.append
+      (Seq.map encode_chunk chunks)
+      (Seq.return (Cstruct.of_string "0\r\n\r\n"))
+
+  (** Calculate content length from chunks (consumes the stream) *)
+  let content_length (chunks : Cstruct.t Sync.t) : int =
+    Sync.fold (fun acc cs -> acc + Cstruct.length cs) 0 chunks
+end

lib/tls_config.ml

···
+(** TLS configuration and helpers for HCS.
+
+    This module provides TLS configuration that works with tls-eio and ca-certs
+    for system certificate loading. *)
+
+(** {1 ALPN Protocol Identifiers} *)
+
+(** HTTP/2 over TLS ALPN identifier *)
+let alpn_h2 = "h2"
+
+(** HTTP/1.1 ALPN identifier *)
+let alpn_http11 = "http/1.1"
+
+(** HTTP/2 cleartext (h2c) identifier - used in Upgrade header, not ALPN *)
+let alpn_h2c = "h2c"
+
+(** Protocol type for negotiation results *)
+type protocol = HTTP_1_1 | HTTP_2
+
+(** Convert ALPN string to protocol type *)
+let protocol_of_alpn = function
+  | s when s = alpn_h2 -> Some HTTP_2
+  | s when s = alpn_http11 -> Some HTTP_1_1
+  | _ -> None
+
+(** Convert protocol to ALPN string *)
+let alpn_of_protocol = function HTTP_2 -> alpn_h2 | HTTP_1_1 -> alpn_http11
+
+(** Client TLS configuration *)
+module Client = struct
+  (** Certificate verification mode *)
+  type verification =
+    | System_certs  (** Use system CA certificates *)
+    | No_verify  (** Disable verification (INSECURE!) *)
+
+  type t = {
+    verification : verification;
+    alpn_protocols : string list option;  (** ALPN: ["h2"; "http/1.1"] *)
+  }
+
+  let default =
+    { verification = System_certs; alpn_protocols = Some [ "http/1.1" ] }
+
+  (** TLS config for HTTP/2 - advertises h2 protocol *)
+  let h2 = { verification = System_certs; alpn_protocols = Some [ "h2" ] }
+
+  (** TLS config that prefers HTTP/2 but falls back to HTTP/1.1 *)
+  let h2_or_http11 =
+    { verification = System_certs; alpn_protocols = Some [ "h2"; "http/1.1" ] }
+
+  let with_alpn protocols config =
+    { config with alpn_protocols = Some protocols }
+
+  let insecure =
+    { verification = No_verify; alpn_protocols = Some [ "http/1.1" ] }
+
+  let insecure_h2 = { verification = No_verify; alpn_protocols = Some [ "h2" ] }
+
+  (** Create tls-eio authenticator from config *)
+  let make_authenticator config =
+    match config.verification with
+    | System_certs -> (
+        match Ca_certs.authenticator () with
+        | Ok auth -> Ok auth
+        | Error (`Msg msg) -> Error msg)
+    | No_verify -> Ok (fun ?ip:_ ~host:_ _ -> Ok None)
+
+  (** Create Tls.Config.client from our config *)
+  let to_tls_config config ~host:_ =
+    match make_authenticator config with
+    | Error msg -> Error msg
+    | Ok authenticator -> (
+        match
+          Tls.Config.client ~authenticator ?alpn_protocols:config.alpn_protocols
+            ()
+        with
+        | Ok tls_config -> Ok tls_config
+        | Error (`Msg msg) -> Error msg)
+end
+
+module Server = struct
+  type t = {
+    certificate : Tls.Config.own_cert;
+    alpn_protocols : string list option;
+  }
+
+  let with_alpn protocols config =
+    { config with alpn_protocols = Some protocols }
+
+  let h1_only config = with_alpn [ alpn_http11 ] config
+  let h2_only config = with_alpn [ alpn_h2 ] config
+  let h2_or_http11 config = with_alpn [ alpn_h2; alpn_http11 ] config
+
+  let of_pem ~cert_file ~key_file =
+    try
+      let cert_pem = In_channel.with_open_bin cert_file In_channel.input_all in
+      let key_pem = In_channel.with_open_bin key_file In_channel.input_all in
+      let certs = X509.Certificate.decode_pem_multiple cert_pem in
+      let key = X509.Private_key.decode_pem key_pem in
+      match (certs, key) with
+      | Ok certs, Ok key ->
+          Ok
+            {
+              certificate = `Single (certs, key);
+              alpn_protocols = Some [ alpn_h2; alpn_http11 ];
+            }
+      | Error (`Msg msg), _ -> Error ("Certificate error: " ^ msg)
+      | _, Error (`Msg msg) -> Error ("Key error: " ^ msg)
+    with Sys_error msg -> Error ("File error: " ^ msg)
+
+  (** Create Tls.Config.server from our config *)
+  let to_tls_config config =
+    Tls.Config.server ~certificates:config.certificate
+      ?alpn_protocols:config.alpn_protocols ()
+end
+
+(** Convert TLS failure to string *)
+let failure_to_string failure = Tls.Engine.string_of_failure failure
+
+(** Wrap an Eio flow with TLS (client side) *)
+let client_wrap ~config flow =
+  match Client.to_tls_config config ~host:"" with
+  | Error msg -> Error msg
+  | Ok tls_config -> (
+      try
+        let tls_flow = Tls_eio.client_of_flow tls_config flow in
+        Ok tls_flow
+      with
+      | Tls_eio.Tls_failure failure -> Error (failure_to_string failure)
+      | exn -> Error (Printexc.to_string exn))
+
+(** Wrap an Eio flow with TLS (server side) *)
+let server_wrap config flow =
+  match Server.to_tls_config config with
+  | Error (`Msg msg) -> Error msg
+  | Ok tls_config -> (
+      try
+        let tls_flow = Tls_eio.server_of_flow tls_config flow in
+        Ok tls_flow
+      with
+      | Tls_eio.Tls_failure failure -> Error (failure_to_string failure)
+      | exn -> Error (Printexc.to_string exn))
+
+let negotiated_protocol (tls_flow : Tls_eio.t) : protocol option =
+  match Tls_eio.epoch tls_flow with
+  | Error () -> None
+  | Ok epoch_data -> (
+      match epoch_data.Tls.Core.alpn_protocol with
+      | None -> None
+      | Some alpn -> protocol_of_alpn alpn)

lib/websocket.ml

···
+(** WebSocket implementation for HCS (RFC 6455).
+
+    This module provides WebSocket client and server functionality with Eio for
+    structured concurrency. *)
+
+open Eio.Std
+
+(** {1 Constants} *)
+
+(** UUID used in WebSocket handshake per RFC 6455 *)
+let websocket_uuid = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
+
+(** {1 Types} *)
+
+(** WebSocket frame opcode *)
+module Opcode = struct
+  type t =
+    | Continuation  (** 0x0 *)
+    | Text  (** 0x1 *)
+    | Binary  (** 0x2 *)
+    | Close  (** 0x8 *)
+    | Ping  (** 0x9 *)
+    | Pong  (** 0xA *)
+    | Ctrl of int  (** Other control opcodes *)
+    | Nonctrl of int  (** Other non-control opcodes *)
+
+  let to_int = function
+    | Continuation -> 0
+    | Text -> 1
+    | Binary -> 2
+    | Close -> 8
+    | Ping -> 9
+    | Pong -> 10
+    | Ctrl n -> n
+    | Nonctrl n -> n
+
+  let of_int = function
+    | 0 -> Continuation
+    | 1 -> Text
+    | 2 -> Binary
+    | 8 -> Close
+    | 9 -> Ping
+    | 10 -> Pong
+    | n when n > 7 -> Ctrl n
+    | n -> Nonctrl n
+
+  let to_string = function
+    | Continuation -> "continuation"
+    | Text -> "text"
+    | Binary -> "binary"
+    | Close -> "close"
+    | Ping -> "ping"
+    | Pong -> "pong"
+    | Ctrl n -> Printf.sprintf "ctrl(%d)" n
+    | Nonctrl n -> Printf.sprintf "nonctrl(%d)" n
+
+  let is_control = function Close | Ping | Pong | Ctrl _ -> true | _ -> false
+end
+
+type frame = {
+  opcode : Opcode.t;
+  extension : int;
+  final : bool;
+  content : string;
+}
+(** WebSocket frame *)
+
+let pp_frame fmt frame =
+  Format.fprintf fmt "{opcode=%s; final=%b; len=%d}"
+    (Opcode.to_string frame.opcode)
+    frame.final
+    (String.length frame.content)
+
+let make_frame ?(opcode = Opcode.Text) ?(extension = 0) ?(final = true)
+    ?(content = "") () =
+  { opcode; extension; final; content }
+
+let close_frame code =
+  let content =
+    if code < 0 then ""
+    else
+      let buf = Bytes.create 2 in
+      Bytes.set buf 0 (Char.chr ((code lsr 8) land 0xff));
+      Bytes.set buf 1 (Char.chr (code land 0xff));
+      Bytes.to_string buf
+  in
+  { opcode = Close; extension = 0; final = true; content }
+
+type t = {
+  flow : Eio.Flow.two_way_ty r;
+  mutable closed : bool;
+  is_client : bool;  (** Client must mask frames *)
+  read_buf : Buffer.t;
+}
+(** WebSocket connection *)
+
+(** Error type *)
+type error = Connection_closed | Protocol_error of string | Io_error of string
+
+(** {1 Cryptographic helpers} *)
+
+(** Compute SHA-1 hash and base64 encode *)
+let b64_encoded_sha1sum s =
+  let hash = Digestif.SHA1.digest_string s in
+  Base64.encode_exn (Digestif.SHA1.to_raw_string hash)
+
+(** Compute the Sec-WebSocket-Accept value *)
+let compute_accept_key key = b64_encoded_sha1sum (key ^ websocket_uuid)
+
+(** {1 Random number generation for masking} *)
+
+module Rng = struct
+  let initialized = ref false
+
+  let init () =
+    if not !initialized then begin
+      Random.self_init ();
+      initialized := true
+    end
+
+  (** Generate n random bytes *)
+  let generate n =
+    init ();
+    let buf = Bytes.create n in
+    for i = 0 to n - 1 do
+      Bytes.set buf i (Char.chr (Random.int 256))
+    done;
+    Bytes.to_string buf
+end
+
+(** {1 Frame parsing/serialization} *)
+
+(** Apply XOR mask to data *)
+let xor_mask mask data =
+  let len = String.length data in
+  let result = Bytes.create len in
+  for i = 0 to len - 1 do
+    let mask_byte = Char.code mask.[i mod 4] in
+    let data_byte = Char.code data.[i] in
+    Bytes.set result i (Char.chr (data_byte lxor mask_byte))
+  done;
+  Bytes.to_string result
+
+(** Serialize a frame to bytes. Client frames must be masked, server frames must
+    not be masked. *)
+let write_frame_to_buf ~is_client buf frame =
+  let mask = is_client in
+  let opcode = Opcode.to_int frame.opcode in
+  let fin = if frame.final then 0x80 else 0 in
+  let rsv = (frame.extension land 0x7) lsl 4 in
+
+  Buffer.add_char buf (Char.chr (fin lor rsv lor opcode));
+
+  let len = String.length frame.content in
+  let mask_bit = if mask then 0x80 else 0 in
+
+  (* Encode payload length *)
+  if len < 126 then Buffer.add_char buf (Char.chr (mask_bit lor len))
+  else if len < 65536 then begin
+    Buffer.add_char buf (Char.chr (mask_bit lor 126));
+    Buffer.add_char buf (Char.chr ((len lsr 8) land 0xff));
+    Buffer.add_char buf (Char.chr (len land 0xff))
+  end
+  else begin
+    Buffer.add_char buf (Char.chr (mask_bit lor 127));
+    (* 64-bit length, big-endian *)
+    for i = 7 downto 0 do
+      Buffer.add_char buf (Char.chr ((len lsr (i * 8)) land 0xff))
+    done
+  end;
+
+  (* Add mask and payload *)
+  if mask then begin
+    let mask_key = Rng.generate 4 in
+    Buffer.add_string buf mask_key;
+    Buffer.add_string buf (xor_mask mask_key frame.content)
+  end
+  else Buffer.add_string buf frame.content
+
+(** Read exactly n bytes from flow *)
+let read_exactly flow n =
+  let buf = Cstruct.create n in
+  let rec loop off =
+    if off < n then begin
+      let cs = Cstruct.sub buf off (n - off) in
+      let read = Eio.Flow.single_read flow cs in
+      loop (off + read)
+    end
+  in
+  loop 0;
+  Cstruct.to_string buf
+
+(** Parse a frame from flow *)
+let read_frame ~is_client flow =
+  try
+    (* Read first 2 bytes *)
+    let header = read_exactly flow 2 in
+    let b0 = Char.code header.[0] in
+    let b1 = Char.code header.[1] in
+
+    let final = b0 land 0x80 <> 0 in
+    let extension = (b0 land 0x70) lsr 4 in
+    let opcode = Opcode.of_int (b0 land 0x0f) in
+    let masked = b1 land 0x80 <> 0 in
+    let len0 = b1 land 0x7f in
+
+    (* Server receiving from client: frames must be masked
+       Client receiving from server: frames must not be masked *)
+    if (not is_client) && not masked then
+      Error (Protocol_error "Client frames must be masked")
+    else if is_client && masked then
+      Error (Protocol_error "Server frames must not be masked")
+    else begin
+      (* Read extended length if needed *)
+      let len =
+        if len0 < 126 then len0
+        else if len0 = 126 then begin
+          let ext = read_exactly flow 2 in
+          (Char.code ext.[0] lsl 8) lor Char.code ext.[1]
+        end
+        else begin
+          (* 64-bit length *)
+          let ext = read_exactly flow 8 in
+          let len = ref 0 in
+          for i = 0 to 7 do
+            len := (!len lsl 8) lor Char.code ext.[i]
+          done;
+          !len
+        end
+      in
+
+      (* Control frames cannot be fragmented and max 125 bytes *)
+      if Opcode.is_control opcode && ((not final) || len > 125) then
+        Error (Protocol_error "Invalid control frame")
+      else begin
+        (* Read mask key if present *)
+        let mask_key = if masked then Some (read_exactly flow 4) else None in
+
+        (* Read payload *)
+        let content = if len > 0 then read_exactly flow len else "" in
+        let content =
+          match mask_key with
+          | Some key -> xor_mask key content
+          | None -> content
+        in
+
+        Ok { opcode; extension; final; content }
+      end
+    end
+  with
+  | End_of_file -> Error Connection_closed
+  | exn -> Error (Io_error (Printexc.to_string exn))
+
+(** {1 Connection API} *)
+
+(** Check if connection is open *)
+let is_open t = not t.closed
+
+(** Send a frame *)
+let send t frame =
+  if t.closed then Error Connection_closed
+  else
+    try
+      let buf = Buffer.create 128 in
+      write_frame_to_buf ~is_client:t.is_client buf frame;
+      Eio.Flow.write t.flow [ Cstruct.of_string (Buffer.contents buf) ];
+      Ok ()
+    with exn -> Error (Io_error (Printexc.to_string exn))
+
+(** Send a text message *)
+let send_text t content = send t (make_frame ~opcode:Text ~content ())
+
+(** Send a binary message *)
+let send_binary t content = send t (make_frame ~opcode:Binary ~content ())
+
+(** Send a ping *)
+let send_ping t ?(content = "") () =
+  send t (make_frame ~opcode:Ping ~content ())
+
+(** Send a pong *)
+let send_pong t ?(content = "") () =
+  send t (make_frame ~opcode:Pong ~content ())
+
+(** Receive a frame *)
+let recv t =
+  if t.closed then Error Connection_closed
+  else
+    match read_frame ~is_client:t.is_client t.flow with
+    | Ok frame ->
+        (* Handle control frames *)
+        (match frame.opcode with
+        | Close ->
+            t.closed <- true;
+            (* Echo close frame back *)
+            ignore (send t (close_frame (-1)))
+        | Ping ->
+            (* Auto-respond to pings with pong *)
+            ignore (send_pong t ~content:frame.content ())
+        | _ -> ());
+        Ok frame
+    | Error e ->
+        t.closed <- true;
+        Error e
+
+(** Receive a complete message (handles fragmentation) *)
+let recv_message t =
+  let rec collect_fragments first_opcode buf =
+    match recv t with
+    | Error e -> Error e
+    | Ok frame -> (
+        Buffer.add_string buf frame.content;
+        if frame.final then Ok (first_opcode, Buffer.contents buf)
+        else
+          match frame.opcode with
+          | Continuation -> collect_fragments first_opcode buf
+          | _ -> Error (Protocol_error "Expected continuation frame"))
+  in
+  let rec loop () =
+    match recv t with
+    | Error e -> Error e
+    | Ok frame -> (
+        match frame.opcode with
+        | Text | Binary ->
+            if frame.final then Ok (frame.opcode, frame.content)
+            else begin
+              let buf = Buffer.create 256 in
+              Buffer.add_string buf frame.content;
+              collect_fragments frame.opcode buf
+            end
+        | Close -> Error Connection_closed
+        | Ping | Pong ->
+            (* Control frames handled in recv, try again *)
+            loop ()
+        | Continuation -> Error (Protocol_error "Unexpected continuation")
+        | _ -> Error (Protocol_error "Unexpected opcode"))
+  in
+  loop ()
+
+(** Close the connection *)
+let close ?(code = 1000) t =
+  if not t.closed then begin
+    t.closed <- true;
+    ignore (send t (close_frame code))
+  end
+
+(** {1 Handshake helpers} *)
+
+(** Check if request headers indicate a WebSocket upgrade *)
+let is_upgrade_request headers =
+  let upgrade = H1.Headers.get headers "upgrade" in
+  let connection = H1.Headers.get headers "connection" in
+  let key = H1.Headers.get headers "sec-websocket-key" in
+  match (upgrade, connection, key) with
+  | Some u, Some c, Some _ ->
+      let u = String.lowercase_ascii u in
+      let c = String.lowercase_ascii c in
+      u = "websocket" && (c = "upgrade" || String.sub c 0 7 = "upgrade")
+  | _ -> false
+
+(** Get the Sec-WebSocket-Key from request headers *)
+let get_websocket_key headers = H1.Headers.get headers "sec-websocket-key"
+
+(** Generate random base64-encoded key for client handshake *)
+let generate_key () = Base64.encode_exn (Rng.generate 16)
+
+(** {1 Client API} *)
+
+(** Connect to a WebSocket server *)
+let connect ~sw ~net ?(tls_config = Tls_config.Client.default) ?protocols url =
+  let uri = Uri.of_string url in
+  let scheme = Uri.scheme uri |> Option.value ~default:"ws" in
+  let is_secure = scheme = "wss" in
+  let host = Uri.host uri |> Option.value ~default:"localhost" in
+  let default_port = if is_secure then 443 else 80 in
+  let port = Uri.port uri |> Option.value ~default:default_port in
+  let path =
+    let p = Uri.path_and_query uri in
+    if p = "" then "/" else p
+  in
+
+  (* Resolve and connect *)
+  let addrs = Eio.Net.getaddrinfo_stream net host in
+  match addrs with
+  | [] -> Error (Io_error ("Cannot resolve host: " ^ host))
+  | addr_info :: _ -> (
+      let addr =
+        match addr_info with
+        | `Tcp (ip, _) -> `Tcp (ip, port)
+        | `Unix _ -> failwith "Unix sockets not supported"
+      in
+      let tcp_flow = Eio.Net.connect ~sw net addr in
+
+      (* Wrap with TLS if secure *)
+      let flow_result =
+        if is_secure then
+          match Tls_config.Client.to_tls_config tls_config ~host with
+          | Error msg -> Error (Io_error ("TLS error: " ^ msg))
+          | Ok tls_cfg -> (
+              try
+                let host_domain =
+                  match Domain_name.of_string host with
+                  | Ok dn -> (
+                      match Domain_name.host dn with
+                      | Ok h -> Some h
+                      | Error _ -> None)
+                  | Error _ -> None
+                in
+                let tls_flow =
+                  Tls_eio.client_of_flow tls_cfg ?host:host_domain tcp_flow
+                in
+                Ok (tls_flow :> Eio.Flow.two_way_ty r)
+              with exn -> Error (Io_error (Printexc.to_string exn)))
+        else Ok (tcp_flow :> Eio.Flow.two_way_ty r)
+      in
+
+      match flow_result with
+      | Error e -> Error e
+      | Ok flow -> (
+          (* Generate key and build upgrade request *)
+          let key = generate_key () in
+          let expected_accept = compute_accept_key key in
+
+          let headers =
+            [
+              ("Host", host);
+              ("Upgrade", "websocket");
+              ("Connection", "Upgrade");
+              ("Sec-WebSocket-Key", key);
+              ("Sec-WebSocket-Version", "13");
+            ]
+          in
+          let headers =
+            match protocols with
+            | Some ps ->
+                ("Sec-WebSocket-Protocol", String.concat ", " ps) :: headers
+            | None -> headers
+          in
+
+          (* Send HTTP upgrade request *)
+          let buf = Buffer.create 256 in
+          Buffer.add_string buf (Printf.sprintf "GET %s HTTP/1.1\r\n" path);
+          List.iter
+            (fun (k, v) ->
+              Buffer.add_string buf (Printf.sprintf "%s: %s\r\n" k v))
+            headers;
+          Buffer.add_string buf "\r\n";
+
+          try
+            Eio.Flow.write flow [ Cstruct.of_string (Buffer.contents buf) ];
+
+            (* Read response headers *)
+            let response_buf = Buffer.create 1024 in
+            let rec read_until_crlf_crlf () =
+              let byte = read_exactly flow 1 in
+              Buffer.add_string response_buf byte;
+              let len = Buffer.length response_buf in
+              if
+                len >= 4
+                && Buffer.nth response_buf (len - 4) = '\r'
+                && Buffer.nth response_buf (len - 3) = '\n'
+                && Buffer.nth response_buf (len - 2) = '\r'
+                && Buffer.nth response_buf (len - 1) = '\n'
+              then ()
+              else read_until_crlf_crlf ()
+            in
+            read_until_crlf_crlf ();
+
+            (* Parse status line and headers *)
+            let response_str = Buffer.contents response_buf in
+            let lines = String.split_on_char '\n' response_str in
+
+            (* Check status line *)
+            match lines with
+            | status_line :: header_lines -> (
+                let status_line = String.trim status_line in
+                if
+                  not
+                    (String.length status_line >= 12
+                    && String.sub status_line 9 3 = "101")
+                then Error (Protocol_error ("Bad status: " ^ status_line))
+                else
+                  (* Parse headers *)
+                  let headers =
+                    List.filter_map
+                      (fun line ->
+                        let line = String.trim line in
+                        if line = "" then None
+                        else
+                          match String.index_opt line ':' with
+                          | Some i ->
+                              let key =
+                                String.lowercase_ascii (String.sub line 0 i)
+                              in
+                              let value =
+                                String.trim
+                                  (String.sub line (i + 1)
+                                     (String.length line - i - 1))
+                              in
+                              Some (key, value)
+                          | None -> None)
+                      header_lines
+                  in
+
+                  (* Validate accept key *)
+                  let accept = List.assoc_opt "sec-websocket-accept" headers in
+                  match accept with
+                  | Some a when a = expected_accept ->
+                      Ok
+                        {
+                          flow;
+                          closed = false;
+                          is_client = true;
+                          read_buf = Buffer.create 4096;
+                        }
+                  | Some a ->
+                      Error
+                        (Protocol_error
+                           (Printf.sprintf "Bad accept key: %s (expected %s)" a
+                              expected_accept))
+                  | None -> Error (Protocol_error "Missing accept key"))
+            | [] -> Error (Protocol_error "Empty response")
+          with exn -> Error (Io_error (Printexc.to_string exn))))
+
+(** {1 Server API} *)
+
+(** Accept a WebSocket upgrade from an HTTP connection. Returns a WebSocket
+    connection after sending the upgrade response. *)
+let accept ~flow ~key =
+  let accept = compute_accept_key key in
+  let response =
+    Printf.sprintf
+      "HTTP/1.1 101 Switching Protocols\r\n\
+       Upgrade: websocket\r\n\
+       Connection: Upgrade\r\n\
+       Sec-WebSocket-Accept: %s\r\n\
+       \r\n"
+      accept
+  in
+  try
+    Eio.Flow.write flow [ Cstruct.of_string response ];
+    Ok
+      {
+        flow :> Eio.Flow.two_way_ty r;
+        closed = false;
+        is_client = false;
+        read_buf = Buffer.create 4096;
+      }
+  with exn -> Error (Io_error (Printexc.to_string exn))

opencode.json

···
+{
+  "$schema": "https://opencode.ai/config.json",
+  "snapshot": false,
+  "lsp": {
+    "ocaml-lsp": {
+      "command": ["ocamllsp"],
+      "extensions": [".ml", ".mli"]
+    },
+    "clangd": {
+      "command": ["clangd"],
+      "extensions": [".c", ".h", ".cpp", ".hpp", ".cc", ".cxx", ".hh", ".hxx"]
+    }
+  },
+  "formatter": {
+    "ocamlformat": {
+      "command": ["ocamlformat", "--inplace", "$FILE"],
+      "extensions": [".ml", ".mli"]
+    },
+    "clang-format": {
+      "command": ["clang-format", "-i", "$FILE"],
+      "extensions": [".c", ".h", ".cpp", ".hpp", ".cc", ".cxx", ".hh", ".hxx"]
+    }
+  },
+  "mcp": {
+    "beads": {
+      "type": "local",
+      "command": ["uv", "tool", "run", "beads-mcp"],
+      "enabled": true
+    }, 
+    "tod": {
+      "type": "local",
+      "command": ["tod", "mcp", "--log-file", "/tmp/tod.log"],
+      "enabled": true
+    },
+    "jetbrains": {
+      "type": "local",
+      "environment": {
+        "IJ_MCP_SERVER_PORT": "64342"
+      },
+     "command": [ "/home/gdiazlo/.local/share/JetBrains/Toolbox/apps/clion/jbr/bin/java", "-classpath", "/home/gdiazlo/.local/share/JetBrains/CLion2025.3/mcpserver/lib/mcpserver.jar:/home/gdiazlo/.local/share/JetBrains/CLion2025.3/mcpserver/lib/io.modelcontextprotocol.kotlin.sdk.jar:/home/gdiazlo/.local/share/JetBrains/CLion2025.3/mcpserver/lib/io.github.oshai.kotlin.logging.jvm.jar:/home/gdiazlo/.local/share/JetBrains/Toolbox/apps/clion/lib/util-8.jar:/home/gdiazlo/.local/share/JetBrains/Toolbox/apps/clion/lib/module-intellij.libraries.ktor.client.cio.jar:/home/gdiazlo/.local/share/JetBrains/Toolbox/apps/clion/lib/module-intellij.libraries.ktor.client.jar:/home/gdiazlo/.local/share/JetBrains/Toolbox/apps/clion/lib/module-intellij.libraries.ktor.network.tls.jar:/home/gdiazlo/.local/share/JetBrains/Toolbox/apps/clion/lib/module-intellij.libraries.ktor.io.jar:/home/gdiazlo/.local/share/JetBrains/Toolbox/apps/clion/lib/module-intellij.libraries.ktor.utils.jar:/home/gdiazlo/.local/share/JetBrains/Toolbox/apps/clion/lib/module-intellij.libraries.kotlinx.io.jar:/home/gdiazlo/.local/share/JetBrains/Toolbox/apps/clion/lib/module-intellij.libraries.kotlinx.serialization.core.jar:/home/gdiazlo/.local/share/JetBrains/Toolbox/apps/clion/lib/module-intellij.libraries.kotlinx.serialization.json.jar",  "com.intellij.mcpserver.stdio.McpStdioRunnerKt" ]
+    }
+  }
+}

test/certs/cert.pem

···
+-----BEGIN CERTIFICATE-----
+MIIDCTCCAfGgAwIBAgIURfGI0GrBt2X78EYcfpuFIogJg1AwDQYJKoZIhvcNAQEL
+BQAwFDESMBAGA1UEAwwJbG9jYWxob3N0MB4XDTI1MTIzMDIwNTIyMFoXDTI2MTIz
+MDIwNTIyMFowFDESMBAGA1UEAwwJbG9jYWxob3N0MIIBIjANBgkqhkiG9w0BAQEF
+AAOCAQ8AMIIBCgKCAQEA31KLbLy0SawqPU+v3N1fbWDS2/5KVsai65o96pz/ENJA
+Y2797qomtd9mX3cSUTr8R0lAINqDoz158NIPRBezonWxiyBR3ZFh+uYEvlGjvJ7V
+RXpzOrW0OhmCHQoOJBf3EmC3GlBKPUK2WwPvF6kA/9kf/rFbPDdUKu3kV3np2Var
+pyAPQvjWcBvHzAOGMjkFxQHhlSAIY5JJkb5k0BsQsvcIEY1Sj6dqKZKmFhoJY1k2
+fysDc8nMto87fJm/OHVJtco6vmgEy4uAqpuUOeqdE9VYF9rdzmKUr19HQVFd4AwN
+UEpCNfjEAIlWg2hQqAXbn9xcjrKq41b/O8MXZBuUkwIDAQABo1MwUTAdBgNVHQ4E
+FgQUtlOWGEII5hFsFDU9RbLuqZ/1eMgwHwYDVR0jBBgwFoAUtlOWGEII5hFsFDU9
+RbLuqZ/1eMgwDwYDVR0TAQH/BAUwAwEB/zANBgkqhkiG9w0BAQsFAAOCAQEAbYHg
+hbev2BCczOqzoc3AI9rJL8S/m759lG55xcFO2j82ADwi3o8fIQpTBlNQu/HrvOLP
+BWvcc8kOyKZyTAzcCqZMreBGxP1B9LgOiRaoc8akoyKuqXg/iJ+RKwjqnUZiq0eQ
+nEhHzcVojRzBqLfKTuhLa/FOx++fUDrbr59zVcrJl62FUuNB9cqdFZZIV8xv0xYH
+yZ/gN4EceVY/uzC9HL0MCnaSUuJ7ZJ+C5Mv4DC6RoHxc0byjYv9JV0+xArbLMaEC
+mhe1vqAIbFw9zhgF+4uwQ1WKCvKiIJZGV1h21MhIXBwg8fZckX0OiTsjC4n1spMp
+JZc3Qt/B18/78/vBdg==
+-----END CERTIFICATE-----

test/certs/key.pem

···
+-----BEGIN PRIVATE KEY-----
+MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDfUotsvLRJrCo9
+T6/c3V9tYNLb/kpWxqLrmj3qnP8Q0kBjbv3uqia132ZfdxJROvxHSUAg2oOjPXnw
+0g9EF7OidbGLIFHdkWH65gS+UaO8ntVFenM6tbQ6GYIdCg4kF/cSYLcaUEo9QrZb
+A+8XqQD/2R/+sVs8N1Qq7eRXeenZVqunIA9C+NZwG8fMA4YyOQXFAeGVIAhjkkmR
+vmTQGxCy9wgRjVKPp2opkqYWGgljWTZ/KwNzycy2jzt8mb84dUm1yjq+aATLi4Cq
+m5Q56p0T1VgX2t3OYpSvX0dBUV3gDA1QSkI1+MQAiVaDaFCoBduf3FyOsqrjVv87
+wxdkG5STAgMBAAECggEAb5vARHK2o48geQ3HNVmJZI+cMggPPPj+2UJ3qTYXH2AE
+f+0riUiOGhzw+8r1Y5VYGYRZQVITsdR6iclhicVSqGGrfn2DjHko/4xPWJJSg2TZ
+72Q4DGJdFSBEb6Dj2lQDzbJ6L/Nqdt1NZ4U6y5dSAYuQuugGUbzRGrdThAhQv6Xq
+slO366T8XaAaYGpp5Bl8RW0C8H46lnVbvhyBZG+v+XCsvsYyuj8XtUc/FLT3NDBF
+8KSs62SRlhEr7oVc90oZtOd2/Cy05GqKjxn+e2iEuSGJtqmQwSmoc7kUC3rPpVuQ
+8nwVSvztfIO53zmWROJ2Nzq5c5//J5HUgHdDtC+T8QKBgQD9grp8+ZNw2ViHRboT
+GnvqbETiJFFpdjJHkuZCuDjYTBcOp9Kgtlj8oQP+v4Bxz8BUWuz4RvfloR1qN3AU
+79rbJQInOReReAAIrQIz8Hht1ldmwn98xB3CZdD4CQx5+yHRxwyEpIOtdwVlEFpO
+Y/b7kT0e9V97XABUI+x2voQHGQKBgQDhg+3vxaAkc+g62pW/a6gwJ1qlLziZL1PY
+KwDP2lzZ840pVnKMZAcLQkyC3mtqV/zxnDjfcY77SIpKI/EusNCC6SgW/nFDCaPw
+6HvLpzksS9kaU8KiTnX80cc2Wj0ovKUW0tZN5DpYtGKKwx55NQ2ntqMMruTRCSHo
+xHlTX6LKiwKBgAKVfokfkh0oWfqm/0qKjpDJIbqcXCgTCFgqayZq8kliHSoNE9yH
+f0iz63KBSTHfyDoT4y50qrowdjhK8F2GRFjPe8IiltbovjdYbBlTbibQdHubp+kB
+prwAhazBitsDcEjPGpWPh7gQ6oEpNYJvCmluBY13Os3rFiXFZ/ed4YKhAoGAN4jw
+sEo/nJp6hvvLQr91RJ58YQ9W5cpU4Hf+lDEXColCqvph7Ra48VnbU6MIWsDeRnWN
+P+FML692drmRLElYn9RhDgCMzdBy8eGektFUcAchqK0V0jh2L9NNNqJUS1LhaNR0
+9+uLPsr1NWzFdV3ORg3g6z+qk5unIRY5NoHnqe8CgYEA0ToCHBg/rM2VGaZbAfFp
+mTf2TQzbaD9IEQ2J7G3hzuw13FTWCyEbDoXvGtDqZYCnh2Mwj9okusvCLAyOlx29
+UUIJwEXhaxwoOqseLvUGYyP8wmD4r/D2aYqM6nKbeY4tdqKxZ18x2p27Dc25XKiP
+zdHQJbsvcTFunZsJiVa4DFQ=
+-----END PRIVATE KEY-----

test/dune

···
+(test
+ (name test_hcs)
+ (package hcs)
+ (libraries hcs alcotest qcheck qcheck-alcotest eio_main))
+
+(executable
+ (name test_client_integration)
+ (libraries hcs eio_main mirage-crypto-rng-eio)
+ (modules test_client_integration))
+
+(executable
+ (name test_alpn_server)
+ (libraries hcs eio_main mirage-crypto-rng-eio mirage-crypto-rng.unix)
+ (modules test_alpn_server))
+
+(executable
+ (name test_alpn_client)
+ (libraries hcs eio_main mirage-crypto-rng-eio mirage-crypto-rng.unix)
+ (modules test_alpn_client))

test/h2spec_runner.sh

···
+#!/bin/bash
+# h2spec compliance testing for HCS HTTP/2 server
+#
+# Prerequisites:
+#   - h2spec installed: go install github.com/summerwind/h2spec/cmd/h2spec@latest
+#   - OR download from: https://github.com/summerwind/h2spec/releases
+#
+# Usage:
+#   1. Start the HCS server: dune exec bin/hcs-demo.exe
+#   2. Run this script: ./test/h2spec_runner.sh
+#
+# Note: The server should be running on localhost:8443 with TLS
+#       or localhost:8080 without TLS
+
+set -e
+
+H2SPEC=${H2SPEC:-h2spec}
+HOST=${H2SPEC_HOST:-localhost}
+PORT=${H2SPEC_PORT:-8080}
+USE_TLS=${H2SPEC_TLS:-false}
+
+echo "H2Spec HTTP/2 Compliance Tests"
+echo "=============================="
+echo "Host: $HOST"
+echo "Port: $PORT"
+echo "TLS: $USE_TLS"
+echo ""
+
+# Check if h2spec is available
+if ! command -v "$H2SPEC" &> /dev/null; then
+    echo "Error: h2spec not found in PATH"
+    echo ""
+    echo "Install h2spec:"
+    echo "  go install github.com/summerwind/h2spec/cmd/h2spec@latest"
+    echo ""
+    echo "Or download from:"
+    echo "  https://github.com/summerwind/h2spec/releases"
+    exit 1
+fi
+
+# Build test options
+OPTS="-h $HOST -p $PORT"
+
+if [ "$USE_TLS" = "true" ]; then
+    OPTS="$OPTS -t -k"  # -t for TLS, -k to skip cert verification
+fi
+
+# Run h2spec
+echo "Running h2spec..."
+echo ""
+
+$H2SPEC $OPTS --strict
+
+echo ""
+echo "H2Spec tests complete."

test/test_alpn_client.ml

···
+let test_external_servers () =
+  Eio_main.run @@ fun env ->
+  let net = Eio.Stdenv.net env in
+  let clock = Eio.Stdenv.clock env in
+  Eio.Switch.run @@ fun sw ->
+  let urls =
+    [
+      ("https://www.google.com", "Google");
+      ("https://httpbin.org/get", "httpbin");
+      ("https://www.cloudflare.com", "Cloudflare");
+    ]
+  in
+  List.iter
+    (fun (url, name) ->
+      Eio.traceln "\n=== Testing %s ===" name;
+      Eio.traceln "URL: %s" url;
+
+      Eio.traceln "\n--- HTTP/1.1 mode ---";
+      let config = Hcs.Client.default_config |> Hcs.Client.with_http11 in
+      (match Hcs.Client.get ~sw ~net ~clock ~config url with
+      | Ok resp ->
+          let proto =
+            match resp.protocol with
+            | Hcs.Client.HTTP_1_1 -> "HTTP/1.1"
+            | Hcs.Client.HTTP_2 -> "HTTP/2"
+          in
+          Eio.traceln "Status: %d, Protocol: %s, Body size: %d" resp.status
+            proto (String.length resp.body)
+      | Error e ->
+          let msg =
+            match e with
+            | Hcs.Client.Connection_failed s -> "Connection failed: " ^ s
+            | Hcs.Client.Tls_error s -> "TLS error: " ^ s
+            | Hcs.Client.Protocol_error s -> "Protocol error: " ^ s
+            | Hcs.Client.Timeout -> "Timeout"
+            | Hcs.Client.Invalid_response s -> "Invalid response: " ^ s
+            | Hcs.Client.Too_many_redirects -> "Too many redirects"
+          in
+          Eio.traceln "Error: %s" msg);
+
+      Eio.traceln "\n--- HTTP/2 mode ---";
+      let config = Hcs.Client.default_config |> Hcs.Client.with_http2 in
+      match Hcs.Client.get ~sw ~net ~clock ~config url with
+      | Ok resp ->
+          let proto =
+            match resp.protocol with
+            | Hcs.Client.HTTP_1_1 -> "HTTP/1.1"
+            | Hcs.Client.HTTP_2 -> "HTTP/2"
+          in
+          Eio.traceln "Status: %d, Protocol: %s, Body size: %d" resp.status
+            proto (String.length resp.body)
+      | Error e ->
+          let msg =
+            match e with
+            | Hcs.Client.Connection_failed s -> "Connection failed: " ^ s
+            | Hcs.Client.Tls_error s -> "TLS error: " ^ s
+            | Hcs.Client.Protocol_error s -> "Protocol error: " ^ s
+            | Hcs.Client.Timeout -> "Timeout"
+            | Hcs.Client.Invalid_response s -> "Invalid response: " ^ s
+            | Hcs.Client.Too_many_redirects -> "Too many redirects"
+          in
+          Eio.traceln "Error: %s" msg)
+    urls
+
+let () =
+  Mirage_crypto_rng_unix.use_default ();
+  test_external_servers ()

test/test_alpn_server.ml

···
+let () =
+  Mirage_crypto_rng_unix.use_default ();
+  Eio_main.run @@ fun env ->
+  let net = Eio.Stdenv.net env in
+  Eio.Switch.run @@ fun sw ->
+  match
+    Hcs.Tls_config.Server.of_pem ~cert_file:"test/certs/cert.pem"
+      ~key_file:"test/certs/key.pem"
+  with
+  | Error msg ->
+      Eio.traceln "TLS config error: %s" msg;
+      exit 1
+  | Ok tls_config ->
+      let handler (req : Hcs.Server.request) =
+        let protocol_str =
+          match req.version with
+          | Hcs.Server.HTTP_1_1 -> "HTTP/1.1"
+          | Hcs.Server.HTTP_2 -> "HTTP/2"
+        in
+        Hcs.Server.respond ~status:`OK
+          (Printf.sprintf "Hello from %s! Target: %s" protocol_str req.target)
+      in
+      let config =
+        Hcs.Server.default_config |> Hcs.Server.with_port 8443
+        |> Hcs.Server.with_protocol Hcs.Server.Auto
+        |> Hcs.Server.with_tls tls_config
+      in
+      Hcs.Server.run ~sw ~net ~config handler

test/test_client_integration.ml

···
+(** Integration tests using httpbin.org for HTTP client compliance.
+
+    These tests require network access and use the public httpbin.org service.
+    They validate that the HCS HTTP client correctly implements HTTP semantics.
+
+    Run with: dune exec test/test_client_integration.exe
+
+    For local testing, you can run httpbin in Docker: docker run -p 8080:80
+    kennethreitz/httpbin
+
+    Then set HTTPBIN_URL=http://localhost:8080 *)
+
+let httpbin_url =
+  match Sys.getenv_opt "HTTPBIN_URL" with
+  | Some url -> url
+  | None -> "https://httpbin.org"
+
+(* Note: These are integration tests that require network access.
+   They are separate from unit tests and should be run manually or in CI
+   with network access enabled. *)
+
+let run_tests env () =
+  Eio.Switch.run @@ fun sw ->
+  let net = Eio.Stdenv.net env in
+  let clock = Eio.Stdenv.clock env in
+
+  (* Test 1: Simple GET request *)
+  Printf.printf "Test 1: GET /get ... ";
+  (try
+     let resp = Hcs.Client.get ~sw ~net ~clock (httpbin_url ^ "/get") in
+     match resp with
+     | Ok resp ->
+         if resp.status = 200 then begin
+           Printf.printf "OK (status=%d, body=%d bytes)\n" resp.status
+             (String.length resp.body)
+         end
+         else Printf.printf "FAIL (status=%d)\n" resp.status
+     | Error e ->
+         let msg =
+           match e with
+           | Hcs.Client.Connection_failed s -> "Connection_failed: " ^ s
+           | Hcs.Client.Tls_error s -> "Tls_error: " ^ s
+           | Hcs.Client.Protocol_error s -> "Protocol_error: " ^ s
+           | Hcs.Client.Timeout -> "Timeout"
+           | Hcs.Client.Invalid_response s -> "Invalid_response: " ^ s
+           | Hcs.Client.Too_many_redirects -> "Too_many_redirects"
+         in
+         Printf.printf "FAIL (error=%s)\n" msg
+   with exn -> Printf.printf "FAIL (exception=%s)\n" (Printexc.to_string exn));
+
+  (* Test 2: GET with query parameters *)
+  Printf.printf "Test 2: GET /get?foo=bar ... ";
+  (try
+     let resp =
+       Hcs.Client.get ~sw ~net ~clock (httpbin_url ^ "/get?foo=bar&baz=qux")
+     in
+     match resp with
+     | Ok resp ->
+         if resp.status = 200 && String.length resp.body > 0 then
+           Printf.printf "OK\n"
+         else Printf.printf "FAIL\n"
+     | Error _ -> Printf.printf "FAIL\n"
+   with exn -> Printf.printf "FAIL (exception=%s)\n" (Printexc.to_string exn));
+
+  (* Test 3: POST with body *)
+  Printf.printf "Test 3: POST /post with body ... ";
+  (try
+     let body = "Hello, httpbin!" in
+     let resp = Hcs.Client.post ~sw ~net ~clock ~body (httpbin_url ^ "/post") in
+     match resp with
+     | Ok resp ->
+         if resp.status = 200 then Printf.printf "OK\n"
+         else Printf.printf "FAIL (status=%d)\n" resp.status
+     | Error _ -> Printf.printf "FAIL\n"
+   with exn -> Printf.printf "FAIL (exception=%s)\n" (Printexc.to_string exn));
+
+  (* Test 4: Status code 201 *)
+  Printf.printf "Test 4: GET /status/201 ... ";
+  (try
+     let resp = Hcs.Client.get ~sw ~net ~clock (httpbin_url ^ "/status/201") in
+     match resp with
+     | Ok resp ->
+         if resp.status = 201 then Printf.printf "OK\n"
+         else Printf.printf "FAIL (status=%d)\n" resp.status
+     | Error _ -> Printf.printf "FAIL\n"
+   with exn -> Printf.printf "FAIL (exception=%s)\n" (Printexc.to_string exn));
+
+  (* Test 5: User-Agent header *)
+  Printf.printf "Test 5: GET /user-agent ... ";
+  (try
+     let resp = Hcs.Client.get ~sw ~net ~clock (httpbin_url ^ "/user-agent") in
+     match resp with
+     | Ok resp ->
+         if resp.status = 200 && String.length resp.body > 0 then
+           Printf.printf "OK\n"
+         else Printf.printf "FAIL\n"
+     | Error _ -> Printf.printf "FAIL\n"
+   with exn -> Printf.printf "FAIL (exception=%s)\n" (Printexc.to_string exn));
+
+  (* Test 6: Response headers *)
+  Printf.printf "Test 6: GET /response-headers?X-Test=value ... ";
+  (try
+     let resp =
+       Hcs.Client.get ~sw ~net ~clock
+         (httpbin_url ^ "/response-headers?X-Test=hello")
+     in
+     match resp with
+     | Ok resp ->
+         let has_header =
+           List.exists
+             (fun (k, _) -> String.lowercase_ascii k = "x-test")
+             resp.headers
+         in
+         if resp.status = 200 && has_header then Printf.printf "OK\n"
+         else Printf.printf "FAIL (missing header or bad status)\n"
+     | Error _ -> Printf.printf "FAIL\n"
+   with exn -> Printf.printf "FAIL (exception=%s)\n" (Printexc.to_string exn));
+
+  (* Test 7: Redirect (we don't follow redirects by default) *)
+  Printf.printf "Test 7: GET /absolute-redirect/1 ... ";
+  (try
+     (* Use config without redirects *)
+     let config = Hcs.Client.without_redirects Hcs.Client.default_config in
+     let resp =
+       Hcs.Client.get ~sw ~net ~clock ~config
+         (httpbin_url ^ "/absolute-redirect/1")
+     in
+     match resp with
+     | Ok resp ->
+         (* Should get 302 since we don't follow redirects *)
+         Printf.printf "OK (status=%d)\n" resp.status
+     | Error _ -> Printf.printf "FAIL\n"
+   with exn -> Printf.printf "FAIL (exception=%s)\n" (Printexc.to_string exn));
+
+  (* Test 8: HTTP/2 if available *)
+  Printf.printf "Test 8: GET /get with HTTP/2 ... ";
+  (try
+     let config = Hcs.Client.with_http2 Hcs.Client.default_config in
+     let resp = Hcs.Client.get ~sw ~net ~clock ~config (httpbin_url ^ "/get") in
+     match resp with
+     | Ok resp ->
+         let proto =
+           match resp.protocol with
+           | Hcs.Client.HTTP_1_1 -> "HTTP/1.1"
+           | Hcs.Client.HTTP_2 -> "HTTP/2"
+         in
+         Printf.printf "OK (status=%d, protocol=%s)\n" resp.status proto
+     | Error _ -> Printf.printf "FAIL\n"
+   with exn -> Printf.printf "FAIL (exception=%s)\n" (Printexc.to_string exn));
+
+  (* Test 9: gzip response *)
+  Printf.printf "Test 9: GET /gzip ... ";
+  (try
+     let resp = Hcs.Client.get ~sw ~net ~clock (httpbin_url ^ "/gzip") in
+     match resp with
+     | Ok resp ->
+         if resp.status = 200 then Printf.printf "OK\n"
+         else Printf.printf "FAIL (status=%d)\n" resp.status
+     | Error _ -> Printf.printf "FAIL\n"
+   with exn -> Printf.printf "FAIL (exception=%s)\n" (Printexc.to_string exn));
+
+  (* Test 10: Large response *)
+  Printf.printf "Test 10: GET /bytes/10000 ... ";
+  (try
+     let resp = Hcs.Client.get ~sw ~net ~clock (httpbin_url ^ "/bytes/10000") in
+     match resp with
+     | Ok resp ->
+         if resp.status = 200 && String.length resp.body = 10000 then
+           Printf.printf "OK (%d bytes)\n" (String.length resp.body)
+         else
+           Printf.printf "FAIL (status=%d, body=%d bytes)\n" resp.status
+             (String.length resp.body)
+     | Error _ -> Printf.printf "FAIL\n"
+   with exn -> Printf.printf "FAIL (exception=%s)\n" (Printexc.to_string exn));
+
+  Printf.printf "\nIntegration tests complete.\n"
+
+let () =
+  Printf.printf "HCS HTTP Client Integration Tests\n";
+  Printf.printf "Using httpbin at: %s\n\n" httpbin_url;
+
+  Eio_main.run @@ fun env ->
+  (Mirage_crypto_rng_eio.run [@alert "-deprecated"])
+    (module Mirage_crypto_rng.Fortuna)
+    env
+  @@ run_tests env

test/test_hcs.ml

···
+(** HCS Test Suite
+
+    This test suite covers:
+    - Codec module (identity, string codecs)
+    - Stream module (sync and async streams)
+    - Http module (request builder DSL)
+    - Router module (path parsing, route matching)
+    - Middleware module (composition, conditional)
+    - Property-based tests using QCheck *)
+
+open Alcotest
+
+(* ================================================================== *)
+(* Codec Tests *)
+(* ================================================================== *)
+
+module Test_codec = struct
+  open Hcs.Codec
+
+  let test_identity_codec_encode () =
+    let encoder : Cstruct.t Identity_codec.encoder = Fun.id in
+    let input = Cstruct.of_string "hello world" in
+    match Identity_codec.encode encoder input with
+    | Ok result ->
+        check string "encode" "hello world" (Cstruct.to_string result)
+    | Error e -> fail e
+
+  let test_identity_codec_decode () =
+    let decoder : Cstruct.t Identity_codec.decoder = fun cs -> Ok cs in
+    let input = Cstruct.of_string "hello world" in
+    match Identity_codec.decode decoder input with
+    | Ok result ->
+        check string "decode" "hello world" (Cstruct.to_string result)
+    | Error e -> fail e
+
+  let test_identity_codec_content_type () =
+    check string "content_type" "application/octet-stream"
+      Identity_codec.content_type
+
+  let test_string_codec_encode () =
+    let encoder : string String_codec.encoder = Fun.id in
+    match String_codec.encode encoder "hello world" with
+    | Ok result ->
+        check string "encode" "hello world" (Cstruct.to_string result)
+    | Error e -> fail e
+
+  let test_string_codec_decode () =
+    let decoder : string String_codec.decoder = fun s -> Ok s in
+    let input = Cstruct.of_string "hello world" in
+    match String_codec.decode decoder input with
+    | Ok result -> check string "decode" "hello world" result
+    | Error e -> fail e
+
+  let test_string_codec_content_type () =
+    check string "content_type" "text/plain; charset=utf-8"
+      String_codec.content_type
+
+  let test_codec_error_to_string () =
+    check string "encode_error" "Encode error: test"
+      (codec_error_to_string (Encode_error "test"));
+    check string "decode_error" "Decode error: test"
+      (codec_error_to_string (Decode_error "test"));
+    check string "unsupported" "Unsupported body type for codec operation"
+      (codec_error_to_string Unsupported_body_type)
+
+  let test_with_codec_encode_body () =
+    let module W = With_codec (String_codec) in
+    let encoder : string String_codec.encoder = String.uppercase_ascii in
+    match W.encode_body encoder "hello" with
+    | Ok result -> check string "encode_body" "HELLO" result
+    | Error e -> fail (codec_error_to_string e)
+
+  let test_with_codec_decode_body () =
+    let module W = With_codec (String_codec) in
+    let decoder : string String_codec.decoder =
+     fun s -> Ok (String.uppercase_ascii s)
+    in
+    match W.decode_body decoder "hello" with
+    | Ok result -> check string "decode_body" "HELLO" result
+    | Error e -> fail (codec_error_to_string e)
+
+  let tests =
+    [
+      test_case "identity codec encode" `Quick test_identity_codec_encode;
+      test_case "identity codec decode" `Quick test_identity_codec_decode;
+      test_case "identity codec content_type" `Quick
+        test_identity_codec_content_type;
+      test_case "string codec encode" `Quick test_string_codec_encode;
+      test_case "string codec decode" `Quick test_string_codec_decode;
+      test_case "string codec content_type" `Quick
+        test_string_codec_content_type;
+      test_case "codec error to string" `Quick test_codec_error_to_string;
+      test_case "with_codec encode_body" `Quick test_with_codec_encode_body;
+      test_case "with_codec decode_body" `Quick test_with_codec_decode_body;
+    ]
+end
+
+(* ================================================================== *)
+(* Stream Tests *)
+(* ================================================================== *)
+
+module Test_stream = struct
+  open Hcs.Stream
+
+  (* Sync stream tests *)
+  let test_sync_empty () =
+    let s = Sync.empty in
+    check (list int) "empty" [] (Sync.to_list s)
+
+  let test_sync_singleton () =
+    let s = Sync.singleton 42 in
+    check (list int) "singleton" [ 42 ] (Sync.to_list s)
+
+  let test_sync_of_list () =
+    let s = Sync.of_list [ 1; 2; 3 ] in
+    check (list int) "of_list" [ 1; 2; 3 ] (Sync.to_list s)
+
+  let test_sync_map () =
+    let s = Sync.of_list [ 1; 2; 3 ] |> Sync.map (fun x -> x * 2) in
+    check (list int) "map" [ 2; 4; 6 ] (Sync.to_list s)
+
+  let test_sync_filter () =
+    let s =
+      Sync.of_list [ 1; 2; 3; 4; 5 ] |> Sync.filter (fun x -> x mod 2 = 0)
+    in
+    check (list int) "filter" [ 2; 4 ] (Sync.to_list s)
+
+  let test_sync_take () =
+    let s = Sync.of_list [ 1; 2; 3; 4; 5 ] |> Sync.take 3 in
+    check (list int) "take" [ 1; 2; 3 ] (Sync.to_list s)
+
+  let test_sync_drop () =
+    let s = Sync.of_list [ 1; 2; 3; 4; 5 ] |> Sync.drop 2 in
+    check (list int) "drop" [ 3; 4; 5 ] (Sync.to_list s)
+
+  let test_sync_fold () =
+    let result = Sync.of_list [ 1; 2; 3; 4; 5 ] |> Sync.fold ( + ) 0 in
+    check int "fold" 15 result
+
+  let test_sync_chunks () =
+    let s = Sync.of_list [ 1; 2; 3; 4; 5 ] |> Sync.chunks 2 in
+    check
+      (list (list int))
+      "chunks"
+      [ [ 1; 2 ]; [ 3; 4 ]; [ 5 ] ]
+      (Sync.to_list s)
+
+  let test_sync_repeat () =
+    let s = Sync.repeat 3 "x" in
+    check (list string) "repeat" [ "x"; "x"; "x" ] (Sync.to_list s)
+
+  let test_sync_unfold () =
+    let s = Sync.unfold (fun n -> if n > 0 then Some (n, n - 1) else None) 3 in
+    check (list int) "unfold" [ 3; 2; 1 ] (Sync.to_list s)
+
+  let test_sync_append () =
+    let s1 = Sync.of_list [ 1; 2 ] in
+    let s2 = Sync.of_list [ 3; 4 ] in
+    let s = Sync.append s1 s2 in
+    check (list int) "append" [ 1; 2; 3; 4 ] (Sync.to_list s)
+
+  let test_sync_cstructs_to_string () =
+    let s =
+      Sync.of_list
+        [
+          Cstruct.of_string "hello";
+          Cstruct.of_string " ";
+          Cstruct.of_string "world";
+        ]
+    in
+    check string "cstructs_to_string" "hello world" (Sync.cstructs_to_string s)
+
+  let test_sync_string_to_cstructs () =
+    let s = Sync.string_to_cstructs ~chunk_size:5 "hello world" in
+    let result =
+      s |> Sync.map Cstruct.to_string |> Sync.to_list |> String.concat ""
+    in
+    check string "string_to_cstructs" "hello world" result
+
+  (* Async stream tests *)
+  let test_async_empty () =
+    let s = Async.empty in
+    check (list int) "async empty" [] (Async.to_list s)
+
+  let test_async_singleton () =
+    let s = Async.singleton 42 in
+    check (list int) "async singleton" [ 42 ] (Async.to_list s)
+
+  let test_async_of_list () =
+    let s = Async.of_list [ 1; 2; 3 ] in
+    check (list int) "async of_list" [ 1; 2; 3 ] (Async.to_list s)
+
+  let test_async_map () =
+    let s = Async.of_list [ 1; 2; 3 ] in
+    let mapped = Async.map (fun x -> x * 2) s in
+    check (list int) "async map" [ 2; 4; 6 ] (Async.to_list mapped)
+
+  let test_async_filter () =
+    let s = Async.of_list [ 1; 2; 3; 4; 5 ] in
+    let filtered = Async.filter (fun x -> x mod 2 = 0) s in
+    check (list int) "async filter" [ 2; 4 ] (Async.to_list filtered)
+
+  let test_async_take () =
+    let s = Async.of_list [ 1; 2; 3; 4; 5 ] in
+    let taken = Async.take 3 s in
+    check (list int) "async take" [ 1; 2; 3 ] (Async.to_list taken)
+
+  let test_async_fold () =
+    let s = Async.of_list [ 1; 2; 3; 4; 5 ] in
+    let result = Async.fold ( + ) 0 s in
+    check int "async fold" 15 result
+
+  (* Chunked encoding tests *)
+  let test_chunked_encode () =
+    let chunks = Sync.of_list [ Cstruct.of_string "hello" ] in
+    let encoded = Chunked.encode chunks in
+    let result = Sync.cstructs_to_string encoded in
+    (* 5 in hex is "5", chunk format: "5\r\nhello\r\n" followed by terminator "0\r\n\r\n" *)
+    check string "chunked encode" "5\r\nhello\r\n0\r\n\r\n" result
+
+  let test_chunked_content_length () =
+    let chunks =
+      Sync.of_list [ Cstruct.of_string "hello"; Cstruct.of_string " world" ]
+    in
+    let len = Chunked.content_length chunks in
+    check int "chunked content_length" 11 len
+
+  let tests =
+    [
+      (* Sync tests *)
+      test_case "sync empty" `Quick test_sync_empty;
+      test_case "sync singleton" `Quick test_sync_singleton;
+      test_case "sync of_list" `Quick test_sync_of_list;
+      test_case "sync map" `Quick test_sync_map;
+      test_case "sync filter" `Quick test_sync_filter;
+      test_case "sync take" `Quick test_sync_take;
+      test_case "sync drop" `Quick test_sync_drop;
+      test_case "sync fold" `Quick test_sync_fold;
+      test_case "sync chunks" `Quick test_sync_chunks;
+      test_case "sync repeat" `Quick test_sync_repeat;
+      test_case "sync unfold" `Quick test_sync_unfold;
+      test_case "sync append" `Quick test_sync_append;
+      test_case "sync cstructs_to_string" `Quick test_sync_cstructs_to_string;
+      test_case "sync string_to_cstructs" `Quick test_sync_string_to_cstructs;
+      (* Async tests *)
+      test_case "async empty" `Quick test_async_empty;
+      test_case "async singleton" `Quick test_async_singleton;
+      test_case "async of_list" `Quick test_async_of_list;
+      test_case "async map" `Quick test_async_map;
+      test_case "async filter" `Quick test_async_filter;
+      test_case "async take" `Quick test_async_take;
+      test_case "async fold" `Quick test_async_fold;
+      (* Chunked tests *)
+      test_case "chunked encode" `Quick test_chunked_encode;
+      test_case "chunked content_length" `Quick test_chunked_content_length;
+    ]
+end
+
+(* ================================================================== *)
+(* HTTP Request Builder Tests *)
+(* ================================================================== *)
+
+module Test_http = struct
+  open Hcs.Http
+
+  let test_get () =
+    let req = get "https://example.com/path" |> build in
+    check string "method" "GET" (meth_to_string req.req_meth);
+    check string "host" "example.com" (host req);
+    check string "path" "/path" (path req);
+    check bool "is_https" true (is_https req)
+
+  let test_post () =
+    let req = post "http://example.com/api" |> build in
+    check string "method" "POST" (meth_to_string req.req_meth);
+    check bool "is_https" false (is_https req)
+
+  let test_put () =
+    let req = put "http://example.com/resource" |> build in
+    check string "method" "PUT" (meth_to_string req.req_meth)
+
+  let test_delete () =
+    let req = delete "http://example.com/resource/1" |> build in
+    check string "method" "DELETE" (meth_to_string req.req_meth)
+
+  let test_patch () =
+    let req = patch "http://example.com/resource/1" |> build in
+    check string "method" "PATCH" (meth_to_string req.req_meth)
+
+  let test_head () =
+    let req = head "http://example.com/" |> build in
+    check string "method" "HEAD" (meth_to_string req.req_meth)
+
+  let test_options () =
+    let req = options "http://example.com/" |> build in
+    check string "method" "OPTIONS" (meth_to_string req.req_meth)
+
+  let test_header () =
+    let req =
+      get "http://example.com" |> header "X-Custom" "value"
+      |> header "X-Another" "another"
+      |> build
+    in
+    check bool "has X-Custom"
+      (List.mem ("X-Custom", "value") req.req_headers)
+      true;
+    check bool "has X-Another"
+      (List.mem ("X-Another", "another") req.req_headers)
+      true
+
+  let test_content_type () =
+    let req =
+      post "http://example.com" |> content_type "application/json" |> build
+    in
+    check bool "has Content-Type"
+      (List.mem ("Content-Type", "application/json") req.req_headers)
+      true
+
+  let test_accept () =
+    let req = get "http://example.com" |> accept "text/html" |> build in
+    check bool "has Accept"
+      (List.mem ("Accept", "text/html") req.req_headers)
+      true
+
+  let test_user_agent () =
+    let req = get "http://example.com" |> user_agent "HCS/1.0" |> build in
+    check bool "has User-Agent"
+      (List.mem ("User-Agent", "HCS/1.0") req.req_headers)
+      true
+
+  let test_bearer () =
+    let req = get "http://example.com" |> bearer "token123" |> build in
+    check bool "has Authorization"
+      (List.mem ("Authorization", "Bearer token123") req.req_headers)
+      true
+
+  let test_query () =
+    let req =
+      get "http://example.com/search"
+      |> query "q" "ocaml" |> query "limit" "10" |> build
+    in
+    let pq = path_and_query req in
+    check bool "has q param" (String.length pq > 0) true
+
+  let test_body_string () =
+    let req =
+      post "http://example.com"
+      |> body_string ~content_type:"text/plain" "hello"
+      |> build
+    in
+    check string "body" "hello" (body_to_string req.req_body);
+    check bool "has Content-Type"
+      (List.mem ("Content-Type", "text/plain") req.req_headers)
+      true
+
+  let test_body_json () =
+    let req =
+      post "http://example.com" |> body_json {|{"key": "value"}|} |> build
+    in
+    check string "body" {|{"key": "value"}|} (body_to_string req.req_body);
+    check bool "has Content-Type"
+      (List.mem ("Content-Type", "application/json") req.req_headers)
+      true
+
+  let test_form () =
+    let req =
+      post "http://example.com"
+      |> form [ ("name", "Alice"); ("age", "30") ]
+      |> build
+    in
+    let body_str = body_to_string req.req_body in
+    check bool "has name" (String.length body_str > 0) true;
+    check bool "has Content-Type"
+      (List.mem
+         ("Content-Type", "application/x-www-form-urlencoded")
+         req.req_headers)
+      true
+
+  let test_port_default_http () =
+    let req = get "http://example.com/" |> build in
+    check int "port" 80 (port req)
+
+  let test_port_default_https () =
+    let req = get "https://example.com/" |> build in
+    check int "port" 443 (port req)
+
+  let test_port_explicit () =
+    let req = get "http://example.com:8080/" |> build in
+    check int "port" 8080 (port req)
+
+  let test_meth_of_string () =
+    check string "GET" "GET" (meth_to_string (meth_of_string "GET"));
+    check string "POST" "POST" (meth_to_string (meth_of_string "POST"));
+    check string "CUSTOM" "CUSTOM" (meth_to_string (meth_of_string "CUSTOM"))
+
+  let test_body_length () =
+    check int "empty body" 0 (body_length Empty);
+    check int "string body" 5 (body_length (String "hello"));
+    check int "form body" (String.length "a=1&b=2")
+      (body_length (Form [ ("a", "1"); ("b", "2") ]))
+
+  let test_cookie () =
+    let req = get "http://example.com" |> cookie "session" "abc123" |> build in
+    check bool "has Cookie"
+      (List.exists
+         (fun (n, v) -> n = "Cookie" && String.length v > 0)
+         req.req_headers)
+      true
+
+  let test_cookies_multiple () =
+    let req =
+      get "http://example.com" |> cookie "a" "1" |> cookie "b" "2" |> build
+    in
+    let cookie_header =
+      List.find_opt (fun (n, _) -> n = "Cookie") req.req_headers
+    in
+    match cookie_header with
+    | Some (_, v) -> check bool "has a" (String.length v > 0) true
+    | None -> fail "no Cookie header"
+
+  let tests =
+    [
+      test_case "get" `Quick test_get;
+      test_case "post" `Quick test_post;
+      test_case "put" `Quick test_put;
+      test_case "delete" `Quick test_delete;
+      test_case "patch" `Quick test_patch;
+      test_case "head" `Quick test_head;
+      test_case "options" `Quick test_options;
+      test_case "header" `Quick test_header;
+      test_case "content_type" `Quick test_content_type;
+      test_case "accept" `Quick test_accept;
+      test_case "user_agent" `Quick test_user_agent;
+      test_case "bearer" `Quick test_bearer;
+      test_case "query" `Quick test_query;
+      test_case "body_string" `Quick test_body_string;
+      test_case "body_json" `Quick test_body_json;
+      test_case "form" `Quick test_form;
+      test_case "port default http" `Quick test_port_default_http;
+      test_case "port default https" `Quick test_port_default_https;
+      test_case "port explicit" `Quick test_port_explicit;
+      test_case "meth_of_string" `Quick test_meth_of_string;
+      test_case "body_length" `Quick test_body_length;
+      test_case "cookie" `Quick test_cookie;
+      test_case "cookies multiple" `Quick test_cookies_multiple;
+    ]
+end
+
+(* ================================================================== *)
+(* Router Tests *)
+(* ================================================================== *)
+
+module Test_router = struct
+  open Hcs.Router
+
+  let test_parse_path_empty () =
+    check (list string) "empty" []
+      (List.map
+         (function Literal s -> s | Param s -> ":" ^ s | Wildcard -> "*")
+         (parse_path ""))
+
+  let test_parse_path_root () =
+    check (list string) "root" []
+      (List.map
+         (function Literal s -> s | Param s -> ":" ^ s | Wildcard -> "*")
+         (parse_path "/"))
+
+  let test_parse_path_simple () =
+    let segments = parse_path "/users/list" in
+    check int "length" 2 (List.length segments);
+    match segments with
+    | [ Literal "users"; Literal "list" ] -> ()
+    | _ -> fail "unexpected segments"
+
+  let test_parse_path_with_params () =
+    let segments = parse_path "/users/:id/posts/:post_id" in
+    check int "length" 4 (List.length segments);
+    match segments with
+    | [ Literal "users"; Param "id"; Literal "posts"; Param "post_id" ] -> ()
+    | _ -> fail "unexpected segments"
+
+  let test_parse_path_with_wildcard () =
+    let segments = parse_path "/files/*" in
+    check int "length" 2 (List.length segments);
+    match segments with
+    | [ Literal "files"; Wildcard ] -> ()
+    | _ -> fail "unexpected segments"
+
+  let test_router_literal_match () =
+    let router = empty () in
+    add_route router ~method_:(Some `GET) ~path:"/users"
+      ~handler:"users_handler";
+    match lookup router ~method_:`GET ~path:"/users" with
+    | Some (handler, _) -> check string "handler" "users_handler" handler
+    | None -> fail "no match"
+
+  let test_router_param_match () =
+    let router = empty () in
+    add_route router ~method_:(Some `GET) ~path:"/users/:id"
+      ~handler:"user_handler";
+    match lookup router ~method_:`GET ~path:"/users/123" with
+    | Some (handler, params) ->
+        check string "handler" "user_handler" handler;
+        check (option string) "id param" (Some "123") (param "id" params)
+    | None -> fail "no match"
+
+  let test_router_multiple_params () =
+    let router = empty () in
+    add_route router ~method_:(Some `GET) ~path:"/users/:user_id/posts/:post_id"
+      ~handler:"post_handler";
+    match lookup router ~method_:`GET ~path:"/users/42/posts/100" with
+    | Some (handler, params) ->
+        check string "handler" "post_handler" handler;
+        check (option string) "user_id" (Some "42") (param "user_id" params);
+        check (option string) "post_id" (Some "100") (param "post_id" params)
+    | None -> fail "no match"
+
+  let test_router_wildcard_match () =
+    let router = empty () in
+    add_route router ~method_:(Some `GET) ~path:"/files/*"
+      ~handler:"files_handler";
+    match lookup router ~method_:`GET ~path:"/files/path/to/file.txt" with
+    | Some (handler, params) ->
+        check string "handler" "files_handler" handler;
+        check (option string) "wildcard" (Some "path/to/file.txt")
+          (param "*" params)
+    | None -> fail "no match"
+
+  let test_router_method_match () =
+    let router = empty () in
+    add_route router ~method_:(Some `GET) ~path:"/users" ~handler:"get_handler";
+    add_route router ~method_:(Some `POST) ~path:"/users"
+      ~handler:"post_handler";
+    (match lookup router ~method_:`GET ~path:"/users" with
+    | Some (handler, _) -> check string "GET handler" "get_handler" handler
+    | None -> fail "no GET match");
+    match lookup router ~method_:`POST ~path:"/users" with
+    | Some (handler, _) -> check string "POST handler" "post_handler" handler
+    | None -> fail "no POST match"
+
+  let test_router_any_method () =
+    let router = empty () in
+    add_route router ~method_:None ~path:"/health" ~handler:"health_handler";
+    (match lookup router ~method_:`GET ~path:"/health" with
+    | Some (handler, _) -> check string "GET" "health_handler" handler
+    | None -> fail "no GET match");
+    match lookup router ~method_:`POST ~path:"/health" with
+    | Some (handler, _) -> check string "POST" "health_handler" handler
+    | None -> fail "no POST match"
+
+  let test_router_no_match () =
+    let router = empty () in
+    add_route router ~method_:(Some `GET) ~path:"/users" ~handler:"handler";
+    match lookup router ~method_:`GET ~path:"/posts" with
+    | Some _ -> fail "unexpected match"
+    | None -> ()
+
+  let test_router_compile () =
+    let routes =
+      [
+        Route.get "/users" "list_users";
+        Route.post "/users" "create_user";
+        Route.get "/users/:id" "get_user";
+        Route.delete "/users/:id" "delete_user";
+      ]
+    in
+    let router = compile routes in
+    (match lookup router ~method_:`GET ~path:"/users" with
+    | Some (h, _) -> check string "list" "list_users" h
+    | None -> fail "no list match");
+    match lookup router ~method_:`GET ~path:"/users/42" with
+    | Some (h, params) ->
+        check string "get" "get_user" h;
+        check (option string) "id" (Some "42") (param "id" params)
+    | None -> fail "no get match"
+
+  let test_param_helpers () =
+    let params = [ ("id", "42"); ("name", "alice") ] in
+    check (option string) "param" (Some "42") (param "id" params);
+    check (option string) "param missing" None (param "foo" params);
+    check string "param_or" "default" (param_or "foo" ~default:"default" params);
+    check (option int) "param_int" (Some 42) (param_int "id" params);
+    check int "param_int_or" 0 (param_int_or "foo" ~default:0 params)
+
+  let tests =
+    [
+      test_case "parse_path empty" `Quick test_parse_path_empty;
+      test_case "parse_path root" `Quick test_parse_path_root;
+      test_case "parse_path simple" `Quick test_parse_path_simple;
+      test_case "parse_path with params" `Quick test_parse_path_with_params;
+      test_case "parse_path with wildcard" `Quick test_parse_path_with_wildcard;
+      test_case "router literal match" `Quick test_router_literal_match;
+      test_case "router param match" `Quick test_router_param_match;
+      test_case "router multiple params" `Quick test_router_multiple_params;
+      test_case "router wildcard match" `Quick test_router_wildcard_match;
+      test_case "router method match" `Quick test_router_method_match;
+      test_case "router any method" `Quick test_router_any_method;
+      test_case "router no match" `Quick test_router_no_match;
+      test_case "router compile" `Quick test_router_compile;
+      test_case "param helpers" `Quick test_param_helpers;
+    ]
+end
+
+(* ================================================================== *)
+(* Middleware Tests *)
+(* ================================================================== *)
+
+module Test_middleware = struct
+  open Hcs.Middleware
+
+  let test_identity () =
+    let handler x = x + 1 in
+    let wrapped = apply identity handler in
+    check int "identity" 2 (wrapped 1)
+
+  let test_compose () =
+    let m1 : (int, int) t = fun next x -> next (x * 2) in
+    let m2 : (int, int) t = fun next x -> next (x + 1) in
+    let composed = compose m1 m2 in
+    let handler x = x in
+    let result = apply composed handler 5 in
+    (* m1 runs first: 5 * 2 = 10, then m2: 10 + 1 = 11 *)
+    check int "compose" 11 result
+
+  let test_compose_all () =
+    let m1 : (int, int) t = fun next x -> next (x * 2) in
+    let m2 : (int, int) t = fun next x -> next (x + 1) in
+    let m3 : (int, int) t = fun next x -> next (x - 3) in
+    let composed = compose_all [ m1; m2; m3 ] in
+    let handler x = x in
+    let result = apply composed handler 5 in
+    (* m1: 5 * 2 = 10, m2: 10 + 1 = 11, m3: 11 - 3 = 8 *)
+    check int "compose_all" 8 result
+
+  let test_infix_compose () =
+    let m1 : (int, int) t = fun next x -> next (x * 2) in
+    let m2 : (int, int) t = fun next x -> next (x + 1) in
+    let composed = m1 @> m2 in
+    let handler x = x in
+    check int "infix" 11 (apply composed handler 5)
+
+  let test_logging () =
+    let logs = ref [] in
+    let log msg = logs := msg :: !logs in
+    let m = logging ~log in
+    let handler _ = "response" in
+    let _ = apply m handler () in
+    check int "log count" 2 (List.length !logs);
+    check bool "has request log" (List.mem "Request received" !logs) true;
+    check bool "has response log" (List.mem "Response sent" !logs) true
+
+  let test_timing () =
+    let duration_ref = ref 0.0 in
+    let on_complete d = duration_ref := d in
+    let m = timing ~on_complete in
+    let handler _ =
+      Unix.sleepf 0.01;
+      "response"
+    in
+    let _ = apply m handler () in
+    check bool "duration > 0" (!duration_ref > 0.0) true
+
+  let test_recover () =
+    let m = recover ~on_error:(fun _ -> "recovered") in
+    let handler _ = failwith "error" in
+    let result = apply m handler () in
+    check string "recover" "recovered" result
+
+  let test_when_true () =
+    let m : (int, int) t = fun next x -> next (x * 2) in
+    let conditional = when_ (fun x -> x > 0) m in
+    let handler x = x in
+    check int "when true" 10 (apply conditional handler 5);
+    check int "when false" (-5) (apply conditional handler (-5))
+
+  let test_unless () =
+    let m : (int, int) t = fun next x -> next (x * 2) in
+    let conditional = unless (fun x -> x < 0) m in
+    let handler x = x in
+    check int "unless true" 10 (apply conditional handler 5);
+    check int "unless false" (-5) (apply conditional handler (-5))
+
+  let tests =
+    [
+      test_case "identity" `Quick test_identity;
+      test_case "compose" `Quick test_compose;
+      test_case "compose_all" `Quick test_compose_all;
+      test_case "infix compose" `Quick test_infix_compose;
+      test_case "logging" `Quick test_logging;
+      test_case "timing" `Quick test_timing;
+      test_case "recover" `Quick test_recover;
+      test_case "when_ true/false" `Quick test_when_true;
+      test_case "unless" `Quick test_unless;
+    ]
+end
+
+(* ================================================================== *)
+(* Log Tests *)
+(* ================================================================== *)
+
+module Test_log = struct
+  open Hcs.Log
+
+  let test_level_to_string () =
+    check string "debug" "DEBUG" (level_to_string Debug);
+    check string "info" "INFO" (level_to_string Info);
+    check string "warn" "WARN" (level_to_string Warn);
+    check string "error" "ERROR" (level_to_string Error)
+
+  let test_level_of_string () =
+    check bool "DEBUG" true (level_of_string "DEBUG" = Some Debug);
+    check bool "debug" true (level_of_string "debug" = Some Debug);
+    check bool "INFO" true (level_of_string "INFO" = Some Info);
+    check bool "WARN" true (level_of_string "WARN" = Some Warn);
+    check bool "unknown" true (level_of_string "unknown" = None)
+
+  let test_level_gte () =
+    check bool "error >= debug" true (level_gte Error Debug);
+    check bool "error >= error" true (level_gte Error Error);
+    check bool "debug >= error" false (level_gte Debug Error);
+    check bool "warn >= info" true (level_gte Warn Info)
+
+  let test_method_to_string () =
+    check string "GET" "GET" (method_to_string GET);
+    check string "POST" "POST" (method_to_string POST);
+    check string "Other" "CUSTOM" (method_to_string (Other "CUSTOM"))
+
+  let test_event_to_string_request_start () =
+    let e =
+      Request_start { id = "req-1"; meth = GET; uri = "/test"; headers = [] }
+    in
+    let s = event_to_string e in
+    check bool "contains id" (String.length s > 0) true;
+    check bool "contains GET" true (String.length s > 0)
+
+  let test_event_to_string_request_end () =
+    let e =
+      Request_end
+        {
+          id = "req-1";
+          status = 200;
+          duration_ms = 42.5;
+          body_size = Some 1024;
+        }
+    in
+    let s = event_to_string e in
+    check bool "contains status" (String.length s > 0) true
+
+  let test_event_to_string_error () =
+    let e =
+      Error
+        { id = Some "req-1"; error = "connection failed"; context = Some "TLS" }
+    in
+    let s = event_to_string e in
+    check bool "contains error" (String.length s > 0) true
+
+  let test_event_to_json_request_start () =
+    let e =
+      Request_start { id = "req-1"; meth = GET; uri = "/test"; headers = [] }
+    in
+    let j = event_to_json e in
+    check bool "is json" true (String.sub j 0 1 = "{");
+    check bool "contains event" true (String.length j > 10)
+
+  let test_event_to_json_custom () =
+    let e = Custom { name = "test_event"; data = [ ("key", "value") ] } in
+    let j = event_to_json e in
+    check bool "is json" true (String.sub j 0 1 = "{");
+    check bool "contains name" true (String.length j > 10)
+
+  let test_null_logger () =
+    (* Should not raise *)
+    null Info
+      (Request_start { id = "req-1"; meth = GET; uri = "/"; headers = [] });
+    null Error (Error { id = None; error = "test"; context = None })
+
+  let test_custom_logger () =
+    let logged = ref [] in
+    let logger = custom (fun level msg -> logged := (level, msg) :: !logged) in
+    logger Info
+      (Request_start { id = "req-1"; meth = GET; uri = "/"; headers = [] });
+    check int "logged count" 1 (List.length !logged)
+
+  let test_combine_loggers () =
+    let count1 = ref 0 in
+    let count2 = ref 0 in
+    let logger1 = custom (fun _ _ -> incr count1) in
+    let logger2 = custom (fun _ _ -> incr count2) in
+    let combined = combine [ logger1; logger2 ] in
+    combined Info (Custom { name = "test"; data = [] });
+    check int "logger1 count" 1 !count1;
+    check int "logger2 count" 1 !count2
+
+  let test_with_min_level () =
+    let logged = ref [] in
+    let base = custom (fun level msg -> logged := (level, msg) :: !logged) in
+    let filtered = with_min_level Warn base in
+    filtered Debug (Custom { name = "debug"; data = [] });
+    filtered Info (Custom { name = "info"; data = [] });
+    filtered Warn (Custom { name = "warn"; data = [] });
+    filtered Error (Custom { name = "error"; data = [] });
+    check int "logged count" 2 (List.length !logged)
+
+  let test_generate_request_id () =
+    let id1 = generate_request_id () in
+    let id2 = generate_request_id () in
+    check bool "starts with req-" true (String.sub id1 0 4 = "req-");
+    check bool "unique" true (id1 <> id2)
+
+  let tests =
+    [
+      test_case "level_to_string" `Quick test_level_to_string;
+      test_case "level_of_string" `Quick test_level_of_string;
+      test_case "level_gte" `Quick test_level_gte;
+      test_case "method_to_string" `Quick test_method_to_string;
+      test_case "event_to_string request_start" `Quick
+        test_event_to_string_request_start;
+      test_case "event_to_string request_end" `Quick
+        test_event_to_string_request_end;
+      test_case "event_to_string error" `Quick test_event_to_string_error;
+      test_case "event_to_json request_start" `Quick
+        test_event_to_json_request_start;
+      test_case "event_to_json custom" `Quick test_event_to_json_custom;
+      test_case "null logger" `Quick test_null_logger;
+      test_case "custom logger" `Quick test_custom_logger;
+      test_case "combine loggers" `Quick test_combine_loggers;
+      test_case "with_min_level" `Quick test_with_min_level;
+      test_case "generate_request_id" `Quick test_generate_request_id;
+    ]
+end
+
+module Test_tls_config = struct
+  open Hcs.Tls_config
+
+  let test_alpn_constants () =
+    check string "h2" "h2" alpn_h2;
+    check string "http/1.1" "http/1.1" alpn_http11;
+    check string "h2c" "h2c" alpn_h2c
+
+  let test_protocol_of_alpn () =
+    check (option string) "h2 -> HTTP_2" (Some "HTTP_2")
+      (Option.map
+         (function HTTP_2 -> "HTTP_2" | HTTP_1_1 -> "HTTP_1_1")
+         (protocol_of_alpn "h2"));
+    check (option string) "http/1.1 -> HTTP_1_1" (Some "HTTP_1_1")
+      (Option.map
+         (function HTTP_2 -> "HTTP_2" | HTTP_1_1 -> "HTTP_1_1")
+         (protocol_of_alpn "http/1.1"));
+    check (option string) "unknown -> None" None
+      (Option.map
+         (function HTTP_2 -> "HTTP_2" | HTTP_1_1 -> "HTTP_1_1")
+         (protocol_of_alpn "unknown"))
+
+  let test_alpn_of_protocol () =
+    check string "HTTP_2 -> h2" "h2" (alpn_of_protocol HTTP_2);
+    check string "HTTP_1_1 -> http/1.1" "http/1.1" (alpn_of_protocol HTTP_1_1)
+
+  let test_client_configs () =
+    check
+      (option (list string))
+      "default has http/1.1" (Some [ "http/1.1" ]) Client.default.alpn_protocols;
+    check
+      (option (list string))
+      "h2 has h2" (Some [ "h2" ]) Client.h2.alpn_protocols;
+    check
+      (option (list string))
+      "h2_or_http11 has both"
+      (Some [ "h2"; "http/1.1" ])
+      Client.h2_or_http11.alpn_protocols
+
+  let tests =
+    [
+      test_case "alpn constants" `Quick test_alpn_constants;
+      test_case "protocol_of_alpn" `Quick test_protocol_of_alpn;
+      test_case "alpn_of_protocol" `Quick test_alpn_of_protocol;
+      test_case "client configs" `Quick test_client_configs;
+    ]
+end
+
+(* ================================================================== *)
+(* Property-Based Tests (QCheck) *)
+(* ================================================================== *)
+
+module Test_properties = struct
+  (* Stream properties *)
+  let prop_sync_map_identity =
+    QCheck.Test.make ~name:"sync map identity" ~count:100
+      QCheck.(list int)
+      (fun l ->
+        let open Hcs.Stream.Sync in
+        let s = of_list l in
+        to_list (map Fun.id s) = l)
+
+  let prop_sync_map_composition =
+    QCheck.Test.make ~name:"sync map composition" ~count:100
+      QCheck.(list nat_small)
+      (fun l ->
+        let open Hcs.Stream.Sync in
+        let f x = x + 1 in
+        let g x = x * 2 in
+        let s = of_list l in
+        to_list (map (fun x -> g (f x)) s) = to_list (map g (map f (of_list l))))
+
+  let prop_sync_filter_all =
+    QCheck.Test.make ~name:"sync filter true keeps all" ~count:100
+      QCheck.(list int)
+      (fun l ->
+        let open Hcs.Stream.Sync in
+        to_list (filter (fun _ -> true) (of_list l)) = l)
+
+  let prop_sync_filter_none =
+    QCheck.Test.make ~name:"sync filter false removes all" ~count:100
+      QCheck.(list int)
+      (fun l ->
+        let open Hcs.Stream.Sync in
+        to_list (filter (fun _ -> false) (of_list l)) = [])
+
+  let prop_sync_take_drop =
+    QCheck.Test.make ~name:"sync take n ++ drop n = original" ~count:100
+      QCheck.(pair (list int) nat_small)
+      (fun (l, n) ->
+        let open Hcs.Stream.Sync in
+        let s1 = of_list l in
+        let s2 = of_list l in
+        let taken = to_list (take n s1) in
+        let dropped = to_list (drop n s2) in
+        taken @ dropped = l)
+
+  let prop_sync_fold_sum =
+    QCheck.Test.make ~name:"sync fold sum = List.fold_left sum" ~count:100
+      QCheck.(list nat_small)
+      (fun l ->
+        let open Hcs.Stream.Sync in
+        fold ( + ) 0 (of_list l) = List.fold_left ( + ) 0 l)
+
+  (* Router properties *)
+  let prop_router_param_extraction =
+    QCheck.Test.make ~name:"router extracts all params" ~count:100
+      QCheck.(pair string_small string_small)
+      (fun (id, name) ->
+        (* Skip edge cases: empty strings or strings containing / *)
+        if
+          id = "" || name = "" || String.contains id '/'
+          || String.contains name '/'
+        then true (* vacuously true for invalid inputs *)
+        else
+          let open Hcs.Router in
+          let router = empty () in
+          add_route router ~method_:(Some `GET) ~path:"/users/:id/items/:name"
+            ~handler:"handler";
+          match
+            lookup router ~method_:`GET
+              ~path:(Printf.sprintf "/users/%s/items/%s" id name)
+          with
+          | Some (_, params) ->
+              param "id" params = Some id && param "name" params = Some name
+          | None -> false)
+
+  (* HTTP builder properties *)
+  let prop_http_method_roundtrip =
+    QCheck.Test.make ~name:"http method roundtrip" ~count:20
+      QCheck.(
+        make
+          Gen.(
+            oneof
+              [
+                return "GET";
+                return "POST";
+                return "PUT";
+                return "DELETE";
+                return "PATCH";
+                return "HEAD";
+                return "OPTIONS";
+              ]))
+      (fun m ->
+        let open Hcs.Http in
+        meth_to_string (meth_of_string m) = m)
+
+  (* Middleware properties *)
+  let prop_middleware_identity =
+    QCheck.Test.make ~name:"middleware identity is neutral" ~count:100
+      QCheck.int (fun x ->
+        let open Hcs.Middleware in
+        let handler n = n + 1 in
+        apply identity handler x = handler x)
+
+  let prop_middleware_compose_associative =
+    QCheck.Test.make ~name:"middleware compose is associative" ~count:100
+      QCheck.nat_small (fun x ->
+        let open Hcs.Middleware in
+        let m1 : (int, int) t = fun next n -> next (n + 1) in
+        let m2 : (int, int) t = fun next n -> next (n * 2) in
+        let m3 : (int, int) t = fun next n -> next (n - 3) in
+        let handler n = n in
+        let left = apply (compose (compose m1 m2) m3) handler x in
+        let right = apply (compose m1 (compose m2 m3)) handler x in
+        left = right)
+
+  let tests =
+    List.map QCheck_alcotest.to_alcotest
+      [
+        prop_sync_map_identity;
+        prop_sync_map_composition;
+        prop_sync_filter_all;
+        prop_sync_filter_none;
+        prop_sync_take_drop;
+        prop_sync_fold_sum;
+        prop_router_param_extraction;
+        prop_http_method_roundtrip;
+        prop_middleware_identity;
+        prop_middleware_compose_associative;
+      ]
+end
+
+(* ================================================================== *)
+(* Main *)
+(* ================================================================== *)
+
+let () =
+  run "HCS"
+    [
+      ("Codec", Test_codec.tests);
+      ("Stream", Test_stream.tests);
+      ("Http", Test_http.tests);
+      ("Router", Test_router.tests);
+      ("Middleware", Test_middleware.tests);
+      ("Log", Test_log.tests);
+      ("Tls_config", Test_tls_config.tests);
+      ("Properties", Test_properties.tests);
+    ]