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

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/map.md

@@ -0,0 +1,73 @@
+# HTTP context mapping
+
+The `map` directive family is used to map HTTP request parts to operation call input properties.
+
+[Features](../features/map.feature).
+
+## TL;DR
+
+```yaml
+exposition:
+  /:group:
+    languages: [en, fr]   # supported languages
+    GET:
+      map:authority: hostname # request authority (e.g., hostname)
+      map:language: lang      # requested language
+      map:headers: # raw header values
+        token: x-access-token
+      map:segments: # route parameters
+        group: group
+      map:claims: # Bearer token claims
+        address: email
+        verified: email_verified
+      endpoint: observe
+```
+
+The operation input type must be an object.
+If the input already contains the specified keys, they will be overwritten.
+
+## Authority
+
+The `map:authority` directive maps the [authority identifier](authorities.md) to an operation call
+input property specified by the directive value.
+
+### Language
+
+The `map:language` mapping sets the [most matching](https://github.com/jshttp/negotiator) language
+code based on the `accept-language` request header and a list of supported languages defined by
+the `map:languages` directive, and also adds `accept-language` to the `Vary` HTTP response header
+value.
+
+If none of the supported languages match, the first supported language is used.
+
+> `map:languages` has a shorthand form: `languages: [en, fr]`.
+
+## Header values
+
+The `map:headers` directive maps the values of HTTP request headers to operation call input
+properties.
+The value of the directive is a map where keys are the names of the input properties and values are
+the names of the HTTP request headers.
+
+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 combined
+as a comma-separated list.
+
+## Route parameters
+
+The `map:segments` directive maps the values of route parameters to operation call input properties.
+The value of the directive is a map where keys are the names of the input properties, and values are
+the names of the route parameters.
+
+## Bearer token claims
+
+The `map:claims` directive maps the values of
+the [token claims](https://datatracker.ietf.org/doc/html/rfc7519#section-4).
+The value of the directive is a map where keys are the names of the input properties and values are
+the names of the claims.
+
+If the claim is not present in the token or the request is not authenticated using
+the [`Bearer` scheme](identity.md#bearer-scheme), the input properties are not set.

package/documentation/octets.md

@@ -14,26 +14,28 @@ directives under the current RTD Node.
   octets:context: images
 ```
 
-## `octets:store`
+## `octets:put`
 
 Stores the content of the request body into a storage, under the request path with
 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 an object with the following properties:
+The value of the directive is `null` or an object with the following properties:
 
+- `limit`: [maximum size](#stream-size-limit) of the incoming stream.
 - `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).
 - `workflow`: [workflow](#workflows) to be executed once the content is successfully stored.
+- `trust`: a list of [trusted origins](#downloading-external-content).
 
 ```yaml
 /images:
   octets:context: images
   POST:
-    octets:store:
+    octets:put:
       accept:
         - image/jpeg
         - image/png
@@ -43,47 +45,80 @@ The value of the directive is an object with the following properties:
         analyze: images.analyze
 ```
 
-### Workflows
+`content-id` header can be used to set the ID of the Entry.
+The value must match the following regular expression `^[a-zA-Z0-9-_]{1,16}$`.
 
-A workflow is a list of endpoints to be called.
-The following input will be passed to each endpoint:
+Non-standard `content-attributes` header can be used
+to set initial [metadata](/extensions/storages/readme.md#entry) value for the Entry.
+
+The value of the `content-attributes` header is a comma-separated list of key-value string pairs.
+If no value is provided for a key, the string `true` is used.
+
+```http
+POST /images/ HTTP/1.1
+content-type: image/jpeg
+content-id: example-id
+content-attributes: foo, bar=baz
+content-attributes: baz=1
+```
 
 ```yaml
-storage: string
-path: string
-entry: Entry
+attributes:
+  foo: 'true'
+  bar: 'baz'
+  baz: '1'
 ```
 
-See [Entry](/extensions/storages/readme.md#entry) and an
-example [workflow step processor](../features/steps/components/octets.tester).
+If the Entry already exists, the `content-attributes` header is ignored.
 
-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.
+### Stream size limit
 
-```yaml
-octets:store:
-  workflow:
-    resize: images.resize
-    analyze: images.analyze
+The `limit` property can be used to set the maximum size of the incoming stream in bytes.
+
+The property value can be specified as a number
+(representing bytes) or a string that combines a number with a unit (e.g., `1MB`).
+Both [binary and decimal prefixes](https://en.wikipedia.org/wiki/Binary_prefix) are supported.
+If the prefix or unit is specified _incorrectly_ (e.g., `1mb`),
+it will default to a binary prefix interpretation.
+
+- `1b`, `1B`: 1 byte
+- `1KB`: 1000 bytes
+- `1KiB`: 1024 bytes
+- `1kb`: 1024 bytes
+
+The default value is `64MiB`.
+
+### Downloading external content
+
+The `octets:put` directive can be used to download external content:
+
+```http
+POST /images/ HTTP/1.1
+content-location: https://example.com/image.jpg
+content-length: 0
 ```
 
-A workflow can be a single unit, or an array of units.
-If it's an array, the workflow units are executed in sequence.
+Requests with `content-location` header must have an empty body (`content-length: 0` header).
+
+Target origin must be allowed by the `trust` property,
+which can contain a list of trusted origins or regular expressions to match the full URL.
+
+URL of the downloaded content is stored in the `origin` property of
+the [Entry](/extensions/storages/readme.md#entry).
 
 ```yaml
-octets:store:
-  workflow:
-    - optimize: images.optimize   # executed first
-    - resize: images.resize       # executed second
-      analyze: images.analyze     # executed in parallel with `resize`
+/images:
+  octets:context: images
+  POST:
+    octets:put:
+      trust:
+        - https://example.com
+        - ^https://example\.com/[a-z]+\.jpe?g$
 ```
 
-If one of the workflow units returns an error, the execution of the workflow is interrupted.
-
 ### Response
 
-The response of the `octets:store` directive is the created Entry.
+The response of the `octets:put` directive is the created Entry.
 
 ```
 201 Created
@@ -94,12 +129,13 @@ type: image/jpeg
 created: 1698004822358
 ```
 
-If the `octets:store` directive contains a `workflow`, the response
+If the `octets:put` directive contains a `workflow`, the response
 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.
 
 ```
@@ -107,20 +143,33 @@ 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
-error:
+
 step: resize
-code: TOO_SMALL
-message: Image is too small
+error:
+  code: TOO_SMALL
+  message: Image is too small
+status: completed
+
+--cut
+
+step: analyze
+status: exception
+
 --cut--
 ```
 
-## `octets:fetch`
+## `octets:get`
 
 Fetches the content of a stored BLOB corresponding to the request path, and returns it as the
 response body with the corresponding `content-type`, `content-length`
@@ -132,65 +181,113 @@ The value of the directive is an object with the following properties:
 
 - `meta`: `boolean` indicating whether an Entry is accessible.
   Defaults to `false`.
-- `blob`: `boolean` indicating whether the original BLOB is accessible,
-  [BLOB variant](/extensions/storages/readme.md#async-fetchpath-string-maybereadable) must be
-  specified in the path otherwise.
-  Defaults to `true`.
 
 ```yaml
 /images:
   octets:context: images
   /*:
     GET:
-      octets:fetch:
+      octets:get:
         blob: false # prevent access to the original BLOB
         meta: true  # allow access to an Entry
 ```
 
-To access an Entry, the request path must be suffixed with `:meta`:
+The `octets:get: ~` 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`
+## `octets:delete`
 
-Lists the entries stored under the request path.
+Delete the entry corresponding to the request path.
 
 ```yaml
 /images:
   octets:context: images
-  GET:
-    octets:list: ~
+  DELETE:
+    octets:delete: ~
 ```
 
-Responds with a list of entry identifiers.
-
-## `octets:delete`
-
-Delete the entry corresponding to the request path.
+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: ~
+    octets:delete:
+      workflow:
+        cleanup: images.cleanup
 ```
 
-## `octets:permute`
+The error returned by the workflow prevents the deletion of the entry.
+
+## `octets:workflow`
 
-Performs
-a [permutation](/extensions/storages/readme.md#async-permutepath-string-ids-string-maybevoid) on the
-entries
-under the request path.
+Execute a [workflow](#workflows) on the entry under the request path.
 
 ```yaml
 /images:
-  octets:context: images
-  PUT:
-    octets:permute: ~
+  /*:
+    DELETE:
+      octets:workflow:
+        archive: images.archive
 ```
 
-The request body must be a list of entry identifiers.
+## Workflows
+
+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
+```
+
+- [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.
+Steps within a workflow unit are executed in parallel.
+
+```yaml
+octets:put:
+  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:put:
+  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 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:put:
+  workflow:
+    optimize: task:images.optimize
+```

package/documentation/protocol.md

@@ -4,9 +4,9 @@
 
 The following media types are supported for both requests and responses:
 
-- `application/msgpack` using [msgpackr](https://github.com/kriszyp/msgpackr)
-- `application/yaml` using [js-yaml](https://github.com/nodeca/js-yaml)
 - `application/json`
+- `application/yaml` using [js-yaml](https://github.com/nodeca/js-yaml)
+- `application/msgpack` using [msgpackr](https://github.com/kriszyp/msgpackr)
 - `text/plain`
 
 The response format is determined by content negotiation
@@ -26,8 +26,9 @@ 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
+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             |
@@ -37,6 +38,9 @@ the parts:
 | `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:
 
 ```
@@ -48,10 +52,14 @@ accept: application/yaml
 200 OK
 content-type: multipart/yaml; boundary=cut
 
+--cut
+ACK
 --cut
 foo: bar
 --cut
 baz: qux
+--cut
+FIN
 --cut--
 ```
 
@@ -60,3 +68,25 @@ 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`
+- `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

@@ -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,10 +108,10 @@ 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
+#### POST method
 
 `POST` method semantically used to create a new entity instance, that is, calling a Transition
 without Query.
@@ -173,6 +177,10 @@ Constant values can be declared using the shortcut:
 limit: 10
 ```
 
+```http
+GET /dummies/?omit=100&limit=10
+```
+
 ## Sort
 
 The `sort` query property defines the result order of Observations within an `objects` scope
@@ -209,6 +217,8 @@ 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.
@@ -224,3 +234,63 @@ 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 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
+```