@toa.io/extensions.exposition 0.22.0 → 0.23.0-dev.0

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

@@ -1,27 +1,30 @@
 import { atob } from 'buffer'
 import { compare } from 'bcryptjs'
-import { type Query } from '@toa.io/types'
-import { Nope, type Nopeable } from 'nopeable'
+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<Nopeable<Output>> {
+export async function computation (input: string, context: Context): Promise<Maybe<Output>> {
   const [username, password] = atob(input).split(':')
   const query: Query = { criteria: `username==${username}` }
   const credentials = await context.local.observe({ query })
 
-  if (credentials instanceof Nope)
+  if (credentials instanceof Error)
     return credentials
 
   if (credentials === null)
-    return new Nope('NOT_FOUND')
+    return ERR_NOT_FOUND
 
   const spicy = password + context.configuration.pepper
   const match = await compare(spicy, credentials.password)
 
   if (match) return { identity: { id: credentials.id } }
-  else return new Nope('PASSWORD_MISMATCH')
+  else return ERR_PASSWORD_MISMATCH
 }
 
+const ERR_NOT_FOUND = Err('NOT_FOUND')
+const ERR_PASSWORD_MISMATCH = Err('PASSWORD_MISMATCH')
+
 interface Output {
   identity: {
     id: string

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

@@ -1,8 +1,7 @@
-import { type Nopeable } from 'nopeable'
 import { type Context } from './types'
 
 export async function effect
-(input: CreateInput, context: Context): Promise<Nopeable<CreateOutput>> {
+(input: CreateInput, context: Context): Promise<CreateOutput> {
   const [username, password] = atob(input.credentials).split(':')
   const request = { input: { username, password }, query: { id: input.id } }
 

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

@@ -1,6 +1,6 @@
 import { genSalt, hash } from 'bcryptjs'
-import { type Operation } from '@toa.io/types'
-import { Nope, type Nopeable } from 'nopeable'
+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 {
@@ -21,7 +21,7 @@ export class Transition implements Operation {
     this.passwrodRx = toRx(context.configuration.password)
   }
 
-  public async execute (input: TransitInput, object: Entity): Promise<Nopeable<TransitOutput>> {
+  public async execute (input: TransitInput, object: Entity): Promise<Maybe<TransitOutput>> {
     const existent = object._version !== 0
 
     if (existent)
@@ -29,17 +29,17 @@ export class Transition implements Operation {
 
     if (input.username !== undefined) {
       if (existent && object.username === this.principal)
-        return new Nope('PRINCIPAL_LOCKED', 'Principal username cannot be changed.')
+        return ERR_PRINCIPAL_LOCKED
 
       if (invalid(input.username, this.usernameRx))
-        return new Nope('INVALID_USERNAME', 'Username is not meeting the requirements.')
+        return ERR_INVALID_USERNAME
 
       object.username = input.username
     }
 
     if (input.password !== undefined) {
       if (invalid(input.password, this.passwrodRx))
-        return new Nope('INVALID_PASSWORD', 'Password is not meeting the requirements.')
+        return ERR_INVALID_PASSWORD
 
       const salt = await genSalt(this.rounds)
       const spicy = input.password + this.pepper
@@ -61,4 +61,8 @@ function invalid (value: string, expressions: RegExp[]): boolean {
   return expressions.some((expression) => !expression.test(value))
 }
 
+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/identity.basic/source/types.ts

@@ -1,8 +1,8 @@
-import { type Call, type Observation, type Query } from '@toa.io/types'
+import { type Call, type Maybe, type Observation, type Query } from '@toa.io/types'
 
 export interface Context {
   local: {
-    observe: Observation<Entity>
+    observe: Observation<Maybe<Entity>>
     transit: Call<TransitOutput, TransitInput>
   }
   remote: {

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

@@ -1,5 +1,4 @@
-import { Nope, type Nopeable } from 'nopeable'
-import { type Operation } from '@toa.io/types'
+import { type Maybe, type Operation } from '@toa.io/types'
 import { type AuthenticateOutput, type Context } from './types'
 
 export class Computation implements Operation {
@@ -13,10 +12,10 @@ export class Computation implements Operation {
     this.observe = context.local.observe
   }
 
-  public async execute (token: string): Promise<Nopeable<AuthenticateOutput>> {
+  public async execute (token: string): Promise<Maybe<AuthenticateOutput>> {
     const claim = await this.decrypt({ input: token })
 
-    if (claim instanceof Nope)
+    if (claim instanceof Error)
       return claim
 
     const identity = claim.identity
@@ -28,7 +27,7 @@ export class Computation implements Operation {
       const revocation = await this.observe({ query: { id: identity.id } })
 
       if (revocation !== null && iat < revocation.revokedAt)
-        return new Nope('REVOKED')
+        return ERR_TOKEN_REVOKED
     }
 
     const refresh = stale || claim.refresh
@@ -36,3 +35,5 @@ export class Computation implements Operation {
     return { identity, refresh }
   }
 }
+
+const ERR_TOKEN_REVOKED = new Error('TOKEN_REVOKED')

package/components/identity.tokens/source/decrypt.ts

@@ -1,9 +1,9 @@
 import { V3 } from 'paseto'
-import { Nope, type Nopeable } from 'nopeable'
+import { type Maybe } from '@toa.io/types'
 import { type Context, type Claim, type DecryptOutput } from './types'
 
 export async function computation (token: string, context: Context):
-Promise<Nopeable<DecryptOutput>> {
+Promise<Maybe<DecryptOutput>> {
   let refresh = false
   let claim = await decrypt(token, context.configuration.key0)
 
@@ -12,8 +12,14 @@ Promise<Nopeable<DecryptOutput>> {
     claim = await decrypt(token, context.configuration.key1)
   }
 
-  if (claim === null) return new Nope('INVALID_TOKEN', 'Invalid token')
-  else return { identity: claim.identity, iat: claim.iat, exp: claim.exp, refresh }
+  if (claim === null)
+    return ERR_INVALID_TOKEN
+  else return {
+    identity: claim.identity,
+    iat: claim.iat,
+    exp: claim.exp,
+    refresh
+  }
 }
 
 async function decrypt (token: string, key: string): Promise<Claim | null> {
@@ -23,3 +29,5 @@ async function decrypt (token: string, key: string): Promise<Claim | null> {
     return null
   }
 }
+
+const ERR_INVALID_TOKEN = new Error('INVALID_TOKEN')

package/components/identity.tokens/source/encrypt.test.ts

@@ -31,5 +31,5 @@ it('should encrypt with given lifetime', async () => {
 
   await timeout(lifetime * 1000)
 
-  await expect(decrypt(encrypted, context)).resolves.toMatchObject({ code: 'INVALID_TOKEN' })
+  await expect(decrypt(encrypted, context)).resolves.toMatchObject({ message: 'INVALID_TOKEN' })
 })

package/components/identity.tokens/source/types.ts

@@ -1,9 +1,9 @@
-import { type Call, type Observation } from '@toa.io/types'
+import { type Call, type Maybe, type Observation } from '@toa.io/types'
 
 export interface Context {
   local: {
     observe: Observation<Entity>
-    decrypt: Call<DecryptOutput, string>
+    decrypt: Call<Maybe<DecryptOutput>, string>
   }
   configuration: Configuration
 }

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