@toa.io/core 1.0.0-alpha.292 → 1.0.0-alpha.299

package/source/receiver.ts

@@ -1,120 +0,0 @@
-import { console, decode, run, type SpanOptions } from 'openspan'
-import { add } from '@toa.io/generic'
-import { Connector } from './connector.js'
-import type { Component } from './component.js'
-import type { Receiver as Bridge } from './types/bridges.js'
-import type { Message } from './types/message.js'
-import type { Request, Source } from './types/request.js'
-
-export interface Definition {
-  conditioned?: boolean
-  adaptive?: boolean
-  operation: string
-  label?: string
-  destination?: string
-  arguments?: unknown[]
-  origin?: Source
-}
-
-export class Receiver extends Connector {
-  readonly #conditioned: boolean | undefined
-  readonly #adaptive: boolean | undefined
-  readonly #endpoint: string
-  readonly #label: string
-  readonly #destination: string
-  readonly #arguments: unknown[] | undefined
-  readonly #origin: Source | undefined
-  readonly #local: Component
-  readonly #bridge: Bridge | undefined
-  readonly #delivery: SpanOptions
-  readonly #processing: SpanOptions
-
-  public constructor(definition: Definition, local: Component, bridge?: Bridge) {
-    super()
-
-    const { conditioned, adaptive, operation } = definition
-
-    this.#conditioned = conditioned
-    this.#adaptive = adaptive
-    this.#endpoint = operation
-    this.#label = definition.label ?? operation
-    this.#destination = definition.destination ?? this.#label
-    this.#arguments = definition.arguments
-    this.#origin = definition.origin
-
-    this.#local = local
-    this.#bridge = bridge
-
-    this.depends(local)
-    if (bridge !== undefined) this.depends(bridge)
-
-    /*
-     * The delivery span is created on behalf of the messaging destination, so that
-     * each consumer forms its own complete producer/consumer pair, and service graphs
-     * display fan-out correctly: producer -> destination -> each consumer
-     * (Tempo pairs spans one-to-one, thus multiple consumers can not pair
-     * with a single producer span, see grafana/tempo#5408)
-     */
-    this.#delivery = {
-      name: `${this.#label} deliver`,
-      kind: 'producer',
-      service: this.#destination,
-      attributes: { 'messaging.destination.name': this.#destination }
-    }
-
-    this.#processing = {
-      name: `${this.#label} process`,
-      kind: 'consumer',
-      service: local.locator.id,
-      attributes: { 'messaging.destination.name': this.#destination }
-    }
-  }
-
-  /** @hot */
-  public async receive(message: Message): Promise<void> {
-    const { payload, telemetry, ...extensions } = message
-
-    if (this.#conditioned === true && (await this.#bridge?.condition(payload)) === false)
-      return
-
-    const request = await this.#request(payload)
-
-    add(request, extensions)
-
-    // set after `add`, so that a message field can not spoof the origin
-    if (this.#origin !== undefined) request.source = this.#origin
-
-    // continue the trace from the producer span
-    const remote = telemetry === undefined ? null : decode(telemetry)
-    const task = async (): Promise<void> => {
-      await this.#process(request)
-    }
-
-    if (remote === null) await task()
-    else await run(remote, task)
-  }
-
-  async #process(request: Request): Promise<void> {
-    return console.span(this.#delivery, async () =>
-      console.span(this.#processing, async () => {
-        try {
-          await this.#local.invoke(this.#endpoint, request)
-        } catch (error) {
-          console.error('Receiver error', {
-            component: this.#local.locator.id,
-            endpoint: this.#endpoint,
-            error
-          })
-
-          throw error
-        }
-      })
-    )
-  }
-
-  async #request(payload: object): Promise<Request> {
-    return this.#adaptive === true
-      ? await this.#bridge!.request(payload, ...(this.#arguments ?? []))
-      : { input: payload }
-  }
-}

package/source/reflection.ts

@@ -1,20 +0,0 @@
-import { Connector } from './connector.js'
-
-/** What a reflection reads, once, as it connects. */
-export type Source<T = any> = () => Promise<T>
-
-export class Reflection<T = any> extends Connector {
-  public value: T | undefined
-
-  readonly #source: Source<T>
-
-  public constructor(source: Source<T>) {
-    super()
-
-    this.#source = source
-  }
-
-  protected override async open(): Promise<void> {
-    this.value = await this.#source()
-  }
-}

package/source/remote.ts

@@ -1,20 +0,0 @@
-import assert from 'node:assert'
-import { Component } from './component.js'
-import type { Invocable } from './component.js'
-
-/** A call knows what its endpoint declares, which is what an explanation is read from. */
-export interface Explicable extends Invocable {
-  explain(): any
-}
-
-export class Remote extends Component<Explicable> {
-  protected override kind = 'client' as const
-
-  public explain(endpoint: string): any {
-    if (!(endpoint in this.operations))
-      // `assert.fail`, not `assert.ok`: the message is built only when it is needed
-      assert.fail(`Endpoint '${endpoint}' is not provided by '${this.locator.id}'`)
-
-    return this.operations[endpoint].explain()
-  }
-}

package/source/state.ts

@@ -1,179 +0,0 @@
-import { EntitySet } from './entities/set.js'
-import { StatePreconditionException, StateNotFoundException } from './exceptions.js'
-import type { Readable } from 'node:stream'
-import type { Factory } from './entities/factory.js'
-import type { Entity } from './entities/entity.js'
-import type { Changeset } from './entities/changeset.js'
-import type { Outbox } from './outbox/outbox.js'
-import type { Row } from './types/outbox.js'
-import type { Query, Record, Storage } from './types/storages.js'
-
-/**
- * What an operation acquires and commits. One method per scope a manifest may declare, which
- * is how an operation reaches the one it was declared with.
- */
-export class State {
-  public readonly storage: Storage
-
-  readonly #entities: Factory
-  readonly #outbox: Outbox | undefined
-
-  /** whether an entity exists by virtue of the identity it is looked up by */
-  readonly #associated: boolean
-
-  // eslint-disable-next-line max-params
-  public constructor(
-    storage: Storage,
-    entities: Factory,
-    outbox: Outbox | undefined,
-    associated?: boolean
-  ) {
-    this.storage = storage
-
-    this.#entities = entities
-    this.#outbox = outbox
-    this.#associated = associated === true
-  }
-
-  public init(id?: string): Entity {
-    return this.#entities.init(id)
-  }
-
-  public fit(values: object): void {
-    this.#entities.fit(values)
-  }
-
-  /** scope `object` */
-  public async object(query: Query, mutable = true): Promise<Entity | null> {
-    const record = await this.storage.get(query)
-
-    if (record !== null) return this.#entities.object(record, mutable)
-
-    // an associated entity is whatever the identity it is looked up by names, so a miss on
-    // that identity alone is a blank rather than an absence
-    if (
-      this.#associated &&
-      query.id !== undefined &&
-      query.criteria === undefined &&
-      query.version === undefined
-    )
-      return this.init(query.id)
-
-    if (query.version !== undefined) throw new StatePreconditionException()
-
-    return null
-  }
-
-  /** scope `objects` */
-  public async objects(query: Query, mutable = true): Promise<EntitySet> {
-    const recordset = await this.storage.find(query)
-    const ids = query.ids
-
-    const missing = this.#associated && ids !== undefined && recordset.length < ids.length
-
-    const init = missing
-      ? ids.filter((id) => !recordset.some((record) => record.id === id))
-      : undefined
-
-    return this.#entities.objects(recordset, init, mutable)
-  }
-
-  /** scope `stream` */
-  public async stream(query: Query): Promise<Readable> {
-    return this.storage.stream(query)
-  }
-
-  /** scope `changeset` */
-  public changeset(query: Query): Changeset {
-    return this.#entities.changeset(query)
-  }
-
-  /** scope `none`: an operation that acquires nothing still asks for its scope */
-  public none(): null {
-    return null
-  }
-
-  /** get-or-create, in one indivisible step */
-  public async ensure(
-    query: Query | undefined,
-    properties: object,
-    input?: object
-  ): Promise<Entity> {
-    const object = this.#entities.init()
-    const blank = object.get()
-
-    Object.assign(blank, properties)
-    object.set(blank)
-
-    const row = this.#outbox?.row(object.event(input))
-    const record = await this.storage.ensure(query, properties, object.get(), row)
-
-    // whatever came back under another id was already there, and an effect never commits it
-    if (record.id !== blank.id) return this.#entities.object(record, NOT_MUTABLE)
-
-    await this.#publish(row)
-
-    return object
-  }
-
-  public async commit(state: Entity | EntitySet, input?: object): Promise<boolean> {
-    if (state instanceof EntitySet) return this.massCommit(state, input)
-
-    // the row is built before the write so that the storage can commit it in the same
-    // transaction, closing the window this used to have
-    const row = this.#outbox?.row(state.event(input))
-    const ok = await this.storage.store(state.get(), row)
-
-    if (ok) await this.#publish(row)
-
-    return ok
-  }
-
-  public async massCommit(state: EntitySet, input?: object): Promise<boolean> {
-    const outbox = this.#outbox
-
-    const rows =
-      outbox === undefined
-        ? undefined
-        : state.events(input).map((event) => outbox.row(event))
-
-    const ok = await this.storage.massStore(state.get(), rows)
-
-    if (ok && rows !== undefined)
-      await Promise.all(rows.map(async (row) => this.#publish(row)))
-
-    return ok
-  }
-
-  public async apply(state: Changeset, input?: object): Promise<Record> {
-    // an assignment's images are the write's own, so the storage fills them in
-    const row = this.#outbox?.row({ input })
-    const result = await this.storage.upsert(state.query, state.export(), row)
-
-    if (result === null)
-      throw state.query.version === undefined
-        ? new StateNotFoundException()
-        : new StatePreconditionException()
-
-    if (row !== undefined) {
-      // a storage that does not know how leaves the event with what it was given
-      row.event.state ??= result
-      row.event.origin ??= null
-
-      await this.#publish(row)
-    }
-
-    return result
-  }
-
-  /**
-   * Without a durable outbox this is the emission itself, and the operation waits for it;
-   * with one the row is already committed and this returns at once.
-   */
-  async #publish(row: Row | undefined): Promise<void> {
-    if (row !== undefined) await this.#outbox?.publish(row)
-  }
-}
-
-/** an effect never commits what `ensure` hands it, see `Effect` */
-const NOT_MUTABLE = false

package/source/transition.ts

@@ -1,79 +0,0 @@
-import { retry } from '@toa.io/generic'
-import { Operation } from './operation.js'
-import { StateConcurrencyException, StateNotFoundException } from './exceptions.js'
-import type { Contracts, Definition, Store } from './operation.js'
-import type { Cascade } from './cascade.js'
-import type { State } from './state.js'
-import type { Query as Translator } from './query.js'
-import type { Entity } from './entities/entity.js'
-
-export class Transition extends Operation {
-  /** a transition is the only operation that commits */
-  protected override mutable = true
-
-  readonly #concurrency: string | undefined
-
-  // eslint-disable-next-line max-params
-  public constructor(
-    cascade: Cascade,
-    scope: State,
-    contract: Contracts,
-    query: Translator,
-    definition: Definition
-  ) {
-    super(cascade, scope, contract, query, definition)
-
-    this.#concurrency = definition.concurrency
-  }
-
-  protected override async process(store: Store): Promise<any> {
-    return retry(async (retry) => this.#retry(store, retry), RETRY)
-  }
-
-  protected override async acquire(store: Store): Promise<void> {
-    const { request } = store
-
-    store.scope =
-      request.query === undefined ? this.scope.init() : await this.query(request.query)
-
-    const entity = store.scope as Entity | null
-
-    if (
-      entity === null ||
-      (entity.deleted && (request.query as any)?.options?.deleted !== true)
-    )
-      throw new StateNotFoundException()
-
-    store.state = entity.get()
-  }
-
-  protected override async commit(store: Store): Promise<void> {
-    const { scope, state, reply, retry } = store
-
-    if (reply.error !== undefined) return
-
-    const entity = scope as Entity
-
-    entity.set(state)
-
-    const result = await this.scope.commit(entity, store.request.input)
-
-    if (result !== false) return
-
-    if (this.#concurrency === 'retry') await retry?.()
-    else throw new StateConcurrencyException()
-  }
-
-  async #retry(store: Store, retry: () => Promise<any>): Promise<any> {
-    store.retry = retry
-
-    return super.process(store)
-  }
-}
-
-const RETRY = {
-  base: 10,
-  max: 5000,
-  dispersion: 1,
-  retries: 32
-}

package/source/transmission.ts

@@ -1,38 +0,0 @@
-import { Connector } from './connector.js'
-import { TransmissionException } from './exceptions.js'
-import type { Consumer } from './types/bindings.js'
-import type { Request } from './types/request.js'
-
-export class Transmission extends Connector {
-  readonly #bindings: Consumer[]
-
-  public constructor(bindings: Consumer[]) {
-    super()
-
-    this.#bindings = bindings
-    this.depends(bindings)
-  }
-
-  public async request(request: Request): Promise<any> {
-    let reply: any = false
-    let i = 0
-
-    while (reply === false && i < this.#bindings.length) {
-      const binding = this.#bindings[i]
-
-      i++
-
-      if (request?.task === true) {
-        if (binding.task === undefined) continue
-
-        await binding.task(request)
-        reply = null
-      } else reply = await binding.request(request)
-    }
-
-    if (reply === false)
-      throw new TransmissionException(`All (${this.#bindings.length}) bindings rejected.`)
-
-    return reply
-  }
-}

package/source/types/atomicity.ts

@@ -1,63 +0,0 @@
-import type { Connector } from '../connector.js'
-
-/** Which of the group this replica is, and how many of them there are. */
-export interface Assignment {
-  i: number
-  n: number
-}
-
-/**
- * What one group of replicas decides together, in one place. The decisions here are the ones
- * processes cannot arrange by talking to each other: they need a single arbiter and a step
- * indivisible from its point of view.
- */
-export interface Atom extends Connector {
-  /**
-   * An exclusive claim on slots of `0..total`: while this replica holds one, no other
-   * replica of the group does. Answered from memory, so it costs nothing to ask.
-   *
-   * `null` while this replica owns nothing — after a restart, during a rollout, or while
-   * coordination is unreachable. Whoever asks must be able to stand down: acting on a claim
-   * that cannot be supported is a different guarantee, not a degraded one.
-   */
-  slots(total: number): number[] | null
-
-  /**
-   * Calls `listener` with the assignment this replica holds, and again whenever it changes —
-   * one arrived, was lost, or the group resized. Answers with what removes the listener
-   * again.
-   *
-   * A change and not a heartbeat: a group that stays as it is never calls back. It is called
-   * once as it is added, with the claim as it stands.
-   */
-  onassigned(listener: (assignment: Assignment | null) => void): () => void
-
-  /**
-   * Debt the group has run up under each key, in milliseconds. Every call adds its own deltas
-   * and reads back where the group stands, so a replica reports what it alone has spent and
-   * still decides on what all of them have.
-   *
-   * Rejects where there is nothing to arbitrate through.
-   */
-  meter(keys: string[], deltas: number[]): Promise<number[]>
-
-  /**
-   * Runs `routine` holding `keys`, and while it holds them no other replica of the group
-   * does. Waits for as long as it takes to acquire them.
-   *
-   * The lease is extended for as long as the routine runs. An extension that fails aborts the
-   * signal the routine is given, which is the only way it learns it no longer holds what it
-   * is working under.
-   *
-   * Rejects where there is nothing to arbitrate through.
-   */
-  lock<T>(
-    keys: string | string[],
-    routine: (signal: AbortSignal, context: unknown) => Promise<T>
-  ): Promise<T>
-}
-
-export interface Factory {
-  /** @param group what the replicas deciding together have in common */
-  atom(group: string, options?: { interval?: number }): Atom
-}

package/source/types/bindings.ts

@@ -1,59 +0,0 @@
-import type { Readable } from 'node:stream'
-import type { Connector } from '../connector.js'
-import type { Locator } from '../locator.js'
-import type { Component } from '../component.js'
-import type { Receiver } from './receiver.js'
-import type { Message } from './message.js'
-import type { Reply, Request } from './request.js'
-
-/** What a binding module exports beside its factory. */
-export interface Properties {
-  /** delivers asynchronously; an event's binding must */
-  async?: boolean
-  /** in-process: its producers are connected first and torn down last */
-  local?: boolean
-}
-
-export interface Consumer extends Connector {
-  /**
-   * `false` says this binding does not carry the endpoint, and the transmission tries the
-   * next one. A `Readable` is a streamed reply.
-   */
-  request(request: Request): Promise<Reply | Readable | false>
-
-  /**
-   * Absent where the binding cannot enqueue — a transmission skips a binding that offers
-   * no `task` rather than failing over it.
-   */
-  task?(request: Request): Promise<void>
-}
-
-export interface Emitter extends Connector {
-  emit(message: Message): Promise<void>
-}
-
-export interface Broadcast<L extends string = string> extends Connector {
-  transmit<T>(label: L, payload: T): Promise<void>
-
-  receive<T>(label: L, callback: (payload: T) => void | Promise<void>): Promise<void>
-}
-
-export interface Factory {
-  producer(locator: Locator, endpoints: string[], component: Component): Connector
-
-  consumer(locator: Locator, endpoint: string): Consumer
-
-  /** only the binding an event declares is asked for one */
-  emitter?(locator: Locator, label: string): Emitter
-
-  /** `group` is absent for an exclusive subscription */
-  // eslint-disable-next-line max-params
-  receiver?(
-    locator: Locator,
-    label: string,
-    group: string | undefined,
-    receiver: Receiver
-  ): Connector
-
-  broadcast?(name: string, group?: string): Broadcast
-}

package/source/types/bridges.ts

@@ -1,54 +0,0 @@
-import type { Readable } from 'node:stream'
-import type { Connector } from '../connector.js'
-import type { Context } from '../context.js'
-import type { Event as StateEvent } from './state.js'
-import type { Reply, Request } from './request.js'
-
-/**
- * What runs one endpoint. `mount` and `unmount` are the component author's, called by the
- * bridge as it opens and closes; core only ever asks for `execute`.
- */
-export interface Algorithm extends Connector {
-  execute(input: any, scope?: object | object[]): Promise<Reply | Readable>
-}
-
-export interface Event extends Connector {
-  condition(event: StateEvent): Promise<boolean>
-
-  payload(event: StateEvent): Promise<object>
-}
-
-export interface Receiver extends Connector {
-  condition(payload: object): Promise<boolean>
-
-  /** the trailing arguments are what the receiver declaration named */
-  request(payload: object, ...args: unknown[]): Promise<Request>
-}
-
-/** Runs on every change to an entity's state, before the contract is applied. */
-export interface Guard {
-  fit(state: object, origin: object | null): boolean
-}
-
-/** Connectors whose lifecycle moments are the component's. */
-export interface RunCommands {
-  preflight?: Connector
-  settle?: Connector
-  dispose?: Connector
-}
-
-export interface Factory {
-  algorithm(
-    path: string,
-    endpoint: string,
-    context: Context
-  ): Algorithm | Promise<Algorithm>
-
-  event?(path: string, label: string, context: Context): Event | Promise<Event>
-
-  receiver?(path: string, label: string): Receiver | Promise<Receiver>
-
-  guard?(path: string, name: string, context: Context): Guard | Promise<Guard>
-
-  rc?(path: string, context: Context): Promise<RunCommands | undefined>
-}