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

package/features/steps/UI.ts

@@ -4,10 +4,15 @@ import { resolve } from 'node:path'
 import tsflow from 'cucumber-tsflow'
 
 import { UI } from '../../source/UI.js'
-import { UI_PORT } from '../../source/const.js'
 
 const { after, binding, given, then, when } = tsflow
 
+/**
+ * Not `UI_PORT`, which a deployment serves the page on: an application built on Toa is served
+ * on this machine too, and its own explorer holds that one. See CONTRIBUTING.md.
+ */
+const PORT = 31003
+
 /**
  * The scenarios are about the server, not about the page: it is pointed at a fixture
  * directory, so that running them never needs a UI build.
@@ -18,40 +23,42 @@ export class Site {
   private response: Response | null = null
 
   @given('the UI is published')
-  public async publish (): Promise<void> {
-    this.server = new UI(UI_PORT, resolve(import.meta.dirname, '..', 'site'))
+  public async publish(): Promise<void> {
+    this.server = new UI(PORT, resolve(import.meta.dirname, '..', 'site'))
 
     await this.server.connect()
   }
 
   @when('{string} is requested')
-  public async request (path: string): Promise<void> {
+  public async request(path: string): Promise<void> {
     this.response = await get(path)
   }
 
   @then('the status is {int}')
-  public statusIs (status: number): void {
+  public statusIs(status: number): void {
     assert.equal(this.response?.status, status)
   }
 
   @then('the body contains {string}')
-  public bodyContains (text: string): void {
-    assert.ok(this.response?.body.includes(text),
-      `Expected the body to contain '${text}', got '${this.response?.body}'`)
+  public bodyContains(text: string): void {
+    assert.ok(
+      this.response?.body.includes(text),
+      `Expected the body to contain '${text}', got '${this.response?.body}'`
+    )
   }
 
   @then('the body is empty')
-  public bodyIsEmpty (): void {
+  public bodyIsEmpty(): void {
     assert.equal(this.response?.body, '')
   }
 
   @then('the {string} header is {string}')
-  public headerIs (name: string, value: string): void {
+  public headerIs(name: string, value: string): void {
     assert.equal(this.response?.headers[name], value)
   }
 
   @after()
-  public async shutdown (): Promise<void> {
+  public async shutdown(): Promise<void> {
     await this.server?.disconnect()
 
     this.server = null
@@ -63,10 +70,10 @@ export class Site {
  * Raw `http`, not `fetch`: the URL parser normalizes `%2e%2e` away, and one of the
  * scenarios is about exactly that segment reaching the server.
  */
-async function get (path: string): Promise<Response> {
+async function get(path: string): Promise<Response> {
   return await new Promise((resolve, reject) => {
     // `agent: false` — a keep-alive socket outlives the scenario that opened it
-    const request = http.get({ port: UI_PORT, path, agent: false }, (response) => {
+    const request = http.get({ port: PORT, path, agent: false }, (response) => {
       let body = ''
 
       response.setEncoding('utf8')

package/notes/consistency.md

@@ -33,15 +33,15 @@ single moment when configuration can be safely changed. Thus, it must be a proce
 
 1. Configuration updates are always backward compatible.
 2. Configuration updates are always being delivered before algorithm updates.
-    1. Including federated deployment, that is: first deliver configuration to all facilities (data
-       centers, zones,
-       whatever), then deliver algorithm updates.
+   1. Including federated deployment, that is: first deliver configuration to all facilities (data
+      centers, zones,
+      whatever), then deliver algorithm updates.
 3. Configuration storage and access solution must provide the transactional updates, that is if any
    arbitrary
    participant observed a certain configuration version, then any other participant is guaranteed to
    be able to
    subsequently observe that version.
-    1. Including federated deployment[^1].
+   1. Including federated deployment[^1].
 
 ## Solution
 
@@ -62,8 +62,9 @@ However, an attempt
 will be made to implement this solution with a certain
 constraints [#147](https://github.com/toa-io/toa/issues/147).
 
-[^1]: Since it looks like there is no reasonable way to provide this kind of guarantee without
-significant performance
-and/or availability impact, it may be implemented as a mechanism with read retries and with a
-timeout considered as
-“enough for the most of fail-over scenarios”.
+[^1]:
+    Since it looks like there is no reasonable way to provide this kind of guarantee without
+    significant performance
+    and/or availability impact, it may be implemented as a mechanism with read retries and with a
+    timeout considered as
+    “enough for the most of fail-over scenarios”.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/extensions.configuration",
-  "version": "1.0.0-alpha.284",
+  "version": "1.0.0-alpha.287",
   "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": "5c7944a70c16065ab6372072385cc1f02f5db77c",
   "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.287",
+    "@toa.io/generic": "1.0.0-alpha.286",
+    "@toa.io/schemas": "1.0.0-alpha.287",
+    "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)