@toa.io/boot 1.0.0-alpha.28 → 1.0.0-alpha.283

package/src/composition.js

@@ -1,24 +1,89 @@
-'use strict'
+import { console } from 'openspan'
+import { Composition } from '@toa.io/core'
+import { version } from '@toa.io/runtime'
 
-const { Composition } = require('@toa.io/core')
+import * as boot from './index.js'
+import { span } from './span.js'
 
-const boot = require('./index')
-
-async function composition (paths, options) {
+export 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,21 @@
-'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, { removeAdditional: true })
 
-  return new Request(schema)
+  return new Request(schema, definition)
 }
 
-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: what the operation returned is what the caller gets,
+  // and a value that only fits once coerced does not fit
+  const schema = schemas.schema(reply, { coerceTypes: false, useDefaults: false })
 
   return new Reply(schema)
 }
-
-exports.request = request
-exports.reply = reply

package/src/discovery.js

@@ -1,13 +1,11 @@
-'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 () => {
+export const discovery = async () => {
   if (instance === null) {
     instance = new Discovery(lookup)
     promise = instance.connect()
@@ -19,17 +17,18 @@ const discovery = async () => {
 }
 
 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 +37,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,18 @@
-'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,15 @@
-'use strict'
-
-const { file } = require('@toa.io/filesystem')
-
-async function setup () {
-  const path = await file.dot('env')
-
-  if (path !== undefined) require('dotenv').config({ path })
-}
-
-if (!('TOA_ENV' in process.env)) {
-  (async () => {
-    await setup()
-  })()
-}
+import dotenv from 'dotenv'
+import { findUp } from '@toa.io/generic'
+
+/*
+ * A local run reads what `toa env` wrote. `dotenv` leaves a variable that is already set
+ * alone, 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.
+ */
+const path = findUp('.env')
+
+if (path !== undefined) dotenv.config({ path })

package/src/events.js

@@ -0,0 +1,25 @@
+/**
+ * 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 = process.env[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/exposition.js

@@ -1,10 +1,8 @@
-'use strict'
+import { Exposition, Locator } from '@toa.io/core'
 
-const { Exposition, Locator } = require('@toa.io/core')
+import * as boot from './index.js'
 
-const boot = require('./index')
-
-const exposition = async (manifest) => {
+export const exposition = async (manifest) => {
   const locator = new Locator('', '')
   const exposition = new Exposition(locator, manifest)
   const producers = boot.bindings.expose(exposition)
@@ -13,5 +11,3 @@ const exposition = async (manifest) => {
 
   return producers
 }
-
-exports.exposition = exposition

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[]}
  */
-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}
  */
-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}
  */
-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,17 @@
-'use strict'
-
-const { instances } = require('./instances')
+import { instances } from './instances.js'
 
 /**
  * @param {toa.core.bindings.Emitter} emitter
  * @param {string} label
+ * @param {toa.core.Locator} locator
  * @returns {toa.core.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}}
  */
-exports.instances = {}
+export const instances = {}

package/src/extensions/load.js

@@ -1,14 +1,12 @@
-'use strict'
-
-const { resolve } = require('./resolve')
+import { resolve } from './resolve.js'
 
 /**
  * @param {toa.norm.Component} manifest
  */
-const load = (manifest) => {
-  if (manifest.extensions === undefined) return
+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,16 @@
+import { instances } from './instances.js'
+
+/**
+ * @param {toa.core.Connector} composition
+ * @returns {toa.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,20 +1,17 @@
-'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}
  */
-const receiver = (receiver, locator) => {
+export const receiver = (receiver, locator) => {
   let decorated = receiver
 
   for (const factory of Object.values(instances)) {
-    if (factory.receiver !== undefined) decorated = factory.receiver(decorated, locator)
+    if (factory.receiver !== undefined)
+      decorated = factory.receiver(decorated, 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<toa.core.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 {toa.core.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())
+}

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}
  */
-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[]}
  */
-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