@toa.io/extensions.exposition 1.0.0-alpha.285 → 1.0.0-alpha.287

package/documentation/credentials.md

@@ -23,13 +23,13 @@ basic:
 federation:
   - id: 09200d0bcc2448c5863e3f50ae18af84
     iss: https://accounts.google.com
-    _created: 1754899200000
+    CREATED: 1754899200000
 passkeys:
   - id: 54ed430804324e81b39756ea4708b546
     aid: adce0002-35bc-c60a-648b-0b25f1f05503
     synced: true
     label: Personal iPhone
-    _created: 1754899200000
+    CREATED: 1754899200000
 ```
 
 `basic` is `null` when Basic credentials do not exist. `federation` and `passkeys` are always

package/documentation/identity.md

@@ -209,11 +209,9 @@ This can be achieved by using the `auth:incept` directive as follows:
 name: users
 
 entity:
-  schema:
-    type: object
-    properties:
-      name:
-        type: string
+  properties:
+    name:
+      type: string
 
 exposition:
   /:
@@ -266,10 +264,10 @@ The directive itself does not allow or deny access to the requested resource.
 > Used authentication scheme must support inception.
 
 ```yaml
-  /accounts/echo:
-    auth:assert: true
-    auth:anyone: true
-    endpoint: echo
+/accounts/echo:
+  auth:assert: true
+  auth:anyone: true
+  endpoint: echo
 ```
 
 ```http

package/documentation/map.md

@@ -9,10 +9,10 @@ The `map` directive family is used to map HTTP request parts to operation call i
 ```yaml
 exposition:
   /:group:
-    languages: [en, fr]   # supported languages
+    languages: [en, fr] # supported languages
     GET:
       map:authority: hostname # request authority (e.g., hostname)
-      map:language: lang      # requested language
+      map:language: lang # requested language
       map:headers: # raw header values
         token: x-access-token
       map:buffer: body # unparsed request body

package/documentation/mcp.md

@@ -117,14 +117,14 @@ 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` | `{}` |
+| 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.
@@ -164,15 +164,15 @@ 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` |
+|          |                                                        |
+| -------- | ------------------------------------------------------ |
+| `-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 |
+| `-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

package/documentation/notes/peers.md

@@ -9,7 +9,7 @@ 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*.
+2. In a distributed system, there is no concept of a _global current time_.
 
 ## Solution
 

package/documentation/notes/throttling.md

@@ -24,7 +24,7 @@ error.
 ## Forces
 
 1. No per request IO is allowed (centralized solutions do not fit).
-2. In a distributed system, there is no concept of a *global current time*.
+2. In a distributed system, there is no concept of a _global current time_.
 3. Failure to retrieve the quota state should not result in Gateway failure.
 
 ## Solution

package/documentation/octets.md

@@ -210,7 +210,7 @@ The value of the directive is an object with the following properties:
     GET:
       octets:get:
         blob: false # prevent access to the original BLOB
-        meta: true  # allow access to an Entry
+        meta: true # allow access to an Entry
 ```
 
 The `octets:get: ~` declaration is equivalent to defaults.
@@ -295,9 +295,9 @@ If it's an array, the workflow units are executed in sequence.
 ```yaml
 octets:put:
   workflow:
-    - optimize: images.optimize   # executed first
-    - resize: images.resize       # executed second
-      analyze: images.analyze     # executed in parallel with `resize`
+    - optimize: images.optimize # executed first
+    - resize: images.resize # executed second
+      analyze: images.analyze # executed in parallel with `resize`
 ```
 
 If one of the workflow units returns or throws an error,

package/documentation/protocol.md

@@ -36,7 +36,7 @@ corresponding to the type of
 the parts:
 
 | Response type       | Part type             |
-|---------------------|-----------------------|
+| ------------------- | --------------------- |
 | `multipart/msgpack` | `application/msgpack` |
 | `multipart/yaml`    | `application/yaml`    |
 | `multipart/json`    | `application/json`    |
@@ -70,7 +70,7 @@ FIN
 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))
+- [Content-Type: multipart](<https://learn.microsoft.com/en-us/previous-versions/office/developer/exchange-server-2010/aa493937(v=exchg.140)>)
   at Microsoft
 
 ## HTTP version
@@ -82,7 +82,7 @@ exposition:
   protocol: h2c
   service:
     annotations:
-      projectcontour.io/upstream-protocol.h2c: "8000"
+      projectcontour.io/upstream-protocol.h2c: '8000'
 ```
 
 `h2c` requires an ingress controller that proxies cleartext HTTP/2 upstream, and the

package/documentation/query.md

@@ -48,9 +48,13 @@ Undefined `query` denies any query arguments in requests.
 
 Search criteria in [RSQL](https://github.com/jirutka/rsql-parser) format.
 
-The `criteria` property is considered as *open* when it ends with a `;`, allowing the combination of
+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.
+Otherwise, criteria property is _closed_, that is, doesn't allow `criteria` in a request query.
 
 ```yaml
 # manifest.toa.yaml
@@ -151,7 +155,9 @@ rank: 5
 
 ## Text search
 
-For entities with `text` indexes, search queries can be enabled using the `search` property.
+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
@@ -223,7 +229,7 @@ sort: rank:asc
 sort: rank:desc;timestamp:asc
 ```
 
-If `sort` value ends with a semicolon `;` then the sorting is considered *open*
+If `sort` value ends with a semicolon `;` then the sorting is considered _open_
 and can be extended using request query `sort` argument.
 
 ```yaml
@@ -274,10 +280,10 @@ GET /dummies/?foo=0&bar=baz
 
 ## Optimistic concurrency control
 
-If an operation returns an object with `_version` property,
-then its value is passed as the value of
-the [`etag` header](https://datatracker.ietf.org/doc/html/rfc7232#section-2.3) in the response
-(and removed from the object).
+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.

package/documentation/rpc.md

@@ -21,14 +21,14 @@ The separator is `.` and not `/` because a name is a tool's name too, and
 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` |
+| 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` |
+| `/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
@@ -55,17 +55,25 @@ A key the template names is a route variable, and is taken by the path. `query`
 querystring. Whatever is left is the body.
 
 ```json
-{"jsonrpc": "2.0", "id": 1, "method": "pots._id.GET", "params": {"id": "a1b2"}}
+{ "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}}
+{
+  "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}}}
+{
+  "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
@@ -91,8 +99,10 @@ A request may carry an array of calls instead of one, and answers an array of wh
 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"}}]
+[
+  { "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
@@ -114,14 +124,14 @@ 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 |
+|          |                                                    |
+| -------- | -------------------------------------------------- |
+| `-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` |
+| `-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

package/documentation/tracing.md

@@ -32,7 +32,7 @@ clients instrumented with OpenTelemetry-compatible tooling, or by upstream proxi
 traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
 ```
 
-In addition to the trace ID, it carries the ID of the client span, which becomes the *parent* of
+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`
@@ -52,9 +52,9 @@ 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
+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 _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

package/documentation/tree.md

@@ -112,7 +112,7 @@ key.
 HTTP methods can only be mapped to operations of the corresponding types.
 
 | HTTP method | Operation type                                |
-|-------------|-----------------------------------------------|
+| ----------- | --------------------------------------------- |
 | `POST`      | **Transition** (without Query)<br/>**Effect** |
 | `PUT`       | **Transition** (with Query)<br/>**Effect**    |
 | `GET`       | **Observation**<br/>**Computation**           |

package/features/auth.assert.feature

@@ -2,8 +2,8 @@ Feature: Identity assertion
 
   Scenario: Assert Identity
     Given the `identity.basic` database contains:
-      | _id                              | authority | username  | password                                                     | _version |
-      | efe3a65ebbee47ed95a73edd911ea328 | nex       | developer | $2b$10$ZRSKkgZoGnrcTNA5w5eCcu3pxDzdTduhteVYXcp56AaNcilNkwJ.O | 1        |
+      | _id                              | authority | username  | password                                                     | VERSION |
+      | efe3a65ebbee47ed95a73edd911ea328 | nex       | developer | $2b$10$ZRSKkgZoGnrcTNA5w5eCcu3pxDzdTduhteVYXcp56AaNcilNkwJ.O | 1       |
     And the `echo` is running with the following manifest:
       """yaml
       exposition:

package/features/auth.bearer.feature

@@ -87,7 +87,7 @@ Feature: More than one provider claims Bearer
     Given the `identity.federation` configuration:
       """yaml
       trust:
-        - iss: http://localhost:44444
+        - iss: http://localhost:31005
           aud: test
       """
     And the IDP token for User is issued

package/features/auth.claims.feature

@@ -8,7 +8,7 @@ Feature: Federated identity authentication
     And the `identity.federation` configuration:
       """yaml
       trust:
-        - iss: http://localhost:44444
+        - iss: http://localhost:31005
           aud: test
       """
 
@@ -18,7 +18,7 @@ Feature: Federated identity authentication
       /:
         GET:
           auth:claims:
-            iss: http://localhost:44444
+            iss: http://localhost:31005
             aud: test
             sub: Bob
           dev:stub: ok
@@ -62,7 +62,7 @@ Feature: Federated identity authentication
       /:
         GET:
           auth:claims:
-            iss: http://localhost:44444
+            iss: http://localhost:31005
             aud: test
           dev:stub: ok
       """
@@ -84,7 +84,7 @@ Feature: Federated identity authentication
       /:
         GET:
           auth:claims:
-            iss: http://localhost:44444
+            iss: http://localhost:31005
             sub: Alice
           dev:stub: ok
       """
@@ -106,7 +106,7 @@ Feature: Federated identity authentication
       /:
         GET:
           auth:claims:
-            iss: http://localhost:44444
+            iss: http://localhost:31005
             aud: goalkeepers
           dev:stub: ok
       """

package/features/auth.incept.feature

@@ -121,8 +121,8 @@ Feature: Identity inception
 
   Scenario: Inception with a wrong password for existing credentials
     Given the `identity.basic` database contains:
-      | _id                              | authority | username  | password                                                     | _version |
-      | efe3a65ebbee47ed95a73edd911ea328 | nex       | developer | $2b$10$ZRSKkgZoGnrcTNA5w5eCcu3pxDzdTduhteVYXcp56AaNcilNkwJ.O | 1        |
+      | _id                              | authority | username  | password                                                     | VERSION |
+      | efe3a65ebbee47ed95a73edd911ea328 | nex       | developer | $2b$10$ZRSKkgZoGnrcTNA5w5eCcu3pxDzdTduhteVYXcp56AaNcilNkwJ.O | 1       |
     And the `users` is running with the following manifest:
       """yaml
       exposition:

package/features/authorities.federation.feature

@@ -6,7 +6,7 @@ Feature: OIDC tokens with authorities
     And the `identity.federation` configuration:
       """yaml
       trust:
-        - iss: http://localhost:44444
+        - iss: http://localhost:31005
           aud: test
       """
 

package/features/configuration.feature

@@ -28,9 +28,9 @@ Feature: Configuration values
               type: string
             bar:
               type: string
-              default: world
         defaults:
           foo: deployed
+          bar: world
       """
     And the configuration values are running
 
@@ -49,6 +49,7 @@ Feature: Configuration values
 
       configuration:
         foo: deployed
+        bar: world
       schema:
         type: object
         properties:
@@ -56,7 +57,6 @@ Feature: Configuration values
             type: string
           bar:
             type: string
-            default: world
       epoch: e1
       """
 
@@ -82,9 +82,9 @@ Feature: Configuration values
               type: string
             bar:
               type: string
-              default: world
         configuration:
           foo: deployed
+          bar: world
       """
 
   Scenario: Listing without the role
@@ -154,7 +154,6 @@ Feature: Configuration values
 
       configuration:
         foo: created
-        bar: world
       epoch: e1
       """
 

package/features/credentials.feature

@@ -7,12 +7,12 @@ Feature: Persistent credentials management
       | _id                              | authority | username  | password                                                     |
       | efe3a65ebbee47ed95a73edd911ea328 | nex       | developer | $2b$10$ZRSKkgZoGnrcTNA5w5eCcu3pxDzdTduhteVYXcp56AaNcilNkwJ.O |
     And the `identity.federation` database contains:
-      | _id                              | authority | identity                         | iss                         | sub    | _created |
-      | fed3a65ebbee47ed95a73edd911ea328 | nex       | efe3a65ebbee47ed95a73edd911ea328 | https://accounts.google.com | google | 1000     |
-      | fed3a65ebbee47ed95a73edd911ea329 | nex       | efe3a65ebbee47ed95a73edd911ea328 | https://appleid.apple.com   | apple  | 900      |
+      | _id                              | authority | identity                         | iss                         | sub    | CREATED |
+      | fed3a65ebbee47ed95a73edd911ea328 | nex       | efe3a65ebbee47ed95a73edd911ea328 | https://accounts.google.com | google | 1000    |
+      | fed3a65ebbee47ed95a73edd911ea329 | nex       | efe3a65ebbee47ed95a73edd911ea328 | https://appleid.apple.com   | apple  | 900     |
     And the `identity.passkeys` database contains:
-      | _id                              | authority | identity                         | kid     | aid                                  | synced | key    | counter | label           | _created |
-      | ace3a65ebbee47ed95a73edd911ea328 | nex       | efe3a65ebbee47ed95a73edd911ea328 | key-one | adce0002-35bc-c60a-648b-0b25f1f05503 | true   | cHVibGlj | 0       | Personal iPhone | 2000     |
+      | _id                              | authority | identity                         | kid     | aid                                  | synced | key      | counter | label           | CREATED |
+      | ace3a65ebbee47ed95a73edd911ea328 | nex       | efe3a65ebbee47ed95a73edd911ea328 | key-one | adce0002-35bc-c60a-648b-0b25f1f05503 | true   | cHVibGlj | 0       | Personal iPhone | 2000    |
 
   Scenario: Listing all persistent credentials
     When the following request is received:
@@ -32,16 +32,16 @@ Feature: Persistent credentials management
       federation:
         - id: fed3a65ebbee47ed95a73edd911ea328
           iss: https://accounts.google.com
-          _created: 1000
+          CREATED: 1000
         - id: fed3a65ebbee47ed95a73edd911ea329
           iss: https://appleid.apple.com
-          _created: 900
+          CREATED: 900
       passkeys:
         - id: ace3a65ebbee47ed95a73edd911ea328
           aid: adce0002-35bc-c60a-648b-0b25f1f05503
           synced: true
           label: Personal iPhone
-          _created: 2000
+          CREATED: 2000
       """
 
   Scenario: Deleting credentials through their components
@@ -101,6 +101,6 @@ Feature: Persistent credentials management
       federation:
         - id: fed3a65ebbee47ed95a73edd911ea329
           iss: https://appleid.apple.com
-          _created: 900
+          CREATED: 900
       passkeys: []
       """

package/features/dev.feature

@@ -1,5 +1,6 @@
 Feature: Dev
 
+  @timing
   Scenario: Delays
     Given the annotation:
       """yaml

package/features/dynamic.feature

@@ -83,6 +83,7 @@ Feature: Dynamic tree updates
       200 OK
       """
 
+  @timing
   Scenario: Stale branch expires
     Given the branch TTL is 5 seconds
     And the Gateway is running

package/features/errors.feature

@@ -92,6 +92,27 @@ Feature: Errors
       must have required property 'title'
       """
 
+  Scenario: Criteria value the property cannot hold
+    Given the `pots` is running with the following manifest:
+      """yaml
+      exposition:
+        /:
+          GET: enumerate
+      """
+    When the following request is received:
+      """
+      GET /pots/?criteria=volume>abc HTTP/1.1
+      host: nex.toa.io
+      accept: text/plain
+      """
+    Then the following reply is sent:
+      """
+      400 Bad Request
+      content-type: text/plain
+
+      Criteria selector 'volume' takes a number, and 'abc' is not one
+      """
+
   Scenario: Query limit out of range
     Given the `pots` is running with the following manifest:
       """yaml