@toa.io/extensions.exposition 1.0.0-alpha.0 → 1.0.0-alpha.10

package/documentation/io.md

@@ -0,0 +1,56 @@
+# I/O restrictions
+
+The Exposition comes with `io` directives to control access to the operation's input and output
+properties.
+
+## `io: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.
+
+## `io: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 and errors.

package/documentation/octets.md

@@ -23,7 +23,7 @@ If request's `content-type` is not acceptable, or if the request body does not p
 the [validation](/extensions/storages/readme.md#async-putpath-string-stream-readable-type-typecontrol-maybeentry),
 the request is rejected with a `415 Unsupported Media Type` response.
 
-The value of the directive is an object with the following properties:
+The value of the directive is `null` or an object with the following properties:
 
 - `accept`: a media type or an array of media types that are acceptable.
   If the `accept` property is not specified, any media type is acceptable (which is the default).
@@ -43,43 +43,27 @@ The value of the directive is an object with the following properties:
         analyze: images.analyze
 ```
 
-### Workflows
-
-A workflow is a list of endpoints to be called.
-The following input will be passed to each endpoint:
-
-```yaml
-storage: string
-path: string
-entry: Entry
-```
-
-See [Entry](/extensions/storages/readme.md#entry) and an
-example [workflow step processor](../features/steps/components/octets.tester).
+Non-standard `content-meta` header can be used
+to set initial [metadata](/extensions/storages/readme.md#entry) value for the Entry.
 
-A _workflow unit_ is an object with keys referencing the workflow step identifier, and an endpoint
-as value.
-Steps within a workflow unit are executed in parallel.
+The value of the `content-meta` header is a comma-separated list of key-value string pairs.
+If no value is provided for a key, the string `true` is used.
 
-```yaml
-octets:store:
-  workflow:
-    resize: images.resize
-    analyze: images.analyze
+```http
+POST /images/ HTTP/1.1
+content-type: image/jpeg
+content-meta: foo, bar=baz
+content-meta: baz=1
 ```
 
-A workflow can be a single unit, or an array of units.
-If it's an array, the workflow units are executed in sequence.
-
 ```yaml
-octets:store:
-  workflow:
-    - optimize: images.optimize   # executed first
-    - resize: images.resize       # executed second
-      analyze: images.analyze     # executed in parallel with `resize`
+meta:
+  foo: 'true'
+  bar: 'baz'
+  baz: '1'
 ```
 
-If one of the workflow units returns an error, the execution of the workflow is interrupted.
+If the Entry already exists, the `content-meta` header is ignored.
 
 ### Response
 
@@ -114,9 +98,9 @@ created: 1698004822358
 optimize: null
 --cut
 error:
-step: resize
-code: TOO_SMALL
-message: Image is too small
+  step: resize
+  code: TOO_SMALL
+  message: Image is too small
 --cut--
 ```
 
@@ -147,26 +131,42 @@ The value of the directive is an object with the following properties:
         meta: true  # allow access to an Entry
 ```
 
-To access an Entry, the request path must be suffixed with `:meta`:
+The `octets:fetch: ~` declaration is equivalent to defaults.
+
+To access an Entry, the `accept` request header must contain the `octets.entry` subtype
+in
+the `toa` [vendor tree](https://datatracker.ietf.org/doc/html/rfc6838#section-3.2):
 
 ```http
-GET /images/eecd837c:meta HTTP/1.1
+GET /images/eecd837c HTTP/1.1
+accept: application/vnd.toa.octets.entry+yaml
 ```
 
-The `octets:fetch: ~` declaration is equivalent to defaults.
-
 ## `octets:list`
 
 Lists the entries stored under the request path.
 
+The value of the directive is an object with the following properties:
+
+- `meta`: `boolean` indicating whether the list of Entries is accessible.
+  Defaults to `false`, which means that only entry identifiers are returned.
+
 ```yaml
 /images:
   octets:context: images
   GET:
-    octets:list: ~
+    octets:list:
+      meta: true
 ```
 
-Responds with a list of entry identifiers.
+The `octets:list: ~` declaration is equivalent to defaults.
+
+To access a list of Entries, the `accept` request header must contain the `octets.entries` subtype:
+
+```http
+GET /images/ HTTP/1.1
+accept: application/vnd.toa.octets.entries+yaml
+```
 
 ## `octets:delete`
 
@@ -179,6 +179,20 @@ Delete the entry corresponding to the request path.
     octets:delete: ~
 ```
 
+The value of the directive may contain a [workflow](#workflows) declaration, to be executed before
+the entry is deleted.
+
+```yaml
+/images:
+  octets:context: images
+  DELETE:
+    octets:delete:
+      workflow:
+        cleanup: images.cleanup
+```
+
+The error returned by the workflow prevents the deletion of the entry.
+
 ## `octets:permute`
 
 Performs
@@ -194,3 +208,54 @@ under the request path.
 ```
 
 The request body must be a list of entry identifiers.
+
+## `octets:workflow`
+
+Execute a [workflow](#workflows) on the entry under the request path.
+
+```yaml
+/images:
+  /*:
+    DELETE:
+      octets:workflow:
+        archive: images.archive
+```
+
+## Workflows
+
+A workflow is a list of endpoints to be called.
+The following input will be passed to each endpoint:
+
+```yaml
+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).
+
+A _workflow unit_ is an object with keys referencing the workflow step identifier, and an endpoint
+as value.
+Steps within a workflow unit are executed in parallel.
+
+```yaml
+octets:store:
+  workflow:
+    resize: images.resize
+    analyze: images.analyze
+```
+
+A workflow can be a single unit, or an array of units.
+If it's an array, the workflow units are executed in sequence.
+
+```yaml
+octets:store:
+  workflow:
+    - 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 an error, the execution of the workflow is interrupted.

package/documentation/protocol.md

@@ -27,7 +27,8 @@ foo: bar
 ### Multipart types
 
 Multipart responses are endoded using content negotiation,
-and the `content-type` of the response is set to one of the custom `multipart/` subtypes, corresponding to the type of
+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             |
@@ -60,3 +61,22 @@ 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
+
+## 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`
+- headers used by the [`vary:embed` directive](vary.md#embeddings)
+
+The following response headers are exposed:
+
+- `authorization`
+- `content-type`
+- `content-length`
+- `etag`

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,7 +77,7 @@ query:
 
 ### Path variables
 
-Path variables are prepended to the `criteria` request query parameter using logial AND,
+Path variables are prepended to the `criteria` request query parameter using logical AND,
 except for the [`POST` method](#post-method).
 
 Given the following declaration:
@@ -107,7 +107,7 @@ Operation call will have the following query criteria:
 criteria: state==hot;type==cool;rank=5
 ```
 
-### POST method
+#### POST method
 
 `POST` method semantically used to create a new entity instance, that is, calling a Transition
 without Query.
@@ -224,3 +224,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/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

@@ -0,0 +1,69 @@
+# HTTP request details
+
+The `vary` directives family provides the capability to include HTTP request details as input for an
+operation call.
+
+## TL;DR
+
+```yaml
+exposition:
+  realms:
+    toa: the.toa.io
+  /:
+    vary:languages: [en, fr]
+    GET:
+      vary:embed:
+        lang: language # predefined embeddings
+        realm: realm
+        token: :x-access-token # raw header value
+      endpoint: dummies.get
+```
+
+## Embeddings
+
+Request parts are embedded into the operation call according to the mapping
+defined by the `vary:embed` directive.
+The keys in the embedding map are the names of the input properties details to be embedded to,
+and the values are the names of the embedding functions.
+If the value is an array, the first non-empty embedding function's result is used.
+
+> If a property is already present in the input, the embedded value will overwrite its current
+> value.
+
+### Realm
+
+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.
+
+### Language
+
+The `language` embedding substitutes the most matching language code based on the `accept-language`
+request header and a list of supported languages defined by the `vary:languages` directive, and also
+adds `accept-language` to the `vary` HTTP response header value.
+If neither of the supported languages matches, the first supported language is used.
+
+### 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.
+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 embedded
+as a comma-separated list.
+
+### Fallbacks
+
+If the embedding function is an array, the first non-empty resolved value is used.
+
+```yaml
+vary:embed:
+  ip: # fallbacks
+    - :CloudFront-Viewer-Address
+    - :CF-Connecting-IP
+    - :X-Appengine-User-IP
+```

package/features/access.feature

@@ -30,6 +30,7 @@ Feature: Access authorization
     Given the annotation:
       """yaml
       /:
+        io:output: true
         auth:anonymous: true
         GET:
           dev:stub:
@@ -71,6 +72,7 @@ Feature: Access authorization
     Given the annotation:
       """yaml
       /:
+        io:output: true
         /:id:
           auth:id: id
           GET:
@@ -109,6 +111,7 @@ Feature: Access authorization
     And the annotation:
       """yaml
       /:
+        io:output: true
         auth:role: developer
         GET:
           dev:stub:
@@ -146,6 +149,7 @@ Feature: Access authorization
     And the annotation:
       """yaml
       /:
+        io:output: true
         /:
           auth:role: developer:rust:junior  # role scope matches
           /nested:
@@ -190,6 +194,7 @@ Feature: Access authorization
           - developer
           - admin
         GET:
+          io:output: true
           dev:stub:
             access: granted!
       """
@@ -215,6 +220,7 @@ Feature: Access authorization
     And the annotation:
       """yaml
       /:
+        io:output: true
         /rust/:id:
           auth:rule:
             id: id
@@ -257,6 +263,7 @@ Feature: Access authorization
     Given the annotation:
       """yaml
       /:
+        io:output: true
         /:id:
           auth:id: id
           GET:
@@ -295,6 +302,7 @@ Feature: Access authorization
     Given the annotation:
       """yaml
       /:
+        io:output: true
         auth:role: developer
         GET:
           dev:stub:
@@ -335,6 +343,7 @@ Feature: Access authorization
     Given the annotation:
       """yaml
       /:
+        io:output: true
         /:id:
           auth:scheme: basic
           auth:id: id
@@ -374,7 +383,8 @@ Feature: Access authorization
 
     Given the annotation:
       """yaml
-      anonymous: true
+      /:
+        anonymous: true
       """
     When the following request is received:
       """
@@ -396,6 +406,7 @@ Feature: Access authorization
       """yaml
       /:
         /:id:
+          io:output: true
           auth:id: id
           GET:
             dev:stub:
@@ -425,7 +436,7 @@ Feature: Access authorization
       """
     Then the following reply is sent:
       """
-      204 No Content
+      200 OK
       """
     # accessing a resource with a banned Identity
     When the following request is received:

package/features/annotation.feature

@@ -4,6 +4,7 @@ Feature: Annotation
     Given the annotation:
       """yaml
       /:
+        io:output: true
         anonymous: true
         /foo:
           GET:

package/features/body.feature

@@ -5,7 +5,8 @@ Feature: Request body
       """yaml
       exposition:
         /:
-          POST: transit
+          io:output: true
+          POST: create
       """
     When the following request is received:
       """
@@ -25,6 +26,7 @@ Feature: Request body
       """yaml
       exposition:
         /:name:
+          io:output: true
           GET: <operation>
       """
     When the following request is received:

package/features/cache.feature

@@ -14,6 +14,7 @@ Feature: Caching
     Given the annotation:
       """yaml
       /:
+        io:output: true
         anonymous: true
         GET:
           cache:control: max-age=60000
@@ -37,6 +38,7 @@ Feature: Caching
     Given the annotation:
       """yaml
       /:
+        io:output: true
         cache:control: max-age=30000
         GET:
           anonymous: true
@@ -120,6 +122,7 @@ Feature: Caching
     Given the annotation:
       """yaml
       /:
+        io:output: true
         auth:role: developer
         cache:exact: max-age=60000, public
         GET: