handler

The HTTP request handler factory for ergo’s two-accumulator model. Creates domain and response accumulators per request, runs the composed pipeline, catches unexpected errors, and calls send() exactly once. This is the standalone equivalent of ergo-router’s auto-wrap.

Pipeline stage: Execution (wraps the entire pipeline)

Import

import { handler } from "@centralping/ergo";

Arguments

Argument	Type	Description
`pipeline`	`function`	Required. Composed middleware pipeline

Options

Option	Type	Default	Description
`debug`	`boolean`	`false`	Enable pipeline debug tracing. When true, `responseAcc._trace` is initialized with `{steps, breakAt}` before the pipeline runs. On error responses (≥ 400), `_trace` appears as an RFC 9457 extension member.
`redactErrors`	`boolean`	`true`	Control whether caught 5xx exception messages appear in the RFC 9457 response `detail` field. When `true`, `detail` is set to generic status text. When `false`, `err.message` is passed through for 5xx only — 4xx always uses generic text. Stack traces are never exposed. Only set to `false` in development.
`prettify`	`boolean`	`false`	Pretty-print JSON output (forwarded to send)
`vary`	`string[]`	`['Accept']`	Vary header values to append (forwarded to send)
`etag`	`boolean`	`true`	Generate ETags and evaluate conditional headers (forwarded to send)
`prefer`	`boolean`	`false`	Read `domainAcc.prefer` for RFC 7240 `return=minimal` / `return=representation` (forwarded to send)
`paginate`	`boolean`	`false`	Read `domainAcc.paginate` and `responseAcc.paginate` to auto-generate RFC 8288 Link headers and `X-Total-Count` for paginated responses (forwarded to send)
`envelope`	`boolean \| function`	`false`	Wrap 2xx Object bodies in a response envelope (forwarded to send)
`errorFormatter`	`function`	—	Custom error body formatter for 4xx/5xx responses. Receives the RFC 9457 Problem Details object and `{requestId, statusCode, method}` context. Return value becomes the response body as `application/json` instead of `application/problem+json`. (forwarded to send)

Return Value

Returns an async handler (req, res) => void suitable for http.createServer().

Error Handling

Sets responseAcc.statusCode = 500 for uncaught pipeline errors (unless a timeout or earlier pipeline break already set the status)
Attaches instance from the X-Request-Id response header
Emits error on res if error listeners are present
If send() itself throws: res.statusCode = 500; res.end()

Error Responses

Status	Condition
500 Internal Server Error	Uncaught pipeline error (detail is redacted for security)

import http from "node:http";
import {
  handler, compose, logger, authorization, body,
} from "@centralping/ergo";

const pipeline = compose(
  {fn: logger(), setPath: "log"},
  {fn: authorization({ strategies }), setPath: "auth"},
  {fn: body(), setPath: "body"},
  (req, res, acc) => ({
    response: {
      body: processRequest(acc),
      statusCode: 200,
    },
  }),
);

const server = http.createServer(
  handler(pipeline, { debug: true, prettify: true }),
);
server.listen(3000);

// ergo-router uses auto-wrap internally — you don't call
// handler() directly. The router's handle() method creates
// the two-accumulator wrapper automatically.

import createRouter, { graceful } from "@centralping/ergo-router";

const router = createRouter();
router.get("/health", {
  execute: () => ({ response: { body: { ok: true } } }),
});

await graceful(router.handle(), { port: 3000 });

Custom Middleware — Writing middleware that fits ergo’s accumulator-based return-value contract
Debug Tracing — Finding which middleware rejected a request using pipeline debug mode

API Reference

See the auto-generated handler API docs.