hono 4.13.2: Compose nested sub-routers with onion middleware context propagation and centralized error handling in Hono

# Hono Nested Routing, Onion Middleware, and Error Handling

## Prior Findings

A search for known solutions on the target package returned sample `sha256:4119fb31a4aae36adedb382471bf336dc173784bfa20d638562f477ab0d9702c`, which verified basic route definitions (`app.get`, `app.post`) and simple parameter parsing with `c.req.param`.

This sample proves a distinct set of behaviors: multi-level route composition with `app.route`, context state propagation with `c.set` and `c.get` across nested routers, onion middleware execution order with downstream header mutations, and centralized error handling with `app.onError` and `HTTPException`.

## Pinned Release

- `hono`: `4.13.2` (pinned exactly in `package.json` and `package-lock.json`)

## Observed Behaviors

1. **Onion Middleware Lifecycle**:
   - Middleware registered on the root router with `app.use('*', async (c, next) => { ... await next(); ... })` executes before sub-routers and handlers.
   - Code before `await next()` sets context variables (`c.set('traceId', ...)`).
   - Code after `await next()` executes after handlers and nested middleware finish, enabling post-downstream response header modifications (`c.header(...)`).

2. **Hierarchical Route Composition & Parameter Extraction**:
   - Sub-routers mounted via `app.route('/api', api)` inherit context variables set by outer middleware.
   - Handlers in mounted sub-routers extract multi-segment parameters (e.g., `/catalog/:categoryId/:itemId`) via `c.req.param('categoryId')` and `c.req.param('itemId')` while simultaneously accessing inherited context variables via `c.get('traceId')`.

3. **Centralized Error Handling**:
   - When handlers in sub-routers throw `HTTPException`, root `app.onError` catches the exception without unhandled rejections.
   - Handlers in `app.onError` access context variables set during earlier middleware execution and return structured JSON responses with the appropriate HTTP status code.

4. **In-Memory Request Dispatch**:
   - Requests dispatched via `app.request('http://localhost/...')` run the full middleware and routing pipeline in-memory using standard Web Request and Response semantics.

{"case":{"caseId":"case:sha256:3a0217c6f4d0419bbb85ea7c0c0db880733e37401fcf3d53a69bd520441741a3","contract":["Root onion middleware intercepts nested sub-app routes, propagates context variables set with c.set() to downstream handlers, and mutates response headers after await next().","Multi-segment path parameters within mounted sub-routers are extracted via c.req.param() alongside inherited context variables.","Centralized app.onError catches HTTPException instances thrown in nested routes and returns custom status codes with preserved context state.","Unmatched routes traverse outer onion middleware and return 404 with middleware-injected response headers."],"goal":"Compose nested sub-routers with onion middleware context propagation and centralized error handling in Hono","kind":"HOW","packages":["pkg:npm/hono@4.13.2"],"schemaVersion":1,"symbols":["Hono","c.set","c.get","app.route","app.onError"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","ecosystem":"npm","executionContext":"node","language":"node","os":"linux","packageManager":"npm","runtime":"node","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/hono@4.13.2"],"schemaVersion":1,"symbols":["Hono","c.set","c.get","app.route","app.onError"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-hono-version-depth",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-hono-version-depth",
      "version": "1.0.0",
      "dependencies": {
        "hono": "4.13.2"
      }
    },
    "node_modules/hono": {
      "version": "4.13.2",
      "resolved": "https://registry.npmjs.org/hono/-/hono-4.13.2.tgz",
      "integrity": "sha512-JydRilDRkYBQMt9qR9U92mXxmbGqsqSn/IKOrh4e7/gEbn+0zSr8igTu0obwJoNGN4sez28DIql7FBHWydoJpA==",
      "license": "MIT",
      "engines": {
        "node": ">=16.9.0"
      }
    }
  }
}

{
  "name": "sample-hono-version-depth",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "dependencies": {
    "hono": "4.13.2"
  }
}

import { Hono } from 'hono';
import { HTTPException } from 'hono/http-exception';

export function createApp() {
  const app = new Hono();

  // Root onion middleware
  app.use('*', async (c, next) => {
    c.set('traceId', 'req-trace-42');
    c.set('startedAt', 1000);

    await next();

    c.header('X-Trace-Id', c.get('traceId'));
    c.header('X-Pipeline-Stage', 'completed');
  });

  // Sub-router for API resources
  const api = new Hono();

  api.use('*', async (c, next) => {
    c.set('apiScope', 'v1');
    await next();
  });

  api.get('/catalog/:categoryId/:itemId', (c) => {
    const categoryId = c.req.param('categoryId');
    const itemId = c.req.param('itemId');
    const traceId = c.get('traceId');
    const apiScope = c.get('apiScope');

    return c.json({
      categoryId,
      itemId,
      traceId,
      apiScope,
      ok: true,
    }, 200);
  });

  api.get('/protected-action', () => {
    throw new HTTPException(401, { message: 'Unauthorized action' });
  });

  // Mount sub-router under /api prefix
  app.route('/api', api);

  // Centralized error handler
  app.onError((err, c) => {
    const traceId = c.get('traceId') ?? 'unknown';
    if (err instanceof HTTPException) {
      return c.json({
        error: err.message,
        status: err.status,
        traceId,
      }, err.status);
    }
    return c.json({ error: 'Internal error', traceId }, 500);
  });

  return app;
}

import { strict as assert } from 'node:assert';
import { createApp } from '../src/index.mjs';

const app = createApp();

// 1. Nested sub-app route with onion middleware and context propagation
const successRes = await app.request('http://localhost/api/catalog/electronics/laptop-99');
assert.equal(successRes.status, 200);
assert.equal(successRes.headers.get('x-trace-id'), 'req-trace-42');
assert.equal(successRes.headers.get('x-pipeline-stage'), 'completed');

const successBody = await successRes.json();
assert.deepEqual(successBody, {
  categoryId: 'electronics',
  itemId: 'laptop-99',
  traceId: 'req-trace-42',
  apiScope: 'v1',
  ok: true,
});

// 2. Centralized error handling for nested sub-app HTTPException
const errorRes = await app.request('http://localhost/api/protected-action');
assert.equal(errorRes.status, 401);
assert.equal(errorRes.headers.get('x-trace-id'), 'req-trace-42');

const errorBody = await errorRes.json();
assert.deepEqual(errorBody, {
  error: 'Unauthorized action',
  status: 401,
  traceId: 'req-trace-42',
});

// 3. Unmatched route passes through outer onion middleware and returns 404
const notFoundRes = await app.request('http://localhost/api/unknown-endpoint');
assert.equal(notFoundRes.status, 404);
assert.equal(notFoundRes.headers.get('x-trace-id'), 'req-trace-42');
assert.equal(notFoundRes.headers.get('x-pipeline-stage'), 'completed');

console.log('CONTRACT PASS: nested sub-app routing, onion middleware, and error handling verified');