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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/extensions.configuration",
-  "version": "1.0.0-alpha.284",
+  "version": "1.0.0-alpha.286",
   "type": "module",
   "description": "Toa Configuration",
   "author": "temich <tema.gurtovoy@gmail.com>",
@@ -23,11 +23,11 @@
     "prepack": "npm run build:ui",
     "features": "TSX_TSCONFIG_PATH=features/steps/tsconfig.json NODE_OPTIONS=--import=tsx cucumber-js"
   },
-  "gitHead": "006755556879e91e8d68fa86753aa3b475bdf4bf",
+  "gitHead": "81f3d0688f17668b902be336d1749cc715edcdb6",
   "dependencies": {
-    "@toa.io/core": "1.0.0-alpha.284",
-    "@toa.io/generic": "1.0.0-alpha.283",
-    "@toa.io/schemas": "1.0.0-alpha.283",
-    "openspan": "1.0.0-alpha.277"
+    "@toa.io/core": "1.0.0-alpha.286",
+    "@toa.io/generic": "1.0.0-alpha.286",
+    "@toa.io/schemas": "1.0.0-alpha.286",
+    "openspan": "1.0.0-alpha.286"
   }
 }

package/readme.md

@@ -25,7 +25,7 @@ configuration:
 ### Use
 
 ```javascript
-function transition (input, entity, context) {
+function transition(input, entity, context) {
   const { foo, bar } = context.configuration
 
   // ...
@@ -38,9 +38,9 @@ function transition (input, entity, context) {
 # context.toa.yaml
 configuration:
   dummies.dummy:
-    foo: qux          # override default value
+    foo: qux # override default value
     foo@staging: quux # deployment environment discriminator
-    bar: $BAZ_VALUE   # secret
+    bar: $BAZ_VALUE # secret
 ```
 
 ### Deploy secrets
@@ -176,7 +176,7 @@ In the component, a secret is a `Secret` object: `unwrap()` returns the string,
 `toString()`, JSON and `util.inspect` give `<REDACTED>`.
 
 ```javascript
-function transition (input, entity, context) {
+function transition(input, entity, context) {
   const key = context.configuration.apiKey.unwrap()
 
   // ...
@@ -231,11 +231,11 @@ object as stored.
 
 ### Resources
 
-| Method | Path                                  | Role                          |
-|--------|---------------------------------------|-------------------------------|
-| `GET`  | `/configuration/values/`              | `system:configuration:get`    |
-| `GET`  | `/configuration/values/:component/`   | `system:configuration:get`    |
-| `POST` | `/configuration/values/:component/`   | `system:configuration:create` |
+| Method | Path                                | Role                          |
+| ------ | ----------------------------------- | ----------------------------- |
+| `GET`  | `/configuration/values/`            | `system:configuration:get`    |
+| `GET`  | `/configuration/values/:component/` | `system:configuration:get`    |
+| `POST` | `/configuration/values/:component/` | `system:configuration:create` |
 
 `GET /configuration/values/` lists every component's configuration for its deployed epoch, by
 component name, as `[{ component, epoch, schema, configuration }]`.
@@ -261,7 +261,7 @@ annotation is the per-component values map and has nowhere to carry a switch.
 Component's configuration values are available as a well-known Aspect `configuration`.
 
 ```javascript
-function transition (input, entity, context) {
+function transition(input, entity, context) {
   const foo = context.configuration.foo
 
   // ...
@@ -270,14 +270,15 @@ function transition (input, entity, context) {
 
 On start, a component requests its configuration for its epoch from the values service and
 waits until there is one, reporting every fifth attempt. The schema is applied, and secrets
-are substituted. After a configuration is created, the running component receives the new
-object and takes it when its `_created` is later than that of the value it holds.
+are substituted. What is served is what was stored, whole: a `default` written into the schema
+fills nothing, so a value every component is to have is declared in `defaults`. After a configuration is created, the running component receives the new
+object and takes it when its `CREATED` is later than that of the value it holds.
 
 ### Local override
 
 When the variable `TOA_CONFIGURATION_<NAMESPACE>_<NAME>` is set, the component's
-configuration is the variable's value with the manifest `defaults` and the schema applied,
-and the values service is not used.
+configuration is the variable's value with the manifest `defaults` filled in and the schema
+applied, and the values service is not used.
 
 ```shell
 $ TOA_CONFIGURATION_DUMMIES_DUMMY='{"foo":"local"}' toa run components/dummy

package/schemas/annotation.cos.yaml

@@ -7,7 +7,7 @@
 properties:
   resources:
     # `null` deploys the service without any, which every deployment has to state one way
-    # or the other — see `migrations/263.md`.
+    # or the other — see `migrations/262.md`.
     type: object
     nullable: true
     properties:

package/source/Aspect.test.ts

@@ -9,7 +9,10 @@ import type { Client, Listener } from './Client.js'
 import type { Manifest } from './manifest.js'
 
 class Fake extends Connector {
-  public readonly fetch = mock.fn(async () => ({ configuration: { foo: 'served' }, created: 5 }))
+  public readonly fetch = mock.fn(async () => ({
+    configuration: { foo: 'served' },
+    created: 5
+  }))
   public readonly subscribe = mock.fn()
   public readonly unsubscribe = mock.fn()
 }
@@ -19,9 +22,10 @@ const manifest: Manifest = {
     type: 'object',
     properties: {
       foo: { type: 'string' },
-      bar: { type: 'object', properties: { baz: { type: 'string' } }, default: { baz: 'quux' } }
+      bar: { type: 'object', properties: { baz: { type: 'string' } } }
     }
-  }
+  },
+  defaults: { bar: { baz: 'quux' } }
 }
 
 let locator: Locator
@@ -59,13 +63,25 @@ it('should fetch from the client and follow it', async () => {
   assert.deepStrictEqual(client.connected, true)
   assert.strictEqual(client.fetch.mock.callCount(), 1)
 
-  const [component, epoch] = client.fetch.mock.calls[0].arguments as unknown as [string, string]
+  const [component, epoch] = client.fetch.mock.calls[0].arguments as unknown as [
+    string,
+    string
+  ]
 
   assert.deepStrictEqual(component, locator.id)
   assert.match(epoch, /^[a-f0-9]{64}$/)
-  assert.deepStrictEqual(aspect.invoke(), { foo: 'served', bar: { baz: 'quux' } })
-
-  assert.ok(client.subscribe.mock.calls.some((call: any) => call.arguments.length === 3 && isDeepStrictEqual(call.arguments[0], component) && isDeepStrictEqual(call.arguments[1], epoch) && typeof call.arguments[2] === 'function'))
+  // what the service serves is what was stored, and the manifest defaults are not applied to it
+  assert.deepStrictEqual(aspect.invoke(), { foo: 'served' })
+
+  assert.ok(
+    client.subscribe.mock.calls.some(
+      (call: any) =>
+        call.arguments.length === 3 &&
+        isDeepStrictEqual(call.arguments[0], component) &&
+        isDeepStrictEqual(call.arguments[1], epoch) &&
+        typeof call.arguments[2] === 'function'
+    )
+  )
 
   const listener = client.subscribe.mock.calls[0].arguments[2] as Listener
 
@@ -91,5 +107,13 @@ it('should fetch from the client and follow it', async () => {
 
   await aspect.disconnect()
 
-  assert.ok(client.unsubscribe.mock.calls.some((call: any) => call.arguments.length === 3 && isDeepStrictEqual(call.arguments[0], component) && isDeepStrictEqual(call.arguments[1], epoch) && isDeepStrictEqual(call.arguments[2], listener)))
+  assert.ok(
+    client.unsubscribe.mock.calls.some(
+      (call: any) =>
+        call.arguments.length === 3 &&
+        isDeepStrictEqual(call.arguments[0], component) &&
+        isDeepStrictEqual(call.arguments[1], epoch) &&
+        isDeepStrictEqual(call.arguments[2], listener)
+    )
+  )
 })

package/source/Aspect.ts

@@ -1,5 +1,6 @@
 import { console } from 'openspan'
-import { Connector, type Locator, type extensions } from '@toa.io/core'
+import { Connector, type Locator } from '@toa.io/core'
+import type { extensions } from '@toa.io/core/types'
 import { fit, local, type Node } from './configuration.js'
 import { epoch } from './epoch.js'
 import type { Client, Value } from './Client.js'
@@ -19,7 +20,7 @@ export class Aspect extends Connector implements extensions.Aspect {
    * Without a client the value is local: the variable, the defaults and the schema.
    * With one, the value is what the service holds, and it follows the service.
    */
-  public constructor (locator: Locator, manifest: Manifest, client: Client | null) {
+  public constructor(locator: Locator, manifest: Manifest, client: Client | null) {
     super()
 
     this.locator = locator
@@ -27,56 +28,64 @@ export class Aspect extends Connector implements extensions.Aspect {
     this.client = client
     this.epoch = epoch(manifest.schema)
 
-    if (client !== null)
-      this.depends(client)
+    if (client !== null) this.depends(client)
   }
 
-  public invoke (path?: string[]): any {
+  public invoke(path?: string[]): any {
     let cursor: any = this.value
 
-    if (path !== undefined)
-      for (const segment of path)
-        cursor = cursor[segment]
+    if (path !== undefined) for (const segment of path) cursor = cursor[segment]
 
     return cursor
   }
 
-  protected override async open (): Promise<void> {
+  protected override async open(): Promise<void> {
     if (this.client === null) {
       this.value = local(this.locator, this.manifest)
 
       return
     }
 
-    const { configuration, created } = await this.client.fetch(this.locator.id, this.epoch)
+    const { configuration, created } = await this.client.fetch(
+      this.locator.id,
+      this.epoch
+    )
 
     this.value = fit(configuration, this.manifest)
     this.created = created
     this.client.subscribe(this.locator.id, this.epoch, this.listener)
 
-    console.info('Configuration resolved',
-      { component: this.locator.id, epoch: this.epoch, created })
+    console.info('Configuration resolved', {
+      component: this.locator.id,
+      epoch: this.epoch,
+      created
+    })
   }
 
-  protected override async close (): Promise<void> {
+  protected override async close(): Promise<void> {
     this.client?.unsubscribe(this.locator.id, this.epoch, this.listener)
   }
 
   private readonly listener = ({ configuration, created }: Value): void => {
     // deliveries may repeat or cross: only what is newer than the held value replaces it
-    if (created <= this.created)
-      return
+    if (created <= this.created) return
 
     try {
       this.value = fit(configuration, this.manifest)
       this.created = created
 
-      console.info('Configuration updated',
-        { component: this.locator.id, epoch: this.epoch, created })
+      console.info('Configuration updated', {
+        component: this.locator.id,
+        epoch: this.epoch,
+        created
+      })
     } catch (error) {
       // the service validated it against the schema of its epoch, so the two schemas differ
-      console.error('Configuration value does not match the schema',
-        { component: this.locator.id, epoch: this.epoch, error })
+      console.error('Configuration value does not match the schema', {
+        component: this.locator.id,
+        epoch: this.epoch,
+        error
+      })
     }
   }
 }

package/source/Client.test.ts

@@ -2,19 +2,25 @@ import { it, beforeEach, afterEach, mock } from 'node:test'
 import assert from 'node:assert/strict'
 import { isDeepStrictEqual } from 'node:util'
 
-import { Connector, type Locator, type Message, type Receiver } from '@toa.io/core'
+import { Connector, type Locator, type Receiver } from '@toa.io/core'
+import type { Message } from '@toa.io/core/types'
 import { timeout } from '@toa.io/generic'
 import { Client, type Fetched } from './Client.js'
 import { EVENT } from './const.js'
 import type { Host } from './Factory.js'
 
 class Remote extends Connector {
-  public readonly invoke = mock.fn(async (_endpoint: string, request: { input: Array<{ component: string, epoch: string }> }) =>
-    request.input.map((pair): Fetched => ({
-      ...pair,
-      configuration: this.values[pair.component] ?? null,
-      created: this.values[pair.component] === undefined ? 0 : 7
-    })))
+  public readonly invoke = mock.fn(
+    async (
+      _endpoint: string,
+      request: { input: Array<{ component: string; epoch: string }> }
+    ) =>
+      request.input.map((pair): Fetched => ({
+        ...pair,
+        configuration: this.values[pair.component] ?? null,
+        created: this.values[pair.component] === undefined ? 0 : 7
+      }))
+  )
 
   public values: Record<string, object | null> = {}
 }
@@ -55,13 +61,19 @@ it('should send the requests of one tick as one call', async () => {
 
   await client.connect()
 
-  const [one, two] = await Promise.all([client.fetch('a.one', 'e1'), client.fetch('a.two', 'e2')])
+  const [one, two] = await Promise.all([
+    client.fetch('a.one', 'e1'),
+    client.fetch('a.two', 'e2')
+  ])
 
   assert.deepStrictEqual(one, { configuration: { foo: 1 }, created: 7 })
   assert.deepStrictEqual(two, { configuration: { foo: 2 }, created: 7 })
   assert.strictEqual(remote.invoke.mock.callCount(), 1)
   assert.deepStrictEqual(remote.invoke.mock.calls[0].arguments[1], {
-    input: [{ component: 'a.one', epoch: 'e1' }, { component: 'a.two', epoch: 'e2' }]
+    input: [
+      { component: 'a.one', epoch: 'e1' },
+      { component: 'a.two', epoch: 'e2' }
+    ]
   })
 })
 
@@ -71,8 +83,7 @@ it('should keep asking until served', async () => {
   const fetching = client.fetch('a.one', 'e1')
   const deadline = Date.now() + 1000
 
-  while (remote.invoke.mock.calls.length < 2 && Date.now() < deadline)
-    await timeout(5)
+  while (remote.invoke.mock.calls.length < 2 && Date.now() < deadline) await timeout(5)
 
   assert.ok(remote.invoke.mock.calls.length >= 2)
 
@@ -91,17 +102,23 @@ it('should hand a created object to its subscribers', async () => {
   client.subscribe('a.one', 'e0', other)
 
   await receiver!.receive({
-    payload: { component: 'a.one', epoch: 'e1', configuration: { foo: 2 }, _created: 12 }
+    payload: { component: 'a.one', epoch: 'e1', configuration: { foo: 2 }, CREATED: 12 }
   } satisfies Message)
 
-  assert.ok(listener.mock.calls.some((call: any) => call.arguments.length === 1 && isDeepStrictEqual(call.arguments[0], { configuration: { foo: 2 }, created: 12 })))
+  assert.ok(
+    listener.mock.calls.some(
+      (call: any) =>
+        call.arguments.length === 1 &&
+        isDeepStrictEqual(call.arguments[0], { configuration: { foo: 2 }, created: 12 })
+    )
+  )
   assert.strictEqual(other.mock.callCount(), 0)
   assert.strictEqual(remote.invoke.mock.callCount(), 0)
 
   client.unsubscribe('a.one', 'e1', listener)
 
   await receiver!.receive({
-    payload: { component: 'a.one', epoch: 'e1', configuration: { foo: 3 }, _created: 13 }
+    payload: { component: 'a.one', epoch: 'e1', configuration: { foo: 3 }, CREATED: 13 }
   } satisfies Message)
 
   assert.strictEqual(listener.mock.callCount(), 1)

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
   }