@toa.io/core 1.0.0-alpha.284 → 1.0.0-alpha.286

package/src/receiver.js

@@ -1,123 +0,0 @@
-import { console, decode, run } from 'openspan'
-import { add } from '@toa.io/generic'
-import { Connector } from './connector.js'
-
-/**
- * @implements {toa.core.Receiver}
- */
-export class Receiver extends Connector {
-  /** @type {boolean} */
-  #conditioned
-
-  /** @type {boolean} */
-  #adaptive
-
-  /** @type {string} */
-  #endpoint
-
-  /** @type {string} */
-  #label
-
-  /** @type {string} */
-  #destination
-
-  /** @type {unknown[]} */
-  #arguments
-
-  /** @type {toa.core.Source} */
-  #origin
-
-  #local
-
-  #bridge
-
-  /** @type {object} */
-  #delivery
-
-  /** @type {object} */
-  #processing
-
-  constructor (definition, local, 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 */
-  async receive (message) {
-    const { payload, telemetry, ...extensions } = message
-
-    if (this.#conditioned && 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 = () => this.#process(request)
-
-    if (remote === null)
-      await task()
-    else
-      await run(remote, task)
-  }
-
-  async #process (request) {
-    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) {
-    return this.#adaptive ? await this.#bridge.request(payload, ...(this.#arguments ?? [])) : { input: payload }
-  }
-}

package/src/reflection.js

@@ -1,24 +0,0 @@
-import { Connector } from './connector.js'
-
-/**
- * @implements {toa.core.Reflection}
- */
-export class Reflection extends Connector {
-  /** @type {toa.core.reflection.Source} */
-  #source
-
-  value
-
-  /**
-   * @param {toa.core.reflection.Source} source
-   */
-  constructor (source) {
-    super()
-
-    this.#source = source
-  }
-
-  async open () {
-    this.value = await this.#source()
-  }
-}

package/src/remote.js

@@ -1,14 +0,0 @@
-import assert from 'node:assert'
-import { Component } from './component.js'
-
-export class Remote extends Component {
-  kind = 'client'
-
-  explain (endpoint) {
-    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/src/state.js

@@ -1,138 +0,0 @@
-import { StatePreconditionException, StateNotFoundException } from './exceptions.js'
-
-export class State {
-  storage
-
-  #associated
-  #entities
-  #outbox
-
-  constructor (storage, entity, outbox, associated) {
-    this.storage = storage
-    this.#entities = entity
-    this.#outbox = outbox
-    this.#associated = associated === true
-  }
-
-  init (id) {
-    return this.#entities.init(id)
-  }
-
-  fit (values) {
-    return this.#entities.fit(values)
-  }
-
-  async object (query, mutable = true) {
-    const record = await this.storage.get(query)
-
-    if (record === null) {
-      if (this.#associated && query.id !== undefined && query.criteria === undefined && query.version === undefined)
-        return this.init(query.id)
-      else if (query.version !== undefined)
-        throw new StatePreconditionException()
-
-      return null
-    } else
-      return this.#entities.object(record, mutable)
-  }
-
-  async objects (query, mutable = true) {
-    const recordset = await this.storage.find(query)
-    const missing = this.#associated && query.ids !== undefined && recordset.length < query.ids.length
-    const init = missing ? query.ids.filter((id) => !recordset.some((record) => record.id === id)) : undefined
-    
-    return this.#entities.objects(recordset, init, mutable)
-  }
-
-  async stream (query) {
-    return this.storage.stream(query)
-  }
-
-  changeset (query) {
-    return this.#entities.changeset(query)
-  }
-
-  none () {
-    return null
-  }
-
-  async ensure (query, properties, input) {
-    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)
-
-    if (record.id !== blank.id) // exists
-      return this.#entities.object(record, NOT_MUTABLE)
-
-    if (row !== undefined)
-      await this.#outbox.publish(row)
-
-    return object
-  }
-
-  async commit (state, input) {
-    if (state.constructor.name === 'EntitySet') 
-      return this.massCommit(state, input)
-
-    const data = state.get()
-
-    // 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(data, row)
-
-    if (ok === true && row !== undefined)
-      await this.#outbox.publish(row)
-
-    return ok
-  }
-
-  async massCommit (state, input) {
-    const data = state.get()
-    const rows = this.#outbox === undefined
-      ? undefined
-      : state.events(input).map((event) => this.#outbox.row(event))
-
-    const ok = await this.storage.massStore(data, rows)
-
-    if (ok === true && rows !== undefined)
-      await Promise.all(rows.map((row) => this.#outbox.publish(row)))
-
-    return ok
-  }
-
-  async apply (state, input) {
-    const changeset = state.export()
-
-    // an assignment's event is the write's own images, so the storage fills them in;
-    // see `apply` in the outbox design
-    const row = this.#outbox?.row({ input })
-    const result = await this.storage.upsert(state.query, changeset, row)
-
-    if (result === null) {
-      if (state.query.version !== undefined) {
-        throw new StatePreconditionException()
-      } else {
-        throw new StateNotFoundException()
-      }
-    } else if (row !== undefined) {
-      // the storage fills `origin` and `state` from its own write; 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.#outbox.publish(row)
-    }
-
-    return result
-  }
-}
-
-/** an effect never commits what `ensure` hands it, see `Effect` */
-const NOT_MUTABLE = false

package/src/transition.js

@@ -1,61 +0,0 @@
-import { retry } from '@toa.io/generic'
-import { Operation } from './operation.js'
-import { StateConcurrencyException, StateNotFoundException } from './exceptions.js'
-
-export class Transition extends Operation {
-  /** a transition is the only operation that commits */
-  mutable = true
-
-  #concurrency
-
-  constructor (cascade, scope, contract, query, definition) {
-    super(cascade, scope, contract, query, definition)
-
-    this.#concurrency = definition.concurrency
-  }
-
-  async process (store) {
-    return retry((retry) => this.#retry(store, retry), RETRY)
-  }
-
-  async acquire (store) {
-    const { request } = store
-
-    store.scope = request.query ? await this.query(request.query) : this.scope.init()
-
-    if (store.scope === null || (store.scope.deleted === true && request.query?.options?.deleted !== true))
-      throw new StateNotFoundException()
-  
-    store.state = store.scope.get()
-  }
-
-  async commit (store) {
-    const { scope, state, reply, retry } = store
-
-    if (reply.error !== undefined) return
-
-    scope.set(state)
-
-    const result = await this.scope.commit(scope, store.request.input)
-
-    if (result === false) {
-      if (this.#concurrency === 'retry')
-        return retry()
-      else
-        throw new StateConcurrencyException()
-    }
-  }
-
-  async #retry (store, retry) {
-    store.retry = retry
-
-    return super.process(store)
-  }
-}
-
-const RETRY = {
-  base: 10,
-  max: 5000,
-  dispersion: 1,
-  retries: 32
-}

package/src/unmanaged.js

@@ -1,7 +0,0 @@
-import { Operation } from './operation.js'
-
-export class Unmanaged extends Operation {
-  acquire (context) {
-    context.state = this.scope.storage.raw
-  }
-}

package/types/atomicity.d.ts

@@ -1,79 +0,0 @@
-// noinspection ES6UnusedImports
-
-import { Connector } from './connector.js'
-
-declare namespace toa.core {
-
-  namespace atomicity {
-
-    /**
-     * 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.
-     */
-    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.
-       *
-       * What `slots` cannot say. Reading serves a consumer that asks often, where a stale
-       * answer costs it one cycle; a consumer that asks rarely has to be told, or it samples
-       * the one moment a rollout was passing through and stands down for a whole cycle.
-       */
-      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>
-    }
-
-    /** Which of the group this replica is, and how many of them there are. */
-    interface Assignment {
-      i: number
-      n: number
-    }
-
-    interface Factory {
-      /** @param group what the replicas deciding together have in common */
-      atom (group: string, options?: object): Atom
-    }
-
-  }
-
-}
-
-export type Atom = toa.core.atomicity.Atom
-export type Assignment = toa.core.atomicity.Assignment
-export type Factory = toa.core.atomicity.Factory

package/types/bindings.d.ts

@@ -1,42 +0,0 @@
-import * as _core from './index.js'
-
-declare namespace toa.core.bindings {
-
-  type Properties = {
-    async?: boolean
-  }
-
-  interface Consumer extends _core.Connector {
-    request (request: Request): Promise<_core.Reply>
-
-    task (request: Request): Promise<void>
-  }
-
-  interface Emitter extends _core.Connector {
-    emit (message: _core.Message): Promise<void>
-  }
-
-  interface Broadcast<L> extends _core.Connector {
-    transmit<T> (label: L, payload: T): Promise<void>
-
-    receive<T> (label: L, callback: (payload: T) => void | Promise<void>): Promise<void>
-  }
-
-  interface Factory {
-    producer? (locator: _core.Locator, endpoints: Array<string>, producer: _core.Component): _core.Connector
-
-    consumer? (locator: _core.Locator, endpoint: string): Consumer
-
-    emitter? (locator: _core.Locator, label: string): Emitter
-
-    receiver? (locator: _core.Locator, label: string, group: string, receiver: _core.Receiver): _core.Connector
-
-    broadcast? (name: string, group?: string): Broadcast
-  }
-
-}
-
-export type Emitter = toa.core.bindings.Emitter
-export type Factory = toa.core.bindings.Factory
-export type Properties = toa.core.bindings.Properties
-export type Broadcast<L = any> = toa.core.bindings.Broadcast<L>

package/types/bridges.ts

@@ -1,33 +0,0 @@
-import type { Request, Reply } from './request.js'
-import type { Context } from './context.js'
-import type { Connector } from './connector.js'
-
-export interface Algorithm {
-  mount: (context?: Context) => Promise<void>
-
-  execute: ((input: any, scope: object | object[]) => Promise<Reply>) |
-  ((input: any) => Promise<Reply>) |
-  (() => Promise<Reply>)
-}
-
-export interface Event {
-  condition: (object: object) => Promise<boolean>
-
-  payload: (object: object) => Promise<object>
-}
-
-export interface Receiver {
-  condition: (object: object) => Promise<boolean>
-
-  request: (object: object) => Promise<Request>
-}
-
-export interface Factory {
-  algorithm?: (path: string, name: string, context: Context) => Algorithm
-
-  event?: (path: string, label: string) => Event
-
-  receiver?: (path: string, label: string) => Receiver
-
-  rc?: (path: string, context: Context) => Promise<{ preflight?: Connector, settle?: Connector, dispose?: Connector } | undefined>
-}

package/types/call.d.ts

@@ -1,13 +0,0 @@
-import type { Request } from './request.js'
-
-/**
- * How an endpoint is called. What it resolves to is what the operation declares — `toa types`
- * writes that per operation, and these are what a hand-written context says instead.
- */
-export type Call<Output = any, Input = any> = (request: Request<Input>) => Promise<Output>
-
-export type Observation<Output = any, Input = never, Entity = unknown> =
-  (request: Request<Input, Entity>) => Promise<Output extends unknown[] ? Output : Output | null>
-
-export type Transition<Output = any, Input = never, Entity = unknown> =
-  (request: Request<Input, Entity>) => Promise<Output | null>

package/types/component.d.ts

@@ -1,12 +0,0 @@
-import { Connector } from './connector.js'
-import { Locator } from './locator.js'
-import { Request } from './request.js'
-import { Operation } from './operations.js'
-
-export class Component extends Connector {
-  locator: Locator
-
-  constructor (locator: Locator, operations: Record<string, Operation>)
-
-  invoke<T = any> (endpoint: string, request: Request): Promise<T>
-}

package/types/connector.d.ts

@@ -1,18 +0,0 @@
-export class Connector {
-  public id: string
-  public connected: boolean
-
-  public connect (): Promise<void>
-
-  public disconnect (interrupt?: boolean): Promise<void>
-
-  public depends (connector: Connector | Connector[]): Connector
-
-  link (connector: Connector): void
-
-  protected open (): Promise<void> | void
-
-  protected close (): Promise<void> | void
-
-  protected dispose (): Promise<void> | void
-}

package/types/context.d.ts

@@ -1,24 +0,0 @@
-import * as _request from './request.js'
-import { Locator } from './locator.js'
-import * as _reply from './reply'
-import * as _extensions from './extensions.js'
-import * as _connector from './connector.js'
-
-export interface Context extends _connector.Connector{
-  aspects: _extensions.Aspect[]
-
-  locator: Locator
-
-  /**
-   * Calls local endpoint
-   */
-  apply (endpoint: string, request: _request.Request): Promise<_reply.Reply>
-
-  /**
-   * Calls remote endpoint
-   */
-  call (namespace: string, name: string, endpoint: string, request: _request.Request): Promise<_reply.Reply>
-
-  // shortcuts
-  [key: string]: any
-}

package/types/entity.d.ts

@@ -1,46 +0,0 @@
-import * as _event from './event.js'
-import * as _storages from './storages.js'
-
-declare namespace toa.core {
-
-  namespace entity {
-
-    interface Factory {
-      init(id: string): Entity
-
-      object(record: Object, mutable?: boolean): Entity
-
-      objects(recordset: Object[], init?: string[], mutable?: boolean): Entity[]
-
-      changeset(query: _storages.Query): Changeset
-    }
-
-  }
-
-  interface Entity {
-    get(): _storages.Record
-
-    set(value: _storages.Record): void
-
-    event(): _event.Event
-  }
-
-  type Upsert = {
-    changeset: Object
-    insert: Object
-  }
-
-  interface Changeset {
-    query: _storages.Query
-
-    get(): Object
-
-    set(value: Object): void
-
-    export(): Upsert
-  }
-
-}
-
-export type Entity = toa.core.Entity
-export type Changeset = toa.core.Changeset

package/types/event.d.ts

@@ -1,11 +0,0 @@
-import * as _state from './state.js'
-
-declare namespace toa.core {
-
-  interface Event {
-    emit(event: _state.Event): Promise<void>
-  }
-
-}
-
-export type Event = toa.core.Event

package/types/exception.d.ts

@@ -1,4 +0,0 @@
-export interface Exception {
-  code: number
-  message: string
-}