@toa.io/extensions.exposition 1.0.0-alpha.0 → 1.0.0-alpha.2

package/source/directives/octets/Delete.ts

@@ -1,32 +1,73 @@
+import { Readable } from 'stream'
 import { NotFound } from '../../HTTP'
 import * as schemas from './schemas'
+import { Workflow } from './workflow'
+import type { Parameter } from '../../RTD'
+import type { Unit } from './workflow'
 import type { Maybe } from '@toa.io/types'
 import type { Component } from '@toa.io/core'
-import type { Output } from '../../Directive'
-
+import type { Output } from '../../io'
 import type { Directive, Input } from './types'
+import type { Remotes } from '../../Remotes'
+import type { Entry } from '@toa.io/extensions.storages'
 
 export class Delete implements Directive {
   public readonly targeted = true
 
+  private readonly workflow?: Workflow
   private readonly discovery: Promise<Component>
   private storage: Component | null = null
 
-  public constructor (value: null, discovery: Promise<Component>) {
-    schemas.remove.validate(value)
+  public constructor (options: Options | null, discovery: Promise<Component>, remotes: Remotes) {
+    schemas.remove.validate(options)
+
+    if (options?.workflow !== undefined)
+      this.workflow = new Workflow(options.workflow, remotes)
 
     this.discovery = discovery
   }
 
-  public async apply (storage: string, request: Input): Promise<Output> {
+  public async apply (storage: string, request: Input, parameters: Parameter[]): Promise<Output> {
     this.storage ??= await this.discovery
 
-    const input = { storage, path: request.path }
-    const error = await this.storage.invoke<Maybe<unknown>>('delete', { input })
+    const entry = await this.storage.invoke<Maybe<Entry>>('get',
+      { input: { storage, path: request.url } })
 
-    if (error instanceof Error)
+    if (entry instanceof Error)
       throw new NotFound()
 
-    return {}
+    const output: Output = {}
+
+    if (this.workflow !== undefined) {
+      output.status = 202
+      output.body = Readable.from(this.execute(request, storage, entry, parameters))
+    } else
+      await this.delete(storage, request)
+
+    return output
+  }
+
+  private async delete (storage: string, request: Input): Promise<void> {
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    await this.storage!.invoke('delete',
+      { input: { storage, path: request.url } })
   }
+
+  // eslint-disable-next-line max-params
+  private async * execute
+  (request: Input, storage: string, entry: Entry, parameters: Parameter[]): AsyncGenerator {
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    for await (const chunk of this.workflow!.execute(request, storage, entry, parameters)) {
+      yield chunk
+
+      if (typeof chunk === 'object' && chunk !== null && 'error' in chunk)
+        return
+    }
+
+    await this.delete(storage, request)
+  }
+}
+
+export interface Options {
+  workflow?: Unit[] | Unit
 }

package/source/directives/octets/Fetch.ts

@@ -5,18 +5,18 @@ import type { Maybe } from '@toa.io/types'
 import type { Entry } from '@toa.io/extensions.storages'
 import type { Readable } from 'node:stream'
 import type { Component } from '@toa.io/core'
-import type { Output } from '../../Directive'
+import type { Output } from '../../io'
 
 import type { Directive, Input } from './types'
 
 export class Fetch implements Directive {
   public readonly targeted = true
 
-  private readonly permissions: Permissions = { blob: true, meta: false }
+  private readonly permissions: Required<Permissions> = { blob: true, meta: false }
   private readonly discovery: Promise<Component>
   private storage: Component = null as unknown as Component
 
-  public constructor (permissions: Partial<Permissions> | null, discovery: Promise<Component>) {
+  public constructor (permissions: Permissions | null, discovery: Promise<Component>) {
     schemas.fetch.validate(permissions)
 
     Object.assign(this.permissions, permissions)
@@ -26,19 +26,22 @@ export class Fetch implements Directive {
   public async apply (storage: string, request: Input): Promise<Output> {
     this.storage ??= await this.discovery
 
-    if (request.url.slice(-5) === ':meta')
-      return await this.get(storage, request)
-    else
-      return await this.fetch(storage, request)
-  }
+    const variant = posix.basename(request.url).includes('.')
+    const metadata = request.subtype === 'octets.entry'
 
-  private async fetch (storage: string, request: Input): Promise<Output> {
-    const filename = posix.basename(request.url)
-    const variant = filename.includes('.')
+    if (!variant && metadata)
+      if (this.permissions.meta)
+        return this.get(storage, request)
+      else
+        throw new Forbidden('Metadata is not accessible.')
 
     if (!variant && !this.permissions.blob)
       throw new Forbidden('BLOB variant must be specified.')
 
+    return await this.fetch(storage, request)
+  }
+
+  private async fetch (storage: string, request: Input): Promise<Output> {
     if ('if-none-match' in request.headers)
       return { status: 304 }
 
@@ -58,11 +61,7 @@ export class Fetch implements Directive {
   }
 
   private async get (storage: string, request: Input): Promise<Output> {
-    if (!this.permissions.meta)
-      throw new Forbidden('Metadata is not accessible.')
-
-    const path = request.url.slice(0, -5)
-    const input = { storage, path }
+    const input = { storage, path: request.url }
     const entry = await this.storage.invoke<Maybe<Entry>>('get', { input })
 
     if (entry instanceof Error)
@@ -72,9 +71,9 @@ export class Fetch implements Directive {
   }
 }
 
-interface Permissions {
-  blob: boolean
-  meta: boolean
+export interface Permissions {
+  blob?: boolean
+  meta?: boolean
 }
 
 interface FetchResult {

package/source/directives/octets/List.ts

@@ -1,32 +1,62 @@
-import { NotFound } from '../../HTTP'
+import { posix } from 'node:path'
+import { Forbidden, NotFound } from '../../HTTP'
 import * as schemas from './schemas'
+import type { Entry } from '@toa.io/extensions.storages'
 import type { Maybe } from '@toa.io/types'
 import type { Component } from '@toa.io/core'
-import type { Output } from '../../Directive'
+import type { Output } from '../../io'
 
 import type { Directive, Input } from './types'
 
 export class List implements Directive {
   public readonly targeted = false
 
+  private readonly permissions: Required<Permissions> = { meta: false }
   private readonly discovery: Promise<Component>
   private storage: Component | null = null
 
-  public constructor (value: null, discovery: Promise<Component>) {
-    schemas.remove.validate(value)
+  public constructor (permissions: Permissions | null, discovery: Promise<Component>) {
+    schemas.list.validate(permissions)
 
+    Object.assign(this.permissions, permissions)
     this.discovery = discovery
   }
 
   public async apply (storage: string, request: Input): Promise<Output> {
     this.storage ??= await this.discovery
 
-    const input = { storage, path: request.path }
-    const list = await this.storage.invoke<Maybe<unknown>>('list', { input })
+    const metadata = request.subtype === 'octets.entries'
+
+    if (metadata && !this.permissions.meta)
+      throw new Forbidden('Metadata is not accessible.')
+
+    const input = { storage, path: request.url }
+    const list = await this.storage.invoke<Maybe<string[]>>('list', { input })
 
     if (list instanceof Error)
       throw new NotFound()
 
-    return { body: list }
+    const body = metadata
+      ? await this.expand(storage, request.url, list)
+      : list
+
+    return { body }
   }
+
+  private async expand (storage: string, prefix: string, list: string[]):
+  Promise<Array<Maybe<Entry>>> {
+    const promises = list.map(async (id) => {
+      const path = posix.join(prefix, id)
+      const input = { storage, path }
+
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- ensured in `apply`
+      return this.storage!.invoke<Maybe<Entry>>('get', { input })
+    })
+
+    return await Promise.all(promises)
+  }
+}
+
+export interface Permissions {
+  meta?: boolean
 }

package/source/directives/octets/{Family.ts → Octets.ts}

@@ -5,12 +5,14 @@ import { Fetch } from './Fetch'
 import { List } from './List'
 import { Delete } from './Delete'
 import { Permute } from './Permute'
+import type { Output } from '../../io'
 import type { Component } from '@toa.io/core'
 import type { Remotes } from '../../Remotes'
-import type { Output, Family } from '../../Directive'
+import type { Family } from '../../Directive'
 import type { Directive, Input } from './types'
+import type { Parameter } from '../../RTD'
 
-class Octets implements Family<Directive> {
+export class Octets implements Family<Directive> {
   public readonly name: string = 'octets'
   public readonly mandatory: boolean = false
 
@@ -27,7 +29,8 @@ class Octets implements Family<Directive> {
     return new Class(value, this.discovery, remotes)
   }
 
-  public async preflight (directives: Directive[], input: Input): Promise<Output> {
+  public async preflight
+  (directives: Directive[], input: Input, parameters: Parameter[]): Promise<Output> {
     let context: Context | null = null
     let action: Directive | null = null
 
@@ -50,7 +53,7 @@ class Octets implements Family<Directive> {
     if (targeted !== action.targeted)
       throw new NotFound(`Trailing slash is ${action.targeted ? 'redundant' : 'required'}.`)
 
-    return await action.apply(context.storage, input)
+    return await action.apply(context.storage, input, parameters)
   }
 }
 
@@ -64,5 +67,3 @@ const DIRECTIVES: Record<string, Constructor> = {
 }
 
 type Constructor = new (value: any, discovery: Promise<Component>, remotes: Remotes) => Directive
-
-export = new Octets()

package/source/directives/octets/Permute.ts

@@ -2,7 +2,7 @@ import { NotAcceptable, NotFound } from '../../HTTP'
 import * as schemas from './schemas'
 import type { Maybe } from '@toa.io/types'
 import type { Component } from '@toa.io/core'
-import type { Output } from '../../Directive'
+import type { Output } from '../../io'
 
 import type { Directive, Input } from './types'
 
@@ -13,7 +13,7 @@ export class Permute implements Directive {
   private storage: Component | null = null
 
   public constructor (value: null, discovery: Promise<Component>) {
-    schemas.remove.validate(value)
+    schemas.permute.validate(value)
 
     this.discovery = discovery
   }
@@ -24,7 +24,7 @@ export class Permute implements Directive {
     if (request.encoder === null)
       throw new NotAcceptable()
 
-    const path = request.path
+    const path = request.url
     const list = await request.parse()
     const input = { storage, path, list }
     const error = await this.storage.invoke<Maybe<unknown>>('permute', { input })

package/source/directives/octets/Store.ts

@@ -1,25 +1,23 @@
-import { Readable } from 'node:stream'
-import { posix } from 'node:path'
 import { match } from 'matchacho'
-import { promex } from '@toa.io/generic'
 import { BadRequest, UnsupportedMediaType } from '../../HTTP'
+import { cors } from '../cors'
 import * as schemas from './schemas'
-import type { Maybe } from '@toa.io/types'
+import { Workflow } from './workflow'
+import type { Parameter } from '../../RTD'
+import type { Unit } from './workflow'
 import type { Entry } from '@toa.io/extensions.storages'
 import type { Remotes } from '../../Remotes'
 import type { ErrorType } from 'error-value'
 import type { Component } from '@toa.io/core'
-import type { Output } from '../../Directive'
+import type { Output } from '../../io'
 import type { Directive, Input } from './types'
 
 export class Store implements Directive {
   public readonly targeted = false
 
-  private readonly accept: string | undefined
-  private readonly workflow: Workflow | undefined
+  private readonly accept?: string
+  private readonly workflow?: Workflow
   private readonly discovery: Record<string, Promise<Component>> = {}
-  private readonly remotes: Remotes
-  private readonly components: Record<string, Component> = {}
   private storage: Component | null = null
 
   public constructor
@@ -31,30 +29,38 @@ export class Store implements Directive {
       Array, (types: string[]) => types.join(','),
       undefined)
 
-    this.workflow = match(options?.workflow,
-      Array, (units: Unit[]) => units,
-      Object, (unit: Unit) => [unit],
-      undefined)
+    if (options?.workflow !== undefined)
+      this.workflow = new Workflow(options.workflow, remotes)
 
     this.discovery.storage = discovery
-    this.remotes = remotes
+
+    cors.allowHeader('content-meta')
   }
 
-  public async apply (storage: string, request: Input): Promise<Output> {
+  public async apply (storage: string, request: Input, parameters: Parameter[]): Promise<Output> {
     this.storage ??= await this.discovery.storage
 
-    const input = { storage, request, accept: this.accept }
-    const entry = await this.storage.invoke('store', { input })
+    const input: StoreInput = { storage, request }
+    const meta = request.headers['content-meta']
+
+    if (this.accept !== undefined)
+      input.accept = this.accept
+
+    if (meta !== undefined)
+      input.meta = this.parseMeta(meta)
+
+    const entry = await this.storage.invoke<Entry>('store', { input })
 
     return match<Output>(entry,
       Error, (error: ErrorType) => this.throw(error),
-      () => this.reply(request, storage, entry))
+      () => this.reply(request, storage, entry, parameters))
   }
 
-  private reply (request: Input, storage: string, entry: Entry): Output {
+  // eslint-disable-next-line max-params
+  private reply (request: Input, storage: string, entry: Entry, parameters: Parameter[]): Output {
     const body = this.workflow === undefined
       ? entry
-      : Readable.from(this.execute(request, storage, entry))
+      : this.workflow.execute(request, storage, entry, parameters)
 
     return { body }
   }
@@ -66,93 +72,31 @@ export class Store implements Directive {
       error)
   }
 
-  /* eslint-disable no-useless-return, max-depth */
-
-  /**
-   * Execute workflow units sequentially, steps within a unit in parallel.
-   * Yield results as soon as they come.
-   *
-   * If you need to change this, it may take a while.
-   */
-  private async * execute (request: Input, storage: string, entry: Entry): AsyncGenerator {
-    yield entry
-
-    const path = posix.join(request.path, entry.id)
-    let interrupted = false
-
-    for (const unit of this.workflow as Workflow) {
-      if (interrupted)
-        break
-
-      const steps = Object.keys(unit)
-
-      // unit result promises queue
-      const results = Array.from(steps, promex<unknown>)
-      let next = 0
-
-      // execute steps in parallel
-      for (const step of steps)
-        // these promises are indirectly awaited in the yield loop
-        void (async () => {
-          const endpoint = unit[step]
-          const context: Context = { storage, path, entry }
-          const result = await this.call(endpoint, context)
-
-          if (interrupted)
-            return
-
-          // as a result is received, resolve the next promise from the queue
-          const promise = results[next++]
-
-          if (result instanceof Error) {
-            interrupted = true
-            promise.resolve({ error: { step, ...result } })
-
-            // cancel pending promises
-            results[next].resolve(null)
-          } else
-            promise.resolve({ [step]: result ?? null })
-        })().catch((e) => results[next].reject(e))
-
-      // yield results from the queue as they come
-      for (const promise of results) {
-        const result = await promise
-
-        if (result === null) // canceled promise
-          break
-        else
-          yield result
-      }
-    }
-  }
-
-  private async call (endpoint: string, context: Context): Promise<Maybe<unknown>> {
-    const [operation, component, namespace = 'default'] = endpoint.split('.').reverse()
-    const key = `${namespace}.${component}`
+  private parseMeta (value: string | string[]): Record<string, string> {
+    if (Array.isArray(value))
+      value = value.join(',')
 
-    this.components[key] ??= await this.discover(key, namespace, component)
+    const meta: Record<string, string> = {}
 
-    return await this.components[key].invoke(operation, { input: context })
-  }
+    for (const pair of value.split(',')) {
+      const eq = pair.indexOf('=')
+      const key = (eq === -1 ? pair : pair.slice(0, eq)).trim()
 
-  private async discover (key: string, namespace: string, component: string): Promise<Component> {
-    if (this.discovery[key] === undefined)
-      this.discovery[key] = this.remotes.discover(namespace, component)
+      meta[key] = eq === -1 ? 'true' : pair.slice(eq + 1).trim()
+    }
 
-    return await this.discovery[key]
+    return meta
   }
 }
 
-type Unit = Record<string, string>
-type Workflow = Unit[]
-
-interface Options {
-  accept: string | string[]
-  workflow: Workflow | Unit
+export interface Options {
+  accept?: string | string[]
+  workflow?: Unit[] | Unit
 }
 
-interface Context {
+interface StoreInput {
   storage: string
-  path: string
-  entry: Entry
+  request: Input
+  accept?: string
+  meta?: Record<string, string>
 }

package/source/directives/octets/index.ts

@@ -1,3 +1,3 @@
-import Family from './Family'
+import { Octets } from './Octets'
 
-export = Family
+export const octets = new Octets()

package/source/directives/octets/schemas.ts

@@ -1,12 +1,17 @@
 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 type { Schema } from '@toa.io/schemas'
 
 const path = resolve(__dirname, '../../../schemas/octets')
 const namespace = schemas.namespace(path)
 
-export const context = namespace.schema('context')
-export const store = namespace.schema('store')
-export const fetch = namespace.schema('fetch')
-export const remove = namespace.schema('delete')
-export const list = namespace.schema('list')
-export const permute = namespace.schema('permute')
+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 remove: Schema<DeleteOptions | null> = namespace.schema('delete')
+export const list: Schema<ListPermissions | null> = namespace.schema('list')
+export const permute: Schema<null> = namespace.schema('permute')

package/source/directives/octets/types.ts

@@ -1,13 +1,14 @@
-import type * as directive from '../../Directive'
+import type { Parameter } from '../../RTD'
+import type * as io from '../../io'
 
 export interface Directive {
   readonly targeted: boolean
 
-  apply: (storage: string, input: Input) => directive.Output | Promise<directive.Output>
+  apply: (storage: string, input: Input, parameters: Parameter[]) => io.Output | Promise<io.Output>
 }
 
 export interface Extension {
   octets?: string
 }
 
-export type Input = directive.Input & Extension
+export type Input = io.Input & Extension

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

@@ -0,0 +1,78 @@
+import { Readable } from 'stream'
+import type { Unit } from './Workflow'
+import type { Remotes } from '../../../Remotes'
+import type { Component } from '@toa.io/core'
+import type { Maybe } from '@toa.io/types'
+import type { Entry } from '@toa.io/extensions.storages'
+
+export class Execution extends Readable {
+  private readonly units: Unit[]
+  private readonly remotes: Remotes
+  private readonly context: Context
+  private readonly components: Record<string, Component> = {}
+  private readonly discovery: Record<string, Promise<Component>> = {}
+  private interrupted = false
+
+  public constructor (context: Context, units: Unit[], remotes: Remotes) {
+    super({ objectMode: true })
+
+    this.context = context
+    this.units = units
+    this.remotes = remotes
+
+    void this.run()
+  }
+
+  public override _read (): void {
+  }
+
+  private async run (): Promise<void> {
+    this.push(this.context.entry)
+
+    for (const unit of this.units) {
+      await this.execute(unit)
+
+      if (this.interrupted)
+        break
+    }
+
+    this.push(null)
+  }
+
+  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))
+
+      if (result instanceof Error) {
+        this.push({ error: { step, ...result } })
+        this.interrupted = true
+      } else
+        this.push({ [step]: result ?? null })
+    })
+
+    await Promise.all(promises)
+  }
+
+  private async call (endpoint: string): Promise<Maybe<unknown>> {
+    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 })
+  }
+
+  private async discover (key: string, namespace: string, component: string): Promise<Component> {
+    if (this.discovery[key] === undefined)
+      this.discovery[key] = this.remotes.discover(namespace, component)
+
+    return await this.discovery[key]
+  }
+}
+
+export interface Context {
+  storage: string
+  path: string
+  entry: Entry
+  parameters: Record<string, string>
+}

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

@@ -0,0 +1,37 @@
+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 type { Entry } from '@toa.io/extensions.storages'
+import type { Remotes } from '../../../Remotes'
+
+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])
+
+    this.remotes = remotes
+  }
+
+  // eslint-disable-next-line max-params
+  public execute
+  (request: Input, storage: string, entry: Entry, params: Parameter[]): Execution {
+    const path = posix.join(request.path, entry.id)
+    const parameters: Record<string, string> = {}
+
+    for (const { name, value } of params)
+      parameters[name] = value
+
+    const context: Context = { storage, path, entry, parameters }
+
+    return new Execution(context, this.units, this.remotes)
+  }
+}
+
+export type Unit = Record<string, string>

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

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

package/source/directives/vary/Directive.ts

@@ -0,0 +1,6 @@
+import type { Properties } from './Properties'
+import type { Input } from '../../io'
+
+export interface Directive {
+  preflight: (request: Input, properties: Properties) => void
+}