@toa.io/extensions.exposition 1.0.0-alpha.291 → 1.0.0-alpha.293

package/documentation/io.md

@@ -1,167 +0,0 @@
-# I/O restrictions
-
-The Exposition comes with `io` directives to control access to the operation's input and output
-properties, and to let an operation state the status of its reply.
-
-## Input
-
-The `io:input` optional directive contains a list of properties that are allowed to be specified in
-the request body.
-
-```yaml
-POST:
-  endpoint: create
-  io:input: [name, location]
-```
-
-The list must be a valid subset of the operation's input properties.
-
-If `io:input` is specified and the request body is not an object, or contains properties that are
-not in the list, the request will be rejected with a `400` status code.
-
-> Therefore, `io:input` is only applicable to operations which input is an object or an
-> array of objects.
-
-## Output
-
-The `io:output` mandatory directive contains a list of properties that are allowed to be included in
-the response body.
-
-```yaml
-GET:
-  endpoint: observe
-  io:output: [name, location]
-```
-
-When an operation does not return an object (e.g., a primitive or a stream), or an object is dynamic
-and its properties are not known in advance, `io:output` may have a value of `true` to disable
-output restrictions.
-
-```yaml
-GET:
-  endpoint: proxy
-  io:output: true
-```
-
-If a method declaration lacks `io:output` directive, it will trigger a warning, and its
-response will consistently be empty.
-If this behavior is intended, a `false` value can be employed to suppress warnings.
-
-```yaml
-GET:
-  endpoint: conceal
-  io:output: false
-```
-
-Output restrictions are not applied to stream responses, nor to a reply the gateway built out of an
-exception — an operation that returns an error is answered with a code and a message of the
-gateway's own, and a list of permitted properties has nothing to say about those. A reply the
-operation returned is restricted whatever status it carries, see [Status](#status).
-
-## Status
-
-The `io:status` optional directive names a property of the reply that carries the status of the
-response. The property is removed from the body.
-
-```yaml
-POST:
-  endpoint: register
-  io:status: status
-  io:output: [client_id, client_name, error, error_description]
-```
-
-```javascript
-return { status: 400, error: 'invalid_redirect_uri' }
-```
-
-```http
-400 Bad Request
-
-error: invalid_redirect_uri
-```
-
-A reply that does not carry the property is answered with the status it would have been. A property
-that is not a number is an error.
-
-This is for an outcome the operation knows and the transport does not — a protocol that states its
-error as a body rather than as a status of its own, or a request that created where it might have
-updated. Such an operation returns no error: both replies are its output, and `io:output` permits
-the properties of both. An operation that does return an error is unaffected — that reply is the
-gateway's, and is not restricted.
-
-## Throttling
-
-The `io:throttle` directive limits the rate of requests meeting the specified criteria.
-
-```yaml
-exposition:
-  /:
-    io:throttle:
-      key:
-        - route
-        - ip
-      condition:
-        status: 404
-      requests: 500
-      interval: 30
-```
-
-Requests are metered per `key`. A key may spend `requests` at once, and earns them back at a rate of
-`requests` per `interval` seconds. A request carrying a key with nothing left to spend is answered
-`429 Too Many Requests`, with a `Retry-After` saying how long until one would be admitted again.
-`interval` is in seconds.
-
-So `requests` is the burst, and `requests / interval` the rate it is repaid at. There is no window to
-save a budget up in and spend twice across the edge of, and no lockout to sit out: a key that has
-overspent is admitted again as soon as it has earned a single request back, and a client that keeps
-asking meanwhile is not penalised for it.
-
-`requests` is a budget for the **whole group** of gateway instances, not for one of them. Instances
-reconcile through Redis on a timer, so they converge on one number rather than each enforcing the
-limit separately. Between two of those, an instance goes on what it alone has spent — so the group
-can overshoot by what the other instances admit within that window, and by no more. The window is a
-tenth of `interval`, between a quarter of a second and two seconds, whatever `interval` is. Precise
-per-request enforcement is not what this is for.
-
-An instance that cannot reach Redis keeps throttling on what it has seen itself and keeps serving,
-and reports what it could not the next time it gets through.
-
-### Key components
-
-What a request is metered against. Give one, or a list — a list keys on the combination, so
-`[route, ip]` meters each address separately on each route.
-
-- `ip` — the client address, as the request context resolved it. See [Client address](ip.md) for
-  where it is read from and why.
-- `path` — the path the request came in on, `/users/1`.
-- `route` — the route as declared, `/users/:id`. Every path matching the route shares one budget,
-  which `path` cannot do: keyed on `path`, walking ids is a way around the limit.
-- `identity` — the authenticated identity. Requests carrying none share a single budget between
-  them, so pair it with `ip` if that matters.
-- `segment: <name>` — the value bound to a named route segment, `1` for `:id` in `/users/:id`.
-
-### Conditions
-
-What is metered, as opposed to what it is metered against. A request that fails a condition is served
-and costs nothing. Conditions are evaluated against the response, so they cannot decide whether to
-refuse a request — only whether it is charged for, once it has been answered.
-
-- `status: <code>` — charge only for responses with this status.
-
-```yaml
-io:throttle:
-  key: ip
-  condition:
-    status: 404
-  requests: 20
-  interval: 600
-```
-
-An address may probe for twenty missing paths at once, and thereafter for one every thirty seconds.
-Requests that find something are served and never counted against it.
-
-## Introspection
-
-What these admit is what [`OPTIONS`](introspection.md) states: `io:input` restricts the input
-schema, `io:output` the output schema, and a method declaring no `io:output` states no output at
-all — nothing of the reply is sent.

package/documentation/ip.md

@@ -1,24 +0,0 @@
-# Client address
-
-The address a request comes from is resolved once, into the request context, and read from there
-by whatever keys on it: the meter of [failed authentications](identity.md#failed-authentications)
-and the `ip` key of [`io:throttle`](io.md#key-components).
-
-```yaml
-# context.toa.yaml
-
-exposition:
-  ip: cf-connecting-ip
-```
-
-`ip` names the header the address is read from. In production the gateway sits behind a load
-balancer, an ingress or a CDN: the connection it accepts comes from that machine, so every client
-shares one address and nothing tells them apart. The edge is the one that saw the client connect,
-and it writes the client's address into a header of its own, `CF-Connecting-IP`, `X-Real-IP` or
-`X-Forwarded-For`, depending on the infrastructure. A client may send any of these headers too, so
-the gateway trusts none of them on its own: the deployment names the one its edge overwrites, and
-where the header holds a list, the last value is the one the edge appended.
-
-The connection's address is never used. Without `ip`, or for a request that does not carry the
-header, the request has no address: the bouncer and a throttle keyed on `ip` let it through and
-say so in the log, once per hundred seconds rather than once per request.

package/documentation/map.md

@@ -1,123 +0,0 @@
-# HTTP context mapping
-
-The `map` directive family is used to map HTTP request parts to operation call input properties.
-
-[Features](../features/map.feature).
-
-## TL;DR
-
-```yaml
-exposition:
-  /:group:
-    languages: [en, fr] # supported languages
-    GET:
-      map:authority: hostname # request authority (e.g., hostname)
-      map:language: lang # requested language
-      map:headers: # raw header values
-        token: x-access-token
-      map:buffer: body # unparsed request body
-      map:segments: # route parameters
-        group: group
-      map:claims: # Bearer token claims
-        address: email
-        verified: email_verified
-      endpoint: observe
-```
-
-The operation input type must be an object.
-If the input already contains the specified keys, they will be overwritten.
-
-## Authority
-
-The `map:authority` directive maps the [authority identifier](authorities.md) to an operation call
-input property specified by the directive value.
-
-### Language
-
-The `map:language` mapping sets the [most matching](https://github.com/jshttp/negotiator) language
-code based on the `accept-language` request header and a list of supported languages defined by
-the `map:languages` directive, and also adds `accept-language` to the `Vary` HTTP response header
-value.
-
-If none of the supported languages match, the first supported language is used.
-
-> `map:languages` has a shorthand form: `languages: [en, fr]`.
-
-## Header values
-
-The `map:headers` directive maps the values of HTTP request headers to operation call input
-properties.
-The value of the directive is a map where keys are the names of the input properties and values are
-the names of the HTTP request headers.
-
-The names of these headers are then included in the `Vary` HTTP response header
-and [Access-Control-Allow-Headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Headers)
-of the [CORS](protocol.md#cors).
-
-[Multiple header fields](https://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.2) are combined
-as a comma-separated list.
-
-## Raw body
-
-The `map:buffer` directive maps the unparsed request body to an operation call input property.
-The directive value is the name of the input property.
-
-```yaml
-/webhook:
-  POST:
-    map:buffer: body
-    map:headers:
-      signature: x-signature
-    endpoint: verify
-```
-
-The body is read from the request stream as raw bytes and delivered as a UTF-8 string.
-
-Body parsing is bypassed, so the route does not depend on a supported `Content-Type` or format decoding. The request stream is consumed; a route with `map:buffer` cannot also receive a parsed body from the same request.
-
-## Route parameters
-
-The `map:segments` directive maps the values of route parameters to operation call input properties.
-The value of the directive is a map where keys are the names of the input properties, and values are
-the names of the route parameters.
-
-Parameter name may be prefixed with `~`
-to indicate that the parameter should not be available to the
-remaining directives or used as criteria in the operation call.
-
-```yaml
-/:id/:tag:
-  POST:
-    map:segments:
-      id: id
-      tag: ~tag
-    endpoint: create
-```
-
-Wildcard routes are supported by using `**` as the parameter name.
-
-```yaml
-/path/to/**:
-  GET:
-    map:segments:
-      path: '**'
-    endpoint: observe
-```
-
-## Bearer token claims
-
-The `map:claims` directive maps the values of
-the [token claims](https://datatracker.ietf.org/doc/html/rfc7519#section-4).
-The value of the directive is a map where keys are the names of the input properties and values are
-the names of the claims.
-
-If the claim is not present in the token or the request is not authenticated using
-the [`Bearer` scheme](identity.md#bearer-scheme), the input properties are not set.
-
-## Introspection
-
-A property a mapping fills is not the caller's to send, so [`OPTIONS`](introspection.md) takes it
-out of the input. `map:headers` states it under `headers`, naming the header it is read from, and
-`map:segments` under `route`, named as the property rather than as the segment. The rest —
-`map:claims`, `map:authority`, `map:language`, `map:buffer` — come from the request itself, and a
-caller has nowhere to put one.

package/documentation/mcp.md

@@ -1,183 +0,0 @@
-# Model Context Protocol
-
-An application annotates it, and the methods it names as tools are what a model may call.
-
-```yaml
-exposition:
-  mcp:
-    name: Teapots
-    instructions: A pot is read by its id. A pot that is brewing cannot be emptied.
-    origins: [https://claude.ai]
-```
-
-<dl>
-<dt><code>name</code></dt>
-<dd>Required. What the server calls itself, which a client shows a user.</dd>
-<dt><code>instructions</code></dt>
-<dd>What a model is told before it calls anything here.</dd>
-<dt><code>origins</code></dt>
-<dd>Browser origins the endpoint answers. A request carrying an <code>Origin</code> that is not
-listed is <code>403</code>, and an empty list admits none; a request carrying none is unaffected.</dd>
-<dt><code>anonymous</code></dt>
-<dd>Whether the endpoint answers without a credential. It does not unless it says so.</dd>
-</dl>
-
-Without the annotation `/.mcp` is a path like any other, and nothing answers there. The path is
-fixed: one an application could choose is one it could collide with a route of its own.
-
-## What a tool is
-
-A tool is an RTD method that says it is one, named as the [procedure](rpc.md#the-name) it is:
-
-```yaml
-/pots:
-  GET:
-    mcp:tool: true
-    help:method: Every pot there is, newest first.
-    endpoint: enumerate
-  /hot:
-    GET:
-      query: { criteria: temperature=gt=80 }
-      mcp:tool: true
-      help:method:
-        title: Hot pots
-        description: The pots that are too hot to pour.
-      endpoint: enumerate
-```
-
-A default denies, and a tree holds everything an application serves — its identity endpoints, its
-uploads, the machinery of the authorization flow the model already came through. Publishing all of
-it would spend a model's context on what it has no business calling.
-
-`mcp:tool` says only whether the method is published. What the tool is called and what it is for is
-[`help:method`](help.md), which is what describes the method everywhere else as well — a tool a
-model cannot read the purpose of is one it cannot choose, so declare one beside the other.
-
-A declaration is inherited by everything below it, as every directive is, and the nearer one wins —
-so a node publishes a subtree, and `mcp:tool: false` withdraws one method of it.
-
-A route whose name a client [cannot spell](rpc.md#what-has-a-name) is refused where the directive
-is built, rather than served as a tool that is quietly never listed.
-
-`tools/list` answers every published method this caller may reach — a method whose directives refuse
-them is not listed, and a route with [no name](rpc.md#what-has-a-name) is not either. `tools/call`
-answers `404` to a name that is not published, whether or not a route would have taken it: what an
-application did not publish is not reachable by guessing what it would have been called.
-
-`annotations` are read from the verb: `GET` and `HEAD` are `readOnlyHint`, `DELETE` is
-`destructiveHint`, `PUT` and `DELETE` are `idempotentHint`.
-
-## What a tool takes
-
-`inputSchema` is the procedure's `params`, which is what the method
-[says of itself](introspection.md): a route variable by the name the template gives it, the
-querystring under `query`, and what is left is the body. `io:input` restricts it, and a property
-`map` fills is not there — a call carries no headers of its own.
-
-`query` carries what selects records — `criteria`, `sort`, `limit`, `omit`, `search` — beside the
-parameters the resource declares. `OPTIONS` states only the latter, because the former is the same
-of every queryable resource; here it is stated, because here it is something the caller sends.
-
-```yaml
-type: object
-properties:
-  id: { type: string, pattern: ^[a-fA-F0-9]{32}$ }
-  query:
-    type: object
-    properties:
-      criteria: { type: string }
-      sort: { type: string }
-      limit: { type: integer, minimum: 1, maximum: 100, default: 10 }
-      omit: { type: integer, minimum: 0, maximum: 1000, default: 0 }
-required: [id]
-additionalProperties: false
-```
-
-## What a tool answers
-
-`content` carries one `text` block holding the reply's JSON, and `structuredContent` the reply
-itself. A reply of nothing is an empty `content`.
-
-`outputSchema` is what the operation declares, restricted by `io:output`. An operation's `output` is
-optional and normalizes to `{}`, which describes nothing, and none is stated for it — an
-application that wants the schema declares the operation's `output`.
-
-An operation that refuses answers a result with `isError: true` carrying its message, not an error
-of the protocol: it is something a model reads and may correct itself by.
-
-## Two revisions
-
-Both are answered from one endpoint that remembers nothing between requests.
-[`2026-07-28`](https://modelcontextprotocol.io/specification/2026-07-28) carries the version and
-the client's capabilities in every request; `2025-11-25` opens with `initialize`. Which one a
-request is, is read from `MCP-Protocol-Version`, or from
-`_meta['io.modelcontextprotocol/protocolVersion']` where the header is absent; `initialize` is one
-by itself, and a request naming no version is of a revision that sent none.
-
-| method                      |                                                                            |
-| --------------------------- | -------------------------------------------------------------------------- |
-| `server/discover`           | what is served, and who serves it                                          |
-| `tools/list`                | every tool this caller may reach, in a stable order                        |
-| `tools/call`                | the call the tool is                                                       |
-| `initialize`                | the same as `server/discover`, in the shape a client of `2025-11-25` reads |
-| `notifications/initialized` | `202`, and nothing done                                                    |
-| `ping`                      | `{}`                                                                       |
-
-`POST` only, one message per request; `GET` and `DELETE` are `405`. An `Mcp-Session-Id` is ignored
-and none is minted, a `Last-Event-ID` is ignored, and `accept` is negotiated as everywhere else.
-
-Of the modern revision, `MCP-Protocol-Version` and `Mcp-Method` are required, and `Mcp-Name` for a
-`tools/call`; each must say what the body says. `_meta` states the protocol version and the client's
-capabilities. Every result carries `resultType` and names the server in its own `_meta`, and a
-`server/discover` or a `tools/list` carries how long it may be held: half an hour, `public` for the
-first and `private` for the second, which is filtered by the identity that asked.
-
-Neither `listChanged` nor a subscription is declared: both are a stream held open, and this endpoint
-holds none.
-
-## Authorization
-
-The endpoint is a protected resource, and an application advertises it as one:
-
-```yaml
-exposition:
-  oauth:
-    authorize: https://app.example.com/oauth/authorize
-    resources: ['/.mcp']
-```
-
-Its RFC 9728 document is then read at `/.well-known/oauth-protected-resource/.mcp`, and the
-canonical URI of the resource is `https://api.example.com/.mcp`. See [OAuth](oauth.md).
-
-A request without a credential is `401`, carrying the challenge that names that document — which is
-where the flow starts. A call the identity is not authorized to make is `403` with
-`error="insufficient_scope"`. Each tool is authorized as the resource it is, against the path and
-the verb its name states.
-
-A route that is [`anonymous`](access.md#anonymous) is reached here whatever the client presented:
-the rule that refuses a credentialed request is about a cacheable reply, and what a tool answers is
-not one. So a resource that is public over HTTP is a public tool, and nothing in a manifest has to
-say it twice.
-
-## What refuses
-
-|          |                                                        |
-| -------- | ------------------------------------------------------ |
-| `-32700` | the body is not readable                               |
-| `-32600` | the body is not one JSON-RPC message                   |
-| `-32601` | no method of that name, at `404`                       |
-| `-32602` | the arguments do not fit, or `_meta` states too little |
-| `-32603` | anything the gateway did not mean to answer            |
-| `-32020` | a header says one thing and the body another           |
-| `-32022` | a revision neither served, naming both                 |
-
-The codes MCP reserves for itself are `-32020` to `-32099`, and it has an implementation use none of
-`-32000` to `-32019` — which is where [JSON-RPC](rpc.md#what-refuses) has this gateway's own, so none
-of those is answered here.
-
-## References
-
-- [The specification](https://modelcontextprotocol.io/specification/2026-07-28)
-- [JSON-RPC](rpc.md), where a procedure gets its name
-- [Introspection](introspection.md), which is what a tool's schemas are
-- [Features](../features/mcp.feature)

package/documentation/notes/peers.md

@@ -1,59 +0,0 @@
-# Distributed Peer Discovery
-
-## Problem
-
-Modulo partitioning algorithm `taks.id % replicas == index` requires
-to know the number of task processing instances running in the cluster,
-and the own index of the current instance.
-
-## Forces
-
-1. Static configuration is not an option (due to dynamic scaling / failover).
-2. In a distributed system, there is no concept of a _global current time_.
-
-## Solution
-
-An algorithm that emits `(index, replicas)` once per `interval` seconds, using common Redis
-key and atomic increment.
-
-Define the following parameters:
-
-- `name`: a name of the task processing (e.g. `mail-sender`)
-- `interval`: indexing interval that is deliberately greater than the expected clock skew among
-  instances
-
-At the start of each `interval` in [Unix epoch](https://en.wikipedia.org/wiki/Unix_time):
-
-1. Calculate an ordinal number of the current interval: `number = ceil(now() / interval)`
-2. Compose a `key` as `{name}:{number}`
-3. Atomically increment a `key` in Redis ([INCR](https://redis.io/docs/latest/commands/incr/))
-4. If `index` is defined (see 5)
-
-- get the value of previous key `{name}:{number-1}` as `replicas`
-- if the `replicas` is defined, emit `(index, replicas)` **algorithm result**
-
-5. Store the response (3) in `index`.
-
-## Safe index transition
-
-If the `index` or `replicas` changes, the algorithm consumer must stop consuming new tasks
-and execute _safe index transition_, to prevent task duplication or loss.
-
-The transition can be implemented in a manner similar to the described algorithm, using a dedicated
-`{name}:transition` key.
-However, this process is considered outside the scope of this document.
-
-## Extension
-
-If the system clocks are too precisely synchronized (skew is less than a round-trip time to Redis),
-this may result in continuous [index transitions](#safe-index-transition).
-
-To mitigate this, the algorithm can be extended with a random delay:
-
-1. Before starting the algorithm, define a random constant clock skew, significantly smaller than
-   `interval`: `skew = random() * (interval / 2)`
-2. Start the algorithm at each `interval + skew`.
-
-## Caveats
-
-- The first result will become known between `interval` and `interval × 2` seconds.

package/documentation/notes/sse.md

@@ -1,71 +0,0 @@
-# Note: Server Sent Events
-
-## TL;DR
-
-1. Doesn't exist.
-2. Ridiculous.
-3. Redundant.
-
-## There is no SSE
-
-The initial premise of SSE is to deliver real-time events specifically targeted at a particular user. It's evident that
-to access these events, user authentication is essential, typically implemented through
-an [HTTP Authentication framework](https://datatracker.ietf.org/doc/html/rfc2617).
-
-However, despite this being the most straightforward
-scenario, [it does not work this way](https://github.com/whatwg/html/issues/2177). The only viable way to use SSE is
-to avoid the standard `EventSource` implementation.
-
-## Peculiar event format
-
-### SLAP
-
-[Event stream format](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#event_stream_format)
-defines four fields: `event`, `data`, `id`, `retry`.
-
-In practice, code capable of producing such an object is forced to break the Single Level of Abstraction Principle. This
-requires knowledge of both event structures and connection properties. In real-world systems, these may be handled by
-different processes, such as an Events microservice and an API Gateway.
-
-### Content negotiation
-
-The `data` property is expected to be an arbitrary string, although real-world event data is often structured as an
-object.
-
-Furthermore, since the Event stream format defines its own content type, there is no built-in way to negotiate the
-format of the events.
-
-Additionally, the `data` value is limited to a single line, which hinders the use of
-more [human-friendly formats](https://yaml.org) in a straightforward manner.
-
-## HTTP is enough
-
-Rather than resorting to a non-standard client and a predefined content format, a basic HTTP request can provide a
-solution:
-
-```http
-GET /events/ HTTP/1.1
-accept: application/yaml
-```
-
-```
-200 OK
-content-type: application/yaml
-transfer-encoding: chunked
-
-id: 1
-event: created
-data:
-  foo: bar
-
-id: 2
-event: deleted
-data:
-  bar: baz
-```
-
-Server-side implementation with flow control and stream termination handling is trivial:
-
-```javascript
-eventStream.pipe(response)
-```