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

package/documentation/protocol.md

@@ -1,120 +0,0 @@
-# Protocol Support
-
-## Media types
-
-The following media types are supported for both requests and responses:
-
-- `application/json`
-- `application/yaml` using [js-yaml](https://github.com/nodeca/js-yaml)
-- `application/msgpack` using [msgpackr](https://github.com/kriszyp/msgpackr)
-- `text/plain`
-
-A request may also be sent as `application/x-www-form-urlencoded`. A form is read and never
-written, so it is not a format a response is negotiated to. A name repeated in a form is read as
-the list it is.
-
-The response format is determined by content negotiation
-using [negotiator](https://github.com/jshttp/negotiator).
-
-```http
-GET / HTTP/1.1
-accept: application/yaml
-```
-
-```
-200 OK
-content-type: application/yaml
-
-foo: bar
-```
-
-### Multipart types
-
-Multipart responses are encoded using content negotiation,
-and the `content-type` of the response is set to one of the custom `multipart/` subtypes,
-corresponding to the type of
-the parts:
-
-| Response type       | Part type             |
-| ------------------- | --------------------- |
-| `multipart/msgpack` | `application/msgpack` |
-| `multipart/yaml`    | `application/yaml`    |
-| `multipart/json`    | `application/json`    |
-| `multipart/text`    | `text/plain`          |
-
-Multipart responses are started with a text chunk `ACK`, and finished with a text
-chunk `FIN`.
-
-Example:
-
-```
-GET /stream/ HTTP/1.1
-accept: application/yaml
-```
-
-```
-200 OK
-content-type: multipart/yaml; boundary=cut
-
---cut
-ACK
---cut
-foo: bar
---cut
-baz: qux
---cut
-FIN
---cut--
-```
-
-See also:
-
-- [Multipart Content-Type](https://www.w3.org/Protocols/rfc1341/7_2_Multipart.html) at W3C
-- [Content-Type: multipart](<https://learn.microsoft.com/en-us/previous-versions/office/developer/exchange-server-2010/aa493937(v=exchg.140)>)
-  at Microsoft
-
-## HTTP version
-
-The gateway serves HTTP/1.1 by default. `protocol: h2c` serves cleartext HTTP/2 instead.
-
-```yaml
-exposition:
-  protocol: h2c
-  service:
-    annotations:
-      projectcontour.io/upstream-protocol.h2c: '8000'
-```
-
-`h2c` requires an ingress controller that proxies cleartext HTTP/2 upstream, and the
-annotation that controller reads to do so. Contour, Traefik and Envoy-based controllers
-proxy it; ingress-nginx does not. A cleartext HTTP/2 server answers nothing else on the
-same port: there is no ALPN to negotiate with, so a controller that speaks HTTP/1.1 upstream
-reaches nothing.
-
-Under `h2c` a request refused before its body is read is answered and then cancelled with
-`RST_STREAM(NO_ERROR)`. The reply arrives; the upload stops where it is. A client streaming
-a request body sees that body cancelled — in Node, `ERR_STREAM_PREMATURE_CLOSE` on the stream
-it passed, which throws if nothing handles it. A real failure shows in the reply, or in the
-request rejecting because no reply came. A buffered body is unaffected.
-
-## CORS
-
-[CORS](https://www.w3.org/TR/2020/SPSD-cors-20200602/) is supported,
-credentials, any `origin`, and any request header fields are allowed.
-
-The following request headers are allowed:
-
-- `accept`
-- `authorization`
-- `content-type`
-- `etag`
-- `if-match`
-- `if-none-match`
-- headers used by the [`map` directive family](map.md)
-
-The following response headers are exposed:
-
-- `authorization`
-- `content-type`
-- `content-length`
-- `etag`

package/documentation/query.md

@@ -1,324 +0,0 @@
-# Query mapping
-
-## TL;DR
-
-```yaml
-id?: string
-criteria?: string
-sort?: string
-omit?: integer
-limit?: integer
-selectors?: string[]
-projection?: string[]
-```
-
-```yaml
-# manifest.toa.yaml
-
-name: pots
-namespace: tea
-
-exposition:
-  /hot:
-    GET:
-      endpoint: enumerate
-      query:
-        criteria: state==hot
-    /top10:
-      GET:
-        endpoint: enumerate
-        query:
-          criteria: state==hot
-          sort: rank:desc
-          text: true
-          limit: 10
-  /latest:
-    GET:
-      endpoint: observe
-      query:
-        sort: timestamp:desc
-        limit: 1
-```
-
-Undefined `query` denies any query arguments in requests.
-
-`POST` method mapping cannot have `query` declaration.
-
-## Criteria
-
-Search criteria in [RSQL](https://github.com/jirutka/rsql-parser) format.
-
-A value is read as what the property it selects on holds, and one that cannot be read as that is
-refused with `400 Bad Request` — `volume>abc` where `volume` is a number, or `booked==yes` where
-`booked` is a boolean. A string property takes whatever is written.
-
-The `criteria` property is considered as _open_ when it ends with a `;`, allowing the combination of
-request query criteria using `and` logic.
-Otherwise, criteria property is _closed_, that is, doesn't allow `criteria` in a request query.
-
-```yaml
-# manifest.toa.yaml
-
-name: dummy
-
-exposition:
-  /:
-    GET:
-      endpoint: observe
-      query:
-        criteria: state==hot; # open criteria
-```
-
-```http
-GET /dummies/?criteria=rank==5
-```
-
-The request example above will result in an operation call with the following Request:
-
-```yaml
-query:
-  criteria: state==hot;rank=5
-```
-
-### Path variables
-
-Path variables are prepended to the `criteria` request query parameter except for
-the [`POST` method](#post-method).
-
-If query criteria starts with logical operator (`,` or `;`), then path variables are prepended
-accordingly.
-`AND` logical operator is used by default.
-
-Given the following declaration:
-
-```yaml
-# manifest.toa.yaml
-
-name: dummies
-
-exposition:
-  /:type:
-    GET:
-      endpoint: observe
-      query:
-        criteria: ,state==hot; # open criteria
-```
-
-and the following request:
-
-```http request
-GET /dummies/cool/?criteria=rank==5
-```
-
-Operation call will have the following query criteria:
-
-```yaml
-criteria: (type==cool,state==hot);(rank=5)
-```
-
-#### POST method
-
-`POST` method semantically used to create a new entity instance, that is, calling a Transition
-without Query.
-Thus, path variables are added to the request input.
-
-Given the following declaration:
-
-```yaml
-# manifest.toa.yaml
-
-name: dummies
-
-exposition:
-  /:type:
-    POST: transit
-```
-
-and the following request:
-
-```http request
-POST /dummies/cool/
-content-type: application/yaml
-
-input:
-  rank: 5
-```
-
-Operation call will have the following input:
-
-```yaml
-type: cool
-rank: 5
-```
-
-> In case of conflict, path variables override input properties.
-
-## Text search
-
-For entities with `text` indexes — declared in a
-[migration](/documentation/component/declaration.md#migrations) — search queries can be enabled
-using the `search` property.
-
-```yaml
-# manifest.toa.yaml
-
-name: dummies
-
-exposition:
-  /:type:
-    GET:
-      endpoint: observe
-      query:
-        search: true
-```
-
-```yaml
-GET /dummies/?search=some+text+query
-```
-
-## Omit, limit
-
-`omit` and `limit` properties can declare their default values and allowed boundaries:
-
-```yaml
-limit:
-  value: 10
-  range: [1, 100]
-```
-
-If no default value is provided, then the lower boundary of the range is used.
-
-Default values for `omit` and `limit` are:
-
-```yaml
-omit:
-  value: 0
-  range: [0, 1000]
-limit:
-  value: 10
-  range: [1, 1000]
-```
-
-Constant values can be declared using the shortcut:
-
-```yaml
-limit: 10
-```
-
-```http
-GET /dummies/?omit=100&limit=10
-```
-
-## Sort
-
-The `sort` query property defines the result order of Observations within an `objects` scope
-(enumeration).
-It comprises an ordered set of sorting statements delimited by semicolons.
-Each statement consists of an entity property name with an optional sorting direction suffix:
-`:asc`for ascending or `:desc` for descending.
-
-```yaml
-sort: rank # ascending by default
-```
-
-```yaml
-sort: rank:asc
-```
-
-```yaml
-sort: rank:desc;timestamp:asc
-```
-
-If `sort` value ends with a semicolon `;` then the sorting is considered _open_
-and can be extended using request query `sort` argument.
-
-```yaml
-sort: rank:desc; # open sort
-```
-
-Having the above `sort` declaration, the following request will result in an operation call
-with `rank:desc;timestamp:asc` sort:
-
-```http
-GET /dummies/?sort=timestamp:asc
-```
-
-## Selectors
-
-![Not implemented](https://img.shields.io/badge/Not_implemented-red)
-
-The `selectors` query property contains a list of Entity properties allowed for a client to use in
-the `criteria` and `sort` query parameters.
-If no value is provided, then no selectors are allowed.
-
-```yaml
-selectors: [rank, timestamp]
-```
-
-## Projection
-
-A list of Entity properties to be included in the Observation result.
-
-```yaml
-projection: [id, title, timestamp]
-```
-
-## Parameters
-
-By default, the only query parameters allowed are described above. Arbitrary query parameters
-can be allowed by specifying them in the `parameters` property.
-
-```yaml
-parameters: [foo, bar]
-```
-
-These parameters are embedded in the operation call input, which must be an object.
-
-```http
-GET /dummies/?foo=0&bar=baz
-```
-
-## Optimistic concurrency control
-
-If an operation answers a safe request (`GET`, `HEAD`) with an object that has a `VERSION`
-property, its value is passed as the value of
-the [`etag` header](https://datatracker.ietf.org/doc/html/rfc7232#section-2.3) in the response,
-see [validators](cache.md#validators).
-
-Client can use the `if-match` request header to perform an operation only if the corresponding
-object has not been modified since the last retrieval.
-
-```http
-GET /dummies/5e82ed5e/ HTTP/1.1
-
----
-
-HTTP/1.1 200 OK
-etag: "1"
-
-foo: bar
-```
-
-```http request
-PUT /dummies/5e82ed5e/ HTTP/1.1
-if-match: "1"
-
-foo: baz
-```
-
-```http
-200 OK
-```
-
-```http request
-PUT /dummies/5e82ed5e/ HTTP/1.1
-if-match: "never"
-
-foo: baz
-```
-
-```http
-412 Precondition Failed
-```
-
-The value within the quotes is mapped to the `version` property of operation call query.

package/documentation/require.md

@@ -1,15 +0,0 @@
-# Directive family Require
-
-The `require` directive family provides the ability to specify HTTP request requirements to be met.
-
-## Headers
-
-`require:header` requires a specific header to be present in the request, and `require:headers`
-requires a set of headers to be present.
-
-```yaml
-exposition:
-  /:id:
-    require:header: if-match # enforce concurrency control
-    PUT: transit
-```

package/documentation/rpc.md

@@ -1,154 +0,0 @@
-# JSON-RPC
-
-An application annotates it, and every resource it exposes answers as a procedure as well.
-
-```yaml
-exposition:
-  rpc:
-    batch: 32
-```
-
-Without it `/.rpc` 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.
-
-## The name
-
-A procedure is an RTD method — a node and a verb — and its name is the route template with a
-variable marked by a leading `_` and the verb as the last segment, joined by `.`.
-
-The separator is `.` and not `/` because a name is a tool's name too, and
-[MCP](mcp.md) names the characters one may hold: letters, digits, `_`, `-` and `.`. A client that
-receives one outside that set may refuse the tool, and one that accepts it rewrites what it shows
-a model — so what is published has to be spellable as it stands.
-
-| route                        | verb   | method                           |
-| ---------------------------- | ------ | -------------------------------- |
-| `/pots`                      | `GET`  | `pots.GET`                       |
-| `/pots`                      | `POST` | `pots.POST`                      |
-| `/pots/:id`                  | `GET`  | `pots._id.GET`                   |
-| `/identity/tokens/:identity` | `POST` | `identity.tokens._identity.POST` |
-| `/files/**`                  | `GET`  | `files.__.GET`                   |
-| `/`                          | `GET`  | `GET`                            |
-
-The verb is always the last segment, so `/pots/GET` answering `POST` is `pots.GET.POST` and
-`/pots` answering `GET` is `pots.GET`. Nothing is declared to make a name: a re-mounted route is
-a renamed procedure, because the name is the address.
-
-## What has a name
-
-A segment is addressed where it holds only `A-Z`, `a-z`, `0-9` and `-`. `_` is the name's own,
-marking a variable, and `__` the rest of a path; `.` is what divides one segment from the next.
-
-A route with a segment holding anything else — a `.`, a `_`, a `*`, a variable that is not one
-word — has no name. It is served over HTTP as it always was; what it loses is the address, so
-`/.rpc` cannot call it. Each is said once at startup, naming the route and the segment.
-
-```
-Route cannot be addressed as a procedure  route=/pots/v1.0 segment=v1.0
-```
-
-## The parameters
-
-`params` is by name, and carries what a request carries.
-
-A key the template names is a route variable, and is taken by the path. `query` is the
-querystring. Whatever is left is the body.
-
-```json
-{ "jsonrpc": "2.0", "id": 1, "method": "pots._id.GET", "params": { "id": "a1b2" } }
-```
-
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 2,
-  "method": "pots.POST",
-  "params": { "title": "Kettle", "volume": 1.7 }
-}
-```
-
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 3,
-  "method": "pots.GET",
-  "params": { "query": { "criteria": "volume=gt=1", "limit": 10 } }
-}
-```
-
-The querystring has a name of its own because an operation's input is free to have an `id` or
-a `limit`, and the two would otherwise be one object. An operation whose input has a property
-named `query` cannot be called with one.
-
-A variable stands for a single segment, so its value may not contain `/`, `?` or `#`. `__`
-stands for the rest of the path and may contain `/`; its value is read under the name `**`,
-which is what the RTD calls it wherever else it is read.
-
-## What answers
-
-The reply is the operation's, restricted by the same [`io:output`](io.md) as the resource's,
-and encoded as the request's `accept` asks. A call that returned nothing answers `result: null`
-— JSON-RPC has no 404, and nothing went wrong.
-
-A call with no `id` is a notification: it runs and answers nothing, and a request carrying only
-notifications answers `204`.
-
-## Several at once
-
-A request may carry an array of calls instead of one, and answers an array of what they
-answered — shorter than what it was given, where some were notifications.
-
-```json
-[
-  { "jsonrpc": "2.0", "id": 1, "method": "pots._id.GET", "params": { "id": "a1b2" } },
-  { "jsonrpc": "2.0", "method": "pots._id.DELETE", "params": { "id": "c3d4" } }
-]
-```
-
-They run one after another, in the order given. `batch` is how many one request may carry, 32
-where the annotation does not say: a request is one authentication and one reply however many
-calls it makes, so what a caller may ask for at once is bounded.
-
-## What refuses
-
-The whole request is refused, with a status, when it is not a request this endpoint serves: a
-verb other than `POST` is `405`, an unreadable body is `400`, and an array that is empty or
-longer than `batch` is `400`.
-
-A call that is not one — a version it does not state, a method it does not name — is answered
-to nobody: `id` is `null`, because nothing about it is trustworthy enough to answer to.
-
-A credential is the request's, so a call cannot be refused for one: a request that presents
-none where the procedure requires one is `401`, and carries the challenge that says where to
-authenticate.
-
-Everything else a call runs into is a value, at `200`, because the request itself succeeded.
-
-|          |                                                    |
-| -------- | -------------------------------------------------- |
-| `-32601` | no route of that name, or no such verb on it       |
-| `-32602` | a variable is missing, or a query is not one       |
-| `-32000` | the identity is not authorized to make this call   |
-| `-32001` | the operation refused, its own code in `data.code` |
-| `-32603` | anything the gateway did not mean to answer        |
-| `-32002` | the request carries more calls than `batch`        |
-
-The first five codes JSON-RPC states mean the same to every client. `-32000` and `-32001` are
-this gateway's, from the block the specification reserves and leaves empty, so
-`-32001` says only that an operation refused — `data.code` is the code that operation declares
-in its manifest, and is what a caller reads.
-
-## Authorization
-
-A procedure is authorized as the resource is, against the path and the verb its name states.
-A token restricted to `/pots/:id/` for `GET` authorizes `pots._id.GET` and nothing else,
-whichever way the call arrives.
-
-[`anonymous`](access.md#anonymous) is the one directive that reads a call differently from a
-request: it admits one whatever the request presented, because what refuses a credentialed request
-is that the reply would not be cacheable, and what a call answers is not a reply.
-
-## What has no procedure
-
-`map:buffer` reads the request, and a call is not the request. A resource that declares it
-answers over HTTP alone.

package/documentation/tracing.md

@@ -1,70 +0,0 @@
-# Tracing
-
-Each incoming request is processed within a [trace](../../telemetry/readme.md#tracing) —
-a server span is created, and its trace context is propagated to component invocations and
-emitted events, so all log entries and spans across the application caused by the request
-share the same `trace_id`.
-
-## The `ray` response header
-
-Each response contains a `ray` header with the trace ID of the request.
-It can be used to find related log entries, or be attached to a support ticket.
-
-Log entries are stamped with the trace ID regardless of the sampling decision,
-while the trace itself is only recorded if the trace is sampled (see [Sampling](#sampling)).
-
-```
-HTTP/1.1 201 Created
-ray: 0af7651916cd43dd8448eb211c80319c
-```
-
-## Continuing a trace
-
-By default, the trace starts at the gateway. If the request carries a trace context in one of the
-following headers, the trace is continued, that is, the incoming trace ID is used.
-
-### `traceparent`
-
-The [W3C Trace Context](https://www.w3.org/TR/trace-context/#traceparent-header) header, sent by
-clients instrumented with OpenTelemetry-compatible tooling, or by upstream proxies.
-
-```
-traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
-```
-
-In addition to the trace ID, it carries the ID of the client span, which becomes the _parent_ of
-the gateway's server span, linking client-side and server-side spans into a single trace tree.
-
-### `ray`
-
-A bare trace ID (32 lowercase hex digits), for clients without tracing instrumentation willing to
-correlate their requests with server-side traces.
-
-```
-ray: 4bf92f3577b34da6a3ce929d0e0e4736
-```
-
-Unlike `traceparent`, it carries no parent span, so the gateway's server span becomes the root of
-the trace.
-
-If both headers are present, `traceparent` takes precedence as it carries more information.
-Headers with invalid values are ignored, and a new trace is started.
-
-## Sampling
-
-The trace _context_ (trace ID) is always created and propagated, so the `ray` header and
-`trace_id` in log entries are always present. The sampling decision only determines whether
-the _spans_ of the trace are recorded.
-
-The decision is made once, by the process that starts the trace, and is propagated along with
-the trace context (the flags byte of `traceparent`), so a trace is either recorded as a whole
-or not at all. Sampling is configured with the
-[`telemetry.traces` annotation](../../telemetry/readme.md#sampling).
-
-Sending a trace context does not bypass sampling: an incoming `ray` header adopts the trace ID,
-while the recording decision is still made by the gateway. The `sampled` flag of an incoming
-`traceparent` is respected, as the decision belongs to the trace root.
-
-## See also
-
-- [Telemetry extension](../../telemetry/readme.md) — spans, structured logs, `context.span`