@toa.io/extensions.exposition 1.0.0-alpha.8 → 1.0.0-alpha.82

package/documentation/introspection.md

@@ -0,0 +1,82 @@
+# Resource introspection
+
+Any resource can be introspected by sending an `OPTIONS` request to the resource's path.
+The response will contain the resource's input and output schemas for each supported method.
+
+Introspection properties:
+
+- `route` route parameters
+- `query` query parameters
+- `input` input schema
+- `output` output schema
+- `errors` error codes
+
+```http
+OPTIONS /pots/:id/ HTTP/1.1
+accept: application/yaml
+```
+
+```http
+200 OK
+Allow: GET, POST, OPTIONS
+
+GET:
+  route:
+    id:
+      type: string
+      pattern: ^[a-fA-F0-9]{32}$
+  output:
+    type: array
+    items:
+      type: object
+      properties:
+        title:
+          type: string
+          maxLength: 64
+        volume:
+          type: number
+          exclusiveMinimum: 0
+          maximum: 1000
+        temperature:
+          type: number
+          exclusiveMinimum: 0
+          maximum: 300
+      additionalProperties: false
+      required:
+        - id
+        - title
+        - volume
+POST:
+  route:
+    id:
+      type: string
+      pattern: ^[a-fA-F0-9]{32}$
+  input:
+    type: object
+    properties:
+      title:
+        type: string
+        maxLength: 64
+      temperature:
+        type: number
+        exclusiveMinimum: 0
+        maximum: 300
+      volume:
+        type: number
+        exclusiveMinimum: 0
+        maximum: 1000
+    additionalProperties: false
+    required:
+      - title
+      - volume
+  output:
+    type: object
+    properties:
+      id:
+        type: string
+        pattern: ^[a-fA-F0-9]{32}$
+    additionalProperties: false
+  errors:
+    - NO_WAY
+    - WONT_CREATE
+```

package/documentation/octets.md

@@ -20,14 +20,16 @@ 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:
 
+- `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:
@@ -65,6 +67,51 @@ meta:
 
 If the Entry already exists, the `content-meta` header is ignored.
 
+### Stream size limit
+
+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:store` directive can be used to download external content:
+
+```http
+POST /images/ HTTP/1.1
+content-location: https://example.com/image.jpg
+content-length: 0
+```
+
+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
+/images:
+  octets:context: images
+  POST:
+    octets:store:
+      trust:
+        - https://example.com
+        - ^https://example\.com/[a-z]+\.jpe?g$
+```
+
 ### Response
 
 The response of the `octets:store` directive is the created Entry.
@@ -83,7 +130,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 +139,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 +254,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 +272,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 +305,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

@@ -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,7 +26,7 @@ foo: bar
 
 ### Multipart types
 
-Multipart responses are endoded using content negotiation,
+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:
@@ -38,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:
 
 ```
@@ -49,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--
 ```
 
@@ -72,6 +79,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

@@ -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
@@ -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.
@@ -225,6 +235,21 @@ A list of Entity properties to be included in the Observation result.
 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,

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.

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.