@toa.io/extensions.exposition 1.0.0-alpha.29 → 1.0.0-alpha.291

package/source/directives/octets/schemas.test.ts

@@ -1,21 +1,20 @@
-import * as schemas from './schemas'
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import * as schemas from './schemas.js'
 
 describe('workflow', () => {
-  const ok = [
-    { echo: 'hello world' },
-    [{ echo: 'hello world' }, { ok: 'ok' }]
-  ]
+  const ok = [{ echo: 'hello world' }, [{ echo: 'hello world' }, { ok: 'ok' }]]
 
-  const oh = [
-    { echo: [] },
-    { echo: 'hello world', ok: { not: 'ok' } }
-  ]
+  const oh = [{ echo: [] }, { echo: 'hello world', ok: { not: 'ok' } }]
 
-  it.each(ok)('should be valid', (workflow) => {
-    expect(() => schemas.workflow.validate(workflow)).not.toThrow()
-  })
+  for (const workflow of ok)
+    it('should be valid', () => {
+      assert.doesNotThrow(() => schemas.workflow.validate(workflow))
+    })
 
-  it.each(oh)('should not be valid', (workflow) => {
-    expect(() => schemas.workflow.validate(workflow)).toThrow()
-  })
+  for (const workflow of oh)
+    it('should not be valid', () => {
+      assert.throws(() => schemas.workflow.validate(workflow))
+    })
 })

package/source/directives/octets/schemas.ts

@@ -1,19 +1,15 @@
 import { resolve } from 'node:path'
-import schemas from '@toa.io/schemas'
-import type { Permissions as FetchPermissions } from './Fetch'
-import type { Permissions as ListPermissions } from './List'
-import type { Options as StoreOptions } from './Store'
-import type { Options as DeleteOptions } from './Delete'
+import * as schemas from '@toa.io/schemas'
+import type { Options as GetOptions } from './Get.js'
+import type { Options as PutOptions } from './Put.js'
+import type { Options as DeleteOptions } from './Delete.js'
 import type { Schema } from '@toa.io/schemas'
-import type { Unit } from './workflows'
+import type { Unit } from './workflows/index.js'
 
-const path = resolve(__dirname, '../../../schemas/octets')
+const path = resolve(import.meta.dirname, '../../../schemas/octets')
 const namespace = schemas.namespace(path)
 
-export const context: Schema<string> = namespace.schema('context')
-export const store: Schema<StoreOptions | null> = namespace.schema('store')
-export const fetch: Schema<FetchPermissions | null> = namespace.schema('fetch')
+export const put: Schema<PutOptions | null> = namespace.schema('put')
+export const get: Schema<GetOptions | null> = namespace.schema('get')
 export const remove: Schema<DeleteOptions | null> = namespace.schema('delete')
-export const list: Schema<ListPermissions | null> = namespace.schema('list')
-export const permute: Schema<null> = namespace.schema('permute')
 export const workflow: Schema<Unit[] | Unit> = namespace.schema('workflow')

package/source/directives/octets/types.ts

@@ -1,6 +1,8 @@
-import type * as io from '../../io'
+import type * as io from '../../io.js'
+import type { Identity } from '../auth/types.js' // meh
 
 export interface Extension {
+  identity?: Identity
   octets?: string
 }
 

package/source/directives/octets/workflows/Execution.ts

@@ -1,8 +1,9 @@
-import { Readable } from 'stream'
-import type { Unit } from './Workflow'
-import type { Remotes } from '../../../Remotes'
+import { Readable } from 'node:stream'
+import { console } from 'openspan'
+import type { Unit } from './Workflow.js'
+import type { Remotes } from '../../../Remotes.js'
 import type { Component } from '@toa.io/core'
-import type { Maybe } from '@toa.io/types'
+import type { Maybe } from '@toa.io/core/types'
 import type { Entry } from '@toa.io/extensions.storages'
 
 export class Execution extends Readable {
@@ -13,7 +14,7 @@ export class Execution extends Readable {
   private readonly discovery: Record<string, Promise<Component>> = {}
   private interrupted = false
 
-  public constructor (context: Context, units: Unit[], remotes: Remotes) {
+  public constructor(context: Context, units: Unit[], remotes: Remotes) {
     super({ objectMode: true })
 
     this.context = context
@@ -23,44 +24,87 @@ export class Execution extends Readable {
     void this.run()
   }
 
-  public override _read (): void {
-  }
+  public override _read(): void {}
 
-  private async run (): Promise<void> {
+  private async run(): Promise<void> {
     for (const unit of this.units) {
       await this.execute(unit)
 
-      if (this.interrupted)
-        break
+      if (this.interrupted) break
     }
 
     this.push(null)
   }
 
-  private async execute (unit: Unit): Promise<void> {
+  private async execute(unit: Unit): Promise<void> {
     const promises = Object.entries(unit).map(async ([step, endpoint]) => {
-      const result = await this.call(endpoint).catch((error: Error) => console.error(error))
+      try {
+        const result = await this.call(endpoint)
+
+        if (result instanceof Readable) return await this.stream(step, result)
 
-      if (result instanceof Error) {
-        this.push({ error: { step, ...result } })
-        this.interrupted = true
-      } else
-        this.push({ [step]: result ?? null })
+        this.report(step, result)
+      } catch (e: unknown) {
+        this.exception(step, e)
+      }
     })
 
     await Promise.all(promises)
   }
 
-  private async call (endpoint: string): Promise<Maybe<unknown>> {
+  private async stream(step: string, stream: Readable): Promise<void> {
+    try {
+      for await (const result of stream) this.report(step, result, false)
+
+      this.report(step, undefined, true)
+    } catch (e: unknown) {
+      this.exception(step, e)
+    }
+  }
+
+  private report(step: string, result?: Maybe<unknown>, completed = true): void {
+    const report: Report = { step }
+
+    if (completed) report.status = 'completed'
+
+    if (result instanceof Error) {
+      // an Error cannot be serialized where it sits, and the encoders only unwrap
+      // one they are handed directly — this one travels nested inside the report
+      report.error = { ...result }
+      this.interrupted = true
+    } else if (result !== undefined) {
+      report.output = result
+      this.context.steps[step] = structuredClone(result)
+    }
+
+    this.push(report)
+  }
+
+  private exception(step: string, error: unknown): void {
+    console.error('Workflow exception', error as Error)
+
+    this.push({ step, status: 'exception' } satisfies Report)
+    this.interrupted = true
+  }
+
+  private async call(endpoint: string): Promise<Maybe<unknown>> {
+    const task = endpoint.startsWith('task:')
+
+    if (task) endpoint = endpoint.slice(5)
+
     const [operation, component, namespace = 'default'] = endpoint.split('.').reverse()
     const key = `${namespace}.${component}`
 
     this.components[key] ??= await this.discover(key, namespace, component)
 
-    return await this.components[key].invoke(operation, { input: this.context })
+    return this.components[key].invoke(operation, { input: this.context, task })
   }
 
-  private async discover (key: string, namespace: string, component: string): Promise<Component> {
+  private async discover(
+    key: string,
+    namespace: string,
+    component: string
+  ): Promise<Component> {
     if (this.discovery[key] === undefined)
       this.discovery[key] = this.remotes.discover(namespace, component)
 
@@ -69,8 +113,18 @@ export class Execution extends Readable {
 }
 
 export interface Context {
+  authority: string
+  identity?: string
   storage: string
   path: string
   entry: Entry
   parameters: Record<string, string>
+  steps: Record<string, unknown>
+}
+
+interface Report {
+  step: string
+  status?: 'completed' | 'exception'
+  output?: unknown
+  error?: Record<string, unknown>
 }

package/source/directives/octets/workflows/Workflow.ts

@@ -1,37 +1,51 @@
 import { posix } from 'node:path'
 import { match } from 'matchacho'
-import { Execution } from './Execution'
-import type { Context } from './Execution'
-import type { Parameter } from '../../../RTD'
-import type { Input } from '../types'
+import { Execution } from './Execution.js'
 import type { Entry } from '@toa.io/extensions.storages'
-import type { Remotes } from '../../../Remotes'
+import type { Context } from './Execution.js'
+import type { Parameter } from '../../../RTD/index.js'
+import type { Remotes } from '../../../Remotes.js'
 
 export class Workflow {
   private readonly units: Unit[]
   private readonly remotes: Remotes
 
-  public constructor (units: Unit[] | Unit, remotes: Remotes) {
-    this.units = match<Unit[]>(units,
-      Array, (units: Unit[]) => units,
-      Object, (unit: Unit) => [unit])
+  public constructor(units: Unit[] | Unit, remotes: Remotes) {
+    this.units = match<Unit[]>(
+      units,
+      Array,
+      (units: Unit[]) => units,
+      Object,
+      (unit: Unit) => [unit]
+    )
 
     this.remotes = remotes
   }
 
-  // eslint-disable-next-line max-params
-  public execute
-  (input: Input, storage: string, entry: Entry, params: Parameter[]): Execution {
-    const path = posix.join(input.request.url, entry.id)
+  public execute(location: Location, entry: Entry, params: Parameter[]): Execution {
     const parameters: Record<string, string> = {}
 
-    for (const { name, value } of params)
-      parameters[name] = value
+    for (const { name, value } of params) parameters[name] = value
 
-    const context: Context = { storage, path, entry, parameters }
+    const context: Context = {
+      authority: location.authority,
+      identity: location.identity,
+      storage: location.storage,
+      path: posix.join(location.path, entry.id),
+      entry,
+      parameters,
+      steps: {}
+    }
 
     return new Execution(context, this.units, this.remotes)
   }
 }
 
+export interface Location {
+  authority: string
+  identity?: string
+  storage: string
+  path: string
+}
+
 export type Unit = Record<string, string>

package/source/directives/octets/workflows/index.ts

@@ -1 +1 @@
-export { Workflow, type Unit } from './Workflow'
+export { Workflow, type Unit, type Location } from './Workflow.js'

package/source/directives/require/Directive.ts

@@ -1,5 +1,5 @@
-import type { Input } from '../../io'
+import type { Input } from '../../io.js'
 
 export interface Directive {
-  preflight: (context: Input) => void
+  precall: (context: Input) => void
 }

package/source/directives/require/Headers.ts

@@ -1,18 +1,17 @@
-import { BadRequest } from '../../HTTP'
-import type { Input } from '../../io'
-import type { Directive } from './Directive'
+import { BadRequest } from '../../HTTP/index.js'
+import type { Input } from '../../io.js'
+import type { Directive } from './Directive.js'
 
 export class Headers implements Directive {
   private readonly headers: string[]
 
-  public constructor (headers: string[]) {
-    if (!Array.isArray(headers))
-      headers = [headers]
+  public constructor(headers: string[]) {
+    if (!Array.isArray(headers)) headers = [headers]
 
     this.headers = headers
   }
 
-  public preflight (context: Input): void {
+  public precall(context: Input): void {
     for (const header of this.headers)
       if (context.request.headers[header] === undefined)
         throw new BadRequest(`Header required: ${header}`)

package/source/directives/require/Require.ts

@@ -1,22 +1,21 @@
 import assert from 'node:assert'
-import { Headers } from './Headers'
-import type { Input } from '../../io'
-import type { Directive } from './Directive'
-import type { DirectiveFamily } from '../../RTD'
+import { Headers } from './Headers.js'
+import type { Input } from '../../io.js'
+import type { Directive } from './Directive.js'
+import type { DirectiveFamily } from '../../RTD/index.js'
 
 export class Require implements DirectiveFamily {
   public readonly name = 'require'
   public readonly mandatory = false
 
-  public create (name: string, value: unknown): Directive {
+  public create(name: string, value: unknown): Directive {
     assert.ok(name in directives, `Unknown directive: require:${name}`)
 
     return new directives[name](value)
   }
 
-  public preflight (instances: Directive[], context: Input): null {
-    for (const instance of instances)
-      instance.preflight(context)
+  public precall(instances: Directive[], context: Input): null {
+    for (const instance of instances) instance.precall(context)
 
     return null
   }

package/source/directives/require/index.ts

@@ -1,3 +1,3 @@
-import { Require } from './Require'
+import { Require } from './Require.js'
 
 export const req = new Require()

package/source/exceptions.ts

@@ -1,28 +1,47 @@
 import { match } from 'matchacho'
-import * as http from './HTTP'
-import { Exception as HTTPException } from './HTTP'
+import { console } from 'openspan'
+import * as http from './HTTP/index.js'
+import { Exception as HTTPException } from './HTTP/index.js'
 import type { Exception } from '@toa.io/core'
 
-export function rethrow (exception: Exception | HTTPException): void {
-  if (exception instanceof HTTPException)
-    throw exception
+export function rethrow(exception: Exception | HTTPException): void {
+  if (exception instanceof HTTPException) throw exception
 
   // see /runtime/core/src/exceptions.js
-  throw match(exception.code,
-    badRequest, () => new http.BadRequest(exception.message),
-    302, NOT_FOUND,
-    303, PRECONDITION_FAILED,
-    306, () => new http.Conflict(),
+  throw match(
+    exception.code,
+    badRequest,
+    () => new http.BadRequest(exception.message),
+    CORE_EXCEPTIONS.StateNotFound,
+    NOT_FOUND,
+    CORE_EXCEPTIONS.StatePrecondition,
+    PRECONDITION_FAILED,
+    CORE_EXCEPTIONS.Duplicate,
+    CONFLICT,
+    CORE_EXCEPTIONS.StateConcurrency,
+    CONFLICT,
+    CORE_EXCEPTIONS.EntityGuard,
+    CONFLICT,
     () => {
-      console.error(exception)
+      console.error('Request processing exception', exception)
 
       return exception
-    })
+    }
+  )
 }
 
-function badRequest (code: number): boolean {
+function badRequest(code: number): boolean {
   return (code >= 200 && code < 210) || code === 221
 }
 
 const NOT_FOUND = new http.NotFound()
 const PRECONDITION_FAILED = new http.PreconditionFailed()
+const CONFLICT = new http.Conflict()
+
+const CORE_EXCEPTIONS = {
+  StateNotFound: 302,
+  StatePrecondition: 303,
+  StateConcurrency: 304,
+  EntityGuard: 213,
+  Duplicate: 306
+}

package/source/index.ts

@@ -1,6 +1,12 @@
-export { manifest } from './manifest'
-export { deployment } from './deployment'
-export { components } from './Composition'
-export { Factory } from './Factory'
+export { manifest } from './manifest.js'
+export { deployment, image } from './deployment.js'
+export { components } from './Composition.js'
+export { Factory } from './Factory.js'
 
-export type { Remotes } from './Remotes'
+export type { Remotes } from './Remotes.js'
+
+// what an operation is written against, rather than the gateway's own
+export type { Claims, Identity } from './userland.js'
+
+// what an octets workflow is given
+export type * as octets from './octets.js'

package/source/io.ts

@@ -1,4 +1,4 @@
-import type { Context, OutgoingMessage } from './HTTP'
+import type { Context, OutgoingMessage } from './HTTP/index.js'
 
 export type Input = Context
 export type Output = OutgoingMessage | null

package/source/manifest.test.ts

@@ -1,6 +1,9 @@
+import { it, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+
 import { type Manifest } from '@toa.io/norm'
 import { generate } from 'randomstring'
-import { manifest } from './manifest'
+import { manifest } from './manifest.js'
 
 const name = 'cm-' + generate()
 const namespace = 'ns' + generate()
@@ -20,9 +23,9 @@ const declaration = {
 it('should create branch', async () => {
   const node = manifest(declaration, mf)
 
-  expect(node).toBeDefined()
-  expect(node.routes).toHaveLength(1)
-  expect(node.routes[0].path).toBe('/' + namespace + '/' + name)
+  assert.notStrictEqual(node, undefined)
+  assert.strictEqual(node.routes.length, 1)
+  assert.strictEqual(node.routes[0].path, '/' + namespace + '/' + name)
 })
 
 it('should not create node for default namespace', async () => {
@@ -30,13 +33,15 @@ it('should not create node for default namespace', async () => {
 
   const node = manifest(declaration, mf)
 
-  expect(node.routes).toHaveLength(1)
-  expect(node.routes[0].path).toBe('/' + name)
+  assert.strictEqual(node.routes.length, 1)
+  assert.strictEqual(node.routes[0].path, '/' + name)
 })
 
 it('should throw on invalid declaration type', async () => {
-  expect(() => manifest('hello' as unknown as object, mf))
-    .toThrow('Exposition declaration must be an object')
+  assert.throws(
+    () => manifest('hello' as unknown as object, mf),
+    (error: any) => /Exposition declaration must be an object/.test(error.message)
+  )
 })
 
 it('should set namespace and component', async () => {
@@ -46,6 +51,6 @@ it('should set namespace and component', async () => {
   const intemediate = root.routes[0].node
   const GET = intemediate.methods[0]
 
-  expect(GET.mapping?.namespace).toBe(namespace)
-  expect(GET.mapping?.component).toBe(name)
+  assert.strictEqual(GET.mapping?.namespace, namespace)
+  assert.strictEqual(GET.mapping?.component, name)
 })

package/source/manifest.ts

@@ -1,50 +1,55 @@
 import assert from 'node:assert'
-import { parse, type Node, type Method, type Query } from './RTD/syntax'
-import { shortcuts } from './Directive'
-import * as schemas from './schemas'
+import { parse, type Node, type Method, type Query } from './RTD/syntax/index.js'
+import { shortcuts } from './shortcuts.js'
+import * as schemas from './schemas.js'
 import type { Manifest } from '@toa.io/norm'
 
-export function manifest (declaration: object, manifest: Manifest): Node {
-  assert.ok(typeof declaration === 'object' && declaration !== null,
-    'Exposition declaration must be an object')
+export function manifest(declaration: object, manifest: Manifest): Node {
+  assert.ok(
+    typeof declaration === 'object' && declaration !== null,
+    'Exposition declaration must be an object'
+  )
 
   declaration = wrap(declaration, manifest.namespace, manifest.name)
 
   const node = parse(declaration, shortcuts)
 
-  concretize(node, manifest)
+  specify(node, manifest)
   schemas.node.validate(node)
 
   return node
 }
 
-function wrap (declaration: object, namespace: string, name: string): object {
-  const path = (namespace === undefined || namespace === 'default' ? '' : '/' + namespace) +
-    '/' + name
+function wrap(declaration: object, namespace: string, name: string): object {
+  const path =
+    (namespace === undefined || namespace === 'default' ? '' : '/' + namespace) +
+    '/' +
+    name
 
-  return { [path]: { protected: true, ...declaration } }
+  return { [path]: declaration }
 }
 
-function concretize (node: Node, manifest: Manifest): void {
+function specify(node: Node, manifest: Manifest): void {
   for (const route of node.routes) {
-    for (const method of route.node.methods)
-      concretizeMethod(method, manifest)
+    for (const method of route.node.methods) specifyMethod(method, manifest)
 
-    concretize(route.node, manifest)
+    specify(route.node, manifest)
   }
 }
 
-function concretizeMethod (method: Method, manifest: Manifest): void {
-  if (method.mapping === undefined)
-    return
+function specifyMethod(method: Method, manifest: Manifest): void {
+  if (method.mapping?.endpoint === undefined) return
 
   const operation = manifest.operations[method.mapping.endpoint]
 
-  if (operation === undefined)
-    throw new Error(`Operation '${method.mapping.endpoint}' not found`)
+  assert.ok(operation !== undefined, `Operation '${method.mapping.endpoint}' not found`)
 
-  if (method.mapping.query === undefined && operation.query !== false)
-    method.mapping.query = {} as unknown as Query // schema will substitute default values
+  if (method.mapping.query === undefined)
+    method.mapping.query = operation.query === false ? null : ({} as unknown as Query)
+
+  // a page is taken of a collection, and of nothing else: an operation that answers one object
+  // takes no `omit` and no `limit`, and refuses a request that carries them
+  method.mapping.paged = operation.type === 'observation' && operation.scope === 'objects'
 
   method.mapping.namespace = manifest.namespace
   method.mapping.component = manifest.name

package/source/octets.d.ts

@@ -0,0 +1,17 @@
+export interface WorkflowInput<
+  TParameters extends Record<string, string> = Record<string, string>,
+  TSteps extends Record<string, unknown> = Record<string, unknown>
+> {
+  authority: string
+  identity?: string
+  storage: string
+  path: string
+  entry: {
+    id: string
+    type: string
+    size: number
+    meta: Record<string, unknown>
+  }
+  parameters: TParameters
+  steps: TSteps
+}

package/source/root.ts

@@ -1,9 +1,10 @@
-import { decode, merge } from '@toa.io/generic'
-import { syntax } from './RTD'
+import { environment, merge } from '@toa.io/generic'
+import { syntax } from './RTD/index.js'
 
-export function resolve (): syntax.Node {
-  const value = process.env.TOA_EXPOSITION
-  const root = value !== undefined ? decode<syntax.Node>(value) : syntax.createNode()
+export function resolve(): syntax.Node {
+  const value = environment.get('TOA_EXPOSITION')
+  const root =
+    value !== undefined ? (JSON.parse(value) as syntax.Node) : syntax.createNode()
 
   merge(root, PREDEFINED)
 
@@ -21,15 +22,30 @@ const PREDEFINED: syntax.Node = {
           {
             verb: 'GET',
             directives: [
+              {
+                family: 'io',
+                name: 'output',
+                value: ['id', 'roles']
+              },
               {
                 family: 'auth',
                 name: 'echo',
                 value: null
-              },
+              }
+            ]
+          },
+          {
+            verb: 'POST',
+            directives: [
               {
                 family: 'io',
                 name: 'output',
                 value: ['id', 'roles']
+              },
+              {
+                family: 'auth',
+                name: 'incept',
+                value: null
               }
             ]
           }