@toa.io/boot 1.0.0-alpha.34 → 1.0.0-alpha.341

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
+}

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,76 @@
-'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 {Promise<import('@toa.io/core/types').extensions.Factory>}
+ */
+export const resolve = async (reference, base = process.cwd()) => {
+  const path = find(pack(reference), base)
+
+  loading[path] ??= create(path)
+  instances[path] = await loading[path]
+
+  return keyed(instances[path], reference)
+}
 
 /**
+ * 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}
+ * @returns {import('@toa.io/core/types').extensions.Factory}
  */
-const resolve = (reference, base = process.cwd()) => {
-  const path = find(reference, base)
+export const instance = (reference, base = process.cwd()) => {
+  const factory = instances[find(pack(reference), base)]
 
-  if (instances[path] === undefined) instances[path] = create(path)
+  if (factory === undefined) throw new Error(`Extension '${reference}' is not loaded`)
 
-  return instances[path]
+  return keyed(factory, reference)
 }
 
-const create = (path) => {
-  const { Factory } = require(path)
+/**
+ * `package#key` is a declaration a package claims beside its main one, and what the package's
+ * factory offers for that key answers for it — so a key is never taken for the package itself.
+ *
+ * @param {import('@toa.io/core/types').extensions.Factory} factory
+ * @param {string} reference
+ * @returns {import('@toa.io/core/types').extensions.Factory}
+ */
+const keyed = (factory, reference) => {
+  const key = reference.split('#')[1]
+
+  if (key === undefined) return factory
+
+  const claimed = factory.keys?.[key]
 
-  return new Factory(boot)
+  if (claimed === undefined)
+    throw new Error(`'${reference}' names a key its package does not claim`)
+
+  return claimed
 }
 
-exports.resolve = resolve
+/** The package a reference is of. */
+const pack = (reference) => reference.split('#')[0]
+
+const create = async (path) => {
+  const { Factory } = await import(pathToFileURL(require.resolve(path)).href)
+
+  return new Factory(boot.host())
+}

package/src/extensions/storage.js

@@ -1,19 +1,16 @@
-'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
+ * @param {import('@toa.io/core').Locator} locator whose storage it is
+ * @returns {import('@toa.io/core/types').storages.Storage}
  */
-const storage = (storage) => {
+export const storage = (storage, locator) => {
   let decorated = storage
 
   for (const factory of Object.values(instances)) {
-    if (factory.storage !== undefined) decorated = factory.storage(decorated)
+    if (factory.storage !== undefined) decorated = factory.storage(decorated, locator)
   }
 
   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,29 @@
+import { Gate } from '@toa.io/core'
+
+import * as boot from './index.js'
+
+/**
+ * @param {import('./workload.js').Workload} [workload] the process, where there is one
+ *
+ * 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 = (workload) => ({
+  // an extension knows a version only where something told it one; see `Remotes` in exposition
+  remote: (locator, source, contract) => boot.remote(locator, source, { contract }),
+  broadcast: boot.bindings.broadcast,
+  composition: boot.composition,
+  receive: boot.receive,
+  atom: boot.atomicity,
+  outbound: boot.bindings.outbound,
+  inbound: boot.bindings.inbound,
+
+  // a composition booted outside a process — by a scenario, by `toa call` — has no workload, so
+  // its gates are ones nothing ever takes down and a halt asked of it is nobody's to perform
+  gate: (build) => workload?.gate(build) ?? new Gate(build),
+  quiesce: async () => await workload?.quiesce(),
+  cancel: async () => await workload?.cancel(),
+  stop: (seconds) => workload?.stop(seconds)
+})

package/src/inbox.js

@@ -0,0 +1,12 @@
+/**
+ * Whether any operation of this component declares `once`, which is what decides that a place
+ * to record a call is made at all. Local to the manifest, unlike the events something consumes,
+ * so there is no variable a deployment computes.
+ *
+ * @param {toa.norm.Component} manifest
+ * @returns {boolean}
+ */
+export const inbox = (manifest) =>
+  Object.values(manifest.operations ?? {}).some(
+    (definition) => definition.once === true || typeof definition.once === 'number'
+  )

package/src/index.js

@@ -1,36 +1,31 @@
-'use strict'
+// the environment is read at module scope elsewhere, so it is loaded first
+export { load as env } from './env.js'
 
-require('./env')
+export * as bindings from './bindings/index.js'
+export * as bridge from './bridge.js'
+export * as contract from './contract.js'
+export * 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')
-
-exports.bindings = require('./bindings')
-exports.bridge = require('./bridge')
-exports.contract = require('./contract')
-exports.discovery = require('./discovery')
-exports.extensions = require('./extensions')
-
-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 { call } from './call.js'
+export { cascade } from './cascade.js'
+export { component } from './component.js'
+export { composition } from './composition.js'
+export { context } from './context.js'
+export { emission } from './emission.js'
+export { events } from './events.js'
+export { inbox } from './inbox.js'
+export { outbox } from './outbox.js'
+export { atomicity } from './atomicity.js'
+export { atom } from './atom.js'
+export * as map from './map.js'
+export { manifest } from './manifest.js'
+export { operation } from './operation.js'
+export { receivers, receive } from './receivers.js'
+export { remote } from './remote.js'
+export { rendering } from './rendering.js'
+export { regional } from './regional.js'
+export { storage } from './storage.js'
+export { guards } from './guards.js'
+export { host } from './host.js'
+export { rc } from './rc.js'
+export { Workload } from './workload.js'