@toa.io/extensions.exposition 0.22.1 → 0.23.0-dev.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/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/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/errors.feature

@@ -191,3 +191,21 @@ Feature: Errors
       | debug | response          |
       | false | content-length: 0 |
       | true  | Error: Broken!    |
+
+  Scenario: Not acceptable request
+    Given the annotation:
+      """yaml
+      /:
+        GET:
+          anonymous: true
+          dev:stub: hello
+      """
+    When the following request is received:
+      """
+      GET / HTTP/1.1
+      accept: image/jpeg
+      """
+    Then the following reply is sent:
+      """
+      406 Not Acceptable
+      """

package/features/identity.basic.feature

@@ -181,6 +181,7 @@ Feature: Basic authentication
     When the following request is received:
       """
       POST /identity/basic/ HTTP/1.1
+      accept: application/yaml
       content-type: application/yaml
 
       username: root
@@ -224,6 +225,7 @@ Feature: Basic authentication
       """
       PATCH /identity/basic/${{ id }}/ HTTP/1.1
       authorization: Token ${{ token }}
+      accept: application/yaml
       content-type: application/yaml
 
       username: admin