hcs#

HTTP library for OCaml 5+ built on Eio. Supports HTTP/1.1, HTTP/2, and WebSocket.

Modules#

Module	Description
Client	HTTP client with auto-protocol selection and connection pooling
Server	HTTP server with multi-domain parallelism
Router	Radix trie router with path parameters, scopes, and per-route plugs
Plug	Phoenix-style middleware composition
Pipeline	Reusable plug collections for route scopes
Endpoint	Global plug entry point, builds handler from plugs + router
Websocket	WebSocket client and server (RFC 6455)
Sse	Server-Sent Events
Pubsub	Lock-free topic-based pub/sub messaging
Channel	WebSocket channel abstraction with topic subscriptions
Pool	Connection pool data structure
Stream	Sync and async streaming
Codec	Codec signature for serialization
Tls_config	TLS configuration
Log	Structured logging
Request	Request helpers
Response	Response helpers
Multipart	Multipart form data parsing
Http	Request builder DSL
H1_client	HTTP/1.1 client
H2_client	HTTP/2 client
H1_server	HTTP/1.1 server
H2_server	HTTP/2 server

Plug System#

Plug provides Phoenix-style middleware composition for request/response pipelines.

Available Plugs#

Plug	Description
`Plug.Logger`	Request/response logging
`Plug.Request_id`	Add unique request ID header
`Plug.Head`	Convert HEAD to GET, strip body
`Plug.Timeout`	Request timeout with cancellation
`Plug.Recover`	Exception recovery with custom handler
`Plug.Cors`	CORS headers
`Plug.Rate_limit`	Token bucket rate limiting
`Plug.Etag`	ETag generation and validation
`Plug.Cache_control`	Cache-Control headers
`Plug.Static`	Static file serving
`Plug.Compress`	Gzip/zstd response compression
`Plug.Circuit_breaker`	Circuit breaker pattern
`Plug.Retry`	Retry with backoff
`Plug.Basic_auth`	HTTP Basic authentication
`Plug.Csrf`	CSRF token validation
`Plug.Negotiate`	Content negotiation (Accept header parsing)
`Plug.Token`	Signed/encrypted token generation and validation
`Plug.Session`	Cookie-based session management

Usage#

open Hcs

let pipeline =
  Plug.Logger.create ~clock logger
  @> Plug.Compress.create ()
  @> Plug.Timeout.create ~clock 30.0
  @> Plug.Cors.create ()
  @> Plug.identity

let handler = Plug.apply pipeline my_handler

Plugs compose left-to-right with @>. The pipeline wraps my_handler, executing plugs in order for requests and reverse order for responses.

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:

# 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:

# 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#

opam install . --deps-only
dune build

Running Tests#

dune test

Dependencies#

eio - Structured concurrency
h1 - HTTP/1.1 parsing
h2 - HTTP/2 parsing
tls-eio - TLS with Eio
ca-certs - System CA certificates
uri - URI parsing
climate - CLI parsing