@toa.io/operations 1.0.0-alpha.296 → 1.0.0-alpha.298

package/CHANGELOG.md

@@ -3,6 +3,21 @@
 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.298](https://github.com/toa-io/toa/compare/v1.0.0-alpha.297...v1.0.0-alpha.298) (2026-09-08)
+
+### Features
+
+* **operations:** tag a deploy with the environment so registries can prune ([7247c35](https://github.com/toa-io/toa/commit/7247c35f33fb34dcfb3ffa04b196c14bfb3d5620))
+
+
+# [1.0.0-alpha.297](https://github.com/toa-io/toa/compare/v1.0.0-alpha.296...v1.0.0-alpha.297) (2026-09-08)
+
+**Note:** Version bump only for package @toa.io/operations
+
+
+
+
+
 # [1.0.0-alpha.296](https://github.com/toa-io/toa/compare/v1.0.0-alpha.295...v1.0.0-alpha.296) (2026-09-08)
 
 ### Bug Fixes

package/image/runtime.Dockerfile

@@ -7,12 +7,8 @@ ARG VERSION
 WORKDIR /toa
 
 # mounted rather than written: npm's cache is a hundred megabytes, and a layer keeps whatever
-# the command left behind.
-# `--legacy-peer-deps` installs no peer this does not ask for: `promex`, `reretry` and
-# `matchacho` declare `typescript` a peer without marking it optional, and nothing here imports
-# it. Every other peer in the closure is a dependency of the runtime's already. Drop the flag
-# once those three are published with `peerDependenciesMeta`.
+# the command left behind
 RUN --mount=type=cache,target=/root/.npm,sharing=locked \
-  npm i @toa.io/runtime@${VERSION} --omit=dev --legacy-peer-deps
+  npm i @toa.io/runtime@${VERSION} --omit=dev
 
 ENV PATH=/toa/node_modules/.bin:$PATH

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/operations",
-  "version": "1.0.0-alpha.296",
+  "version": "1.0.0-alpha.298",
   "type": "module",
   "description": "Toa Deployment",
   "homepage": "https://toa.io",
@@ -30,8 +30,9 @@
   "dependencies": {
     "@toa.io/generic": "1.0.0-alpha.292",
     "@toa.io/kubernetes": "1.0.0-alpha.293",
-    "@toa.io/norm": "1.0.0-alpha.296",
+    "@toa.io/norm": "1.0.0-alpha.298",
+    "oxc-parser": "0.149.0",
     "paseto": "4.0.0"
   },
-  "gitHead": "d0fd4f9d13483f763acd9dd2b3c3eb8cb8856524"
+  "gitHead": "334fad8726adfa7507462c33b509ce7db9db853f"
 }

package/readme.md

@@ -79,7 +79,10 @@ downloads nor uploads the dependencies again. The same holds for `mono`.
 Beside each component's sources the layer carries `manifest.toa.json`, the manifest as this
 build normalised it. A composition reads it instead of normalising again, so it loads no
 bridge to read what a module declares; a workspace has no such file and is read as it always
-was. What a build cannot express there — a prototype in a directory of the application's own
+was. A component an extension ships has none either — its package is published long before any
+image is built — and is read from the digest `@toa.io/definitions` carries, which a deploy has
+always read. So nothing that runs reads a module's source, and `oxc-parser` is installed only
+where a manifest is normalised: a workspace and a deploy, both through `@toa.io/operations`. What a build cannot express there — a prototype in a directory of the application's own
 rather than in a package — fails the build, where before it failed the container.
 
 A pushed image builds on the `toa` container builder, whose registry exporter is what lays
@@ -175,3 +178,46 @@ a secret containing required credentials can be specified using `registry.creden
 registry:
   credentials: docker-credentials-secret-name
 ```
+
+#### Toa images
+
+Each release publishes `ghcr.io/toa-io/runtime:<version>` and, beside it, `:alpha` or `:latest`.
+The extension services share that 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
+```
+
+Untagged manifests are deleted. A prerelease older than 90 days, and not among the last 30, is
+deleted with the four service images of that version. `:alpha`, `:latest`, and a version without
+a pre-release suffix stay.
+
+An application still on a deleted prerelease cannot pull `registry.services: published` and cannot
+rebuild `FROM` that runtime. Images already in `registry.base` keep running. Stay inside the
+window, or pin a graduated release.
+
+#### Userspace images
+
+`toa deploy production` writes two tags on the same composition image (`mono` and a service
+`registry.services: build` built are the same):
+
+- `<name>:<hash>` — what the chart pins. A hash of the runtime and the sources. `toa push` writes
+  this tag and nothing else.
+- `<name>:production` — moved onto that image. The next production deploy moves it again.
+
+`deps-<hash>` is not tagged with the environment. Do not name an environment eight hex digits, or
+`deps-` plus eight: a retention job would treat it as a content tag.
+
+A job the application runs deletes every `<hash>` and `deps-<hash>` older than 7 days, except the
+last 5, except the image `:production` (or `:staging`, or `:latest`) currently names. Then:
+
+```shell
+$ doctl registries garbage-collection start --include-untagged-manifests <registry>
+```
+
+Rollback is only those 7 days, those last 5, and whatever the environment tag still names. Turn
+the job on after the first deploy that writes that tag. The first garbage collection returns the
+space the old tags held, and blocks pushes while it runs.

package/src/deployment/factory.js

@@ -61,7 +61,7 @@ export class Factory {
       this.#image
     )
 
-    return new Operator(deployment, this.#registry)
+    return new Operator(deployment, this.#registry, this.#context.environment)
   }
 
   registry() {

package/src/deployment/images/dependencies.Dockerfile

@@ -19,7 +19,5 @@ RUN --mount=type=cache,target=/root/.npm,sharing=locked \
 # what the extensions need for what these components declare: installed beside the extension
 # that reads the declaration, in Toa's own install, because that is where Node resolves an
 # extension's imports from — and one copy for the composition rather than one per component
-# `--legacy-peer-deps` for the reason the base image installs with it: what is added here
-# re-resolves the tree, and a peer nothing imports comes back with it — 23 MB of `typescript`
 RUN --mount=type=cache,target=/root/.npm,sharing=locked \
-  if [ -s .packages ]; then npm i --prefix /toa --omit=dev --legacy-peer-deps $(cat .packages); fi
+  if [ -s .packages ]; then npm i --prefix /toa --omit=dev $(cat .packages); fi

package/src/deployment/images/dependencies.test.js

@@ -176,9 +176,7 @@ describe('prepare', () => {
 
     const dockerfile = await readFile(join(context, 'Dockerfile'), 'utf8')
 
-    assert.ok(
-      dockerfile.includes('npm i --prefix /toa --omit=dev --legacy-peer-deps $(cat .packages)')
-    )
+    assert.ok(dockerfile.includes('npm i --prefix /toa --omit=dev $(cat .packages)'))
   })
 
   it('should hold what a service the composition runs brings', async () => {

package/src/deployment/images/format.test.js

@@ -111,3 +111,39 @@ describe('normalized', () => {
     assert.strictEqual(read.locator.id, 'todos.tasks')
   })
 })
+
+describe('a service image', () => {
+  it('installs what its components declare beside Toa as well', async () => {
+    const { Service } = await import('./service.js')
+
+    const path = join(root, 'extension')
+    const component = join(path, 'components', 'octets')
+
+    await mkdir(component, { recursive: true })
+    await writeFile(join(path, 'package.json'), JSON.stringify({ name: 'ext', version: '1' }))
+    await writeFile(
+      join(component, 'package.json'),
+      JSON.stringify({ dependencies: { cloudinary: '2.11.0', jose: '6.2.10' } })
+    )
+
+    const service = new Service('', { version: '1' }, {}, path, {
+      group: 'g',
+      name: 'n',
+      version: '1'
+    })
+
+    service.reference = 'probe'
+
+    const context = await service.prepare(join(root, 'service'))
+
+    // what an extension imports on a component's behalf is imported from where Toa is
+    assert.strictEqual(
+      await readFile(join(context, '.packages'), 'utf8'),
+      'cloudinary@2.11.0\njose@6.2.10'
+    )
+
+    const dockerfile = await readFile(join(context, 'Dockerfile'), 'utf8')
+
+    assert.ok(dockerfile.includes('npm i --prefix /toa --omit=dev $(cat .packages)'))
+  })
+})

package/src/deployment/images/service.Dockerfile

@@ -16,6 +16,11 @@ RUN --mount=type=cache,target=/root/.npm,sharing=locked \
 RUN --mount=type=cache,target=/root/.npm,sharing=locked \
   for entry in components/*; do if grep -qs '"dependencies"' "$entry/package.json"; then (cd $entry && npm i --omit=dev); fi; done
 
+# and beside Toa as well, because what an extension imports on a component's behalf — a storage
+# provider's SDK — is imported from where the extension is, which is `/toa` and not here
+RUN --mount=type=cache,target=/root/.npm,sharing=locked \
+  if [ -s .packages ]; then npm i --prefix /toa --omit=dev $(cat .packages); fi
+
 # no USER: the runtime drops to `node` itself, and only a process that started as root can
 # close its environment under /proc — see runtime/runtime/bin/toa
 CMD toa serve .

package/src/deployment/images/service.js

@@ -1,8 +1,9 @@
 import { createRequire } from 'node:module'
 import { join, dirname } from 'node:path'
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
 
 import { Image } from './image.js'
-import { cp } from 'node:fs/promises'
+import { cp, writeFile } from 'node:fs/promises'
 
 // a service is named the way a package is, and its directory is where it lives
 const require = createRequire(import.meta.url)
@@ -60,11 +61,46 @@ export class Service extends Image {
     const context = await super.prepare(root)
 
     await cp(this.#path, context, { recursive: true })
+    await writeFile(join(context, PACKAGES), this.#packages().join('\n'))
 
     return context
   }
+
+  /**
+   * What the components this service runs declare, as `name@version`.
+   *
+   * Each is installed beside its component, where the component's own modules import it, and
+   * beside Toa, where an extension that imports on a component's behalf is — a storage
+   * provider's SDK is imported by `@toa.io/extensions.storages`, not by the component that
+   * declares the storage.
+   *
+   * @returns {string[]}
+   */
+  #packages() {
+    const directory = join(this.#path, 'components')
+
+    if (!existsSync(directory)) return []
+
+    /** @type {Record<string, string>} */
+    const packages = {}
+
+    for (const label of readdirSync(directory)) {
+      const manifest = join(directory, label, 'package.json')
+
+      if (!existsSync(manifest)) continue
+
+      Object.assign(packages, JSON.parse(readFileSync(manifest, 'utf8')).dependencies)
+    }
+
+    return Object.entries(packages)
+      .map(([name, version]) => `${name}@${version}`)
+      .sort()
+  }
 }
 
+/** Where the install reads what the components need, one `name@version` per line. */
+const PACKAGES = '.packages'
+
 /**
  * Where the extension is installed, which is what its image is built from. A deploy install
  * carries what an extension declares and not the extension, so a service is built only where

package/src/deployment/operator.js

@@ -7,13 +7,18 @@ export class Operator {
   /** @type {toa.deployment.Registry} */
   #registry
 
+  /** @type {string | undefined} */
+  #environment
+
   /**
-   * @param deployment {toa.deployment.Deployment}
-   * @param registry {toa.deployment.Registry}
+   * @param {toa.deployment.Deployment} deployment
+   * @param {toa.deployment.Registry} registry
+   * @param {string} [environment]
    */
-  constructor(deployment, registry) {
+  constructor(deployment, registry, environment) {
     this.#deployment = deployment
     this.#registry = registry
+    this.#environment = environment
   }
 
   async export(path) {
@@ -36,6 +41,7 @@ export class Operator {
     options = Object.assign({}, OPTIONS, options)
 
     await Promise.all([this.export(), this.push()])
+    await this.#registry.alias(this.#environment)
     await this.#deployment.install(options)
   }
 

package/src/deployment/operator.test.js

@@ -43,3 +43,52 @@ describe('env', () => {
     assert.deepStrictEqual(output, variables)
   })
 })
+
+describe('install', () => {
+  /** @type {toa.deployment.Deployment} */
+  let deployment
+
+  /** @type {toa.deployment.Registry} */
+  let registry
+
+  beforeEach(() => {
+    deployment = /** @type {toa.deployment.Deployment} */ {
+      export: mock.fn(async () => {}),
+      install: mock.fn(async () => {})
+    }
+    registry = /** @type {toa.deployment.Registry} */ {
+      push: mock.fn(async () => {}),
+      alias: mock.fn(async () => {})
+    }
+  })
+
+  it('should tag the environment after a push', async () => {
+    const order = []
+
+    registry.push = mock.fn(async () => {
+      order.push('push')
+    })
+    registry.alias = mock.fn(async () => {
+      order.push('alias')
+    })
+    deployment.install = mock.fn(async () => {
+      order.push('install')
+    })
+
+    operator = new Operator(deployment, registry, 'production')
+
+    await operator.install()
+
+    assert.deepStrictEqual(order, ['push', 'alias', 'install'])
+    assert.deepStrictEqual(registry.alias.mock.calls[0].arguments, ['production'])
+  })
+
+  it('should not tag the environment on push', async () => {
+    operator = new Operator(deployment, registry, 'production')
+
+    await operator.push()
+
+    assert.strictEqual(registry.push.mock.callCount(), 1)
+    assert.strictEqual(registry.alias.mock.callCount(), 0)
+  })
+})

package/src/deployment/registry.js

@@ -50,6 +50,24 @@ export class Registry {
     await this.#run(true)
   }
 
+  /**
+   * A second tag on each workload image, the environment, so a retention job can see what
+   * a deploy left running. `deps-*` is not in `#images`.
+   *
+   * @param {string} [environment]
+   * @returns {Promise<void>}
+   */
+  async alias(environment) {
+    if (
+      typeof environment !== 'string' ||
+      environment === '' ||
+      CONTENT_TAG.test(environment)
+    )
+      return
+
+    await Promise.all(this.#images.map((image) => this.#alias(image, environment)))
+  }
+
   tags() {
     return this.#images.map((image) => image.reference)
   }
@@ -159,6 +177,22 @@ export class Registry {
     await this.#process.execute('docker', args)
   }
 
+  /**
+   * @param {toa.deployment.images.Image} image
+   * @param {string} environment
+   * @returns {Promise<void>}
+   */
+  async #alias(image, environment) {
+    const target = retag(image.reference, environment)
+    const args = ['buildx', 'imagetools', 'create', '--tag', target]
+
+    if (LOCAL.test(image.reference)) args.push('--insecure')
+
+    args.push(image.reference)
+
+    await this.#process.execute('docker', args)
+  }
+
   async exists(tag) {
     const args = ['manifest', 'inspect']
 
@@ -230,8 +264,20 @@ async function pool(items, work) {
   await Promise.all(workers)
 }
 
+/**
+ * @param {string} reference
+ * @param {string} tag
+ * @returns {string}
+ */
+function retag(reference, tag) {
+  return reference.slice(0, reference.lastIndexOf(':') + 1) + tag
+}
+
 const BUILDER = 'toa'
 
+/** An environment named this way is a content tag, and must not be moved as one. */
+const CONTENT_TAG = /^(deps-)?[0-9a-f]{8}$/
+
 /** A reference into a registry on this machine, by any of the names it goes by. */
 const LOCAL = /^(localhost|127\.\d+\.\d+\.\d+|host\.docker\.internal)(:\d+)?\//
 

package/src/deployment/registry.test.js

@@ -15,16 +15,7 @@ let images
 
 beforeEach(() => {
   images = []
-  process = /** @type {toa.operations.Process} */ {
-    execute: mock.fn(async (cmd, args) => {
-      if (args[0] === 'manifest') throw new Error('manifest unknown')
-
-      if (args[0] === 'buildx' && args[1] === 'inspect')
-        throw new Error('builder not found')
-
-      return ''
-    })
-  }
+  process = execute()
 
   factory = /** @type {toa.deployment.images.Factory} */ {
     composition: () => createImage('composition-mono', true),
@@ -336,25 +327,115 @@ it('should skip build when image already exists', async () => {
   )
 })
 
+it('should tag the environment on each workload image', async () => {
+  const proc = execute()
+  const registry = createRegistry(
+    { base: 'example.com/reg', platforms: ['linux/amd64'] },
+    proc
+  )
+
+  registry.composition(/** @type {any} */ ({}))
+  registry.service('.', /** @type {any} */ ({}))
+
+  await registry.alias('production')
+
+  const aliases = imagetools(proc)
+  const tags = aliases.map((args) => args[args.indexOf('--tag') + 1]).sort()
+  const sources = aliases.map((args) => args.at(-1)).sort()
+
+  assert.strictEqual(aliases.length, 2)
+  assert.deepStrictEqual(tags, [
+    'example.com/reg/acme/composition-mono:production',
+    'example.com/reg/acme/extension-realtime:production'
+  ])
+  assert.deepStrictEqual(sources, [
+    'example.com/reg/acme/composition-mono:abcdef12',
+    'example.com/reg/acme/extension-realtime:abcdef12'
+  ])
+})
+
+it('should not tag deps images with the environment', async () => {
+  const proc = execute()
+  const registry = createRegistry(
+    { base: 'example.com/reg', platforms: ['linux/amd64'] },
+    proc
+  )
+
+  registry.composition(/** @type {any} */ ({}))
+
+  await registry.alias('production')
+
+  const aliases = imagetools(proc)
+
+  assert.strictEqual(aliases.length, 1)
+  assert.ok(!aliases[0].some((arg) => String(arg).includes(':deps-')))
+})
+
+it('should not tag the environment on push', async () => {
+  const proc = execute()
+  const registry = createRegistry(
+    { base: 'example.com/reg', platforms: ['linux/amd64'] },
+    proc
+  )
+
+  registry.composition(/** @type {any} */ ({}))
+
+  await registry.push()
+
+  assert.deepStrictEqual(imagetools(proc), [])
+})
+
+it('should not move a content tag as the environment', async () => {
+  const proc = execute()
+  const registry = createRegistry(
+    { base: 'example.com/reg', platforms: ['linux/amd64'] },
+    proc
+  )
+
+  registry.composition(/** @type {any} */ ({}))
+
+  await registry.alias('abcdef12')
+  await registry.alias('deps-12345678')
+
+  assert.deepStrictEqual(imagetools(proc), [])
+})
+
+it('should not tag without an environment', async () => {
+  const proc = execute()
+  const registry = createRegistry(
+    { base: 'example.com/reg', platforms: ['linux/amd64'] },
+    proc
+  )
+
+  registry.composition(/** @type {any} */ ({}))
+
+  await registry.alias()
+  await registry.alias('')
+
+  assert.deepStrictEqual(imagetools(proc), [])
+})
+
 it('should probe a local registry as insecure', async () => {
-  process.execute = mock.fn(async () => '')
+  const proc = execute()
 
-  const registry = createRegistry({ base: 'localhost:5000', platforms: null })
+  proc.execute = mock.fn(async () => '')
 
-  factory.composition = () => {
-    const image = createImage('composition-mono', true)
+  const image = createImage('composition-mono', true)
 
-    image.reference = 'localhost:5000/acme/composition-mono:abcdef12'
-    image.dependencies.reference = 'localhost:5000/acme/composition-mono:deps-12345678'
+  image.reference = 'localhost:5000/acme/composition-mono:abcdef12'
+  image.dependencies.reference = 'localhost:5000/acme/composition-mono:deps-12345678'
 
-    return image
-  }
+  const registry = new Registry(
+    { base: 'localhost:5000', platforms: null },
+    { composition: () => image, service: factory.service, mono: factory.mono },
+    proc
+  )
 
   registry.composition(/** @type {any} */ ({}))
 
   await registry.build()
 
-  const probes = process.execute.mock.calls
+  const probes = proc.execute.mock.calls
     .filter(({ arguments: [, args] }) => args[0] === 'manifest')
     .map(({ arguments: [, args] }) => args)
 
@@ -364,12 +445,56 @@ it('should probe a local registry as insecure', async () => {
     assert.deepStrictEqual(args.slice(0, 3), ['manifest', 'inspect', '--insecure'])
 })
 
+it('should tag a local registry as insecure', async () => {
+  const proc = execute()
+  const image = createImage('composition-mono', true)
+
+  image.reference = 'localhost:5000/acme/composition-mono:abcdef12'
+  image.dependencies.reference = 'localhost:5000/acme/composition-mono:deps-12345678'
+
+  const registry = new Registry(
+    { base: 'localhost:5000', platforms: null },
+    { composition: () => image, service: factory.service, mono: factory.mono },
+    proc
+  )
+
+  registry.composition(/** @type {any} */ ({}))
+
+  await registry.alias('production')
+
+  assert.deepStrictEqual(imagetools(proc), [
+    [
+      'buildx',
+      'imagetools',
+      'create',
+      '--tag',
+      'localhost:5000/acme/composition-mono:production',
+      '--insecure',
+      'localhost:5000/acme/composition-mono:abcdef12'
+    ]
+  ])
+})
+
 /**
  * @param {object} [registry]
  * @returns {Registry}
  */
-function createRegistry(registry = {}) {
-  return new Registry(registry, factory, process)
+function createRegistry(registry = {}, proc = process) {
+  return new Registry(registry, factory, proc)
+}
+
+/** @returns {toa.operations.Process} */
+function execute() {
+  return /** @type {toa.operations.Process} */ {
+    execute: mock.fn(async (cmd, args) => {
+      if (args[0] === 'manifest') throw new Error('manifest unknown')
+
+      if (args[0] === 'buildx' && args[1] === 'inspect')
+        throw new Error('builder not found')
+
+      return ''
+    })
+  }
 }
 
 /**
@@ -397,6 +522,13 @@ function createImage(name, bundle = false) {
   return image
 }
 
+/** @returns {string[][]} the arguments of every imagetools run */
+function imagetools(proc = process) {
+  return proc.execute.mock.calls
+    .filter(({ arguments: [, args] }) => args[0] === 'buildx' && args[1] === 'imagetools')
+    .map(({ arguments: [, args] }) => args)
+}
+
 /** @returns {string[][]} the arguments of every build run */
 function builds() {
   return process.execute.mock.calls

package/types/_deployment/registry.d.ts

@@ -14,6 +14,9 @@ declare namespace toa.deployment {
 
     push(): Promise<void>
 
+    /** Point each workload image at `environment` (`:production`). `deps-*` is not tagged. */
+    alias(environment?: string): Promise<void>
+
     tags(): string[]
   }
 }