health

health(config?): RouteConfig

Defined in: src/core/health.ts:76

Create a health check route for liveness and upstream probing.

Returns a RouteConfig (not a Policy) — add it directly to the gateway’s routes array. Without upstream probes, returns a simple { status: "healthy" } response. With probes, performs concurrent HEAD requests (5s timeout each) and reports aggregate status:

• "healthy" — all probes passed
• "degraded" — some probes failed
• "unhealthy" — all probes failed (returns 503)

Parameters

config?

HealthConfig

Endpoint path, upstream probe URLs, and status detail toggle. All fields optional.

Returns

RouteConfig

A RouteConfig for a GET health endpoint.

Security

Enabling includeUpstreamStatus: true causes the response to include the URLs and availability status of internal upstream services. On public-facing endpoints this leaks internal service topology, which can aid attackers in reconnaissance (identifying internal hostnames, ports, and service availability patterns). Restrict health routes that expose upstream status to internal or admin-only paths, or protect them with an authentication policy.

Example

import { createGateway } from "@homegrower-club/stoma";
import { health } from "@homegrower-club/stoma/policies";

createGateway({
  routes: [
    // Simple liveness check at /health
    health(),

    // Probe upstreams with detailed status at /healthz
    health({
      path: "/healthz",
      upstreamProbes: [
        "https://api.example.com/health",
        "https://auth.example.com/health",
      ],
      includeUpstreamStatus: true,
    }),

    // ...other routes
  ],
});