63 lines
4.4 KiB
Markdown
63 lines
4.4 KiB
Markdown
# @suaveplan/api-router-hono — concrete Hono router adapter for the @suaveplan/api plugin system. Implements the abstract Router contract from @suaveplan/api-router on top of a Hono instance, including the HonoBlueGreenSlot atomic-flip primitive and bidirectional Middleware <-> Hono MiddlewareHandler adapters. Passes runRouterConformance.
|
|
|
|
Stage-4 concrete Hono router adapter for `@suaveplan/api`. Implements the abstract `Router` contract from `@suaveplan/api-router` on top of a Hono `Hono` instance and provides the matching `BlueGreenSlot` implementation for hot-reload.
|
|
|
|
<!-- begin:auto-docs -->
|
|
## Documentation tree
|
|
|
|
- [adapter](./src/adapter/adapter.md) — `HonoRouter` is The concrete `Router` adapter for the API plugin system. It implements every public method…
|
|
- [adapter](./src/adapter/adapter.md) — `HonoRouter` is The concrete `Router` adapter for the API plugin system. It implements every public method…
|
|
- [blue-green-slot](./src/blue-green-slot/blue-green-slot.md) — `HonoBlueGreenSlot` is the per-plugin atomic flip primitive backing hot-reload for a Hono-backed `Router`. It holds at…
|
|
- [blue-green-slot](./src/blue-green-slot/blue-green-slot.md) — `HonoBlueGreenSlot` is the per-plugin atomic flip primitive backing hot-reload for a Hono-backed `Router`. It holds at…
|
|
- [error-codes](./src/error-codes/error-codes.md) — This module defines the canonical, frozen error-code namespace `ROUTER_HONO.*` shared by every production path inside `…
|
|
- [error-codes](./src/error-codes/error-codes.md) — This module defines the canonical, frozen error-code namespace `ROUTER_HONO.*` shared by every production path inside `…
|
|
- [middleware-adapter](./src/middleware-adapter/middleware-adapter.md) — This module bidirectionally bridges the onion-model `Middleware` type from `@suaveplan/api-router` and Hono's n…
|
|
- [middleware-adapter](./src/middleware-adapter/middleware-adapter.md) — This module bidirectionally bridges the onion-model `Middleware` type from `@suaveplan/api-router` and Hono's n…
|
|
- [pipeline](./src/pipeline/pipeline.md) — `@suaveplan/api-host`'s request pipeline drives its routing through a `PipelineRouter`-shaped seam — `match(method, url…
|
|
- [pipeline](./src/pipeline/pipeline.md) — `@suaveplan/api-host`'s request pipeline drives its routing through a `PipelineRouter`-shaped seam — `match(method, url…
|
|
<!-- end:auto-docs -->
|
|
|
|
## What it ships
|
|
|
|
- `HonoRouter` / `createHonoRouter()` — concrete `Router` adapter that subclasses the abstract base, mirrors every verb registration onto a private Hono app, and exposes `getHonoApp()` for ops integrations.
|
|
- `HonoBlueGreenSlot` — `BlueGreenSlot` impl with atomic flip, in-flight counter, AbortSignal-aware `dispose(timeoutMs)`.
|
|
- `toHonoMiddleware` / `fromHonoMiddleware` — bidirectional bridge between the onion-model `Middleware` and Hono's `MiddlewareHandler`.
|
|
- `ROUTER_HONO_CODES` / `RouterHonoError` — stable error-code registry (`ROUTER_HONO.HONO_INTERNAL_ERROR`, `ROUTER_HONO.INVALID_HONO_PEER`).
|
|
|
|
## Conformance
|
|
|
|
The package passes `runRouterConformance` from `@suaveplan/api-router/testing` — see `tests/conformance.test.ts`. Adding new behaviours requires re-running the harness against the adapter.
|
|
|
|
## Modules
|
|
|
|
- [`src/adapter/adapter.md`](./src/adapter/adapter.md) — adapter façade + factory.
|
|
- [`src/blue-green-slot/blue-green-slot.md`](./src/blue-green-slot/blue-green-slot.md) — hot-reload primitive.
|
|
- [`src/middleware-adapter/middleware-adapter.md`](./src/middleware-adapter/middleware-adapter.md) — middleware bridge.
|
|
- [`src/error-codes/error-codes.md`](./src/error-codes/error-codes.md) — error registry.
|
|
|
|
## Usage
|
|
|
|
```ts
|
|
import { createHonoRouter, HonoBlueGreenSlot } from "@suaveplan/api-router-hono";
|
|
|
|
const router = createHonoRouter({ plugin: "billing" });
|
|
router.get("/invoices/:id", () => null);
|
|
|
|
const slot = new HonoBlueGreenSlot("billing", () => "v1");
|
|
slot.setShadow(() => "v2");
|
|
const draining = slot.flip();
|
|
await slot.dispose(draining.slotId, { timeoutMs: 1_000 });
|
|
```
|
|
|
|
## Dependencies
|
|
|
|
- `@suaveplan/api-router` — abstract contract + conformance harness.
|
|
- `@suaveplan/api-types` — `OtelSpanLike`, `TenantId`, `Principal`.
|
|
- `@suaveplan/error` — `SuaveplanError` + `defineCodes`.
|
|
- `hono` (peer ≥4.0.0) — wire-side dispatch.
|
|
|
|
## Version
|
|
|
|
`0.1.0` — initial Stage-4 ship. Graduates to `1.0.0` when the plugin system as a whole is declared production-ready.
|
|
|