@toa.io/operations 1.0.0-alpha.288 → 1.0.0-alpha.289

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 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.289](https://github.com/toa-io/toa/compare/v1.0.0-alpha.288...v1.0.0-alpha.289) (2026-09-07)
+
+* A deploy moves only what changed, and a component sees none of the runtime's environment (#1073) ([f38e3db](https://github.com/toa-io/toa/commit/f38e3db533f24db866c57bfa1ef294eff1eaf499)), closes [#1073](https://github.com/toa-io/toa/issues/1073) [#1064](https://github.com/toa-io/toa/issues/1064) [#1066](https://github.com/toa-io/toa/issues/1066) [#1067](https://github.com/toa-io/toa/issues/1067) [#1068](https://github.com/toa-io/toa/issues/1068) [#1069](https://github.com/toa-io/toa/issues/1069) [#1071](https://github.com/toa-io/toa/issues/1071) [#1070](https://github.com/toa-io/toa/issues/1070) [#1072](https://github.com/toa-io/toa/issues/1072)
+
+### BREAKING CHANGES
+
+* a component that read `process.env.TOA_*` reads `context` instead;
+  `echo(input)` no longer substitutes from the environment; a bash operation sees no
+  `TOA_*`; images no longer set `USER node` — see migrations/289.md.
+
+
 # [1.0.0-alpha.288](https://github.com/toa-io/toa/compare/v1.0.0-alpha.287...v1.0.0-alpha.288) (2026-09-06)
 
 **Note:** Version bump only for package @toa.io/operations

package/package.json

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

package/readme.md

@@ -38,6 +38,22 @@ registry:
     run: npm i -g @toa.io/runtime --omit=dev
 ```
 
+#### Composition Images
+
+A composition is two images in one repository. `composition-<name>:deps-<hash>` is what its
+components depend on, installed on the base image: it is tagged by everything the install
+reads — the runtime version, the base image, the build options and each component's
+`package.json` (and `package-lock.json`, where there is one) — and is built only when one of
+those changes. `composition-<name>:<hash>` is the sources laid over it in a single linked
+layer, so a deploy that changes code alone builds and pushes that layer, and neither
+downloads nor uploads the dependencies again. The same holds for `mono`.
+
+A pushed image builds on the `toa` container builder, whose registry exporter is what lays
+an image over a base it never pulled; `toa build` loads on the daemon's own.
+
+A dependency named by a moving git ref is installed when the dependencies image is built and
+not again until its manifest changes, so pin such a dependency to a commit and bump it there.
+
 #### Extension Service Images
 
 `registry.services` says where an extension service's image comes from.

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

@@ -20,9 +20,72 @@ export function resources(context, values) {
           "Declare them on it or as the context's 'resources', " +
           "or 'resources: null' to deploy it without any."
       )
+
+    heap(unit.deployment)
   }
 }
 
+/**
+ * The memory limit sizes the heap. Node reads the machine's memory rather than the
+ * container's, so without this the heap grows past the limit and the pod is killed instead
+ * of collected. What is left of the limit is the process itself: its code, its buffers and
+ * its threads. A deployment that states `NODE_OPTIONS` of its own keeps them.
+ */
+function heap(deployment) {
+  const limit = deployment.resources?.memory?.[1]
+
+  if (limit === undefined) return
+
+  deployment.variables ??= []
+
+  if (deployment.variables.some((variable) => variable.name === NODE_OPTIONS)) return
+
+  const megabytes = Math.floor((quantity(limit) * HEAP_SHARE) / 2 ** 20)
+
+  deployment.variables.push({
+    name: NODE_OPTIONS,
+    value: `--max-old-space-size=${megabytes}`
+  })
+}
+
+/**
+ * A Kubernetes quantity, in bytes.
+ *
+ * @param {string | number} value
+ * @returns {number}
+ */
+export function quantity(value) {
+  const match = String(value).match(/^(\d+(?:\.\d+)?)([KMGTPE]i?|[kmun])?$/)
+
+  if (match === null) throw new Error(`'${value}' is not a quantity`)
+
+  const [, number, suffix = ''] = match
+  const scale = SUFFIXES[suffix]
+
+  if (scale === undefined) throw new Error(`'${value}' is not a memory quantity`)
+
+  return Number(number) * scale
+}
+
+const NODE_OPTIONS = 'NODE_OPTIONS'
+const HEAP_SHARE = 0.75
+
+const SUFFIXES = {
+  '': 1,
+  K: 1e3,
+  M: 1e6,
+  G: 1e9,
+  T: 1e12,
+  P: 1e15,
+  E: 1e18,
+  Ki: 2 ** 10,
+  Mi: 2 ** 20,
+  Gi: 2 ** 30,
+  Ti: 2 ** 40,
+  Pi: 2 ** 50,
+  Ei: 2 ** 60
+}
+
 function* units(values) {
   if (values.mono !== undefined)
     yield { deployment: values.mono, subject: 'The mono deployment' }

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

@@ -1,7 +1,7 @@
 import { describe, it } from 'node:test'
 import assert from 'node:assert/strict'
 
-import { resources } from './resources.js'
+import { resources, quantity } from './resources.js'
 
 const declared = { cpu: ['100m', '1'], memory: ['100Mi', '1Gi'] }
 
@@ -68,3 +68,62 @@ describe('refusal', () => {
     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/chart/templates/compositions.yaml

@@ -8,6 +8,13 @@ spec:
   # A backstop for stuck rollouts only. Must stay above the `helm upgrade --timeout`
   # the deploy runs with, so a slow but progressing rollout is not marked failed.
   progressDeadlineSeconds: 900
+  strategy:
+    type: RollingUpdate
+    rollingUpdate:
+      # a replacement must pass readiness before a running replica is taken out, and every
+      # replacement starts at once: the rollout takes one start-up, not one per replica
+      maxUnavailable: 0
+      maxSurge: 100%
   selector:
     matchLabels:
       toa/composition: {{ .name }}
@@ -78,9 +85,10 @@ spec:
             httpGet:
               path: {{ .probe.path }}
               port: {{ .probe.port }}
-            periodSeconds: 10
+            # a replica is ready when it says so, not at the next tick of a slow clock
+            periodSeconds: 2
             timeoutSeconds: 3
-            failureThreshold: 3
+            failureThreshold: 5
           {{- end }}
           {{- if .mounts }}
           volumeMounts:

package/src/deployment/chart/templates/mono.yaml

@@ -11,7 +11,7 @@ spec:
     type: RollingUpdate
     rollingUpdate:
       maxUnavailable: 0
-      maxSurge: 50%
+      maxSurge: 100%
   selector:
     matchLabels:
       toa/composition: mono
@@ -75,9 +75,10 @@ spec:
             httpGet:
               path: {{ .probe.path }}
               port: {{ .probe.port }}
-            periodSeconds: 10
+            # a replica is ready when it says so, not at the next tick of a slow clock
+            periodSeconds: 2
             timeoutSeconds: 3
-            failureThreshold: 3
+            failureThreshold: 5
           {{- end }}
           {{- if .mounts }}
           volumeMounts:

package/src/deployment/chart/templates/services.yaml

@@ -12,10 +12,10 @@ spec:
   strategy:
     type: RollingUpdate
     rollingUpdate:
-      # a replacement must pass readiness before a running replica is taken out,
-      # otherwise a single pod serves all traffic while the others start up
+      # a replacement must pass readiness before a running replica is taken out, and every
+      # replacement starts at once: the rollout takes one start-up, not one per replica
       maxUnavailable: 0
-      maxSurge: 50%
+      maxSurge: 100%
   selector:
     matchLabels:
       toa/service: extension-{{ .name }}
@@ -68,9 +68,10 @@ spec:
             httpGet:
               path: {{ .probe.path }}
               port: {{ .probe.port }}
-            periodSeconds: 10
+            # a replica is ready when it says so, not at the next tick of a slow clock
+            periodSeconds: 2
             timeoutSeconds: 3
-            failureThreshold: 3
+            failureThreshold: 5
           {{- end }}
           lifecycle:
             preStop:

package/src/deployment/deployment.js

@@ -1,9 +1,10 @@
 import { join } from 'node:path'
 import { writeFile as write } from 'node:fs/promises'
 import { yaml as jsyaml } from '@toa.io/generic'
-import fs from 'fs-extra'
+import { cp } from 'node:fs/promises'
 
 import { merge, declare, describe } from './.deployment/index.js'
+import { drain } from './drain.js'
 
 export class Deployment {
   #chart
@@ -26,7 +27,7 @@ export class Deployment {
     await Promise.all([
       write(join(target, 'Chart.yaml'), chart),
       write(join(target, 'values.yaml'), values),
-      fs.copy(TEMPLATES, join(target, 'templates'))
+      cp(TEMPLATES, join(target, 'templates'), { recursive: true })
     ])
 
     this.#target = target
@@ -50,6 +51,9 @@ export class Deployment {
       ...args,
       this.#target
     ])
+
+    // ready is not done: the replicas replaced are still draining when helm answers
+    if (options.wait === true) await drain(this.#process, options)
   }
 
   async template(options) {

package/src/deployment/drain.js

@@ -0,0 +1,70 @@
+import { setTimeout as sleep } from 'node:timers/promises'
+
+/**
+ * Waits until no pod of the application is still terminating. `helm --wait` answers once the
+ * replacements are ready, while the replicas they replace are still draining, and a request
+ * made then may land on either.
+ *
+ * @param {toa.operations.Process} process
+ * @param {toa.deployment.installation.Options} options
+ * @returns {Promise<void>}
+ */
+export async function drain(process, options) {
+  const timeout = options.timeout ?? DEFAULT_TIMEOUT
+  const deadline = Date.now() + duration(timeout)
+  const args = ['get', 'pods', '-o', 'json']
+
+  if (options.namespace !== undefined) args.push('-n', options.namespace)
+
+  let announced = false
+
+  for (;;) {
+    const output = await process.execute('kubectl', args, { silently: true })
+    const pods = JSON.parse(output).items.filter(terminating)
+
+    if (pods.length === 0) return
+
+    if (Date.now() >= deadline)
+      throw new Error(`${pods.length} replaced pod(s) still terminating after ${timeout}`)
+
+    if (!announced) {
+      console.log(`Waiting for ${pods.length} replaced pod(s) to terminate`)
+      announced = true
+    }
+
+    await sleep(INTERVAL)
+  }
+}
+
+/**
+ * A pod of the application on its way out. The chart labels every pod it renders under `toa/`,
+ * and nothing else in the namespace is waited for.
+ */
+const terminating = (pod) =>
+  pod.metadata.deletionTimestamp !== undefined &&
+  Object.keys(pod.metadata.labels ?? {}).some((label) => label.startsWith('toa/'))
+
+/**
+ * A helm duration, `12m` or `1h30m` or `90s`, in milliseconds.
+ *
+ * @param {string} value
+ * @returns {number}
+ */
+export function duration(value) {
+  const matches = value.matchAll(/(\d+)(h|ms|m|s)/g)
+
+  let total = 0
+
+  for (const [, amount, unit] of matches) total += Number(amount) * UNITS[unit]
+
+  if (total === 0) throw new Error(`'${value}' is not a duration`)
+
+  return total
+}
+
+const UNITS = { h: 3_600_000, m: 60_000, s: 1_000, ms: 1 }
+
+/** helm's own default for `--timeout` */
+const DEFAULT_TIMEOUT = '5m'
+
+const INTERVAL = 3_000

package/src/deployment/drain.test.js

@@ -0,0 +1,64 @@
+import { it, beforeEach, mock } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { drain, duration } from './drain.js'
+
+/** @type {Array<object[]>} what each poll answers */
+let polls
+
+/** @type {toa.operations.Process} */
+let process
+
+beforeEach(() => {
+  polls = []
+  process = /** @type {toa.operations.Process} */ {
+    execute: mock.fn(async () => JSON.stringify({ items: polls.shift() ?? [] }))
+  }
+})
+
+it('should answer once no pod of the application is terminating', async () => {
+  polls.push([pod('composition-a', true), pod('composition-b')], [pod('composition-b')])
+
+  await drain(process, { namespace: 'acme', timeout: '1m' })
+
+  assert.strictEqual(process.execute.mock.callCount(), 2)
+
+  const [, args, options] = process.execute.mock.calls[0].arguments
+
+  assert.deepStrictEqual(args, ['get', 'pods', '-o', 'json', '-n', 'acme'])
+  assert.deepStrictEqual(options, { silently: true })
+})
+
+it('should not wait for a pod that is not the application', async () => {
+  polls.push([pod('redis-0', true, {})])
+
+  await drain(process, {})
+
+  assert.strictEqual(process.execute.mock.callCount(), 1)
+})
+
+it('should give up at the timeout', async () => {
+  polls.push([pod('composition-a', true)], [pod('composition-a', true)])
+
+  await assert.rejects(drain(process, { timeout: '1ms' }), /still terminating after 1ms/)
+})
+
+it('should read a helm duration', () => {
+  assert.strictEqual(duration('12m'), 720_000)
+  assert.strictEqual(duration('1h30m'), 5_400_000)
+  assert.strictEqual(duration('90s'), 90_000)
+  assert.throws(() => duration('soon'), /not a duration/)
+})
+
+/**
+ * @param {string} name
+ * @param {boolean} [terminating]
+ * @param {object} [labels]
+ */
+function pod(name, terminating = false, labels = { 'toa/composition': 'a' }) {
+  const metadata = { name, labels }
+
+  if (terminating) metadata.deletionTimestamp = '2026-01-01T00:00:00Z'
+
+  return { metadata }
+}

package/src/deployment/images/bundle.js

@@ -0,0 +1,82 @@
+import { basename, join } from 'node:path'
+import { cp } from 'node:fs/promises'
+import { createHash } from 'node:crypto'
+
+import { Image } from './image.js'
+import { Dependencies } from './dependencies.js'
+import { declare } from './format.js'
+
+/**
+ * Components in one image: their sources laid over their dependencies, which are an image
+ * of their own (see `Dependencies`). What is built here is the sources layer alone.
+ *
+ * @implements {toa.deployment.images.Bundle}
+ * @abstract
+ */
+export class Bundle extends Image {
+  /** @type {Dependencies} */
+  dependencies
+
+  /** @type {string | undefined} */
+  image
+
+  /** @type {toa.norm.Component[]} */
+  components
+
+  constructor(scope, runtime, registry, composition) {
+    super(scope, runtime, registry)
+
+    this.image = composition.image
+    this.components = composition.components
+    this.dependencies = new Dependencies(scope, runtime, registry, this)
+  }
+
+  tag() {
+    this.dependencies.tag()
+    super.tag()
+  }
+
+  get version() {
+    const hash = createHash('sha256')
+
+    for (const component of this.components) {
+      hash.update(component.locator.id)
+      hash.update(component.version)
+    }
+
+    // laid over a different base is a different image, whatever the sources
+    hash.update(this.dependencies.version)
+
+    return hash.digest('hex').slice(0, 8)
+  }
+
+  get base() {
+    return this.dependencies.reference
+  }
+
+  /**
+   * What to say when the components ask for different base images.
+   *
+   * @abstract
+   * @returns {string}
+   */
+  conflict() {
+    throw new Error('Not implemented')
+  }
+
+  async prepare(root) {
+    const context = await super.prepare(root)
+
+    for (const component of this.components) {
+      const target = join(context, component.locator.label)
+
+      // what was installed in the workspace is not what the image installs
+      await cp(component.path, target, { recursive: true, filter: sources })
+      await declare(component.path, target, component.locator.label)
+    }
+
+    return context
+  }
+}
+
+const sources = (path) => basename(path) !== 'node_modules'

package/src/deployment/images/composition.Dockerfile

@@ -1,19 +1,10 @@
 FROM {{build.image}}
 
-{{build.arguments}}
-
-ENV NODE_ENV=production
-RUN if [ "{{runtime.registry}}" != "" ]; then npm set registry {{runtime.registry}}; fi
-RUN if [ "{{runtime.proxy}}" != "" ]; then npm set proxy {{runtime.proxy}}; fi
-
-WORKDIR /composition
-COPY --chown=node:node . /composition
-
-{{build.run}}
-
-# run 'npm i' in each component
-RUN --mount=type=cache,target=/root/.npm,sharing=locked \
-  for entry in *; do if grep -qs '"dependencies"' "$entry/package.json"; then (cd $entry && npm i --omit=dev); fi; done
+# the one instruction that touches the filesystem, and linked: the base is not pulled to lay
+# the sources over it, and a push carries this layer and a manifest, not the base's layers.
+# Owned by root like the dependencies beside them: a linked layer knows no user by name,
+# and the runtime reads its sources, it does not write them
+COPY --link . /composition
 
 USER node
 CMD toa compose *

package/src/deployment/images/composition.js

@@ -1,75 +1,23 @@
 import { join } from 'node:path'
-import fs from 'fs-extra'
-import { createHash } from 'node:crypto'
 
-import { Image } from './image.js'
-import { declare } from './format.js'
+import { Bundle } from './bundle.js'
 
-export class Composition extends Image {
+export class Composition extends Bundle {
   dockerfile = join(import.meta.dirname, 'composition.Dockerfile')
 
   #name
-  #image
-  #components
 
   constructor(scope, runtime, registry, composition) {
-    super(scope, runtime, registry)
+    super(scope, runtime, registry, composition)
 
     this.#name = composition.name
-    this.#image = composition.image
-    this.#components = composition.components
   }
 
   get name() {
     return 'composition-' + this.#name
   }
 
-  get version() {
-    const hash = createHash('sha256')
-
-    for (const component of this.#components) {
-      hash.update(component.locator.id)
-      hash.update(component.version)
-    }
-
-    return hash.digest('hex').slice(0, 8)
-  }
-
-  get base() {
-    if (this.#image !== undefined) return this.#image
-
-    const images = new Set(this.#components.map((component) => component.build?.image))
-
-    if (images.size > 1)
-      throw new Error(
-        `Composition '${this.#name}' requires different base images for its components. Specify base image for the composition in the context.`
-      )
-
-    return images.values().next().value
-  }
-
-  get run() {
-    const commands = []
-
-    for (const component of this.#components) {
-      const run = component.build?.run
-
-      if (run !== undefined) commands.push(run)
-    }
-
-    return commands.join('\n')
-  }
-
-  async prepare(root) {
-    const context = await super.prepare(root)
-
-    for (const component of this.#components) {
-      const target = join(context, component.locator.label)
-
-      await fs.copy(component.path, target)
-      await declare(component.path, target, component.locator.label)
-    }
-
-    return context
+  conflict() {
+    return `Composition '${this.#name}' requires different base images for its components. Specify base image for the composition in the context.`
   }
 }

package/src/deployment/images/dependencies.Dockerfile

@@ -0,0 +1,16 @@
+FROM {{build.image}}
+
+{{build.arguments}}
+
+ENV NODE_ENV=production
+RUN if [ "{{runtime.registry}}" != "" ]; then npm set registry {{runtime.registry}}; fi
+RUN if [ "{{runtime.proxy}}" != "" ]; then npm set proxy {{runtime.proxy}}; fi
+
+WORKDIR /composition
+COPY --chown=node:node . /composition
+
+{{build.run}}
+
+# the context holds the manifests alone, so this is every dependency and none of the sources
+RUN --mount=type=cache,target=/root/.npm,sharing=locked \
+  for entry in *; do if grep -qs '"dependencies"' "$entry/package.json"; then (cd $entry && npm i --omit=dev); fi; done