@toa.io/boot 1.0.0-alpha.3 → 1.0.0-alpha.300

package/src/receivers.js

@@ -1,34 +1,51 @@
-'use strict'
+import { Receiver, Locator } from '@toa.io/core'
 
-const { Receiver, Locator } = require('@toa.io/core')
+import * as boot from './index.js'
+import * as extensions from './extensions/index.js'
 
-const boot = require('./index')
-const extensions = require('./extensions')
-
-const receivers = async (manifest, runtime) => {
+export const receivers = async (manifest, component) => {
   if (manifest.receivers === undefined) return []
 
   const receivers = []
-  const local = await boot.remote(manifest.locator, manifest)
+  const local = await boot.remote(manifest.locator, undefined, manifest)
 
   for (const [label, definition] of Object.entries(manifest.receivers)) {
-    const bridge = definition.bridge !== undefined ? boot.bridge.receiver(definition.bridge, manifest.path, label) : undefined
-    const receiver = new Receiver(definition, local, bridge)
-    const decorator = extensions.receiver(receiver, manifest.locator)
-
     const locator = Locator.parse(label)
-    const transport = definition.binding ?? await resolveBinding(locator, label)
     const source = definition.source ? Locator.parse(definition.source) : locator
-    const binding = boot.bindings.receive(transport, source, label, manifest.locator.id, decorator)
+    const event = label.split('.').pop()
+    const destination = `${source.id}.${event}`
+
+    // the origin of the calls this receiver makes to its local operation
+    const origin = { namespace: source.namespace, component: source.name, event }
 
-    binding.depends(runtime)
+    const bridge =
+      definition.bridge !== undefined
+        ? await boot.bridge.receiver(definition.bridge, manifest.path, label)
+        : undefined
+    const receiver = new Receiver(
+      { ...definition, label, destination, origin },
+      local,
+      bridge
+    )
+    const decorator = extensions.receiver(receiver, manifest.locator)
+
+    const transport = definition.binding ?? (await resolveBinding(locator, label))
+    const binding = await boot.bindings.receive(
+      transport,
+      source,
+      label,
+      manifest.locator.id,
+      decorator
+    )
+
+    binding.depends(component)
     receivers.push(binding)
   }
 
   return receivers
 }
 
-async function receive (label, group, callback) {
+export async function receive(label, group, callback) {
   if (callback === undefined) {
     callback = group
     group = undefined
@@ -37,21 +54,18 @@ async function receive (label, group, callback) {
   const locator = Locator.parse(label)
   const transport = await resolveBinding(locator, label)
 
-  return boot.bindings.receive(transport, locator, label, group, callback)
+  return await boot.bindings.receive(transport, locator, label, group, callback)
 }
 
 /**
- * @param {toa.core.Locator} locator
+ * @param {import('@toa.io/core').Locator} locator
  * @param {string} label
  * @return {Promise<string>}
  */
-async function resolveBinding (locator, label) {
+async function resolveBinding(locator, label) {
   const event = label.split('.').pop()
   const discovery = await boot.discovery.discovery()
   const { events } = await discovery.lookup(locator)
 
   return events[event].binding
 }
-
-exports.receivers = receivers
-exports.receive = receive

package/src/remote.js

@@ -1,25 +1,46 @@
-'use strict'
-
-const { Remote } = require('@toa.io/core')
-const { remap } = require('@toa.io/generic')
-
-const boot = require('./index')
-
-const remote = async (locator, manifest = undefined) => {
-  const discovery = await boot.discovery.discovery()
-
-  if (manifest === undefined) manifest = await discovery.lookup(locator)
-
-  const calls = manifest.operations === undefined
-    ? {}
-    : remap(manifest.operations, (definition, endpoint) => boot.call(locator, endpoint, definition, manifest.entity))
+import { console } from 'openspan'
+import { Remote } from '@toa.io/core'
+import { remap } from '@toa.io/generic'
+
+import * as boot from './index.js'
+
+/**
+ * @param {import('@toa.io/core').Locator} locator
+ * @param {import('@toa.io/core/types').Source} [source] the origin stamped on every call made through this remote
+ * @param {toa.norm.Component} [manifest] skips discovery when the manifest is already known
+ */
+export const remote = async (locator, source, manifest) => {
+  let discovery
+
+  if (manifest === undefined) {
+    console.debug('Lookup', { locator: locator.id })
+
+    discovery = await boot.discovery.discovery(locator)
+    manifest = await discovery.lookup(locator)
+  }
+
+  // a call binds its consumers, which are loaded rather than required
+  const calls =
+    manifest.operations === undefined
+      ? {}
+      : await settle(
+          remap(manifest.operations, (definition, endpoint) =>
+            boot.call(locator, endpoint, definition, manifest.entity, source)
+          )
+        )
 
   const remote = new Remote(locator, calls)
 
   // ensure discovery shutdown
-  remote.depends(discovery)
+  if (discovery !== undefined) remote.depends(discovery)
 
   return remote
 }
 
-exports.remote = remote
+/** An object whose values are promises, as an object of what they resolve to. */
+async function settle(object) {
+  const entries = Object.entries(object)
+  const values = await Promise.all(entries.map(([, promise]) => promise))
+
+  return Object.fromEntries(entries.map(([key], index) => [key, values[index]]))
+}

package/src/span.js

@@ -0,0 +1,19 @@
+import { console, traces } from 'openspan'
+import { environment } from '@toa.io/generic'
+
+const enabled = environment.get('TOA_BOOT_TRACE') === '1'
+
+// Tracing is off until an exporter is configured, and the CLI opens its own span before
+// any extension gets to configure one — so asking for a boot trace turns the console
+// exporter on here. Extensions keep it: see `development()` in the telemetry factory.
+if (enabled) traces({ exporters: { console: {} } })
+
+/**
+ * Creates a span if boot tracing is enabled (TOA_BOOT_TRACE=1), otherwise just runs the task
+ *
+ * @param {string | object} options
+ * @param {() => Promise<any>} task
+ * @returns {Promise<any>}
+ */
+export const span = async (options, task) =>
+  enabled ? console.span(options, task) : task()

package/src/storage.js

@@ -1,41 +1,60 @@
-'use strict'
-
-const { join } = require('node:path')
-const extensions = require('./extensions')
-
-const storage = (manifest) => {
+import { createRequire } from 'node:module'
+import { pathToFileURL } from 'node:url'
+import * as extensions from './extensions/index.js'
+
+// import.meta.resolve takes no paths, and the connector is resolved against the
+// component that names it
+const require = createRequire(import.meta.url)
+
+/**
+ * @param {toa.norm.Component} manifest
+ * @param {boolean} outbox whether this component publishes anything, and so needs a place to
+ *   commit it with the entity
+ * @param {boolean} inbox whether any of its operations declares `once`, and so needs a place to
+ *   record the call it commits
+ */
+export const storage = async (manifest, outbox, inbox) => {
   if (manifest.entity === undefined) return
 
-  const [Factory, properties] = load(manifest)
+  const Factory = await load(manifest)
 
-  /** @type {toa.core.storages.Factory} */
+  /** @type {import('@toa.io/core/types').storages.Factory} */
   const factory = new Factory()
-  const storage = factory.storage(manifest.locator, properties)
-
-  return extensions.storage(storage)
+  const storage = factory.storage(manifest.locator, manifest.entity, { outbox, inbox })
+
+  // a component whose structure nothing will make must not start with the structure it lacks;
+  // what it inherits was written for descendants that store, and one that stores nothing has
+  // nothing to convert
+  const own = manifest.entity.migrations?.some(
+    (migration) => migration.prototype === undefined
+  )
+
+  if (own === true && storage.migrates !== true)
+    throw new Error(
+      `Component '${manifest.locator.id}' declares migrations, ` +
+        `which storage '${manifest.entity.storage}' does not apply`
+    )
+
+  /*
+   * Refused here rather than degraded: a storage that cannot record a call would run every
+   * duplicate of it, which is what declaring `once` asked not to happen. Whether the deployment
+   * can commit one is the storage's own to refuse, once it is connected.
+   */
+  if (inbox && storage.claims !== true)
+    throw new Error(
+      `Component '${manifest.locator.id}' declares 'once', ` +
+        `which storage '${manifest.entity.storage}' does not provide`
+    )
+
+  return extensions.storage(storage, manifest.locator)
 }
 
-function load (component) {
+async function load(component) {
   const reference = component.entity.storage
-  const path = require.resolve(reference, { paths: [component.path, __dirname] })
-  const { Factory } = require(path)
+  const path = require.resolve(reference, {
+    paths: [component.path, import.meta.dirname]
+  })
+  const { Factory } = await import(pathToFileURL(path).href)
 
-  const pkg = loadPackageJson(component.path, reference)
-  const properties = pkg === null ? null : component.properties?.[pkg.name]
-
-  return [Factory, properties]
+  return Factory
 }
-
-function loadPackageJson (root, reference) {
-  const packageJson = join(reference, 'package.json')
-
-  try {
-    const path = require.resolve(packageJson, { paths: [root, __dirname] })
-
-    return require(path)
-  } catch (e) {
-    return null
-  }
-}
-
-exports.storage = storage

package/src/storage.test.js

@@ -0,0 +1,57 @@
+import { it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { Locator } from '@toa.io/core'
+
+import { storage } from './storage.js'
+
+const manifest = (entity) => ({
+  locator: new Locator('one', 'test'),
+  path: import.meta.dirname,
+  entity
+})
+
+const schema = { properties: {} }
+
+it('should not create a storage for a component that stores nothing', async () => {
+  assert.equal(await storage(manifest(undefined), false), undefined)
+})
+
+it('should refuse migrations a storage does not apply', async () => {
+  const entity = {
+    schema,
+    storage: '@toa.io/storages.null',
+    migrations: [{ id: '0001', steps: [] }]
+  }
+
+  await assert.rejects(
+    storage(manifest(entity), false),
+    /declares migrations, which storage '@toa.io\/storages.null' does not apply/
+  )
+})
+
+it('should accept inherited migrations a storage does not apply', async () => {
+  const entity = {
+    schema,
+    storage: '@toa.io/storages.null',
+    migrations: [{ id: 'system:0001', steps: [], prototype: 'system' }]
+  }
+
+  assert.notEqual(await storage(manifest(entity), false), undefined)
+})
+
+it('should accept a storage with no migrations', async () => {
+  const entity = { schema, storage: '@toa.io/storages.null' }
+
+  assert.notEqual(await storage(manifest(entity), false), undefined)
+})
+
+it('should accept migrations a storage applies', async () => {
+  const entity = {
+    schema,
+    storage: '@toa.io/storages.mongodb',
+    migrations: [{ id: '0001', steps: [] }]
+  }
+
+  assert.notEqual(await storage(manifest(entity), false), undefined)
+})

package/src/workload.js

@@ -0,0 +1,84 @@
+import { Connector } from '@toa.io/core'
+import { PREDEFINED } from '@toa.io/definitions'
+
+import { resolve } from './extensions/resolve.js'
+import { host } from './host.js'
+
+/**
+ * A process, as a connector.
+ *
+ * What it holds is in two parts. Its *residents* are what the extensions keep in every process
+ * whatever it runs — the readiness probe is the one there is — and they connect before
+ * everything else and go last. The rest is what the command built.
+ *
+ * Which is what a process had no name for before: `toa compose`, `toa serve` and `toa mono`
+ * each assembled a root out of a bare `Connector` and their own arithmetic, and an extension
+ * with something to put in a process had nowhere to put it.
+ */
+export class Workload extends Connector {
+  /** @type {(workload: Workload) => Promise<import('@toa.io/core').Connector>} */
+  #build
+
+  /** @type {import('@toa.io/core/types').extensions.Resident[]} */
+  #residents = []
+
+  /**
+   * @param {(workload: Workload) => Promise<import('@toa.io/core').Connector>} build
+   *   what the command runs, called once
+   */
+  constructor(build) {
+    super()
+
+    this.#build = build
+  }
+
+  async open() {
+    /*
+     * Connected here rather than declared as dependencies, because what they are is read from
+     * the extensions and a connector's dependencies are walked before `open` runs. The probe
+     * goes up before the build so that it answers while the build is still happening.
+     */
+    this.#residents = await residents()
+
+    for (const resident of this.#residents) {
+      this.depends(resident)
+
+      await resident.connect()
+    }
+
+    const root = await this.#build(this)
+
+    this.depends(root)
+
+    await root.connect()
+
+    for (const resident of this.#residents) await resident.complete?.()
+  }
+}
+
+/**
+ * What the extensions this process has loaded keep in it.
+ *
+ * The predefined ones are loaded here rather than left to whichever component happens to
+ * reference them: what a resident answers for is the process, and a process that runs no
+ * component of its own must have one all the same.
+ *
+ * @returns {Promise<import('@toa.io/core/types').extensions.Resident[]>}
+ */
+async function residents() {
+  const { instances } = await import('./extensions/instances.js')
+
+  await Promise.all(Object.keys(PREDEFINED).map(async (name) => await resolve(name)))
+
+  const residents = []
+
+  for (const factory of Object.values(instances)) {
+    if (factory.resident === undefined) continue
+
+    const resident = await factory.resident(host())
+
+    if (resident !== null && resident !== undefined) residents.push(resident)
+  }
+
+  return residents
+}

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 (name: string, group?: string, binding?: string): bindings.Broadcast
+export function broadcast<T>(
+  name: string,
+  group?: string,
+  binding?: string
+): bindings.Broadcast<T>

package/types/index.d.ts

@@ -1,21 +1,35 @@
-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 * as composition from './composition.js'
 
-export * as bindings from './bindings'
+export * as bindings from './bindings.js'
 
-export async function composition (paths: string[], options?: composition.Options): Promise<core.Connector>
+export async function composition(
+  paths: string[],
+  options?: composition.Options
+): Promise<core.Connector>
 
-export async function remote (locator: core.Locator): Promise<core.Component>
+export async function remote(
+  locator: core.Locator,
+  source?: types.Source
+): Promise<core.Remote>
 
-export async function receive<T = any> (
+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>)
+}

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.js'
 
 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/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