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

package/src/composition.js

@@ -1,24 +1,113 @@
-'use strict'
+import { console } from 'openspan'
+import { Composition } from '@toa.io/core'
+import { version } from '@toa.io/runtime'
+import { environment } from '@toa.io/generic'
 
-const { Composition } = require('@toa.io/core')
+import * as boot from './index.js'
+import { span } from './span.js'
 
-const boot = require('./index')
+export async function composition(paths, options) {
+  // what a test set after this package loaded goes to the store now, before a module of a
+  // component is imported: nothing of it is left in `process.env` for that module to read
+  environment.absorb()
 
-async function composition (paths, options) {
   options = Object.assign({}, options)
 
-  const manifests = await Promise.all(paths.map((path) => boot.manifest(path, options)))
-  const tenants = await Promise.all(manifests.map(boot.extensions.tenants))
-  const expositions = await Promise.all(manifests.map(boot.discovery.expose))
-  const components = await Promise.all(manifests.map(boot.component))
+  return span('boot composition', async () => {
+    const manifests = await span(
+      'load manifests',
+      async () => await Promise.all(paths.map((path) => boot.manifest(path, options)))
+    )
 
-  const producers = components.map((component, index) =>
-    boot.bindings.produce(component, manifests[index].operations))
+    console.info('Starting composition', {
+      runtime: version,
+      components: manifests.map((manifest) => manifest.locator.id)
+    })
 
-  const receivers = await Promise.all(components.map((component, index) =>
-    boot.receivers(manifests[index], component)))
+    const tenants = await span(
+      'create tenants',
+      async () => await Promise.all(manifests.map(boot.extensions.tenants))
+    )
 
-  return new Composition(expositions.flat(), producers.flat(), receivers.flat(), tenants.flat())
-}
+    const expositions = await span(
+      'expose discovery',
+      async () => await Promise.all(manifests.map(boot.discovery.expose))
+    )
+
+    try {
+      const components = await span(
+        'create components',
+        async () => await Promise.all(manifests.map(boot.component))
+      )
+
+      const groups = await Promise.all(
+        components.map(
+          async (component, index) =>
+            await boot.bindings.produce(component, manifests[index].operations)
+        )
+      )
+
+      const receivers = await span(
+        'create receivers',
+        async () =>
+          await Promise.all(
+            components.map((component, index) =>
+              boot.receivers(manifests[index], component)
+            )
+          )
+      )
+
+      const producers = []
+      const settles = []
+
+      for (let i = 0; i < components.length; i++) {
+        const { local, other } = groups[i]
+        const settle = components[i].settle
+        const serving = [...local, ...other]
+
+        producers.push(...serving)
+
+        /*
+         * A receiver turns an event into a call to an operation of its own component, and
+         * that call is served by these — the loop producer first, the broker's if it has
+         * already gone. They are siblings under the composition otherwise, so a receiver
+         * still draining a delivery would be left calling something already torn down.
+         */
+        // one at a time: `depends` given an array links the group it makes rather than its
+        // members, and it is the members whose teardown has to wait for this one
+        for (const receiver of receivers[i])
+          for (const producer of serving) receiver.depends(producer)
 
-exports.composition = composition
+        if (settle === undefined) continue
+
+        if (local.length > 0) settle.depends(local)
+
+        for (const producer of other) producer.depends(settle)
+
+        for (const receiver of receivers[i]) receiver.depends(settle)
+
+        settles.push(settle)
+      }
+
+      const composition = new Composition(
+        expositions.flat(),
+        producers.concat(settles),
+        receivers.flat(),
+        tenants.flat()
+      )
+
+      /*
+       * A lookup that is never answered holds a connection open, and whoever
+       * awaits it has nothing to disconnect — the remote it would belong to does
+       * not exist yet. The composition owns the process's discovery instead, so
+       * an unanswered lookup cannot outlive it.
+       */
+      composition.depends(await boot.discovery.discovery())
+
+      return boot.extensions.manage(composition)
+    } catch (exception) {
+      await Promise.all(expositions.flat().map((connector) => connector.disconnect(true)))
+      throw exception
+    }
+  })
+}

package/src/context.js

@@ -1,13 +1,14 @@
-'use strict'
+import { Context, Locator } from '@toa.io/core'
 
-const { Context, Locator } = require('@toa.io/core')
+import * as boot from './index.js'
 
-const boot = require('./index')
-
-const context = async (manifest) => {
-  const local = await boot.remote(manifest.locator, manifest)
+export const context = async (manifest) => {
+  const local = await boot.remote(manifest.locator, undefined, manifest)
   const aspects = boot.extensions.aspects(manifest)
 
+  // a system aspect: it is there in every component, declared by none of them
+  aspects.push(boot.atom(manifest.locator.id))
+
   const lookup = async (namespace, name) => {
     const locator = new Locator(name, namespace)
     const remote = await boot.remote(locator)
@@ -21,5 +22,3 @@ const context = async (manifest) => {
 
   return boot.extensions.context(context)
 }
-
-exports.context = context

package/src/contract.js

@@ -1,21 +1,20 @@
-'use strict'
+import { contract } from '@toa.io/core'
+import * as schemas from '@toa.io/schemas'
 
-const { contract: { Request, Reply } } = require('@toa.io/core')
-const { Schema } = require('@toa.io/schema')
+const { Request, Reply } = contract
 
-const request = (definition, entity) => {
+export const request = (definition, entity) => {
   const request = Request.schema(definition, entity)
-  const schema = new Schema(request, { removeAdditional: true }) // soft inputs
+  const schema = schemas.schema(request)
 
-  return new Request(schema)
+  return new Request(schema, definition, entity)
 }
 
-const reply = (output, error) => {
-  const reply = Reply.schema(output, error)
-  const schema = new Schema(reply) // outputs strict
+export const reply = (output, errors) => {
+  const reply = Reply.schema(output, errors)
+
+  // a reply is read, not shaped: a value that only fits once coerced does not fit
+  const schema = schemas.schema(reply, { coerceTypes: false })
 
   return new Reply(schema)
 }
-
-exports.request = request
-exports.reply = reply

package/src/discovery.js

@@ -1,35 +1,49 @@
-'use strict'
+import { Discovery, Exposition } from '@toa.io/core'
 
-const { Discovery, Exposition } = require('@toa.io/core')
-
-const boot = require('./index')
+import * as boot from './index.js'
 
 let promise
 let instance = null
 
-const discovery = async () => {
-  if (instance === null) {
-    instance = new Discovery(lookup)
-    promise = instance.connect()
+/**
+ * The process's discovery, for as long as it is connected.
+ *
+ * A disconnected one is replaced rather than reused. A lookup becomes a dependency of the
+ * discovery that made it and nothing takes one back, so an instance carried across a
+ * disconnection would reconnect every call it has ever made beside the ones the composition now
+ * booting asks for — and every disconnection after that would walk all of them again.
+ */
+export const discovery = async () => {
+  while (true) {
+    if (instance === null) {
+      instance = new Discovery(lookup)
+      promise = instance.connect()
+    }
+
+    const current = instance
+
+    await promise
+
+    if (current.connected) return current
+
+    // whoever replaced it first wins, and the loop reads what they left
+    if (instance === current) instance = null
   }
-
-  await promise
-
-  return instance
 }
 
 const lookup = async (locator) => {
-  const call = boot.call(locator, ENDPOINT, { bindings: BINDINGS })
+  const call = await boot.call(locator, ENDPOINT, { bindings: BINDINGS })
 
   await call.connect()
 
   return call
 }
 
-const expose = async (manifest) => {
+export const expose = async (manifest) => {
   const exposition = new Exposition(manifest.locator, manifest)
   const operations = { [ENDPOINT]: { bindings: BINDINGS } }
-  const producers = boot.bindings.produce(exposition, operations)
+  const { local, other } = await boot.bindings.produce(exposition, operations)
+  const producers = local.concat(other)
 
   await Promise.all(producers.map((producer) => producer.connect()))
 
@@ -38,6 +52,3 @@ const expose = async (manifest) => {
 
 const BINDINGS = ['@toa.io/bindings.amqp']
 const ENDPOINT = '.lookup'
-
-exports.discovery = discovery
-exports.expose = expose

package/src/emission.js

@@ -1,22 +1,29 @@
-'use strict'
+import { Emission, Event } from '@toa.io/core'
 
-const { Emission, Event } = 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 emission = (definitions, locator, context) => {
+export const emission = async (definitions, locator, context) => {
   if (definitions === undefined) return
 
-  const events = Object.entries(definitions).map(([label, definition]) => {
-    const emitter = boot.bindings.emit(definition.binding, locator, label)
-    const decorator = extensions.emitter(emitter, label)
-    const bridge = boot.bridge.event(definition.bridge, definition.path, label, context)
+  const events = await Promise.all(
+    Object.entries(definitions).map(async ([label, definition]) => {
+      const emitter = await boot.bindings.emit(definition.binding, locator, label)
+      const decorator = extensions.emitter(emitter, label, locator)
+      const bridge = await boot.bridge.event(
+        definition.bridge,
+        definition.path,
+        label,
+        context
+      )
 
-    return new Event(definition, decorator, bridge)
-  })
+      return new Event(
+        { ...definition, label: `${locator.id}.${label}` },
+        decorator,
+        bridge
+      )
+    })
+  )
 
   return new Emission(events)
 }
-
-exports.emission = emission

package/src/env.js

@@ -1,15 +1,22 @@
-'use strict'
+import { readFileSync } from 'node:fs'
+import dotenv from 'dotenv'
+import { environment, findUp } from '@toa.io/generic'
 
-const { file } = require('@toa.io/filesystem')
-
-async function setup () {
-  const path = await file.dot('env')
-
-  if (path !== undefined) require('dotenv').config({ path })
+/*
+ * A local run reads what `toa env` wrote. What the file says goes to the environment store
+ * and never into `process.env`: a `.env` is where a local run keeps its secrets, and a
+ * component's code must not find them. A variable already set is left alone, as `dotenv`
+ * left it, so what the environment says still wins — and reading the file costs nothing
+ * where there is none: a deployment has no `.env` to find.
+ *
+ * It used to be read only where `TOA_ENV` was unset, taking that one variable as proof the
+ * environment had been injected. Setting it for any other reason then dropped the file
+ * whole, and every variable in it with it.
+ */
+export function load(path) {
+  environment.absorbEntries(dotenv.parse(readFileSync(path, 'utf8')))
 }
 
-if (!('TOA_ENV' in process.env)) {
-  (async () => {
-    await setup()
-  })()
-}
+const path = findUp('.env')
+
+if (path !== undefined) load(path)

package/src/events.js

@@ -0,0 +1,27 @@
+import { environment } from '@toa.io/generic'
+
+/**
+ * The events of this component that something consumes. An event nobody consumes is not
+ * published, so it gets no emitter and no exchange, and a component none of whose events are
+ * consumed gets no emission — and therefore no outbox and no transaction.
+ *
+ * The deployment computes this from the whole context. Without one — a local run, `toa mono`,
+ * a composition booted in a test — the variable is absent and every event is published.
+ *
+ * @param {toa.norm.Component} manifest
+ * @returns {toa.norm.Events | undefined}
+ */
+export const events = (manifest) => {
+  if (manifest.events === undefined) return
+
+  const value = environment.get(VARIABLE + manifest.locator.uppercase)
+
+  if (value === undefined) return manifest.events
+
+  const consumed = new Set(value.split(' ').filter(Boolean))
+  const entries = Object.entries(manifest.events).filter(([label]) => consumed.has(label))
+
+  return entries.length === 0 ? undefined : Object.fromEntries(entries)
+}
+
+const VARIABLE = 'TOA_EVENTS_'

package/src/extensions/aspects.js

@@ -1,18 +1,16 @@
-'use strict'
-
-const { resolve } = require('./resolve')
+import { instance } from './resolve.js'
 
 /**
  * @param {toa.norm.Component} manifest
- * @returns {toa.core.extensions.Aspect[]}
+ * @returns {import('@toa.io/core/types').extensions.Aspect[]}
  */
-const aspects = (manifest) => {
+export const aspects = (manifest) => {
   const aspects = []
 
   if (manifest.extensions === undefined) return aspects
 
   for (const [name, declaration] of Object.entries(manifest.extensions)) {
-    const factory = resolve(name, manifest.path)
+    const factory = instance(name, manifest.path)
 
     if (factory.aspect === undefined) continue
 
@@ -24,5 +22,3 @@ const aspects = (manifest) => {
 
   return aspects
 }
-
-exports.aspects = aspects

package/src/extensions/component.js

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

package/src/extensions/context.js

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

package/src/extensions/emitter.js

@@ -1,20 +1,18 @@
-'use strict'
-
-const { instances } = require('./instances')
+import { instances } from './instances.js'
 
 /**
- * @param {toa.core.bindings.Emitter} emitter
+ * @param {import('@toa.io/core/types').bindings.Emitter} emitter
  * @param {string} label
- * @returns {toa.core.bindings.Emitter}
+ * @param {import('@toa.io/core').Locator} locator
+ * @returns {import('@toa.io/core/types').bindings.Emitter}
  */
-const emitter = (emitter, label) => {
+export const emitter = (emitter, label, locator) => {
   let decorated = emitter
 
   for (const factory of Object.values(instances)) {
-    if (factory.emitter !== undefined) decorated = factory.emitter(decorated, label)
+    if (factory.emitter !== undefined)
+      decorated = factory.emitter(decorated, label, locator)
   }
 
   return decorated
 }
-
-exports.emitter = emitter

package/src/extensions/index.js

@@ -1,19 +1,9 @@
-'use strict'
-
-const { aspects } = require('./aspects')
-const { component } = require('./component')
-const { context } = require('./context')
-const { emitter } = require('./emitter')
-const { load } = require('./load')
-const { receiver } = require('./receiver')
-const { storage } = require('./storage')
-const { tenants } = require('./tenants')
-
-exports.aspects = aspects
-exports.component = component
-exports.context = context
-exports.emitter = emitter
-exports.load = load
-exports.receiver = receiver
-exports.storage = storage
-exports.tenants = tenants
+export { aspects } from './aspects.js'
+export { component } from './component.js'
+export { context } from './context.js'
+export { emitter } from './emitter.js'
+export { load } from './load.js'
+export { manage } from './manage.js'
+export { receiver } from './receiver.js'
+export { storage } from './storage.js'
+export { tenants } from './tenants.js'

package/src/extensions/instances.js

@@ -1,6 +1,4 @@
-'use strict'
-
 /**
- * @type {{ [key: string]: toa.core.extensions.Factory}}
+ * @type {{ [key: string]: import('@toa.io/core/types').extensions.Factory}}
  */
-exports.instances = {}
+export const instances = {}

package/src/extensions/load.js

@@ -1,14 +1,14 @@
-'use strict'
-
-const { resolve } = require('./resolve')
+import { resolve } from './resolve.js'
 
 /**
  * @param {toa.norm.Component} manifest
  */
-const load = (manifest) => {
+export const load = async (manifest) => {
   if (manifest.extensions === undefined) return
 
-  for (const name of Object.keys(manifest.extensions)) resolve(name, manifest.path)
+  await Promise.all(
+    Object.keys(manifest.extensions).map(
+      async (name) => await resolve(name, manifest.path)
+    )
+  )
 }
-
-exports.load = load

package/src/extensions/manage.js

@@ -0,0 +1,15 @@
+import { instances } from './instances.js'
+
+/**
+ * @param {import('@toa.io/core').Connector} composition
+ * @returns {import('@toa.io/core').Connector}
+ */
+export const manage = (composition) => {
+  let managed = composition
+
+  for (const factory of Object.values(instances)) {
+    if (factory.manage !== undefined) managed = factory.manage(managed)
+  }
+
+  return managed
+}

package/src/extensions/receiver.js

@@ -1,13 +1,11 @@
-'use strict'
-
-const { instances } = require('./instances')
+import { instances } from './instances.js'
 
 /**
- * @param {toa.core.Receiver} receiver
- * @param {toa.core.Locator} locator
- * @returns {toa.core.Receiver}
+ * @param {import('@toa.io/core/types').Receiver} receiver
+ * @param {import('@toa.io/core').Locator} locator
+ * @returns {import('@toa.io/core/types').Receiver}
  */
-const receiver = (receiver, locator) => {
+export const receiver = (receiver, locator) => {
   let decorated = receiver
 
   for (const factory of Object.values(instances)) {
@@ -16,5 +14,3 @@ const receiver = (receiver, locator) => {
 
   return decorated
 }
-
-exports.receiver = receiver

package/src/extensions/resolve.js

@@ -1,27 +1,52 @@
-'use strict'
+import { createRequire } from 'node:module'
+import { pathToFileURL } from 'node:url'
+import { find } from '@toa.io/generic'
+import * as boot from '../../src/index.js'
 
-const { directory: { find } } = require('@toa.io/filesystem')
-const boot = require('../..')
+import { instances } from './instances.js'
 
-const { instances } = require('./instances')
+// what `find` returns is a package directory, and a module is loaded by file
+const require = createRequire(import.meta.url)
+
+// an extension is loaded once, and what is remembered while it loads is the
+// promise, so two components cannot each make a factory
+const loading = {}
 
 /**
+ * Loads an extension and remembers its factory.
+ *
  * @param {string} reference
  * @param {string} base
- * @returns {toa.core.extensions.Factory}
+ * @returns {Promise<import('@toa.io/core/types').extensions.Factory>}
  */
-const resolve = (reference, base = process.cwd()) => {
+export const resolve = async (reference, base = process.cwd()) => {
   const path = find(reference, base)
 
-  if (instances[path] === undefined) instances[path] = create(path)
+  loading[path] ??= create(path)
+  instances[path] = await loading[path]
 
   return instances[path]
 }
 
-const create = (path) => {
-  const { Factory } = require(path)
+/**
+ * The factory of an extension already loaded. Everything that decorates what a
+ * component is made of runs after its extensions are loaded, and stays
+ * synchronous.
+ *
+ * @param {string} reference
+ * @param {string} base
+ * @returns {import('@toa.io/core/types').extensions.Factory}
+ */
+export const instance = (reference, base = process.cwd()) => {
+  const factory = instances[find(reference, base)]
+
+  if (factory === undefined) throw new Error(`Extension '${reference}' is not loaded`)
 
-  return new Factory(boot)
+  return factory
 }
 
-exports.resolve = resolve
+const create = async (path) => {
+  const { Factory } = await import(pathToFileURL(require.resolve(path)).href)
+
+  return new Factory(boot.host())
+}