Sub-Routers

Problem

You are building a multi-resource API where different route groups need different auth strategies, middleware defaults, or rate limits. Putting everything on a single router forces you to override config on every route — violating DRY and obscuring the group-level intent.

Solution

Basic Mounting

Create a sub-router with its own defaults and mount it at a prefix:

Standalone

import {compose, authorization} from '@centralping/ergo';

// Each group composes its own pipeline independently
const adminPipeline = compose(
  authorization({
    strategies: [{type: 'Basic', authorizer: verifyAdmin}],
  }),
  (req, res, acc) => ({
    response: {body: {admin: true}},
  }),
);

ergo-router

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

const adminRouter = createRouter({
  defaults: {
    authorization: {
      strategies: [{type: 'Basic', authorizer: verifyAdmin}],
    },
  },
});

adminRouter.get('/dashboard', {execute: getDashboard});
adminRouter.get('/users', {execute: listAllUsers});

const router = createRouter({transport: {/* ... */}});
router.mount('/admin', adminRouter);
// GET /admin/dashboard, GET /admin/users — both require Basic auth

Per-Group Auth

Different route groups use different authentication — admin routes require Basic, user routes require Bearer, and public routes skip auth entirely:

Standalone

import {compose, authorization} from '@centralping/ergo';

const adminPipeline = compose(
  authorization({
    strategies: [{type: 'Basic', authorizer: verifyAdmin}],
  }),
  (req, res, acc) => ({
    response: {body: {role: 'admin'}},
  }),
);

const userPipeline = compose(
  authorization({
    strategies: [{type: 'Bearer', authorizer: verifyJwt}],
  }),
  (req, res, acc) => ({
    response: {body: {userId: acc.auth.user.id}},
  }),
);

const publicPipeline = compose(
  (req, res, acc) => ({
    response: {body: {status: 'healthy'}},
  }),
);

ergo-router

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

const adminRouter = createRouter({
  defaults: {
    authorization: {
      strategies: [{type: 'Basic', authorizer: verifyAdmin}],
    },
  },
});
adminRouter.get('/stats', {execute: getStats});

const usersRouter = createRouter({
  defaults: {
    authorization: {
      strategies: [{type: 'Bearer', authorizer: verifyJwt}],
    },
  },
});
usersRouter.get('/me', {execute: getMe});
usersRouter.patch('/me', {
  validate: {body: updateUserSchema},
  execute: updateMe,
});

const publicRouter = createRouter();
publicRouter.get('/health', {
  authorization: false,
  execute: (req, res, acc) => ({
    response: {body: {status: 'ok'}},
  }),
});

const router = createRouter({transport: {/* ... */}});
router
  .mount('/admin', adminRouter)
  .mount('/users', usersRouter)
  .mount('/public', publicRouter);

Shared Defaults vs. Isolation

Child router defaults do not merge with parent defaults. Each sub-router’s routes use only the defaults they were registered with:

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

const parent = createRouter({
  defaults: {
    accepts: {types: ['application/json']},
    timeout: {ms: 5000},
  },
});

const child = createRouter({
  defaults: {
    authorization: {strategies: [bearerStrategy]},
  },
});

child.get('/items', {execute: listItems});
parent.mount('/api', child);
// GET /api/items has authorization (from child defaults)
// but does NOT have accepts or timeout (from parent defaults)

To intentionally share defaults between parent and child, spread them:

const sharedDefaults = {
  accepts: {types: ['application/json']},
  timeout: {ms: 5000},
};

const parent = createRouter({
  defaults: sharedDefaults,
  transport: {/* ... */},
});

const child = createRouter({
  defaults: {
    ...sharedDefaults,
    authorization: {strategies: [bearerStrategy]},
  },
});

Per-Group Rate Limiting

Different sub-routers can set different rateLimit defaults to enforce per-group limits at the pipeline level:

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

const publicRouter = createRouter({
  defaults: {
    rateLimit: {max: 100, windowMs: 60_000},
  },
});
publicRouter.get('/search', {execute: search});

const premiumRouter = createRouter({
  defaults: {
    authorization: {strategies: [apiKeyStrategy]},
    rateLimit: {max: 1000, windowMs: 60_000},
  },
});
premiumRouter.get('/search', {execute: search});

const router = createRouter({
  transport: {
    rateLimit: {max: 10_000, windowMs: 60_000},
  },
});
router
  .mount('/v1', publicRouter)
  .mount('/premium', premiumRouter);

Proxy-aware rate limiting

When rate limiting behind a reverse proxy, provide a custom keyGenerator so each client gets its own rate-limit bucket instead of sharing the proxy’s IP. See the rate-limit middleware guide — Proxy Awareness for the pattern and security caveats.

Transport vs. pipeline rate limiting

Transport-level rateLimit (in the parent’s transport config) is a global limit applied to every request before routing. Pipeline-level rateLimit (in defaults) is per-route and runs inside the pipeline after routing. They serve different purposes — transport protects the server; pipeline protects individual resources. Both can be active on the same request — a request that passes the transport limit can still be rejected by a stricter pipeline limit on a specific route.

Complete Multi-Resource API

A practical example combining transport on the parent, per-group defaults on children, and mount chaining:

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

// --- Sub-routers with per-group concerns ---

const projectsRouter = createRouter({
  defaults: {
    authorization: {strategies: [bearerStrategy]},
    accepts: {types: ['application/json']},
  },
});
projectsRouter.get('/', {execute: listProjects});
projectsRouter.post('/', {
  validate: {body: projectSchema},
  execute: createProject,
});
projectsRouter.get('/:id', {execute: getProject});

const adminRouter = createRouter({
  defaults: {
    authorization: {
      strategies: [{type: 'Basic', authorizer: verifyAdmin}],
    },
    accepts: {types: ['application/json']},
  },
});
adminRouter.get('/users', {execute: listAllUsers});
adminRouter.delete('/users/:id', {execute: deleteUser});

const healthRouter = createRouter();
healthRouter.get('/', {
  authorization: false,
  execute: (req, res, acc) => ({
    response: {body: {status: 'ok', ts: Date.now()}},
  }),
});

// --- Parent router with transport ---

const router = createRouter({
  transport: {
    requestId: true,
    security: {hsts: {maxAge: 31_536_000}},
    cors: {origin: 'https://app.example.com'},
    rateLimit: {max: 10_000, windowMs: 60_000},
  },
  strictPatch: true,
  strictBody: true,
});

router
  .mount('/projects', projectsRouter)
  .mount('/admin', adminRouter)
  .mount('/health', healthRouter);

Explanation

Copy Semantics

router.mount(prefix, subRouter) copies all currently registered routes from the child into the parent’s dispatcher with the prefix prepended to each path. This is a one-time copy, not a live delegation — the parent and child are independent after mounting.

This means:

1. Order matters — register all routes on the child before calling mount() on the parent
2. No runtime delegation — the parent’s find-my-way dispatcher handles all matching directly (no double-dispatch overhead)
3. Pipelines are frozen — each child route’s pipeline was built at addRoute() time using the child’s defaults; mounting does not re-resolve

Isolation Summary

Aspect	Scope	Who Controls It
defaults (accepts, authorization, validate, etc.)	Child	Each sub-router’s routes use the defaults they were registered with
router.use() middleware	Child	Baked into child pipelines at registration time
send / catchHandler	Child	Route options from child’s config
Transport (CORS, security headers, rate limit, request ID)	Parent	Runs before routing at parent dispatch level
strictPatch / strictBody	Parent	Content-Type enforcement at parent dispatch
REST compliance (405, HEAD, OPTIONS)	Parent	Applied to the merged route table

Related

• Config Resolution — how route values override defaults
• Application Middleware — router.use() scoping
• Multi-Auth Strategies — per-route auth overrides within a single router