@toa.io/extensions.exposition 1.0.0-alpha.3 → 1.0.0-alpha.31

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
@@ -45,7 +45,7 @@ Undefined `query` denies any query arguments in requests.
 
 ## Criteria
 
-Search critaria in [RSQL](https://github.com/jirutka/rsql-parser) format.
+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
 request query criteria using `and` logic.
@@ -77,8 +77,12 @@ query:
 
 ### Path variables
 
-Path variables are prepended to the `criteria` request query parameter using logial 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
@@ -224,3 +228,48 @@ A list of Entity properties to be included in the Observation result.
 ```yaml
 projection: [id, title, timestamp]
 ```
+
+## 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).
+
+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

@@ -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

@@ -102,7 +102,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 +110,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 +140,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,31 @@ 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
-      """
-    # accessing a resource with a banned Identity
-    When the following request is received:
-      """
-      GET /e8e4f9c2a68d419b861403d71fabc915/ HTTP/1.1
-      authorization: Basic dXNlcjoxMjM0NQ==
-      """
-    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 }}
-      """
-    Then the following reply is sent:
-      """
-      401 Unauthorized
+      identity:
+        id: efe3a65ebbee47ed95a73edd911ea328
+        roles:
+          - developer
       """

package/features/annotation.feature

@@ -4,6 +4,7 @@ Feature: Annotation
     Given the annotation:
       """yaml
       /:
+        io:output: true
         anonymous: true
         /foo:
           GET:
@@ -17,6 +18,7 @@ Feature: Annotation
     When the following request is received:
       """
       GET /foo/ HTTP/1.1
+      host: nex.toa.io
       accept: application/yaml
       """
     Then the following reply is sent: