@toa.io/boot 1.0.0-alpha.32 → 1.0.0-alpha.321

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/map.js

@@ -0,0 +1,108 @@
+import assert from 'node:assert'
+import { gunzipSync } from 'node:zlib'
+import { readFile } from 'node:fs/promises'
+import * as core from '@toa.io/core'
+
+/**
+ * What this process was given about the components it calls: the contract of the version each of
+ * them runs.
+ *
+ * Held as the file it was given rather than as what the file said, and read at every call for
+ * one: a deployment rewrites it under a running process, and a process may first call a peer
+ * long after that peer was replaced. A contract is read once per peer, so this is a read per
+ * peer.
+ *
+ * @type {string | Record<string, import('@toa.io/core').Contract> | undefined}
+ */
+let source
+
+/**
+ * What this process composes, which it knows from the sources it booted from. What the map
+ * states wins: two compositions of one locator run in one process while a rollout is staged,
+ * and the map is what says which of them a caller is held to.
+ *
+ * @type {Record<string, import('@toa.io/core').Contract>}
+ */
+let composed = {}
+
+/**
+ * @param {string | Record<string, import('@toa.io/core').Contract> | undefined} value the file, or the map itself
+ */
+export const use = (value) => {
+  source = value
+}
+
+/**
+ * Forgets what this process composed, which is what a test does between one composition and
+ * the next: a component that is no longer composed is one nothing states.
+ */
+export const forget = () => {
+  composed = {}
+}
+
+/**
+ * What this process composes, stated by the boot that composes it — and held to the map it was
+ * given a file of, which one `toa deploy` writes with the images it deploys: the two differ only
+ * where the map was not written again. What a test states instead is what that test means, and
+ * is not checked.
+ *
+ * @param {toa.norm.Component[]} manifests
+ * @returns {Promise<void>}
+ */
+export const compose = async (manifests) => {
+  const file = typeof source === 'string' ? await read(source) : undefined
+
+  for (const manifest of manifests) {
+    const stated = file?.[manifest.locator.id]
+
+    assert.ok(
+      stated === undefined || stated.version === manifest.version,
+      `'${manifest.locator.id}' is composed at a version the component map does not state. ` +
+        'Run `toa map`.'
+    )
+
+    composed[manifest.locator.id] = core.contract.component(manifest)
+  }
+}
+
+/**
+ * What a component provides: what the map states of it, or what this process composes.
+ *
+ * @param {string} id
+ * @returns {Promise<import('@toa.io/core').Contract | undefined>}
+ */
+export const contract = async (id) => {
+  if (source === undefined) return composed[id]
+  if (typeof source !== 'string') return source[id] ?? composed[id]
+
+  return (await read(source))[id] ?? composed[id]
+}
+
+/**
+ * A map is read gzipped where it is deployed and plain where it is not, so what it is is told by
+ * its first two bytes rather than by its name.
+ *
+ * @param {string} path
+ * @returns {Promise<Record<string, import('@toa.io/core').Contract>>}
+ */
+async function read(path) {
+  let contents
+
+  try {
+    contents = await readFile(path)
+  } catch (cause) {
+    throw new Error(`Cannot read the component map '${path}'`, { cause })
+  }
+
+  try {
+    if (contents[0] === 0x1f && contents[1] === 0x8b) contents = gunzipSync(contents)
+  } catch (cause) {
+    throw new Error(`The component map '${path}' is not readable gzip`, { cause })
+  }
+
+  try {
+    return JSON.parse(contents.toString('utf8'))
+  } catch (cause) {
+    throw new Error(`The component map '${path}' is not JSON`, { cause })
+  }
+}

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 request = boot.contract.request({ input, stream: definition.stream }, 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)
+}

package/src/receivers.js

@@ -1,34 +1,52 @@
-'use strict'
+import assert from 'node:assert'
+import { Receiver, Locator } from '@toa.io/core'
 
-const { Receiver, Locator } = 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 receivers = async (manifest, runtime) => {
+export const receivers = async (manifest, component) => {
   if (manifest.receivers === undefined) return []
 
   const receivers = []
-  const local = await boot.remote(manifest.locator, manifest)
+  const local = await boot.remote(manifest.locator, undefined, { contract: manifest })
 
   for (const [label, definition] of Object.entries(manifest.receivers)) {
-    const bridge = definition.bridge !== undefined ? boot.bridge.receiver(definition.bridge, manifest.path, label) : undefined
-    const receiver = new Receiver(definition, local, bridge)
-    const decorator = extensions.receiver(receiver, manifest.locator)
-
     const locator = Locator.parse(label)
-    const transport = definition.binding ?? await resolveBinding(locator, label)
     const source = definition.source ? Locator.parse(definition.source) : locator
-    const binding = boot.bindings.receive(transport, source, label, manifest.locator.id, decorator)
+    const event = label.split('.').pop()
+    const destination = `${source.id}.${event}`
+
+    // the origin of the calls this receiver makes to its local operation
+    const origin = { namespace: source.namespace, component: source.name, event }
+
+    const bridge =
+      definition.bridge !== undefined
+        ? await boot.bridge.receiver(definition.bridge, manifest.path, label)
+        : undefined
+    const receiver = new Receiver(
+      { ...definition, label, destination, origin },
+      local,
+      bridge
+    )
+    const decorator = extensions.receiver(receiver, manifest.locator)
 
-    binding.depends(runtime)
+    const transport = definition.binding ?? (await resolveBinding(locator, label))
+    const binding = await boot.bindings.receive(
+      transport,
+      source,
+      label,
+      manifest.locator.id,
+      decorator
+    )
+
+    binding.depends(component)
     receivers.push(binding)
   }
 
   return receivers
 }
 
-async function receive (label, group, callback) {
+export async function receive(label, group, callback) {
   if (callback === undefined) {
     callback = group
     group = undefined
@@ -37,21 +55,33 @@ async function receive (label, group, callback) {
   const locator = Locator.parse(label)
   const transport = await resolveBinding(locator, label)
 
-  return boot.bindings.receive(transport, locator, label, group, callback)
+  return await boot.bindings.receive(transport, locator, label, group, callback)
 }
 
 /**
- * @param {toa.core.Locator} locator
+ * Which transport carries an event, as the component whose event it is declares it.
+ *
+ * @param {import('@toa.io/core').Locator} locator
  * @param {string} label
  * @return {Promise<string>}
  */
-async function resolveBinding (locator, label) {
+async function resolveBinding(locator, label) {
   const event = label.split('.').pop()
-  const discovery = await boot.discovery.discovery()
-  const { events } = await discovery.lookup(locator)
+  const contract = await boot.map.contract(locator.id)
+
+  assert.ok(
+    contract !== undefined,
+    `The component map states nothing of '${locator.id}', whose event '${label}' receives. ` +
+      'Run `toa map`.'
+  )
+
+  const { events, version } = contract
+
+  assert.ok(
+    events?.[event] !== undefined,
+    `'${locator.id}'${version === undefined ? '' : ` at version ${version}`} declares no ` +
+      `event '${event}', which is what '${label}' receives`
+  )
 
   return events[event].binding
 }
-
-exports.receivers = receivers
-exports.receive = receive

package/src/regional.js

@@ -0,0 +1,18 @@
+import { Regional } from '@toa.io/core'
+
+/**
+ * Gives every destination that carries a change to other regions the others that write to
+ * something each region keeps for itself. Neither knows what the other is: the carrier is given
+ * what they export, and hands back what arrives.
+ *
+ * @param {import('@toa.io/core/types').outbox.Destination[]} destinations
+ * @returns {void}
+ */
+export const regional = (destinations) => {
+  const regionals = destinations.filter((destination) => Regional.is(destination))
+
+  if (regionals.length === 0) return
+
+  for (const destination of destinations)
+    if (destination.carries === true) destination.regional = new Regional(regionals)
+}

package/src/regional.test.js

@@ -0,0 +1,28 @@
+import { it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { regional } from './regional.js'
+
+const regionalDestination = (name) => ({
+  name,
+  export: async () => [name],
+  import: async () => undefined
+})
+
+it('should give a carrier the regional destinations', async () => {
+  const carrier = { name: 'convergence', carries: true }
+  const events = { name: 'events' }
+
+  regional([events, carrier, regionalDestination('realtime')])
+
+  assert.deepEqual(await carrier.regional.export({}), { realtime: ['realtime'] })
+  assert.equal('regional' in events, false)
+})
+
+it('should give a carrier nothing where no destination is regional', () => {
+  const carrier = { name: 'convergence', carries: true }
+
+  regional([carrier, { name: 'events' }])
+
+  assert.equal(carrier.regional, undefined)
+})

package/src/remote.js

@@ -1,25 +1,44 @@
-'use strict'
-
-const { Remote } = require('@toa.io/core')
-const { remap } = require('@toa.io/generic')
-
-const boot = require('./index')
-
-const remote = async (locator, manifest = undefined) => {
-  const discovery = await boot.discovery.discovery()
-
-  if (manifest === undefined) manifest = await discovery.lookup(locator)
-
-  const calls = manifest.operations === undefined
-    ? {}
-    : remap(manifest.operations, (definition, endpoint) => boot.call(locator, endpoint, definition, manifest.entity))
-
-  const remote = new Remote(locator, calls)
+import { Remote, contract as coreContract, exceptions } from '@toa.io/core'
+import { remap } from '@toa.io/generic'
+
+import * as boot from './index.js'
+
+/**
+ * @param {import('@toa.io/core').Locator} locator
+ * @param {import('@toa.io/core/types').Source} [source] the origin stamped on every call made through this remote
+ * @param {{ contract?: import('@toa.io/core').Contract }} [options]
+ *   `contract` is what the caller already has — a manifest of its own is one, and so is what a
+ *   tenant announced — and absent it, what the map this process was given states.
+ */
+export const remote = async (locator, source, options = {}) => {
+  const stated = options.contract ?? (await boot.map.contract(locator.id))
+
+  if (stated === undefined)
+    throw new exceptions.UnstatedException(
+      `Cannot call '${locator.id}': the component map states nothing of it. Run \`toa map\`.`
+    )
+
+  // a contract states once, or not at all, what the runtime gives every component; the calls
+  // are made from the whole of it
+  const contract = coreContract.restore(stated)
+
+  // a call binds its consumers, which are loaded rather than required
+  const calls =
+    contract.operations === undefined
+      ? {}
+      : await settle(
+          remap(contract.operations, (definition, endpoint) =>
+            boot.call(locator, endpoint, definition, contract.entity, source)
+          )
+        )
+
+  return new Remote(locator, calls)
+}
 
-  // ensure discovery shutdown
-  remote.depends(discovery)
+/** An object whose values are promises, as an object of what they resolve to. */
+async function settle(object) {
+  const entries = Object.entries(object)
+  const values = await Promise.all(entries.map(([, promise]) => promise))
 
-  return remote
+  return Object.fromEntries(entries.map(([key], index) => [key, values[index]]))
 }
-
-exports.remote = remote

package/src/rendering.js

@@ -0,0 +1,50 @@
+import { Event, Rendering } from '@toa.io/core'
+
+import * as boot from './index.js'
+
+/**
+ * Gives every destination that names the events it renders a `Rendering` of them, made with the
+ * component's own bridges. Every event of the manifest may be named, including those nothing
+ * consumes and are therefore not published: a destination writes somewhere of its own.
+ *
+ * @param {toa.norm.Component} manifest
+ * @param {import('@toa.io/core/types').outbox.Destination[]} destinations
+ * @param {import('@toa.io/core').Context} context
+ * @returns {Promise<void>}
+ */
+export const rendering = async (manifest, destinations, context) => {
+  for (const destination of destinations) {
+    if (destination.renders === undefined) continue
+
+    const events = new Map()
+
+    for (const label of destination.renders) {
+      const definition = manifest.events?.[label]
+
+      if (definition === undefined)
+        throw new Error(
+          `Component '${manifest.locator.id}' has no event '${label}' to render for ` +
+            `'${destination.name}'`
+        )
+
+      const bridge = await boot.bridge.event(
+        definition.bridge,
+        definition.path,
+        label,
+        context
+      )
+      const event = new Event(
+        { ...definition, label: `${manifest.locator.id}.${label}` },
+        null,
+        bridge
+      )
+
+      events.set(label, event)
+    }
+
+    const rendering = new Rendering(events)
+
+    destination.rendering = rendering
+    destination.depends(rendering)
+  }
+}

package/src/span.js

@@ -0,0 +1,19 @@
+import { console, traces } from 'openspan'
+import { environment } from '@toa.io/generic'
+
+const enabled = environment.get('TOA_BOOT_TRACE') === '1'
+
+// Tracing is off until an exporter is configured, and the CLI opens its own span before
+// any extension gets to configure one — so asking for a boot trace turns the console
+// exporter on here. Extensions keep it: see `development()` in the telemetry factory.
+if (enabled) traces({ exporters: { console: {} } })
+
+/**
+ * Creates a span if boot tracing is enabled (TOA_BOOT_TRACE=1), otherwise just runs the task
+ *
+ * @param {string | object} options
+ * @param {() => Promise<any>} task
+ * @returns {Promise<any>}
+ */
+export const span = async (options, task) =>
+  enabled ? console.span(options, task) : task()

package/src/storage.js

@@ -1,26 +1,60 @@
-'use strict'
-
-const { join } = require('node:path')
-const extensions = require('./extensions')
-
-const storage = (manifest) => {
+import { createRequire } from 'node:module'
+import { pathToFileURL } from 'node:url'
+import * as extensions from './extensions/index.js'
+
+// import.meta.resolve takes no paths, and the connector is resolved against the
+// component that names it
+const require = createRequire(import.meta.url)
+
+/**
+ * @param {toa.norm.Component} manifest
+ * @param {boolean} outbox whether this component publishes anything, and so needs a place to
+ *   commit it with the entity
+ * @param {boolean} inbox whether any of its operations declares `once`, and so needs a place to
+ *   record the call it commits
+ */
+export const storage = async (manifest, outbox, inbox) => {
   if (manifest.entity === undefined) return
 
-  const Factory = load(manifest)
+  const Factory = await load(manifest)
 
-  /** @type {toa.core.storages.Factory} */
+  /** @type {import('@toa.io/core/types').storages.Factory} */
   const factory = new Factory()
-  const storage = factory.storage(manifest.locator, manifest.entity)
-
-  return extensions.storage(storage)
+  const storage = factory.storage(manifest.locator, manifest.entity, { outbox, inbox })
+
+  // a component whose structure nothing will make must not start with the structure it lacks;
+  // what it inherits was written for descendants that store, and one that stores nothing has
+  // nothing to convert
+  const own = manifest.entity.migrations?.some(
+    (migration) => migration.prototype === undefined
+  )
+
+  if (own === true && storage.migrates !== true)
+    throw new Error(
+      `Component '${manifest.locator.id}' declares migrations, ` +
+        `which storage '${manifest.entity.storage}' does not apply`
+    )
+
+  /*
+   * Refused here rather than degraded: a storage that cannot record a call would run every
+   * duplicate of it, which is what declaring `once` asked not to happen. Whether the deployment
+   * can commit one is the storage's own to refuse, once it is connected.
+   */
+  if (inbox && storage.claims !== true)
+    throw new Error(
+      `Component '${manifest.locator.id}' declares 'once', ` +
+        `which storage '${manifest.entity.storage}' does not provide`
+    )
+
+  return extensions.storage(storage, manifest.locator)
 }
 
-function load (component) {
+async function load(component) {
   const reference = component.entity.storage
-  const path = require.resolve(reference, { paths: [component.path, __dirname] })
-  const { Factory } = require(path)
+  const path = require.resolve(reference, {
+    paths: [component.path, import.meta.dirname]
+  })
+  const { Factory } = await import(pathToFileURL(path).href)
 
   return Factory
 }
-
-exports.storage = storage