httpkit

Small, composable HTTP libraries for OCaml. Use checked HTTP values, incremental HTTP/1 codecs and a Sans-I/O engine independently, or add native Eio and Lwt adapters for streaming clients and servers.

Core has no dependencies beyond the OCaml standard library. Each adapter uses its runtime's native concurrency and cancellation model.

For outbound requests, try the experimental streaming HTTP/HTTPS client.

Start a separate application with the GitHub + SQLite/PostgreSQL guide. See validation status for passed checks and open issues.

Get started

Requires OCaml 5.5.0. To work from this repository, install mise, a C build toolchain and Git, then run these commands from the checkout:

mise trust
mise install opam
mise run setup

Setup provisions the compiler and locked dependencies locally through mise → opam → Dune. See development for toolchain details and dependency updates.

Try it with Eio

Run a complete HTTP client/server exchange over a local socket pair:

tools/dune-pkg exec ./examples/runtime/eio_example.exe

It prints Hello /. The Eio example owns the connection lifetimes with switches, sends a request, and collects the response. Both sides run in one process; no listening port is needed.

The server uses this pure handler:

open Httpkit_core

let handle request =
  let body = "Hello " ^ Target.to_string (Request.target request) ^ "\n" in
  let headers =
    Result.get_ok
      (Headers.of_list
         [ ("content-length", string_of_int (String.length body)) ])
  in
  Response.create ~status:Status.ok ~headers body

The executable links httpkit-transport-eio and eio_main; the handler needs only httpkit-core. This small example collects bodies; use the adapter's streaming operations for larger transfers and configure limits for your application.

Prefer Lwt? Run the equivalent example:

tools/dune-pkg exec ./examples/runtime/lwt_example.exe

Packages and documentation

Use httpkit-eio or httpkit-lwt for applications and httpkit-client-eio or httpkit-client-lwt for outbound requests. Add database, cookie, session, password and OIDC packages as needed. The core values, codecs, engine, router and middleware are independently usable; applications supply listeners and server-side TLS.

• Documentation index: guides organized by task.
• Package reference: every package, dependency boundary and entry module.
• Runnable examples: from in-memory exchanges to applications.
• Development: build, test and generate API documentation.

Status

Experimental; APIs may change. Local suites have passed, but broad internal rollout and public release are not yet signed off. Remaining work. See the security policy for reporting guidance.