@toa.io/boot 1.0.0-alpha.3 → 1.0.0-alpha.300

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

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,17 @@
+import * as boot from './index.js'
+
+/**
+ * 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 = () => ({
+  remote: boot.remote,
+  broadcast: boot.bindings.broadcast,
+  composition: boot.composition,
+  receive: boot.receive,
+  atom: boot.atomicity,
+  outbound: boot.bindings.outbound,
+  inbound: boot.bindings.inbound
+})

package/src/inbox.js

@@ -0,0 +1,10 @@
+/**
+ * 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)

package/src/index.js

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

package/src/manifest.js

@@ -1,52 +1,98 @@
-'use strict'
+import clone from 'clone-deep'
+import { existsSync, readFileSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { basename, dirname, join } from 'node:path'
+import { merge } from '@toa.io/generic'
+import { component as load, definition, revive, NORMALIZED } from '@toa.io/norm'
+import { Locator } from '@toa.io/core'
 
-const clone = require('clone-deep')
-const { merge } = require('@toa.io/generic')
-const { component: load } = require('@toa.io/norm')
-const { Locator } = require('@toa.io/core')
+import { span } from './span.js'
+
+export const manifest = async (path, options = {}) => {
+  options = merge(clone(options), DEFAULTS)
+
+  const manifest = await span(
+    { name: `manifest ${basename(path)}`, attributes: { path } },
+    async () => await read(path)
+  )
+
+  if (manifest.extensions === undefined) manifest.extensions = {}
+
+  if (options.extensions !== undefined) {
+    for (const extension of options.extensions) {
+      if (!(extension in manifest.extensions)) manifest.extensions[extension] = null
+    }
+  }
+
+  if ('storage' in options && 'entity' in manifest)
+    manifest.entity.storage = options.storage
+
+  manifest.locator = new Locator(manifest.name, manifest.namespace)
+
+  return manifest
+}
 
 /**
- * @type {toa.boot.Manifest}
+ * A manifest already normalised, where there is one, and the sources read where there is not.
+ *
+ * A component of an application's own comes with the manifest its build wrote beside it. A
+ * component an extension ships comes with none — its package is published once, long before
+ * any image is built — but `@toa.io/definitions` carries the digest of those manifests, which
+ * a deploy has read for as long as it has been unable to install the extension. A service runs
+ * them from the package, so it reads the same digest rather than reading their sources again.
+ *
+ * Only a workspace normalises, then, which is the one place a source can have changed since.
+ *
+ * @param {string} path
  */
-const manifest = async (path, options = {}) => {
-  options = merge(clone(options), DEFAULTS)
+async function read(path) {
+  const file = join(path, NORMALIZED)
 
-  const manifest = await load(path)
+  if (existsSync(file)) return revive(JSON.parse(await readFile(file, 'utf8')), path)
 
-  if (options?.bindings !== undefined) {
-    if ('operations' in manifest)
-      for (const operation of Object.values(manifest.operations))
-        operation.bindings = options.bindings
+  return (await digested(path)) ?? (await load(path))
+}
 
-    const check = (binding) => require(binding).properties?.async === true
-    const asyncBinding = options.bindings.find(check)
+/**
+ * What the digest holds for a component of an extension's own, by the directory it is in.
+ *
+ * An extension ships its components in `components/` beside its manifest and nowhere else, so
+ * that is the whole of what is looked for: anything else — an application's own component, a
+ * fixture in a workspace — is read from its sources.
+ *
+ * @param {string} path
+ * @returns {Promise<object | undefined>}
+ */
+async function digested(path) {
+  const directory = dirname(path)
 
-    if (asyncBinding === undefined) throw new Error('Bindings override must contain at least one async binding')
+  if (basename(directory) !== COMPONENTS) return undefined
 
-    if ('events' in manifest)
-      for (const event of Object.values(manifest.events)) event.binding = asyncBinding
+  const root = dirname(directory)
+  const manifest = join(root, MANIFEST)
 
-    if ('receivers' in manifest)
-      for (const receiver of Object.values(manifest.receivers))
-        if (receiver.source === undefined) receiver.binding = asyncBinding
-  }
+  if (!existsSync(manifest)) return undefined
 
-  if (manifest.extensions === undefined) manifest.extensions = {}
+  const { name } = JSON.parse(readFileSync(manifest, 'utf8'))
 
-  // add `null` manifests
-  for (const extension of options.extensions) {
-    if (!(extension in manifest.extensions)) manifest.extensions[extension] = null
-  }
+  // the digest is of what Toa ships, and a package it does not define has none
+  if (name === undefined || !name.startsWith(SCOPE)) return undefined
 
-  if ('storage' in options && 'entity' in manifest) manifest.entity.storage = options.storage
+  const { module } = await definition(name)
+  const { labels, manifests } = module.components?.() ?? {}
 
-  manifest.locator = new Locator(manifest.name, manifest.namespace)
+  if (manifests === undefined) return undefined
 
-  return manifest
-}
+  // a chart names a component's workload the way the digest labels it
+  const index = labels.indexOf(basename(path).replace('.', '-'))
 
-const DEFAULTS = {
-  extensions: ['@toa.io/extensions.sampling']
+  return index === -1 ? undefined : revive(manifests[index], path)
 }
 
-exports.manifest = manifest
+const SCOPE = '@toa.io/'
+
+const COMPONENTS = 'components'
+
+const MANIFEST = 'package.json'
+
+const DEFAULTS = {}

package/src/manifest.test.js

@@ -1,12 +1,33 @@
-'use strict'
+import { it, mock } from 'node:test'
+import assert from 'node:assert/strict'
 
-const { generate } = require('randomstring')
+import { mkdtemp, mkdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { generate } from 'randomstring'
 
-jest.mock('@toa.io/norm', () => ({
-  component: () => mockComponent()
-}))
+const NORMALIZED = 'manifest.toa.json'
 
-const { manifest } = require('./manifest')
+let normalised = 0
+
+const digest = { labels: ['identity-basic'], manifests: [{ name: 'basic', namespace: 'identity' }] }
+
+mock.module('@toa.io/norm', {
+  namedExports: {
+    component: () => {
+      normalised++
+
+      return mockComponent()
+    },
+    definition: async (reference) => ({
+      module: reference === '@toa.io/extensions.exposition' ? { components: () => digest } : {}
+    }),
+    revive: (declared, path) => ({ ...declared, path }),
+    NORMALIZED
+  }
+})
+
+const { manifest } = await import('./manifest.js')
 
 const path = generate()
 
@@ -15,9 +36,65 @@ it('should not modify options', async () => {
 
   await manifest(path, options)
 
-  expect(options.extensions.length).toStrictEqual(2)
+  assert.deepStrictEqual(options.extensions.length, 2)
+})
+
+it('should normalize a component the build did not', async () => {
+  const before = normalised
+
+  await manifest(path)
+
+  assert.strictEqual(normalised, before + 1)
+})
+
+it('should read what the build wrote, and not normalize', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'toa-manifest-test'))
+  const declared = { name: 'tasks', namespace: 'todos', operations: { compute: {} } }
+
+  await writeFile(join(root, NORMALIZED), JSON.stringify(declared))
+
+  const before = normalised
+  const read = await manifest(root)
+
+  assert.strictEqual(normalised, before, 'the component was normalized')
+  assert.strictEqual(read.path, root)
+  assert.deepStrictEqual(read.operations, declared.operations)
+  assert.strictEqual(read.locator.id, 'todos.tasks')
+})
+
+it('should read the digest for a component an extension ships, and not normalize', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'toa-manifest-test'))
+  const component = join(root, 'components', 'identity.basic')
+
+  await mkdir(component, { recursive: true })
+  await writeFile(
+    join(root, 'package.json'),
+    JSON.stringify({ name: '@toa.io/extensions.exposition' })
+  )
+
+  const before = normalised
+  const read = await manifest(component)
+
+  assert.strictEqual(normalised, before, 'the component was normalized')
+  assert.strictEqual(read.path, component)
+  assert.strictEqual(read.locator.id, 'identity.basic')
+})
+
+it('should normalize a component that only looks like one an extension ships', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'toa-manifest-test'))
+  const component = join(root, 'components', 'identity.basic')
+
+  await mkdir(component, { recursive: true })
+  // an application's own package, which the digest knows nothing about
+  await writeFile(join(root, 'package.json'), JSON.stringify({ name: 'acme' }))
+
+  const before = normalised
+
+  await manifest(component)
+
+  assert.strictEqual(normalised, before + 1)
 })
 
-function mockComponent () {
+function mockComponent() {
   return { name: generate(), namespace: generate() }
 }

package/src/operation.js

@@ -1,18 +1,31 @@
-'use strict'
+import {
+  Transition,
+  Observation,
+  Assignment,
+  Operation,
+  Query,
+  Effect,
+  Unmanaged
+} from '@toa.io/core'
 
-const { Transition, Observation, Assignment, Operation, Query } = require('@toa.io/core')
+import * as boot from './index.js'
 
-const boot = require('./index')
-
-const operation = (manifest, endpoint, definition, context, scope) => {
-  const cascade = boot.cascade(manifest, endpoint, definition, context)
-  const reply = boot.contract.reply(definition.output, definition.error)
+export async function operation(
+  manifest,
+  endpoint,
+  definition,
+  context,
+  scope,
+  preflight
+) {
+  const cascade = await boot.cascade(manifest, endpoint, definition, context, preflight)
+  const reply = boot.contract.reply(definition.output, definition.errors)
   const input = definition.input
   const request = boot.contract.request({ input }, manifest.entity)
   const contracts = { reply, request }
-  const query = manifest.entity === undefined
-    ? undefined
-    : new Query(manifest.entity.schema.properties)
+
+  const query =
+    manifest.entity === undefined ? undefined : new Query(manifest.entity.properties)
 
   const Type = TYPES[definition.type]
 
@@ -24,7 +37,6 @@ const TYPES = {
   observation: Observation,
   assignment: Assignment,
   computation: Operation,
-  effect: Operation
+  effect: Effect,
+  unmanaged: Unmanaged
 }
-
-exports.operation = operation

package/src/outbox.js

@@ -0,0 +1,22 @@
+import { Outbox } from '@toa.io/core'
+
+import * as boot from './index.js'
+
+/**
+ * A component with nothing to publish to has no outbox — the static check that keeps the
+ * common case free of a transaction. Its own events are one destination; an extension may
+ * contribute others, and a component that declares no event at all has an outbox where one of
+ * those is there.
+ *
+ * @param {toa.norm.Component} manifest
+ * @param {import('@toa.io/core/types').storages.Storage} [storage]
+ * @param {import('@toa.io/core').Emission} [emission]
+ * @param {import('@toa.io/core/types').outbox.Destination[]} [contributed]
+ */
+export const outbox = (manifest, storage, emission, contributed = []) => {
+  const destinations = emission === undefined ? contributed : [emission, ...contributed]
+
+  if (destinations.length === 0) return
+
+  return new Outbox(destinations, storage, boot.atomicity(manifest.locator.id), {})
+}

package/src/rc.js

@@ -0,0 +1,5 @@
+import * as boot from './index.js'
+
+export async function rc(manifest, context) {
+  return boot.bridge.rc(manifest.bridge, manifest.path, context)
+}