@gjermundgaraba/effect-actions 0.11.0 → 0.12.0

package/docs/ActionHttp.md

@@ -1,307 +1,227 @@
 # ActionHttp
 
-JSON `POST` routes on Effect's `HttpApi`. `ActionHttp.make` binds actions to a mount path and
-names the authentication descriptor of its protected actions; the binding is shared by the
-server, every client, and the OpenAPI document. Servers mount it with
-`ActionHttp.layer(Http, implementations)`, serving the binding's actions among the
-implementations, or those its `actions` lists: each protected route authenticated before its
-body is read, then each call
-behind its implementation's authorization. Clients call it with
-`ActionHttp.client(Http)`.
+JSON `POST` routes on Effect's `HttpApi`, one per action. `ActionHttp.make` binds actions to a
+mount path; the server mounts that one binding, every client calls it and the OpenAPI document is
+generated from it.
+
+Read this page alone, in one tool call: pages read together are cut. When something fails,
+search [ActionHttp-failures.md](ActionHttp-failures.md). Reading order: [README.md](README.md).
 
 ## API
 
 Import `@gjermundgaraba/effect-actions/ActionHttp`.
 
-| API                                      | Purpose                                                                                      |
-| ---------------------------------------- | -------------------------------------------------------------------------------------------- |
-| `make(actions, options?)`                | Bind a list of actions; returns a `Binding`. Options are required for a protected action.    |
-| `Http.actions`                           | The exact bound actions.                                                                     |
-| `Http.error`                             | The errors every endpoint declares besides its action's own.                                 |
-| `Http.prefix`                            | Where the routes mount: `/api` by default, `/` at the root, without a trailing slash.        |
-| `Http.authentication`                    | The authentication descriptor of its protected actions, or `undefined`.                      |
-| `Http.api`                               | Native Effect `HttpApi` for clients and OpenAPI.                                             |
-| `layer(Http, implementations, options?)` | Mount the routes of the bound actions these implementations hold, or the listed ones.        |
-| `client(Http, options?)`                 | An Effect of a typed client; requires the native `HttpClient`, as `HttpApiClient.make` does. |
-| `fetchClient(Http, options?)`            | The same client, built over `fetch` outside an Effect: its methods require nothing.          |
-
-Exported types: `Binding`; `Any`, any binding; `Client`, a client's type: `Client<typeof Http>`; `MethodError`, what one of its calls fails with; `Options` of `make`, `LayerOptions` of `layer`, `ClientOptions` of `client` and `FetchClientOptions` of `fetchClient`.
-
-| Option                      | Meaning                                                                                                                           |
-| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| `make`: `prefix`            | Mount path of every route; defaults to `/api`. `/` mounts at the root; a trailing slash is dropped.                               |
-| `make`: `error`             | Errors middleware around the routes sends, such as a limit before decoding: declared by every endpoint, so clients decode them.   |
-| `make`: `authentication`    | The descriptor of the protected actions' identity, `Authentication.make(...)`: required when the binding holds one.               |
-| `layer`: `actions`          | The bound actions it serves, among the implementations': `[GetUser]`. Defaults to every one they hold.                            |
-| `layer`: `middleware`       | Native `HttpApiMiddleware` run around every route the layer serves, inside authentication, outside decoding; the first innermost. |
-| `client`: `baseUrl`         | What routes are resolved against, such as `https://api.example.com`. Omitted: relative routes (the page's origin in a browser).   |
-| `client`: `transformClient` | Wraps the native `HttpClient`. A bearer token: `HttpClient.mapRequest(HttpClientRequest.bearerToken(token))`.                     |
-| `fetchClient`: `fetch`      | What each call sends with; it also takes `client`'s options. Omitted: the global `fetch`, looked up on every call.                |
-
-Routes: each action is served at `POST <prefix>/<action>`, operation ID `<action>`. A
-read-only action is a `POST` too: `readOnly` changes neither the method nor caching. The
-OpenAPI tag is the mount path's segments (`api`, `v2/api`), or `/` at the root. Every
-endpoint declares its action's errors, the binding's `error`, and the built-in
-`InvalidInput` (400), `Unauthenticated` (401) and `Forbidden` (403); a protected one also
-declares its descriptor's `error`, what the verifier may fail with.
-
-Layer failures and startup requirements come from the builders of the supplied
-implementations, and, where it serves a protected action, the descriptor's provider,
-`Authentication.layer`. The request services of each implementation's authorizer and of the
-handlers of the actions the layer serves
-remain router request requirements until middleware provided around the layer provides them,
-the protected actions' identity excepted, which the provider supplies; an action the binding
-leaves out owes nothing there. Router/platform services are also required
-([guarantees.md](guarantees.md#dependency-lifetimes)).
-
-## Canonical
-
-The binding, shared by the server and every client, names the authentication descriptor of its
-protected actions ([Authentication.md](Authentication.md#canonical)):
-
-```ts example=binding.ts
-import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
-import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
-import { CurrentActor } from "./authorization.js";
-import { Double, GetUser, RenameUser, Status, WhoAmI } from "./contracts.js";
-
-// Browser-safe: how a remote caller proves it is CurrentActor, a bearer token unless
-// `security` names another native scheme. The verifier lives in authentication.ts. The literal
-// name identifies the verifier that may provide it.
-export const Login = Authentication.make("example.Login", CurrentActor);
-
-// Protected contracts get native bearer security (enforced and documented); `status`,
-// declared `caller: Action.Anyone`, gets none.
-export const Http = ActionHttp.make([Status, GetUser, RenameUser, Double, WhoAmI], {
+| API                                      | Purpose                                                                 |
+| ---------------------------------------- | ----------------------------------------------------------------------- |
+| `make(actions, options?)`                | Bind a list of actions; returns a `Binding`.                            |
+| `Http.actions`                           | The bound actions.                                                      |
+| `Http.error`                             | The errors every endpoint declares besides its action's own, as a list. |
+| `Http.prefix`                            | Where the routes mount.                                                 |
+| `Http.authentication`                    | Its protected actions' authentication descriptor, or `undefined`.       |
+| `Http.api`                               | The native `HttpApi`, for OpenAPI and Effect's own tools.               |
+| `layer(Http, implementations, options?)` | Mount the routes of the bound actions the implementations hold.         |
+| `client(Http, options?)`                 | An Effect of a typed client; requires the native `HttpClient`.          |
+| `fetchClient(Http, options?)`            | The same client over `fetch`, built outside an Effect.                  |
+
+Exported types: `Binding`; `Any`, any binding; `Client<typeof Http>`, a client's type;
+`MethodError`, what one of its calls fails with; `Options` of `make`, `LayerOptions`,
+`ClientOptions` and `FetchClientOptions`.
+
+| Option                      | Meaning                                                                                           |
+| --------------------------- | ------------------------------------------------------------------------------------------------- |
+| `make`: `prefix`            | Mount path of every route; defaults to `/api`. `/` mounts at the root.                            |
+| `make`: `error`             | What middleware around the routes answers with, one schema or a list; every endpoint declares it. |
+| `make`: `authentication`    | The protected actions' descriptor, `Authentication.make(...)`; required with a protected action.  |
+| `layer`: `actions`          | The bound actions it serves: `[GetUser]`. Defaults to every one the implementations hold.         |
+| `layer`: `middleware`       | Native `HttpApiMiddleware` around every route it serves, the first innermost.                     |
+| `client`: `baseUrl`         | What routes resolve against: `https://api.example.com`. Omitted: relative ones, a page's origin.  |
+| `client`: `transformClient` | Wraps the native `HttpClient`: `HttpClient.mapRequest(HttpClientRequest.bearerToken(token))`.     |
+| `fetchClient`: `fetch`      | Its `fetch`, beside `client`'s options. Omitted: the global `fetch`, looked up on every call.     |
+
+Each action is served at `POST <prefix>/<action>`, a `readOnly` one too. One without `success`
+answers an empty 200, with no body and no content type, so a hand-written client must not parse
+it. One without `input` still takes the body `{}`, typed as JSON. Statuses and bodies:
+[guarantees.md](guarantees.md#wire-behavior).
+
+## Bind actions to routes
+
+Call `ActionHttp.make` once, in a file that imports contracts and no server code, and export the
+binding: the server, every client, the CLI and the tests import that one value.
+
+```ts
+export const Http = ActionHttp.make([GetStatus, ...Notes, WhoAmI], {
+  prefix: "/api",
   authentication: Login,
 });
 ```
 
-### Serving
-
-One layer serves the public and the protected actions: each protected route authenticates
-before its body is read, and `status` stays open.
-
-```ts example=http.ts
-import { Layer } from "effect";
-import { HttpRouter, HttpServerResponse } from "effect/http";
-import { HttpApiSwagger, OpenApi } from "effect/http-api";
-import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
-import { authenticate } from "./authentication.js";
-import { Http } from "./binding.js";
-import { double, status, userActions } from "./handlers.js";
-
-// One layer: each protected route authenticates before decoding; `status` stays public.
-const routes = ActionHttp.layer(Http, [status, userActions, double]).pipe(
-  Layer.provide(authenticate),
-);
-
-const documentation = Layer.mergeAll(
-  HttpRouter.add(
-    "GET",
-    "/api/openapi.json",
-    HttpServerResponse.jsonUnsafe(OpenApi.fromApi(Http.api)),
-  ),
-  HttpApiSwagger.layer(Http.api, { path: "/docs" }),
-);
-
-export const layer = Layer.mergeAll(routes, documentation);
-```
+Files: [quickstart/src/Api.ts](../examples/quickstart/src/Api.ts) (public actions, no options),
+[notes-service/src/Api.ts](../examples/notes-service/src/Api.ts) (protected actions),
+[kitchen-sink/src/Api.ts](../examples/kitchen-sink/src/Api.ts) (`prefix`, `error`, two bindings).
 
-Serve with `HttpRouter.serve(layer).pipe(Layer.provide(NodeHttpServer.layer(createServer, { port })), Layer.launch)`, and set a request body limit ([guarantees.md](guarantees.md#wire-behavior)). Put a job or an agent the process runs inside `layer`, not beside `HttpRouter.serve`, so it shares the routes' builders and services rather than building its own ([dependency lifetimes](guarantees.md#dependency-lifetimes)).
+- To keep an action off HTTP, leave it out of the binding; its implementation may still serve
+  it as a tool or a command.
+- A binding holding a protected action names its descriptor
+  ([Authentication.md](Authentication.md#declare-how-callers-sign-in)), and has only one: a
+  second identity gets a second binding with its own `prefix`. A public action may be in both.
+- `error` declares what middleware answers with on any route, such as a quota's 429. An error a
+  handler fails with goes in its action's `error`
+  ([Action.md](Action.md#fail-with-declared-and-built-in-errors)).
+- Action names are unique within a binding. Split a large API, or two actions sharing a name,
+  into one binding per area, each with its own `prefix` and client; one host serves them all.
 
-A large API, or two actions that would share a name, gets one binding per area, each with its
-own `prefix` and client, served by one host, and each documented on its own where they share a
-name ([Failure modes](#failure-modes)):
+## Serve the routes
 
-```ts
-export const Billing = ActionHttp.make([Invoice, Refund], { prefix: "/api/billing" });
-export const Accounts = ActionHttp.make([GetUser, RenameUser], { prefix: "/api/accounts" });
+Give `ActionHttp.layer` the binding and the implementations, merge it with the host's other
+routes, provide the descriptor's provider
+([Authentication.md](Authentication.md#verify-credentials)), and serve the result with
+`HttpRouter.serve`.
 
-// Each layer takes the whole list, and serves its binding's actions among it.
-const routes = Layer.mergeAll(
-  ActionHttp.layer(Billing, [billing, accounts]),
-  ActionHttp.layer(Accounts, [billing, accounts]),
-);
+```ts
+const api = ActionHttp.layer(Http, implementations);
 
-// One document for both, when no action name repeats across them:
-// HttpApi.make("app").addHttpApi(Billing.api).addHttpApi(Accounts.api)
+export const routes = Layer.mergeAll(api, mcp, health, openApi).pipe(Layer.provide(authenticate));
 ```
 
-### Client
-
-`client(Http)` is Effect's native `HttpApiClient` with one method per action, taking the
-action's input directly and answering with its decoded success: `client.<action>(input)`.
-
-```ts example=client.ts
-import { Console, Effect } from "effect";
-import { FetchHttpClient, HttpClient, HttpClientRequest } from "effect/http";
-import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
-import { Http } from "./binding.js";
-
-const lookup = Effect.gen(function* () {
-  const client = yield* ActionHttp.client(Http, {
-    baseUrl: "http://127.0.0.1:3000",
-    transformClient: HttpClient.mapRequest(HttpClientRequest.bearerToken("alice")),
-  });
+Files: [quickstart/src/routes.ts](../examples/quickstart/src/routes.ts) and
+[quickstart/src/server.ts](../examples/quickstart/src/server.ts);
+[notes-service/src/routes.ts](../examples/notes-service/src/routes.ts) and
+[notes-service/src/server.ts](../examples/notes-service/src/server.ts).
+
+- Pass every surface the same list of implementations: the layer serves the binding's actions
+  among them.
+- A service a handler or an authorizer reads per request stays owed by the layer until router
+  middleware around it, `HttpRouter.provideRequest` or the layer's own `middleware` provides it.
+  Router middleware is the one that reads the request, such as a header:
+  `HttpRouter.middleware<{ provides: Tenant }>()((route) => …)`, given as
+  `Layer.provide(resolveTenant.layer)`
+  ([kitchen-sink/src/workspaces/tenant.ts](../examples/kitchen-sink/src/workspaces/tenant.ts)).
+  Without the type argument it runs and the layer still owes the service.
+  `HttpRouter.provideRequest(layer)` builds its layer once, at startup, and gives every request
+  that one value: never an identity or a tenant
+  ([Action.md](Action.md#say-who-may-call-an-action)).
+- Give the server a `host`: `NodeHttpServer.layer(createServer, { port })` without one listens on
+  every interface. The examples bind `127.0.0.1`.
+- Two listeners are two `HttpRouter.serve` calls, each building its routes on its own. What they
+  share is provided outside both
+  ([Action-in-process.md](Action-in-process.md#share-one-build-across-servers),
+  [kitchen-sink/src/server.ts](../examples/kitchen-sink/src/server.ts)).
+
+Set a request body limit: a body has none unless the host provides one to `HttpRouter.serve`, as
+below. It covers every route of the server, MCP endpoints included, except a body a route reads
+as a stream. On Node (`NodeHttpServer`), a request over it gets no response, not a 413: its connection is
+closed. `HttpRouter.toWebHandler` ignores it, so limit bodies in the platform serving the handler.
 
-  const status = yield* client.status();
-  const user = yield* client.getUser({ id: "1" });
-  const identity = yield* client.whoAmI();
+```ts
+Layer.provide(Layer.succeed(HttpServerRequest.MaxBodySize, ByteSize.mebibytes(1))),
+```
 
-  return { status, user, identity };
-});
+An `ErrorReporter` the server runs with is also given, with severity `Info`, what a handler
+or `authorize` fails with and an input that does not decode, a declared 404, a 403 or a 400:
+Effect's `HttpApi` reports a route's failures, of which a refused credential is none. MCP and
+RPC report a defect alone. To keep a declared error out of a tracker, give its class
+`override readonly [ErrorReporter.ignore] = true`; a built-in error takes no mark, so drop
+`Info` there.
+
+### Split a binding across layers, and add middleware
+
+Several layers may serve one binding, each with its own `actions` and `middleware`; serve each
+action from exactly one. Files:
+[kitchen-sink/src/routes.ts](../examples/kitchen-sink/src/routes.ts) (`api`),
+[kitchen-sink/src/identity/quota.ts](../examples/kitchen-sink/src/identity/quota.ts).
+
+| Where                                                | Runs                                     | Use it for                                                 |
+| ---------------------------------------------------- | ---------------------------------------- | ---------------------------------------------------------- |
+| Global router middleware                             | before routing, on every route           | a Host or Origin policy, CORS                              |
+| Router middleware provided to a `layer` call         | around its routes, before authentication | a per-request service; a limit on unauthenticated requests |
+| The layer's `middleware`                             | after authentication, before decoding    | a limit keyed by the caller, counting invalid input too    |
+| The handler ([Action.md](Action.md#authorize-calls)) | after decoding and the authorizer        | a limit that holds on every surface, MCP included          |
+
+- A layer middleware requiring the identity needs a layer serving protected actions only. Serve
+  the public actions from a second layer without it.
+- Router middleware answering with a binding error encodes and sends it itself,
+  `HttpServerResponse.schemaJson(QuotaExceeded)(error, { status: 429 })`, at the error's
+  `httpApiStatus`, or 422 without one: at any other status the client fails with an
+  `HttpClientError`.
+- A request policy that must run before authentication and OAuth discovery:
+  [Authentication-advanced.md](Authentication-advanced.md#run-a-request-policy-before-authentication).
+
+### Publish the OpenAPI document
+
+Give `Http.api`, a plain `HttpApi`, to `OpenApi.fromApi`, `HttpApiSwagger.layer` or
+`HttpApiScalar.layer`, on routes of the host's own. Files:
+[notes-service/src/routes.ts](../examples/notes-service/src/routes.ts) (`openApi`),
+[kitchen-sink/src/routes.ts](../examples/kitchen-sink/src/routes.ts) (`documentation`).
+
+- The document's route is public unless you put middleware around it.
+- A header that middleware reads is not in the document: its operations list no `parameters`.
+  Add it by rewriting the document,
+  `OpenApi.fromApi(Http.api.annotate(OpenApi.Transform, (document) => …))`, or make the value an
+  input.
+- The document and the clients list every action of the binding, served or not. An action no
+  layer serves answers 404.
+- An OAuth protected resource is documented as a bearer scheme: Effect has no OAuth scheme
+  ([Authentication.md](Authentication.md#publish-oauth-discovery)).
+- Serve the binding with `ActionHttp.layer`, never with the native `HttpApiBuilder`.
+- One document over several bindings, `HttpApi.make("app").addHttpApi(A.api).addHttpApi(B.api)`,
+  works only when their prefixes differ and no action name repeats. Otherwise document each alone.
+
+## Call the API from Effect
+
+`ActionHttp.client` yields a client with one method per action.
 
-// Every endpoint declares the built-in refusals, so the 401 the authentication
-// renders arrives as a typed `Unauthenticated`, not a decode error.
-const refused = Effect.gen(function* () {
+```ts
+Effect.gen(function* () {
   const client = yield* ActionHttp.client(Http, { baseUrl: "http://127.0.0.1:3000" });
 
-  return yield* Effect.flip(client.whoAmI());
-});
-
-await Effect.runPromise(
-  Effect.all([lookup, refused]).pipe(
-    Effect.tap(Console.log),
-    Effect.provide(FetchHttpClient.layer),
-  ),
-);
-```
-
-The argument may be omitted when `{}` is a valid encoded input, such as for an action declared
-without `input` (`client.whoAmI()`) or one whose fields are all optional or have a decoding
-default, in a struct or a class; omitting it sends the input `{}` decodes to. Other headers also go through `transformClient`
-(`HttpClient.mapRequest(HttpClientRequest.setHeader("x-agent", agent))`). The options are the
-native `HttpApiClient.make` options except `transformResponse`, which may change a call's
-success, failure or required services, which the method types cannot follow; use
-`transformClient`, or the native client.
-
-`transformClient` sees every response before the contract decodes it, so a status is read
-there whatever its body: a page told that its session ended, by the contract's 401 or a
-proxy's, with
-`HttpClient.tap((response) => Effect.sync(() => { if (response.status === 401) signedOut(); }))`.
-The call still fails as typed, with `Unauthenticated` or an `HttpClientError`.
-
-### Promise callers
-
-Code that holds a client outside an Effect, such as a browser app, builds it once with
-`fetchClient(Http, options?)`: `client` over `fetch`, its methods the same Effects, requiring
-nothing. Each call runs with `Effect.runPromise`.
-
-```ts example=promise-client.ts
-import { Effect } from "effect";
-import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
-import { Http } from "./binding.js";
-
-// Built once, outside any Effect: its methods need nothing more.
-export const api = ActionHttp.fetchClient(Http);
-
-// A promise per call. A declared error rejects it as its decoded value, so
-// `error instanceof UserNotFound` holds in a `catch`.
-export const userName = async (id: string): Promise<string> =>
-  (await Effect.runPromise(api.getUser({ id }))).name;
+  yield* Console.log(yield* client.greet({ name: "Ada" }));
+}).pipe(Effect.provide(FetchHttpClient.layer), NodeRuntime.runMain);
 ```
 
-A declared error rejects the promise as its decoded value, so `catch` code matches it with
-`instanceof`. A call sends with the `fetch` option, such as one sending the page's cookies,
-`(input, init) => fetch(input, { ...init, credentials: "include" })`; without it, with the
-global `fetch` as the call finds it, so a test's stub installed after the client is built is
-used. A `fetch` of your own keeps `init.signal`, which aborts the request when its call is
-interrupted: a deadline is `Effect.timeout` on the call,
-`api.getUser({ id }).pipe(Effect.timeout("5 seconds"))`, not a signal that replaces it.
-In a browser, relative routes resolve against the page; elsewhere, give `baseUrl`.
-
-## Rules
-
-- The binding decides what HTTP serves: the actions passed to `make`, and no others; an action has no HTTP switch. To keep an action off HTTP, leave it out of the list. Its implementation may still hold it for MCP, a Toolkit or `ActionCli.make`, which serve the actions their `actions` option lists, or every action of the implementations without it.
-- Action names are unique within a binding. Two bindings with different prefixes may reuse a name and be served side by side, but not combined into one `HttpApi`.
-- `layer(Http, implementations)` mounts the routes of the binding's actions among the implementations it receives, matched by identity: the exact contract values passed to `make`. Their other actions get no route, and their names are not checked. `actions` narrows it to the listed ones, each of the binding's and held by an implementation, as on every surface ([guarantees.md](guarantees.md#names)); an implementation holding none of those served is left out, and not built. Implementations holding none of the binding's actions at all are refused when `layer` is called, as the wrong implementations or the wrong binding. An equal-looking copy of a bound action is not the bound action, so it is not served.
-- An action may be served once per call; two implementations there may both hold an action the binding leaves out. An action no layer serves still appears in `Http.api`, OpenAPI and clients, and answers 404.
-- The binding is plain data: `layer` and `client` read everything from its fields, so a copy of the binding, or one made by another installed copy of the package, serves the same.
-- One layer serves a binding's public and protected actions, from one implementation or several. Each action's contract decides: a protected route is authenticated by the binding's descriptor, before its body is read ([guarantees.md](guarantees.md#authorization)), and a public one is open, ignoring any credential. A binding holding a protected action names its descriptor, and the layer serving it requires the descriptor's provider ([Authentication.md](Authentication.md#rules)); a layer serving only public actions, of a binding or an implementation holding protected ones too, requires none.
-- Router middleware provided to a `layer` call covers that call's routes, before their authentication, and no others. Several layers over one binding, such as one per area of the host, still share one binding, one document and one client.
-- `middleware` takes native `HttpApiMiddleware` services, which run around every route the layer serves, inside a protected route's authentication and outside its content-type and schema checks, so they see a decoding failure as the failure of `route`. The first listed is innermost, as native `.middleware` chaining is. The layer requires each one's service, and owes what each requires, less what one further out provides, in that order; a list not written as a tuple, or options whose `middleware` may be absent, owe what any of them requires, and provide nothing. `layer` takes options or none; an explicit type argument naming middleware requires the options argument, and a misspelled option beside `middleware` is a type error. A reusable options value names its tuple, `ActionHttp.LayerOptions<readonly [typeof Audit]>`, or is written `as const`: bare `ActionHttp.LayerOptions` takes no middleware.
-- A layer middleware may require the identity only where every action the layer serves is protected: on a layer serving a public action too, the identity stays owed. List the protected actions in its `actions`, and serve the public ones from another layer: `ActionHttp.layer(Http, users, { actions: [RenameUser], middleware: [Audit] })` beside `ActionHttp.layer(Http, users, { actions: [GetUser] })`. Options whose `actions` may be absent narrow nothing.
-- A layer middleware fails only with the binding's `error` or a built-in error, and needs no client: anything else is a type error, since clients decode only what the binding and every endpoint declare ([Binding errors](#binding-errors)). A middleware refusing a caller, such as an address allowlist, fails with `Action.Forbidden`, which needs no binding error. It is where a limit keyed by the caller runs before decoding, so it counts input that does not decode too; a limit after decoding, on every surface, is the handler's, failing with an error the contract declares ([Action.md](Action.md#implementations)). A middleware observing failures uses `Effect.onExit`, not `Effect.map`, which a failure skips. A step-up refusal is answered as it leaves the layer's middleware: one that recovers from it keeps its own response, and one that turns it into another error the binding declares answers with that error ([guarantees.md](guarantees.md#authorization)). MCP endpoints take no layer middleware.
-- Authorization, builders, request-time services and headers follow [guarantees.md](guarantees.md): `ActionHttp` itself sets no header.
-- `Http.api` is a plain `HttpApi`, which Effect's own tools document and call: `OpenApi.fromApi`, `HttpApiSwagger.layer`, `HttpApiScalar.layer`, `Http.api.addHttpApi(other)` to combine with other APIs, `HttpApiClient.make`. Serve it with `layer`, not the native `HttpApiBuilder`: its protected endpoints carry the descriptor's native security middleware, which `layer` satisfies with the provider and the native builder lacks.
-- The endpoints are one top-level group named after the mount path, so the native client exposes them as `client.<action>({ payload })`.
-- Bindings combine into one host API with the native `addHttpApi` method, `HttpApi.make("app").addHttpApi(Http.api)`, for one document or one native client, only when their prefixes differ and no action name repeats across them. An operation ID is the action name, and a group is keyed by its mount path. Serving several bindings with `layer` has neither limit.
-- Serve the OpenAPI document as a native route: `HttpRouter.add("GET", "/api/openapi.json", HttpServerResponse.jsonUnsafe(OpenApi.fromApi(Http.api)))`. It documents every bound action, not only the served ones. It is a plain route: middleware provided to its layer covers it, and nothing covers it otherwise.
-- A route runs only a request typed as JSON: any other type, or none, is a 415, after authentication on a protected route, as on an MCP endpoint, whatever encoding the input is annotated with, such as `HttpApiSchema.asFormUrlEncoded()`, which `HttpApi` would read and no other surface does. So no request a page on another origin can send without a CORS preflight reaches a handler, whatever credentials, cookies included, it carries; one typed as JSON is preflighted, and the host's CORS policy decides.
-- A media field, `Action.Image`, is JSON in the body: `{ "data": "<base64>", "mimeType": "image/png" }`, as Effect's JSON codec encodes a `Uint8Array`. The OpenAPI document lists `data` as `type: string`, `format: byte`, `contentEncoding: base64`, as Effect's JSON Schema does, and `client` decodes it to a `Uint8Array`. Only MCP lifts it into a block of its own ([ActionMcp.md](ActionMcp.md#media)).
-- Wire format: [guarantees.md](guarantees.md#wire-behavior). Spans and log annotations: [guarantees.md](guarantees.md#observability).
-
-### Binding errors
-
-- The binding's `error`, one schema or a list, is what middleware answers with, on any endpoint, router middleware around the routes and the layer's own `middleware` alike: `ActionHttp.make(actions, { error: RateLimited })`. A binding holds it as a list, `Http.error`. Every endpoint declares them, OpenAPI shows them, and every client decodes them.
-- Middleware sends one as the binding declares it, at the status its `httpApiStatus` states, or 422 without one: for `class RateLimited extends Schema.TaggedError<RateLimited>()("RateLimited", {}, { httpApiStatus: 429 }) {}`, `HttpServerResponse.schemaJson(RateLimited)(error, { status: 429 })`. A union with its own `httpApiStatus` uses that status for every member; otherwise, each member of a plain union is declared at its own status, or 422 without one.
-- No handler fails with them: it serves every surface, and only HTTP declares them. An action whose handler fails with one lists it in its own `error`, a limit after decoding included ([guarantees.md](guarantees.md#authorization)). A layer middleware fails with them as a native `HttpApiMiddleware` does, declaring the error, `{ error: RateLimited }`, which the binding declares too.
-- They may not reuse a built-in error's tag: `make` refuses such a binding.
-- Options that may leave `error` out, such as a value annotated `ActionHttp.Options<readonly [typeof RateLimited]>`, declare those errors or none, `readonly [typeof RateLimited] | []`, as the binding has at run time: clients decode each that may arrive, and a layer middleware failing with one is a type error, since the binding may lack it. Give `error` inline, or in a value whose type requires it. Explicit type arguments naming `error` require the options argument, which alone holds them. A layer middleware may fail only with an error the binding surely declares: one in a slot of its own in a list of fixed length, inline `error: RateLimited`, not in an array of unknown length, `[RateLimited, ...more]` included, which may be empty, a slot that may hold either of several, or options whose `error` may be either of two lists.
-
-### Security
-
-- OpenAPI security follows each contract's `caller`. Every protected endpoint carries the descriptor's native security middleware, the one that enforces it: `OpenApi.fromApi`, `HttpApiSwagger` and `HttpApiScalar` show its scheme in `components.securitySchemes`, keyed by the descriptor's name as it is, `example.Login`, and `[{ "example.Login": [] }]` as the operation's requirement, and a public endpoint states `security: []`. A combined document keeps each binding's: distinct descriptors have distinct names, so their schemes never share a key ([Authentication.md](Authentication.md#rules)).
-- The document and the routes cannot disagree: no option documents a scheme the routes do not enforce, or a public action the routes protect.
-- Effect has no OAuth or OpenID Connect scheme, so an OAuth protected resource is documented as a bearer scheme; its discovery is the provider's ([Authentication.md](Authentication.md#rules)).
-- Clients read none of it: a client sends what `transformClient` adds, whatever the document says.
-
-### Client methods
-
-- A method fails with what the native client fails with, but for input: input that does not encode is `InvalidInput` with its `issues`, as every surface answers it, and nothing is sent. Declared errors arrive as their decoded values: the action's own, the binding's, and the three built-in errors every endpoint declares. Match them with `Effect.catchTag`.
-- Anything the contract does not account for is Effect's own error:
-  - `HttpClientError` with `response` `undefined`: the server could not be reached.
-  - `HttpClientError` with `reason._tag` `DecodeError`: the server answered with a status no schema declares, such as the empty 500 of a defect.
-  - `HttpClientError` with `StatusCodeError`: a declared status whose body did not decode.
-  - `SchemaError`: the success body did not decode.
-- The library interprets no status. Which failures mean "signed out" or "try again" is the caller's decision.
-- Nothing is retried. A failed write may or may not have happened; only a declared error says what the server did.
-- Every action of the binding has a method, whether or not a server serves it. An unserved action answers 404 with no body, so its method fails with `HttpClientError`: `DecodeError`, or `StatusCodeError` when the action declares a 404 error, whose body the empty response is not.
-- A given argument is sent as given: `null` or `undefined` is the input itself, for a schema that accepts it.
-- The client holds no connections or timers. `client` builds the native client once from the `HttpClient` in context.
-- The native client stays available: `HttpApiClient.make(Http.api)` has the same routes, with methods taking `{ payload }`.
-- In a browser, import the binding from a module with no server code, so the bundle keeps the client alone ([setup.md](setup.md#browser)).
-- In tests, provide `Testing.layer(routes)` instead of a network client; `baseUrl` may be left out ([Testing.md](Testing.md)). `Action.client` has the same methods in process, for what an implementation does without the wire ([Action.md](Action.md#clients)).
-
-### Built-in errors
-
-- Every endpoint declares the built-in errors ([guarantees.md](guarantees.md#wire-behavior)). `client`, a remote `ActionCli` command and the native `HttpApiClient` decode them as typed failures, and OpenAPI shows them on every operation. They cannot be left out; the binding's `error` add to them.
-- `InvalidInput`'s `message` is the schema's own description of every issue, and `issues` lists each by its path: `{"_tag":"InvalidInput","message":"Expected string\n  at [\"name\"]","issues":[{"path":["name"],"message":"Expected string"}]}`.
-
-## Failure modes
-
-- Route returns 404: the action is not in the binding, its implementation was never passed to a `layer` call, or the path lacks the prefix. An implementation's action is served only if the binding holds that very value: an equal-looking copy, such as a test declaring the contract again, is not.
-- `No action of these implementations is in this HTTP binding: x` thrown by `layer`: none of the implementations' actions was passed to this binding's `make`, so they are the wrong implementations or it is the wrong binding. `x (another contract)` is an action of a bound name that is not the bound value, as a second copy of the contracts module makes: implement the exact contract value the binding received. Matching names and schemas do not establish identity.
-- `Authentication "<name>": the binding's descriptor is not its provider's`, a defect when `layer` builds: the binding and `Authentication.layer` were given two descriptors of one name. Build both from one descriptor ([Authentication](Authentication.md#failure-modes)).
-- `Listed in actions, but the binding does not hold it: <names>`, or `but no implementation holds it`, thrown by `layer`: those actions are not among the binding's or the implementations', by identity. `(another contract)` marks one whose name the binding holds.
-- `Duplicate served action: <name>`: one `layer` call received two implementations of the same bound action.
-- `Duplicate middleware: <key>` thrown by `layer`: its `middleware` lists one middleware twice, which a native endpoint would run once. List it once.
-- `Method 'POST' already declared for route '<prefix>/<action>'` when the host builds: two `layer` calls serve the same action, such as one implementation given to two layers of one binding. Serve each action in one call: one layer serves public and protected actions alike, or give each layer its own `actions`.
-- `ActionHttp binding: error _tag "Forbidden" is built in, and declared on every surface` thrown by `make`: a binding error has a built-in tag, or is a built-in error. Drop a built-in error, which every endpoint declares already; rename an error of your own.
-- `Duplicate action: <name>` thrown by `make`: two actions share a name, or one action value is listed twice. Rename one, or bind it under another prefix.
-- `Duplicate OpenAPI operationId: <name>` from `OpenApi.fromApi` on a combined API: two combined bindings have an action of that name. Rename one, or document each binding on its own.
-- A combined document or native client lacks one binding's actions: two combined bindings share a prefix, so one group replaced the other. Give each its own prefix, or bind the actions together.
-- `Provider<CurrentActor, "example.Login">` among the layer's requirements, or `Type 'Provider<...>' is not assignable to type 'never'` where the server is launched: the layer serves a protected action and its descriptor's provider is not provided. Provide it, `Layer.provide(authenticate)` ([Authentication.md](Authentication.md#failure-modes)). Nothing else stands in for it.
-- `Type 'X' is not assignable to type 'never'` where the server is launched, or `Request<"Requires", X>` in the layer's type: a handler or the authorizer yields a request service `X` that no middleware around the layer provides. Provide it with router middleware, or `HttpRouter.provideRequest`; never an identity at startup. `X` the identity on a layer serving public actions: a public handler reads it, or a layer middleware requires it. No public route gets an identity: make the action protected, or serve the middleware's protected actions from a layer of their own ([Rules](#rules)).
-- `No overload matches this call` at `make`, its last overload naming `"Protected actions take options naming their authentication"`, or a type error naming `authentication`: the binding holds a protected action and names no descriptor, or one of another identity. Give `{ authentication: Login }`, never `caller: Action.Anyone` on the contract to silence it.
-- `Argument of type 'Options<…> | undefined' is not assignable` at `make`: a helper forwards options that may be absent. `make` takes options or none, two forms, so pass `options ?? {}`.
-- A type error on `middleware` naming `"Layer middleware fails only with the binding's errors and needs no client"`: a middleware declares an error neither the binding nor the built-ins hold, or a client counterpart. Add the error to the binding's `error`, or, for a limit after decoding on every surface, move it to the handlers, declaring it on their actions.
-- A route answers without credentials: its contract is `caller: Action.Anyone`. Make it protected; its route is then authenticated, whatever its handler reads.
-- A protected route answers 401 to a request missing its content type or sending invalid input: it presented no credential that verifies, and authentication runs before anything reads the body. Send the token, then the content type and the input are checked.
-- Swagger shows no Authorize button: the binding holds no protected action.
-- `Service not found: effect-actions/Authentication/Security/…` when the host builds: `Http.api` of a binding holding a protected action is served with the native `HttpApiBuilder`. Serve it with `layer`.
-- 400 `InvalidInput` on a valid-looking request: its `message` names each field that did not decode, or that the action does not declare, such as a misspelling. An action without input takes only `{}`, and a body.
-- 415 `Unsupported content-type: <type>` (`none` when it has none): the request is not typed as JSON. It has another content type, such as `fetch`'s default `text/plain` for a string body, or none, as for a `Blob` body. Send `Content-Type: application/json`, as the clients do.
-- Empty 500: a defect, or a handler result that does not match the success schema. The cause is in the server's logs.
-
-### Client methods
-
-- Fails with `HttpClientError` whose `reason._tag` is `DecodeError` for a status such as 429: the server answered with a status no schema declares. Declare that error on the binding, `make`'s `error`, when router middleware answers with it; on the action when its handler does; or handle the native error. The built-in 400, 401 and 403 always decode, as long as their body is the built-in error's JSON.
-- Fails with `HttpClientError` whose `reason._tag` is `InvalidUrlError` outside a browser: `baseUrl` is omitted, and there is no page to resolve relative routes against. Set `baseUrl`.
-- Type error listing `HttpClient` as an unsatisfied requirement of `client`: provide one, such as `FetchHttpClient.layer`.
-- Property does not exist on the client: the action is not in the binding.
-- `Expected 1 arguments`: `{}` is not a valid encoded input for the action, so it needs its input.
-- Type error passing `undefined` to a method whose argument may be omitted: leave the argument out instead.
-- Fails with `InvalidInput` `Expected Filters` given a plain object, which TypeScript may let through: the input is a class, `Filters`, which encodes only its instances. Pass `new Filters({ ... })`, or leave out an argument whose fields are all optional.
-- Type error passing `{ payload: ... }`: that is the native client's shape. These methods take the input itself.
+Files: [quickstart/src/client.ts](../examples/quickstart/src/client.ts),
+[kitchen-sink/src/seed.ts](../examples/kitchen-sink/src/seed.ts) (`baseUrl` from `Config`,
+headers, errors by tag).
+
+- Outside a browser, set `baseUrl`. A token or any other header goes through `transformClient`.
+  Where no client is built by hand, as under `ActionCli.remote`, transform the `HttpClient`
+  itself (`connection` in [notes-service/src/commands.ts](../examples/notes-service/src/commands.ts)).
+- Leave the argument out when `{}` is a valid input. A given argument is the decoded input, so
+  it states a defaulted field.
+- A declared error is a typed failure, as its decoded value: the action's own, the binding's,
+  the verifier's, and the built-in `InvalidInput`, `Unauthenticated` and `Forbidden`. Handle
+  each with `Effect.catchTag`.
+- Anything else is Effect's own: an `HttpClientError` when the server could not be reached or
+  answered with a status or body the binding does not declare, such as a defect's empty 500; a
+  `SchemaError` when the success does not decode.
+- The client interprets no status and retries nothing. A failed write may have happened; only a
+  declared error says what the server did.
+- A handler calling another service through this client maps that service's `Unauthenticated`
+  and `Forbidden` before failing with them
+  ([Action.md](Action.md#fail-with-declared-and-built-in-errors)).
+- In a test, provide `Testing.layer(routes)` instead of a network client and leave `baseUrl` out
+  ([Testing.md](Testing.md#test-routes-in-memory),
+  [notes-service/test/routes.test.ts](../examples/notes-service/test/routes.test.ts)).
+
+## Call the API from a browser
+
+Code outside an Effect builds the client once with `ActionHttp.fetchClient` and runs each call
+with `Effect.runPromise`. Files:
+[notes-service/src/browser.ts](../examples/notes-service/src/browser.ts),
+[kitchen-sink/src/sdk.ts](../examples/kitchen-sink/src/sdk.ts) (a `baseUrl`, two headers).
+
+- A page on another origin passes `baseUrl`, and the server must allow that origin with
+  `HttpRouter.cors`
+  ([kitchen-sink/src/request-policy.ts](../examples/kitchen-sink/src/request-policy.ts), `cors`).
+- An unhandled declared error rejects the promise as its decoded value, so
+  `error instanceof Action.Unauthenticated` works in a `catch`. Handle an expected one by its tag
+  before `Effect.runPromise`.
+- A page on the API's own origin sends its cookies already. From another origin, pass `fetch`:
+  `(input, init) => fetch(input, { ...init, credentials: "include" })`, and allow credentials in
+  the server's CORS, `HttpRouter.cors({ allowedOrigins, credentials: true })`. A `fetch` of your
+  own keeps `init.signal`, which aborts the request when its call is interrupted: a deadline is
+  `Effect.timeout` on the call.
+- A route answers a request not typed as JSON with 415, so what another site's page can send
+  without a CORS preflight, such as a form post carrying the user's cookie, never reaches a
+  handler; the server's CORS policy decides the rest.
+- The page imports the binding from a module with no server code
+  ([setup.md](setup.md#bundle-for-a-browser)).

package/docs/ActionMcp-failures.md

@@ -0,0 +1,31 @@
+# ActionMcp failure modes
+
+Search for a fragment of the message. The tasks are in [ActionMcp.md](ActionMcp.md).
+
+- `MCP tool input must be one object with keys, such as a struct: <name>, ...`: those actions' input is a union, an array, a scalar, or an object without keys such as `Schema.Struct({})`. Wrap it in a field, `input: { notification: Schema.Union([Email, Sms]) }`, omit `input` for no arguments, or leave the action out of `actions`.
+- `MCP media must be the success or an array of it, or a top-level field of a struct success, one, optional or a required array: <name>, ...`: those actions hold an `Action.Image` no tool can send as a block. Make it a top-level field of a `Schema.Struct` success, give an optional array as a required one, empty when absent, or leave the action out of `actions`.
+- `Duplicate MCP tool: <name>`: two implementations serve actions of one name. Split the endpoint or rename one. `actions` tells apart only separate contracts sharing a name; of two implementations of one contract, pass one.
+- `Duplicate MCP tool: <name>, claimed by an action and a native feature`, a defect when the endpoint builds: a native tool among `features` has an action's name. Rename it, or leave the action out of `actions`.
+- `Listed in actions, but no implementation holds it: <names>`: those actions are not among the implementations', by identity. `(another contract)` marks one whose name an implementation holds, as a second copy of the contracts module makes. Pass the implementation holding it, or list the contract it implements.
+- `Property 'authentication' is missing` on `layerHttp`'s options: the endpoint serves a protected action and names no descriptor. `Type 'Other' is not assignable to type 'CurrentUser'` on `authentication`: the descriptor is another identity's. Give the protected actions' descriptor.
+- `Authentication "<name>": the binding's descriptor is not its provider's`, a defect when `layerHttp` builds: give the endpoint the descriptor its provider was built from ([Authentication-failures.md](Authentication-failures.md)).
+- `Type 'X' is not assignable to type 'never'` where the server is launched, or `Request<"Requires", X>` in an MCP endpoint's type: a handler or an authorizer yields a request service no middleware around the endpoint provides. Provide it with router middleware; never an identity at startup. `X` the identity, on an endpoint serving public tools: a public handler reads it, which no public tool gets, signed in or not. Make that action protected.
+- `Type 'CurrentUser' is not assignable to type 'never'` where the server is launched, with `CurrentUser` among an MCP endpoint's startup requirements, not its `Request<"Requires", ...>`: a native feature reads a request service, which features never receive. Serve that content as an action.
+- `Type 'CurrentUser' is not assignable to type 'never'` at a stdio program's `runMain`: it serves a protected tool, whose caller the host supplies. Provide the identity around `runStdio`.
+- A native resource, prompt or toolkit layer is never served (`resources/list` is empty, `prompts/list` is not found, `tools/list` lists only the actions): an endpoint serves only the native layers passed as its `features`; one merged beside it builds without error. Pass it as `features`.
+- A prompt or resource demands credentials: on an endpoint naming `authentication`, every prompt and resource request needs one. Serve them on an endpoint without protected tools.
+- A public tool's call answers 401: a public tool needs no credential, but one a request presents is still verified, and this one failed. Send a valid one, or none.
+- A protected tool's call answers 401 to a signed-in client after a while: its token expired. The client refreshes it, or signs in again, on the challenge's `invalid_token`.
+- An MCP client gets an `isError` refusal, not the 401 or 403 it re-authorizes on: the handler sent a notification first, which starts the response, so its refusal is a tool result. Refuse in `authorize`.
+- A client that opens with `initialize` gets 401 where it lists the tools or calls a public one, on an endpoint that also serves protected tools: a session's every request authenticates. Sign the client in, or serve the public tools on an endpoint of their own.
+- A request over HTTP answers 400, `MCP-Session-Id header is required; send initialize to start a session`: its `MCP-Protocol-Version` header is absent or names a 2025 revision, so it is a session's request, and it follows no `initialize`. One answering 404 names a session that ended, or one of a process since restarted: the client opens another.
+- A hand-written HTTP request answers 400 with JSON-RPC error `-32602`, `Required request metadata is missing` or `io.modelcontextprotocol/clientCapabilities request metadata is required`: it names 2026-07-28 in `MCP-Protocol-Version` and its `params._meta` lacks `io.modelcontextprotocol/protocolVersion`, for the first message, or `io.modelcontextprotocol/clientCapabilities`, for the second. Build it with `Testing.mcpRequest`, or copy the `curl` of [ActionMcp.md](ActionMcp.md#serve-tools-over-stdio).
+- A hand-written HTTP request answers 400 with JSON-RPC error `-32020`, `MCP-Protocol-Version header is required`, `Mcp-Method header does not match request method` or `Mcp-Name header does not match request parameters`: those headers repeat a 2026-07-28 request's revision, method and `tools/call` name, and one is absent or differs from its body. Build it with `Testing.mcpRequest`.
+- A hand-written HTTP request answers an empty 406: its `Accept` header does not list both `application/json` and `text/event-stream`, as `*/*` does not. Send both.
+- A client asking for 2025-03-26 or 2024-11-05 is offered 2025-11-25, and disconnects if it cannot speak it: HTTP and stdio serve 2026-07-28, 2025-11-25 and 2025-06-18. Update the client.
+- A request written by hand to a stdio server answers JSON-RPC error `-32602`, `Invalid request metadata`: it is neither preceded by `initialize` nor carries the 2026-07-28 metadata. Open with `initialize` and `notifications/initialized`, or give the request's `_meta` its `io.modelcontextprotocol/protocolVersion` and `io.modelcontextprotocol/clientCapabilities`.
+- A client reports a broken transport from a stdio subprocess: something wrote to stdout. The global `console.log` did, or a layer provided around `runStdio` did, through the default logger, or through `Console` or a logger such as `Logger.consoleJson`, which `logToStderr` does not move. Remove the write, apply `ActionCli.logToStderr` last, or log JSON with `Logger.withConsoleError(Logger.formatJson)`.
+- A request carrying an `Origin` gets an empty 403: the origin is not in `allowedOrigins`. Add the exact origin, if the deployment trusts it.
+- A disallowed `Origin` gets 401, not 403: the endpoint's authentication, which runs before its Origin check, refused the request.
+- Browser calls fail despite an allowed origin, the preflight answering 405, or 401 on an endpoint with `authentication`, which every method but `POST` meets first: `allowedOrigins` is no CORS. Add `HttpRouter.cors` ([browser clients](ActionMcp.md#allow-browser-clients)).
+- `Tool <name> has an output schema but did not return structured content` raised by a Python MCP client for an action that returns nothing: its success is sent as `null`, which a Python SDK release before the fix of python-sdk#3345 reads as missing. Update the SDK.