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

package/src/extensions/storage.js

@@ -1,12 +1,10 @@
-'use strict'
-
-const { instances } = require('./instances')
+import { instances } from './instances.js'
 
 /**
- * @param {toa.core.Storage} storage
- * @returns {toa.core.Storage}
+ * @param {import('@toa.io/core/types').storages.Storage} storage
+ * @returns {import('@toa.io/core/types').storages.Storage}
  */
-const storage = (storage) => {
+export const storage = (storage) => {
   let decorated = storage
 
   for (const factory of Object.values(instances)) {
@@ -15,5 +13,3 @@ const storage = (storage) => {
 
   return decorated
 }
-
-exports.storage = storage

package/src/extensions/tenants.js

@@ -1,27 +1,23 @@
-'use strict'
-
-const { resolve } = require('./resolve')
+import { resolve } from './resolve.js'
 
 /**
  * @param {toa.norm.Component} manifest
- * @returns {toa.core.Connector[]}
+ * @returns {import('@toa.io/core').Connector[]}
  */
-const tenants = (manifest) => {
+export const tenants = async (manifest) => {
   const tenants = []
 
   if (manifest.extensions === undefined) return tenants
 
   for (const [name, declaration] of Object.entries(manifest.extensions)) {
-    const factory = resolve(name, manifest.path)
+    const factory = await resolve(name, manifest.path)
 
     if (factory.tenant === undefined) continue
 
-    const tenant = factory.tenant(manifest.locator, declaration)
+    const tenant = await factory.tenant(manifest.locator, declaration, manifest)
 
     tenants.push(tenant)
   }
 
   return tenants
 }
-
-exports.tenants = tenants

package/src/guards.js

@@ -0,0 +1,20 @@
+import { Guard } from '@toa.io/core'
+import * as boot from './index.js'
+
+export async function guards(manifest, context) {
+  if (manifest.guards === undefined) return
+
+  const entries = Object.entries(manifest.guards)
+
+  return await Promise.all(
+    entries.map(async ([name, guard]) => {
+      const bridge = await load(guard, name, context)
+
+      return new Guard(name, bridge)
+    })
+  )
+}
+
+async function load(guard, name, context) {
+  return await boot.bridge.guard(guard.bridge, guard.path, name, context)
+}

package/src/host.js

@@ -0,0 +1,15 @@
+import * as boot from './index.js'
+
+/**
+ * What the process hosting an extension provides to it. The counterpart of a component's
+ * context: an extension reaches the core through this and through nothing else.
+ *
+ * @returns {import('@toa.io/core/types').extensions.Host}
+ */
+export const host = () => ({
+  remote: boot.remote,
+  broadcast: boot.bindings.broadcast,
+  composition: boot.composition,
+  receive: boot.receive,
+  atom: boot.atomicity
+})

package/src/index.js

@@ -1,36 +1,52 @@
-'use strict'
+// the environment is read at module scope elsewhere, so it is loaded first
+import { load as env } from './env.js'
 
-require('./env')
+import * as bindings from './bindings/index.js'
+import * as bridge from './bridge.js'
+import * as contract from './contract.js'
+import * as discovery from './discovery.js'
+import * as extensions from './extensions/index.js'
 
-const { call } = require('./call')
-const { cascade } = require('./cascade')
-const { component } = require('./component')
-const { composition } = require('./composition')
-const { context } = require('./context')
-const { emission } = require('./emission')
-const { exposition } = require('./exposition')
-const { manifest } = require('./manifest')
-const { operation } = require('./operation')
-const { receivers, receive } = require('./receivers')
-const { remote } = require('./remote')
-const { storage } = require('./storage')
+import { call } from './call.js'
+import { cascade } from './cascade.js'
+import { component } from './component.js'
+import { composition } from './composition.js'
+import { context } from './context.js'
+import { emission } from './emission.js'
+import { events } from './events.js'
+import { outbox } from './outbox.js'
+import { atomicity } from './atomicity.js'
+import { atom } from './atom.js'
+import { manifest } from './manifest.js'
+import { operation } from './operation.js'
+import { receivers, receive } from './receivers.js'
+import { remote } from './remote.js'
+import { storage } from './storage.js'
+import { guards } from './guards.js'
+import { host } from './host.js'
+import { rc } from './rc.js'
 
-exports.bindings = require('./bindings')
-exports.bridge = require('./bridge')
-exports.contract = require('./contract')
-exports.discovery = require('./discovery')
-exports.extensions = require('./extensions')
+export {
+  call,
+  env,
+  cascade,
+  component,
+  composition,
+  context,
+  emission,
+  events,
+  outbox,
+  atomicity,
+  atom,
+  host,
+  manifest,
+  operation,
+  receivers,
+  receive,
+  remote,
+  storage,
+  guards,
+  rc
+}
 
-exports.call = call
-exports.cascade = cascade
-exports.component = component
-exports.composition = composition
-exports.context = context
-exports.emission = emission
-exports.exposition = exposition
-exports.manifest = manifest
-exports.operation = operation
-exports.receivers = receivers
-exports.receive = receive
-exports.remote = remote
-exports.storage = storage
+export { bindings, bridge, contract, discovery, extensions }

package/src/manifest.js

@@ -1,17 +1,18 @@
-'use strict'
+import clone from 'clone-deep'
+import { basename } from 'node:path'
+import { merge } from '@toa.io/generic'
+import { component as load, definition } from '@toa.io/norm'
+import { Locator } from '@toa.io/core'
 
-const clone = require('clone-deep')
-const { merge } = require('@toa.io/generic')
-const { component: load } = require('@toa.io/norm')
-const { Locator } = require('@toa.io/core')
+import { span } from './span.js'
 
-/**
- * @type {toa.boot.Manifest}
- */
-const manifest = async (path, options = {}) => {
+export const manifest = async (path, options = {}) => {
   options = merge(clone(options), DEFAULTS)
 
-  const manifest = await load(path)
+  const manifest = await span(
+    { name: `manifest ${basename(path)}`, attributes: { path } },
+    async () => await load(path)
+  )
 
   if (options?.bindings !== undefined) {
     if ('operations' in manifest) {
@@ -20,10 +21,19 @@ const manifest = async (path, options = {}) => {
       }
     }
 
-    const check = (binding) => require(binding).properties?.async === true
-    const asyncBinding = options.bindings.find(check)
+    let asyncBinding
 
-    if (asyncBinding === undefined) throw new Error('Bindings override must contain at least one async binding')
+    for (const binding of options.bindings) {
+      const { properties } = (await definition(binding)).module
+
+      if (properties?.async === true) {
+        asyncBinding = binding
+        break
+      }
+    }
+
+    if (asyncBinding === undefined)
+      throw new Error('Bindings override must contain at least one async binding')
 
     if ('events' in manifest) {
       for (const event of Object.values(manifest.events)) event.binding = asyncBinding
@@ -44,7 +54,8 @@ const manifest = async (path, options = {}) => {
     }
   }
 
-  if ('storage' in options && 'entity' in manifest) manifest.entity.storage = options.storage
+  if ('storage' in options && 'entity' in manifest)
+    manifest.entity.storage = options.storage
 
   manifest.locator = new Locator(manifest.name, manifest.namespace)
 
@@ -52,5 +63,3 @@ const manifest = async (path, options = {}) => {
 }
 
 const DEFAULTS = {}
-
-exports.manifest = manifest

package/src/manifest.test.js

@@ -1,12 +1,16 @@
-'use strict'
+import { it, mock } from 'node:test'
+import assert from 'node:assert/strict'
 
-const { generate } = require('randomstring')
+import { generate } from 'randomstring'
 
-jest.mock('@toa.io/norm', () => ({
-  component: () => mockComponent()
-}))
+mock.module('@toa.io/norm', {
+  namedExports: {
+    component: () => mockComponent(),
+    definition: async () => ({ module: {} })
+  }
+})
 
-const { manifest } = require('./manifest')
+const { manifest } = await import('./manifest.js')
 
 const path = generate()
 
@@ -15,9 +19,9 @@ it('should not modify options', async () => {
 
   await manifest(path, options)
 
-  expect(options.extensions.length).toStrictEqual(2)
+  assert.deepStrictEqual(options.extensions.length, 2)
 })
 
-function mockComponent () {
+function mockComponent() {
   return { name: generate(), namespace: generate() }
 }

package/src/operation.js

@@ -1,18 +1,31 @@
-'use strict'
+import {
+  Transition,
+  Observation,
+  Assignment,
+  Operation,
+  Query,
+  Effect,
+  Unmanaged
+} from '@toa.io/core'
 
-const { Transition, Observation, Assignment, Operation, Query } = require('@toa.io/core')
+import * as boot from './index.js'
 
-const boot = require('./index')
-
-const operation = (manifest, endpoint, definition, context, scope) => {
-  const cascade = boot.cascade(manifest, endpoint, definition, context)
-  const reply = boot.contract.reply(definition.output, definition.error)
+export async function operation(
+  manifest,
+  endpoint,
+  definition,
+  context,
+  scope,
+  preflight
+) {
+  const cascade = await boot.cascade(manifest, endpoint, definition, context, preflight)
+  const reply = boot.contract.reply(definition.output, definition.errors)
   const input = definition.input
   const request = boot.contract.request({ input }, manifest.entity)
   const contracts = { reply, request }
-  const query = manifest.entity === undefined
-    ? undefined
-    : new Query(manifest.entity.schema.properties)
+
+  const query =
+    manifest.entity === undefined ? undefined : new Query(manifest.entity.properties)
 
   const Type = TYPES[definition.type]
 
@@ -24,7 +37,6 @@ const TYPES = {
   observation: Observation,
   assignment: Assignment,
   computation: Operation,
-  effect: Operation
+  effect: Effect,
+  unmanaged: Unmanaged
 }
-
-exports.operation = operation

package/src/outbox.js

@@ -0,0 +1,17 @@
+import { Outbox } from '@toa.io/core'
+
+import * as boot from './index.js'
+
+/**
+ * A component with no declared events has nothing to publish and therefore no outbox — the
+ * static check that keeps the common case free of a transaction.
+ *
+ * @param {toa.norm.Component} manifest
+ * @param {import('@toa.io/core/types').storages.Storage} [storage]
+ * @param {import('@toa.io/core').Emission} [emission]
+ */
+export const outbox = (manifest, storage, emission) => {
+  if (emission === undefined) return
+
+  return new Outbox(emission, storage, boot.atomicity(manifest.locator.id), {})
+}

package/src/rc.js

@@ -0,0 +1,5 @@
+import * as boot from './index.js'
+
+export async function rc(manifest, context) {
+  return boot.bridge.rc(manifest.bridge, manifest.path, context)
+}

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,26 +1,47 @@
-'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
+ */
+export const storage = async (manifest, outbox) => {
   if (manifest.entity === undefined) return
 
-  const Factory = 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, manifest.entity)
+  const storage = factory.storage(manifest.locator, manifest.entity, { outbox })
+
+  // 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`
+    )
 
   return extensions.storage(storage)
 }
 
-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)
 
   return Factory
 }
-
-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/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>