@toa.io/extensions.exposition 1.0.0-alpha.40 → 1.0.0-alpha.42

package/documentation/octets.md

@@ -20,7 +20,7 @@ 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:
@@ -83,7 +83,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 +92,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 +207,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 +225,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 +258,5 @@ 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.

package/features/octets.entries.feature

@@ -123,7 +123,6 @@ Feature: Accessing entries
       """
       200 OK
       content-type: application/yaml
-      content-length: 124
 
       id: 10cf16b458f759e0d617f2f3d83599ff
       type: application/octet-stream

package/features/octets.workflows.feature

@@ -24,7 +24,7 @@ Feature: Octets storage workflows
       """
       POST / HTTP/1.1
       host: nex.toa.io
-      accept: application/yaml
+      accept: application/yaml, multipart/yaml
       content-type: application/octet-stream
       """
     Then the following reply is sent:
@@ -33,18 +33,29 @@ Feature: Octets storage workflows
       content-type: multipart/yaml; boundary=cut
 
       --cut
+
       id: 10cf16b458f759e0d617f2f3d83599ff
       type: application/octet-stream
       size: 8169
       --cut
-      add-foo: null
+
+      step: add-foo
+      status: completed
       --cut
-      add-bar:
+
+      step: add-bar
+      output:
         bar: baz
+      status: completed
       --cut
-      add-baz: null
+
+      step: add-baz
+      status: completed
       --cut
-      diversify: null
+
+      step: diversify
+      output: hello
+      status: completed
       --cut--
       """
     When the following request is received:
@@ -88,15 +99,15 @@ Feature: Octets storage workflows
         POST:
           octets:store:
             workflow:
-              add-foo: octets.tester.foo
-              add-bar: octets.tester.err
-              add-baz: octets.tester.baz
+              - add-foo: octets.tester.foo
+              - add-bar: octets.tester.err
+              - add-baz: octets.tester.baz
       """
     When the stream of `lenna.ascii` is received with the following headers:
       """
       POST / HTTP/1.1
       host: nex.toa.io
-      accept: application/yaml
+      accept: application/yaml, multipart/yaml
       content-type: application/octet-stream
       """
     Then the following reply is sent:
@@ -109,12 +120,16 @@ Feature: Octets storage workflows
       type: application/octet-stream
       size: 8169
       --cut
-      add-foo: null
+
+      step: add-foo
+      status: completed
       --cut
+
+      step: add-bar
       error:
-        step: add-bar
         code: ERROR
         message: Something went wrong
+      status: completed
       --cut--
       """
 
@@ -149,7 +164,7 @@ Feature: Octets storage workflows
       """
       DELETE /10cf16b458f759e0d617f2f3d83599ff HTTP/1.1
       host: nex.toa.io
-      accept: application/yaml
+      accept: application/yaml, multipart/yaml
       """
     Then the following reply is sent:
       """
@@ -157,7 +172,9 @@ Feature: Octets storage workflows
       content-type: multipart/yaml; boundary=cut
 
       --cut
-      echo: 10cf16b458f759e0d617f2f3d83599ff
+      step: echo
+      status: completed
+      output: 10cf16b458f759e0d617f2f3d83599ff
       --cut--
       """
     When the following request is received:
@@ -201,7 +218,7 @@ Feature: Octets storage workflows
       """
       DELETE /10cf16b458f759e0d617f2f3d83599ff HTTP/1.1
       host: nex.toa.io
-      accept: application/yaml
+      accept: application/yaml, multipart/yaml
       """
     Then the following reply is sent:
       """
@@ -209,8 +226,10 @@ Feature: Octets storage workflows
       content-type: multipart/yaml; boundary=cut
 
       --cut
+
+      step: err
+      status: completed
       error:
-        step: err
         code: ERROR
         message: Something went wrong
       --cut--
@@ -242,7 +261,7 @@ Feature: Octets storage workflows
       """
       POST /hello/world/ HTTP/1.1
       host: nex.toa.io
-      accept: application/yaml
+      accept: application/yaml, multipart/yaml
       content-type: application/octet-stream
       """
     Then the following reply is sent:
@@ -251,11 +270,53 @@ Feature: Octets storage workflows
       content-type: multipart/yaml; boundary=cut
 
       --cut
+
       id: 10cf16b458f759e0d617f2f3d83599ff
       type: application/octet-stream
       size: 8169
       --cut
-      concat: hello world
+
+      step: concat
+      status: completed
+      output: hello world
+      --cut--
+      """
+
+  Scenario: Passing authority to the workflow
+    Given the `octets.tester` is running
+    And the annotation:
+      """yaml
+      /:
+        /:a/:b:
+          auth:anonymous: true
+          octets:context: octets
+          POST:
+            octets:store:
+              workflow:
+                authority: octets.tester.authority
+      """
+    When the stream of `lenna.ascii` is received with the following headers:
+      """
+      POST /hello/world/ HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml, multipart/yaml
+      content-type: application/octet-stream
+      """
+    Then the following reply is sent:
+      """
+      201 Created
+      content-type: multipart/yaml; boundary=cut
+
+      --cut
+
+      id: 10cf16b458f759e0d617f2f3d83599ff
+      type: application/octet-stream
+      size: 8169
+      --cut
+
+      step: authority
+      status: completed
+      output: nex
       --cut--
       """
 
@@ -287,7 +348,7 @@ Feature: Octets storage workflows
       """
       DELETE /10cf16b458f759e0d617f2f3d83599ff HTTP/1.1
       host: nex.toa.io
-      accept: application/yaml
+      accept: application/yaml, multipart/yaml
       """
     Then the following reply is sent:
       """
@@ -295,6 +356,110 @@ Feature: Octets storage workflows
       content-type: multipart/yaml; boundary=cut
 
       --cut
-      echo: 10cf16b458f759e0d617f2f3d83599ff
+
+      step: echo
+      status: completed
+      output: 10cf16b458f759e0d617f2f3d83599ff
+
+      --cut--
+      """
+
+  Scenario: Workflow with streaming response
+    Given the `octets.tester` is running
+    And the annotation:
+      """yaml
+      /:
+        auth:anonymous: true
+        octets:context: octets
+        POST:
+          octets:store:
+            workflow:
+              - foo: octets.tester.foo
+              - yield: octets.tester.yield
+      """
+    When the stream of `lenna.ascii` is received with the following headers:
+      """
+      POST / HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml, multipart/yaml
+      content-type: application/octet-stream
+      """
+    Then the following reply is sent:
+      """
+      201 Created
+      content-type: multipart/yaml; boundary=cut
+
+      --cut
+
+      id: 10cf16b458f759e0d617f2f3d83599ff
+      type: application/octet-stream
+
+      --cut
+
+      step: foo
+      status: completed
+
+      --cut
+
+      step: yield
+      output: hello
+
+      --cut
+
+      step: yield
+      output: world
+
+      --cut
+
+      step: yield
+      status: completed
+
+      --cut--
+      """
+
+  Scenario: Workflow with streaming response and an exception
+    Given the `octets.tester` is running
+    And the annotation:
+      """yaml
+      /:
+        auth:anonymous: true
+        octets:context: octets
+        POST:
+          octets:store:
+            workflow:
+              yield: octets.tester.yex
+      """
+    When the stream of `lenna.ascii` is received with the following headers:
+      """
+      POST / HTTP/1.1
+      host: nex.toa.io
+      accept: application/yaml, multipart/yaml
+      content-type: application/octet-stream
+      """
+    Then the following reply is sent:
+      """
+      201 Created
+      content-type: multipart/yaml; boundary=cut
+
+      --cut
+
+      id: 10cf16b458f759e0d617f2f3d83599ff
+      type: application/octet-stream
+
+      --cut
+
+      step: yield
+      output: hello
+
+      --cut
+
+      step: yield
+      output: world
+
+      --cut
+
+      step: yield
+      status: exception
+
       --cut--
       """

package/features/steps/components/octets.tester/manifest.toa.yaml

@@ -7,9 +7,10 @@ storages: octets
 operations:
   foo: &operation
     input:
+      authority*: string
       storage*: string
       path*: string
-      entry: object
+      entry*: object
       parameters: object
   bar: *operation
   baz: *operation
@@ -17,3 +18,6 @@ operations:
   echo: *operation
   concat: *operation
   diversify: *operation
+  yield: *operation
+  yex: *operation
+  authority: *operation

package/features/steps/components/octets.tester/operations/authority.js

@@ -0,0 +1,7 @@
+'use strict'
+
+function computation (input) {
+  return input.authority
+}
+
+exports.computation = computation

package/features/steps/components/octets.tester/operations/baz.js

@@ -4,8 +4,7 @@ import { setTimeout } from 'node:timers/promises'
 
 async function baz (input, context) {
   await setTimeout(30)
-
-  return context.storages.octets.annotate(input.path, 'baz', 'qux')
+  await context.storages.octets.annotate(input.path, 'baz', 'qux')
 }
 
 exports.effect = baz

package/features/steps/components/octets.tester/operations/diversify.js

@@ -8,7 +8,9 @@ const lenna = join(__dirname, 'lenna.png')
 async function diversify (input, context) {
   const stream = createReadStream(lenna)
 
-  return context.storages[input.storage].diversify(input.path, 'hello.png', stream)
+  await context.storages[input.storage].diversify(input.path, 'hello.png', stream)
+
+  return 'hello'
 }
 
 exports.effect = diversify

package/features/steps/components/octets.tester/operations/foo.js

@@ -1,7 +1,7 @@
 'use strict'
 
-function foo (input, context) {
-  return context.storages.octets.annotate(input.path, 'foo', 'bar')
+async function foo (input, context) {
+  await context.storages.octets.annotate(input.path, 'foo', 'bar')
 }
 
 exports.effect = foo

package/features/steps/components/octets.tester/operations/yex.js

@@ -0,0 +1,16 @@
+'use strict'
+
+import { setTimeout } from 'node:timers/promises'
+
+async function * effect (_) {
+  await setTimeout(10)
+  yield 'hello'
+
+  await setTimeout(10)
+  yield 'world'
+
+  await setTimeout(10)
+  throw new Error('Oops!')
+}
+
+exports.effect = effect

package/features/steps/components/octets.tester/operations/yield.js

@@ -0,0 +1,13 @@
+'use strict'
+
+import { setTimeout } from 'node:timers/promises'
+
+async function * effect (_) {
+  await setTimeout(10)
+  yield 'hello'
+
+  await setTimeout(10)
+  yield 'world'
+}
+
+exports.effect = effect

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/extensions.exposition",
-  "version": "1.0.0-alpha.40",
+  "version": "1.0.0-alpha.42",
   "description": "Toa Exposition",
   "author": "temich <tema.gurtovoy@gmail.com>",
   "homepage": "https://github.com/toa-io/toa#readme",
@@ -17,9 +17,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@toa.io/core": "1.0.0-alpha.40",
-    "@toa.io/generic": "1.0.0-alpha.40",
-    "@toa.io/schemas": "1.0.0-alpha.40",
+    "@toa.io/core": "1.0.0-alpha.42",
+    "@toa.io/generic": "1.0.0-alpha.42",
+    "@toa.io/schemas": "1.0.0-alpha.42",
     "bcryptjs": "2.4.3",
     "error-value": "0.3.0",
     "js-yaml": "4.1.0",
@@ -44,11 +44,11 @@
     "features:security": "cucumber-js --tags @security"
   },
   "devDependencies": {
-    "@toa.io/agent": "1.0.0-alpha.40",
-    "@toa.io/extensions.storages": "1.0.0-alpha.40",
+    "@toa.io/agent": "1.0.0-alpha.42",
+    "@toa.io/extensions.storages": "1.0.0-alpha.42",
     "@types/bcryptjs": "2.4.3",
     "@types/cors": "2.8.13",
     "@types/negotiator": "0.6.1"
   },
-  "gitHead": "973a253abb982ddd6cdd7427ef98331d1157180d"
+  "gitHead": "6df7ba51d3f8f419b95253538e08dc7e9bc14072"
 }

package/source/HTTP/messages.test.ts

@@ -1,9 +1,13 @@
-import { Readable } from 'node:stream'
+import { PassThrough, Readable } from 'node:stream'
+import * as streamConsumers from 'node:stream/consumers'
+import { once } from 'node:events'
 import { generate } from 'randomstring'
 import * as msgpack from 'msgpackr'
-import { read } from './messages'
+import { multipart, read, type OutgoingMessage } from './messages'
 import { BadRequest, UnsupportedMediaType } from './exceptions'
+import { formats } from './formats'
 import { Timing } from './Timing'
+import type * as http from 'node:http'
 import type { Context } from './Context'
 
 beforeEach(() => {
@@ -69,6 +73,39 @@ describe('read', () => {
 
     await expect(read(request)).rejects.toThrow(BadRequest)
   })
+
+  it('should output correct mulitpart format', async () => {
+    const response = new class extends PassThrough {
+      public readonly headers = new Headers()
+
+      public setHeader (key: string, value: string): this {
+        this.headers.set(key, value)
+
+        return this
+      }
+    }()
+
+    const context = { encoder: formats['text/plain'] } as unknown as Context
+    const message = { body: Readable.from(['Hello', 'New', 'World']) } as unknown as OutgoingMessage
+
+    multipart(message, context, response as unknown as http.ServerResponse)
+
+    await once(message.body, 'end')
+
+    const result = await streamConsumers.text(response)
+
+    expect(result).toBe([
+      '--cut',
+      '',
+      'Hello',
+      '--cut',
+      '',
+      'New',
+      '--cut',
+      '',
+      'World',
+      '--cut--'].join('\r\n'))
+  })
 })
 
 export function createContext

package/source/HTTP/messages.ts

@@ -72,7 +72,7 @@ function stream
   })
 }
 
-function multipart
+export function multipart
 (message: OutgoingMessage, context: Context, response: http.ServerResponse): void {
   if (context.encoder === null)
     throw new NotAcceptable()
@@ -82,7 +82,11 @@ function multipart
   response.setHeader('content-type', `${encoder.multipart}; boundary=${BOUNDARY}`)
 
   message.body
-    .map((part: unknown) => Buffer.concat([CUT, encoder.encode(part), CRLF]))
+    .map((part: unknown) => Buffer.concat([
+      CUT,
+      CRLF /* indicates no boundary headers */,
+      encoder.encode(part),
+      CRLF]))
     .on('end', () => response.end(FINALCUT))
     .pipe(response)
 }