feat: configurable external middleware pipeline

[mcarlson]

Summary

Adds a configurable middleware pipeline that lets users compose request/response transformations without forking the gateway. Builds on the external loading concept from #1563 with ordering guarantees, per-middleware config, and error reporting.

• Middleware are standard Hono middleware loaded from a directory and configured in conf.json
• Array order = execution order — first middleware is outermost (wraps everything downstream)
• Factory pattern — each file exports a function that receives config and returns Hono middleware
• Fail-fast startup — gateway refuses to start if any middleware is missing or fails to initialize
• Error attribution — runtime errors are prefixed with the middleware name for easy debugging

Config schema

{
  "middleware_dir": "./middleware",
  "middleware": [
    { "name": "request-logger", "config": { "verbose": true } },
    { "name": "cache-optimizer", "enabled": false }
  ]
}

Middleware authoring

// middleware/request-logger.js
module.exports = function(config) {
  return async (c, next) => {
    const start = Date.now();
    await next();
    console.log(`${c.req.method} ${c.req.path} → ${c.res.status} (${Date.now() - start}ms)`);
  };
};

Files changed

File	Purpose
src/types/middlewareConfig.ts	Config parser (middleware array, dir, enabled flag)
src/middlewares/external.ts	Loader: import factories, call with config, register in order
src/index.ts	Wire loader before hooks pipeline
conf.json	Add middleware_dir and middleware fields (empty by default)
examples/middleware/request-logger.js	Example middleware
src/types/__tests__/middlewareConfig.test.ts	Config parser tests (6 tests)
src/middlewares/__tests__/external.test.ts	Loader tests (7 tests)

Relationship to existing systems

Concern	Mechanism
HTTP-level (compression, CORS, auth)	Built-in Hono middleware
Request/response transformation	External middleware (this PR)
Content filtering, safety checks	Plugins/guardrails (hooks pipeline)

External middleware wraps the hooks pipeline — it runs before guardrails see the request and after they produce the response.

Limitations (v1)

• Node.js only — dynamic filesystem imports don't work on Workers
• No hot reload — restart gateway to change middleware config
• No per-request middleware selection — same pipeline for all requests

Test plan

• Config parser: empty config, valid config, disabled entries, CLI override, invalid entries (6 tests)
• Loader: ordering, config passing, missing file, factory error, empty entries, async factory, error wrapping (7 tests)
• Manual: add example middleware to conf.json, verify logs on startup and per-request

🤖 Generated with Claude Code