99 lines
6.8 KiB
Markdown
99 lines
6.8 KiB
Markdown
# @suaveplan/api-router — contract package for the Suaveplan API plugin system. Defines the abstract Router interface (verb methods + use + mount + match), Request / Response host-side shapes, Zod-validated RouteOptions schema, Middleware composition helpers with insertion-point guard, RouteMatch shape, BlueGreenSlot interface for hot-reload, the frozen ROUTER_CODES registry, and the runRouterConformance harness every concrete adapter must pass.
|
|
|
|
Stage-1 contract package for the Suaveplan API plugin system.
|
|
|
|
This package defines the abstract `Router` interface, the host-side
|
|
`Request` / `Response` shapes, the Zod-validated `RouteOptions` schema, the
|
|
`Middleware` composition contract with insertion-point guard, the
|
|
`RouteMatch` shape, the `BlueGreenSlot` interface backing hot reload, the
|
|
frozen `ROUTER_CODES` registry, and the `runRouterConformance` harness
|
|
every concrete adapter must pass.
|
|
|
|
The reference in-memory `Router` and `InMemoryBlueGreenSlot` implementations
|
|
ship here so the conformance harness is self-checking and Stage-1 consumers
|
|
have a working router before any concrete adapter lands.
|
|
|
|
<!-- begin:auto-docs -->
|
|
## Documentation tree
|
|
|
|
- [error-codes](./src/error-codes/error-codes.md) — The `error-codes` module is the single source of truth for every failure class this package surfaces. It exports the fr…
|
|
- [error-codes](./src/error-codes/error-codes.md) — The `error-codes` module is the single source of truth for every failure class this package surfaces. It exports the fr…
|
|
- [middleware](./src/middleware/middleware.md) — The `middleware` module defines the onion-model `Middleware` contract and the `composeMiddleware` builder. Every adapte…
|
|
- [insertion-point](./src/middleware/insertion-point.md) — The `insertion-point` module enforces the security invariant from design doc §6: plugin-supplied middleware is allowed…
|
|
- [middleware](./src/middleware/middleware.md) — The `middleware` module defines the onion-model `Middleware` contract and the `composeMiddleware` builder. Every adapte…
|
|
- [request](./src/request/request.md) — The `request` module defines the host-side `RouterRequest` shape — the post-parse, post-validation view that route hand…
|
|
- [request](./src/request/request.md) — The `request` module defines the host-side `RouterRequest` shape — the post-parse, post-validation view that route hand…
|
|
- [response](./src/response/response.md) — The `response` module provides the host-side `RouterResponse` shape and a fluent `ResponseBuilder` that adapters serial…
|
|
- [response](./src/response/response.md) — The `response` module provides the host-side `RouterResponse` shape and a fluent `ResponseBuilder` that adapters serial…
|
|
- [route-match](./src/route-match/route-match.md) — The `route-match` module defines `RouteMatch`, the shape every concrete adapter yields after resolving an incoming `(me…
|
|
- [route-match](./src/route-match/route-match.md) — The `route-match` module defines `RouteMatch`, the shape every concrete adapter yields after resolving an incoming `(me…
|
|
- [route-options](./src/route-options/route-options.md) — The `route-options` module is the Zod-validated boundary for every per-route configuration block. It widens the minimal…
|
|
- [route-options](./src/route-options/route-options.md) — The `route-options` module is the Zod-validated boundary for every per-route configuration block. It widens the minimal…
|
|
- [router](./src/router/router.md) — The `router` module defines the abstract `Router` — the verb-method surface (`get` / `post` / `put` / `patch` / `delete…
|
|
- [router](./src/router/router.md) — The `router` module defines the abstract `Router` — the verb-method surface (`get` / `post` / `put` / `patch` / `delete…
|
|
- [slot](./src/slot/slot.md) — The `slot` module defines `BlueGreenSlot` — the per-plugin atomic mount point that backs hot-reload. It exposes three p…
|
|
- [slot](./src/slot/slot.md) — The `slot` module defines `BlueGreenSlot` — the per-plugin atomic mount point that backs hot-reload. It exposes three p…
|
|
- [testing](./src/testing/conformance.md) — The `testing/conformance` module exports `runRouterConformance(factory)` — the canonical conformance harness every conc…
|
|
- [pipeline-router-conformance](./src/testing/pipeline-router-conformance/pipeline-router-conformance.md) — `runPipelineRouterConformance(factory)` is the canonical contract suite every concrete `PipelineRouter` adapter MUST pa…
|
|
- [pipeline-router-conformance](./src/testing/pipeline-router-conformance/pipeline-router-conformance.md) — `runPipelineRouterConformance(factory)` is the canonical contract suite every concrete `PipelineRouter` adapter MUST pa…
|
|
- [conformance](./src/testing/conformance.md) — The `testing/conformance` module exports `runRouterConformance(factory)` — the canonical conformance harness every conc…
|
|
<!-- end:auto-docs -->
|
|
|
|
## Status
|
|
|
|
- Version: `0.1.0`
|
|
- Stage: 1 (Contracts) — see umbrella design.
|
|
- Dependents: none yet (host wires this in).
|
|
|
|
## Install
|
|
|
|
```bash
|
|
bun add @suaveplan/api-router
|
|
```
|
|
|
|
## Modules
|
|
|
|
- [`router`](./src/router/router.md) — abstract `Router` + reference in-memory implementation.
|
|
- [`request`](./src/request/request.md) — host-side `RouterRequest` + `MapHeaders`.
|
|
- [`response`](./src/response/response.md) — `RouterResponse` + fluent builder.
|
|
- [`route-options`](./src/route-options/route-options.md) — Zod-validated `RouteOptions`.
|
|
- [`middleware`](./src/middleware/middleware.md) — onion-model `Middleware` + `composeMiddleware`.
|
|
- [`middleware/insertion-point`](./src/middleware/insertion-point.md) — pipeline-step guard.
|
|
- [`route-match`](./src/route-match/route-match.md) — `RouteMatch` shape + factory.
|
|
- [`slot`](./src/slot/slot.md) — `BlueGreenSlot` interface + in-memory reference impl.
|
|
- [`error-codes`](./src/error-codes/error-codes.md) — `ROUTER_CODES` + `RouterError`.
|
|
- [`testing/conformance`](./src/testing/conformance.md) — `runRouterConformance` adapter harness.
|
|
|
|
## Error codes
|
|
|
|
The five frozen codes (every one thrown by a production path):
|
|
|
|
- `ROUTER.ROUTE_COLLISION`
|
|
- `ROUTER.INVALID_PREFIX`
|
|
- `ROUTER.MIDDLEWARE_INSERTION_DENIED`
|
|
- `ROUTER.SLOT_FLIP_FAILED`
|
|
- `ROUTER.SLOT_DISPOSE_TIMEOUT`
|
|
|
|
## Subpath exports
|
|
|
|
Every module has its own subpath export so consumers tree-shake to exactly
|
|
what they import:
|
|
|
|
```ts
|
|
import { Router } from "@suaveplan/api-router/router";
|
|
import { composeMiddleware } from "@suaveplan/api-router/middleware";
|
|
import { parseRouteOptions } from "@suaveplan/api-router/route-options";
|
|
import { runRouterConformance } from "@suaveplan/api-router/testing";
|
|
```
|
|
|
|
## Verification
|
|
|
|
- `bunx turbo lint typecheck test --filter=@suaveplan/api-router` — green.
|
|
- `bunx turbo test:coverage --filter=@suaveplan/api-router` — 100/100/100/100.
|
|
- `bunx turbo build --filter=@suaveplan/api-router` — green.
|
|
|
|
## License
|
|
|
|
MIT
|
|
|