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

package/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# [1.0.0-alpha.292](https://github.com/toa-io/toa/compare/v1.0.0-alpha.291...v1.0.0-alpha.292) (2026-09-07)
+
+**Note:** Version bump only for package @toa.io/core
+
+
+
+
+
+# [1.0.0-alpha.291](https://github.com/toa-io/toa/compare/v1.0.0-alpha.290...v1.0.0-alpha.291) (2026-09-07)
+
+**Note:** Version bump only for package @toa.io/core
+
+
+
+
+
+# [1.0.0-alpha.289](https://github.com/toa-io/toa/compare/v1.0.0-alpha.288...v1.0.0-alpha.289) (2026-09-07)
+
+* A deploy moves only what changed, and a component sees none of the runtime's environment (#1073) ([f38e3db](https://github.com/toa-io/toa/commit/f38e3db533f24db866c57bfa1ef294eff1eaf499)), closes [#1073](https://github.com/toa-io/toa/issues/1073) [#1064](https://github.com/toa-io/toa/issues/1064) [#1066](https://github.com/toa-io/toa/issues/1066) [#1067](https://github.com/toa-io/toa/issues/1067) [#1068](https://github.com/toa-io/toa/issues/1068) [#1069](https://github.com/toa-io/toa/issues/1069) [#1071](https://github.com/toa-io/toa/issues/1071) [#1070](https://github.com/toa-io/toa/issues/1070) [#1072](https://github.com/toa-io/toa/issues/1072)
+
+### BREAKING CHANGES
+
+* a component that read `process.env.TOA_*` reads `context` instead;
+  `echo(input)` no longer substitutes from the environment; a bash operation sees no
+  `TOA_*`; images no longer set `USER node` — see migrations/289.md.
+
+
+# [1.0.0-alpha.288](https://github.com/toa-io/toa/compare/v1.0.0-alpha.287...v1.0.0-alpha.288) (2026-09-06)
+
+**Note:** Version bump only for package @toa.io/core
+
+
+
+
+
+# [1.0.0-alpha.287](https://github.com/toa-io/toa/compare/v1.0.0-alpha.286...v1.0.0-alpha.287) (2026-09-06)
+
+**Note:** Version bump only for package @toa.io/core

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@toa.io/core",
-  "version": "1.0.0-alpha.29",
+  "version": "1.0.0-alpha.292",
+  "type": "module",
   "description": "Toa Core",
   "author": "temich <tema.gurtovoy@gmail.com>",
   "homepage": "https://github.com/toa-io/toa#readme",
@@ -11,23 +12,32 @@
   "bugs": {
     "url": "https://github.com/toa-io/toa/issues"
   },
-  "main": "src/index.js",
-  "types": "types/index.ts",
+  "main": "transpiled/index.js",
+  "types": "transpiled/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./transpiled/index.d.ts",
+      "default": "./transpiled/index.js"
+    },
+    "./types": {
+      "types": "./transpiled/types/index.d.ts",
+      "default": "./transpiled/types/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
+    "transpile": "tsc",
     "test": "echo \"Error: run tests from root\" && exit 1"
   },
   "dependencies": {
-    "@rsql/parser": "1.2.4",
-    "@toa.io/console": "1.0.0-alpha.29",
-    "@toa.io/generic": "1.0.0-alpha.29",
-    "@toa.io/yaml": "1.0.0-alpha.29",
-    "error-value": "0.3.0"
-  },
-  "devDependencies": {
-    "clone-deep": "4.0.1"
+    "@rsql/parser": "1.6.0",
+    "@toa.io/generic": "1.0.0-alpha.292",
+    "@toa.io/schemas": "1.0.0-alpha.292",
+    "openspan": "1.0.0-alpha.286",
+    "uuid": "14.0.2"
   },
-  "gitHead": "186d0e17c12a9016b8076edf925963cbb32b9219"
+  "gitHead": "0f6aa3ad9dbec86bb632a7975ea61d1dde1d8fc5"
 }

package/source/assignment.ts

@@ -0,0 +1,27 @@
+import { Operation } from './operation.js'
+import type { Store } from './operation.js'
+import type { Changeset } from './entities/changeset.js'
+
+export class Assignment extends Operation {
+  protected override async acquire(store: Store): Promise<void> {
+    const changeset = this.scope.changeset(store.request.query as any)
+
+    store.scope = changeset
+    store.state = changeset.get()
+  }
+
+  protected override async commit(store: Store): Promise<void> {
+    const { scope, state, reply, request } = store
+
+    if (reply.error !== undefined) return
+
+    const changeset = scope as Changeset
+
+    changeset.set(state)
+
+    const output = await this.scope.apply(changeset, request.input)
+
+    // assignment returns new state by default
+    if (store.reply.output === undefined) store.reply.output = output
+  }
+}

package/source/call.ts

@@ -0,0 +1,63 @@
+import { Readable } from 'node:stream'
+import { current, encode } from 'openspan'
+import { Connector } from './connector.js'
+import type { Transmission } from './transmission.js'
+import type { Request as Contract } from './contract/request.js'
+import type { Request, Source } from './types/request.js'
+
+export class Call extends Connector {
+  readonly #transmitter: Transmission
+  readonly #contract: Contract
+  readonly #source: Source | undefined
+
+  public constructor(transmitter: Transmission, contract: Contract, source?: Source) {
+    super()
+
+    this.#transmitter = transmitter
+    this.#contract = contract
+    this.#source = source
+
+    this.depends(transmitter)
+  }
+
+  public async invoke(request: Request = {}): Promise<any> {
+    // the caller may have attributed the call itself, as the node bridge does
+    if (this.#source !== undefined) request.source ??= this.#source
+
+    this.#contract.fit(request)
+
+    // an operation that takes no input still has to send an explicit null
+    request.input ??= null
+
+    // avoid validation on the recipient's side
+    request.authentic = true
+
+    const context = current()
+
+    if (context !== undefined) request.telemetry = encode(context)
+
+    const reply = await this.#transmitter.request(request)
+
+    if (reply === null) return null
+    else if (reply instanceof Readable) return reply
+    else {
+      if (reply.exception !== undefined) throw reply.exception
+
+      if (reply.error !== undefined) return new RemoteError(reply.error)
+      else return reply.output
+    }
+  }
+
+  public explain(): any {
+    return this.#contract.discovery
+  }
+}
+
+// the remote error as a value: every property it carries, and nothing else enumerable
+class RemoteError extends Error {
+  public constructor(error: object) {
+    super()
+
+    Object.assign(this, error)
+  }
+}

package/source/cascade.ts

@@ -0,0 +1,32 @@
+import { Connector } from './connector.js'
+import type { Algorithm } from './types/bridges.js'
+
+export class Cascade extends Connector {
+  readonly #last: Algorithm
+
+  public constructor(bridges: Algorithm[], preflight?: Connector) {
+    super()
+
+    // this.#bridges = bridges
+    this.#last = bridges[bridges.length - 1]
+
+    if (preflight === undefined) this.depends(bridges)
+    else this.depends(bridges).depends(preflight)
+  }
+
+  public async run(...args: [any, any?]): Promise<any> {
+    // const reply = {}
+    //
+    // for (const bridge of this.#bridges) {
+    //   const partial = await bridge.execute(...args)
+    //
+    //   if (partial.error) return { error: partial.error }
+    //
+    //   merge(reply, partial)
+    // }
+    //
+    // return reply
+
+    return this.#last.execute(...args)
+  }
+}

package/source/component.ts

@@ -0,0 +1,83 @@
+import assert from 'node:assert'
+import { console, current, decode, run, type SpanOptions } from 'openspan'
+import { Connector } from './connector.js'
+import type { Locator } from './locator.js'
+import type { Request } from './types/request.js'
+
+/** What a component holds one of per endpoint: an operation, or the call that stands for it. */
+export interface Invocable extends Connector {
+  invoke: (request: Request) => Promise<any>
+}
+
+export class Component<O extends Invocable = Invocable> extends Connector {
+  public readonly locator: Locator
+
+  protected readonly operations: Record<string, O>
+
+  protected kind: 'server' | 'client' = 'server'
+
+  /** span options per endpoint */
+  readonly #spans: Record<string, SpanOptions> = {}
+
+  public constructor(locator: Locator, operations: Record<string, O>) {
+    super()
+
+    this.locator = locator
+    this.operations = operations
+
+    Object.values(operations).forEach((operation) => this.depends(operation))
+  }
+
+  public async invoke<T = any>(endpoint: string, request?: Request): Promise<T> {
+    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}'`)
+
+    // if the request carries no telemetry, the trace starts here
+    const remote = request?.telemetry === undefined ? null : decode(request.telemetry)
+    const task = async (): Promise<any> => this.#process(endpoint, request)
+
+    if (remote === null) return task()
+    else return run(remote, task)
+  }
+
+  async #process(endpoint: string, request?: Request): Promise<any> {
+    return console.span(this.#span(endpoint), async () => {
+      const reply = await this.operations[endpoint].invoke(request as Request)
+
+      if (reply?.exception !== undefined) {
+        const span = current()
+
+        if (span !== undefined) span.status = 'error'
+
+        console.error('Failed to execute operation', {
+          endpoint: `${this.locator.id}.${endpoint}`,
+          exception: reply.exception
+        })
+      }
+
+      return reply
+    })
+  }
+
+  /**
+   * The span of an endpoint never changes, so it is built once. Not in the constructor:
+   * `kind` is a field of the subclass, and those are assigned after this one is built.
+   *
+   */
+  #span(endpoint: string): SpanOptions {
+    let options = this.#spans[endpoint]
+
+    if (options === undefined) {
+      options = { name: `${this.locator.id}.${endpoint}`, kind: this.kind }
+
+      // the server span is emitted by the component itself, while the client span
+      // belongs to the calling service and inherits it from the context
+      if (this.kind === 'server') options.service = this.locator.id
+
+      this.#spans[endpoint] = options
+    }
+
+    return options
+  }
+}

package/source/composition.ts

@@ -0,0 +1,27 @@
+import { console } from 'openspan'
+import { Connector } from './connector.js'
+
+export class Composition extends Connector {
+  // eslint-disable-next-line max-params
+  public constructor(
+    expositions: Connector[],
+    producers: Connector[],
+    receivers: Connector[],
+    tenants: Connector[]
+  ) {
+    super()
+
+    if (expositions.length > 0) this.depends(expositions)
+    if (producers.length > 0) this.depends(producers)
+    if (receivers.length > 0) this.depends(receivers)
+    if (tenants.length > 0) this.depends(tenants)
+  }
+
+  protected override async open(): Promise<void> {
+    console.info('Composition complete')
+  }
+
+  protected override async dispose(): Promise<void> {
+    console.info('Composition shutdown complete')
+  }
+}

package/source/connector.ts

@@ -0,0 +1,217 @@
+import { console } from 'openspan'
+import { environment } from '@toa.io/generic'
+import type { Locator } from './locator.js'
+
+/** Abstract connections hierarchy */
+export class Connector {
+  #dependencies: Connector[] = []
+  #links: Connector[] = []
+  #connecting: Promise<void> | undefined
+  #disconnecting: Promise<void> | undefined
+  #discarded: boolean = false
+
+  public readonly id: string
+  public connected: boolean = false
+
+  public constructor() {
+    this.id = this.constructor.name + '#' + Math.random().toString(36).substring(2, 8)
+  }
+
+  /**
+   * Creates a dependency and backlink with another Connector or a set of Connectors
+   *
+   * See .connect() and .disconnect()
+   *
+   */
+  public depends(connector: Connector | Connector[]): Connector {
+    let next: Connector
+
+    if (connector instanceof Array) {
+      if (connector.length === 0) throw new Error('Connectors array must not be empty')
+
+      if (connector.length > 1) {
+        next = new Connector()
+
+        for (const item of connector) {
+          this.#dependencies.push(item)
+          item.depends(next)
+        }
+      } else next = connector[0]
+    } else next = connector
+
+    this.#dependencies.push(next)
+    next.link(this)
+
+    // See .#discard()
+    if (this.#disconnecting !== undefined) next.#discard()
+
+    return next
+  }
+
+  /**
+   * Disconnects, now and again if a connection is still to land.
+   *
+   * A dependency taken on after its dependant was disconnected — a lookup that returns
+   * once the teardown walk has gone by — is one nothing is left to take down, as the
+   * walk that would have reached it is over. One that stays connected holds open
+   * everything it depends on with it: a dependency reads `connected` of every dependant
+   * before it closes, and a dependant that is connected for good is a dependency that
+   * never closes.
+   */
+  #discard(): void {
+    this.#discarded = true
+
+    // one that is up already, or on its way, is taken down here; one that is not is
+    // taken down by the connection when it comes, and until then there is nothing to do
+    if (this.#connecting !== undefined) void this.#drop()
+  }
+
+  /**
+   * Creates a backlink to another Connector
+   *
+   * See .connect() and .disconnect()
+   *
+   */
+  public link(connector: Connector): void {
+    this.#links.push(connector)
+  }
+
+  /**
+   * Connects dependants then self
+   *
+   * In case of exception disconnects with current connection interruption
+   *
+   * Method is idempotent
+   *
+   */
+  public async connect(): Promise<void> {
+    if (this.#connecting) return this.#connecting
+
+    this.#disconnecting = undefined
+
+    const work = async () => {
+      await Promise.all(this.#dependencies.map((connector) => connector.connect()))
+      await this.open()
+    }
+
+    // anonymous grouping nodes are not worth a span
+    const connecting =
+      TRACE_BOOT && this.constructor.name !== 'Connector'
+        ? console.span(
+            {
+              name: `connect ${this.constructor.name}`,
+              // a connector that has a locator is named by it; a grouping node has none
+              attributes: { id: (this as { locator?: Locator }).locator?.id ?? this.id }
+            },
+            work
+          )
+        : work()
+
+    this.#connecting = connecting
+
+    try {
+      await connecting
+
+      /*
+       * A disconnection that did not wait for this connection emptied `#connecting` to
+       * say so. Reporting `connected` now would report it of a connector nothing takes
+       * down again — its `#disconnecting` has settled, so a later call returns at once —
+       * and what it depends on reads that of every dependant before it closes.
+       */
+      if (this.#connecting === connecting) this.connected = true
+    } catch (e) {
+      await this.disconnect(true)
+      throw e
+    }
+
+    // a connection asked for before this one was discarded, landing after. See .#discard()
+    if (this.#discarded) await this.#drop()
+  }
+
+  /** Disconnects a discarded connector, saying so rather than throwing at whoever is not waiting. */
+  async #drop(): Promise<void> {
+    this.#discarded = false
+
+    try {
+      await this.disconnect()
+    } catch (error) {
+      console.error('Discarded connector failed to disconnect', { id: this.id, error })
+    }
+  }
+
+  /**
+   * Disconnects self then dependants
+   *
+   * Does nothing if there are connected linked Connectors
+   *
+   * Method is idempotent
+   *
+   */
+  public async disconnect(interrupt?: boolean): Promise<void> {
+    // a connector that has not finished connecting has nothing to close, and
+    // awaiting a connection that may never settle outlives any grace period
+    const pending = interrupt === true || this.connected === false
+
+    if (!pending) await this.#connecting
+
+    if (this.#disconnecting) return this.#disconnecting
+
+    const linked = this.#links.reduce((acc, parent) => acc || parent.connected, false)
+
+    if (linked && interrupt !== true) return
+
+    this.#disconnecting = (async () => {
+      const start = +new Date()
+
+      const interval = setInterval(() => {
+        const delay = +new Date() - start
+
+        if (delay > DELAY)
+          console.warn(`Connector ${this.id} still disconnecting (${delay})`)
+      }, DELAY)
+
+      if (!pending) await this.close()
+
+      // said once the closing is done rather than when it starts: a dependant that is
+      // still closing is still using what it depends on, and the check above reads this
+      // of every dependant. Saying it early lets the first to start tear down a shared
+      // dependency under the others.
+      this.connected = false
+      this.#connecting = undefined
+
+      clearInterval(interval)
+
+      await Promise.all(this.#dependencies.map((connector) => connector.disconnect()))
+
+      await this.dispose()
+    })()
+
+    await this.#disconnecting
+  }
+
+  public async reconnect(): Promise<void> {
+    await this.disconnect()
+    await this.connect()
+  }
+
+  public debug(node: Record<string, any> = {}): Record<string, any> {
+    node[this.id] = { connected: this.connected }
+
+    if (this.#dependencies.length > 0)
+      for (const connector of this.#dependencies) connector.debug?.(node[this.id])
+
+    return node
+  }
+
+  /** Called on connection */
+  protected open(): Promise<void> | void {}
+
+  /** Called on disconnection */
+  protected close(): Promise<void> | void {}
+
+  /** Called after self and dependants disconnection is complete */
+  protected dispose(): Promise<void> | void {}
+}
+
+const DELAY = 5000
+const TRACE_BOOT = environment.get('TOA_BOOT_TRACE') === '1'

package/source/context.ts

@@ -0,0 +1,68 @@
+import { Connector } from './connector.js'
+import { environment } from '@toa.io/generic'
+import type { Locator } from './locator.js'
+import type { Component } from './component.js'
+import type { Remote } from './remote.js'
+import type { Aspect } from './types/extensions.js'
+import type { Request } from './types/request.js'
+
+type Discover = (namespace: string, name: string) => Promise<Remote>
+
+export class Context extends Connector {
+  public readonly env: string | undefined
+  public readonly name: string | undefined
+  public readonly aspects: Aspect[]
+  public readonly locator: Locator
+
+  readonly #local: Component
+  readonly #discover: Discover
+  readonly #remotes: Record<string, Promise<Remote>> = {}
+
+  public constructor(local: Component, discover: Discover, aspects: Aspect[] = []) {
+    super()
+
+    this.env = environment.get('TOA_ENV')
+    this.name = environment.get('TOA_CONTEXT')
+    this.aspects = aspects
+    this.locator = local?.locator
+
+    this.#local = local
+    this.#discover = discover
+
+    this.depends(local)
+
+    if (aspects.length > 0) this.depends(aspects)
+  }
+
+  public async apply(endpoint: string, request: Request): Promise<any> {
+    return this.#local.invoke(endpoint, request)
+  }
+
+  // eslint-disable-next-line max-params
+  public async call(
+    namespace: string,
+    name: string,
+    endpoint: string,
+    request: Request
+  ): Promise<any> {
+    const remote = await this.#remote(namespace, name)
+
+    return remote.invoke(endpoint, request)
+  }
+
+  async #remote(namespace: string, name: string): Promise<Remote> {
+    const key = namespace + '.' + name
+
+    this.#remotes[key] ??= this.#connect(namespace, name)
+
+    return this.#remotes[key]
+  }
+
+  async #connect(namespace: string, name: string): Promise<Remote> {
+    const remote = await this.#discover(namespace, name)
+
+    this.depends(remote)
+
+    return remote
+  }
+}

package/source/contract/contract.ts

@@ -0,0 +1,23 @@
+import { SystemException } from '../exceptions.js'
+import type { Schema, SchemaError } from '@toa.io/schemas'
+import type { Exception } from '../exceptions.js'
+
+/** What a contract throws with, stated by the subclass. */
+export type Refusal = new (error: SchemaError, cause?: unknown) => Exception
+
+export class Contract {
+  public readonly schema: Schema
+
+  public static Exception: Refusal = SystemException as unknown as Refusal
+
+  public constructor(schema: Schema) {
+    this.schema = schema
+  }
+
+  public fit(value: unknown): void {
+    const error = this.schema.fit(value)
+
+    if (error !== null)
+      throw new (this.constructor as typeof Contract).Exception(error, value)
+  }
+}

package/source/contract/index.ts

@@ -0,0 +1,2 @@
+export { Request } from './request.js'
+export { Reply } from './reply.js'