@toa.io/operations 1.0.0-alpha.29 → 1.0.0-alpha.291

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

@@ -0,0 +1,129 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { resources, quantity } from './resources.js'
+
+const declared = { cpu: ['100m', '1'], memory: ['100Mi', '1Gi'] }
+
+it('should take the declaration of a deployment', () => {
+  const values = { compositions: [{ name: 'edge', resources: declared }] }
+
+  resources({}, values)
+
+  assert.deepStrictEqual(values.compositions[0].resources, declared)
+})
+
+it('should fall back to the context', () => {
+  const values = { compositions: [{ name: 'edge' }] }
+
+  resources({ resources: declared }, values)
+
+  assert.deepStrictEqual(values.compositions[0].resources, declared)
+})
+
+it('should take `null` as an answer', () => {
+  const values = { compositions: [{ name: 'edge', resources: null }] }
+
+  assert.doesNotThrow(() => resources({ resources: declared }, values))
+  assert.strictEqual(values.compositions[0].resources, null)
+})
+
+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)
+    )
+  })
+
+  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)
+    )
+  })
+
+  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)
+    )
+  })
+
+  it('should not ask a service a composition runs', () => {
+    // it has no deployment of its own to size; the composition running it states the pod's
+    const values = {
+      compositions: [{ name: 'edge', resources: declared }],
+      services: [{ name: 'exposition-gateway', workload: ['edge'] }]
+    }
+
+    assert.doesNotThrow(() => resources({}, values))
+    assert.strictEqual(values.services[0].resources, undefined)
+  })
+})
+
+describe('heap', () => {
+  it('should size the heap by the memory limit', () => {
+    const values = { compositions: [{ name: 'edge', resources: declared }] }
+
+    resources({}, values)
+
+    assert.deepStrictEqual(values.compositions[0].variables, [
+      { name: 'NODE_OPTIONS', value: '--max-old-space-size=768' }
+    ])
+  })
+
+  it('should size the heap of a service and of the mono deployment', () => {
+    const values = {
+      services: [
+        { name: 'exposition-gateway', resources: { memory: ['200Mi', '500Mi'] } }
+      ],
+      mono: { variables: [{ name: 'TOA_ENV', value: 'test' }] }
+    }
+
+    resources({ resources: declared }, values)
+
+    assert.deepStrictEqual(values.services[0].variables, [
+      { name: 'NODE_OPTIONS', value: '--max-old-space-size=375' }
+    ])
+
+    assert.deepStrictEqual(values.mono.variables, [
+      { name: 'TOA_ENV', value: 'test' },
+      { name: 'NODE_OPTIONS', value: '--max-old-space-size=768' }
+    ])
+  })
+
+  it('should keep the options a deployment states', () => {
+    const variables = [{ name: 'NODE_OPTIONS', value: '--max-old-space-size=100' }]
+    const values = { compositions: [{ name: 'edge', resources: declared, variables }] }
+
+    resources({}, values)
+
+    assert.deepStrictEqual(values.compositions[0].variables, variables)
+  })
+
+  it('should not size the heap without a memory limit', () => {
+    const values = { compositions: [{ name: 'edge', resources: { cpu: ['100m', '1'] } }] }
+
+    resources({}, values)
+
+    assert.strictEqual(values.compositions[0].variables, undefined)
+  })
+
+  it('should read a quantity', () => {
+    assert.strictEqual(quantity('512Mi'), 512 * 2 ** 20)
+    assert.strictEqual(quantity('1Gi'), 2 ** 30)
+    assert.strictEqual(quantity('500M'), 500e6)
+    assert.strictEqual(quantity('1.5Gi'), 1.5 * 2 ** 30)
+    assert.strictEqual(quantity(1024), 1024)
+    assert.throws(() => quantity('500m'), /not a memory quantity/)
+    assert.throws(() => quantity('big'), /not a quantity/)
+  })
+})

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

@@ -1,11 +1,37 @@
-'use strict'
+import { addVariables } from './variables.js'
 
-const { addVariables } = require('./variables')
-
-function services (services, variables) {
+export function services(services, variables, probe, ingress) {
   for (const service of services) {
-    addVariables(service, variables)
+    // 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
+    else if (service.probe === undefined && probe !== undefined && probe !== false)
+      service.probe = probe
+
+    if (service.ingress !== undefined) expose(service, ingress)
   }
 }
 
-exports.services = services
+/**
+ * A service declares only its own intent — a path, a port. Where that lands is
+ * the context's business, so everything else comes from its `ingress` section.
+ * What the service did declare wins.
+ */
+function expose(service, ingress = {}) {
+  const declared = Object.fromEntries(
+    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."
+    )
+
+  if (service.port === undefined)
+    throw new Error(`Service '${service.name}' declares an ingress, but no port.`)
+}

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

@@ -0,0 +1,78 @@
+import { it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { services } from './services.js'
+
+const service = (extra = {}) => ({
+  group: 'group',
+  name: 'group-one',
+  version: '0',
+  ...extra
+})
+
+it('should leave a service without an ingress alone', () => {
+  const list = [service()]
+
+  services(list, {}, undefined, { hosts: ['api.dev'] })
+
+  assert.strictEqual(list[0].ingress, undefined)
+})
+
+/*
+ * A service declares only where it wants to land; the cluster-level plumbing
+ * belongs to the context.
+ */
+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' }
+  })
+
+  assert.deepStrictEqual(list[0].ingress, {
+    path: '/.introspection',
+    hosts: ['api.dev'],
+    class: 'alb',
+    annotations: { a: 'b' }
+  })
+})
+
+it('should keep what the service declared itself', () => {
+  const list = [service({ port: 8000, ingress: { path: '/', hosts: ['own.dev'] } })]
+
+  services(list, {}, undefined, { hosts: ['api.dev'], class: 'alb' })
+
+  assert.deepStrictEqual(list[0].ingress.hosts, ['own.dev'])
+  assert.deepStrictEqual(list[0].ingress.class, 'alb')
+})
+
+it('should ignore properties the service left undefined', () => {
+  const list = [service({ port: 8000, ingress: { path: '/', class: undefined } })]
+
+  services(list, {}, undefined, { hosts: ['api.dev'], class: 'alb' })
+
+  assert.deepStrictEqual(list[0].ingress.class, 'alb')
+})
+
+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
+      )
+  )
+})
+
+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)
+  )
+})

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

@@ -1,20 +1,16 @@
-'use strict'
+export function addVariables(composition, variables, keys = composition.components) {
+  composition.variables ??= []
 
-function addVariables (deployment, variables) {
-  const used = new Set()
-
-  deployment.variables ??= []
+  const used = new Set(composition.variables.map((variable) => variable.name))
 
   for (const [key, set] of Object.entries(variables)) {
-    if (key !== 'global' && !deployment.components?.includes(key)) continue
+    if (key !== 'global' && !keys?.includes(key)) continue
 
     for (const variable of set) {
       if (used.has(variable.name)) continue
 
-      deployment.variables.push(variable)
+      composition.variables.push(variable)
       used.add(variable.name)
     }
   }
 }
-
-exports.addVariables = addVariables

package/src/deployment/.deployment/declare.js

@@ -1,11 +1,9 @@
-'use strict'
-
 /**
  * @param {toa.norm.Context} context
  * @param {toa.deployment.Dependency} dependency
  * @returns {toa.deployment.Declaration}
  */
-const declare = (context, dependency) => {
+export const declare = (context, dependency) => {
   const { references } = dependency
   const { name, description, version } = context
 
@@ -25,5 +23,3 @@ const DECLARATION = {
   apiVersion: 'v2',
   type: 'application'
 }
-
-exports.declare = declare

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

@@ -1,8 +1,11 @@
-'use strict'
+import * as desc from './.describe/index.js'
+import { addVariables } from './.describe/variables.js'
+import { addMounts } from './.describe/mounts.js'
+import { resources } from './.describe/resources.js'
+import { events } from './.describe/events.js'
+import { fold } from './.describe/fold.js'
 
-const get = require('./.describe')
-
-const describe = (context, compositions, dependency) => {
+export const describe = (context, compositions, dependency, image) => {
   const { services } = dependency
 
   dependency.variables.global ??= []
@@ -11,24 +14,136 @@ const describe = (context, compositions, dependency) => {
     {
       name: 'TOA_CONTEXT',
       value: context.name
-    }, {
+    },
+    {
       name: 'TOA_ENV',
       value: context.environment
     }
   )
 
-  const components = get.components(compositions)
+  const atomicity = context.atomicity
+
+  if (atomicity?.redis !== undefined) {
+    const addresses = Array.isArray(atomicity.redis) ? atomicity.redis : [atomicity.redis]
+
+    // 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`
+      )
+
+    dependency.variables.global.push({
+      name: 'TOA_ATOMICITY_REDIS',
+      value: addresses.join(' ')
+    })
+  }
+
+  if (atomicity?.interval !== undefined)
+    dependency.variables.global.push({
+      name: 'TOA_ATOMICITY_INTERVAL',
+      value: String(atomicity.interval)
+    })
+
+  const outbox = context.outbox
+
+  if (outbox?.interval !== undefined)
+    dependency.variables.global.push({
+      name: 'TOA_OUTBOX_INTERVAL',
+      value: String(outbox.interval)
+    })
+
+  if (outbox?.batch !== undefined)
+    dependency.variables.global.push({
+      name: 'TOA_OUTBOX_BATCH',
+      value: String(outbox.batch)
+    })
+
+  if (outbox?.retention !== undefined)
+    dependency.variables.global.push({
+      name: 'TOA_OUTBOX_RETENTION',
+      value: String(outbox.retention)
+    })
+
+  events(context, dependency)
+
   const credentials = context.registry?.credentials
 
-  get.compositions(compositions, dependency.variables, context.environment)
-  get.services(services, dependency.variables)
+  if (image !== undefined) {
+    const mono = unit(context, dependency)
+
+    mono.image = image.reference
+
+    const values = {
+      compositions: [],
+      components: mono.components,
+      services: [],
+      credentials,
+      mono
+    }
+
+    resources(context, values)
+
+    return values
+  }
+
+  const components = desc.components(compositions)
 
-  return {
+  desc.compositions(compositions, dependency)
+  desc.services(services, dependency.variables, dependency.probe, context.ingress)
+
+  const values = {
     compositions,
     components,
     services,
     credentials
   }
+
+  resources(context, values)
+
+  return values
 }
 
-exports.describe = describe
+function unit(context, dependency) {
+  const components = (context.components ?? []).map(
+    (component) => component.locator.label
+  )
+
+  const variables = dependency.variables ?? {}
+  const mounts = dependency.mounts ?? {}
+
+  const mono = {
+    replicas: context.mono?.replicas,
+    resources: context.mono?.resources,
+    components,
+    variables: []
+  }
+
+  if (context.ingress !== undefined) mono.ingress = Object.assign({}, context.ingress)
+
+  addVariables(mono, variables, Object.keys(variables))
+  addMounts(mono, dependency.mounts, Object.keys(mounts))
+
+  fold(mono, dependency.services ?? [], dependency)
+
+  // mono is the one workload that fronts every service it runs under a single name,
+  // so it inherits how they are reached as well as what they run
+  for (const service of dependency.services ?? []) {
+    // one Service fronts every backend, so its annotations are the union
+    if (service.annotations !== undefined)
+      mono.annotations = Object.assign(mono.annotations ?? {}, service.annotations)
+
+    if (service.ingress !== undefined) {
+      const { path, hosts, ...ingress } = service.ingress
+
+      mono.ingress = Object.assign(mono.ingress ?? {}, ingress)
+
+      // one Ingress serves every path, so its hosts are the union, not the last word
+      if (hosts !== undefined)
+        mono.ingress.hosts = [...new Set([...(mono.ingress.hosts ?? []), ...hosts])]
+    }
+  }
+
+  return mono
+}

package/src/deployment/.deployment/index.js

@@ -1,9 +1,3 @@
-'use strict'
-
-const { declare } = require('./declare')
-const { describe } = require('./describe')
-const { merge } = require('./merge')
-
-exports.declare = declare
-exports.describe = describe
-exports.merge = merge
+export { declare } from './declare.js'
+export { describe } from './describe.js'
+export { merge } from './merge.js'

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

@@ -1,6 +1,4 @@
-'use strict'
-
-const merge = (dependencies) => {
+export const merge = (dependencies) => {
   /** @type {toa.deployment.dependency.Reference[]} */
   const references = []
 
@@ -13,14 +11,78 @@ const merge = (dependencies) => {
   /** @type {toa.deployment.dependency.Variables} */
   const variables = {}
 
+  /** event labels consumed by something other than a component's own receivers */
+  const events = []
+
+  const mounts = {}
+
+  /** @type {toa.deployment.dependency.Probe | false | undefined} */
+  let probe
+
   for (const dependency of dependencies) {
     if (dependency.references !== undefined) references.push(...dependency.references)
     if (dependency.services !== undefined) services.push(...dependency.services)
     if (dependency.proxies !== undefined) proxies.push(...dependency.proxies)
     if (dependency.variables !== undefined) append(variables, dependency.variables)
+    if (dependency.events !== undefined) events.push(...dependency.events)
+    if (dependency.mounts !== undefined) append(mounts, dependency.mounts)
+    if (dependency.probe !== undefined) probe = dependency.probe
   }
 
-  return { references, services, proxies, variables }
+  reserve(services, probe)
+
+  return { references, services, proxies, variables, mounts, events, probe }
+}
+
+/**
+ * A workload that hosts services puts them in one process — `mono`, a composition that
+ * declares them, a local run — so within one a port may be claimed once and only once.
+ * A service deploying on its own is a pod of its own, and shares a port with nobody.
+ */
+const reserve = (services, probe) => {
+  /** @type {Map<string, Map<number, string>>} */
+  const workloads = new Map()
+
+  for (const service of services)
+    // a service several compositions run binds its ports in each of their pods
+    for (const workload of service.workload ?? [service.name]) {
+      let claimed = workloads.get(workload)
+
+      if (claimed === undefined) {
+        claimed = new Map()
+
+        if (probe !== undefined && probe !== false)
+          claimed.set(probe.port, 'the readiness probe')
+
+        workloads.set(workload, claimed)
+      }
+
+      for (const [port, claimant] of ports(service)) {
+        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}'`)
+          )
+
+        claimed.set(port, claimant)
+      }
+    }
+}
+
+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.probe !== undefined &&
+    service.probe !== false &&
+    service.probe.port !== service.port
+  )
+    yield [service.probe.port, `the readiness probe of ${name}`]
 }
 
 const append = (merged, variables) => {
@@ -30,5 +92,3 @@ const append = (merged, variables) => {
     merged[component].push(...vars)
   }
 }
-
-exports.merge = merge

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

@@ -0,0 +1,133 @@
+import { describe, it } from 'node:test'
+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
+})
+
+it('should merge services of all dependencies', () => {
+  const merged = merge([
+    { services: [service('one', { port: 8000 })] },
+    { services: [service('two', { port: 8001 })] }
+  ])
+
+  assert.strictEqual(merged.services.length, 2)
+})
+
+/*
+ * A workload that hosts services puts them in one process, so a port is claimed once
+ * within one. Services in separate pods share nothing.
+ */
+describe('port reservation', () => {
+  const hosted = (name, extra = {}) => service(name, { workload: ['mono'], ...extra })
+
+  it('should reject two services of one workload claiming one port', () => {
+    const dependencies = [
+      { services: [hosted('one', { port: 8000 })] },
+      { 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
+        )
+    )
+  })
+
+  it('should allow two workloads to claim one port', () => {
+    const dependencies = [
+      { services: [service('one', { port: 8000, workload: ['edge'] })] },
+      { services: [service('two', { port: 8000, workload: ['inner'] })] }
+    ]
+
+    assert.doesNotThrow(() => merge(dependencies))
+  })
+
+  it('should reserve the ports of a service in every workload running it', () => {
+    const dependencies = [
+      { services: [service('one', { port: 8000, workload: ['edge', 'inner'] })] },
+      { 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
+        )
+    )
+  })
+
+  it('should allow two services deployed on their own to claim one port', () => {
+    const dependencies = [
+      { services: [service('one', { port: 8000 })] },
+      { services: [service('two', { port: 8000 })] }
+    ]
+
+    assert.doesNotThrow(() => merge(dependencies))
+  })
+
+  it('should reject a service claiming the port of the readiness probe', () => {
+    const dependencies = [
+      { probe: { path: '/.ready', port: 8001 } },
+      { 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
+        )
+    )
+  })
+
+  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 } })]
+      }
+    ]
+
+    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 } })]
+      }
+    ]
+
+    assert.doesNotThrow(() => merge(dependencies))
+  })
+
+  it('should ignore services without a port', () => {
+    const dependencies = [{ services: [service('one'), service('two')] }]
+
+    assert.doesNotThrow(() => merge(dependencies))
+  })
+
+  it('should ignore a disabled probe', () => {
+    const dependencies = [
+      { probe: false, services: [service('one', { port: 8000, probe: false })] }
+    ]
+
+    assert.doesNotThrow(() => merge(dependencies))
+  })
+})