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

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,10 +0,0 @@
-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/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: []
-}

package/source/service.ts

@@ -1,95 +0,0 @@
-import assert from 'node:assert'
-import { console, traces, type LevelName, type TracesOptions } from 'openspan'
-import { Gateway } from './Gateway.js'
-import { Remotes } from './Remotes.js'
-import { Tree } from './RTD/index.js'
-import { EndpointsFactory } from './Endpoint.js'
-import { families, interceptors } from './directives/index.js'
-import { DirectivesFactory } from './Directive.js'
-import { Composition } from './Composition.js'
-import * as root from './root.js'
-import { ATOM_GROUP, CHANNEL } from '@toa.io/definitions/extensions.exposition'
-import { Interception } from './Interception.js'
-import { Dispatcher } from './RPC/index.js'
-import { Server as Model } from './MCP/index.js'
-import * as http from './HTTP/index.js'
-import { environment } from '@toa.io/generic'
-import type { Broadcast } from './Gateway.js'
-import type { Connector } from '@toa.io/core'
-import type { Host } from './Factory.js'
-
-/**
- * The gateway. A composition loads this extension for its tenants alone, so what the
- * gateway is made of is reached from here and nowhere the factory imports.
- */
-export async function service(host: Host): Promise<Connector | null> {
-  const properties = environment.get('TOA_EXPOSITION_PROPERTIES')
-
-  assert.ok(properties !== undefined, 'TOA_EXPOSITION_PROPERTIES is undefined')
-
-  configureLogs()
-
-  const options = JSON.parse(properties) as http.Options
-  const broadcast: Broadcast = await host.broadcast(CHANNEL)
-  const server = http.Server.create({ ...options })
-  const remotes = new Remotes(host)
-  const node = root.resolve()
-  const methods = new EndpointsFactory(remotes)
-  const directives = new DirectivesFactory(families, remotes, host, options)
-  const interception = new Interception(interceptors, options)
-  const tree = new Tree(node, methods, directives)
-
-  const composition = new Composition(host)
-  const dispatcher = options.rpc === undefined ? null : new Dispatcher(options.rpc)
-  const mcp = options.mcp === undefined ? null : new Model(options.mcp, tree)
-  const gateway = new Gateway(broadcast, tree, interception, directives, dispatcher, mcp)
-
-  gateway.depends(remotes)
-  gateway.depends(composition)
-  // what the directives meter through; one atom per process, connected once
-  gateway.depends(host.atom(ATOM_GROUP))
-
-  server.attach(gateway.process.bind(gateway))
-  server.depends(gateway)
-
-  return server
-}
-
-const LOGS_PREFIX = 'TOA_TELEMETRY_LOGS'
-const TRACES_ENV = 'TOA_TELEMETRY_TRACES'
-
-function configureLogs(): void {
-  const globEnv = environment.get(LOGS_PREFIX)
-  const level: LevelName = environment.get('TOA_DEV') === '1' ? 'trace' : 'info'
-  const options =
-    globEnv === undefined ? { level } : (JSON.parse(globEnv) as { level?: LevelName })
-
-  console.configure({ level: options.level ?? level })
-
-  const tracesEnv = environment.get(TRACES_ENV)
-  const tracing =
-    tracesEnv === undefined ? development() : (JSON.parse(tracesEnv) as TracesOptions)
-
-  // `openspan` is not Toa's and reads the environment, which no longer holds the context by
-  // the time the exporter is made — so the service is named here
-  if (tracing.exporters?.otlp !== undefined)
-    tracing.exporters.otlp.service ??= environment.get('TOA_CONTEXT')
-
-  traces(tracing)
-}
-
-/**
- * Tracing is off unless it is configured. The console exporter is a local development
- * mechanism, so it is turned on for `toa dev` and for a boot trace the CLI has already
- * asked for (`runtime/boot/src/span.js`), and nowhere else — a deployment that wants
- * traces annotates `telemetry.traces.exporters`.
- *
- * The gateway boots without the telemetry extension, hence the copy of
- * `extensions/telemetry/source/extension.ts`.
- */
-function development(): TracesOptions {
-  const local =
-    environment.get('TOA_DEV') === '1' || environment.get('TOA_BOOT_TRACE') === '1'
-
-  return local ? { exporters: { console: {} } } : {}
-}

package/source/userland.ts

@@ -1,47 +0,0 @@
-/**
- * What Exposition puts into an operation's input, for the operation to be written against.
- *
- * The gateway's own types are its business; these are the application's.
- */
-
-/**
- * The identity behind the call, as `auth:delegate` embeds it:
- *
- * ```yaml
- * /echo:
- *   GET:
- *     auth:assert: true
- *     auth:delegate: identity
- *     endpoint: echo
- * ```
- *
- * ```javascript
- * export async function computation ({ identity }, context) { }
- * ```
- */
-export interface Identity {
-  readonly id: string
-
-  /** What the identity holds. Delegation resolves them, so they are always here. */
-  roles: string[]
-
-  permissions?: Record<string, string[]>
-
-  /** How the identity was authenticated; `null` for a transient one. */
-  scheme: string | null
-
-  /** Whether the credentials presented are due to be exchanged. */
-  refresh: boolean
-
-  /** The token's claims, where the identity was federated. */
-  claims?: Claims
-}
-
-/** A federated token's payload: what it must carry, and whatever else the issuer put there. */
-export interface Claims {
-  iss: string
-  sub: string
-  aud?: string | string[]
-
-  [claim: string]: unknown
-}

package/tsconfig.json

@@ -1,13 +0,0 @@
-{
-  "extends": "../../tsconfig.json",
-  "compilerOptions": {
-    "outDir": "./transpiled",
-    "rootDir": "./source"
-  },
-  "include": [
-    "source"
-  ],
-  "exclude": [
-    "**/*.test.ts"
-  ]
-}