@toa.io/operations 1.0.0-alpha.284 → 1.0.0-alpha.287

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

@@ -14,7 +14,8 @@ export const describe = (context, compositions, dependency, image) => {
     {
       name: 'TOA_CONTEXT',
       value: context.name
-    }, {
+    },
+    {
       name: 'TOA_ENV',
       value: context.environment
     }
@@ -28,8 +29,10 @@ export const describe = (context, compositions, dependency, image) => {
     // 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`)
+      throw new Error(
+        `'atomicity.redis' takes an odd number of addresses, ` +
+          `${addresses.length} given`
+      )
 
     dependency.variables.global.push({
       name: 'TOA_ATOMICITY_REDIS',
@@ -102,8 +105,10 @@ export const describe = (context, compositions, dependency, image) => {
   return values
 }
 
-function unit (context, dependency) {
-  const components = (context.components ?? []).map((component) => component.locator.label)
+function unit(context, dependency) {
+  const components = (context.components ?? []).map(
+    (component) => component.locator.label
+  )
 
   const variables = dependency.variables ?? {}
   const mounts = dependency.mounts ?? {}
@@ -115,8 +120,7 @@ function unit (context, dependency) {
     variables: []
   }
 
-  if (context.ingress !== undefined)
-    mono.ingress = Object.assign({}, context.ingress)
+  if (context.ingress !== undefined) mono.ingress = Object.assign({}, context.ingress)
 
   addVariables(mono, variables, Object.keys(variables))
   addMounts(mono, dependency.mounts, Object.keys(mounts))

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

@@ -61,22 +61,27 @@ const reserve = (services, probe) => {
         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}'`))
+          throw new Error(
+            `Port ${port} is claimed by both ${conflicting} and ${claimant}` +
+              (service.workload === undefined ? '' : ` in '${workload}'`)
+          )
 
         claimed.set(port, claimant)
       }
     }
 }
 
-function * ports (service) {
+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.port !== undefined) yield [service.port, name]
 
-  if (service.probe !== undefined && service.probe !== false && service.probe.port !== service.port)
+  if (
+    service.probe !== undefined &&
+    service.probe !== false &&
+    service.probe.port !== service.port
+  )
     yield [service.probe.port, `the readiness probe of ${name}`]
 }
 

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

@@ -4,7 +4,12 @@ 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 })
+const service = (name, extra = {}) => ({
+  group: 'group',
+  name: `group-${name}`,
+  version: '0',
+  ...extra
+})
 
 it('should merge services of all dependencies', () => {
   const merged = merge([
@@ -28,7 +33,13 @@ describe('port reservation', () => {
       { 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))
+    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', () => {
@@ -46,7 +57,13 @@ describe('port reservation', () => {
       { 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))
+    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', () => {
@@ -64,30 +81,44 @@ describe('port reservation', () => {
       { 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))
+    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 } })] }
+      {
+        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))
+    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 } })] }
+      {
+        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')] }
-    ]
+    const dependencies = [{ services: [service('one'), service('two')] }]
 
     assert.doesNotThrow(() => merge(dependencies))
   })

package/src/deployment/composition.js

@@ -4,7 +4,7 @@ export class Composition {
   /** @type {string[]} */
   components
 
-  constructor (composition, image) {
+  constructor(composition, image) {
     this.name = composition.name
     this.image = image.reference
     this.components = composition.components.map(component)

package/src/deployment/deployment.js

@@ -11,7 +11,7 @@ export class Deployment {
   #process
   #target
 
-  constructor (context, compositions, dependencies, process, image) {
+  constructor(context, compositions, dependencies, process, image) {
     const dependency = merge(dependencies)
 
     this.#chart = declare(context, dependency)
@@ -19,7 +19,7 @@ export class Deployment {
     this.#process = process
   }
 
-  async export (target) {
+  async export(target) {
     const chart = dump(this.#chart)
     const values = dump(this.#values)
 
@@ -32,9 +32,9 @@ export class Deployment {
     this.#target = target
   }
 
-  async install (options) {
+  async install(options) {
     if (options.target) this.#target = options.target
-    if (this.#target === undefined) throw new Error('Deployment hasn\'t been exported')
+    if (this.#target === undefined) throw new Error("Deployment hasn't been exported")
 
     const args = []
 
@@ -42,25 +42,46 @@ export class Deployment {
     if (options.wait === true) args.push('--wait')
     if (options.timeout !== undefined) args.push('--timeout', options.timeout)
 
-    await this.#process.execute('helm', ['dependency', 'update', this.#target])
-    await this.#process.execute('helm', ['upgrade', this.#chart.name, '-i', ...args, this.#target])
+    await this.#update()
+    await this.#process.execute('helm', [
+      'upgrade',
+      this.#chart.name,
+      '-i',
+      ...args,
+      this.#target
+    ])
   }
 
-  async template (options) {
-    if (this.#target === undefined) throw new Error('Deployment hasn\'t been exported')
+  async template(options) {
+    if (this.#target === undefined) throw new Error("Deployment hasn't been exported")
 
-    await this.#process.execute('helm', ['dependency', 'update', this.#target], { silently: true })
+    await this.#update({ silently: true })
 
     const args = []
 
     if (options.namespace !== undefined) args.push('-n', options.namespace)
 
-    return await this.#process.execute('helm',
+    return await this.#process.execute(
+      'helm',
       ['template', this.#chart.name, ...args, this.#target],
-      { silently: true })
+      { silently: true }
+    )
+  }
+
+  /**
+   * A chart with no subcharts has nothing to resolve, and the call still reaches out for
+   * the repositories it would have read.
+   *
+   * @param {object} [options]
+   * @returns {Promise<void>}
+   */
+  async #update(options = {}) {
+    if (this.#chart.dependencies.length === 0) return
+
+    await this.#process.execute('helm', ['dependency', 'update', this.#target], options)
   }
 
-  variables () {
+  variables() {
     const variables = []
     const used = new Set()
 
@@ -74,7 +95,7 @@ export class Deployment {
   }
 }
 
-function addVariables (list, variables, used = new Set()) {
+function addVariables(list, variables, used = new Set()) {
   for (const item of list) {
     if (item.variables === undefined) continue
 
@@ -89,9 +110,7 @@ function addVariables (list, variables, used = new Set()) {
 
 const TEMPLATES = join(import.meta.dirname, 'chart/templates')
 
-
-
-function dump (object) {
+function dump(object) {
   // js-yaml writes plain objects only, and the values carry locators and images
   return jsyaml.dump(JSON.parse(JSON.stringify(object)), { noRefs: true, lineWidth: -1 })
 }

package/src/deployment/factory.js

@@ -29,14 +29,18 @@ export class Factory {
    *  @type {Map<string, string[]>} */
   #claims
 
-  constructor (context, options = {}) {
+  constructor(context, options = {}) {
     this.#context = context
     this.#mono = options.mono === true
     this.#process = new Process()
 
-    const imagesFactory = new ImagesFactory(context.name, context.runtime, context.registry)
+    const imagesFactory = new ImagesFactory(
+      context.name,
+      context.runtime,
+      context.registry
+    )
 
-    this.#registry = new Registry(context.name, context.registry, imagesFactory, this.#process)
+    this.#registry = new Registry(context.registry, imagesFactory, this.#process)
     this.#claims = claims(context)
     this.#dependencies = this.#getDependencies()
     this.#compositions = []
@@ -46,10 +50,12 @@ export class Factory {
         components: context.components
       })
     else
-      this.#compositions = context.compositions.map((composition) => this.#composition(composition))
+      this.#compositions = context.compositions.map((composition) =>
+        this.#composition(composition)
+      )
   }
 
-  async operator () {
+  async operator() {
     const deployment = new Deployment(
       this.#context,
       this.#compositions,
@@ -62,17 +68,17 @@ export class Factory {
     return new Operator(deployment, this.#registry)
   }
 
-  registry () {
+  registry() {
     return this.#registry
   }
 
-  #composition (composition) {
+  #composition(composition) {
     const image = this.#registry.composition(composition)
 
     return new Composition(composition, image)
   }
 
-  async #getDependencies () {
+  async #getDependencies() {
     /** @type {toa.deployment.Dependency[]} */
     const dependencies = []
 
@@ -95,17 +101,21 @@ export class Factory {
     // point where a reference that yields nothing can be told from one that yields a service
     for (const [reference, compositions] of this.#claims)
       if (!contributing.has(reference))
-        throw new Error(`Composition '${compositions[0]}' lists '${reference}', ` +
-          'which contributes no service.')
+        throw new Error(
+          `Composition '${compositions[0]}' lists '${reference}', ` +
+            'which contributes no service.'
+        )
 
     return dependencies
   }
 
-  async #getDependency (reference, instances) {
+  async #getDependency(reference, instances) {
     // a dependency may be named the way a package is or written as a directory,
     // and a module is loaded by file
     const module = await import(pathToFileURL(require.resolve(reference)).href)
-    const pkg = JSON.parse(readFileSync(require.resolve(join(reference, 'package.json')), 'utf8'))
+    const pkg = JSON.parse(
+      readFileSync(require.resolve(join(reference, 'package.json')), 'utf8')
+    )
 
     if (module.deployment === undefined) return
 
@@ -121,9 +131,10 @@ export class Factory {
     /** @type {toa.deployment.Service[]} */
     const services = dependency.services?.map((service) =>
       workload === undefined
-        ? this.#service(reference, service)   // its own deployment, its own image
-        // named the way `Service` would name it, since it skips that wrapper
-        : { ...service, name: `${service.group}-${service.name}`, workload })
+        ? this.#service(reference, service) // its own deployment, its own image
+        : // named the way `Service` would name it, since it skips that wrapper
+          { ...service, name: `${service.group}-${service.name}`, workload }
+    )
 
     return { ...dependency, services }
   }
@@ -133,13 +144,20 @@ export class Factory {
    * @param service {toa.deployment.dependency.Service}
    * @returns {Service}
    */
-  #service (path, service) {
-    const image = this.#registry.service(path, service)
+  #service(path, service) {
+    // an extension that publishes its service's image is taken at its word: nothing is
+    // added to the registry, so nothing is prepared, probed, built or pushed for it
+    const published =
+      service.image !== undefined && this.#context.registry?.services === PUBLISHED
+
+    const image = published
+      ? { reference: `${service.image}:${this.#context.runtime.version}` }
+      : this.#registry.service(path, service)
 
     return new Service(service, image)
   }
 
-  static async create (path, environment, options = {}) {
+  static async create(path, environment, options = {}) {
     const context = await load(path, environment)
 
     return new Factory(context, options)
@@ -148,11 +166,13 @@ export class Factory {
 
 const MONO = 'mono'
 
+const PUBLISHED = 'published'
+
 /**
  * @param {toa.norm.Context} context
  * @returns {Map<string, string[]>}
  */
-function claims (context) {
+function claims(context) {
   const map = new Map()
 
   for (const composition of context.compositions ?? [])

package/src/deployment/images/composition.Dockerfile

@@ -12,7 +12,7 @@ COPY --chown=node:node . /composition
 {{build.run}}
 
 # run 'npm i' in each component
-RUN --mount=type=cache,target=/root/.npm \
+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
 
 USER node

package/src/deployment/images/composition.js

@@ -12,7 +12,7 @@ export class Composition extends Image {
   #image
   #components
 
-  constructor (scope, runtime, registry, composition) {
+  constructor(scope, runtime, registry, composition) {
     super(scope, runtime, registry)
 
     this.#name = composition.name
@@ -20,11 +20,11 @@ export class Composition extends Image {
     this.#components = composition.components
   }
 
-  get name () {
+  get name() {
     return 'composition-' + this.#name
   }
 
-  get version () {
+  get version() {
     const hash = createHash('sha256')
 
     for (const component of this.#components) {
@@ -35,31 +35,32 @@ export class Composition extends Image {
     return hash.digest('hex').slice(0, 8)
   }
 
-  get base () {
+  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.`)
+      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 () {
+  get run() {
     const commands = []
 
     for (const component of this.#components) {
       const run = component.build?.run
 
-      if (run !== undefined)
-        commands.push(run)
+      if (run !== undefined) commands.push(run)
     }
 
     return commands.join('\n')
   }
 
-  async prepare (root) {
+  async prepare(root) {
     const context = await super.prepare(root)
 
     for (const component of this.#components) {

package/src/deployment/images/factory.js

@@ -17,7 +17,7 @@ export class Factory {
    * @param {toa.norm.context.Runtime} runtime
    * @param {toa.norm.context.Registry} registry
    */
-  constructor (scope, runtime, registry) {
+  constructor(scope, runtime, registry) {
     this.#scope = scope
     this.#runtime = runtime
     this.#registry = registry
@@ -26,8 +26,13 @@ export class Factory {
   /**
    * @returns {Composition}
    */
-  composition (composition) {
-    const instance = new Composition(this.#scope, this.#runtime, this.#registry, composition)
+  composition(composition) {
+    const instance = new Composition(
+      this.#scope,
+      this.#runtime,
+      this.#registry,
+      composition
+    )
 
     instance.tag()
 
@@ -37,8 +42,14 @@ export class Factory {
   /**
    * @returns {Service}
    */
-  service (path, service) {
-    const instance = new Service(this.#scope, this.#runtime, this.#registry, path, service)
+  service(path, service) {
+    const instance = new Service(
+      this.#scope,
+      this.#runtime,
+      this.#registry,
+      path,
+      service
+    )
 
     instance.tag()
 
@@ -48,7 +59,7 @@ export class Factory {
   /**
    * @returns {Mono}
    */
-  mono (composition) {
+  mono(composition) {
     const instance = new Mono(this.#scope, this.#runtime, this.#registry, composition)
 
     instance.tag()

package/src/deployment/images/format.js

@@ -14,11 +14,13 @@ import { dirname, join, parse } from 'node:path'
  * @param {string} target where it was copied
  * @param {string} name
  */
-export async function declare (source, target, name) {
+export async function declare(source, target, name) {
   if (existsSync(join(target, MANIFEST))) return
 
-  await writeFile(join(target, MANIFEST),
-    JSON.stringify({ name, private: true, type: format(source) }, null, 2) + '\n')
+  await writeFile(
+    join(target, MANIFEST),
+    JSON.stringify({ name, private: true, type: format(source) }, null, 2) + '\n'
+  )
 }
 
 /**
@@ -28,7 +30,7 @@ export async function declare (source, target, name) {
  * @param {string} directory
  * @returns {'module' | 'commonjs'}
  */
-export function format (directory) {
+export function format(directory) {
   const { root } = parse(directory)
 
   let current = directory
@@ -37,7 +39,9 @@ export function format (directory) {
     const manifest = join(current, MANIFEST)
 
     if (existsSync(manifest))
-      return JSON.parse(readFileSync(manifest, 'utf8')).type === 'module' ? 'module' : 'commonjs'
+      return JSON.parse(readFileSync(manifest, 'utf8')).type === 'module'
+        ? 'module'
+        : 'commonjs'
 
     current = dirname(current)
   }

package/src/deployment/images/image.fixtures.js

@@ -8,11 +8,11 @@ const name = generate()
  * @implements {toa.deployment.images.Image}
  */
 class Class extends Image {
-  get name () {
+  get name() {
     return name
   }
 
-  get version () {
+  get version() {
     return version
   }
 }