@toa.io/extensions.exposition 1.0.0-alpha.5 → 1.0.0-alpha.51

package/documentation/octets.md

@@ -20,7 +20,7 @@ Stores the content of the request body into a storage, under the request path wi
 specified `content-type`.
 
 If request's `content-type` is not acceptable, or if the request body does not pass
-the [validation](/extensions/storages/readme.md#async-putpath-string-stream-readable-type-typecontrol-maybeentry),
+the [validation](/extensions/storages/readme.md#async-putpath-string-stream-readable-options-options-maybeentry),
 the request is rejected with a `415 Unsupported Media Type` response.
 
 The value of the directive is `null` or an object with the following properties:
@@ -83,7 +83,8 @@ is [multipart](protocol.md#multipart-types).
 The first part represents the created Entry, which is sent immediately after the BLOB is stored,
 while subsequent parts are results from the workflow endpoints, sent as soon as they are available.
 
-In case a workflow endpoint returns an `Error`, the error part is sent, and the response is closed.
+In case a workflow endpoint returns an `Error`, the error part is sent,
+and the response is closed.
 Error's properties are added to the error part, among with the `step` identifier.
 
 ```
@@ -91,16 +92,29 @@ Error's properties are added to the error part, among with the `step` identifier
 content-type: multipart/yaml; boundary=cut
 
 --cut
+
 id: eecd837c
 type: image/jpeg
 created: 1698004822358
+
 --cut
-optimize: null
+
+step: optimize
+status: completed
+
 --cut
+
+step: resize
 error:
-  step: resize
   code: TOO_SMALL
   message: Image is too small
+status: completed
+
+--cut
+
+step: analyze
+status: exception
+
 --cut--
 ```
 
@@ -193,22 +207,6 @@ the entry is deleted.
 
 The error returned by the workflow prevents the deletion of the entry.
 
-## `octets:permute`
-
-Performs
-a [permutation](/extensions/storages/readme.md#async-permutepath-string-ids-string-maybevoid) on the
-entries
-under the request path.
-
-```yaml
-/images:
-  octets:context: images
-  PUT:
-    octets:permute: ~
-```
-
-The request body must be a list of entry identifiers.
-
 ## `octets:workflow`
 
 Execute a [workflow](#workflows) on the entry under the request path.
@@ -227,14 +225,16 @@ A workflow is a list of endpoints to be called.
 The following input will be passed to each endpoint:
 
 ```yaml
+authority: string
 storage: string
 path: string
 entry: Entry
 parameters: Record<string, string> # route parameters
 ```
 
-See [Entry](/extensions/storages/readme.md#entry) and an
-example [workflow step processor](../features/steps/components/octets.tester).
+- [Storages](/extensions/storages/readme.md)
+- [Authorities](authorities.md)
+- Example [workflow step processor](../features/steps/components/octets.tester)
 
 A _workflow unit_ is an object with keys referencing the workflow step identifier, and an endpoint
 as value.
@@ -258,4 +258,15 @@ octets:store:
       analyze: images.analyze     # executed in parallel with `resize`
 ```
 
-If one of the workflow units returns an error, the execution of the workflow is interrupted.
+If one of the workflow units returns or throws an error,
+the execution of the workflow is interrupted.
+
+### Workflow tasks
+
+A workflow unit which value starts with `task:` prefix will be executed as a Task.
+
+```yaml
+octets:store:
+  workflow:
+    optimize: task:images.optimize
+```

package/documentation/protocol.md

@@ -72,6 +72,9 @@ The following request headers are allowed:
 - `accept`
 - `authorization`
 - `content-type`
+- `etag`
+- `if-match`
+- `if-none-match`
 - headers used by the [`vary:embed` directive](vary.md#embeddings)
 
 The following response headers are exposed:

package/documentation/query.md

@@ -6,10 +6,10 @@
 id?: string
 criteria?: string
 sort?: string
-omit?: [integer]
-limit?: [integer]
+omit?: integer
+limit?: integer
 selectors?: string[]
-projection?: [string]
+projection?: string[]
 ```
 
 ```yaml
@@ -77,8 +77,12 @@ query:
 
 ### Path variables
 
-Path variables are prepended to the `criteria` request query parameter using logical AND,
-except for the [`POST` method](#post-method).
+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:
 
@@ -92,7 +96,7 @@ exposition:
     GET:
       endpoint: observe
       query:
-        criteria: state==hot; # open criteria
+        criteria: ,state==hot; # open criteria
 ```
 
 and the following request:
@@ -104,7 +108,7 @@ GET /dummies/cool/?criteria=rank==5
 Operation call will have the following query criteria:
 
 ```yaml
-criteria: state==hot;type==cool;rank=5
+criteria: (type==cool,state==hot);(rank=5)
 ```
 
 #### POST method
@@ -251,9 +255,9 @@ PUT /dummies/5e82ed5e/ HTTP/1.1
 if-match: "1"
 
 foo: baz
+```
 
----
-
+```http
 200 OK
 ```
 
@@ -262,8 +266,10 @@ 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

@@ -0,0 +1,15 @@
+# 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/tree.md

@@ -56,6 +56,19 @@ as it provides a more specific match compared to the generic `/users/:id` route.
 
 The priority of Routes with the same specificity is determined by the order of declaration.
 
+## Route forwarding
+
+A Route can be forwarded to another Route by specifying the destination Route as the value of the
+Route.
+
+```yaml
+/destination/:var: ...
+/static: /destination/hello
+/variables/:bar: /destination/:bar
+```
+
+Forwarding Route variables are mapped to the forwarded Route variables if they have the same name.
+
 ## Methods
 
 Methods are mappings of the HTTP methods to the corresponding operations.
@@ -102,7 +115,7 @@ HTTP methods can only be mapped to operations of the corresponding types.
 | `GET`       | **Observation**<br/>**Computation**           |
 | `PATCH`     | **Assignment**<br/>**Effect**                 |
 
-As method mapping is unambiguous for Observation, Assignent, and Computation, a consice syntax is
+As method mapping is unambiguous for Observation, Assignment, and Computation, a concise syntax is
 available:
 
 ```yaml
@@ -110,7 +123,23 @@ available:
 /items/:id: [observe, assign]
 ```
 
-### Intermediate Nodes
+### Projections
+
+A Method can have a `projection` key that specifies the fields of the operation result to be
+included in the response.
+
+```yaml
+/teapots:
+  GET:
+    endpoint: select
+    projection:
+      - name
+      - state
+```
+
+> `id` is always included in the projection.
+
+## Intermediate Nodes
 
 An RTD Node that has a Route with a key `/` is an _intermediate_ Node.
 Intermediate Nodes must not have Methods as they are unreachable.
@@ -124,8 +153,10 @@ Intermediate Nodes must not have Methods as they are unreachable.
 
 ## Directives
 
-RTD Directives are declared using RTD node or Method keys following the `{family}:{directive}` pattern and can be used
-to add or modify the behavior of request processing. Directive declarations are applied to the RTD node where they are
+RTD Directives are declared using RTD node or Method keys following the `{family}:{directive}`
+pattern and can be used
+to add or modify the behavior of request processing. Directive declarations are applied to the RTD
+node where they are
 declared and to all nested nodes.
 
 ```yaml

package/documentation/vary.md

@@ -7,16 +7,15 @@ operation call.
 
 ```yaml
 exposition:
-  realms:
-    toa: the.toa.io
-  /:
+  /:group:
     vary:languages: [en, fr]
     GET:
       vary:embed:
-        lang: language # predefined embeddings
-        realm: realm
+        app: authority # predefined embeddings
+        lang: language
         token: :x-access-token # raw header value
-      endpoint: dummies.get
+        group: /:group # route parameter
+      endpoint: observe
 ```
 
 ## Embeddings
@@ -30,13 +29,9 @@ If the value is an array, the first non-empty embedding function's result is use
 > If a property is already present in the input, the embedded value will overwrite its current
 > value.
 
-### Realm
+### Authority
 
-Realm is an identifier of a domain used to access the Exposition.
-The list of domains is defined by the `vary:realms` directive,
-which is a map of realm names to their domain names.
-
-The `realm` embedding substitutes the realm identified based on the `host` request header.
+The `authority` embedding substitutes request [authority identifier](authorities.md).
 
 ### Language
 
@@ -47,8 +42,8 @@ If neither of the supported languages matches, the first supported language is u
 
 ### Raw header values
 
-Keys in the embedding map starting with a semicolon (:) are the names of HTTP request headers whose
-values to be embedded into an operation call.
+Values in the embedding map starting with a semicolon (:) are the names of HTTP request headers
+whose values to be embedded into an operation call.
 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).
@@ -56,6 +51,11 @@ of the [CORS](protocol.md#cors).
 [Multiple header fields](https://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.2) are embedded
 as a comma-separated list.
 
+### Route parameters
+
+Values in the embedding map starting with `/:` are the names of route parameters whose values
+to be embedded into an operation call.
+
 ### Fallbacks
 
 If the embedding function is an array, the first non-empty resolved value is used.

package/features/access.feature

@@ -1,12 +1,13 @@
+@security
 Feature: Access authorization
 
   Background:
     Given the `identity.basic` database contains:
       # developer:secret
       # user:12345
-      | _id                              | username  | password                                                     |
-      | efe3a65ebbee47ed95a73edd911ea328 | developer | $2b$10$ZRSKkgZoGnrcTNA5w5eCcu3pxDzdTduhteVYXcp56AaNcilNkwJ.O |
-      | e8e4f9c2a68d419b861403d71fabc915 | user      | $2b$10$Frszmrmsz9iwSXzBbRRMKeDVKsNxozkrLNSsN.SnVC.KPxLtQr/bK |
+      | _id                              | authority | username  | password                                                     |
+      | efe3a65ebbee47ed95a73edd911ea328 | nex       | developer | $2b$10$ZRSKkgZoGnrcTNA5w5eCcu3pxDzdTduhteVYXcp56AaNcilNkwJ.O |
+      | e8e4f9c2a68d419b861403d71fabc915 | nex       | user      | $2b$10$Frszmrmsz9iwSXzBbRRMKeDVKsNxozkrLNSsN.SnVC.KPxLtQr/bK |
     And the `identity.bans` database is empty
 
   Scenario: Deny by default
@@ -20,6 +21,7 @@ Feature: Access authorization
     When the following request is received:
       """
       GET / HTTP/1.1
+      host: nex.toa.io
       """
     Then the following reply is sent:
       """
@@ -30,6 +32,7 @@ Feature: Access authorization
     Given the annotation:
       """yaml
       /:
+        io:output: true
         auth:anonymous: true
         GET:
           dev:stub:
@@ -38,6 +41,7 @@ Feature: Access authorization
     When the following request is received:
       """
       GET / HTTP/1.1
+      host: nex.toa.io
       accept: application/yaml
       """
     Then the following reply is sent:
@@ -60,6 +64,7 @@ Feature: Access authorization
     When the following request is received:
       """
       GET / HTTP/1.1
+      host: nex.toa.io
       authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
       """
     Then the following reply is sent:
@@ -71,6 +76,7 @@ Feature: Access authorization
     Given the annotation:
       """yaml
       /:
+        io:output: true
         /:id:
           auth:id: id
           GET:
@@ -80,6 +86,7 @@ Feature: Access authorization
     When the following request is received:
       """
       GET /efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
+      host: nex.toa.io
       authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
       accept: application/yaml
       """
@@ -93,6 +100,7 @@ Feature: Access authorization
     When the following request is received:
       """
       GET /efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
+      host: nex.toa.io
       authorization: Basic dXNlcjoxMjM0NQ==
       accept: application/yaml
       """
@@ -109,6 +117,7 @@ Feature: Access authorization
     And the annotation:
       """yaml
       /:
+        io:output: true
         auth:role: developer
         GET:
           dev:stub:
@@ -118,6 +127,7 @@ Feature: Access authorization
       # identity with `developer` and `user` roles
       """
       GET / HTTP/1.1
+      host: nex.toa.io
       authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
       accept: application/yaml
       """
@@ -132,6 +142,7 @@ Feature: Access authorization
       # identity with no roles
       """
       GET / HTTP/1.1
+      host: nex.toa.io
       authorization: Basic dXNlcjoxMjM0NQ==
       """
     Then the following reply is sent:
@@ -146,6 +157,7 @@ Feature: Access authorization
     And the annotation:
       """yaml
       /:
+        io:output: true
         /:
           auth:role: developer:rust:junior  # role scope matches
           /nested:
@@ -159,6 +171,7 @@ Feature: Access authorization
     When the following request is received:
       """
       GET /nested/ HTTP/1.1
+      host: nex.toa.io
       authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
       accept: text/plain
       """
@@ -172,6 +185,7 @@ Feature: Access authorization
     When the following request is received:
       """
       GET /javascript/ HTTP/1.1
+      host: nex.toa.io
       authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
       """
     Then the following reply is sent:
@@ -190,6 +204,7 @@ Feature: Access authorization
           - developer
           - admin
         GET:
+          io:output: true
           dev:stub:
             access: granted!
       """
@@ -197,6 +212,7 @@ Feature: Access authorization
       # identity with `developer` and `user` roles
       """
       GET / HTTP/1.1
+      host: nex.toa.io
       authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
       accept: application/yaml
       """
@@ -215,6 +231,7 @@ Feature: Access authorization
     And the annotation:
       """yaml
       /:
+        io:output: true
         /rust/:id:
           auth:rule:
             id: id
@@ -233,6 +250,7 @@ Feature: Access authorization
     When the following request is received:
       """
       GET /rust/efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
+      host: nex.toa.io
       authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
       accept: application/yaml
       """
@@ -246,6 +264,7 @@ Feature: Access authorization
     When the following request is received:
       """
       GET /javascript/efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
+      host: nex.toa.io
       authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
       """
     Then the following reply is sent:
@@ -257,6 +276,7 @@ Feature: Access authorization
     Given the annotation:
       """yaml
       /:
+        io:output: true
         /:id:
           auth:id: id
           GET:
@@ -265,8 +285,37 @@ Feature: Access authorization
       """
     When the following request is received:
       """
-      GET /efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
-      authorization: Token v3.local.9oEtVJkfRw4cOJ8M4DxuVuAN29dGT26XMYyPAoXtwrkdkiJVSVj46sMNAOdlxwKGszJZV_ReOL26dxDVlsQ7QAIuRhRPlvsHYNOhcD-LApoAXV0S3IK16EMoEv7tE9z70FCLC3WoIW9RIQ8PR3uZhAdhSgBilsVOpWrk4XtnfCIlVwhYMKu79a66oZZhV2Q7Kl3nfYsf84-6rAL_1H0MsqCDUHVXuIg
+      GET /identity/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      authorization: Token ${{ developer.token }}
+
+      id: ${{ developer.id }}
+      """
+    When the following request is received:
+      """
+      GET /identity/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic dXNlcjoxMjM0NQ==
+      accept: application/yaml
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      authorization: Token ${{ user.token }}
+
+      id: ${{ user.id }}
+      """
+    When the following request is received:
+      """
+      GET /${{ developer.id }}/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Token ${{ developer.token }}
       accept: application/yaml
       """
     Then the following reply is sent:
@@ -282,8 +331,9 @@ Feature: Access authorization
       """
     When the following request is received:
       """
-      GET /efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
-      authorization: Token v3.local.cjlxn4IJ9hI92KuksguzDx7_kYxgDFFGFnfNchf0cWnmos34dqX2XpTAUBd-LqgqfuH-lVGfNvjBUkw5JtHRBiIAVaPHF3Ncc0eafwgH2DPme9pndZL92fWryGnJ-sMHA28Q6UcXsIfhgd2JZ0n-585SBhwlosC3gKTcVHK7XNljeaTen4jZPw8uY-pdbsm6dDq3aKMzl8K78_BTTfiNPG2cI_aNuHw
+      GET /${{ user.id }}/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Token ${{ developer.token }}
       accept: application/yaml
       """
     Then the following reply is sent:
@@ -295,6 +345,7 @@ Feature: Access authorization
     Given the annotation:
       """yaml
       /:
+        io:output: true
         auth:role: developer
         GET:
           dev:stub:
@@ -306,6 +357,7 @@ Feature: Access authorization
     When the following request is received:
       """
       GET / HTTP/1.1
+      host: nex.toa.io
       authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
       accept: application/yaml
       """
@@ -320,6 +372,7 @@ Feature: Access authorization
     When the following request is received:
       """
       GET / HTTP/1.1
+      host: nex.toa.io
       authorization: Token ${{ token }}
       accept: application/yaml
       """
@@ -335,6 +388,7 @@ Feature: Access authorization
     Given the annotation:
       """yaml
       /:
+        io:output: true
         /:id:
           auth:scheme: basic
           auth:id: id
@@ -345,6 +399,7 @@ Feature: Access authorization
     When the following request is received:
       """
       GET /efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
+      host: nex.toa.io
       authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
       accept: application/yaml
       """
@@ -358,6 +413,7 @@ Feature: Access authorization
     When the following request is received:
       """
       GET /efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
+      host: nex.toa.io
       authorization: Token v3.local.9oEtVJkfRw4cOJ8M4DxuVuAN29dGT26XMYyPAoXtwrkdkiJVSVj46sMNAOdlxwKGszJZV_ReOL26dxDVlsQ7QAIuRhRPlvsHYNOhcD-LApoAXV0S3IK16EMoEv7tE9z70FCLC3WoIW9RIQ8PR3uZhAdhSgBilsVOpWrk4XtnfCIlVwhYMKu79a66oZZhV2Q7Kl3nfYsf84-6rAL_1H0MsqCDUHVXuIg
       accept: text/plain
       """
@@ -374,11 +430,13 @@ Feature: Access authorization
 
     Given the annotation:
       """yaml
-      anonymous: true
+      /:
+        anonymous: true
       """
     When the following request is received:
       """
       POST /identity/roles/efe3a65ebbee47ed95a73edd911ea328/ HTTP/1.1
+      host: nex.toa.io
       content-type: application/yaml
 
       role: developer
@@ -388,62 +446,46 @@ Feature: Access authorization
       401 Unauthorized
       """
 
-  Scenario: Banning an Identity
+  Scenario: Authorization delegation
     Given the `identity.roles` database contains:
-      | _id                              | identity                         | role   |
-      | 775a648d054e4ce1a65f8f17e5b51803 | efe3a65ebbee47ed95a73edd911ea328 | system |
-    And the annotation:
-      """yaml
-      /:
-        /:id:
-          auth:id: id
-          GET:
-            dev:stub:
-              access: granted!
-      """
-    And the `identity.tokens` configuration:
+      | _id                              | identity                         | role      |
+      | 775a648d054e4ce1a65f8f17e5b51803 | efe3a65ebbee47ed95a73edd911ea328 | developer |
+    And the `echo` is running with the following manifest:
       """yaml
-      refresh: 1
+      exposition:
+        /:
+          io:output: true
+          auth:delegate: identity
+          GET: identity
       """
     When the following request is received:
       """
-      GET /e8e4f9c2a68d419b861403d71fabc915/ HTTP/1.1
-      authorization: Basic dXNlcjoxMjM0NQ==
+      GET /echo/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
+      accept: application/yaml
       """
     Then the following reply is sent:
       """
       200 OK
       authorization: Token ${{ token }}
-      """
-    When the following request is received:
-      """
-      PUT /identity/bans/e8e4f9c2a68d419b861403d71fabc915/ HTTP/1.1
-      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
-      content-type: application/yaml
 
-      banned: true
-      """
-    Then the following reply is sent:
-      """
-      204 No Content
+      identity:
+        id: efe3a65ebbee47ed95a73edd911ea328
+        roles:
+          - developer
       """
-    # accessing a resource with a banned Identity
     When the following request is received:
       """
-      GET /e8e4f9c2a68d419b861403d71fabc915/ HTTP/1.1
-      authorization: Basic dXNlcjoxMjM0NQ==
+      GET /echo/ HTTP/1.1
+      host: nex.toa.io
+      authorization: Token ${{ token }}
       """
     Then the following reply is sent:
       """
-      401 Unauthorized
-      """
-    Then after 1 second
-    When the following request is received:
-      """
-      GET /e8e4f9c2a68d419b861403d71fabc915/ HTTP/1.1
-      authorization: Token ${{ token }}
+      200 OK
       """
-    Then the following reply is sent:
+    And the reply does not contain:
       """
-      401 Unauthorized
+      authorization: Token
       """