Skip to content
Hypha Stack

Spindle

The Eio-native web framework for modern OCaml.

Source on GitHubDocumentationLatest: 0.9.0

About

Build typed APIs and web applications, simple to start and ready for production. Handlers are straight-line OCaml, and JSON is derived from your types and validated on the way in, with every mistake reported at once.

Your routes give you interactive OpenAPI docs, served by Scalar. Your types become your front end's schemas, Zod included, so a changed type changes both ends.

Multicore by design. Every HTTP requirement it meets is backed by a test, with secure defaults, bounded waits and clean shutdowns. Postgres, WebSockets, live updates, sessions, logging, traces and metrics are included.

HTTP and APIsData contractsData and persistenceObservabilityIdentity and access

Install

From Hypha's opam repository, on OCaml 5.5 or later:

opam repo add hypha https://github.com/hyphatech/opam-repository.git
opam install spindle

Then in your dune file:

(executable
 (name main)
 (libraries spindle eio_main)
 (preprocess (pps ppx_wiretype)))

In code

  1. A route: its method and path, what it reads and what it answers, typed from the records.

    open Spindle.Syntax
    
    type bill = {
      total : float; [@min 0.]
      tip : int; [@min 0] [@max 100]  (** percent *)
      people : int; [@min 1] [@max 50]
    }
    [@@deriving wiretype]
    
    type share = { each : float } [@@deriving wiretype]
    
    let split b =
      let total = b.total *. float (100 + b.tip) /. 100. in
      Ok { each = total /. float b.people }
    
    let routes =
      [
        Spindle.post
          Spindle.Path.(s "split")
          (Spindle.Returns.json share_json)
          (let+ b = Spindle.json bill_json in
           split b);
      ]
    
    let () =
      Spindle.Log.setup ();
      Eio_main.run @@ fun env ->
      Spindle.serve env (routes @ Spindle.Openapi.routes routes)
  2. Called. Interactive docs for every route are at /docs, generated from the same routes.

    $ curl localhost:8080/split --json '{"total": 90, "tip": 10, "people": 3}'
    {"each":33}

Under load

Plaintext

Spindle
78,800
Dream
51,800
NestJS
42,500
FastAPI
16,500

JSON

Spindle
61,200
Dream
46,800
NestJS
32,500
FastAPI
13,500

Sustained RPS on one core, request log on. Apple M4 Pro, Spindle 0.6.0, median of three runs.

Ontology

  • PageRouteis served by
  • QueryRoutecalls
  • FormClient schemais checked by
  • RouteRequestanswers
  • RouteResponsereturns
  • RefusalResponseis a
  • HandlerRouteserves
  • RouteData shapeis typed by
  • Client schemaData shapeprinted from
  • API specRouteprinted from
  • HandlerStatementruns
  • Connection poolDatabaseconnects to
  • TraceRequestfollows
  • SpanTraceis part of
  • SpanStatementrecords
  • MetricRequestcounts
  • LogRequestrecords
  • Health checkDatabasechecks
  • PermissionRouteguards
  • RequestSessioncarries
  • SessionIdentityproves
  • Rate limitRequestthrottles
  • Audit logRequestrecords
  • HandlerConfigreads
  • Feature flagHandlergates
  • HandlerCachereads
  • HandlerEventemits
  • WebhookRequestarrives as
  • HandlerFilestores

Build with Hypha.