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

package/documentation/octets.md

@@ -1,261 +0,0 @@
-# BLOBs
-
-The `octets` directive family implements operations with BLOBs, using
-the [Storages extention](/extensions/storages).
-The most common use case is to handle file uploads, downloads, and processing.
-
-## `octets:context`
-
-Sets the [storage name](/extensions/storages/readme.md#annotation) to be used for the `octets`
-directives under the current RTD Node.
-
-```yaml
-/images:
-  octets:context: images
-```
-
-## `octets:store`
-
-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 request is rejected with a `415 Unsupported Media Type` response.
-
-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).
-- `workflow`: [workflow](#workflows) to be executed once the content is successfully stored.
-
-```yaml
-/images:
-  octets:context: images
-  POST:
-    octets:store:
-      accept:
-        - image/jpeg
-        - image/png
-        - video/*
-      workflow:
-        resize: images.resize
-        analyze: images.analyze
-```
-
-Non-standard `content-meta` header can be used
-to set initial [metadata](/extensions/storages/readme.md#entry) value for the Entry.
-
-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.
-
-```http
-POST /images/ HTTP/1.1
-content-type: image/jpeg
-content-meta: foo, bar=baz
-content-meta: baz=1
-```
-
-```yaml
-meta:
-  foo: 'true'
-  bar: 'baz'
-  baz: '1'
-```
-
-If the Entry already exists, the `content-meta` header is ignored.
-
-### Response
-
-The response of the `octets:store` directive is the created Entry.
-
-```
-201 Created
-content-type: application/yaml
-
-id: eecd837c
-type: image/jpeg
-created: 1698004822358
-```
-
-If the `octets:store` 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.
-Error's properties are added to the error part, among with the `step` identifier.
-
-```
-201 Created
-content-type: multipart/yaml; boundary=cut
-
---cut
-id: eecd837c
-type: image/jpeg
-created: 1698004822358
---cut
-optimize: null
---cut
-error:
-  step: resize
-  code: TOO_SMALL
-  message: Image is too small
---cut--
-```
-
-## `octets:fetch`
-
-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`
-and `etag` ([conditional GET](https://datatracker.ietf.org/doc/html/rfc2616#section-9.3) is
-also supported).
-The `accept` request header is disregarded.
-
-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:
-        blob: false # prevent access to the original BLOB
-        meta: true  # allow access to an Entry
-```
-
-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 HTTP/1.1
-accept: application/vnd.toa.octets.entry+yaml
-```
-
-## `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:
-      meta: true
-```
-
-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`
-
-Delete the entry corresponding to the request path.
-
-```yaml
-/images:
-  octets:context: images
-  DELETE:
-    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
-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.
-
-```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

@@ -1,85 +0,0 @@
-# Protocol Support
-
-## Media types
-
-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`
-- `text/plain`
-
-The response format is determined by content negotiation
-using [negotiator](https://github.com/jshttp/negotiator).
-
-```http
-GET / HTTP/1.1
-accept: application/yaml
-```
-
-```
-200 OK
-content-type: application/yaml
-
-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
-the parts:
-
-| Response type       | Part type             |
-|---------------------|-----------------------|
-| `multipart/msgpack` | `application/msgpack` |
-| `multipart/yaml`    | `application/yaml`    |
-| `multipart/json`    | `application/json`    |
-| `multipart/text`    | `text/plain`          |
-
-Example:
-
-```
-GET /stream/ HTTP/1.1
-accept: application/yaml
-```
-
-```
-200 OK
-content-type: multipart/yaml; boundary=cut
-
---cut
-foo: bar
---cut
-baz: qux
---cut--
-```
-
-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 [`vary:embed` directive](vary.md#embeddings)
-
-The following response headers are exposed:
-
-- `authorization`
-- `content-type`
-- `content-length`
-- `etag`

package/documentation/query.md

@@ -1,275 +0,0 @@
-# Query mapping
-
-## TL;DR
-
-```yaml
-id?: string
-criteria?: string
-sort?: string
-omit?: integer
-limit?: integer
-selectors?: string[]
-projection?: string[]
-```
-
-```yaml
-# manifest.toa.yaml
-
-name: pots
-namespace: tea
-
-exposition:
-  /hot:
-    GET:
-      endpoint: enumerate
-      query:
-        criteria: state==hot
-    /top10:
-      GET:
-        endpoint: enumerate
-        query:
-          criteria: state==hot
-          sort: rank:desc
-          limit: 10
-  /latest:
-    GET:
-      endpoint: observe
-      query:
-        sort: timestamp:desc
-        limit: 1
-```
-
-Undefined `query` denies any query arguments in requests.
-
-`POST` method mapping cannot have `query` declaration.
-
-## Criteria
-
-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.
-Otherwise, criteria property is *closed*, that is, doesn't allow `criteria` in a request query.
-
-```yaml
-# manifest.toa.yaml
-
-name: dummy
-
-exposition:
-  /:
-    GET:
-      endpoint: observe
-      query:
-        criteria: state==hot; # open criteria
-```
-
-```http
-GET /dummies/?criteria=rank==5
-```
-
-The request example above will result in an operation call with the following Request:
-
-```yaml
-query:
-  criteria: state==hot;rank=5
-```
-
-### Path variables
-
-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:
-
-```yaml
-# manifest.toa.yaml
-
-name: dummies
-
-exposition:
-  /:type:
-    GET:
-      endpoint: observe
-      query:
-        criteria: ,state==hot; # open criteria
-```
-
-and the following request:
-
-```http request
-GET /dummies/cool/?criteria=rank==5
-```
-
-Operation call will have the following query criteria:
-
-```yaml
-criteria: (type==cool,state==hot);(rank=5)
-```
-
-#### POST method
-
-`POST` method semantically used to create a new entity instance, that is, calling a Transition
-without Query.
-Thus, path variables are added to the request input.
-
-Given the following declaration:
-
-```yaml
-# manifest.toa.yaml
-
-name: dummies
-
-exposition:
-  /:type:
-    POST: transit
-```
-
-and the following request:
-
-```http request
-POST /dummies/cool/
-content-type: application/yaml
-
-input:
-  rank: 5
-```
-
-Operation call will have the following input:
-
-```yaml
-type: cool
-rank: 5
-```
-
-> In case of conflict, path variables override input properties.
-
-## Omit, limit
-
-`omit` and `limit` properties can declare their default values and allowed boundaries:
-
-```yaml
-limit:
-  value: 10
-  range: [1, 100]
-```
-
-If no default value is provided, then the lower boundary of the range is used.
-
-Default values for `omit` and `limit` are:
-
-```yaml
-omit:
-  value: 0
-  range: [0, 1000]
-limit:
-  value: 10
-  range: [1, 1000]
-```
-
-Constant values can be declared using the shortcut:
-
-```yaml
-limit: 10
-```
-
-## Sort
-
-The `sort` query property defines the result order of Observations within an `objects` scope
-(enumeration).
-It comprises an ordered set of sorting statements delimited by semicolons.
-Each statement consists of an entity property name with an optional sorting direction suffix:
-`:asc`for ascending or `:desc` for descending.
-
-```yaml
-sort: rank # ascending by default
-```
-
-```yaml
-sort: rank:asc
-```
-
-```yaml
-sort: rank:desc;timestamp:asc
-```
-
-If `sort` value ends with a semicolon `;` then the sorting is considered *open*
-and can be extended using request query `sort` argument.
-
-```yaml
-sort: rank:desc; # open sort
-```
-
-Having the above `sort` declaration, the following request will result in an operation call
-with `rank:desc;timestamp:asc` sort:
-
-```http
-GET /dummies/?sort=timestamp:asc
-```
-
-## Selectors
-
-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.
-
-```yaml
-selectors: [rank, timestamp]
-```
-
-## Projection
-
-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

@@ -1,15 +0,0 @@
-# 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
-```