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

package/source/directives/octets/Workflow.ts

@@ -1,60 +0,0 @@
-import { NotFound } from '../../HTTP/index.js'
-import * as schemas from './schemas.js'
-import { Workflow } from './workflows/index.js'
-import { Directive } from './Directive.js'
-import type { Unit, Location } from './workflows/index.js'
-import type { Input } from './types.js'
-import type { Component } from '@toa.io/core'
-import type { Output } from '../../io.js'
-import type { Remotes } from '../../Remotes.js'
-import type { Maybe } from '@toa.io/core/types'
-import type { Entry } from '@toa.io/extensions.storages'
-import type { Parameter } from '../../RTD/index.js'
-
-export class WorkflowDirective extends Directive {
-  public readonly targeted = true
-
-  private readonly workflow: Workflow
-  private readonly discovery: Promise<Component>
-  private storage: Component | null = null
-
-  public constructor(
-    units: Unit[] | Unit,
-    discovery: Promise<Component>,
-    remotes: Remotes
-  ) {
-    super()
-    schemas.workflow.validate(units)
-
-    this.workflow = new Workflow(units, remotes)
-    this.discovery = discovery
-  }
-
-  public async apply(
-    storage: string,
-    input: Input,
-    parameters: Parameter[]
-  ): Promise<Output> {
-    this.storage ??= await this.discovery
-
-    const entry = await this.storage.invoke<Maybe<Entry>>('head', {
-      input: {
-        storage,
-        path: input.request.url
-      }
-    })
-
-    if (entry instanceof Error) throw new NotFound()
-
-    const location: Location = {
-      storage,
-      authority: input.authority,
-      path: input.request.url
-    }
-
-    return {
-      status: 202,
-      body: this.workflow.execute(location, entry, parameters)
-    }
-  }
-}

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

@@ -1,33 +0,0 @@
-import { it } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { toBytes } from './bytes.js'
-
-it('should parse bytes', async () => {
-  assert.strictEqual(toBytes('10'), 10)
-  assert.strictEqual(toBytes('10B'), 10)
-})
-
-it('should parse binary prefix', async () => {
-  assert.strictEqual(toBytes('10KiB'), 10240)
-  assert.strictEqual(toBytes('10MiB'), 10485760)
-  assert.strictEqual(toBytes('10GiB'), 10737418240)
-  assert.strictEqual(toBytes('10TiB'), 10995116277760)
-})
-
-it('should parse decimal prefix', async () => {
-  assert.strictEqual(toBytes('10kB'), 10000)
-  assert.strictEqual(toBytes('10MB'), 10000000)
-  assert.strictEqual(toBytes('10GB'), 10000000000)
-  assert.strictEqual(toBytes('10TB'), 10000000000000)
-})
-
-it('should parse incorrect value as binary', async () => {
-  assert.strictEqual(toBytes('10b'), 10)
-  assert.strictEqual(toBytes('10kb'), 10240)
-  assert.strictEqual(toBytes('10kib'), 10240)
-  assert.strictEqual(toBytes('10mb'), 10485760)
-  assert.strictEqual(toBytes('10gb'), 10737418240)
-  assert.strictEqual(toBytes('10tib'), 10995116277760)
-  assert.strictEqual(toBytes('10Mb'), 10485760)
-})

package/source/directives/octets/bytes.ts

@@ -1,18 +0,0 @@
-import assert from 'node:assert'
-
-export function toBytes(input: string): number {
-  const match = RX.exec(input)
-
-  assert.ok(match !== null, `Invalid bytes format: ${input}`)
-
-  const value = parseFloat(match.groups!.value)
-  const prefix = match.groups!.prefix?.[0].toLowerCase() ?? ''
-  const binary = match.groups!.binary !== undefined || match.groups!.unit === 'b'
-  const base = binary ? 1024 : 1000
-  const power = POWERS.indexOf(prefix)
-
-  return value * Math.pow(base, power)
-}
-
-const POWERS = ['', 'k', 'm', 'g', 't']
-const RX = /^(?<value>(\d+)(\.\d+)?)(?<prefix>[kmgt](?<binary>i)?)?(?<unit>b)?$/i

package/source/directives/octets/index.ts

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

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

@@ -1,20 +0,0 @@
-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 oh = [{ echo: [] }, { echo: 'hello world', ok: { not: 'ok' } }]
-
-  for (const workflow of ok)
-    it('should be valid', () => {
-      assert.doesNotThrow(() => schemas.workflow.validate(workflow))
-    })
-
-  for (const workflow of oh)
-    it('should not be valid', () => {
-      assert.throws(() => schemas.workflow.validate(workflow))
-    })
-})

package/source/directives/octets/schemas.ts

@@ -1,15 +0,0 @@
-import { resolve } from 'node:path'
-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/index.js'
-
-const path = resolve(import.meta.dirname, '../../../schemas/octets')
-const namespace = schemas.namespace(path)
-
-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 workflow: Schema<Unit[] | Unit> = namespace.schema('workflow')

package/source/directives/octets/types.ts

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

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

@@ -1,130 +0,0 @@
-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/core/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> {
-    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]) => {
-      try {
-        const result = await this.call(endpoint)
-
-        if (result instanceof Readable) return await this.stream(step, result)
-
-        this.report(step, result)
-      } catch (e: unknown) {
-        this.exception(step, e)
-      }
-    })
-
-    await Promise.all(promises)
-  }
-
-  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 this.components[key].invoke(operation, { input: this.context, task })
-  }
-
-  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 {
-  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,51 +0,0 @@
-import { posix } from 'node:path'
-import { match } from 'matchacho'
-import { Execution } from './Execution.js'
-import type { Entry } from '@toa.io/extensions.storages'
-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]
-    )
-
-    this.remotes = remotes
-  }
-
-  public execute(location: Location, entry: Entry, params: Parameter[]): Execution {
-    const parameters: Record<string, string> = {}
-
-    for (const { name, value } of params) parameters[name] = value
-
-    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 +0,0 @@
-export { Workflow, type Unit, type Location } from './Workflow.js'

package/source/directives/require/Directive.ts

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

package/source/directives/require/Headers.ts

@@ -1,19 +0,0 @@
-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]
-
-    this.headers = headers
-  }
-
-  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,27 +0,0 @@
-import assert from 'node:assert'
-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 {
-    assert.ok(name in directives, `Unknown directive: require:${name}`)
-
-    return new directives[name](value)
-  }
-
-  public precall(instances: Directive[], context: Input): null {
-    for (const instance of instances) instance.precall(context)
-
-    return null
-  }
-}
-
-const directives: Record<string, new (value: any) => Directive> = {
-  header: Headers,
-  headers: Headers
-}

package/source/directives/require/index.ts

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

package/source/discovery.ts

@@ -1 +0,0 @@
-export type Label = 'ping' | 'expose'

package/source/exceptions.ts

@@ -1,47 +0,0 @@
-import { match } from 'matchacho'
-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
-
-  // see /runtime/core/src/exceptions.js
-  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('Request processing exception', exception)
-
-      return exception
-    }
-  )
-}
-
-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,12 +0,0 @@
-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.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 +0,0 @@
-import type { Context, OutgoingMessage } from './HTTP/index.js'
-
-export type Input = Context
-export type Output = OutgoingMessage | null

package/source/manifest.test.ts

@@ -1,56 +0,0 @@
-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.js'
-
-const name = 'cm-' + generate()
-const namespace = 'ns' + generate()
-
-let mf: Manifest
-
-const operations = { observe: {} }
-
-beforeEach(() => {
-  mf = { namespace, name, operations } as unknown as Manifest
-})
-
-const declaration = {
-  '/': { GET: 'observe' }
-}
-
-it('should create branch', async () => {
-  const node = manifest(declaration, mf)
-
-  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 () => {
-  mf.namespace = 'default'
-
-  const node = manifest(declaration, mf)
-
-  assert.strictEqual(node.routes.length, 1)
-  assert.strictEqual(node.routes[0].path, '/' + name)
-})
-
-it('should throw on invalid declaration type', async () => {
-  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 () => {
-  const node = manifest(declaration, mf)
-
-  const root = node.routes[0].node
-  const intemediate = root.routes[0].node
-  const GET = intemediate.methods[0]
-
-  assert.strictEqual(GET.mapping?.namespace, namespace)
-  assert.strictEqual(GET.mapping?.component, name)
-})

package/source/manifest.ts

@@ -1,56 +0,0 @@
-import assert from 'node:assert'
-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'
-  )
-
-  declaration = wrap(declaration, manifest.namespace, manifest.name)
-
-  const node = parse(declaration, shortcuts)
-
-  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
-
-  return { [path]: declaration }
-}
-
-function specify(node: Node, manifest: Manifest): void {
-  for (const route of node.routes) {
-    for (const method of route.node.methods) specifyMethod(method, manifest)
-
-    specify(route.node, manifest)
-  }
-}
-
-function specifyMethod(method: Method, manifest: Manifest): void {
-  if (method.mapping?.endpoint === undefined) return
-
-  const operation = manifest.operations[method.mapping.endpoint]
-
-  assert.ok(operation !== undefined, `Operation '${method.mapping.endpoint}' not found`)
-
-  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

@@ -1,17 +0,0 @@
-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,59 +0,0 @@
-import { environment, merge } from '@toa.io/generic'
-import { syntax } from './RTD/index.js'
-
-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)
-
-  return root
-}
-
-const PREDEFINED: syntax.Node = {
-  routes: [
-    {
-      path: '/identity',
-      node: {
-        isolated: true,
-        routes: [],
-        methods: [
-          {
-            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
-              }
-            ]
-          }
-        ],
-        directives: []
-      }
-    }
-  ],
-  methods: [],
-  directives: []
-}