@toa.io/boot 1.0.0-alpha.31 → 1.0.0-alpha.310

package/src/workload.test.js

@@ -0,0 +1,321 @@
+import { describe, it, before, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+import { Connector } from '@toa.io/core'
+import { environment, timeout } from '@toa.io/generic'
+
+/*
+ * The probe binds a port and the halt listener reaches a broker, and this suite is about
+ * neither: what it exercises is the workload's own lifecycle, so the extensions that would
+ * contribute a resident are off. `TOA_INTROSPECTION` is unset, so introspection's is `null`.
+ */
+environment.set('TOA_TELEMETRY_READY', 'false')
+
+let Workload
+
+before(async () => {
+  ;({ Workload } = await import('./workload.js'))
+})
+
+let sequence
+
+beforeEach(() => {
+  sequence = []
+})
+
+class TestConnector extends Connector {
+  #label
+
+  constructor(label) {
+    super()
+    this.#label = label
+  }
+
+  async open() {
+    sequence.push(`+${this.#label}`)
+  }
+
+  async close() {
+    sequence.push(`-${this.#label}`)
+  }
+
+  async dispose() {
+    sequence.push(`*${this.#label}`)
+  }
+}
+
+/** One that has something to stop doing, which most connectors have not. */
+class QuietConnector extends Connector {
+  #label
+
+  constructor(label) {
+    super()
+    this.#label = label
+  }
+
+  async pause() {
+    sequence.push(`~${this.#label}`)
+  }
+
+  async unpause() {
+    sequence.push(`^${this.#label}`)
+  }
+}
+
+/** Waits for a condition the halt reaches on its own timers. */
+async function until(condition, limit = 2000) {
+  const deadline = Date.now() + limit
+
+  while (Date.now() < deadline) {
+    if (condition()) return
+
+    await timeout(5)
+  }
+
+  assert.fail('condition was not reached')
+}
+
+describe('Workload', () => {
+  it('should connect what the command built', async () => {
+    const workload = new Workload(async () => new TestConnector('a'))
+
+    await workload.connect()
+
+    assert.deepStrictEqual(sequence, ['+a'])
+
+    await workload.disconnect()
+  })
+
+  it('should take down what a gate holds, and leave the rest connected', async () => {
+    let built = 0
+
+    const workload = new Workload(async (workload) => {
+      const gate = workload.gate(async () => {
+        built++
+
+        return new TestConnector('gated')
+      })
+      const root = new Connector()
+
+      root.depends([gate, new TestConnector('above')])
+
+      return root
+    })
+
+    await workload.connect()
+
+    assert.deepStrictEqual(sequence.sort(), ['+above', '+gated'])
+
+    sequence = []
+
+    // a hundredth of a second, so the window is over before the assertions are
+    workload.stop(0.01)
+
+    // `-gated` and not `-above`: what a gate holds is closed, and nothing else is
+    await until(() => sequence.includes('*gated'))
+
+    assert.deepStrictEqual(sequence, ['-gated', '*gated'])
+
+    await until(() => built === 2)
+
+    assert.deepStrictEqual(sequence, ['-gated', '*gated', '+gated'])
+
+    await workload.disconnect()
+  })
+
+  it('should build again rather than reconnect', async () => {
+    const held = []
+
+    const workload = new Workload(async (workload) =>
+      workload.gate(async () => {
+        const connector = new TestConnector('a')
+
+        held.push(connector)
+
+        return connector
+      })
+    )
+
+    await workload.connect()
+
+    workload.stop(0.01)
+
+    await until(() => held.length === 2)
+
+    assert.notEqual(held[0], held[1])
+
+    await workload.disconnect()
+  })
+
+  it('should return before anything is closed', async () => {
+    const workload = new Workload(async (workload) =>
+      workload.gate(async () => new TestConnector('a'))
+    )
+
+    await workload.connect()
+
+    sequence = []
+    workload.stop(0.01)
+
+    // the caller is a consumer callback: the teardown must not have begun under it
+    assert.deepStrictEqual(sequence, [])
+
+    await until(() => sequence.includes('+a'))
+    await workload.disconnect()
+  })
+
+  it('should make one cycle of two overlapping halts', async () => {
+    let built = 0
+
+    const workload = new Workload(async (workload) =>
+      workload.gate(async () => {
+        built++
+
+        return new TestConnector('a')
+      })
+    )
+
+    await workload.connect()
+
+    workload.stop(0.01)
+    workload.stop(0.01)
+
+    await until(() => built === 2)
+    await timeout(50)
+
+    assert.equal(built, 2)
+
+    await workload.disconnect()
+  })
+
+  it('should not halt what is not connected', async () => {
+    const workload = new Workload(async () => new TestConnector('a'))
+
+    workload.stop(0.01)
+
+    await timeout(30)
+
+    assert.deepStrictEqual(sequence, [])
+  })
+
+  it('should quiesce what it holds, closing nothing', async () => {
+    const workload = new Workload(async (workload) =>
+      workload.gate(async () => new QuietConnector('a'))
+    )
+
+    await workload.connect()
+
+    sequence = []
+
+    await workload.quiesce()
+
+    assert.deepStrictEqual(sequence, ['~a'])
+    assert.equal(workload.quiescent(), true)
+
+    // nothing was taken down, so the process is still working as far as anyone watching it
+    assert.equal(workload.running(), true)
+
+    await workload.disconnect()
+  })
+
+  it('should undo a quiesce without building anything', async () => {
+    let built = 0
+
+    const workload = new Workload(async (workload) =>
+      workload.gate(async () => {
+        built++
+
+        return new QuietConnector('a')
+      })
+    )
+
+    await workload.connect()
+    await workload.quiesce()
+
+    sequence = []
+
+    await workload.cancel()
+
+    assert.deepStrictEqual(sequence, ['^a'])
+    assert.equal(workload.quiescent(), false)
+    assert.equal(built, 1)
+
+    await workload.disconnect()
+  })
+
+  it('should take down a process that is already quiet', async () => {
+    const workload = new Workload(async (workload) =>
+      workload.gate(async () => {
+        const root = new Connector()
+
+        root.depends([new QuietConnector('q'), new TestConnector('a')])
+
+        return root
+      })
+    )
+
+    await workload.connect()
+    await workload.quiesce()
+
+    sequence = []
+    workload.stop(0.01)
+
+    await until(() => sequence.includes('+a'))
+
+    // quieted once, on the quiesce, and not again on the way down
+    assert.deepStrictEqual(sequence, ['-a', '*a', '+a'])
+
+    await workload.disconnect()
+  })
+
+  it('should not let a cancel undo a stop', async () => {
+    const workload = new Workload(async (workload) =>
+      workload.gate(async () => new TestConnector('a'))
+    )
+
+    await workload.connect()
+
+    sequence = []
+    workload.stop(0.01)
+
+    await workload.cancel()
+
+    // it goes down and comes back: a cancel is for a quiesce, and this is past one
+    await until(() => sequence.includes('+a'))
+
+    assert.deepStrictEqual(sequence, ['-a', '*a', '+a'])
+
+    await workload.disconnect()
+  })
+
+  it('should keep the process alive while it is halted', async () => {
+    const workload = new Workload(async (workload) =>
+      workload.gate(async () => new TestConnector('a'))
+    )
+
+    await workload.connect()
+
+    // long enough that the process would have to be held open for it
+    workload.stop(10)
+
+    await until(() => sequence.includes('*a'))
+
+    // a halted process holds nothing else: unreferenced, this timer would let it exit
+    assert.ok(
+      process.getActiveResourcesInfo().includes('Timeout'),
+      'nothing keeps the process alive until the rebuild'
+    )
+
+    await workload.disconnect()
+  })
+
+  it('should take the gates down on its own disconnection', async () => {
+    const workload = new Workload(async (workload) =>
+      workload.gate(async () => new TestConnector('a'))
+    )
+
+    await workload.connect()
+    await workload.disconnect()
+
+    assert.deepStrictEqual(sequence, ['+a', '-a', '*a'])
+  })
+})

package/types/bindings.d.ts

@@ -1,3 +1,7 @@
-import type { bindings } from '@toa.io/core'
+import type { bindings } from '@toa.io/core/types'
 
-export function broadcast<T> (name: string, group?: string, binding?: string): bindings.Broadcast<T>
+export function broadcast<T>(
+  name: string,
+  group?: string,
+  binding?: string
+): bindings.Broadcast<T>

package/types/index.d.ts

@@ -1,21 +1,73 @@
-import * as core from '@toa.io/core'
-import * as composition from './composition'
+import type * as core from '@toa.io/core'
+import type * as types from '@toa.io/core/types'
+import type * as norm from '@toa.io/norm/types'
+import * as composition from './composition.d.ts'
 
-export * as bindings from './bindings'
+export * as bindings from './bindings.d.ts'
 
-export async function composition (paths: string[], options?: composition.Options): Promise<core.Connector>
+export async function manifest(
+  path: string,
+  options?: composition.Options
+): Promise<norm.Manifest>
 
-export async function remote (locator: core.Locator): Promise<core.Component>
+/** What this process was given about the components it calls. */
+export namespace map {
+  /** the file to read it from, or the map itself */
+  function use(value: string | Record<string, core.Contract> | undefined): void
 
-export async function receive<T = any> (
+  /** what this process composes, stated by the boot that composes it */
+  function compose(manifests: norm.Manifest[]): Promise<void>
+
+  /** forgets what this process composed */
+  function forget(): void
+
+  function contract(id: string): Promise<core.Contract | undefined>
+}
+
+export async function composition(
+  paths: string[],
+  options?: composition.Options
+): Promise<core.Connector>
+
+export async function remote(
+  locator: core.Locator,
+  source?: types.Source
+): Promise<core.Remote>
+
+export async function receive<T = any>(
   label: string,
-  receiver: Receiver,
+  receiver: Receiver
 ): Promise<core.Connector>
 
-export async function receive<T = any> (
+export async function receive<T = any>(
   label: string,
   group: string | undefined,
-  receiver: Receiver,
+  receiver: Receiver
 ): Promise<core.Connector>
 
-type Receiver = { receive: (message: core.Message<T>) => void | Promise<void> }
+type Receiver = { receive: (message: types.Message<T>) => void | Promise<void> }
+
+export function host(): types.extensions.Host
+
+/** A process, as a connector: what the command built, and what the extensions keep in one. */
+export class Workload extends core.Connector {
+  constructor(build: (workload: Workload) => Promise<core.Connector>)
+
+  /** A part of this process a halt takes down and builds again. */
+  gate(build: () => Promise<core.Connector>): core.Gate
+
+  /** Whether what a halt takes down is up. */
+  running(): boolean
+
+  /** Whether this process is quiet: it does nothing of its own accord and holds everything. */
+  quiescent(): boolean
+
+  /** Stops what this process does of its own accord, holding open everything it has. */
+  quiesce(): Promise<void>
+
+  /** Undoes a quiesce. */
+  cancel(): Promise<void>
+
+  /** Stops this process for `seconds`, then builds it again. */
+  stop(seconds: number): void
+}

package/types/manifest.d.ts

@@ -1,8 +1,9 @@
 import * as _norm from '@toa.io/norm/types'
-import * as _composition from './composition'
+import * as _composition from './composition.d.ts'
 
 declare namespace toa.boot {
-
-  type Manifest = (path: string, options?: _composition.Options) => Promise<_norm.Component>
-
+  type Manifest = (
+    path: string,
+    options?: _composition.Options
+  ) => Promise<_norm.Component>
 }

package/src/discovery.js

@@ -1,43 +0,0 @@
-'use strict'
-
-const { Discovery, Exposition } = require('@toa.io/core')
-
-const boot = require('./index')
-
-let promise
-let instance = null
-
-const discovery = async () => {
-  if (instance === null) {
-    instance = new Discovery(lookup)
-    promise = instance.connect()
-  }
-
-  await promise
-
-  return instance
-}
-
-const lookup = async (locator) => {
-  const call = boot.call(locator, ENDPOINT, { bindings: BINDINGS })
-
-  await call.connect()
-
-  return call
-}
-
-const expose = async (manifest) => {
-  const exposition = new Exposition(manifest.locator, manifest)
-  const operations = { [ENDPOINT]: { bindings: BINDINGS } }
-  const producers = boot.bindings.produce(exposition, operations)
-
-  await Promise.all(producers.map((producer) => producer.connect()))
-
-  return producers
-}
-
-const BINDINGS = ['@toa.io/bindings.amqp']
-const ENDPOINT = '.lookup'
-
-exports.discovery = discovery
-exports.expose = expose

package/src/exposition.js

@@ -1,17 +0,0 @@
-'use strict'
-
-const { Exposition, Locator } = require('@toa.io/core')
-
-const boot = require('./index')
-
-const exposition = async (manifest) => {
-  const locator = new Locator('', '')
-  const exposition = new Exposition(locator, manifest)
-  const producers = boot.bindings.expose(exposition)
-
-  await Promise.all(producers.map((producer) => producer.connect()))
-
-  return producers
-}
-
-exports.exposition = exposition