suaveplan/openspec/archive/2026-05-26-api-router-hono/proposal.md

@suaveplan/api-router-hono — Hono-backed Router adapter

Package: @suaveplan/api-router-hono Status: PROPOSED Type: new-package Stage: 4 (Base adapters) — see umbrella openspec/changes/api-plugin-foundation/

Why

The plugin host needs a production-grade HTTP router. Hono is fast, Bun-native, has a mature middleware ecosystem, and supports streaming. This package implements the abstract Router contract from @suaveplan/api-router against Hono, including blue-green slot management so a plugin's route table can be swapped atomically during hot reload (design doc §8.1).

Per design doc §15 Stage 4: every adapter ships both a direct callable surface and a MessagePort-marshalled worker-proxy surface so it can serve trusted-tier and isolated/sandboxed-tier plugins from one codebase (§5.2a). The same conformance suite (runRouterConformance from §13.4) MUST pass against both surfaces — anything less is not shippable.

What changes

Net-new package depending on @suaveplan/api-router (contract), @suaveplan/api-types, @suaveplan/api-worker-rpc, @suaveplan/error, @suaveplan/logger, and hono as a peer dependency.

• ADDED: createHonoRouter(opts) — factory returning the direct in-process Router implementation backed by a Hono instance per blue-green slot.
• ADDED: createHonoRouterWorkerProxy(port, opts) — factory returning the proxy surface; calls marshall over a MessagePort to a host-side Hono instance via api-worker-rpc.
• ADDED: HonoRouterOptions — Zod-validated config (basePath, trustProxy, maxBodyBytes, streamingTimeoutMs, blue-green strategy: "swap-on-health" | "swap-immediately").
• ADDED: HonoBlueGreenSlot — internal BlueGreenSlot impl managing two Hono instances (blue + green) and an atomic pointer. In-flight requests complete on the old slot; new requests route to the new slot once health passes.
• ADDED: ROUTER_HONO_* error codes (e.g. ROUTER_HONO_BLUE_GREEN_SWAP_FAILED, ROUTER_HONO_SLOT_NOT_READY, ROUTER_HONO_DUPLICATE_ROUTE, ROUTER_HONO_INVALID_PATTERN).
• ADDED: ./testing subpath — re-exports runRouterConformance from @suaveplan/api-router/testing already bound to createHonoRouter; convenience for downstream tests.

Out of scope

• The abstract Router interface, conformance suite, and BlueGreenSlot contract — those live in api-router (Stage 1).
• HTTP server lifecycle (Bun.serve, address binding) — api-router-hono is a router only; api-host owns the listening socket.
• WebSocket upgrade — api-ws-bun Stage 7.
• OpenAPI integration — api-openapi Stage 8 consumes route metadata from this adapter via the Router contract.

Source mapping

Genesis-original. Source of design intent: docs/superpowers/specs/2026-05-13-api-plugin-foundation-design.md.

Requirement	Design doc section
Router contract implementation	§2.1, §6 (steps 1-2, 10)
Blue-green slot management	§8.1
Worker-proxy variant required	§5.2a
Streaming bypasses buffering	§6 (streaming bullet)
Conformance suite passes both surfaces	§5.2a, §13.4

Verification approach

• src/factory/create-hono-router.test.ts — direct-surface unit tests: route registration, dispatch, middleware ordering, streaming response.
• src/factory/create-hono-router.spec-conformance.test.ts — runs runRouterConformance("hono-direct", createHonoRouter) and asserts the full ~30 invariants pass.
• src/proxy/create-hono-router-worker-proxy.test.ts — proxy-surface unit tests over an in-process MessageChannel.
• src/proxy/create-hono-router-worker-proxy.spec-conformance.test.ts — runs runRouterConformance("hono-worker-proxy", makeProxyFactory) over a real Worker (or MessageChannel simulation) and asserts every invariant passes.
• src/blue-green/hono-blue-green-slot.test.ts — atomic swap, in-flight completion on old slot, health-gated cutover, swap rollback on health failure.
• tests/integration/integration.test.ts — booting createHonoRouter against a real Bun.serve listener and exercising the full request pipeline end-to-end.

Migration impact

None — additive only. No package consumes @suaveplan/api-router-hono yet.