@rotorsoft/act-http 1.10.17 → 1.10.18

package/README.md

@@ -156,137 +156,31 @@ On failure: the adapter responds with the framework's idiomatic 400 (`missing-ke
 
 The framework-agnostic core (`checkWebhook`) and the underlying primitives (`extractIdempotencyKey`, `verifyWebhook`) are exported from `@rotorsoft/act-http/receiver` for receivers whose framework isn't in the adapter list (Koa, raw Node `http`, gRPC-over-HTTP, …) or for receivers with custom policy (e.g. "missing key falls back to body-derived dedup"). Use the `receiver` builder when you can; fall back to the framework `webhookMiddleware`, then the primitives.
 
-### `trpc` — auto-generated tRPC router
+### `trpc`, `hono`, `openapi` — APIs generated from the registry
+
+Each generator walks `app.registry.actions` and emits one route per action, so adding an action to the app adds it to every transport:
 
 ```ts
+import { hono } from "@rotorsoft/act-http/hono";
+import { openapi } from "@rotorsoft/act-http/openapi";
 import { trpc } from "@rotorsoft/act-http/trpc";
-import { initTRPC } from "@trpc/server";
-import { createHTTPServer } from "@trpc/server/adapters/standalone";
 
 const router = trpc(app, {
-  // ActorExtractor from `@rotorsoft/act-http/api` — host's auth seam.
   actor: (ctx) => ({ id: ctx.user.id, name: ctx.user.name }),
-  // Resolve the target stream per call; singleton aggregates return a constant.
   stream: (action, input, ctx) => `tenant-${ctx.tenant}`,
-  // Optional optimistic concurrency — return `undefined` to skip the check.
-  expectedVersion: (action, input, ctx) => readIfMatchHeader(ctx),
 });
 
-createHTTPServer({ router }).listen(4000);
-
-// Client (same types, no codegen):
-// await client.OpenTicket.mutate({ title: "support" });
-```
-
-The generator walks `app.registry.actions` once and emits a flat top-level mutation per action. The internal `authenticated(extractor)` middleware runs `options.actor` once per call and injects the resolved `Actor` onto `ctx.actor`, so any procedure logic downstream of the chain sees the same actor. `actor` and `stream` are required; `idempotency` is optional — when configured, the mutation reads `Idempotency-Key` via `keyFrom(ctx)` and throws `CONFLICT` on duplicate claims (the contract intentionally doesn't cache original results, matching the receiver-side "ack the duplicate" semantics).
-
-Errors map through the shared `toApiError(...)` table at `@rotorsoft/act-http/api`: `ConcurrencyError` → `CONFLICT`, `InvariantError` → `CONFLICT`, `ValidationError` → `UNPROCESSABLE_CONTENT`, `StreamClosedError` → `PRECONDITION_FAILED`, `NonRetryableError` → `BAD_REQUEST`, anything else → `INTERNAL_SERVER_ERROR`. The same envelope flows from every transport sibling so a client speaking two of them never sees two shapes for the same framework error.
-
-```ts
-// Compose the auth middleware into your own procedure chain instead:
-import { authenticated } from "@rotorsoft/act-http/trpc";
-
-const t = initTRPC.context<MyCtx>().create();
-const authed = t.procedure.use(authenticated(myExtractor));
-// `authed` carries `ctx.actor: Actor` downstream — use it for hand-written
-// procedures alongside the generated ones.
-```
-
-### `hono` — auto-generated REST surface
-
-```ts
-import { hono } from "@rotorsoft/act-http/hono";
-import { serve } from "@hono/node-server";
-
 const api = hono(app, {
-  // ActorExtractor from `@rotorsoft/act-http/api` — host's auth seam.
   actor: (c) => resolveActorFromJwt(c),
-  // Resolve the target stream per call; singleton aggregates return a constant.
   stream: (action, input, c) => `tenant-${c.req.header("x-tenant")}`,
-  // Optional optimistic concurrency — return `undefined` to skip the check.
-  expectedVersion: (action, input, c) => {
-    const v = c.req.header("if-match");
-    return v ? Number.parseInt(v, 10) : undefined;
-  },
-});
-
-serve({ fetch: api.fetch, port: 4000 });
-// POST /api/actions/OpenTicket  body: { title }
-// → 200 [Snapshot] | 4xx ApiError envelope
-```
-
-The generator walks `app.registry.actions` once and registers one `POST /actions/<actionName>` per action under the configured `basePath` (default `/api`). Bodies are validated with `@hono/zod-validator` against the action's registered Zod schema; failures short-circuit with `400`. The internal `authenticated(extractor)` middleware runs `options.actor` once per request and stashes the resolved `Actor` under `c.get("actor")`, available to any downstream middleware (logging, tracing, hand-written routes mounted on the same Hono instance). `Idempotency-Key` is read from the request header by default; `keyFrom` overrides for hosts that prefer a custom convention.
-
-Errors map through the shared `toApiError(...)` table at `@rotorsoft/act-http/api`: `ConcurrencyError → 412 / CONCURRENCY`, `InvariantError → 409 / INVARIANT`, `ValidationError → 422 / VALIDATION`, `StreamClosedError → 410 / STREAM_CLOSED`, `NonRetryableError → 400 / NON_RETRYABLE`. The envelope (`{ error, detail?, code? }`) is the same shape every other act-http transport ships so a client speaking REST plus tRPC never sees two formats for the same framework error.
-
-Edge-runtime ready — Hono runs unchanged on Node, Bun, Cloudflare Workers, Vercel Edge, and AWS Lambda. Operators wiring `idempotency` on edge runtimes should verify the `IdempotencyStore` is edge-compatible (in-memory works per worker; cross-worker requires a distributed store).
-
-```ts
-// Compose the auth middleware into your own Hono chain instead:
-import { Hono } from "hono";
-import { authenticated, type ActMiddlewareVariables } from "@rotorsoft/act-http/hono";
-
-const api = new Hono<{ Variables: ActMiddlewareVariables }>();
-api.use("*", authenticated((c) => resolveActorFromJwt(c)));
-// Hand-written routes alongside the generated ones now see c.get("actor") typed.
-```
-
-### `openapi` — OpenAPI 3.1 document emitter
-
-```ts
-import { openapi } from "@rotorsoft/act-http/openapi";
-
-const doc = openapi(app, {
-  info: { title: "Wolfdesk API", version: "1.0.0" },
-  servers: [{ url: "https://api.example.com" }],
-  // Document the optional cross-cutting headers that the live REST API accepts.
-  idempotency: true,
-  expectedVersion: true,
-});
-
-// Serve alongside the Hono adapter:
-api.get("/openapi.json", (c) => c.json(doc));
-```
-
-Pure data emit — no runtime dep on Hono or tRPC. The doc walks `app.registry.actions` once at function call and emits one `POST <basePath>/actions/<actionName>` operation per action, deriving the request-body schema from each action's Zod definition via Zod 4's native `z.toJSONSchema` (OpenAPI 3.1 uses JSON Schema 2020-12 as its schema dialect — no conversion layer needed).
-
-**The doc describes the Hono REST surface, not tRPC.** tRPC's URL convention (`POST /trpc/<procedure>`, JSON-RPC-style body framing, batching) doesn't model cleanly as OpenAPI operations; tRPC consumers share types directly via `typeof router` and don't need a doc. The path shape this emitter produces matches `@rotorsoft/act-http/hono` by construction: same default `basePath` (`/api`), same request/response shapes, same error envelope. If the operator overrides `basePath` on the Hono adapter, pass the same value here so the doc keeps describing the live routes. tRPC and Hono can run side-by-side at different mount points on the same Act instance.
-
-The same shared `ApiError` envelope underwrites cross-transport consistency: it's referenced once from `components.responses` and every error code (`400`, `409`, `410`, `412`, `422`, `500`) points at it. The doc and the live REST API agree on framework-error shapes by construction.
-
-Output is deterministic given the same registry — entries land in `Object.entries(app.registry.actions)` iteration order. CI can snapshot the result to catch unintended API-surface changes; one merge that quietly changes a Zod schema or adds a new action surfaces as a doc diff in the same PR.
-
-### `trpc` + `hono` SSE subscriptions — live state from the generators
-
-Both generators accept an optional `sse` option that walks the registry once and emits a typed subscription per unique state name, all reading from a host-supplied `BroadcastChannel`. Hosts continue to own publication (`channel.publish(streamId, state, patches)` after each `app.do(...)`); the generators own subscription, accounting, cleanup, and the wire format.
-
-```ts
-import { BroadcastChannel } from "@rotorsoft/act-http/sse";
-import { trpc } from "@rotorsoft/act-http/trpc";
-import { hono } from "@rotorsoft/act-http/hono";
-
-const broadcast = new BroadcastChannel<MyState>();
-
-// Server-side: after every app.do(...), publish the derived state.
-const snaps = await app.do(action, target, payload);
-broadcast.publish(target.stream, deriveState(snaps), snaps.map((s) => s.patch).filter(Boolean));
-
-// tRPC — emits `router.subscribe.<stateName>.useSubscription({ stream })`.
-const router = trpc(app, {
-  actor,
-  stream,
-  sse: { channel: broadcast, maxConnections: 500, heartbeatMs: 30_000 },
-});
+}); // POST /api/actions/<action>
 
-// Hono — emits `GET /api/sse/<stateName>?stream=<id>` per registered state.
-const api = hono(app, {
-  actor,
-  stream,
-  sse: { channel: broadcast },
-});
+api.get("/openapi.json", (c) =>
+  c.json(openapi(app, { info: { title: "My API", version: "1.0.0" } }))
+);
 ```
 
-Defaults are sized for typical business-app dashboards: `maxConnections = 500` (range `[1, 10_000]`), `heartbeatMs = 30_000` (range `[15_000, 300_000]`), `maxPendingPerConnection = 256` (range `[1, 100_000]`). The 501st concurrent open returns `503 / SSE_BUSY` with `Retry-After: 1` (Hono) or throws `TOO_MANY_REQUESTS` (tRPC). Each connection's undelivered-frame backlog is bounded by `maxPendingPerConnection`: a stalled consumer on a busy stream drops its oldest queued frame (drop-oldest) rather than growing memory without bound — each frame is a full version-keyed patch, so the consumer still converges on current state. Streams cleaned up via the consumer's `iter.return()` / disconnect both run the loop's `finally` block: unsubscribe from the channel, release the slot (only if one was acquired), clear the heartbeat. See [@rotorsoft/act-http/sse](#sse--live-state-broadcast) below for the channel/cache primitives this wires.
+Framework errors share one envelope (`{ error, detail?, code? }`) and one status table: `ValidationError` → 422, `InvariantError` → 409, `ConcurrencyError` → 412, `StreamClosedError` → 410, `NonRetryableError` → 400, anything else → 500. tRPC has no 410, so `StreamClosedError` is `NOT_FOUND` there. Optimistic concurrency (`expectedVersion`), `Idempotency-Key` handling, SSE subscriptions (`sse: { channel }`), auth composition and deployment recipes are in the [auto-generated API guide](https://rotorsoft.github.io/act-root/docs/guides/auto-generated-api).
 
 ### `sse` — live state broadcast
 
@@ -342,45 +236,14 @@ Each framework adapter exports a single function `webhookMiddleware(options)` th
 | `/receiver/fastify` | `request.idempotency` | `reply.status(...).send({ error: reason })` |
 | `/receiver/hono` | `c.get("idempotency")` (typed via `Variables`) | `c.json({ error: reason }, status)` |
 
-### `/api` subpath
-
-Shared utilities consumed by every transport in the auto-generated API umbrella (act-http-api epic #835). Three concerns surfaced once, not per-transport:
-
-- **`ActorExtractor`** — type alias `(request: unknown) => Actor | Promise<Actor>`. The host-supplied closure resolving an `Actor` from an incoming request. Required on every transport (`trpc(app, { actor })`, `hono(app, { actor })`). Auth (JWT, session, API key) stays in the host; the package only asks for this function.
-- **`ApiError`** — uniform envelope `{ error, detail?, code? }` shipped over the wire by every transport. Hosts get the same shape from REST, tRPC, and OpenAPI.
-- **`ERROR_MAP`** — `as const` table mapping framework error types to `{ status, code }`. `ValidationError → 422 / VALIDATION`, `InvariantError → 409 / INVARIANT`, `ConcurrencyError → 412 / CONCURRENCY`, `StreamClosedError → 410 / STREAM_CLOSED`, `NonRetryableError → 400 / NON_RETRYABLE`.
-- **`toApiError(err) → { status, body }`** — the single mapping helper every transport calls in its error boundary. Known framework errors map per `ERROR_MAP`; everything else surfaces as 500 / `INTERNAL` (with `detail` only when the throw was an `Error` — thrown strings or objects don't leak payloads).
-- **`withIdempotency(store, key, handler)`** — wraps an action handler in a two-phase `Idempotency-Key` claim: it `claim`s tentatively, runs the handler, then `commit`s the key on success or `release`s it and re-throws on a handler rejection (so a transient failure re-processes on retry rather than deduping into a silent success). Reuses `@rotorsoft/act-ops/idempotency` — same contract `@rotorsoft/act-http/receiver` already speaks, so one `IdempotencyStore` covers both halves of the "Act over the wire" surface. Returns `{ deduped: false, result }` on fresh claim, `{ deduped: true }` on duplicate (handler is not called).
-- **`SseOptions`** — `{ channel: BroadcastChannel<S>, maxConnections?, heartbeatMs?, maxPendingPerConnection? }`. Shared SSE wiring options consumed by both `trpc(app, { sse })` and `hono(app, { sse })`. Defaults: `maxConnections=500` (validated `[1, 10_000]`), `heartbeatMs=30_000` (validated `[15_000, 300_000]`), `maxPendingPerConnection=256` (validated `[1, 100_000]`). Out-of-range values throw `RangeError` at transport construction so misconfiguration surfaces at startup, not at first connection.
-- **`SseConnectionCounter`** — per-process slot counter. The 501st concurrent open is refused (`503 / SSE_BUSY` with `Retry-After: 1` on Hono, `TOO_MANY_REQUESTS` on tRPC). Internal — both transports construct one each, shared by every state-name's subscription on a single generator instance.
-- **`runSseSubscription(channel, streamId, accounting?, signal?, on_cap_exceeded?)`** — the shared subscription loop both transports run. Acquires one slot (when an `accounting` is supplied), yields the cached state if present, then forwards every channel publication as a `{ kind: "patch", data }` frame until the consumer breaks or the signal aborts. Used internally; exported for adopters who want to build their own transport surface against the same accounting / cancellation discipline.
-- **`resolveSseConfig(options)`** + **`DEFAULT_SSE_HEARTBEAT_MS`** / **`DEFAULT_SSE_MAX_CONNECTIONS`** — validation helper and exposed defaults.
-- **Types**: `IdempotencyResult<T>`, `ErrorMapEntry`, `SseConfig`, `SseAccounting`, `SseSubscriptionFrame<S>`.
-
-### `/trpc` subpath
-
-Auto-generated tRPC router for the act-http-api epic (#835).
-
-- **`trpc(app, options) → Router`** — generator function. Walks `app.registry.actions` once and emits a flat top-level mutation per action. Each procedure runs the internal `authenticated(options.actor)` middleware (so `ctx.actor: Actor` is set on the downstream context), resolves the target stream via `options.stream(action, input, ctx)`, and calls `app.do(action, { stream, actor }, input)`. Known framework errors map through `toApiError` to the conventional tRPC codes; unknown throws surface as `INTERNAL_SERVER_ERROR`.
-- **`authenticated(extractor) → middleware`** — standalone export of the auth middleware the generator uses internally. Hosts composing their own procedure chain (logging + tracing + custom auth flavors) use `t.procedure.use(authenticated(extractor))` to inject `ctx.actor` without going through the generator. The middleware is structurally-typed so any host `t` instance accepts it.
-- **`TrpcOptions<Ctx>`** — `{ actor, stream, expectedVersion?, idempotency?, sse? }`. `actor` is the `ActorExtractor` from `@rotorsoft/act-http/api`. `stream` returns the target stream per call. `expectedVersion` is optional — `(action, input, ctx) => number | undefined` — when set, the procedure threads the resolved value through `Target.expectedVersion` so `app.do` enforces optimistic concurrency; hosts typically read it from an `If-Match` header or the client's last-known snapshot, and returning `undefined` skips the check for that call. `idempotency` is optional — `{ store: IdempotencyStore; keyFrom: (ctx) => string | undefined }` — when set, the procedure honors `Idempotency-Key` via `withIdempotency`. Duplicate claims throw `CONFLICT` (the contract intentionally doesn't cache the original handler's result). `sse` is optional — when set, the generator emits one subscription per unique registered state name under the nested `router.subscribe.<stateName>` namespace; each yields `{ kind: "state", data }` once (when the channel has a cached state) and then `{ kind: "patch", data }` per channel publication until the consumer breaks. The cap surfaces as `TOO_MANY_REQUESTS`.
+### `/api`, `/trpc`, `/hono`, `/openapi` subpaths
 
-### `/hono` subpath
+- **`/api`** — what every transport shares: `ActorExtractor`, the `ApiError` envelope, `ERROR_MAP` and `toApiError(err)`, `withIdempotency(store, key, handler)`, and the SSE wiring (`SseOptions`, `resolveSseConfig`, `runSseSubscription`). Bad SSE options throw `ZodError` when the transport is built.
+- **`/trpc`** — `trpc(app, options)`, the `authenticated(extractor)` middleware, and `TrpcOptions`.
+- **`/hono`** — `hono(app, options)`, the `authenticated(extractor)` middleware, `HonoOptions` and `ActMiddlewareVariables`. A body that fails its action's schema returns `422` with the `ApiError` envelope.
+- **`/openapi`** — `openapi(app, options)`, which returns an OpenAPI 3.1 document describing the `hono` routes, plus `OpenAPIOptions` and the document types.
 
-Auto-generated REST surface for the act-http-api epic (#835).
-
-- **`hono(app, options) → Hono`** — generator function. Walks `app.registry.actions` once and registers a `POST /actions/<actionName>` per action under `basePath` (default `/api`). Body is validated with `@hono/zod-validator` against the action's Zod schema; failures short-circuit with `400`. The internal `authenticated(options.actor)` middleware stashes the resolved `Actor` under `c.get("actor")`. Routes return `200 Snapshot[]` on success, `4xx ApiError` envelope (with the conventional HTTP status) on framework errors, `500 / INTERNAL` on unknown throws.
-- **`authenticated(extractor) → MiddlewareHandler`** — standalone export of the auth middleware the generator uses internally. Hosts composing their own Hono chain wire `api.use("*", authenticated(extractor))` and downstream routes read `c.get("actor"): Actor`. Errors thrown by the extractor surface as `401 / UNAUTHORIZED`.
-- **`HonoOptions`** — `{ actor, stream, expectedVersion?, idempotency?, sse?, basePath? }`. `actor` is the `ActorExtractor`. `stream` returns the target stream per call. `expectedVersion` threads `Target.expectedVersion` for optimistic concurrency — returning `undefined` skips the check. `idempotency` is optional — `{ store: IdempotencyStore; keyFrom?: (c) => string | undefined }` — when set, the route honors `Idempotency-Key` via `withIdempotency`; default `keyFrom` reads the `Idempotency-Key` header. Duplicate claims return `409 / CONFLICT`. `sse` is optional — when set, the generator emits one `GET <basePath>/sse/<stateName>?stream=<id>` route per unique registered state name; each route opens a `text/event-stream`, yields the cached state (`event: state`) when present, then forwards every channel publication as `event: patch`. The connection cap surfaces as `503 / SSE_BUSY` with `Retry-After: 1`. A heartbeat ping every `heartbeatMs` keeps proxies from idling the connection out. `basePath` defaults to `/api`.
-- **`ActMiddlewareVariables`** — `{ actor: Actor }`. Use as the `Variables` generic on a host Hono instance to get `c.get("actor")` typed downstream of `authenticated`.
-
-### `/openapi` subpath
-
-OpenAPI 3.1 document emitter for the act-http-api epic (#835).
-
-- **`openapi(app, options) → OpenAPIDocument`** — generator function. Walks `app.registry.actions` once and returns a valid OpenAPI 3.1 document object. Each action becomes a `POST <basePath>/actions/<actionName>` operation; the request-body schema comes from Zod 4's `z.toJSONSchema` against the action's registered schema. Error responses reference the shared `#/components/responses/ApiError`. Output is pure data — serve as `/openapi.json`, write to disk during CI, pipe to client codegen.
-- **`OpenAPIOptions`** — `{ info, servers?, basePath?, idempotency?, expectedVersion? }`. `info.title` and `info.version` are required non-empty strings. `servers[].url` may contain `{variable}` template syntax; bare URLs are validated through `URL`'s parser. `basePath` defaults to `/api` (mirrors the Hono sibling). `idempotency` and `expectedVersion` are booleans (default `false`); when `true`, every mutation operation documents the corresponding header — `Idempotency-Key` is marked **required** (the route 400s without it), `If-Match` is optional.
-- **`OpenAPIDocument`** + a structural subset of the OpenAPI 3.1 types (`OpenAPIInfo`, `OpenAPIServer`, `OpenAPIPathItem`, `OpenAPIOperation`, `OpenAPIParameter`, `OpenAPIRequestBody`, `OpenAPIResponse`, `OpenAPIComponents`). Intentionally lighter than the full `openapi-types` package so post-processing doesn't fight the type system; cast to a fuller type when downstream consumers need it.
+Every option is described in the [auto-generated API guide](https://rotorsoft.github.io/act-root/docs/guides/auto-generated-api).
 
 ### `/sse` subpath
 
@@ -442,14 +305,7 @@ Generic catch sites that don't care about HTTP specifics can match on the base `
 
 ### Recovering a blocked stream
 
-When `webhook` blocks a stream — whether on first attempt (4xx) or after exhausting retries — the operator's recovery path is `app.unblock(input)` from `@rotorsoft/act`. It clears the blocked flag and resumes from where the stream stopped, *not* from the beginning. Don't use `app.reset()` — `reset` rebuilds from event 0 and would re-fire every historical webhook.
-
-```ts
-await app.unblock(["webhooks-out-customer-42"]);     // by name
-await app.unblock({ stream: "^webhooks-out-" });     // bulk by pattern
-```
-
-Use `app.blocked_streams()` to discover what's currently blocked.
+When `webhook` blocks a stream (on a 4xx, or after exhausting retries), recover with `app.unblock(...)`, which resumes from where the stream stopped. Never `app.reset()` it: that replays from event 0 and re-fires every historical webhook. See [Blocked streams](https://rotorsoft.github.io/act-root/docs/concepts/error-handling#blocked-streams).
 
 ### SSE wire format