@toa.io/boot 1.0.0-alpha.33 → 1.0.0-alpha.330

package/src/bindings/produce.js

@@ -1,28 +1,73 @@
-'use strict'
+import { definition } from '@toa.io/norm'
+import { LOOP } from './constants.js'
+import { factory } from './factory.js'
 
-const { LOOP } = require('./constants')
-const { factory } = require('./factory')
+export const produce = async (component, operations) => {
+  const local = []
+  const other = []
+  const stateful = addressed(operations)
+  const streams = streamed(operations)
 
-const produce = (component, operations) => group(operations, (factory, endpoints) =>
-  factory.producer(component.locator, endpoints, component))
+  for (const [binding, endpoints] of await group(operations)) {
+    const made = await factory(binding)
+    const carried = stateful.filter((endpoint) => endpoints.includes(endpoint))
+    const carries = streams.filter((endpoint) => endpoints.includes(endpoint))
+    const producer = made.producer(
+      component.locator,
+      endpoints,
+      component,
+      carried,
+      carries
+    )
+    const { properties } = (await definition(binding)).module
 
-const group = (operations, callback) => {
+    if (properties.local === true) local.push(producer)
+    else other.push(producer)
+  }
+
+  return { local, other }
+}
+
+/** The endpoints that take one of their input properties as a stream. */
+const streamed = (operations) =>
+  operations === undefined
+    ? []
+    : Object.entries(operations)
+        .filter(([, operation]) => operation.stream !== undefined)
+        .map(([endpoint]) => endpoint)
+
+/** The endpoints that take addressed calls only. */
+const addressed = (operations) =>
+  operations === undefined
+    ? []
+    : Object.entries(operations)
+        .filter(([, operation]) => operation.stateful === true)
+        .map(([endpoint]) => endpoint)
+
+/** The endpoints each binding carries, as entries. */
+const group = async (operations) => {
   const map = {}
 
-  for (const [endpoint, operation] of Object.entries(operations)) {
-    // noinspection JSUnresolvedVariable
-    const bindings = global.TOA_INTEGRATION_BINDINGS_LOOP_DISABLED
-      ? operation.bindings
-      : [LOOP].concat(operation.bindings)
+  if (operations !== undefined)
+    for (const [endpoint, operation] of Object.entries(operations)) {
+      // noinspection JSUnresolvedVariable
+      const bindings = global.TOA_INTEGRATION_BINDINGS_LOOP_DISABLED
+        ? operation.bindings
+        : [LOOP].concat(operation.bindings)
 
-    for (const binding of bindings) {
-      if (!map[binding]) map[binding] = []
+      for (const binding of bindings) {
+        // an endpoint that takes a stream is served by the bindings that carry one, and by no other
+        if (operation.stream !== undefined && !(await carries(binding))) continue
 
-      map[binding].push(endpoint)
+        if (!map[binding]) map[binding] = []
+
+        map[binding].push(endpoint)
+      }
     }
-  }
 
-  return Object.entries(map).map(([binding, endpoints]) => callback(factory(binding), endpoints))
+  return Object.entries(map)
 }
 
-exports.produce = produce
+/** Whether a binding carries a call whose input holds a stream, which only its module says. */
+export const carries = async (binding) =>
+  (await definition(binding)).module.properties.streams === true

package/src/bindings/receive.js

@@ -1,7 +1,4 @@
-'use strict'
+import { factory } from './factory.js'
 
-const { factory } = require('./factory')
-
-const receive = (binding, locator, label, group, receiver) => factory(binding).receiver(locator, label, group, receiver)
-
-exports.receive = receive
+export const receive = async (binding, locator, label, group, receiver) =>
+  (await factory(binding)).receiver(locator, label, group, receiver)

package/src/bridge.js

@@ -1,28 +1,34 @@
-'use strict'
-
-const algorithm = (bridge, path, endpoint, context) => {
-  const algorithm = resolve(bridge).algorithm(path, endpoint, context)
+export async function algorithm(bridge, path, endpoint, context) {
+  const factory = await resolve(bridge)
+  const algorithm = await factory.algorithm(path, endpoint, context)
 
   algorithm.depends(context)
 
   return algorithm
 }
 
-const event = (bridge, path, label, context) => resolve(bridge).event(path, label, context)
-const receiver = (bridge, path, label) => resolve(bridge).receiver(path, label)
+export const event = async (bridge, path, label, context) =>
+  (await resolve(bridge)).event(path, label, context)
 
-const factories = {}
+export const receiver = async (bridge, path, label) =>
+  (await resolve(bridge)).receiver(path, label)
 
-const resolve = (bridge) => {
-  if (factories[bridge] === undefined) {
-    const { Factory } = require(bridge)
+export const guard = async (bridge, path, label, context) =>
+  (await resolve(bridge)).guard(path, label, context)
 
-    factories[bridge] = new Factory()
-  }
+export async function rc(bridge, path, context) {
+  const factory = await resolve(bridge)
 
-  return factories[bridge]
+  if (factory.rc === undefined) return
+
+  return factory.rc(path, context)
 }
 
-exports.algorithm = algorithm
-exports.event = event
-exports.receiver = receiver
+const factories = {}
+
+// the promise is what is remembered, so two boots cannot each make a factory
+const resolve = async (bridge) => {
+  factories[bridge] ??= import(bridge).then(({ Factory }) => new Factory())
+
+  return await factories[bridge]
+}

package/src/call.js

@@ -1,15 +1,35 @@
-'use strict'
+import { Call, safe, Transmission } from '@toa.io/core'
 
-const { Call, Transmission } = require('@toa.io/core')
+import * as boot from './index.js'
 
-const boot = require('./index')
-
-const call = (locator, endpoint, definition, entity) => {
-  const consumers = boot.bindings.consume(locator, endpoint, definition.bindings)
+// eslint-disable-next-line max-params
+export const call = async (locator, endpoint, definition, entity, source) => {
+  const consumers = await boot.bindings.consume(
+    locator,
+    endpoint,
+    definition.bindings,
+    definition.stream !== undefined
+  )
   const transmission = new Transmission(consumers)
   const contract = boot.contract.request(definition, entity)
 
-  return new Call(transmission, contract)
-}
+  const stateful = definition.stateful === true
 
-exports.call = call
+  /*
+   * An endpoint beginning with `.` is the runtime's own rather than an operation — a lookup, an
+   * exposition — so the safety of operations has nothing to say about it. `Component.invoke`
+   * counts it as no hop in a call chain for the same reason.
+   */
+  const readable = endpoint[0] === '.' || safe(definition.type)
+
+  return new Call(
+    transmission,
+    contract,
+    `${locator.id}.${endpoint}`,
+    source,
+    stateful,
+    readable,
+    definition.stream,
+    definition.once === true || typeof definition.once === 'number'
+  )
+}

package/src/cascade.js

@@ -1,16 +1,19 @@
-'use strict'
+import { Cascade } from '@toa.io/core'
 
-const { Cascade } = require('@toa.io/core')
+import * as boot from './index.js'
 
-const boot = require('./index')
-
-const cascade = (manifest, endpoint, definition, context) => {
+export async function cascade(manifest, endpoint, definition, context, preflight) {
   const bridges = []
 
   if (definition.forward) endpoint = definition.forward
 
   if (definition.bridge) {
-    const bridge = boot.bridge.algorithm(definition.bridge, manifest.path, endpoint, context)
+    const bridge = await boot.bridge.algorithm(
+      definition.bridge,
+      manifest.path,
+      endpoint,
+      context
+    )
 
     bridges.unshift(bridge)
   }
@@ -22,12 +25,15 @@ const cascade = (manifest, endpoint, definition, context) => {
 
     if (operation === undefined) continue
 
-    const bridge = boot.bridge.algorithm(operation.bridge, prototype.path, endpoint, context)
+    const bridge = await boot.bridge.algorithm(
+      operation.bridge,
+      prototype.path,
+      endpoint,
+      context
+    )
 
     bridges.unshift(bridge)
   }
 
-  return new Cascade(bridges)
+  return new Cascade(bridges, preflight)
 }
-
-exports.cascade = cascade

package/src/component.js

@@ -1,48 +1,117 @@
-'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)
+
+  // a destination that renders the component's events renders them with its context
+  await boot.rendering(manifest, destinations, context)
+
+  // and one that carries a change to other regions carries what the regional ones write
+  boot.regional(destinations)
+
+  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,124 @@
-'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)
+
+      /*
+       * A tenant calls its own component as well — a pulse calls an operation, the dispatcher of
+       * delayed calls writes the rows it has made the calls of — and what it has in hand when it
+       * closes it finishes through these. A sibling, it would be left waiting for a reply from
+       * something torn down beside it, which is a shutdown that never ends.
+       */
+      for (const tenant of tenants[i])
+        for (const producer of serving) tenant.depends(producer)
 
-exports.composition = composition
+      /*
+       * 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)
+
+        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