suaveplan/packages/api-stack/api/api-router-hono/README.md

@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.

Documentation tree

• adapter — HonoRouter is The concrete Router adapter for the API plugin system. It implements every public method…
  • adapter — HonoRouter is The concrete Router adapter for the API plugin system. It implements every public method…
• blue-green-slot — HonoBlueGreenSlot is the per-plugin atomic flip primitive backing hot-reload for a Hono-backed Router. It holds at…
  • blue-green-slot — HonoBlueGreenSlot is the per-plugin atomic flip primitive backing hot-reload for a Hono-backed Router. It holds at…
• error-codes — This module defines the canonical, frozen error-code namespace ROUTER_HONO.* shared by every production path inside `…
  • error-codes — This module defines the canonical, frozen error-code namespace ROUTER_HONO.* shared by every production path inside `…
• middleware-adapter — This module bidirectionally bridges the onion-model Middleware type from @suaveplan/api-router and Hono's n…
  • middleware-adapter — This module bidirectionally bridges the onion-model Middleware type from @suaveplan/api-router and Hono's n…
• pipeline — @suaveplan/api-host's request pipeline drives its routing through a PipelineRouter-shaped seam — `match(method, url…
  • pipeline — @suaveplan/api-host's request pipeline drives its routing through a PipelineRouter-shaped seam — `match(method, url…

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 — adapter façade + factory.
• src/blue-green-slot/blue-green-slot.md — hot-reload primitive.
• src/middleware-adapter/middleware-adapter.md — middleware bridge.
• src/error-codes/error-codes.md — error registry.

Usage

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.