A Fast Fail REST API toolkit for Node.js. ergo (error or go) provides composable, stream-native middleware organized around the principle that a server should fail as early as possible -- before doing any expensive work -- through four ordered stages: Negotiation, Authorization, Validation, and Execution. Every behavior is backed by an IETF RFC or industry standard, not invented conventions.
- Fail Fast by design -- Errors are caught at the earliest possible stage. You never parse a request body for an unauthenticated user, and you never execute business logic on invalid input. This principle produces more robust software with fewer defects (Shore, "Fail Fast", IEEE Software 2004) and is a core reliability pillar in the AWS Well-Architected Framework.
- RESTful-first via RFCs -- Every middleware implements a specific RFC or standard. Content negotiation follows RFC 9110, error responses use RFC 9457 Problem Details, cookies follow RFC 6265. No proprietary patterns.
- Defense in depth -- Input validation happens as early as possible in the data flow per OWASP, and access control is enforced at each API endpoint before business logic. Authorization runs before body parsing, so unauthenticated requests never trigger expensive I/O.
- Secure by default -- Security headers ship with conservative defaults (
Content-Security-Policy: default-src 'none',X-Frame-Options: DENY). All user-input objects use null prototypes to prevent prototype pollution. Input parsing is bounded out of the box (query length, pair count, body size, decompressed size). The pipeline's design maps directly to the OWASP API Security Top 10 and REST Security Cheat Sheet. - Zero-overhead composition -- Synchronous middleware avoids microtask overhead entirely. Independent middleware within a stage run concurrently. The pipeline is a single function call with no framework runtime.
- Benchmarked -- Performance is measured, not claimed. ergo is tested against Fastify, Express, Hono, and Koa across 9 scenarios in Docker-isolated, CPU-pinned environments with statistical rigor (3 trials per combination, coefficient of variation analysis).
Every API request passes through exactly four stages, in order:
Request
|
+- Stage 1: Negotiation Parse and inspect the request.
| logger() -> [ cors() | accepts() | cookie() | url() ]
|
+- Stage 2: Authorization Authenticate user, verify request integrity.
| [ authorization() | csrf() ]
|
+- Stage 3: Validation Parse and validate the request body.
| body() . validate()
|
+- Stage 4: Execution Run the handler and send the response.
timeout() . compress() . [your route logic] . send()
Stages run serially. If any middleware throws, the pipeline stops immediately and the error handler runs. Independent middleware within a stage are parallelizable (shown with |).
npm install @centralping/ergoRequires Node.js >= 22. Also works on Deno 2.x and Bun 1.x via their Node.js compatibility layers (see Runtime Support).
import {createServer} from 'node:http';
import {compose, handler, logger, cors, authorization, body} from '@centralping/ergo';
const pipeline = compose(
logger(),
cors(),
authorization({strategies: [{type: 'Bearer', authorizer: (_, token) =>
token === 'my-token' ? {authorized: true, info: {uid: 1}} : {}
}]}),
body(),
(req, res, acc) => ({response: {body: {user: acc.auth, data: acc.body.parsed}}})
);
createServer(handler(pipeline)).listen(3000);TypeScript
import {createServer} from 'node:http';
import {compose, handler, logger, cors, authorization, body} from '@centralping/ergo';
const pipeline = compose(
logger(),
cors(),
authorization({strategies: [{
type: 'Bearer' as const,
authorizer: (_: Record<string, string>, token: string) =>
token === 'my-token' ? {authorized: true, info: {uid: 1}} : {authorized: false}
}]}),
body(),
(req, res, acc: {auth: {uid: number}; body: {parsed: unknown}}) =>
({response: {body: {user: acc.auth, data: acc.body.parsed}}})
);
createServer(handler(pipeline)).listen(3000);Note: The
accannotation on the execute handler is needed because standalonecompose()cannot fully infer accumulator types when response-only middleware (likecors()) is interleaved with domain-producing middleware. For declarative routing with fully inferred accumulator types — no annotations needed — see@centralping/ergo-router'sdefineGetanddefinePosthelpers.
Built-in middleware carries its own accumulator path — compose it as a bare function call. {fn, setPath} config objects remain available for custom middleware that needs to declare an accumulator key.
| Middleware | Description | Standard |
|---|---|---|
logger() |
Request ID + structured request/response logging | -- |
tracing() |
OpenTelemetry distributed tracing with W3C Trace Context propagation | W3C Trace Context |
cors() |
CORS preflight and simple request handling | Fetch Standard |
accepts() |
Content negotiation (type, encoding, language) | RFC 9110 §12.5 |
cookie() |
Cookie parsing with Set-Cookie builder | RFC 6265 |
url() |
URL and query string parsing | -- |
paginate() |
Offset and cursor pagination with RFC 8288 Link headers | RFC 8288 |
authorization() |
Bearer / Basic auth with pluggable strategies | RFC 6750, RFC 7617 |
csrf() |
Double-submit cookie CSRF protection | OWASP CSRF Prevention |
body() |
JSON, multipart/form-data, URL-encoded parsing | RFC 7578 |
validate() |
JSON Schema validation via AJV | -- |
idempotency() |
Idempotency-Key header for safe request retries | draft-ietf-httpapi-idempotency-key-header |
timeout() |
Request timeout with automatic 408/504 | -- |
compress() |
Content-Encoding negotiation (gzip, deflate, br) | RFC 9110 §12.5.3 |
handler() |
Pipeline executor with error normalization and response dispatch | -- |
send() |
Response serialization, ETag, conditional requests, Problem Details errors | RFC 9110, RFC 9457 |
prefer() |
Prefer header parsing and response | RFC 7240 |
precondition() |
428 Precondition Required enforcement | RFC 6585 §3 |
rateLimit() |
Sliding-window rate limiting with 429 responses | RFC 6585 §4 |
securityHeaders() |
HSTS, CSP, X-Content-Type-Options, etc. | RFC 6797 |
cacheControl() |
Cache-Control header management | RFC 9111 |
jsonApiQuery() |
JSON:API query parameter validation | JSON:API |
See the full API reference for detailed options and examples.
| RFC / Standard | Description | ergo Feature |
|---|---|---|
| RFC 9110 | HTTP Semantics | send() conditional requests, ETag, content negotiation |
| RFC 9457 | Problem Details for HTTP APIs | send() error responses, httpErrors utility |
| RFC 9111 | HTTP Caching | cacheControl() |
| RFC 9205 | Building Protocols with HTTP (BCP 56) | Overall API design philosophy |
| RFC 7240 | Prefer Header for HTTP | prefer() |
| RFC 8288 | Web Linking | lib/link.js pagination helpers |
| RFC 6585 | Additional HTTP Status Codes (428, 429) | precondition(), rateLimit() |
| RFC 6265 | HTTP State Management (Cookies) | cookie() |
| RFC 6750 | Bearer Token Usage | authorization() |
| RFC 7617 | Basic HTTP Authentication | authorization() |
| RFC 7578 | multipart/form-data | body() |
| RFC 6797 | HTTP Strict Transport Security | securityHeaders() |
| OWASP API Security Top 10 | Aligned with top API security risks | Pipeline stage ordering, rateLimit(), securityHeaders(), input bounding |
| OWASP REST Security | Aligned with REST security best practices | Auth enforcement, input validation, security headers, error redaction |
ergo is designed for Node.js and uses node:http, node:stream, node:zlib, and node:crypto at its boundaries. However, both Deno 2.x and Bun 1.x provide extensive Node.js compatibility layers that allow ergo to run without modification.
| Runtime | Version | Unit Tests | Contract Tests | Status |
|---|---|---|---|---|
| Node.js | 22, 24 | 100% | 100% | Primary target |
| Deno | 2.x | 96.7% | 100% | Compatible via node:* compat |
| Bun | 1.x | 99.4% | 100% | Compatible via node:* compat |
Known gaps on alternative runtimes:
- OpenTelemetry SDK (Deno):
@opentelemetry/sdk-trace-nodeunit tests fail because the SDK is Node.js-specific. The tracing middleware works correctly (contract tests pass); only SDK-internal unit test assertions are affected. process.emitWarning(Bun): Thehttp/validatemiddleware's developer-experience warnings emit correctly at runtime, but Bun'sprocess.on('warning')listener support differs from Node.js, causing 5 unit test assertions to fail.- Timer precision (both): One
MemoryStoretiming test inlib/rate-limithas microsecond-level sensitivity that can fail across all runtimes under load.
ergo's pipeline core (compose, compose-with, all utils/iterables) has zero node:* imports and is fully portable. The coupling to Node.js APIs concentrates in 6 boundary files: handler.js, send.js, body.js, compress.js, logger.js, and timeout.js.
CI runs the full test suite on Deno and Bun alongside Node.js. These jobs use continue-on-error and are informational rather than required checks.
npm install
npm test # lint + format check + tests with coverage
npm run test:watch # watch mode
npm run lint # ESLint
npm run format # PrettierMIT © 2019-present Jason Cust