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

package/src/component.js

@@ -1,48 +1,110 @@
-'use strict'
-
-const { remap } = require('@toa.io/generic')
-const {
-  Component,
-  Locator,
-  State,
-  entities
-} = require('@toa.io/core')
-const { Schema } = require('@toa.io/schema')
-
-const boot = require('./index')
-
-/**
- * @param {toa.norm.Component} manifest
- * @returns {Promise<toa.core.Component>}
- */
-const component = async (manifest) => {
-  boot.extensions.load(manifest)
+import { Component, Locator, State, entities } from '@toa.io/core'
+import { entity as declaration } from '@toa.io/norm'
+import { schema as compileSchema } from '@toa.io/schemas'
+import { environment } from '@toa.io/generic'
 
+import * as boot from './index.js'
+import { span } from './span.js'
+
+export const component = async (manifest) => {
   const locator = new Locator(manifest.name, manifest.namespace)
-  const storage = boot.storage(manifest)
+
+  return span(`component ${locator.id}`, () => create(manifest, locator))
+}
+
+const create = async (manifest, locator) => {
+  // what a test set after this package loaded goes to the store now, before a module of the
+  // component is imported: nothing of it is left in `process.env` for that module to read
+  environment.absorb()
+
+  // the suffix is what it is now, `.env` having been read: whatever this process sets for the
+  // processes it starts later does not rename what it has
+  environment.suffix()
+
+  await boot.extensions.load(manifest)
+
+  // the storage is told whether there will be an outbox, so what it publishes to comes first:
+  // its own events, and whatever an extension adds
+  const events = boot.events(manifest)
+  const destinations = await boot.extensions.destinations(manifest)
+  const storage = await boot.storage(
+    manifest,
+    events !== undefined || destinations.length > 0,
+    boot.inbox(manifest)
+  )
   const context = await boot.context(manifest)
-  const emission = boot.emission(manifest.events, locator, context)
+  const emission = await boot.emission(events, locator, context)
+  const outbox = boot.outbox(manifest, storage, emission, destinations)
 
   let state
 
   if (manifest.entity !== undefined) {
-    const schema = new Schema(manifest.entity.schema)
-    const entity = new entities.Factory(schema)
+    const schemas = compile(manifest.entity)
+    const guards = await boot.guards(manifest, context)
+    const blank = manifest.entity.blank ?? {}
 
-    state = new State(storage, entity, emission, manifest.entity.associated)
-  }
+    // fitted here rather than where the first record is written, so a component that
+    // declares a blank nothing can hold does not boot
+    const error = schemas.changeset.fit(blank)
+
+    if (error !== null)
+      throw new Error(`Component '${locator.id}' entity blank: ${error.message}`)
 
-  const operations = manifest.operations === undefined
-    ? {}
-    : remap(manifest.operations, (definition, endpoint) =>
-      boot.operation(manifest, endpoint, definition, context, state))
+    state = new State(
+      storage,
+      new entities.Factory(schemas, blank, guards),
+      outbox,
+      manifest.entity.associated
+    )
+  }
 
+  const phases = await boot.rc(manifest, context)
+  const operations = await bootOperations(manifest, context, state, phases?.preflight)
   const component = new Component(locator, operations)
 
   if (storage) component.depends(storage)
-  if (emission) component.depends(emission)
 
-  return boot.extensions.component(component)
+  // the outbox owns the emission and the storage, so it drains before either goes down
+  if (outbox) component.depends(outbox)
+  else if (emission) component.depends(emission)
+
+  const decorated = boot.extensions.component(component)
+
+  if (phases?.settle !== undefined) decorated.settle = phases.settle
+
+  if (phases?.ready !== undefined) decorated.ready = phases.ready
+
+  // a dependency closes after its dependant, so the component is already closed
+  // when the RC releases what it opened
+  if (phases?.dispose !== undefined) decorated.depends(phases.dispose)
+
+  // a dependency of the component, so the walk that stops a tree reaches it there
+  if (phases?.quiescence !== undefined) decorated.depends(phases.quiescence)
+
+  return decorated
+}
+
+async function bootOperations(manifest, context, state, preflight) {
+  if (manifest.operations === undefined) return {}
+
+  const entries = Object.entries(manifest.operations)
+
+  // each one loads its algorithm from disk and compiles its contracts
+  const booted = await Promise.all(
+    entries.map(([endpoint, definition]) =>
+      boot.operation(manifest, endpoint, definition, context, state, preflight)
+    )
+  )
+
+  const operations = {}
+
+  for (let i = 0; i < entries.length; i++) operations[entries[i][0]] = booted[i]
+
+  return operations
 }
 
-exports.component = component
+/** What a stored record must fit, and what a changeset may. */
+const compile = (entity) => ({
+  entity: compileSchema(declaration.schema(entity)),
+  changeset: compileSchema(declaration.changeset(entity))
+})

package/src/composition.js

@@ -1,24 +1,115 @@
-'use strict'
+import { console } from 'openspan'
+import { Composition } from '@toa.io/core'
+import { version } from '@toa.io/definitions'
+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()
+
+  // the suffix is what it is now, `.env` having been read: whatever this process sets for the
+  // processes it starts later does not rename what it has
+  environment.suffix()
 
-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)))
+    // what this process composes it knows, and the map it was given says the same
+    await boot.map.compose(manifests)
 
-  return new Composition(expositions.flat(), producers.flat(), receivers.flat(), tenants.flat())
-}
+    const tenants = await span(
+      'create tenants',
+      async () => await Promise.all(manifests.map(boot.extensions.tenants))
+    )
+
+    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 = []
+    const readies = []
+
+    for (let i = 0; i < components.length; i++) {
+      const { local, other } = groups[i]
+      const { settle, ready } = components[i]
+      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)
+
+      /*
+       * The broker producers serve the stateful endpoints under the process's name, and the
+       * name is held once they are open — before then a call to it is refused. `ready` is where
+       * a component hands the name out, so it waits for every producer and receiver of its own.
+       */
+      if (ready !== undefined) {
+        for (const producer of serving) ready.depends(producer)
 
-exports.composition = composition
+        for (const receiver of receivers[i]) ready.depends(receiver)
+
+        readies.push(ready)
+      }
+
+      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(
+      producers.concat(settles, readies),
+      receivers.flat(),
+      tenants.flat()
+    )
+
+    return boot.extensions.manage(composition)
+  })
+}

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, { contract: 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/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/destinations.js

@@ -0,0 +1,27 @@
+import { instance } from './resolve.js'
+
+/**
+ * Where a committed state change of this component goes, beside its own events. An extension
+ * that contributes one gives the component an outbox whether or not it declares an event, so
+ * this is read before the storage is made.
+ *
+ * @param {toa.norm.Component} manifest
+ * @returns {Promise<import('@toa.io/core/types').outbox.Destination[]>}
+ */
+export const destinations = async (manifest) => {
+  const destinations = []
+
+  if (manifest.extensions === undefined) return destinations
+
+  for (const [name, declaration] of Object.entries(manifest.extensions)) {
+    const factory = instance(name, manifest.path)
+
+    if (factory.destination === undefined) continue
+
+    const destination = await factory.destination(manifest.locator, declaration, manifest)
+
+    if (destination !== undefined) destinations.push(destination)
+  }
+
+  return destinations
+}

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,10 @@
-'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 { destinations } from './destinations.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
+}