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

package/source/query/options.ts

@@ -0,0 +1,35 @@
+import { QuerySyntaxException } from '../exceptions.js'
+import type { Options } from '../types/storages.js'
+import type { Properties } from './criteria.js'
+
+export function options(given: Record<string, any>, properties: Properties): Options {
+  if (given.sort !== undefined) given.sort = sort(given.sort, properties)
+
+  if (given.projection !== undefined) projection(given.projection, properties)
+
+  return given as Options
+}
+
+function sort(sort: string[], properties: Properties): Array<[string, string]> {
+  const result: Array<[string, string]> = []
+
+  for (const sorting of sort) {
+    const [property, direction] = sorting.split(':')
+
+    if (properties[property] === undefined)
+      throw new QuerySyntaxException(`Sort property '${property}' is not defined`)
+
+    result.push([property, direction ?? 'asc'])
+  }
+
+  return result
+}
+
+function projection(projection: string[], properties: Properties): void {
+  for (const property of projection)
+    if (properties[property] === undefined)
+      throw new QuerySyntaxException(`Projection property '${property}' is not defined`)
+
+  for (const property of ['VERSION', 'CREATED', 'UPDATED', 'DELETED'])
+    if (!projection.includes(property)) projection.push(property)
+}

package/{src/query.js → source/query.ts}

@@ -1,28 +1,25 @@
 import { empty } from '@toa.io/generic'
 import * as criteria from './query/criteria.js'
 import * as options from './query/options.js'
+import type { Properties } from './query/criteria.js'
+import type { Node, Options, Query as Parsed } from './types/storages.js'
+import type { Query as Requested } from './types/request.js'
 
 const parse = { ...criteria, ...options }
 
+/** Translates the query a request carries into the one a storage is given. */
 export class Query {
-  #properties
-  #system
+  readonly #properties: Properties
 
-  /** @type {Map<string, object>} parsed criteria by their expression */
-  #asts = new Map()
+  /** parsed criteria by their expression */
+  readonly #asts = new Map<string, Node>()
 
-  constructor (properties) {
+  public constructor(properties: Properties) {
     this.#properties = properties
-    this.#system = Object.keys(properties).filter((key) => properties[key].system === true)
   }
 
-  /**
-   * @param {toa.core.request.Query} query
-   * @returns {toa.core.storages.Query}
-   */
-  parse (query) {
-    /** @type {toa.core.storages.Query} */
-    const result = {}
+  public parse(query: Requested): Parsed {
+    const result: Parsed = {}
     const { id, ids, version, criteria, search, ...rest } = query
 
     const options = this.#options(rest)
@@ -37,10 +34,10 @@ export class Query {
     return result
   }
 
-  #options (options) {
-    if (empty(options)) return
+  #options(given: Record<string, any>): Options | undefined {
+    if (empty(given)) return undefined
 
-    return parse.options(options, this.#properties, this.#system)
+    return parse.options(given, this.#properties)
   }
 
   /**
@@ -52,7 +49,7 @@ export class Query {
    * Expressions come from the client, hence the bound. An invalid one throws before it
    * reaches the cache.
    */
-  #criteria (criteria) {
+  #criteria(criteria: string): Node {
     const known = this.#asts.get(criteria)
 
     if (known !== undefined) return known

package/source/receiver.ts

@@ -0,0 +1,120 @@
+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

@@ -0,0 +1,20 @@
+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

@@ -0,0 +1,20 @@
+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

@@ -0,0 +1,179 @@
+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

@@ -0,0 +1,79 @@
+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/{src/transmission.js → source/transmission.ts}

@@ -1,18 +1,20 @@
 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 {
-  #bindings
+  readonly #bindings: Consumer[]
 
-  constructor (bindings) {
+  public constructor(bindings: Consumer[]) {
     super()
 
     this.#bindings = bindings
     this.depends(bindings)
   }
 
-  async request (request) {
-    let reply = false
+  public async request(request: Request): Promise<any> {
+    let reply: any = false
     let i = 0
 
     while (reply === false && i < this.#bindings.length) {
@@ -21,13 +23,11 @@ export class Transmission extends Connector {
       i++
 
       if (request?.task === true) {
-        if (binding.task === undefined)
-          continue
+        if (binding.task === undefined) continue
 
         await binding.task(request)
         reply = null
-      } else
-        reply = await binding.request(request)
+      } else reply = await binding.request(request)
     }
 
     if (reply === false)

package/source/types/atomicity.ts

@@ -0,0 +1,63 @@
+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

@@ -0,0 +1,59 @@
+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
+}