@toa.io/norm 1.0.0-alpha.32 → 1.0.0-alpha.320

package/src/.context/.dependencies/extensions.js

@@ -1,12 +1,34 @@
-'use strict'
+import { Locator } from '@toa.io/core'
+import { converge } from '../converge.js'
+import { component as load } from '../../component.js'
+import { definition } from '../../definition.js'
 
-const extensions = async (context) => {
+export const extensions = async (context) => {
   const extensions = {}
   const components = context.components?.slice() ?? []
-  const extracted = await extractExtensionComponents(components, extensions)
+
+  /** the components each extension brings, by reference
+   *  @type {Map<string, toa.norm.Component[]>} */
+  const contributed = new Map()
+
+  // an extension a composition runs may be referenced by no component of this context,
+  // and its own components must be extracted all the same
+  const declared = await extractDeclaredServices(context, extensions, contributed)
+
+  const extracted = declared.concat(
+    await extractExtensionComponents(
+      components.concat(declared),
+      extensions,
+      contributed,
+      context.annotations
+    )
+  )
 
   components.push(...extracted)
 
+  // after the extraction, because what an extension ships converges like anything else
+  converge(context, components)
+
   for (const component of components) {
     if (component.extensions === undefined) continue
 
@@ -17,12 +39,33 @@ const extensions = async (context) => {
     }
   }
 
-  return { extensions, components: extracted }
+  return { extensions, components: extracted, contributed }
 }
 
-async function extractExtensionComponents (components, extensions) {
-  const { component: load } = require('../../component')
+async function extractDeclaredServices(context, extensions, contributed) {
+  const extracted = []
+
+  for (const composition of context.compositions ?? [])
+    for (const reference of composition.services ?? []) {
+      if (reference in extensions) continue
 
+      try {
+        extracted.push(
+          ...(await extract(reference, extensions, contributed, context.annotations))
+        )
+      } catch (e) {
+        throw new Error(
+          `Composition '${composition.name}' lists '${reference}', ` +
+            `which cannot be resolved: ${e.message}`,
+          { cause: e }
+        )
+      }
+    }
+
+  return extracted
+}
+
+async function extractExtensionComponents(components, extensions, contributed, annotations) {
   const extracted = []
 
   for (const component of components) {
@@ -31,26 +74,56 @@ async function extractExtensionComponents (components, extensions) {
     for (const reference of Object.keys(component.extensions)) {
       if (reference in extensions) continue
 
-      extensions[reference] = []
+      extracted.push(...(await extract(reference, extensions, contributed, annotations)))
+    }
+  }
+
+  if (extracted.length === 0) return extracted
 
-      const mod = require(reference)
+  const deeper = await extractExtensionComponents(
+    extracted,
+    extensions,
+    contributed,
+    annotations
+  )
 
-      if (mod.components === undefined) continue
+  return extracted.concat(deeper)
+}
 
-      for (const path of mod.components().paths) {
-        const component = await load(path)
+/**
+ * The components an extension contributes, if it contributes any.
+ *
+ * @param {string} reference
+ * @param {object} extensions
+ * @param {Map<string, toa.norm.Component[]>} contributed
+ * @param {object} [annotations]
+ * @returns {Promise<Array<toa.norm.Component>>}
+ */
+async function extract(reference, extensions, contributed, annotations) {
+  extensions[reference] = []
 
-        extracted.push(component)
-      }
-    }
-  }
+  const { name, module: mod } = await definition(reference)
 
-  if (extracted.length === 0)
-    return extracted
+  if (mod.components === undefined) return []
 
-  const deeper = await extractExtensionComponents(extracted, extensions)
+  // the annotation decides whether an extension contributes components at all
+  const annotation = annotations?.[name]
+  const { manifests, paths } = mod.components(annotation)
 
-  return extracted.concat(deeper)
+  // a definition carries the manifests, read where the extension is not installed;
+  // an entry names the directories, where it is
+  const extracted = manifests === undefined ? [] : manifests.map(revive)
+
+  if (manifests === undefined) for (const path of paths) extracted.push(await load(path))
+
+  contributed.set(reference, extracted)
+
+  return extracted
 }
 
-exports.extensions = extensions
+/** A manifest as a digest carries it, which is one norm read, without the locator. */
+function revive(manifest) {
+  manifest.locator = new Locator(manifest.name, manifest.namespace)
+
+  return manifest
+}

package/src/.context/.dependencies/index.js

@@ -1,9 +1,3 @@
-'use strict'
-
-const { connectors } = require('./connectors')
-const { extensions } = require('./extensions')
-const { resolve } = require('./resolve')
-
-exports.connectors = connectors
-exports.extensions = extensions
-exports.resolve = resolve
+export { connectors } from './connectors.js'
+export { extensions } from './extensions.js'
+export { resolve } from './resolve.js'

package/src/.context/.dependencies/resolve.js

@@ -1,13 +1,10 @@
-'use strict'
+import { definition } from '../../definition.js'
 
-const { load } = require('./load')
-
-const resolve = (references, annotations) => {
+export const resolve = async (references, annotations = {}, context = {}) => {
   const dependencies = {}
 
   for (const [dependency, components] of Object.entries(references)) {
-    const { metadata, module } = load(dependency)
-    const id = metadata.name
+    const { name: id, module } = await definition(dependency)
 
     const instances = components.map((component) => ({
       locator: component.locator,
@@ -22,9 +19,49 @@ const resolve = (references, annotations) => {
     if (annotation !== undefined && module.annotation !== undefined) {
       annotations[id] = module.annotation(annotation, instances)
     }
+
+    // what a declaration costs to install, read from the definition rather than from the
+    // package: a deploy installs it, and nothing that declares nothing carries it. A component
+    // is asked for its own instance; a composition that runs the package's service is asked
+    // with none, because what a service brings is not a component's to declare
+    if (module.installs !== undefined) {
+      for (const instance of instances)
+        Object.assign(
+          (instance.component.packages ??= {}),
+          module.installs(instance, annotations[id])
+        )
+
+      const service = module.installs(undefined, annotations[id])
+
+      // mono runs every service in one process, so it takes every service's packages
+      Object.assign((context.packages ??= {}), service)
+
+      for (const composition of context.compositions ?? [])
+        if (composition.services?.includes(dependency) === true)
+          Object.assign((composition.packages ??= {}), service)
+    }
+  }
+
+  for (const dependency of Object.keys(annotations)) {
+    if (dependency in dependencies) continue
+
+    // an annotation may be keyed by a dependency id rather than by a module reference
+    const module = await optional(dependency)
+
+    if (module?.standalone === true) dependencies[dependency] = []
   }
 
   return dependencies
 }
 
-exports.resolve = resolve
+/**
+ * @param {string} reference
+ * @returns {object | null}
+ */
+async function optional(reference) {
+  try {
+    return (await definition(reference)).module
+  } catch {
+    return null
+  }
+}

package/src/.context/complete.js

@@ -1,11 +1,9 @@
-'use strict'
-
 /**
  * Completes missing compositions with unused components
  * @param {toa.norm.Context} context
  * @returns {void}
  */
-const complete = (context) => {
+export const complete = (context) => {
   /** @type {Set<string>} */
   const composed = new Set()
 
@@ -29,5 +27,3 @@ const complete = (context) => {
     context.compositions.push({ name, components: [component] })
   }
 }
-
-exports.complete = complete

package/src/.context/converge.js

@@ -0,0 +1,31 @@
+/**
+ * A context that declares convergence converges every component that stores anything, and no
+ * manifest says so. An extension is loaded, deployed and hooked because a component's
+ * `extensions` names it, so this is where they come to name it.
+ *
+ * **Including the components an extension ships**, which is why this runs where they are
+ * known rather than over what the context declares: an application deployed as two regions
+ * whose identity does not converge is one where a user registered in the first does not
+ * exist in the second.
+ *
+ * There is nothing per-component to normalize and nothing to opt out of: a region is
+ * infrastructure, and what a component stores is not its business. What is genuinely owned by
+ * one region — which delayed calls this one makes — is said where that is decided, in
+ * `cadence.regions`, and not by holding the records back.
+ *
+ * @param {toa.norm.Context} context
+ * @param {toa.norm.Component[]} components every component the context deploys
+ * @returns {void}
+ */
+export const converge = (context, components) => {
+  if (context.annotations?.[REFERENCE] === undefined) return
+
+  for (const component of components) {
+    if (component.entity === undefined) continue
+
+    component.extensions ??= {}
+    component.extensions[REFERENCE] ??= null
+  }
+}
+
+const REFERENCE = '@toa.io/extensions.convergence'

package/src/.context/dependencies.js

@@ -1,13 +1,50 @@
-'use strict'
+import { connectors, extensions, resolve } from './.dependencies/index.js'
 
-const { connectors, extensions, resolve } = require('./.dependencies')
+export const dependencies = async (context) => {
+  const { extensions: e, components, contributed } = await extensions(context)
+
+  unmanaged(context, contributed)
 
-const dependencies = async (context) => {
-  const { extensions: e, components } = await extensions(context)
   const c = connectors(context, components)
   const references = { ...c, ...e }
 
-  return resolve(references, context.annotations)
+  return resolve(references, context.annotations, context)
 }
 
-exports.dependencies = dependencies
+/**
+ * Marks as evicted what only evicted components require: the components an extension brings,
+ * where nothing a deployment carries references the extension and no composition runs it. A
+ * storage or a binding needs no mark of its own — its instances are components, and a
+ * deployment reads theirs.
+ *
+ * @param {toa.norm.Context} context
+ * @param {Map<string, toa.norm.Component[]>} contributed
+ * @returns {void}
+ */
+function unmanaged(context, contributed) {
+  const components = context.components ?? []
+
+  if (!components.some((component) => component.evicted === true)) return
+
+  const required = new Set()
+  const pending = components.filter((component) => component.evicted !== true)
+
+  // what a composition runs is deployed for being listed, whoever references it
+  for (const composition of context.compositions ?? [])
+    for (const reference of composition.services ?? [])
+      pending.push(...(contributed.get(reference) ?? []))
+
+  while (pending.length > 0) {
+    const component = pending.pop()
+
+    if (required.has(component)) continue
+
+    required.add(component)
+
+    for (const reference of Object.keys(component.extensions ?? {}))
+      pending.push(...(contributed.get(reference) ?? []))
+  }
+
+  for (const brought of contributed.values())
+    for (const component of brought) if (!required.has(component)) component.evicted = true
+}

package/src/.context/dereference.js

@@ -1,16 +1,23 @@
-'use strict'
-
 /**
  * Resolves component IDs within compositions with Component objects
  * @param {toa.norm.Context} context
  * @returns {void}
  */
-const dereference = (context) => {
+export const dereference = (context) => {
   const components = map(context.components)
 
   if (context.compositions !== undefined) {
     for (const composition of context.compositions) {
-      composition.components = composition.components.map((id) => components[id])
+      composition.components = composition.components.map((id) => {
+        const component = components[id]
+
+        if (component === undefined)
+          throw new Error(
+            `Composition '${composition.name}' lists an unknown component '${id}'.`
+          )
+
+        return component
+      })
     }
   }
 }
@@ -27,5 +34,3 @@ const map = (components) => {
 
   return map
 }
-
-exports.dereference = dereference

package/src/.context/evict.js

@@ -0,0 +1,38 @@
+/**
+ * Marks what the context evicts. An evicted component stays in the context like any other — it
+ * is called, its types are written, what it receives is published — and only a deployment
+ * leaves it out, because something else deploys it. What only evicted components require is
+ * marked once the extensions are extracted, by `dependencies`.
+ *
+ * An evicted service is taken off the compositions that list it, so that none of them runs it.
+ *
+ * @param {toa.norm.Context} context
+ * @returns {void}
+ */
+export const evict = (context) => {
+  if (context.evicted === undefined) return
+
+  const components = new Set(context.evicted.components ?? [])
+  const services = new Set(context.evicted.services ?? [])
+
+  if (components.size > 0) {
+    const present = new Set(context.components.map((component) => component.locator.id))
+
+    for (const id of components)
+      if (!present.has(id))
+        throw new Error(`'evicted' names an unknown component '${id}'.`)
+
+    for (const component of context.components)
+      if (components.has(component.locator.id)) component.evicted = true
+  }
+
+  if (context.compositions === undefined) return
+
+  for (const composition of context.compositions) {
+    if (composition.services === undefined) continue
+
+    composition.services = composition.services.filter((reference) => !services.has(reference))
+
+    if (composition.services.length === 0) delete composition.services
+  }
+}

package/src/.context/expand.js

@@ -1,13 +1,18 @@
-'use strict'
-
-const shortcuts = require('../shortcuts')
+import * as shortcuts from '../shortcuts.js'
 
 /**
  * @param {toa.norm.context.Declaration | object} context
  */
-const expand = (context) => {
+export const expand = (context) => {
   shortcuts.recognize(shortcuts.SHORTCUTS, context, 'annotations')
   shortcuts.recognize(shortcuts.SHORTCUTS, context.annotations)
-}
 
-exports.expand = expand
+  // a composition names a service the way a manifest names an extension, and everything
+  // downstream matches it against a dependency, which is keyed by package reference
+  for (const composition of context.compositions ?? [])
+    if (composition.services !== undefined)
+      composition.services = composition.services.map(shortcuts.resolve)
+
+  if (context.evicted?.services !== undefined)
+    context.evicted.services = context.evicted.services.map(shortcuts.resolve)
+}

package/src/.context/index.js

@@ -1,15 +1,8 @@
-'use strict'
-
-const { complete } = require('./complete')
-const { dependencies } = require('./dependencies')
-const { dereference } = require('./dereference')
-const { expand } = require('./expand')
-const { normalize } = require('./normalize')
-const { validate } = require('./validate')
-
-exports.complete = complete
-exports.dependencies = dependencies
-exports.dereference = dereference
-exports.expand = expand
-exports.normalize = normalize
-exports.validate = validate
+export { complete } from './complete.js'
+export { converge } from './converge.js'
+export { dependencies } from './dependencies.js'
+export { dereference } from './dereference.js'
+export { evict } from './evict.js'
+export { expand } from './expand.js'
+export { normalize } from './normalize.js'
+export { validate } from './validate.js'

package/src/.context/normalize.js

@@ -1,19 +1,21 @@
-'use strict'
+import * as definitions from '@toa.io/definitions'
 
 /**
  * @param {toa.norm.context.Declaration | Object} context
  */
-const normalize = (context) => {
-  const runtime = require('@toa.io/runtime')
-
-  if (context.runtime === undefined) context.runtime = { version: runtime.version }
+export const normalize = (context) => {
+  if (context.runtime === undefined) context.runtime = { version: definitions.version }
   if (typeof context.runtime === 'string') context.runtime = { version: context.runtime }
 
   if (context.runtime.version === undefined || context.runtime.version === '.') {
-    context.runtime.version = runtime.version
+    context.runtime.version = definitions.version
   }
 
   if (typeof context.registry === 'string') context.registry = { base: context.registry }
+
+  // what an image is built for, where the Context does not say; `~` says the runner's own
+  if (context.registry !== undefined && context.registry.platforms === undefined)
+    context.registry.platforms = PLATFORMS
 }
 
-exports.normalize = normalize
+const PLATFORMS = ['linux/amd64', 'linux/arm/v7', 'linux/arm64']