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

package/source/Client.ts

@@ -1,7 +1,8 @@
 import { console } from 'openspan'
 import { Connector, Locator } from '@toa.io/core'
 import { EVENT, SOURCE } from './const.js'
-import type { Message, Remote } from '@toa.io/core'
+import type { Remote } from '@toa.io/core'
+import type { Message } from '@toa.io/core/types'
 import type { Host } from './Factory.js'
 
 /**
@@ -23,7 +24,7 @@ export class Client extends Connector {
   private fresh = false
   private round = 0
 
-  public constructor (host: Host, options: Partial<Options> = {}) {
+  public constructor(host: Host, options: Partial<Options> = {}) {
     super()
 
     this.host = host
@@ -31,7 +32,7 @@ export class Client extends Connector {
   }
 
   /** The configuration of a component for an epoch, once the service has one. */
-  public async fetch (component: string, epoch: string): Promise<Value> {
+  public async fetch(component: string, epoch: string): Promise<Value> {
     const key = id(component, epoch)
 
     let entry = this.pending.get(key)
@@ -45,28 +46,25 @@ export class Client extends Connector {
       entry!.waiters.push(resolve)
     })
 
-    if (this.flushing)
-      this.fresh = true
-    else
-      this.schedule(0)
+    if (this.flushing) this.fresh = true
+    else this.schedule(0)
 
     return await promise
   }
 
-  public subscribe (component: string, epoch: string, listener: Listener): void {
+  public subscribe(component: string, epoch: string, listener: Listener): void {
     const key = id(component, epoch)
 
-    if (!this.listeners.has(key))
-      this.listeners.set(key, new Set())
+    if (!this.listeners.has(key)) this.listeners.set(key, new Set())
 
     this.listeners.get(key)!.add(listener)
   }
 
-  public unsubscribe (component: string, epoch: string, listener: Listener): void {
+  public unsubscribe(component: string, epoch: string, listener: Listener): void {
     this.listeners.get(id(component, epoch))?.delete(listener)
   }
 
-  protected override async open (): Promise<void> {
+  protected override async open(): Promise<void> {
     this.remote = await this.host.remote(LOCATOR, SOURCE)
 
     this.depends(this.remote)
@@ -79,25 +77,23 @@ export class Client extends Connector {
     await consumer.connect()
   }
 
-  protected override async close (): Promise<void> {
+  protected override async close(): Promise<void> {
     if (this.timer !== null) {
       clearTimeout(this.timer)
       this.timer = null
     }
   }
 
-  protected override async dispose (): Promise<void> {
+  protected override async dispose(): Promise<void> {
     this.disposed = true
   }
 
-  private schedule (delay: number): void {
-    if (this.flushing)
-      return
+  private schedule(delay: number): void {
+    if (this.flushing) return
 
     if (this.timer !== null) {
       // a request that has just arrived does not wait for the round already planned
-      if (delay > 0)
-        return
+      if (delay > 0) return
 
       clearTimeout(this.timer)
     }
@@ -107,7 +103,7 @@ export class Client extends Connector {
     }, delay)
   }
 
-  private async flush (): Promise<void> {
+  private async flush(): Promise<void> {
     this.timer = null
     this.flushing = true
     this.fresh = false
@@ -118,8 +114,7 @@ export class Client extends Connector {
     try {
       const output = await this.remote!.invoke<Fetched[] | Error>('fetch', { input })
 
-      if (output instanceof Error)
-        throw output
+      if (output instanceof Error) throw output
 
       this.settle(output)
     } catch (error) {
@@ -130,35 +125,29 @@ export class Client extends Connector {
 
     this.report(batch)
 
-    if (this.pending.size === 0)
-      return
+    if (this.pending.size === 0) return
 
-    if (this.fresh)
-      this.schedule(0)
-    else
-      this.schedule(this.backoff())
+    if (this.fresh) this.schedule(0)
+    else this.schedule(this.backoff())
   }
 
   /** Those the service has served are told; the rest stay for the next round. */
-  private settle (output: Fetched[]): void {
+  private settle(output: Fetched[]): void {
     for (const { component, epoch, configuration, created } of output) {
-      if (configuration === null)
-        continue
+      if (configuration === null) continue
 
       const key = id(component, epoch)
       const entry = this.pending.get(key)
 
-      if (entry === undefined)
-        continue
+      if (entry === undefined) continue
 
       this.pending.delete(key)
 
-      for (const resolve of entry.waiters)
-        resolve({ configuration, created })
+      for (const resolve of entry.waiters) resolve({ configuration, created })
     }
   }
 
-  private report (batch: Pending[]): void {
+  private report(batch: Pending[]): void {
     const waiting = batch
       .filter(({ component, epoch }) => this.pending.has(id(component, epoch)))
       .map(({ component }) => component)
@@ -172,24 +161,28 @@ export class Client extends Connector {
     this.round++
 
     if (this.round % this.options.warn === 1)
-      console.warn('Waiting for configuration', { components: waiting, round: this.round })
+      console.warn('Waiting for configuration', {
+        components: waiting,
+        round: this.round
+      })
   }
 
-  private backoff (): number {
+  private backoff(): number {
     return Math.min(this.options.base * Math.pow(FACTOR, this.round), this.options.max)
   }
 
   /** A created object goes to the subscribers of its component and epoch, as it is. */
-  private deliver (created: Created): void {
+  private deliver(created: Created): void {
     const listeners = this.listeners.get(id(created.component, created.epoch))
 
-    if (listeners === undefined)
-      return
+    if (listeners === undefined) return
 
-    const value: Value = { configuration: created.configuration, created: created._created }
+    const value: Value = {
+      configuration: created.configuration,
+      created: created.CREATED
+    }
 
-    for (const listener of listeners)
-      listener(value)
+    for (const listener of listeners) listener(value)
   }
 }
 
@@ -197,18 +190,18 @@ export class Client extends Connector {
 class Subscription extends Connector {
   private readonly handler: (created: Created) => void
 
-  public constructor (handler: (created: Created) => void) {
+  public constructor(handler: (created: Created) => void) {
     super()
 
     this.handler = handler
   }
 
-  public async receive (message: Message<Created>): Promise<void> {
+  public async receive(message: Message<Created>): Promise<void> {
     this.handler(message.payload)
   }
 }
 
-function id (component: string, epoch: string): string {
+function id(component: string, epoch: string): string {
   return component + '\0' + epoch
 }
 
@@ -246,7 +239,7 @@ export interface Created {
   component: string
   epoch: string
   configuration: object
-  _created: number
+  CREATED: number
 }
 
 export type Listener = (value: Value) => void

package/source/Composition.ts

@@ -1,7 +1,7 @@
 import { readdirSync, type Dirent } from 'node:fs'
 import { resolve } from 'node:path'
 import { Connector } from '@toa.io/core'
-import { UI_PORT } from './const.js'
+import { uiPort } from './const.js'
 import { UI } from './UI.js'
 import type { Host } from './Factory.js'
 
@@ -9,12 +9,12 @@ import type { Host } from './Factory.js'
 export class Composition extends Connector {
   private readonly host: Host
 
-  public constructor (host: Host) {
+  public constructor(host: Host) {
     super()
     this.host = host
   }
 
-  protected override async open (): Promise<void> {
+  protected override async open(): Promise<void> {
     const composition = await this.host.composition(components().paths)
 
     await composition.connect()
@@ -23,7 +23,7 @@ export class Composition extends Connector {
 
     // connected here rather than declared as a dependency: dependencies are connected
     // before `open` runs, so one added from inside it would never be
-    const ui = new UI(UI_PORT)
+    const ui = new UI(uiPort())
 
     await ui.connect()
 
@@ -31,7 +31,7 @@ export class Composition extends Connector {
   }
 }
 
-export function components (): Components {
+export function components(): Components {
   const labels: string[] = []
   const paths: string[] = []
 
@@ -43,7 +43,7 @@ export function components (): Components {
   return { labels, paths }
 }
 
-function entries (): Dirent[] {
+function entries(): Dirent[] {
   const entries = readdirSync(ROOT, { withFileTypes: true })
 
   return entries.filter((entry) => entry.isDirectory())

package/source/Factory.ts

@@ -1,4 +1,5 @@
-import { type Connector, type Locator, type extensions } from '@toa.io/core'
+import { type Connector, type Locator } from '@toa.io/core'
+import type { extensions } from '@toa.io/core/types'
 import { Aspect } from './Aspect.js'
 import { Client } from './Client.js'
 import { Composition } from './Composition.js'
@@ -9,23 +10,22 @@ export class Factory implements extensions.Factory {
   private readonly host: Host
   private client: Client | null = null
 
-  public constructor (host: Host) {
+  public constructor(host: Host) {
     this.host = host
   }
 
-  public aspect (locator: Locator, manifest: Manifest): extensions.Aspect {
+  public aspect(locator: Locator, manifest: Manifest): extensions.Aspect {
     const client = overridden(locator) ? null : this.shared()
 
     return new Aspect(locator, manifest, client)
   }
 
-  public service (): Connector {
+  public service(): Connector {
     return new Composition(this.host)
   }
 
-  private shared (): Client {
-    if (this.client === null || this.client.disposed)
-      this.client = new Client(this.host)
+  private shared(): Client {
+    if (this.client === null || this.client.disposed) this.client = new Client(this.host)
 
     return this.client
   }

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