health

README

health

Health endpoints for SSPUR HTTP services: liveness, readiness and startup probes for Kubernetes, load balancers and monitors, answering in the format of the IETF draft Health Check Response Format for HTTP APIs (application/health+json). Checks are data (a SQLite ping, an HTTP dependency with a timeout, a writable directory, a file that must exist, or a fixed observation), they run concurrently, a non-critical check that fails degrades the service to warn instead of fail, results can be cached for a while, and a draining switch turns readiness off during graceful shutdown. It covers what terminus (Node) and Spring Boot Actuator's health endpoints do.

Install

$ sspur add health

Example

use health.{Health}

fn api(req: Request) -> Response
= http.text(200, "hello")

fn setup(c: Db) -> Health
= health.health("notes") with version := some("3"), release_id := some("3.1.0"), readiness := [health.db_check("sqlite", c), health.non_critical(health.http_check("mailer", "http://127.0.0.1:1/health", 2000)), health.writable_check("uploads", "/tmp")]

// The real service: health endpoints in front of the API.
fn serve(c: Db) -> Unit ! net, log, db, fs, time, conc
= do
  h = setup(c)
  f = health.flags()
  paths = health.default_paths()
  http.serve_with(http.server(8080), req => health.routes(h, f, paths, req, api))

fn get(h: Health, f: health.Flags, path: Str) -> Response ! db, net, fs, time, conc
= health.routes(h, f, health.default_paths(), Request{method: "GET", url: path, headers: [], body: "", timeout_ms: 0, retries: 0, redirects: 0}, api)

fn main() -> Unit ! log, db, fail[DbErr], net, fs, time, conc
= do
  h = setup(db.open(":memory:"))
  f = health.flags()
  ready = get(h, f, "/health/ready")
  log("{ready.status} {ready.body}")
  health.start_draining(f)
  drained = get(h, f, "/health/ready")
  live = get(h, f, "/health/live")
  log("{drained.status} {drained.body}")
  log("{live.status} {live.body}")

Run as a dependent (health = { path = "..." }); the interpreter gives the same output apart from the timings:

$ sspur run main.ssp
200 {"status":"warn","version":"3","releaseId":"3.1.0","serviceId":"notes","checks":{"sqlite:responseTime":[{"componentType":"datastore","observedValue":0.427,"observedUnit":"ms","status":"pass","time":"2026-10-16T17:40:05.629Z"}],"mailer:responseTime":[{"componentId":"http://127.0.0.1:1/health","componentType":"component","observedValue":19.96,"observedUnit":"ms","status":"fail","time":"2026-10-16T17:40:05.629Z","output":"connect: Failed to connect to 127.0.0.1 port 1 after 0 ms: Couldn't connect to server"}],"uploads:writable":[{"componentId":"/tmp","componentType":"system","observedValue":true,"status":"pass","time":"2026-10-16T17:40:05.629Z"}]}}
503 {"status":"fail","version":"3","releaseId":"3.1.0","serviceId":"notes","output":"draining"}
200 {"status":"pass","version":"3","releaseId":"3.1.0","serviceId":"notes"}

The mailer is down, but it is not critical, so the service is warn and readiness still answers

1. Once draining, readiness answers 503 at once without running the checks, while liveness keeps

passing so the orchestrator doesn't restart a service that is shutting down.

Semantics

• Status codes: 200 for pass and warn, 503 for fail, as the draft recommends. Responses carry Cache-Control: no-cache, no-store, must-revalidate, and HEAD gets the status without a body. Other methods on a health path get 405 with Allow: GET, HEAD.
• Aggregation: the service status is the worst contribution of its checks. A failing check that is not critical contributes warn. A passing check with warn_ms that took longer contributes warn with the output slower than N ms.
• The started and draining state is a Flags value (an Atomic[Int] every handler shares), kept apart from the Health configuration so that stays a plain value. Readiness fails with the output starting until mark_started (new flags count as started; call mark_starting first if startup takes a while) and with draining after start_draining. Startup passes once started. Liveness runs only the liveness checks, which are usually none.
• Checks never raise: a database error, a refused connection, a timeout or an unexpected status is a fail observation with an output that says what happened (connect: ..., timeout: ..., unexpected status 500).
• Concurrency: each check runs as its own task, so a readiness request takes about as long as the slowest check. Bound HTTP checks with their timeout_ms.
• Caching: with_cache(h, ttl_ms) keeps the last liveness and readiness responses for ttl_ms in an in-memory SQLite database that every handler thread shares. Draining is never cached.
• Details: with details := false, responses carry only the status (and the output of a failure), so a public endpoint doesn't list the service's dependencies. Expose details on an internal port or path.
• Custom checks: compute an Observation in the handler and pass it as extra: req => health.readiness(h, f, [("queue:depth", my_queue_check())], req). (Checks themselves are data, not functions, because handler tasks can't share function values.)

API

Statuses and observations

Checks

The service

HTTP

Out of scope

• Disk space: the standard library has no statfs, and running df would add the proc capability to every health function of every dependent. Check free space with your own Static observation if you need it, or rely on the platform's disk alerts.
• Timeouts for database pings and custom checks (SQLite has its own 5 second busy timeout); only HTTP checks can be bounded.
• Consuming other services' health+json documents, and push-style reporting to a monitoring system.

License

MIT, see LICENSE.