@toa.io/operations 1.0.0-alpha.261 → 1.0.0-alpha.263

package/CHANGELOG.md

@@ -3,6 +3,42 @@
 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.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)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/operations",
-  "version": "1.0.0-alpha.261",
+  "version": "1.0.0-alpha.263",
   "description": "Toa Deployment",
   "homepage": "https://toa.io",
   "author": {
@@ -29,10 +29,10 @@
   "dependencies": {
     "@toa.io/filesystem": "1.0.0-alpha.254",
     "@toa.io/generic": "1.0.0-alpha.254",
-    "@toa.io/norm": "1.0.0-alpha.259",
+    "@toa.io/norm": "1.0.0-alpha.263",
     "@toa.io/yaml": "1.0.0-alpha.254",
     "execa": "5.1.1",
     "fs-extra": "11.1.1"
   },
-  "gitHead": "0351da80ae8f1757c950a6787521941931d400c4"
+  "gitHead": "165daa284bb7a75907a593fde359e3553b083417"
 }

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

@@ -0,0 +1,37 @@
+'use strict'
+
+/**
+ * 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.
+ */
+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}'` }
+}
+
+exports.resources = resources

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

@@ -2,7 +2,7 @@
 
 const { addVariables } = require('./variables')
 
-function services (services, variables, probe) {
+function services (services, variables, probe, ingress) {
   for (const service of services) {
     addVariables(service, variables)
 
@@ -10,7 +10,29 @@ function services (services, variables, probe) {
       delete service.probe
     else if (service.probe === undefined && probe !== undefined && probe !== false)
       service.probe = probe
+
+    if (service.ingress !== undefined)
+      expose(service, ingress)
   }
 }
 
+/**
+ * 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.`)
+}
+
 exports.services = services

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

@@ -0,0 +1,61 @@
+'use strict'
+
+const { services } = require('./services')
+
+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'] })
+
+  expect(list[0].ingress).toBeUndefined()
+})
+
+/*
+ * 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' } })
+
+  expect(list[0].ingress).toStrictEqual({
+    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' })
+
+  expect(list[0].ingress.hosts).toStrictEqual(['own.dev'])
+  expect(list[0].ingress.class).toStrictEqual('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' })
+
+  expect(list[0].ingress.class).toStrictEqual('alb')
+})
+
+it('should reject an ingress with nowhere to land', () => {
+  const list = [service({ port: 8002, ingress: { path: '/.introspection' } })]
+
+  expect(() => services(list, {}, undefined, undefined))
+    .toThrow("Service 'group-one' declares an ingress, but no hosts are defined")
+})
+
+it('should reject an ingress without a port', () => {
+  const list = [service({ ingress: { path: '/.introspection' } })]
+
+  expect(() => services(list, {}, undefined, { hosts: ['api.dev'] }))
+    .toThrow("Service 'group-one' declares an ingress, but no port")
+})

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

@@ -3,6 +3,7 @@
 const desc = require('./.describe')
 const { addVariables } = require('./.describe/variables')
 const { addMounts } = require('./.describe/mounts')
+const { resources } = require('./.describe/resources')
 
 const describe = (context, compositions, dependency, image) => {
   const { services } = dependency
@@ -26,26 +27,34 @@ const describe = (context, compositions, dependency, image) => {
 
     mono.image = image.reference
 
-    return {
+    const values = {
       compositions: [],
       components: mono.components,
       services: [],
       credentials,
       mono
     }
+
+    resources(context, values)
+
+    return values
   }
 
   const components = desc.components(compositions)
 
   desc.compositions(compositions, dependency)
-  desc.services(services, dependency.variables, dependency.probe)
+  desc.services(services, dependency.variables, dependency.probe, context.ingress)
 
-  return {
+  const values = {
     compositions,
     components,
     services,
     credentials
   }
+
+  resources(context, values)
+
+  return values
 }
 
 function unit (context, dependency) {
@@ -61,6 +70,9 @@ function unit (context, dependency) {
     variables: []
   }
 
+  if (context.ingress !== undefined)
+    mono.ingress = Object.assign({}, context.ingress)
+
   addVariables(mono, variables, Object.keys(variables))
   addMounts(mono, dependency.mounts, Object.keys(mounts))
 
@@ -70,11 +82,19 @@ function unit (context, dependency) {
         if (!mono.variables.some((item) => item.name === variable.name))
           mono.variables.push(variable)
 
+    // every declared port is bound by the single mono process, none is primary
     if (service.port !== undefined)
-      mono.port = service.port
+      (mono.backends ??= []).push({ port: service.port, path: service.ingress?.path ?? '/' })
 
-    if (service.ingress !== undefined)
-      mono.ingress = service.ingress
+    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])]
+    }
 
     if (service.probe !== undefined && service.probe !== false)
       mono.probe = service.probe
@@ -83,6 +103,9 @@ function unit (context, dependency) {
   if (mono.probe === undefined && dependency.probe !== undefined && dependency.probe !== false)
     mono.probe = dependency.probe
 
+  // the more specific prefix must come first, whatever the controller's tie-break
+  mono.backends?.sort((a, b) => b.path.length - a.path.length)
+
   return mono
 }
 

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

@@ -27,9 +27,42 @@ const merge = (dependencies) => {
     if (dependency.probe !== undefined) probe = dependency.probe
   }
 
+  reserve(services, probe)
+
   return { references, services, proxies, variables, mounts, probe }
 }
 
+/**
+ * In Kubernetes these are separate pods, but `toa mono` and a local run put every
+ * service in one process — so a port may be claimed once and only once.
+ */
+const reserve = (services, probe) => {
+  const claimed = new Map()
+
+  if (probe !== undefined && probe !== false)
+    claimed.set(probe.port, 'the readiness probe')
+
+  for (const service of services)
+    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}`)
+
+      claimed.set(port, claimant)
+    }
+}
+
+function * ports (service) {
+  const name = `'${service.group}-${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) => {
   for (const [component, vars] of Object.entries(variables)) {
     if (merged[component] === undefined) merged[component] = []

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

@@ -0,0 +1,74 @@
+'use strict'
+
+const { merge } = require('./merge')
+
+const service = (name, extra = {}) => ({ group: '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 })] }
+  ])
+
+  expect(merged.services).toHaveLength(2)
+})
+
+/*
+ * In Kubernetes these are separate pods, but `toa mono` and a local run put every
+ * service in one process.
+ */
+describe('port reservation', () => {
+  it('should reject two services claiming one port', () => {
+    const dependencies = [
+      { services: [service('one', { port: 8000 })] },
+      { services: [service('two', { port: 8000 })] }
+    ]
+
+    expect(() => merge(dependencies))
+      .toThrow("Port 8000 is claimed by both 'group-one' and 'group-two'")
+  })
+
+  it('should reject a service claiming the port of the readiness probe', () => {
+    const dependencies = [
+      { probe: { path: '/.ready', port: 8001 } },
+      { services: [service('one', { port: 8001 })] }
+    ]
+
+    expect(() => merge(dependencies))
+      .toThrow("Port 8001 is claimed by both the readiness probe and 'group-one'")
+  })
+
+  it('should reject a probe claiming the port of another service', () => {
+    const dependencies = [
+      { services: [service('one', { port: 8000 })] },
+      { services: [service('two', { port: 8002, probe: { path: '/.ready', port: 8000 } })] }
+    ]
+
+    expect(() => merge(dependencies))
+      .toThrow("Port 8000 is claimed by both 'group-one' and the readiness probe of 'group-two'")
+  })
+
+  it('should allow a service to probe its own port', () => {
+    const dependencies = [
+      { services: [service('one', { port: 8000, probe: { path: '/.ready', port: 8000 } })] }
+    ]
+
+    expect(() => merge(dependencies)).not.toThrow()
+  })
+
+  it('should ignore services without a port', () => {
+    const dependencies = [
+      { services: [service('one'), service('two')] }
+    ]
+
+    expect(() => merge(dependencies)).not.toThrow()
+  })
+
+  it('should ignore a disabled probe', () => {
+    const dependencies = [
+      { probe: false, services: [service('one', { port: 8000, probe: false })] }
+    ]
+
+    expect(() => merge(dependencies)).not.toThrow()
+  })
+})

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

@@ -26,12 +26,14 @@ spec:
       containers:
         - name: mono
           image: {{ .image }}
-          {{- if .port }}
+          {{- if or .backends .probe }}
           ports:
+            {{- range .backends }}
             - containerPort: {{ .port }}
-          {{- else if .probe }}
-          ports:
+            {{- end }}
+            {{- if .probe }}
             - containerPort: {{ .probe.port }}
+            {{- end }}
           {{- end }}
           {{- if .resources }}
           resources:
@@ -108,7 +110,7 @@ spec:
           labelSelector:
             matchLabels:
               toa.io/composition: mono
-{{- if .port }}
+{{- if .backends }}
 ---
 apiVersion: v1
 kind: Service
@@ -119,10 +121,12 @@ spec:
   selector:
     toa.io/composition: mono
   ports:
+    {{- range .backends }}
     - name: port-{{ .port }}
       protocol: TCP
       port: {{ .port }}
       targetPort: {{ .port }}
+    {{- end }}
 {{- end }}
 {{- if .ingress }}
 ---
@@ -138,29 +142,34 @@ spec:
   {{- if .ingress.class }}
   ingressClassName: {{ .ingress.class }}
   {{- end }}
+  {{- $backends := .backends }}
   rules:
     {{- range .ingress.hosts }}
     - host: {{ . }}
       http:
         paths:
-          - path: /
+          {{- range $backends }}
+          - path: {{ .path }}
             pathType: Prefix
             backend:
               service:
                 name: mono
                 port:
-                  number: {{ $.Values.mono.port | default 8000 }}
+                  number: {{ .port }}
+          {{- end }}
     {{- end }}
     {{- if .ingress.default }}
     - http:
         paths:
-          - path: /
+          {{- range $backends }}
+          - path: {{ .path }}
             pathType: Prefix
             backend:
               service:
                 name: mono
                 port:
-                  number: {{ $.Values.mono.port | default 8000 }}
+                  number: {{ .port }}
+          {{- end }}
     {{- end }}
 {{- end }}
 ---

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

@@ -100,6 +100,8 @@ spec:
 {{- end }}
 {{- if .ingress }}
 {{- $service := .name }}
+{{- $port := .port }}
+{{- $path := .ingress.path | default "/" }}
 ---
 apiVersion: networking.k8s.io/v1
 kind: Ingress
@@ -118,24 +120,24 @@ spec:
     - host: {{ . }}
       http:
         paths:
-          - path: /
+          - path: {{ $path }}
             pathType: Prefix
             backend:
               service:
                 name: extension-{{ $service }}
                 port:
-                  number: 8000
+                  number: {{ $port }}
     {{- end }}
     {{- if .ingress.default }}
     - http:
         paths:
-          - path: /
+          - path: {{ $path }}
             pathType: Prefix
             backend:
               service:
                 name: extension-{{ $service }}
                 port:
-                  number: 8000
+                  number: {{ $port }}
     {{- end }}
 {{- end }}
 ---

package/src/deployment/factory.js

@@ -11,7 +11,6 @@ const { Service } = require('./service')
 
 class Factory {
   #context
-  #root
   #mono
   #compositions
   #dependencies
@@ -21,7 +20,6 @@ class Factory {
 
   constructor (context, options = {}) {
     this.#context = context
-    this.#root = options.root
     this.#mono = options.mono === true
     this.#process = new Process()
 
@@ -34,7 +32,7 @@ class Factory {
     if (this.#mono)
       this.#image = this.#registry.mono({
         components: context.components
-      }, this.#root)
+      })
     else
       this.#compositions = context.compositions.map((composition) => this.#composition(composition))
   }
@@ -108,7 +106,7 @@ class Factory {
   static async create (path, environment, options = {}) {
     const context = await load(path, environment)
 
-    return new Factory(context, { ...options, root: path })
+    return new Factory(context, options)
   }
 }
 

package/src/deployment/images/factory.js

@@ -50,8 +50,8 @@ class Factory {
   /**
    * @returns {Mono}
    */
-  mono (composition, root) {
-    const instance = new Mono(this.#scope, this.#runtime, this.#registry, composition, root)
+  mono (composition) {
+    const instance = new Mono(this.#scope, this.#runtime, this.#registry, composition)
 
     instance.tag()
 

package/src/deployment/images/mono.Dockerfile

@@ -12,7 +12,7 @@ COPY --chown=node:node . /composition
 {{build.run}}
 
 RUN --mount=type=cache,target=/root/.npm \
-  for entry in components/*; do if [ -f "$entry/package.json" ]; then (cd $entry && npm i --omit=dev); fi; done
+  for entry in *; do if [ -f "$entry/package.json" ]; then (cd $entry && npm i --omit=dev); fi; done
 
 USER node
-CMD toa mono .
+CMD toa mono *

package/src/deployment/images/mono.js

@@ -9,14 +9,12 @@ const { Image } = require('./image')
 class Mono extends Image {
   dockerfile = join(__dirname, 'mono.Dockerfile')
 
-  #root
   #image
   #components
 
-  constructor (scope, runtime, registry, composition, root) {
+  constructor (scope, runtime, registry, composition) {
     super(scope, runtime, registry)
 
-    this.#root = root
     this.#image = composition.image
     this.#components = composition.components
   }
@@ -67,16 +65,11 @@ class Mono extends Image {
   async prepare (root) {
     const context = await super.prepare(root)
 
-    await fs.copy(join(this.#root, CONTEXT), join(context, CONTEXT))
-    await fs.ensureDir(join(context, 'components'))
-
     for (const component of this.#components)
-      await fs.copy(component.path, join(context, 'components', component.locator.label))
+      await fs.copy(component.path, join(context, component.locator.label))
 
     return context
   }
 }
 
-const CONTEXT = 'context.toa.yaml'
-
 exports.Mono = Mono

package/src/deployment/registry.js

@@ -35,8 +35,8 @@ class Registry {
     return this.#create('service', path, service)
   }
 
-  mono (composition, root) {
-    return this.#create('mono', composition, root)
+  mono (composition) {
+    return this.#create('mono', composition)
   }
 
   async prepare (root) {

package/types/dependency.ts

@@ -43,6 +43,8 @@ export interface Dependency {
 }
 
 interface Ingress {
+  /** Path prefix this service claims on the host. Defaults to `/`. */
+  path?: string
   default?: boolean
   hosts?: string[]
   class?: string