@toa.io/operations 1.0.0-alpha.34 → 1.0.0-alpha.341

package/src/deployment/secrets.test.js

@@ -0,0 +1,180 @@
+import { it, describe, beforeEach, mock } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { references, verify } from './secrets.js'
+
+describe('references', () => {
+  it('should reference a secret by name and key', () => {
+    const variables = [
+      { name: 'TOA_CONTEXT', value: 'todos' },
+      { name: 'USERNAME', secret: { name: 'toa-mongodb.default', key: 'username' } },
+      { name: 'PASSWORD', secret: { name: 'toa-mongodb.default', key: 'password' } }
+    ]
+
+    assert.deepStrictEqual(references(variables), [
+      'toa-mongodb.default/username',
+      'toa-mongodb.default/password'
+    ])
+  })
+
+  it('should not reference an optional key', () => {
+    const variables = [
+      { name: 'KEY', secret: { name: 'toa-tokens', key: 'key0', optional: true } },
+      { name: 'USERNAME', secret: { name: 'toa-mongodb.default', key: 'username' } }
+    ]
+
+    assert.deepStrictEqual(references(variables), ['toa-mongodb.default/username'])
+  })
+
+  it('should reference a key read by two workloads once', () => {
+    const secret = { name: 'toa-mongodb.default', key: 'username' }
+
+    assert.deepStrictEqual(
+      references([
+        { name: 'A', secret },
+        { name: 'B', secret }
+      ]),
+      ['toa-mongodb.default/username']
+    )
+  })
+
+  it('should reference the image pull secret by name', () => {
+    const variables = [
+      { name: 'USERNAME', secret: { name: 'toa-mongodb.default', key: 'username' } }
+    ]
+
+    assert.deepStrictEqual(references(variables, 'registry-credentials'), [
+      'registry-credentials',
+      'toa-mongodb.default/username'
+    ])
+  })
+
+  it('should reference nothing where nothing is secret', () => {
+    assert.deepStrictEqual(references([{ name: 'TOA_ENV', value: 'production' }]), [])
+  })
+
+  it('should reference no pull secret where a context names none', () => {
+    // as the chart reads it: `credentials: ~` renders no `imagePullSecrets`
+    assert.deepStrictEqual(references([], null), [])
+    assert.deepStrictEqual(references([], ''), [])
+  })
+})
+
+describe('verify', () => {
+  /** @type {string} what `kubectl` answers */
+  let secrets
+
+  /** @type {toa.operations.Process} */
+  let process
+
+  beforeEach(() => {
+    secrets = ''
+    process = /** @type {toa.operations.Process} */ {
+      execute: mock.fn(async () => secrets)
+    }
+  })
+
+  it('should read the namespace deployed into', async () => {
+    secrets = 'toa-mongodb.default password username'
+
+    await verify(process, ['toa-mongodb.default/username'], { namespace: 'acme' })
+
+    const [cmd, args, options] = process.execute.mock.calls[0].arguments
+
+    assert.strictEqual(cmd, 'kubectl')
+    assert.deepStrictEqual(args.slice(0, 2), ['get', 'secrets'])
+    assert.deepStrictEqual(args.slice(-2), ['-n', 'acme'])
+    assert.deepStrictEqual(options, { silently: true })
+  })
+
+  it('should read the current namespace where none is given', async () => {
+    await verify(process, [], {})
+
+    assert.strictEqual(process.execute.mock.callCount(), 0)
+
+    await verify(process, ['toa-mongodb.default/username'], {}).catch(() => {})
+
+    const [, args] = process.execute.mock.calls[0].arguments
+
+    assert.strictEqual(args.includes('-n'), false)
+  })
+
+  it('should name every key that is not deployed', async () => {
+    secrets = 'toa-amqp-context.default password username'
+
+    await assert.rejects(
+      verify(
+        process,
+        [
+          'toa-amqp-context.default/username',
+          'toa-mongodb.default/username',
+          'toa-mongodb.default/password'
+        ],
+        {}
+      ),
+      {
+        message:
+          'Secrets are not deployed: toa-mongodb.default/username, ' +
+          'toa-mongodb.default/password'
+      }
+    )
+  })
+
+  it('should name the key a deployed secret lacks', async () => {
+    secrets = 'toa-mongodb.default username'
+
+    await assert.rejects(
+      verify(
+        process,
+        ['toa-mongodb.default/username', 'toa-mongodb.default/password'],
+        {}
+      ),
+      { message: 'Secrets are not deployed: toa-mongodb.default/password' }
+    )
+  })
+
+  it('should name a secret referenced by name alone', async () => {
+    secrets = 'toa-mongodb.default password username'
+
+    await assert.rejects(verify(process, ['registry-credentials'], {}), {
+      message: 'Secrets are not deployed: registry-credentials'
+    })
+
+    secrets = 'registry-credentials .dockerconfigjson'
+
+    await verify(process, ['registry-credentials'], {})
+  })
+
+  it('should pass where the cluster holds every key', async () => {
+    secrets =
+      'default-token\ntoa-amqp-context.default password username\n' +
+      'toa-mongodb.default password username'
+
+    await verify(
+      process,
+      [
+        'toa-amqp-context.default/username',
+        'toa-amqp-context.default/password',
+        'toa-mongodb.default/username',
+        'toa-mongodb.default/password'
+      ],
+      {}
+    )
+  })
+
+  it('should not read the cluster where nothing is secret', async () => {
+    await verify(process, [], { namespace: 'acme' })
+
+    assert.strictEqual(process.execute.mock.callCount(), 0)
+  })
+
+  it('should fail as the error it is where the cluster cannot be read', async () => {
+    process.execute = mock.fn(async () => {
+      throw new Error('Command failed with exit code 1: kubectl get secrets')
+    })
+
+    await assert.rejects(verify(process, ['toa-mongodb.default/username'], {}), {
+      message: /^Command failed/
+    })
+  })
+})

package/src/deployment/service.js

@@ -1,12 +1,10 @@
-'use strict'
-
-class Service {
-  constructor (service, image) {
+// 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) {
     Object.assign(this, service)
 
     this.name = service.group + '-' + service.name
     this.image = image.reference
   }
 }
-
-exports.Service = Service

package/src/deployment/workspace.js

@@ -1,17 +1,22 @@
-'use strict'
-
-const { directory } = require('@toa.io/filesystem')
+import { mkdir, mkdtemp, readdir } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+import { tmpdir } from 'node:os'
 
 /**
  * @param {string} type
  * @param {string} [path]
  * @return {Promise<string>}
  */
-async function create (type, path) {
-  if (path === undefined) path = await directory.temp('toa-' + type)
-  else path = await directory.ensure(path)
+export async function create(type, path) {
+  if (path === undefined) return await mkdtemp(join(tmpdir(), 'toa-' + type))
+
+  path = resolve(path)
+
+  await mkdir(path, { recursive: true })
+
+  const entries = await readdir(path)
+
+  if (entries.length > 0) throw new Error('Target directory must be empty')
 
   return path
 }
-
-exports.create = create

package/src/index.js

@@ -1,3 +1,4 @@
-'use strict'
+export * as deployment from './deployment/index.js'
 
-exports.deployment = require('./deployment')
+// what conceals a secret in the cluster a deployment goes to; the CLI needs no package of its own for it
+export * as kubernetes from '@toa.io/kubernetes'

package/src/process.js

@@ -1,27 +1,65 @@
-'use strict'
-
-const execa = require('execa')
+import { spawn } from 'node:child_process'
 
 /**
  * @implements {toa.operations.Process}
  */
-class Process {
-  async execute (cmd, args, options = {}) {
+export class Process {
+  async execute(cmd, args, options = {}) {
     console.log('toa>', cmd, args.join(' '))
 
-    /** @type {execa.ExecaReturnValue<import('stream').Stream>} */
-    const command = execa(cmd, args)
+    const child = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'] })
+    const stdout = []
+    const stderr = []
+
+    child.stdout.on('data', (chunk) => stdout.push(chunk))
+    child.stderr.on('data', (chunk) => stderr.push(chunk))
 
     if (options.silently !== true) {
-      command.stdout.pipe(process.stdout)
-      command.stderr.pipe(process.stderr)
+      child.stdout.pipe(process.stdout)
+      child.stderr.pipe(process.stderr)
     }
 
-    /** @type {execa.ExecaReturnValue<string>} */
-    const result = await command
+    await exit(child, cmd, args, () => Buffer.concat(stderr).toString())
 
-    return result.stdout
+    return Buffer.concat(stdout).toString().replace(/\n$/, '')
   }
 }
 
-exports.Process = Process
+/**
+ * Runs a command on this process's own streams, and answers once it has exited.
+ *
+ * @param {string} cmd
+ * @param {string[]} args
+ * @returns {Promise<void>}
+ */
+export async function run(cmd, args) {
+  console.log('toa>', cmd, args.join(' '))
+
+  await exit(spawn(cmd, args, { stdio: 'inherit' }), cmd, args)
+}
+
+/**
+ * @param {import('node:child_process').ChildProcess} child
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {() => string} stderr
+ * @returns {Promise<void>}
+ */
+const exit = (child, cmd, args, stderr = () => '') =>
+  new Promise((resolve, reject) => {
+    child.once('error', reject)
+
+    child.once('close', (code, signal) => {
+      if (code === 0) return resolve()
+
+      const output = stderr()
+      const reason = signal === null ? `exit code ${code}` : signal
+
+      reject(
+        new Error(
+          `Command failed with ${reason}: ${cmd} ${args.join(' ')}` +
+            (output === '' ? '' : '\n' + output.trimEnd())
+        )
+      )
+    })
+  })

package/src/process.test.js

@@ -0,0 +1,33 @@
+import { it, describe } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { Process } from './process.js'
+
+describe('execute', () => {
+  it('should answer what the command wrote', async () => {
+    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, with what it wrote', async () => {
+    await assert.rejects(
+      new Process().execute(
+        'node',
+        ['-e', 'process.stderr.write("broken"); process.exit(2)'],
+        { silently: true }
+      ),
+      (error) => /exit code 2: node/.test(error.message) && /broken/.test(error.message)
+    )
+  })
+
+  it('should reject a command that does not exist', async () => {
+    await assert.rejects(
+      new Process().execute('toa-no-such-command', [], { silently: true })
+    )
+  })
+})

package/types/_deployment/composition.d.ts

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

package/types/_deployment/dependency.d.ts

@@ -1,11 +1,12 @@
-import * as _service from './service'
+import * as _service from './service.d.ts'
 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,8 +42,10 @@ declare namespace toa.deployment {
       name: string
       value?: string | number
       secret?: {
-        name: string,
+        name: string
         key: string
+        /** The workload starts without it, so the cluster need not hold it. */
+        optional?: boolean
       }
     }
 
@@ -50,8 +58,8 @@ declare namespace toa.deployment {
       services?: Service[] // dependency.Service
       proxies?: Proxy[]
       variables?: Variables
+      events?: string[]
     }
-
   }
 
   type Dependency = {
@@ -59,8 +67,8 @@ declare namespace toa.deployment {
     services?: _service.Service[] // deployment.Service
     proxies?: dependency.Proxy[]
     variables?: dependency.Variables
+    events?: string[]
   }
-
 }
 
 export type Declaration = toa.deployment.dependency.Declaration

package/types/_deployment/deployment.d.ts

@@ -1,9 +1,8 @@
-import type * as _composition from './composition'
-import type * as _service from './service'
-import type * as _dependency from './dependency'
+import type * as _composition from './composition.d.ts'
+import type * as _service from './service.d.ts'
+import type * as _dependency from './dependency.d.ts'
 
 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 {
@@ -48,13 +45,18 @@ declare namespace toa.deployment {
   interface Deployment {
     export(target: string): Promise<void>
 
+    /** Raises where the cluster does not hold a secret the workloads read. */
+    verify(options: installation.Options): Promise<void>
+
     install(options: installation.Options): Promise<void>
 
     template(options: template.Options): Promise<string>
 
-    variables(): _dependency.Variables
+    variables(options?: {
+      components?: string[]
+      services?: string[]
+    }): _dependency.Variable[]
   }
-
 }
 
 export namespace installation {

package/types/_deployment/factory.d.ts

@@ -1,14 +1,12 @@
-import type * as _operator from './operator'
-import * as _registry from './registry'
+import type * as _operator from './operator.d.ts'
+import * as _registry from './registry.d.ts'
 
 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

@@ -1,17 +1,15 @@
 // noinspection ES6UnusedImports
 
 import type { Composition } from '@toa.io/norm/types'
-import type { Image } from './image'
-import type { dependency } from '../dependency'
+import type { Image } from './image.d.ts'
+import type { dependency } from '../dependency.d.ts'
 
 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,14 +1,29 @@
 declare namespace toa.deployment.images {
-
   export interface Image {
     readonly reference: string
     readonly context: string
 
+    /** The image this one is laid over, built and pushed as an image of its own. */
+    readonly dependencies?: Image
+
+    /** Whether the build reads `registry.build.arguments`. */
+    readonly arguments?: boolean
+
+    name: string
+
     tag(): void
 
     prepare(root: string): Promise<string>
   }
 
+  /** Components in one image, laid over their dependencies. */
+  export interface Bundle extends Image {
+    readonly image?: string
+    readonly components: any[]
+
+    conflict(): string
+  }
 }
 
 export type Image = toa.deployment.images.Image
+export type Bundle = toa.deployment.images.Bundle

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

@@ -1,20 +1,17 @@
 // noinspection ES6UnusedImports
 
 import type { Composition } from '@toa.io/norm'
-import type { dependency } from '../dependency'
-import type { Image } from "./image"
+import type { dependency } from '../dependency.d.ts'
+import type { Image } from './image.d.ts'
 
 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

@@ -1,20 +1,21 @@
-import * as _deployment from './deployment'
-import * as _dependency from './dependency'
+import * as _deployment from './deployment.d.ts'
+import * as _dependency from './dependency.d.ts'
 
 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(options?: {
+      components?: string[]
+      services?: string[]
+    }): _dependency.Variable[]
 
-    listVariables (): _dependency.Variable[]
+    listVariables(): _dependency.Variable[]
   }
-
 }
 
 export type Operator = toa.deployment.Operator

package/types/_deployment/registry.d.ts

@@ -1,9 +1,8 @@
 import type * as _norm from '@toa.io/norm/types'
-import type * as _dependency from './dependency'
-import type * as _image from "./images/image"
+import type * as _dependency from './dependency.d.ts'
+import type * as _image from './images/image.d.ts'
 
 declare namespace toa.deployment {
-  
   interface Registry {
     composition(composition: _norm.Composition): _image.Image
 
@@ -14,8 +13,12 @@ declare namespace toa.deployment {
     build(): Promise<void>
 
     push(): Promise<void>
-  }
 
+    /** Point each workload image at `environment` (`:production`). `deps-*` is not tagged. */
+    alias(environment?: string): Promise<void>
+
+    tags(): string[]
+  }
 }
 
 export type Registry = toa.deployment.Registry

package/types/_deployment/service.d.ts

@@ -1,7 +1,6 @@
-import type * as _deployment from './deployment'
+import type * as _deployment from './deployment.d.ts'
 
 declare namespace toa.deployment {
-
   interface Ingress {
     host: string
     class: string
@@ -11,8 +10,10 @@ declare namespace toa.deployment {
   interface Service extends _deployment.Deployable {
     port: number
     ingress?: Ingress
-  }
 
+    /** Annotations for the Service itself, as opposed to `ingress.annotations`. */
+    annotations?: object
+  }
 }
 
 export type Service = toa.deployment.Service