A REST-compliant router for ergo with strict Fast Fail semantics. Provides path matching via find-my-way, automatic REST compliance (405+Allow, HEAD, OPTIONS, PATCH enforcement), transport-level security, and seamless integration with ergo's composable middleware pipeline.

Why ergo-router?

• Automatic REST compliance -- 405 Method Not Allowed with Allow header, HEAD falls back to GET, OPTIONS auto-responds with allowed methods, PATCH Content-Type enforcement. All per RFC 9110.
• Transport-level security -- Security headers, CORS, rate limiting, and request ID generation run before routing, ensuring every response (including errors) is protected.
• Declarative pipeline assembly -- Define routes with a config object; the router assembles the full Fast Fail pipeline (negotiation, auth, validation, execution) from ergo middleware automatically.
• Graceful shutdown -- Built-in support for draining in-flight requests on SIGTERM/SIGINT.

Request Dispatch Flow

Incoming Request
  |
  +- 1. Transport Layer (every request)
  |    +- Request ID generation (response header)
  |    +- Security headers
  |    +- Rate limiting (429 short-circuit)
  |    +- CORS (preflight 204 short-circuit)
  |
  +- 2. REST Semantics
  |    +- OPTIONS -> 204 + Allow header
  |    +- PATCH Content-Type enforcement -> 415
  |    +- HEAD -> falls back to GET handler
  |    +- Route matching (find-my-way)
  |    +- 405 + Allow or 404
  |
  +- 3. Application Pipeline
       +- Route params seeded in accumulator
       +- Stage 1: Negotiation
       +- Stage 2: Authorization
       +- Stage 3: Validation
       +- Stage 4: Execution
       +- Implicit send()

Every early exit (429, 403, 404, 405, 415, preflight 204) includes security headers and request ID automatically.

Installation

npm install @centralping/ergo-router @centralping/ergo find-my-way

Requires Node.js >= 22. @centralping/ergo is a peer dependency.

Quick Start

import createRouter from '@centralping/ergo-router';

const router = createRouter({
  transport: {
    requestId: {},
    security: {},
    cors: {origin: 'https://myapp.com'}
  },
  defaults: {
    accepts: {types: ['application/json']},
    timeout: {ms: 30000}
  }
});

router.get('/users/:id', {
  execute: (req, res, acc) => ({body: {id: acc.route.params.id}})
});

router.post('/users', {
  validate: {body: {type: 'object', properties: {name: {type: 'string'}}, required: ['name']}},
  execute: (req, res, acc) => ({statusCode: 201, body: acc.body.parsed})
});

router.listen(3000, () => console.log('Listening on :3000'));

API Overview

createRouter(options?)

Creates a new router instance with optional transport and default middleware configuration.

| Option | Description | |---|---| | transport.requestId | Request ID generation config | | transport.security | Security headers (HSTS, CSP, etc.) | | transport.cors | CORS configuration | | transport.rateLimit | Rate limiting (sliding window) | | defaults.* | Default middleware options applied to all routes |

Route Methods

router.get(path, config)
router.post(path, config)
router.put(path, config)
router.patch(path, config)
router.delete(path, config)

Route Config

| Key | Description | Standard | |---|---|---| | execute | Route handler function (required) | -- | | validate | JSON Schema for body/query validation | -- | | accepts | Content negotiation override | RFC 9110 §12.5 | | authorization | Auth strategy override | RFC 6750, RFC 7617 | | timeout | Request timeout override | -- | | precondition | 428 enforcement | RFC 6585 §3 | | rateLimit | Per-route rate limit override | RFC 6585 §4 |

graceful(server, options?)

Graceful shutdown helper. Stops accepting new connections and drains in-flight requests.

import createRouter, {graceful} from '@centralping/ergo-router';
const router = createRouter({...});
const server = router.listen(3000);
graceful(server);

See the full API reference for detailed options and examples.

Standards Compliance

| RFC / Standard | Description | ergo-router Feature | |---|---|---| | RFC 9110 | HTTP Semantics | 405+Allow, HEAD/OPTIONS/PATCH enforcement | | RFC 9457 | Problem Details for HTTP APIs | Structured error responses | | RFC 6797 | HTTP Strict Transport Security | Transport security headers | | RFC 6585 | Additional HTTP Status Codes | Rate limiting (429) | | Fetch Standard | CORS Protocol | Transport CORS handling |

Documentation

• Getting Started
• API Reference
• Architecture & Design

Development

npm install
npm test            # lint + format check + tests with coverage
npm run test:watch  # watch mode
npm run lint        # ESLint
npm run format      # Prettier

License

MIT © 2019-present Jason Cust