@toa.io/extensions.exposition 0.22.1 → 0.24.0-alpha.0

package/components/identity.basic/source/authenticate.ts

@@ -1,6 +1,7 @@
 import { atob } from 'buffer'
 import { compare } from 'bcryptjs'
 import { type Query, type Maybe } from '@toa.io/types'
+import { Err } from 'error-value'
 import { type Context } from './types'
 
 export async function computation (input: string, context: Context): Promise<Maybe<Output>> {
@@ -21,8 +22,8 @@ export async function computation (input: string, context: Context): Promise<May
   else return ERR_PASSWORD_MISMATCH
 }
 
-const ERR_NOT_FOUND = new Error('NOT_FOUND')
-const ERR_PASSWORD_MISMATCH = new Error('PASSWORD_MISMATCH')
+const ERR_NOT_FOUND = Err('NOT_FOUND')
+const ERR_PASSWORD_MISMATCH = Err('PASSWORD_MISMATCH')
 
 interface Output {
   identity: {

package/components/identity.basic/source/transit.ts

@@ -1,5 +1,6 @@
 import { genSalt, hash } from 'bcryptjs'
 import { type Maybe, type Operation } from '@toa.io/types'
+import { Err } from 'error-value'
 import { type Context, type Entity, type TransitInput, type TransitOutput } from './types'
 
 export class Transition implements Operation {
@@ -60,8 +61,8 @@ function invalid (value: string, expressions: RegExp[]): boolean {
   return expressions.some((expression) => !expression.test(value))
 }
 
-const ERR_PRINCIPAL_LOCKED = new Error('PRINCIPAL_LOCKED')
-const ERR_INVALID_USERNAME = new Error('INVALID_USERNAME')
-const ERR_INVALID_PASSWORD = new Error('INVALID_PASSWORD')
+const ERR_PRINCIPAL_LOCKED = Err('PRINCIPAL_LOCKED', 'Principal username cannot be changed.')
+const ERR_INVALID_USERNAME = Err('INVALID_USERNAME', 'Username is not meeting the requirements.')
+const ERR_INVALID_PASSWORD = Err('INVALID_PASSWORD', 'Password is not meeting the requirements.')
 
 type Tokens = Context['remote']['identity']['tokens']

package/components/octets.storage/manifest.toa.yaml

@@ -0,0 +1,26 @@
+namespace: octets
+name: storage
+
+storages: ~
+
+operations:
+  store:
+    bindings: ~
+    input:
+      storage*: string
+      request*: ~
+      accept: string
+  fetch: &simple
+    bindings: ~
+    input:
+      storage*: string
+      path*: string
+  get: *simple
+  list: *simple
+  delete: *simple
+  permute:
+    bindings: ~
+    input:
+      storage*: string
+      path*: string
+      list*: [string]

package/components/octets.storage/operations/delete.js

@@ -0,0 +1,7 @@
+'use strict'
+
+function del (input, context) {
+  return context.storages[input.storage].delete(input.path)
+}
+
+exports.effect = del

package/components/octets.storage/operations/fetch.js

@@ -0,0 +1,46 @@
+'use strict'
+
+const { posix } = require('node:path')
+const { Err } = require('error-value')
+
+async function fetch (input, context) {
+  const storage = context.storages[input.storage]
+  const basename = posix.basename(input.path)
+  const path = posix.dirname(input.path)
+  const [id, suffix] = split(basename)
+  const entry = await storage.get(posix.join(path, id))
+
+  if (entry instanceof Error)
+    return entry
+
+  let variant
+
+  if (suffix !== undefined) {
+    variant = entry.variants.find((variant) => variant.name === suffix)
+
+    if (variant === undefined)
+      return NOT_FOUND
+  }
+
+  const stream = await storage.fetch(input.path)
+
+  if (stream instanceof Error)
+    return stream
+
+  const { type, size } = variant ?? entry
+
+  return { stream, checksum: entry.id, type, size }
+}
+
+function split (basename) {
+  const dot = basename.indexOf('.')
+
+  if (dot === -1)
+    return [basename, undefined]
+  else
+    return [basename.slice(0, dot), basename.slice(dot + 1)]
+}
+
+const NOT_FOUND = Err('NOT_FOUND')
+
+exports.effect = fetch

package/components/octets.storage/operations/get.js

@@ -0,0 +1,7 @@
+'use strict'
+
+function get (input, context) {
+  return context.storages[input.storage].get(input.path)
+}
+
+exports.computation = get

package/components/octets.storage/operations/list.js

@@ -0,0 +1,7 @@
+'use strict'
+
+function list (input, context) {
+  return context.storages[input.storage].list(input.path)
+}
+
+exports.effect = list

package/components/octets.storage/operations/permute.js

@@ -0,0 +1,7 @@
+'use strict'
+
+function permute (input, context) {
+  return context.storages[input.storage].permute(input.path, input.list)
+}
+
+exports.effect = permute

package/components/octets.storage/operations/store.js

@@ -0,0 +1,11 @@
+'use strict'
+
+function store (input, context) {
+  const { storage, request } = input
+  const path = request.path
+  const claim = request.headers['content-type']
+
+  return context.storages[storage].put(path, request, { claim, accept: input.accept })
+}
+
+exports.effect = store

package/cucumber.js

@@ -3,7 +3,6 @@ module.exports = {
     paths: ['features/**/*.feature'],
     requireModule: ['ts-node/register'],
     require: ['./features/**/*.ts'],
-    publishQuiet: true,
     failFast: true
   }
 }

package/documentation/access.md

@@ -13,9 +13,8 @@
 
 The Authorization is implemented as a set of [RTD Directives](tree.md#directives).
 
-Directives are executed in a predetermined order until one of them grants access to a resource. If
-none of the
-directives grants access, then the Authorization interrupts request processing and responds with an
+Directives are executed in a predetermined order until one of them grants access to a resource.
+If none of the directives grants access, then the Authorization interrupts request processing and responds with an
 authorization error.
 
 > The Authorization directive provider is named `authorization`,

package/documentation/cache.md

@@ -0,0 +1,42 @@
+# Caching
+
+Directive family `cache` implements the
+HTTP [Cache-Control](https://datatracker.ietf.org/doc/html/rfc2616#section-14.9).
+
+## `cache:control`
+
+Sets the value of the `Cache-Control` header
+for [successful responses](https://datatracker.ietf.org/doc/html/rfc2616#section-10.2)
+to [safe HTTP methods](https://developer.mozilla.org/en-US/docs/Glossary/Safe/HTTP).
+
+```yaml
+/:
+  GET:
+    cache:control: max-age=60000
+```
+
+### Implicit modifications
+
+In terms of security, the following implicit modifications are made to the `Cache-Control` header:
+
+- If it contains the `public` directive without `no-cache` and the request is authenticated,
+  the `no-cache` directive is added.
+  This is done to prevent the storage of authentication tokens in shared caches.
+- If it does not contain the `private` directive and the request is authenticated, the `private`
+  directive is added.
+  This is to prevent the storage of private data in shared caches.
+
+## `cache:exact`
+
+Same as `cache:control` without implicit modifications.
+
+```yaml
+/:
+  GET:
+    cache:exact: public, max-age=60000
+```
+
+## References
+
+- HTTP 14.9.1 [What is cacheable](https://datatracker.ietf.org/doc/html/rfc2616#section-14.9.1)
+- See also [features](/extensions/exposition/features/cache.feature)

package/documentation/octets.md

@@ -0,0 +1,196 @@
+# 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 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
+```
+
+### 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).
+
+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.
+
+### 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
+```
+
+To access an Entry, the request path must be suffixed with `:meta`:
+
+```http
+GET /images/eecd837c:meta HTTP/1.1
+```
+
+The `octets:fetch: ~` declaration is equivalent to defaults.
+
+## `octets:list`
+
+Lists the entries stored under the request path.
+
+```yaml
+/images:
+  octets:context: images
+  GET:
+    octets:list: ~
+```
+
+Responds with a list of entry identifiers.
+
+## `octets:delete`
+
+Delete the entry corresponding to the request path.
+
+```yaml
+/images:
+  octets:context: images
+  DELETE:
+    octets:delete: ~
+```
+
+## `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.

package/documentation/protocol.md

@@ -4,15 +4,59 @@
 
 The following media types are supported for both requests and responses:
 
-- `application/json`
-- `application/yaml` using [js-yaml](https://github.com/nodeca/js-yaml)
 - `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).
 
-## Streams
+```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:
 
-Reply streams are transmitted
-using [chunked transfer encoding](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Transfer-Encoding#directives).
+- [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

package/documentation/tree.md

@@ -124,7 +124,7 @@ Intermediate Nodes must not have Methods as they are unreachable.
 
 ## Directives
 
-RTD Directives are declared using RTD node or Method keys following the `{provider}:{directive}` pattern and can be used
+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.
 
@@ -151,10 +151,6 @@ When it is necessary to avoid directive nesting, a Route can be declared adjacen
 In this example, the Route `/posts/:user-id/:post-id/` has only the `authorization:role` directive
 applied.
 
-> Directives can be declared without the `{provider}:` prefix unless there are multiple directives
-> with the same name
-> across different providers.
-
 Another way to avoid nesting is to declare an _isolated_ Node as follows:
 
 ```yaml

package/features/access.feature

@@ -38,6 +38,7 @@ Feature: Access authorization
     When the following request is received:
       """
       GET / HTTP/1.1
+      accept: application/yaml
       """
     Then the following reply is sent:
       """

package/features/cache.feature

@@ -0,0 +1,160 @@
+Feature: Caching
+
+  Background:
+    Given the `identity.basic` database contains:
+      # developer:secret
+      # user:12345
+      | _id                              | username  | password                                                     |
+      | b70a7dbca6b14a2eaac8a9eb4b2ff4db | developer | $2b$10$ZRSKkgZoGnrcTNA5w5eCcu3pxDzdTduhteVYXcp56AaNcilNkwJ.O |
+    Given the `identity.roles` database contains:
+      | _id                              | identity                         | role      |
+      | 775a648d054e4ce1a65f8f17e5b51803 | b70a7dbca6b14a2eaac8a9eb4b2ff4db | developer |
+
+  Scenario: Caching successful response
+    Given the annotation:
+      """yaml
+      /:
+        anonymous: true
+        GET:
+          cache:control: max-age=60000
+          dev:stub: hello
+      """
+    When the following request is received:
+      """
+      GET / HTTP/1.1
+      accept: text/plain
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      content-type: text/plain
+      cache-control: max-age=60000
+
+      hello
+      """
+
+  Scenario: Nested cache directives
+    Given the annotation:
+      """yaml
+      /:
+        cache:control: max-age=30000
+        GET:
+          anonymous: true
+          dev:stub: hello
+        /foo:
+          auth:role: developer
+          GET:
+            dev:stub: hello
+        /bar:
+          auth:role: developer
+          cache:control: max-age=60000, public
+          GET:
+            dev:stub: hello
+      """
+    When the following request is received:
+      """
+      GET / HTTP/1.1
+      accept: text/plain
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      content-type: text/plain
+      cache-control: max-age=30000
+
+      hello
+      """
+    When the following request is received:
+      """
+      GET /foo/ HTTP/1.1
+      accept: text/plain
+      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      content-type: text/plain
+      cache-control: private, max-age=30000
+
+      hello
+      """
+    When the following request is received:
+      """
+      GET /bar/ HTTP/1.1
+      accept: text/plain
+      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      content-type: text/plain
+      cache-control: no-cache, max-age=60000, public
+
+      hello
+      """
+    And the reply does not contain:
+      """
+      cache-control: private, max-age=30000
+      """
+
+  Scenario: Cache-control is not added when request is unsafe
+    Given the annotation:
+      """yaml
+      /:
+        anonymous: true
+        cache:control: max-age=60000
+        POST:
+          dev:stub: hello
+      """
+    When the following request is received:
+      """
+      POST / HTTP/1.1
+      accept: application/yaml
+      """
+    Then the reply does not contain:
+      """
+      cache-control: max-age=60000
+      """
+
+  Scenario: Cache-control is added without implicit modifications
+    Given the annotation:
+      """yaml
+      /:
+        auth:role: developer
+        cache:exact: max-age=60000, public
+        GET:
+          dev:stub: hello
+      """
+    When the following request is received:
+      """
+      GET / HTTP/1.1
+      authorization: Basic ZGV2ZWxvcGVyOnNlY3JldA==
+      accept: text/plain
+
+      """
+    Then the following reply is sent:
+      """
+      200 OK
+      content-type: text/plain
+      cache-control: max-age=60000, public
+
+      hello
+      """
+
+  Scenario: Response without caching
+    Given the annotation:
+      """yaml
+      /:
+        anonymous: true
+        GET:
+          dev:stub: hello
+      """
+    When the following request is received:
+      """
+      GET / HTTP/1.1
+      accept: text/plain
+      """
+    Then the reply does not contain:
+      """
+      cache-control:
+      """