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

package/src/deployment/registry.test.js

@@ -17,8 +17,7 @@ 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] === 'manifest') throw new Error('manifest unknown')
 
       if (args[0] === 'buildx' && args[1] === 'inspect')
         throw new Error('builder not found')
@@ -29,30 +28,45 @@ beforeEach(() => {
 
   factory = /** @type {toa.deployment.images.Factory} */ {
     composition: () => createImage('composition-mono'),
-    service: () => createImage('extension-realtime')
+    service: () => createImage('extension-realtime'),
+    mono: () => createImage('mono')
   }
 })
 
 it('should reuse named builder across images', async () => {
-  const registry = createRegistry({ base: 'example.com/reg', platforms: ['linux/amd64'] })
+  const registry = createRegistry({
+    base: 'example.com/reg',
+    platforms: ['linux/amd64', 'linux/arm64']
+  })
 
   registry.composition(/** @type {any} */ ({}))
   registry.service('.', /** @type {any} */ ({}))
 
   await registry.build()
 
-  const creates = process.execute.mock.calls.filter(({ arguments: [, args] }) =>
-    args[0] === 'buildx' && args[1] === 'create')
+  const creates = process.execute.mock.calls.filter(
+    ({ arguments: [, args] }) => args[0] === 'buildx' && args[1] === 'create'
+  )
 
   assert.strictEqual(creates.length, 1)
-  assert.deepStrictEqual(creates[0].arguments[1], ['buildx', 'create', '--name', 'toa', '--bootstrap'])
-
-  const builds = process.execute.mock.calls.filter(({ arguments: [, args] }) =>
-    args[0] === '--context=default' && args[1] === 'buildx' && args[2] === 'build')
+  assert.deepStrictEqual(creates[0].arguments[1], [
+    'buildx',
+    'create',
+    '--name',
+    'toa',
+    '--bootstrap'
+  ])
+
+  const builds = process.execute.mock.calls.filter(
+    ({ arguments: [, args] }) =>
+      args[0] === '--context=default' && args[1] === 'buildx' && args[2] === 'build'
+  )
 
   assert.strictEqual(builds.length, 2)
 
-  for (const { arguments: [, args] } of builds) {
+  for (const {
+    arguments: [, args]
+  } of builds) {
     assert.ok(args.includes('--builder'))
     assert.strictEqual(args[args.indexOf('--builder') + 1], 'toa')
   }
@@ -60,25 +74,28 @@ it('should reuse named builder across images', async () => {
 
 it('should not create builder when it already exists', async () => {
   process.execute = mock.fn(async (cmd, args) => {
-    if (args[0] === 'manifest')
-      throw new Error('manifest unknown')
+    if (args[0] === 'manifest') throw new Error('manifest unknown')
 
     return ''
   })
 
-  const registry = createRegistry({ base: 'example.com/reg', platforms: ['linux/amd64'] })
+  const registry = createRegistry({
+    base: 'example.com/reg',
+    platforms: ['linux/amd64', 'linux/arm64']
+  })
 
   registry.composition(/** @type {any} */ ({}))
 
   await registry.build()
 
-  const creates = process.execute.mock.calls.filter(({ arguments: [, args] }) =>
-    args[0] === 'buildx' && args[1] === 'create')
+  const creates = process.execute.mock.calls.filter(
+    ({ arguments: [, args] }) => args[0] === 'buildx' && args[1] === 'create'
+  )
 
   assert.strictEqual(creates.length, 0)
 })
 
-it('should add shared registry cache flags when base is set', async () => {
+it('should not export a build cache', async () => {
   const registry = createRegistry({ base: 'example.com/reg', platforms: ['linux/amd64'] })
 
   registry.composition(/** @type {any} */ ({}))
@@ -86,35 +103,77 @@ it('should add shared registry cache flags when base is set', async () => {
 
   await registry.build()
 
-  const builds = process.execute.mock.calls.filter(({ arguments: [, args] }) =>
-    args[0] === '--context=default' && args[2] === 'build')
+  const builds = process.execute.mock.calls.filter(
+    ({ arguments: [, args] }) => args[0] === '--context=default' && args[2] === 'build'
+  )
 
   assert.strictEqual(builds.length, 2)
 
-  for (const { arguments: [, args] } of builds) {
-    assert.ok(args.includes('--cache-from'))
-    assert.ok(args.includes('type=registry,ref=example.com/reg/acme/buildcache'))
-    assert.ok(args.includes('--cache-to'))
-    assert.ok(args.includes('type=registry,ref=example.com/reg/acme/buildcache,mode=max,image-manifest=true'))
+  for (const {
+    arguments: [, args]
+  } of builds) {
+    assert.ok(!args.includes('--cache-from'))
+    assert.ok(!args.includes('--cache-to'))
   }
 })
 
-it('should omit cache flags when base is not set', async () => {
-  const registry = createRegistry({ platforms: ['linux/amd64'] })
+it('should use the default builder for a single platform', async () => {
+  const registry = createRegistry({ base: 'example.com/reg', platforms: ['linux/amd64'] })
 
   registry.composition(/** @type {any} */ ({}))
 
   await registry.build()
 
-  const builds = process.execute.mock.calls.filter(({ arguments: [, args] }) =>
-    args[0] === '--context=default' && args[2] === 'build')
+  const creates = process.execute.mock.calls.filter(
+    ({ arguments: [, args] }) => args[0] === 'buildx' && args[1] === 'create'
+  )
 
-  assert.strictEqual(builds.length, 1)
+  assert.strictEqual(creates.length, 0)
+
+  const {
+    arguments: [, args]
+  } = process.execute.mock.calls.find(
+    ({ arguments: [, args] }) => args[0] === '--context=default' && args[2] === 'build'
+  )
+
+  assert.strictEqual(args[args.indexOf('--builder') + 1], 'default')
+  assert.ok(args.includes('--platform'))
+  assert.strictEqual(args[args.indexOf('--platform') + 1], 'linux/amd64')
+})
+
+it('should create the builder once when images build concurrently', async () => {
+  const registry = createRegistry({
+    base: 'example.com/reg',
+    platforms: ['linux/amd64', 'linux/arm64']
+  })
+
+  registry.composition(/** @type {any} */ ({}))
+  registry.service('.', /** @type {any} */ ({}))
+  registry.mono(/** @type {any} */ ({}))
+
+  await registry.build()
+
+  const creates = process.execute.mock.calls.filter(
+    ({ arguments: [, args] }) => args[0] === 'buildx' && args[1] === 'create'
+  )
+
+  assert.strictEqual(creates.length, 1)
+})
+
+it('should probe every image before building any', async () => {
+  const registry = createRegistry({ base: 'example.com/reg', platforms: ['linux/amd64'] })
+
+  registry.composition(/** @type {any} */ ({}))
+  registry.service('.', /** @type {any} */ ({}))
+
+  await registry.build()
 
-  const { arguments: [, args] } = builds[0]
+  const calls = process.execute.mock.calls.map(({ arguments: [, args] }) => args[0])
+  const build = calls.indexOf('--context=default')
+  const probed = calls.slice(0, build).filter((argument) => argument === 'manifest')
 
-  assert.ok(!(args.includes('--cache-from')))
-  assert.ok(!(args.includes('--cache-to')))
+  // both probes are spent before the first build starts, rather than one before each
+  assert.strictEqual(probed.length, 2)
 })
 
 it('should use default builder when platforms is null', async () => {
@@ -124,16 +183,18 @@ it('should use default builder when platforms is null', async () => {
 
   await registry.build()
 
-  const builds = process.execute.mock.calls.filter(({ arguments: [, args] }) =>
-    args[0] === '--context=default' && args[2] === 'build')
+  const builds = process.execute.mock.calls.filter(
+    ({ arguments: [, args] }) => args[0] === '--context=default' && args[2] === 'build'
+  )
 
   assert.strictEqual(builds.length, 1)
 
-  const { arguments: [, args] } = builds[0]
+  const {
+    arguments: [, args]
+  } = builds[0]
 
   assert.strictEqual(args[args.indexOf('--builder') + 1], 'default')
-  assert.ok(!(args.includes('--cache-from')))
-  assert.ok(!(args.includes('--platform')))
+  assert.ok(!args.includes('--platform'))
 })
 
 it('should skip build when image already exists', async () => {
@@ -145,26 +206,39 @@ it('should skip build when image already exists', async () => {
 
   await registry.build()
 
-  const builds = process.execute.mock.calls.filter(({ arguments: [, args] }) =>
-    args[0] === '--context=default' && args[2] === 'build')
+  const builds = process.execute.mock.calls.filter(
+    ({ arguments: [, args] }) => args[0] === '--context=default' && args[2] === 'build'
+  )
 
   assert.strictEqual(builds.length, 0)
-  assert.ok(process.execute.mock.calls.some((call) => call.arguments.length === 3 && isDeepStrictEqual(call.arguments[0], 'docker') && isDeepStrictEqual(call.arguments[1], ['manifest', 'inspect', images[0].reference]) && isDeepStrictEqual(call.arguments[2], { silently: true })))
+  assert.ok(
+    process.execute.mock.calls.some(
+      (call) =>
+        call.arguments.length === 3 &&
+        isDeepStrictEqual(call.arguments[0], 'docker') &&
+        isDeepStrictEqual(call.arguments[1], [
+          'manifest',
+          'inspect',
+          images[0].reference
+        ]) &&
+        isDeepStrictEqual(call.arguments[2], { silently: true })
+    )
+  )
 })
 
 /**
  * @param {object} [registry]
  * @returns {Registry}
  */
-function createRegistry (registry = {}) {
-  return new Registry('acme', registry, factory, process)
+function createRegistry(registry = {}) {
+  return new Registry(registry, factory, process)
 }
 
 /**
  * @param {string} name
  * @returns {toa.deployment.images.Image}
  */
-function createImage (name) {
+function createImage(name) {
   const image = /** @type {toa.deployment.images.Image} */ {
     reference: `example.com/reg/acme/${name}:abcdef12`,
     context: `/tmp/${name}`,

package/src/deployment/service.js

@@ -1,5 +1,7 @@
+// a service is what a deployment carries, and it is constructed
+// oxlint-disable-next-line typescript/no-extraneous-class
 export class Service {
-  constructor (service, image) {
+  constructor(service, image) {
     Object.assign(this, service)
 
     this.name = service.group + '-' + service.name

package/src/deployment/workspace.js

@@ -7,7 +7,7 @@ import { tmpdir } from 'node:os'
  * @param {string} [path]
  * @return {Promise<string>}
  */
-export async function create (type, path) {
+export async function create(type, path) {
   if (path === undefined) return await mkdtemp(join(tmpdir(), 'toa-' + type))
 
   path = resolve(path)

package/src/process.js

@@ -4,7 +4,7 @@ import { execa } from 'execa'
  * @implements {toa.operations.Process}
  */
 export class Process {
-  async execute (cmd, args, options = {}) {
+  async execute(cmd, args, options = {}) {
     console.log('toa>', cmd, args.join(' '))
 
     const command = execa(cmd, args)

package/src/process.test.js

@@ -7,14 +7,18 @@ describe('execute', () => {
   it('should answer what the command wrote', async () => {
     // `execa` is a named export, and calling the module namespace instead answers
     // `execa is not a function` — where only a deployment would have found out
-    const output = await new Process().execute('node', ['-e', 'process.stdout.write("ok")'],
-      { silently: true })
+    const output = await new Process().execute(
+      'node',
+      ['-e', 'process.stdout.write("ok")'],
+      { silently: true }
+    )
 
     assert.strictEqual(output, 'ok')
   })
 
   it('should reject what the command failed at', async () => {
-    await assert.rejects(new Process().execute('node', ['-e', 'process.exit(1)'],
-      { silently: true }))
+    await assert.rejects(
+      new Process().execute('node', ['-e', 'process.exit(1)'], { silently: true })
+    )
   })
 })

package/types/_deployment/composition.d.ts

@@ -1,11 +1,9 @@
 import type * as _deployment from './deployment.js'
 
 declare namespace toa.deployment {
-
   interface Composition extends _deployment.Deployable {
     components: Array<string>
   }
-
 }
 
 export type Composition = toa.deployment.Composition

package/types/_deployment/dependency.d.ts

@@ -2,10 +2,11 @@ import * as _service from './service.js'
 import { dependencies } from '@toa.io/norm/types/context'
 
 declare namespace toa.deployment {
-
   namespace dependency {
-
-    type Constructor = (instances: dependencies.Instance[], annotation: any) => Declaration
+    type Constructor = (
+      instances: dependencies.Instance[],
+      annotation: any
+    ) => Declaration
 
     type Reference = {
       name: string
@@ -19,6 +20,11 @@ declare namespace toa.deployment {
       group: string
       name: string
       version: string
+
+      /** The repository the extension publishes this service's image to, without a tag.
+       *  Stating it lets an application take the published image instead of building one. */
+      image?: string
+
       port: number
       ingress?: {
         host: string
@@ -36,7 +42,7 @@ declare namespace toa.deployment {
       name: string
       value?: string | number
       secret?: {
-        name: string,
+        name: string
         key: string
       }
     }
@@ -52,7 +58,6 @@ declare namespace toa.deployment {
       variables?: Variables
       events?: string[]
     }
-
   }
 
   type Dependency = {
@@ -62,7 +67,6 @@ declare namespace toa.deployment {
     variables?: dependency.Variables
     events?: string[]
   }
-
 }
 
 export type Declaration = toa.deployment.dependency.Declaration

package/types/_deployment/deployment.d.ts

@@ -3,7 +3,6 @@ import type * as _service from './service.js'
 import type * as _dependency from './dependency.js'
 
 declare namespace toa.deployment {
-
   interface Declaration {
     apiVersion: string
     type: string
@@ -25,13 +24,11 @@ declare namespace toa.deployment {
   }
 
   namespace installation {
-
     interface Options {
       wait?: boolean
       target?: string
       namespace?: string
     }
-
   }
 
   namespace template {
@@ -54,7 +51,6 @@ declare namespace toa.deployment {
 
     variables(): _dependency.Variables
   }
-
 }
 
 export namespace installation {

package/types/_deployment/factory.d.ts

@@ -2,13 +2,11 @@ import type * as _operator from './operator.js'
 import * as _registry from './registry.js'
 
 declare namespace toa.deployment {
-
   interface Factory {
     operator(): _operator.Operator
 
     registry(): _registry.Registry
   }
-
 }
 
 export type Factory = toa.deployment.Factory

package/types/_deployment/images/factory.d.ts

@@ -5,13 +5,11 @@ import type { Image } from './image.js'
 import type { dependency } from '../dependency.js'
 
 declare namespace toa.deployment.images {
+  interface Factory {
+    composition(composition: Composition): Image
 
-    interface Factory {
-        composition(composition: Composition): Image
-
-        service(path: string, service: dependency.Service): Image
-    }
-
+    service(path: string, service: dependency.Service): Image
+  }
 }
 
 export type Factory = toa.deployment.images.Factory

package/types/_deployment/images/image.d.ts

@@ -1,16 +1,14 @@
 declare namespace toa.deployment.images {
-
   export interface Image {
     readonly reference: string
     readonly context: string
 
     name: string
 
-    tag (): void
+    tag(): void
 
-    prepare (root: string): Promise<string>
+    prepare(root: string): Promise<string>
   }
-
 }
 
 export type Image = toa.deployment.images.Image

package/types/_deployment/images/registry.d.ts

@@ -2,19 +2,16 @@
 
 import type { Composition } from '@toa.io/norm'
 import type { dependency } from '../dependency.js'
-import type { Image } from "./image.js"
+import type { Image } from './image.js'
 
 declare namespace toa.deployment.images {
+  interface Registry {
+    composition(composition: Composition): Image
 
-    interface Registry {
-        composition(composition: Composition): Image
+    service(path: string, service: dependency.Service): Image
 
-        service(path: string, service: dependency.Service): Image
-
-        prepare(target: string): Promise<void>
-
-        push(): Promise<void>
-    }
+    prepare(target: string): Promise<void>
 
+    push(): Promise<void>
+  }
 }
-

package/types/_deployment/operator.d.ts

@@ -2,19 +2,17 @@ import * as _deployment from './deployment.js'
 import * as _dependency from './dependency.js'
 
 declare namespace toa.deployment {
-
   interface Operator {
-    export (path?: string): Promise<string>
+    export(path?: string): Promise<string>
 
-    install (options?: _deployment.installation.Options): Promise<void>
+    install(options?: _deployment.installation.Options): Promise<void>
 
-    template (options?: _deployment.template.Options): Promise<string>
+    template(options?: _deployment.template.Options): Promise<string>
 
-    variables (): _dependency.Variables
+    variables(): _dependency.Variables
 
-    listVariables (): _dependency.Variable[]
+    listVariables(): _dependency.Variable[]
   }
-
 }
 
 export type Operator = toa.deployment.Operator

package/types/_deployment/registry.d.ts

@@ -3,21 +3,19 @@ import type * as _dependency from './dependency.js'
 import type * as _image from './images/image.js'
 
 declare namespace toa.deployment {
-
   interface Registry {
-    composition (composition: _norm.Composition): _image.Image
+    composition(composition: _norm.Composition): _image.Image
 
-    service (path: string, service: _dependency.Service): _image.Image
+    service(path: string, service: _dependency.Service): _image.Image
 
-    prepare (path: string): Promise<string>
+    prepare(path: string): Promise<string>
 
-    build (): Promise<void>
+    build(): Promise<void>
 
-    push (): Promise<void>
+    push(): Promise<void>
 
-    tags (): string[]
+    tags(): string[]
   }
-
 }
 
 export type Registry = toa.deployment.Registry

package/types/_deployment/service.d.ts

@@ -1,7 +1,6 @@
 import type * as _deployment from './deployment.js'
 
 declare namespace toa.deployment {
-
   interface Ingress {
     host: string
     class: string
@@ -15,7 +14,6 @@ declare namespace toa.deployment {
     /** Annotations for the Service itself, as opposed to `ingress.annotations`. */
     annotations?: object
   }
-
 }
 
 export type Service = toa.deployment.Service

package/types/dependency.ts

@@ -5,6 +5,9 @@ export interface Service {
   group: string
   name: string
   version: string
+  /** The repository the extension publishes this service's image to, without a tag.
+   *  Stating it lets an application take the published image instead of building one. */
+  image?: string
   port?: number
   ingress?: Ingress
   /** Annotations for the Service itself, as opposed to `ingress.annotations`. */