@toa.io/extensions.configuration 1.0.0-alpha.284 → 1.0.0-alpha.286

package/source/Secret.test.ts

@@ -23,7 +23,7 @@ it('should not show in JSON', () => {
 it('should not show when inspected', () => {
   assert.deepStrictEqual(inspect(secret), REDACTED)
   assert.ok(inspect({ key: secret }).includes(REDACTED))
-  assert.ok(!(inspect({ key: secret }).includes('s3cret')))
+  assert.ok(!inspect({ key: secret }).includes('s3cret'))
 })
 
 it('should not expose the value as a property', () => {

package/source/Secret.ts

@@ -8,23 +8,23 @@ import { inspect } from 'node:util'
 export class Secret {
   readonly #value: string
 
-  public constructor (value: string) {
+  public constructor(value: string) {
     this.#value = value
   }
 
-  public unwrap (): string {
+  public unwrap(): string {
     return this.#value
   }
 
-  public toString (): string {
+  public toString(): string {
     return REDACTED
   }
 
-  public toJSON (): string {
+  public toJSON(): string {
     return REDACTED
   }
 
-  public [inspect.custom] (): string {
+  public [inspect.custom](): string {
     return REDACTED
   }
 }

package/source/UI.ts

@@ -17,7 +17,7 @@ export class UI extends Connector {
   private readonly port: number
   private readonly root: string
 
-  public constructor (port: number, root: string = SITE) {
+  public constructor(port: number, root: string = SITE) {
     super()
 
     this.port = port
@@ -27,7 +27,7 @@ export class UI extends Connector {
     })
   }
 
-  protected override async open (): Promise<void> {
+  protected override async open(): Promise<void> {
     /*
      * A taken port is a real error: uniqueness across services is settled at export
      * time, so nothing here has to negotiate for one.
@@ -54,10 +54,12 @@ export class UI extends Connector {
     console.info('Configuration UI started', { port: this.port, path: UI_PATH + '/' })
   }
 
-  protected override async close (): Promise<void> {
-    const closed = new Promise<void>((resolve) => this.server.once('close', () => {
-      resolve()
-    }))
+  protected override async close(): Promise<void> {
+    const closed = new Promise<void>((resolve) =>
+      this.server.once('close', () => {
+        resolve()
+      })
+    )
 
     this.server.close()
     this.server.closeAllConnections()
@@ -65,16 +67,18 @@ export class UI extends Connector {
     await closed
   }
 
-  private listen (request: http.IncomingMessage, response: http.ServerResponse): void {
+  private listen(request: http.IncomingMessage, response: http.ServerResponse): void {
     void this.respond(request, response).catch((error: Error) => {
       console.error('Configuration UI failure', { message: error.message })
 
-      if (!response.writableEnded)
-        response.writeHead(500).end()
+      if (!response.writableEnded) response.writeHead(500).end()
     })
   }
 
-  private async respond (request: http.IncomingMessage, response: http.ServerResponse): Promise<void> {
+  private async respond(
+    request: http.IncomingMessage,
+    response: http.ServerResponse
+  ): Promise<void> {
     if (request.method !== 'GET' && request.method !== 'HEAD') {
       response.writeHead(405, { allow: 'GET, HEAD' }).end()
 
@@ -98,10 +102,8 @@ export class UI extends Connector {
 
     const file = this.resolve(pathname)
 
-    if (file === null)
-      response.writeHead(404).end()
-    else
-      await this.send(file, request, response)
+    if (file === null) response.writeHead(404).end()
+    else await this.send(file, request, response)
   }
 
   /**
@@ -109,22 +111,18 @@ export class UI extends Connector {
    * served as it is; anything else that could be a route falls back to the page,
    * because the client router — not this server — knows what routes there are.
    */
-  private resolve (pathname: string): string | null {
-    if (!pathname.startsWith(UI_PATH))
-      return null
+  private resolve(pathname: string): string | null {
+    if (!pathname.startsWith(UI_PATH)) return null
 
     const relative = pathname.slice(UI_PATH.length)
 
-    if (relative !== '' && !relative.startsWith('/'))
-      return null
+    if (relative !== '' && !relative.startsWith('/')) return null
 
     const file = path.join(this.root, relative)
 
-    if (file !== this.root && !file.startsWith(this.root + path.sep))
-      return null
+    if (file !== this.root && !file.startsWith(this.root + path.sep)) return null
 
-    if (isFile(file))
-      return file
+    if (isFile(file)) return file
 
     /*
      * A missing asset is missing, but a route can look like one: `identity.passkeys` is a
@@ -137,11 +135,16 @@ export class UI extends Connector {
     return asset ? null : path.join(this.root, 'index.html')
   }
 
-  private async send (file: string, request: http.IncomingMessage, response: http.ServerResponse): Promise<void> {
+  private async send(
+    file: string,
+    request: http.IncomingMessage,
+    response: http.ServerResponse
+  ): Promise<void> {
     const stats = await fs.promises.stat(file).catch(() => null)
 
     if (stats === null) {
-      response.writeHead(503, { 'content-type': 'text/plain' })
+      response
+        .writeHead(503, { 'content-type': 'text/plain' })
         .end('The configuration UI is not built. Run `npm run build:ui`.\n')
 
       return
@@ -153,14 +156,12 @@ export class UI extends Connector {
       'cache-control': caching(path.relative(this.root, file))
     })
 
-    if (request.method === 'HEAD')
-      response.end()
-    else
-      fs.createReadStream(file).pipe(response)
+    if (request.method === 'HEAD') response.end()
+    else fs.createReadStream(file).pipe(response)
   }
 }
 
-function decode (url: string): string | null {
+function decode(url: string): string | null {
   try {
     return decodeURIComponent(url.split('?')[0])
   } catch {
@@ -168,7 +169,7 @@ function decode (url: string): string | null {
   }
 }
 
-function isFile (file: string): boolean {
+function isFile(file: string): boolean {
   return fs.existsSync(file) && fs.statSync(file).isFile()
 }
 
@@ -188,7 +189,7 @@ const DAY = 'public, max-age=86400'
  * and their names carry the build. An icon is named for what it is rather than for its
  * content, so it is asked about again, but not on every page load.
  */
-function caching (relative: string): string {
+function caching(relative: string): string {
   if (relative.startsWith(IMMUTABLE)) return FOREVER
 
   return ICONS.has(relative) ? DAY : 'no-cache'

package/source/configuration.test.ts

@@ -21,8 +21,7 @@ beforeEach(() => {
 })
 
 afterEach(() => {
-  for (const name of used)
-    delete process.env[name]
+  for (const name of used) delete process.env[name]
 
   used = []
 })
@@ -92,14 +91,21 @@ describe('local', () => {
     manifest.schema = {
       type: 'object',
       properties: {
-        foo: { type: 'string', default: 'hello' },
+        foo: { type: 'string' },
         bar: { type: 'number' }
       }
     }
 
     set({ bar: 5 })
 
-    assert.deepStrictEqual(local(locator, manifest), { foo: 'hello', bar: 5 })
+    assert.deepStrictEqual(local(locator, manifest), { bar: 5 })
+
+    set({ bar: 'five' })
+
+    assert.throws(
+      () => local(locator, manifest),
+      (error: Error) => /must be number/.test(error.message)
+    )
   })
 })
 
@@ -109,18 +115,18 @@ describe('fit', () => {
       type: 'object',
       properties: {
         foo: { type: 'string' },
-        bar: { type: 'number', default: 1 }
+        bar: { type: 'number' }
       }
     }
 
     set('secret', '_FOO')
 
-    const raw = { foo: '$FOO' }
+    const raw = { foo: '$FOO', bar: 1 }
     const values = fit(raw, manifest)
 
     assert.deepStrictEqual((values.foo as Secret).unwrap(), 'secret')
     assert.deepStrictEqual(values.bar, 1)
-    assert.deepStrictEqual(raw, { foo: '$FOO' }) // untouched
+    assert.deepStrictEqual(raw, { foo: '$FOO', bar: 1 }) // untouched
   })
 
   it('should not apply the manifest defaults', async () => {
@@ -134,7 +140,7 @@ describe('fit', () => {
   })
 })
 
-function set (value: object | string, key = locator.uppercase): void {
+function set(value: object | string, key = locator.uppercase): void {
   const string = typeof value === 'string' ? value : JSON.stringify(value)
   const name = 'TOA_CONFIGURATION_' + key
 

package/source/configuration.ts

@@ -7,22 +7,21 @@ import type { Schema } from '@toa.io/schemas'
 import type { Manifest } from './manifest.js'
 
 /** The variable is set, so the values service is not consulted. */
-export function overridden (locator: Locator): boolean {
+export function overridden(locator: Locator): boolean {
   return process.env[PREFIX + locator.uppercase] !== undefined
 }
 
 /** The variable, the manifest defaults, then the schema. */
-export function local (locator: Locator, manifest: Manifest): Node {
+export function local(locator: Locator, manifest: Manifest): Node {
   const values = read(locator.uppercase)
 
-  if (manifest.defaults !== undefined)
-    add(values, manifest.defaults)
+  if (manifest.defaults !== undefined) add(values, manifest.defaults)
 
   return fit(values, manifest)
 }
 
 /** A copy of the value with the schema applied and the secrets substituted. */
-export function fit (raw: object, manifest: Manifest): Node {
+export function fit(raw: object, manifest: Manifest): Node {
   // a copy of the caller's, and one of this realm: what came over the wire is JSON anyway
   const values = JSON.parse(JSON.stringify(raw)) as Node
 
@@ -33,26 +32,23 @@ export function fit (raw: object, manifest: Manifest): Node {
   return values
 }
 
-function validate (values: Node, manifest: Manifest): void {
+function validate(values: Node, manifest: Manifest): void {
   const schema: Schema<any> = schemas.schema(manifest.schema)
 
   schema.validate(values)
 }
 
-function read (suffix: string): Node {
+function read(suffix: string): Node {
   const variable = PREFIX + suffix
   const string = process.env[variable]
 
-  if (string === undefined)
-    return {}
-  else
-    return JSON.parse(string)
+  if (string === undefined) return {}
+  else return JSON.parse(string)
 }
 
-function substituteSecrets (configuration: Node): void {
+function substituteSecrets(configuration: Node): void {
   for (const [key, value] of Object.entries(configuration)) {
-    if (typeof value === 'object' && value !== null)
-      substituteSecrets(value as Node)
+    if (typeof value === 'object' && value !== null) substituteSecrets(value as Node)
 
     if (typeof value !== 'string') continue
 
@@ -66,7 +62,7 @@ function substituteSecrets (configuration: Node): void {
   }
 }
 
-function getSecret (name: string): string {
+function getSecret(name: string): string {
   const variable = PREFIX + '_' + name
   const value = process.env[variable]
 

package/source/const.ts

@@ -1,4 +1,4 @@
-import type { Source } from '@toa.io/core'
+import type { Source } from '@toa.io/core/types'
 
 /** Per-component variables: the local override and the secrets. */
 export const PREFIX = 'TOA_CONFIGURATION_'
@@ -12,6 +12,18 @@ export const SECRET_RX = /^\$(?<variable>[A-Z0-9_]{1,32})$/
 export const UI_PATH = '/.configuration'
 export const UI_PORT = 8003
 
+/**
+ * The port the UI is served on. `UI_PORT` is what a deployment publishes and what the chart
+ * renders; the variable is for a machine that runs more than one Toa process — a Toa checkout
+ * beside an application, or two applications — where one of them has to give it up.
+ */
+export const UI_PORT_ENV = 'TOA_CONFIGURATION_UI_PORT'
+export function uiPort(): number {
+  const value = process.env[UI_PORT_ENV]
+
+  return value === undefined ? UI_PORT : Number(value)
+}
+
 export const EVENT = 'configuration.values.created'
 
 export const SOURCE: Source = { service: 'configuration' }

package/source/context.ts

@@ -1,8 +1,8 @@
 import type { Manifest } from './manifest.js'
-import type { Contribution } from '@toa.io/core'
+import type { Contribution } from '@toa.io/core/types'
 
 /** What this extension puts on the context of a component that declares it. */
-export function context (declaration: Manifest): Contribution {
+export function context(declaration: Manifest): Contribution {
   const contribution: Contribution = { name: 'configuration', schema: declaration.schema }
 
   // a value the schema declares a secret is one on the context, not a string

package/source/deployment.test.ts

@@ -2,7 +2,12 @@ import { it } from 'node:test'
 import assert from 'node:assert/strict'
 
 import { Locator } from '@toa.io/core'
-import { type Annotation, type Instance, deployment, describe as map } from './deployment.js'
+import {
+  type Annotation,
+  type Instance,
+  deployment,
+  describe as map
+} from './deployment.js'
 import { epoch } from './epoch.js'
 import { EVENT, VALUES } from './const.js'
 
@@ -11,7 +16,7 @@ const schema = {
   properties: { foo: { type: 'string' }, key: { type: 'string' } }
 }
 
-function instance (name: string, defaults?: Record<string, unknown>): Instance {
+function instance(name: string, defaults?: Record<string, unknown>): Instance {
   return {
     locator: new Locator(name, 'configuration'),
     manifest: { schema, defaults },
@@ -22,11 +27,18 @@ function instance (name: string, defaults?: Record<string, unknown>): Instance {
 it('should validate annotation', async () => {
   const wrongType = 'not ok' as unknown as Annotation
 
-  assert.throws(() => deployment([], wrongType), (error: any) => /object/.test(error.message))
+  assert.throws(
+    () => deployment([], wrongType),
+    (error: any) => /object/.test(error.message)
+  )
 })
 
 it('should reject unknown components', async () => {
-  assert.throws(() => deployment([instance('base')], { 'configuration.nope': {} }), (error: any) => /Component 'configuration\.nope' does not request configuration/.test(error.message))
+  assert.throws(
+    () => deployment([instance('base')], { 'configuration.nope': {} }),
+    (error: any) =>
+      /Component 'configuration\.nope' does not request configuration/.test(error.message)
+  )
 })
 
 it('should deploy the values service with the map', async () => {
@@ -61,27 +73,40 @@ it('should describe every component', async () => {
 })
 
 it('should prefer the context over the manifest defaults', async () => {
-  const values = map([instance('base', { foo: 'hello' })], { 'configuration.base': { foo: 'bye' } })
+  const values = map([instance('base', { foo: 'hello' })], {
+    'configuration.base': { foo: 'bye' }
+  })
 
   assert.deepStrictEqual(values['configuration.base'].defaults, { foo: 'bye' })
 })
 
 it('should not map values to the component', async () => {
-  const dependency = deployment([instance('base')], { 'configuration.base': { foo: 'set' } })
+  const dependency = deployment([instance('base')], {
+    'configuration.base': { foo: 'set' }
+  })
 
   assert.deepStrictEqual(dependency.variables, {})
 })
 
 it('should map secrets to the component', async () => {
-  const dependency = deployment([instance('base')], { 'configuration.base': { key: '$KEY' } })
+  const dependency = deployment([instance('base')], {
+    'configuration.base': { key: '$KEY' }
+  })
 
   assert.deepStrictEqual(dependency.variables, {
-    'configuration-base': [{
-      name: 'TOA_CONFIGURATION__KEY',
-      secret: { name: 'toa-configuration', key: 'KEY' }
-    }]
+    'configuration-base': [
+      {
+        name: 'TOA_CONFIGURATION__KEY',
+        secret: { name: 'toa-configuration', key: 'KEY' }
+      }
+    ]
   })
 
   // the service holds the reference, not the secret
-  assert.deepStrictEqual(map([instance('base')], { 'configuration.base': { key: '$KEY' } })['configuration.base'].defaults, { key: '$KEY' })
+  assert.deepStrictEqual(
+    map([instance('base')], { 'configuration.base': { key: '$KEY' } })[
+      'configuration.base'
+    ].defaults,
+    { key: '$KEY' }
+  )
 })

package/source/deployment.ts

@@ -1,6 +1,13 @@
 import { readFileSync } from 'node:fs'
 import assert from 'node:assert'
-import { type Dependency, type Resources, type Service, type Variable, type Variables } from '@toa.io/operations'
+import {
+  type Dependency,
+  type Resources,
+  type Service,
+  type Variable,
+  type Variables
+} from '@toa.io/operations'
+import { add } from '@toa.io/generic'
 import { components } from './Composition.js'
 import { EVENT, PREFIX, SECRET_RX, UI_PATH, UI_PORT, VALUES } from './const.js'
 import { epoch } from './epoch.js'
@@ -8,7 +15,14 @@ import * as validators from './schemas.js'
 import type { Manifest } from './manifest.js'
 import type { context } from '@toa.io/norm'
 
-export function deployment (instances: Instance[], annotation: Annotation = {}): Dependency {
+/** Where Toa's release publishes this service's image. An application takes it
+ *  instead of building one when its context says `registry.services: published`. */
+export const image = 'ghcr.io/toa-io/extension-configuration-values'
+
+export function deployment(
+  instances: Instance[],
+  annotation: Annotation = {}
+): Dependency {
   const { resources, values } = split(annotation)
 
   annotation = prepare(values, instances)
@@ -18,50 +32,60 @@ export function deployment (instances: Instance[], annotation: Annotation = {}):
   for (const instance of instances) {
     const values = annotation[instance.locator.id]
 
-    if (values === undefined)
-      continue
+    if (values === undefined) continue
 
     const secrets = createSecrets(values)
 
-    if (secrets.length > 0)
-      variables[instance.locator.label] = secrets
+    if (secrets.length > 0) variables[instance.locator.label] = secrets
   }
 
   const service: Service = {
     group: 'configuration',
     name: 'values',
-    version: JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version,
+    image,
+    version: JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+      .version,
     components: components().labels,
     resources,
     // the service that holds the values also serves the page that reads them
     port: UI_PORT,
     ingress: { path: UI_PATH },
-    variables: [{
-      name: VALUES,
-      value: JSON.stringify(describe(instances, annotation))
-    }]
+    variables: [
+      {
+        name: VALUES,
+        value: JSON.stringify(describe(instances, annotation))
+      }
+    ]
   }
 
   return { services: [service], variables, events: [EVENT] }
 }
 
 /** What the values service is given: the epoch, the schema and the defaults of every component. */
-export function describe (instances: Instance[], annotation: Annotation = {}): Values {
+export function describe(instances: Instance[], annotation: Annotation = {}): Values {
   annotation = prepare(split(annotation).values, instances)
 
   const values: Values = {}
 
-  for (const { locator, manifest } of instances)
+  for (const { locator, manifest } of instances) {
+    const deployed = annotation[locator.id]
+
     values[locator.id] = {
       epoch: epoch(manifest.schema),
       schema: manifest.schema,
-      defaults: annotation[locator.id] ?? manifest.defaults
+      // what the Context says stands over what the manifest declares, value by value: a
+      // deployment that names one of them does not thereby unset the rest
+      defaults:
+        deployed === undefined
+          ? manifest.defaults
+          : add(structuredClone(deployed), manifest.defaults ?? {})
     }
+  }
 
   return values
 }
 
-function createSecrets (values: object): Variable[] {
+function createSecrets(values: object): Variable[] {
   const secrets: Variable[] = []
 
   for (const value of Object.values(values)) {
@@ -98,7 +122,7 @@ function createSecrets (values: object): Variable[] {
  * called that is written with its namespace, `default.resources`, which is what an id is
  * anyway — the bare form is the shorthand.
  */
-function split (annotation: Annotation): { resources?: Resources, values: Annotation } {
+function split(annotation: Annotation): { resources?: Resources; values: Annotation } {
   validators.annotation.validate(annotation)
 
   const { resources, ...values } = annotation as Annotation & { resources?: Resources }
@@ -107,15 +131,17 @@ function split (annotation: Annotation): { resources?: Resources, values: Annota
 }
 
 /** Validated, keyed by full component ids, and checked against the components that ask. */
-function prepare (annotation: Annotation, instances: Instance[]): Annotation {
+function prepare(annotation: Annotation, instances: Instance[]): Annotation {
   const normalized: Annotation = {}
   const requested = instances.map((instance) => instance.locator.id)
 
   for (const [key, values] of Object.entries(annotation)) {
     const id = key.includes('.') ? key : 'default.' + key
 
-    assert.ok(requested.includes(id),
-      `Component '${id}' does not request configuration or does not exist.`)
+    assert.ok(
+      requested.includes(id),
+      `Component '${id}' does not request configuration or does not exist.`
+    )
 
     normalized[id] = values
   }

package/source/epoch.test.ts

@@ -8,8 +8,14 @@ it('should be a sha256 hex', () => {
 })
 
 it('should not depend on key order', () => {
-  const a = { type: 'object', properties: { foo: { type: 'string', default: 'x' }, bar: { type: 'number' } } }
-  const b = { properties: { bar: { type: 'number' }, foo: { default: 'x', type: 'string' } }, type: 'object' }
+  const a = {
+    type: 'object',
+    properties: { foo: { type: 'string', default: 'x' }, bar: { type: 'number' } }
+  }
+  const b = {
+    properties: { bar: { type: 'number' }, foo: { default: 'x', type: 'string' } },
+    type: 'object'
+  }
 
   assert.deepStrictEqual(epoch(a), epoch(b))
 })

package/source/epoch.ts

@@ -1,17 +1,18 @@
 import { createHash } from 'node:crypto'
 
 /** The same for the same schema, whatever the key order it was written in. */
-export function epoch (schema: object): string {
+export function epoch(schema: object): string {
   return createHash('sha256').update(canonical(schema)).digest('hex')
 }
 
-function canonical (value: unknown): string {
-  if (Array.isArray(value))
-    return '[' + value.map(canonical).join(',') + ']'
+function canonical(value: unknown): string {
+  if (Array.isArray(value)) return '[' + value.map(canonical).join(',') + ']'
 
   if (value !== null && typeof value === 'object') {
     const object = value as Record<string, unknown>
-    const keys = Object.keys(object).filter((key) => object[key] !== undefined).sort()
+    const keys = Object.keys(object)
+      .filter((key) => object[key] !== undefined)
+      .sort()
     const entries = keys.map((key) => JSON.stringify(key) + ':' + canonical(object[key]))
 
     return '{' + entries.join(',') + '}'

package/source/index.ts

@@ -1,5 +1,5 @@
 export { manifest } from './manifest.js'
-export { deployment, describe } from './deployment.js'
+export { deployment, describe, image } from './deployment.js'
 export { components } from './Composition.js'
 export { Factory } from './Factory.js'
 

package/source/manifest.test.ts

@@ -6,13 +6,19 @@ import { type Manifest, manifest } from './manifest.js'
 it('should validate', async () => {
   const additional = { schema: {}, foo: 'bar' } as unknown as Manifest
 
-  assert.throws(() => {
-    manifest(additional)
-  }, (error: any) => /not expected/.test(error.message))
+  assert.throws(
+    () => {
+      manifest(additional)
+    },
+    (error: any) => /not expected/.test(error.message)
+  )
 
   const wrongType = { schema: 'not ok' } as unknown as Manifest
 
-  assert.throws(() => {
-    manifest(wrongType)
-  }, (error: any) => /object/.test(error.message))
+  assert.throws(
+    () => {
+      manifest(wrongType)
+    },
+    (error: any) => /object/.test(error.message)
+  )
 })