56 lines
4.2 KiB
Markdown
56 lines
4.2 KiB
Markdown
# `@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.
|