@toa.io/operations 1.0.0-alpha.28 → 1.0.0-alpha.280

package/CHANGELOG.md

@@ -0,0 +1,204 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# [1.0.0-alpha.280](https://github.com/toa-io/toa/compare/v1.0.0-alpha.279...v1.0.0-alpha.280) (2026-09-03)
+
+### Bug Fixes
+
+* **operations:** call execa, not the module it lives in ([9fe87d5](https://github.com/toa-io/toa/commit/9fe87d54cc02f7ec18e325c85882ff174acbe8ab))
+
+
+# [1.0.0-alpha.278](https://github.com/toa-io/toa/compare/v1.0.0-alpha.277...v1.0.0-alpha.278) (2026-09-03)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.277](https://github.com/toa-io/toa/compare/v1.0.0-alpha.276...v1.0.0-alpha.277) (2026-09-03)
+
+### Bug Fixes
+
+* read a manifest the way js-yaml read one before ([fcea1b2](https://github.com/toa-io/toa/commit/fcea1b21996d6efa6c3198acbfc9f70f1ce0c35c))
+* settle what the module loader made asynchronous ([d4ab9df](https://github.com/toa-io/toa/commit/d4ab9dfb09e382da311dba08f52214e7645f4a6c))
+* what the loader resolves, and what it will not ([1b8a02f](https://github.com/toa-io/toa/commit/1b8a02ff0a5e0f18ee62e3f71bc81116f86f9af1))
+
+
+# [1.0.0-alpha.276](https://github.com/toa-io/toa/compare/v1.0.0-alpha.275...v1.0.0-alpha.276) (2026-09-03)
+
+
+### Bug Fixes
+
+* **operations:** let a deployment state that it has no probe ([477b483](https://github.com/toa-io/toa/commit/477b483560cf2464d486a78e432f8e9b47f011dd))
+
+
+
+
+
+# [1.0.0-alpha.274](https://github.com/toa-io/toa/compare/v1.0.0-alpha.273...v1.0.0-alpha.274) (2026-09-02)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.273](https://github.com/toa-io/toa/compare/v1.0.0-alpha.272...v1.0.0-alpha.273) (2026-09-02)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.272](https://github.com/toa-io/toa/compare/v1.0.0-alpha.271...v1.0.0-alpha.272) (2026-09-01)
+
+
+* feat(atomicity)!: take a quorum of independent servers ([862562f](https://github.com/toa-io/toa/commit/862562f24d77ec00127dbbd88d43802b208c643b))
+* refactor(atomicity)!: take one Redis, not a cluster ([b0a4770](https://github.com/toa-io/toa/commit/b0a4770dff5dfe8fee4b9ae637a4dd297454fcd4))
+* refactor(core)!: pump the outbox in one cycle ([bf590fe](https://github.com/toa-io/toa/commit/bf590fe8ed59c701b5fd1a91ba4874685b79242f))
+* refactor(atomicity)!: rename the connector and free it of the outbox ([21f1a41](https://github.com/toa-io/toa/commit/21f1a41aceafcfd35c7620014062fe46b54afa95))
+* feat(core)!: commit events with the state that produced them ([1eb68cc](https://github.com/toa-io/toa/commit/1eb68cc435dbfa03faa16009fceb866693d22e1a)), closes [#20](https://github.com/toa-io/toa/issues/20)
+
+
+### Features
+
+* **atomicity:** make the interval a setting, and stop repeating n-and-i ([5c3a6d1](https://github.com/toa-io/toa/commit/5c3a6d1533751a21b7eb7d9c737f1a270bf5a5ae))
+
+
+### BREAKING CHANGES
+
+* `atomicity.redis` accepts a list again, of independent servers rather
+than cluster nodes, and refuses an even number of them.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+* `atomicity.redis` is a string. A list is refused at export.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+* `Storage.outbox.pending` takes a fourth argument, the id to
+continue from.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+* `@toa.io/partitions.redis` is now `@toa.io/atomicity`, and its
+`lanes(total)` is `slots(total)`. Redis is declared as `atomicity` in the context
+rather than `outbox.redis`, and read from `TOA_ATOMICITY_REDIS`.
+`TOA_OUTBOX_PARTITION_INTERVAL` is `TOA_ATOMICITY_INTERVAL`.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+* `event.changeset` is removed; use `origin` and `state`. `State`
+takes an `Outbox` in place of an `Emission`. `difference` is dropped from
+`@toa.io/generic` along with its last caller.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+
+
+
+
+
+# [1.0.0-alpha.270](https://github.com/toa-io/toa/compare/v1.0.0-alpha.269...v1.0.0-alpha.270) (2026-08-31)
+
+
+### Bug Fixes
+
+* **operations:** let a composition set its own base image ([61ba331](https://github.com/toa-io/toa/commit/61ba3319dc91915a3197d348111af411bbd5bff1))
+
+
+
+
+
+# [1.0.0-alpha.266](https://github.com/toa-io/toa/compare/v1.0.0-alpha.265...v1.0.0-alpha.266) (2026-08-29)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.265](https://github.com/toa-io/toa/compare/v1.0.0-alpha.264...v1.0.0-alpha.265) (2026-08-29)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.264](https://github.com/toa-io/toa/compare/v1.0.0-alpha.263...v1.0.0-alpha.264) (2026-08-29)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.263](https://github.com/toa-io/toa/compare/v1.0.0-alpha.262...v1.0.0-alpha.263) (2026-08-29)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.262](https://github.com/toa-io/toa/compare/v1.0.0-alpha.261...v1.0.0-alpha.262) (2026-08-28)
+
+
+### Bug Fixes
+
+* **cli:** boot toa mono from components and env, not context ([1518f72](https://github.com/toa-io/toa/commit/1518f729d7611ae88e0538f286231d283a7098ef))
+
+
+* feat(operations)!: require service ports to be unique ([b22cf87](https://github.com/toa-io/toa/commit/b22cf8770d24c555b5f355a5f117a9043a57799b))
+
+
+### Features
+
+* **operations:** let a service claim a path prefix on the host ([02677d1](https://github.com/toa-io/toa/commit/02677d17fcd4222b07c3be458d93bcc496a016a8))
+
+
+### BREAKING CHANGES
+
+* an application whose own extension runs a service on a port
+already taken by another — 8000 by the exposition gateway, 8001 by the telemetry
+readiness probe — must move it.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+
+
+
+
+
+# [1.0.0-alpha.261](https://github.com/toa-io/toa/compare/v1.0.0-alpha.260...v1.0.0-alpha.261) (2026-08-26)
+
+
+### Bug Fixes
+
+* **operations:** include extension pointer variables in --mono ([f8be23d](https://github.com/toa-io/toa/commit/f8be23d2aaf7bbe1b0580101c8bf4d32c3cab99f))
+
+
+
+
+
+# [1.0.0-alpha.259](https://github.com/toa-io/toa/compare/v1.0.0-alpha.258...v1.0.0-alpha.259) (2026-08-24)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.257](https://github.com/toa-io/toa/compare/v1.0.0-alpha.256...v1.0.0-alpha.257) (2026-08-24)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
+# [1.0.0-alpha.256](https://github.com/toa-io/toa/compare/v1.0.0-alpha.255...v1.0.0-alpha.256) (2026-08-23)
+
+
+### Features
+
+* deploy a single mono image with toa deploy --mono ([a7f14f9](https://github.com/toa-io/toa/commit/a7f14f9877a280e9c74d16c195028b35d74fb15a))

package/image/runtime.Dockerfile

@@ -0,0 +1,4 @@
+FROM node:24.14.0-alpine3.22
+
+ARG VERSION
+RUN npm i -g @toa.io/runtime@${VERSION} --omit=dev

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@toa.io/operations",
-  "version": "1.0.0-alpha.28",
+  "version": "1.0.0-alpha.280",
+  "type": "module",
   "description": "Toa Deployment",
   "homepage": "https://toa.io",
   "author": {
@@ -16,23 +17,22 @@
     "url": "https://github.com/toa-io/toa/issues"
   },
   "engines": {
-    "node": ">= 18.0.0"
+    "node": ">= 24.0.0"
   },
   "publishConfig": {
     "access": "public"
   },
   "main": "src/index.js",
-  "types": "types/index.d.ts",
+  "types": "types/index.ts",
   "scripts": {
     "test": "echo \"Error: run tests from root\" && exit 1"
   },
   "dependencies": {
-    "@toa.io/filesystem": "1.0.0-alpha.28",
-    "@toa.io/generic": "1.0.0-alpha.28",
-    "@toa.io/norm": "1.0.0-alpha.28",
-    "@toa.io/yaml": "1.0.0-alpha.28",
-    "execa": "5.1.1",
-    "fs-extra": "11.1.1"
+    "@toa.io/generic": "1.0.0-alpha.278",
+    "@toa.io/norm": "1.0.0-alpha.278",
+    "execa": "10.0.1",
+    "fs-extra": "11.4.0",
+    "js-yaml": "5.4.1"
   },
-  "gitHead": "89c3b7d1314e357c9e33df8d95f8d46954cd3bcf"
+  "gitHead": "2cf23f576c46efbe56c21427d877cef3e7ed98d4"
 }

package/readme.md

@@ -4,6 +4,22 @@
 
 ### Container Registry
 
+Deploy images default to `FROM ghcr.io/toa-io/runtime:<runtime.version>`
+(published with each Toa release). The base image already has `@toa.io/runtime`
+installed; composition/service Dockerfiles only install component dependencies.
+
+To use a custom base image, set `registry.build.image` (or `composition.image`).
+That image must provide the `toa` CLI, or install it via `registry.build.run`:
+
+```yaml
+# context.toa.yaml
+
+registry:
+  build:
+    image: node:24.14.0-alpine3.22
+    run: npm i -g @toa.io/runtime --omit=dev
+```
+
 #### Build Options
 
 ```yaml

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

@@ -1,10 +1,8 @@
-'use strict'
-
 /**
  * @param {toa.deployment.Composition[]} compositions
  * @returns {string[]}
  */
-const components = (compositions) => {
+export const components = (compositions) => {
   /** @type {Set<string>} */
   const components = new Set()
 
@@ -16,5 +14,3 @@ const components = (compositions) => {
 
   return Array.from(components)
 }
-
-exports.components = components

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

@@ -1,11 +1,12 @@
-'use strict'
+import { addVariables } from './variables.js'
+import { addMounts } from './mounts.js'
 
-const { addVariables } = require('./variables')
-
-function compositions (compositions, variables) {
+export function compositions (compositions, dependency) {
   for (const composition of compositions) {
-    addVariables(composition, variables)
+    addVariables(composition, dependency.variables)
+    addMounts(composition, dependency.mounts)
+
+    if (dependency.probe !== undefined && dependency.probe !== false)
+      composition.probe ??= dependency.probe
   }
 }
-
-exports.compositions = compositions

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

@@ -1,10 +1,8 @@
-'use strict'
-
 /**
  * @param {toa.deployment.dependency.Reference[]} references
  * @returns {*}
  */
-const dependencies = (references) => {
+export const dependencies = (references) => {
   return references?.reduce((map, reference) => {
     const { name, alias, values } = reference
 
@@ -13,6 +11,3 @@ const dependencies = (references) => {
     return map
   }, {})
 }
-
-
-exports.dependencies = dependencies

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

@@ -0,0 +1,63 @@
+/**
+ * Tells each component which of its events something consumes. An event nobody consumes gets
+ * no emitter, no exchange and no outbox row, and a component none of whose events are consumed
+ * gets no outbox at all.
+ *
+ * A component that declares events always gets the variable, empty when nothing is consumed —
+ * an absent variable means every event, which is what a run without a deployment gets.
+ *
+ * @param {toa.norm.Context} context
+ * @param {toa.deployment.Dependency} 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))
+
+    dependency.variables[locator.label] ??= []
+
+    dependency.variables[locator.label].push({
+      name: VARIABLE + locator.uppercase,
+      value: labels.join(' ')
+    })
+  }
+}
+
+/**
+ * Every component this context deploys, its own and those its extensions bring. `components`
+ * 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) {
+  const components = new Map()
+
+  for (const instances of Object.values(context.dependencies ?? {}))
+    for (const { component } of instances)
+      components.set(component.locator.id, component)
+
+  return [...components.values()]
+}
+
+/**
+ * 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) {
+  const consumed = new Set(declared ?? [])
+
+  for (const label of contributed ?? []) consumed.add(label)
+
+  for (const { receivers } of components)
+    for (const [label, receiver] of Object.entries(receivers ?? {}))
+      // a receiver with a source consumes from a foreign broker, not from this context
+      if (receiver.source === undefined) consumed.add(label)
+
+  return consumed
+}
+
+const VARIABLE = 'TOA_EVENTS_'

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

@@ -1,13 +1,4 @@
-'use strict'
-
-const { dependencies } = require('./dependencies')
-const { components } = require('./components')
-const { compositions } = require('./compositions')
-const { variables } = require('./variables')
-const { services } = require('./services')
-
-exports.dependencies = dependencies
-exports.components = components
-exports.compositions = compositions
-exports.variables = variables
-exports.services = services
+export { dependencies } from './dependencies.js'
+export { components } from './components.js'
+export { compositions } from './compositions.js'
+export { services } from './services.js'

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

@@ -0,0 +1,20 @@
+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
+
+    for (const { name, path, claim } of mount) {
+      if (used.has(name))
+        continue
+
+      composition.mounts ??= []
+      composition.mounts.push({ name, path, claim })
+      used.add(name)
+    }
+  }
+}

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

@@ -0,0 +1,33 @@
+/**
+ * Every deployment states what it may take. One that states nothing is `BestEffort`: the
+ * first evicted under memory pressure and the last given CPU under contention — which on
+ * a busy node is slow enough for its own startup probe to kill it, in a loop, while the
+ * chart reports nothing wrong. That is not a thing to find out in production.
+ *
+ * A deployment takes its own declaration, or the context's `resources` where it has none.
+ * Deploying without any is a decision rather than an omission, and it is spelled
+ * `resources: null` — at either place.
+ */
+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.')
+  }
+}
+
+function * units (values) {
+  if (values.mono !== undefined)
+    yield { deployment: values.mono, subject: 'The mono deployment' }
+
+  for (const composition of values.compositions ?? [])
+    yield { deployment: composition, subject: `Composition '${composition.name}'` }
+
+  for (const service of values.services ?? [])
+    yield { deployment: service, subject: `Service '${service.name}'` }
+}

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

@@ -1,11 +1,34 @@
-'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)
+
+    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,61 @@
+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,17 @@
-'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