@toa.io/operations 1.0.0-alpha.283 → 1.0.0-alpha.286

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/operations",
-  "version": "1.0.0-alpha.283",
+  "version": "1.0.0-alpha.286",
   "type": "module",
   "description": "Toa Deployment",
   "homepage": "https://toa.io",
@@ -28,11 +28,11 @@
     "test": "echo \"Error: run tests from root\" && exit 1"
   },
   "dependencies": {
-    "@toa.io/generic": "1.0.0-alpha.283",
-    "@toa.io/norm": "1.0.0-alpha.283",
+    "@toa.io/generic": "1.0.0-alpha.286",
+    "@toa.io/norm": "1.0.0-alpha.286",
     "execa": "10.0.1",
     "fs-extra": "11.4.0",
     "js-yaml": "5.4.1"
   },
-  "gitHead": "2f52b023bed0ccb2ecdb2b82fe59fbe38bf282e1"
+  "gitHead": "81f3d0688f17668b902be336d1749cc715edcdb6"
 }

package/readme.md

@@ -38,6 +38,49 @@ registry:
     run: npm i -g @toa.io/runtime --omit=dev
 ```
 
+#### Extension Service Images
+
+`registry.services` says where an extension service's image comes from.
+
+`build`, the default, builds one per service into `registry.base`. Its tag carries the
+runtime version, so every Toa release rebuilds them all.
+
+`published` deploys the image the extension ships and builds nothing:
+
+```yaml
+# context.toa.yaml
+
+registry:
+  services: published
+```
+
+The images are tagged with the runtime version:
+
+```
+ghcr.io/toa-io/extension-exposition-gateway:1.0.0-alpha.285
+ghcr.io/toa-io/extension-realtime-streams:1.0.0-alpha.285
+ghcr.io/toa-io/extension-introspection-explorer:1.0.0-alpha.285
+ghcr.io/toa-io/extension-configuration-values:1.0.0-alpha.285
+```
+
+The cluster pulls them from `ghcr.io` rather than from `registry.base`. They are public and
+`registry.credentials` does not apply; a cluster that cannot reach `ghcr.io` needs `build`.
+
+The field is environment-scoped like the rest:
+
+```yaml
+# context.toa.yaml
+
+registry:
+  base@local: localhost:5000
+  base@production: registry.digitalocean.com/acme
+  services: published
+  services@local: build
+```
+
+An extension that states no image is built whatever this says, as is a service a
+composition runs in its own pod.
+
 #### Build Options
 
 ```yaml

package/src/deployment/.deployment/.describe/compositions.js

@@ -2,15 +2,17 @@ import { addVariables } from './variables.js'
 import { addMounts } from './mounts.js'
 import { fold } from './fold.js'
 
-export function compositions (compositions, dependency) {
+export function compositions(compositions, dependency) {
   for (const composition of compositions) {
-    const claimed = (dependency.services ?? [])
-      .filter((service) => service.workload?.includes(composition.name) === true)
+    const claimed = (dependency.services ?? []).filter(
+      (service) => service.workload?.includes(composition.name) === true
+    )
 
     // a service brings components of its own — the identity components inside the gateway —
     // and their variables are keyed by their own labels, not by the composition's
-    const keys = composition.components
-      .concat(...claimed.map((service) => service.components ?? []))
+    const keys = composition.components.concat(
+      ...claimed.map((service) => service.components ?? [])
+    )
 
     addVariables(composition, dependency.variables, keys)
     addMounts(composition, dependency.mounts, keys)

package/src/deployment/.deployment/.describe/events.js

@@ -9,15 +9,16 @@
  * @param {toa.norm.Context} context
  * @param {toa.deployment.Dependency} dependency
  */
-export function events (context, dependency) {
+export function events(context, dependency) {
   const components = deployed(context)
   const consumed = collect(components, context.events, dependency.events)
 
   for (const { locator, events } of components) {
     if (events === undefined) continue
 
-    const labels = Object.keys(events)
-      .filter((label) => consumed.has(locator.id + '.' + label))
+    const labels = Object.keys(events).filter((label) =>
+      consumed.has(locator.id + '.' + label)
+    )
 
     dependency.variables[locator.label] ??= []
 
@@ -33,12 +34,11 @@ export function events (context, dependency) {
  * holds only the former; the latter reach a deployment as instances of what they depend on,
  * which is also how they are given the rest of their variables.
  */
-function deployed (context) {
+function deployed(context) {
   const components = new Map()
 
   for (const instances of Object.values(context.dependencies ?? {}))
-    for (const { component } of instances)
-      components.set(component.locator.id, component)
+    for (const { component } of instances) components.set(component.locator.id, component)
 
   return [...components.values()]
 }
@@ -47,7 +47,7 @@ function deployed (context) {
  * Everything that consumes an event of this context: the receivers of its own components, what
  * a dependency declares it consumes, and what the context says is consumed outside it.
  */
-function collect (components, declared, contributed) {
+function collect(components, declared, contributed) {
   const consumed = new Set(declared ?? [])
 
   for (const label of contributed ?? []) consumed.add(label)

package/src/deployment/.deployment/.describe/fold.js

@@ -10,7 +10,7 @@
  * @param {toa.deployment.dependency.Service[]} services
  * @param {toa.deployment.Dependency} dependency
  */
-export function fold (workload, services, dependency) {
+export function fold(workload, services, dependency) {
   workload.variables ??= []
 
   for (const service of services) {
@@ -21,13 +21,20 @@ export function fold (workload, services, dependency) {
 
     // every declared port is bound by the single process, none is primary
     if (service.port !== undefined)
-      (workload.backends ??= []).push({ port: service.port, path: service.ingress?.path ?? '/' })
+      (workload.backends ??= []).push({
+        port: service.port,
+        path: service.ingress?.path ?? '/'
+      })
 
     if (service.probe !== undefined && service.probe !== false)
       workload.probe = service.probe
   }
 
-  if (workload.probe === undefined && dependency.probe !== undefined && dependency.probe !== false)
+  if (
+    workload.probe === undefined &&
+    dependency.probe !== undefined &&
+    dependency.probe !== false
+  )
     workload.probe = dependency.probe
 
   // the more specific prefix must come first, whatever the controller's tie-break

package/src/deployment/.deployment/.describe/fold.test.js

@@ -10,8 +10,10 @@ it('should collect the ports of every service', () => {
 
   fold(workload, [service('one', { port: 8000 }), service('two', { port: 8002 })], {})
 
-  assert.deepStrictEqual(workload.backends,
-    [{ port: 8000, path: '/' }, { port: 8002, path: '/' }])
+  assert.deepStrictEqual(workload.backends, [
+    { port: 8000, path: '/' },
+    { port: 8002, path: '/' }
+  ])
 })
 
 it('should take the path a service declares', () => {
@@ -25,12 +27,19 @@ it('should take the path a service declares', () => {
 it('should put the more specific prefix first', () => {
   const workload = {}
 
-  fold(workload, [
-    service('one', { port: 8000, ingress: { path: '/' } }),
-    service('two', { port: 8002, ingress: { path: '/explorer' } })
-  ], {})
-
-  assert.deepStrictEqual(workload.backends.map((backend) => backend.path), ['/explorer', '/'])
+  fold(
+    workload,
+    [
+      service('one', { port: 8000, ingress: { path: '/' } }),
+      service('two', { port: 8002, ingress: { path: '/explorer' } })
+    ],
+    {}
+  )
+
+  assert.deepStrictEqual(
+    workload.backends.map((backend) => backend.path),
+    ['/explorer', '/']
+  )
 })
 
 it('should leave a service without a port out of the backends', () => {
@@ -45,12 +54,19 @@ describe('variables', () => {
   it('should take those of every service', () => {
     const workload = {}
 
-    fold(workload, [
-      service('one', { variables: [{ name: 'A', value: '1' }] }),
-      service('two', { variables: [{ name: 'B', value: '2' }] })
-    ], {})
-
-    assert.deepStrictEqual(workload.variables, [{ name: 'A', value: '1' }, { name: 'B', value: '2' }])
+    fold(
+      workload,
+      [
+        service('one', { variables: [{ name: 'A', value: '1' }] }),
+        service('two', { variables: [{ name: 'B', value: '2' }] })
+      ],
+      {}
+    )
+
+    assert.deepStrictEqual(workload.variables, [
+      { name: 'A', value: '1' },
+      { name: 'B', value: '2' }
+    ])
   })
 
   it('should keep the first of a name', () => {

package/src/deployment/.deployment/.describe/mounts.js

@@ -1,16 +1,13 @@
-export function addMounts (composition, mounts, keys = composition.components) {
-  if (mounts === undefined)
-    return
+export function addMounts(composition, mounts, keys = composition.components) {
+  if (mounts === undefined) return
 
   const used = new Set()
 
   for (const [key, mount] of Object.entries(mounts)) {
-    if (key !== 'global' && !keys?.includes(key))
-      continue
+    if (key !== 'global' && !keys?.includes(key)) continue
 
     for (const { name, path, claim } of mount) {
-      if (used.has(name))
-        continue
+      if (used.has(name)) continue
 
       composition.mounts ??= []
       composition.mounts.push({ name, path, claim })

package/src/deployment/.deployment/.describe/resources.js

@@ -8,20 +8,22 @@
  * Deploying without any is a decision rather than an omission, and it is spelled
  * `resources: null` — at either place.
  */
-export function resources (context, values) {
+export function resources(context, values) {
   for (const unit of units(values)) {
     // `null` is an answer and `undefined` is not one, so the fallback reads only the latter
     if (unit.deployment.resources === undefined)
       unit.deployment.resources = context.resources
 
     if (unit.deployment.resources === undefined)
-      throw new Error(`${unit.subject} declares no resources. ` +
-        'Declare them on it or as the context\'s \'resources\', ' +
-        'or \'resources: null\' to deploy it without any.')
+      throw new Error(
+        `${unit.subject} declares no resources. ` +
+          "Declare them on it or as the context's 'resources', " +
+          "or 'resources: null' to deploy it without any."
+      )
   }
 }
 
-function * units (values) {
+function* units(values) {
   if (values.mono !== undefined)
     yield { deployment: values.mono, subject: 'The mono deployment' }
 

package/src/deployment/.deployment/.describe/resources.test.js

@@ -32,22 +32,29 @@ describe('refusal', () => {
   it('should refuse a composition that declares none', () => {
     const values = { compositions: [{ name: 'edge' }] }
 
-    assert.throws(() => resources({}, values),
-      (error) => /^Composition 'edge' declares no resources\./.test(error.message))
+    assert.throws(
+      () => resources({}, values),
+      (error) => /^Composition 'edge' declares no resources\./.test(error.message)
+    )
   })
 
   it('should refuse a service that declares none', () => {
     const values = { services: [{ name: 'exposition-gateway' }] }
 
-    assert.throws(() => resources({}, values),
-      (error) => /^Service 'exposition-gateway' declares no resources\./.test(error.message))
+    assert.throws(
+      () => resources({}, values),
+      (error) =>
+        /^Service 'exposition-gateway' declares no resources\./.test(error.message)
+    )
   })
 
   it('should refuse the mono deployment when it declares none', () => {
     const values = { mono: {} }
 
-    assert.throws(() => resources({}, values),
-      (error) => /^The mono deployment declares no resources\./.test(error.message))
+    assert.throws(
+      () => resources({}, values),
+      (error) => /^The mono deployment declares no resources\./.test(error.message)
+    )
   })
 
   it('should not ask a service a composition runs', () => {

package/src/deployment/.deployment/.describe/services.js

@@ -1,18 +1,16 @@
 import { addVariables } from './variables.js'
 
-export function services (services, variables, probe, ingress) {
+export function services(services, variables, probe, ingress) {
   for (const service of services) {
     // one a composition runs has no deployment of its own to carry them; the composition
     // it runs in states them, and repeating them here is dead weight in the values
     if (service.workload === undefined) addVariables(service, variables)
 
-    if (service.probe === false)
-      delete service.probe
+    if (service.probe === false) delete service.probe
     else if (service.probe === undefined && probe !== undefined && probe !== false)
       service.probe = probe
 
-    if (service.ingress !== undefined)
-      expose(service, ingress)
+    if (service.ingress !== undefined) expose(service, ingress)
   }
 }
 
@@ -21,15 +19,18 @@ export function services (services, variables, probe, ingress) {
  * the context's business, so everything else comes from its `ingress` section.
  * What the service did declare wins.
  */
-function expose (service, ingress = {}) {
+function expose(service, ingress = {}) {
   const declared = Object.fromEntries(
-    Object.entries(service.ingress).filter(([, value]) => value !== undefined))
+    Object.entries(service.ingress).filter(([, value]) => value !== undefined)
+  )
 
   service.ingress = Object.assign({}, ingress, declared)
 
   if (service.ingress.hosts === undefined)
-    throw new Error(`Service '${service.name}' declares an ingress, but no hosts are defined. ` +
-      "Declare them in the context's 'ingress' section.")
+    throw new Error(
+      `Service '${service.name}' declares an ingress, but no hosts are defined. ` +
+        "Declare them in the context's 'ingress' section."
+    )
 
   if (service.port === undefined)
     throw new Error(`Service '${service.name}' declares an ingress, but no port.`)

package/src/deployment/.deployment/.describe/services.test.js

@@ -3,7 +3,12 @@ import assert from 'node:assert/strict'
 
 import { services } from './services.js'
 
-const service = (extra = {}) => ({ group: 'group', name: 'group-one', version: '0', ...extra })
+const service = (extra = {}) => ({
+  group: 'group',
+  name: 'group-one',
+  version: '0',
+  ...extra
+})
 
 it('should leave a service without an ingress alone', () => {
   const list = [service()]
@@ -20,7 +25,11 @@ it('should leave a service without an ingress alone', () => {
 it('should supply hosts, class and annotations from the context', () => {
   const list = [service({ port: 8002, ingress: { path: '/.introspection' } })]
 
-  services(list, {}, undefined, { hosts: ['api.dev'], class: 'alb', annotations: { a: 'b' } })
+  services(list, {}, undefined, {
+    hosts: ['api.dev'],
+    class: 'alb',
+    annotations: { a: 'b' }
+  })
 
   assert.deepStrictEqual(list[0].ingress, {
     path: '/.introspection',
@@ -50,12 +59,20 @@ it('should ignore properties the service left undefined', () => {
 it('should reject an ingress with nowhere to land', () => {
   const list = [service({ port: 8002, ingress: { path: '/.introspection' } })]
 
-  assert.throws(() => services(list, {}, undefined, undefined), (error) => /Service 'group-one' declares an ingress, but no hosts are defined/.test(error.message))
+  assert.throws(
+    () => services(list, {}, undefined, undefined),
+    (error) =>
+      /Service 'group-one' declares an ingress, but no hosts are defined/.test(
+        error.message
+      )
+  )
 })
 
 it('should reject an ingress without a port', () => {
   const list = [service({ ingress: { path: '/.introspection' } })]
 
-  assert.throws(() => services(list, {}, undefined, { hosts: ['api.dev'] }), (error) => /Service 'group-one' declares an ingress, but no port/.test(error.message))
+  assert.throws(
+    () => services(list, {}, undefined, { hosts: ['api.dev'] }),
+    (error) => /Service 'group-one' declares an ingress, but no port/.test(error.message)
+  )
 })
-

package/src/deployment/.deployment/.describe/variables.js

@@ -1,11 +1,10 @@
-export function addVariables (composition, variables, keys = composition.components) {
+export function addVariables(composition, variables, keys = composition.components) {
   composition.variables ??= []
 
   const used = new Set(composition.variables.map((variable) => variable.name))
 
   for (const [key, set] of Object.entries(variables)) {
-    if (key !== 'global' && !keys?.includes(key))
-      continue
+    if (key !== 'global' && !keys?.includes(key)) continue
 
     for (const variable of set) {
       if (used.has(variable.name)) continue

package/src/deployment/.deployment/describe.js

@@ -14,7 +14,8 @@ export const describe = (context, compositions, dependency, image) => {
     {
       name: 'TOA_CONTEXT',
       value: context.name
-    }, {
+    },
+    {
       name: 'TOA_ENV',
       value: context.environment
     }
@@ -28,8 +29,10 @@ export const describe = (context, compositions, dependency, image) => {
     // a lock is taken on `floor(n / 2) + 1` of them, so an even number tolerates no more
     // losses than the odd number below it, and two tolerate fewer than one does
     if (addresses.length % 2 === 0)
-      throw new Error(`'atomicity.redis' takes an odd number of addresses, ` +
-        `${addresses.length} given`)
+      throw new Error(
+        `'atomicity.redis' takes an odd number of addresses, ` +
+          `${addresses.length} given`
+      )
 
     dependency.variables.global.push({
       name: 'TOA_ATOMICITY_REDIS',
@@ -102,8 +105,10 @@ export const describe = (context, compositions, dependency, image) => {
   return values
 }
 
-function unit (context, dependency) {
-  const components = (context.components ?? []).map((component) => component.locator.label)
+function unit(context, dependency) {
+  const components = (context.components ?? []).map(
+    (component) => component.locator.label
+  )
 
   const variables = dependency.variables ?? {}
   const mounts = dependency.mounts ?? {}
@@ -115,8 +120,7 @@ function unit (context, dependency) {
     variables: []
   }
 
-  if (context.ingress !== undefined)
-    mono.ingress = Object.assign({}, context.ingress)
+  if (context.ingress !== undefined) mono.ingress = Object.assign({}, context.ingress)
 
   addVariables(mono, variables, Object.keys(variables))
   addMounts(mono, dependency.mounts, Object.keys(mounts))

package/src/deployment/.deployment/merge.js

@@ -61,22 +61,27 @@ const reserve = (services, probe) => {
         const conflicting = claimed.get(port)
 
         if (conflicting !== undefined)
-          throw new Error(`Port ${port} is claimed by both ${conflicting} and ${claimant}` +
-            (service.workload === undefined ? '' : ` in '${workload}'`))
+          throw new Error(
+            `Port ${port} is claimed by both ${conflicting} and ${claimant}` +
+              (service.workload === undefined ? '' : ` in '${workload}'`)
+          )
 
         claimed.set(port, claimant)
       }
     }
 }
 
-function * ports (service) {
+function* ports(service) {
   // every service reaching here is named the way it is deployed, `<group>-<name>`
   const name = `'${service.name}'`
 
-  if (service.port !== undefined)
-    yield [service.port, name]
+  if (service.port !== undefined) yield [service.port, name]
 
-  if (service.probe !== undefined && service.probe !== false && service.probe.port !== service.port)
+  if (
+    service.probe !== undefined &&
+    service.probe !== false &&
+    service.probe.port !== service.port
+  )
     yield [service.probe.port, `the readiness probe of ${name}`]
 }
 

package/src/deployment/.deployment/merge.test.js

@@ -4,7 +4,12 @@ import assert from 'node:assert/strict'
 import { merge } from './merge.js'
 
 // a service is named the way it is deployed by the time it reaches `merge`
-const service = (name, extra = {}) => ({ group: 'group', name: `group-${name}`, version: '0', ...extra })
+const service = (name, extra = {}) => ({
+  group: 'group',
+  name: `group-${name}`,
+  version: '0',
+  ...extra
+})
 
 it('should merge services of all dependencies', () => {
   const merged = merge([
@@ -28,7 +33,13 @@ describe('port reservation', () => {
       { services: [hosted('two', { port: 8000 })] }
     ]
 
-    assert.throws(() => merge(dependencies), (error) => /Port 8000 is claimed by both 'group-one' and 'group-two' in 'mono'/.test(error.message))
+    assert.throws(
+      () => merge(dependencies),
+      (error) =>
+        /Port 8000 is claimed by both 'group-one' and 'group-two' in 'mono'/.test(
+          error.message
+        )
+    )
   })
 
   it('should allow two workloads to claim one port', () => {
@@ -46,7 +57,13 @@ describe('port reservation', () => {
       { services: [service('two', { port: 8000, workload: ['inner'] })] }
     ]
 
-    assert.throws(() => merge(dependencies), (error) => /Port 8000 is claimed by both 'group-one' and 'group-two' in 'inner'/.test(error.message))
+    assert.throws(
+      () => merge(dependencies),
+      (error) =>
+        /Port 8000 is claimed by both 'group-one' and 'group-two' in 'inner'/.test(
+          error.message
+        )
+    )
   })
 
   it('should allow two services deployed on their own to claim one port', () => {
@@ -64,30 +81,44 @@ describe('port reservation', () => {
       { services: [service('one', { port: 8001 })] }
     ]
 
-    assert.throws(() => merge(dependencies), (error) => /Port 8001 is claimed by both the readiness probe and 'group-one'/.test(error.message))
+    assert.throws(
+      () => merge(dependencies),
+      (error) =>
+        /Port 8001 is claimed by both the readiness probe and 'group-one'/.test(
+          error.message
+        )
+    )
   })
 
   it('should reject a probe claiming the port of another service of the workload', () => {
     const dependencies = [
       { services: [hosted('one', { port: 8000 })] },
-      { services: [hosted('two', { port: 8002, probe: { path: '/.ready', port: 8000 } })] }
+      {
+        services: [hosted('two', { port: 8002, probe: { path: '/.ready', port: 8000 } })]
+      }
     ]
 
-    assert.throws(() => merge(dependencies), (error) => /Port 8000 is claimed by both 'group-one' and the readiness probe of 'group-two' in 'mono'/.test(error.message))
+    assert.throws(
+      () => merge(dependencies),
+      (error) =>
+        /Port 8000 is claimed by both 'group-one' and the readiness probe of 'group-two' in 'mono'/.test(
+          error.message
+        )
+    )
   })
 
   it('should allow a service to probe its own port', () => {
     const dependencies = [
-      { services: [service('one', { port: 8000, probe: { path: '/.ready', port: 8000 } })] }
+      {
+        services: [service('one', { port: 8000, probe: { path: '/.ready', port: 8000 } })]
+      }
     ]
 
     assert.doesNotThrow(() => merge(dependencies))
   })
 
   it('should ignore services without a port', () => {
-    const dependencies = [
-      { services: [service('one'), service('two')] }
-    ]
+    const dependencies = [{ services: [service('one'), service('two')] }]
 
     assert.doesNotThrow(() => merge(dependencies))
   })

package/src/deployment/composition.js

@@ -4,7 +4,7 @@ export class Composition {
   /** @type {string[]} */
   components
 
-  constructor (composition, image) {
+  constructor(composition, image) {
     this.name = composition.name
     this.image = image.reference
     this.components = composition.components.map(component)