@toa.io/extensions.configuration 1.0.0-alpha.29 → 1.0.0-alpha.292

package/source/configuration.test.ts

@@ -1,85 +1,147 @@
-import { encode } from '@toa.io/generic'
+import { describe, it, beforeEach, afterEach } from 'node:test'
+import assert from 'node:assert/strict'
+
 import { Locator } from '@toa.io/core'
 import { generate } from 'randomstring'
-import { get } from './configuration'
-import { type Manifest } from './manifest'
+import { fit, local, overridden } from './configuration.js'
+import { Secret } from './Secret.js'
+import { type Manifest } from '@toa.io/definitions/extensions.configuration'
 
 let locator: Locator
 let manifest: Manifest
 
 beforeEach(() => {
   locator = new Locator(generate(), generate())
-  manifest = { schema: { foo: 'string' } }
+  manifest = {
+    schema: {
+      type: 'object',
+      properties: { foo: { type: 'string' } }
+    }
+  }
 })
 
 afterEach(() => {
-  for (const name of used)
-    delete process.env[name]
+  for (const name of used) delete process.env[name]
 
   used = []
 })
 
-it('should read value', async () => {
-  manifest.schema = { foo: 'string' }
+describe('overridden', () => {
+  it('should be false without the variable', async () => {
+    assert.deepStrictEqual(overridden(locator), false)
+  })
 
-  const value: object = { foo: generate() }
+  it('should be true with the variable', async () => {
+    set({})
 
-  set(value)
+    assert.deepStrictEqual(overridden(locator), true)
+  })
+})
 
-  const result = get(locator, manifest)
+describe('local', () => {
+  it('should read value', async () => {
+    const value: object = { foo: generate() }
 
-  expect(result).toStrictEqual(value)
-})
+    set(value)
 
-it('should return empty object if no value set', async () => {
-  expect(get(locator, manifest)).toStrictEqual({})
-})
+    assert.deepStrictEqual(local(locator, manifest), value)
+  })
 
-it('should substitute secrets', async () => {
-  const value: object = { foo: '$BAR' }
+  it('should return empty object if no value set', async () => {
+    assert.deepStrictEqual(local(locator, manifest), {})
+  })
 
-  set(value)
-  set('bar', '_BAR')
+  it('should substitute secrets', async () => {
+    set({ foo: '$BAR' })
+    set('bar', '_BAR')
 
-  const result = get(locator, manifest)
+    const { foo } = local(locator, manifest)
 
-  expect(result).toStrictEqual({ foo: 'bar' })
-})
+    assert.ok(foo instanceof Secret)
+    assert.deepStrictEqual((foo as Secret).unwrap(), 'bar')
+    assert.deepStrictEqual(String(foo), '<REDACTED>')
+  })
 
-it('should use defaults', async () => {
-  manifest.schema = { foo: 'string', bar: ['number'], 'baz?': 'string' }
-  manifest.defaults = { foo: 'bar', bar: [1] }
+  it('should substitute secrets in defaults', async () => {
+    manifest.defaults = { foo: '$BAR' }
 
-  const values = { bar: [2], baz: 'foo' }
+    set('bar', '_BAR')
 
-  set(values)
+    assert.deepStrictEqual((local(locator, manifest).foo as Secret).unwrap(), 'bar')
+  })
+
+  it('should use defaults', async () => {
+    manifest.schema = {
+      type: 'object',
+      properties: {
+        foo: { type: 'string' },
+        bar: { type: 'array', items: { type: 'number' } },
+        baz: { type: 'string' }
+      },
+      required: ['foo', 'bar']
+    }
+    manifest.defaults = { foo: 'bar', bar: [1] }
+
+    set({ bar: [2], baz: 'foo' })
+
+    assert.deepStrictEqual(local(locator, manifest), { foo: 'bar', bar: [2], baz: 'foo' })
+  })
+
+  it('should validate', async () => {
+    manifest.schema = {
+      type: 'object',
+      properties: {
+        foo: { type: 'string' },
+        bar: { type: 'number' }
+      }
+    }
+
+    set({ bar: 5 })
 
-  const result = get(locator, manifest)
+    assert.deepStrictEqual(local(locator, manifest), { bar: 5 })
 
-  expect(result).toStrictEqual({
-    foo: 'bar',
-    bar: [2],
-    baz: 'foo'
+    set({ bar: 'five' })
+
+    assert.throws(
+      () => local(locator, manifest),
+      (error: Error) => /must be number/.test(error.message)
+    )
   })
 })
 
-it('should validate', async () => {
-  manifest.schema = { foo: 'hello', bar: 'number' }
+describe('fit', () => {
+  it('should substitute secrets and apply the schema', async () => {
+    manifest.schema = {
+      type: 'object',
+      properties: {
+        foo: { type: 'string' },
+        bar: { type: 'number' }
+      }
+    }
+
+    set('secret', '_FOO')
 
-  const values = { bar: 5 }
+    const raw = { foo: '$FOO', bar: 1 }
+    const values = fit(raw, manifest)
 
-  set(values)
+    assert.deepStrictEqual((values.foo as Secret).unwrap(), 'secret')
+    assert.deepStrictEqual(values.bar, 1)
+    assert.deepStrictEqual(raw, { foo: '$FOO', bar: 1 }) // untouched
+  })
 
-  const result = get(locator, manifest)
+  it('should not apply the manifest defaults', async () => {
+    manifest.defaults = { foo: 'hello' }
+
+    assert.deepStrictEqual(fit({}, manifest), {})
+  })
 
-  expect(result).toStrictEqual({
-    foo: 'hello',
-    bar: 5
+  it('should throw on a value not fitting the schema', async () => {
+    assert.throws(() => fit({ foo: { nested: true } }, manifest))
   })
 })
 
-function set (value: object | string, key = locator.uppercase): void {
-  const string = typeof value === 'string' ? value : encode(value)
+function set(value: object | string, key = locator.uppercase): void {
+  const string = typeof value === 'string' ? value : JSON.stringify(value)
   const name = 'TOA_CONFIGURATION_' + key
 
   process.env[name] = string

package/source/configuration.ts

@@ -1,39 +1,54 @@
 import { type Locator } from '@toa.io/core'
-import { decode, add } from '@toa.io/generic'
+import { add, environment } from '@toa.io/generic'
 import * as schemas from '@toa.io/schemas'
-import { PREFIX, SECRET_RX } from './deployment'
-import { type Manifest } from './manifest'
+import { PREFIX, SECRET_RX } from '@toa.io/definitions/extensions.configuration'
+import { Secret } from './Secret.js'
 import type { Schema } from '@toa.io/schemas'
+import type { Manifest } from '@toa.io/definitions/extensions.configuration'
 
-export function get (locator: Locator, manifest: Manifest): Node {
-  const values = getConfiguration(locator.uppercase)
+/** The variable is set, so the values service is not consulted. */
+export function overridden(locator: Locator): boolean {
+  return environment.get(PREFIX + locator.uppercase) !== undefined
+}
+
+/** The variable, the manifest defaults, then the schema. */
+export function local(locator: Locator, manifest: Manifest): Node {
+  const values = read(locator.uppercase)
+
+  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 {
+  // 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
+
+  // the schema sees the references, which are the strings it declares
+  validate(values, manifest)
   substituteSecrets(values)
 
-  if (manifest.defaults !== undefined)
-    add(values, manifest.defaults)
+  return values
+}
 
+function validate(values: Node, manifest: Manifest): void {
   const schema: Schema<any> = schemas.schema(manifest.schema)
 
   schema.validate(values)
-
-  return values
 }
 
-function getConfiguration (suffix: string): Node {
+function read(suffix: string): Node {
   const variable = PREFIX + suffix
-  const string = process.env[variable]
+  const string = environment.get(variable)
 
-  if (string === undefined)
-    return {}
-  else
-    return decode(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
 
@@ -43,13 +58,13 @@ function substituteSecrets (configuration: Node): void {
 
     const name = match.groups?.variable
 
-    configuration[key] = getSecret(name!)
+    configuration[key] = new Secret(getSecret(name!))
   }
 }
 
-function getSecret (name: string): string {
+function getSecret(name: string): string {
   const variable = PREFIX + '_' + name
-  const value = process.env[variable]
+  const value = environment.get(variable)
 
   if (value === undefined) throw new Error(`${variable} is not set.`)
 

package/source/epoch.test.ts

@@ -0,0 +1,35 @@
+import { it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { epoch } from '@toa.io/definitions/extensions.configuration'
+
+it('should be a sha256 hex', () => {
+  assert.match(epoch({ type: 'object' }), /^[a-f0-9]{64}$/)
+})
+
+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'
+  }
+
+  assert.deepStrictEqual(epoch(a), epoch(b))
+})
+
+it('should depend on values', () => {
+  const a = { type: 'object', properties: { foo: { type: 'string' } } }
+  const b = { type: 'object', properties: { foo: { type: 'number' } } }
+
+  assert.notDeepStrictEqual(epoch(a), epoch(b))
+})
+
+it('should keep array order', () => {
+  const a = { enum: [1, 2] }
+  const b = { enum: [2, 1] }
+
+  assert.notDeepStrictEqual(epoch(a), epoch(b))
+})

package/source/index.ts

@@ -1,3 +1,5 @@
-export { manifest } from './manifest'
-export { deployment } from './deployment'
-export { Factory } from './Factory'
+export { components } from './Composition.js'
+export { Factory } from './Factory.js'
+
+// what a value declared `format: secret` is on a component's context
+export { Secret } from './Secret.js'

package/transpiled/Aspect.d.ts

@@ -1,7 +1,22 @@
-import { Connector, type extensions } from '@toa.io/core';
+import { Connector, type Locator } from '@toa.io/core';
+import type { extensions } from '@toa.io/core/types';
+import type { Client } from './Client.js';
+import type { Manifest } from '@toa.io/definitions/extensions.configuration';
 export declare class Aspect extends Connector implements extensions.Aspect {
     readonly name = "configuration";
-    private readonly value;
-    constructor(value: object);
-    invoke(path: string[]): any;
+    private readonly locator;
+    private readonly manifest;
+    private readonly client;
+    private readonly epoch;
+    private value;
+    private created;
+    /**
+     * 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.
+     */
+    constructor(locator: Locator, manifest: Manifest, client: Client | null);
+    invoke(path?: string[]): any;
+    protected open(): Promise<void>;
+    protected close(): Promise<void>;
+    private readonly listener;
 }

package/transpiled/Aspect.js

@@ -1,13 +1,27 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Aspect = void 0;
-const core_1 = require("@toa.io/core");
-class Aspect extends core_1.Connector {
+import { console } from 'openspan';
+import { Connector } from '@toa.io/core';
+import { fit, local } from './configuration.js';
+import { epoch } from '@toa.io/definitions/extensions.configuration';
+export class Aspect extends Connector {
     name = 'configuration';
-    value;
-    constructor(value) {
+    locator;
+    manifest;
+    client;
+    epoch;
+    value = {};
+    created = 0;
+    /**
+     * 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.
+     */
+    constructor(locator, manifest, client) {
         super();
-        this.value = value;
+        this.locator = locator;
+        this.manifest = manifest;
+        this.client = client;
+        this.epoch = epoch(manifest.schema);
+        if (client !== null)
+            this.depends(client);
     }
     invoke(path) {
         let cursor = this.value;
@@ -16,6 +30,45 @@ class Aspect extends core_1.Connector {
                 cursor = cursor[segment];
         return cursor;
     }
+    async open() {
+        if (this.client === null) {
+            this.value = local(this.locator, this.manifest);
+            return;
+        }
+        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
+        });
+    }
+    async close() {
+        this.client?.unsubscribe(this.locator.id, this.epoch, this.listener);
+    }
+    listener = ({ configuration, created }) => {
+        // deliveries may repeat or cross: only what is newer than the held value replaces it
+        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
+            });
+        }
+        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
+            });
+        }
+    };
 }
-exports.Aspect = Aspect;
 //# sourceMappingURL=Aspect.js.map

package/transpiled/Aspect.js.map

@@ -1 +1 @@
-{"version":3,"file":"Aspect.js","sourceRoot":"","sources":["../source/Aspect.ts"],"names":[],"mappings":";;;AAAA,uCAAyD;AAEzD,MAAa,MAAO,SAAQ,gBAAS;IACnB,IAAI,GAAG,eAAe,CAAA;IAErB,KAAK,CAAQ;IAE9B,YAAoB,KAAa;QAC/B,KAAK,EAAE,CAAA;QAEP,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;IACpB,CAAC;IAEM,MAAM,CAAE,IAAc;QAC3B,IAAI,MAAM,GAAQ,IAAI,CAAC,KAAK,CAAA;QAE5B,IAAI,IAAI,KAAK,SAAS;YACpB,KAAK,MAAM,OAAO,IAAI,IAAI;gBACxB,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,CAAA;QAE5B,OAAO,MAAM,CAAA;IACf,CAAC;CACF;AApBD,wBAoBC"}
+{"version":3,"file":"Aspect.js","sourceRoot":"","sources":["../source/Aspect.ts"],"names":[],"mappings":"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"}

package/transpiled/Client.d.ts

@@ -0,0 +1,61 @@
+import { Connector } from '@toa.io/core';
+import type { Host } from './Factory.js';
+/**
+ * One per process: one remote to the values service and one subscription to its events,
+ * shared by every Aspect. What the Aspects ask for is collected and sent as one call;
+ * what the service creates afterwards is handed to whoever subscribed.
+ */
+export declare class Client extends Connector {
+    /** Disconnected once, a connector keeps what it depended on, so a gone client is not reused. */
+    disposed: boolean;
+    private readonly host;
+    private readonly options;
+    private readonly pending;
+    private readonly listeners;
+    private remote;
+    private timer;
+    private flushing;
+    private fresh;
+    private round;
+    constructor(host: Host, options?: Partial<Options>);
+    /** The configuration of a component for an epoch, once the service has one. */
+    fetch(component: string, epoch: string): Promise<Value>;
+    subscribe(component: string, epoch: string, listener: Listener): void;
+    unsubscribe(component: string, epoch: string, listener: Listener): void;
+    protected open(): Promise<void>;
+    protected close(): Promise<void>;
+    protected dispose(): Promise<void>;
+    private schedule;
+    private flush;
+    /** Those the service has served are told; the rest stay for the next round. */
+    private settle;
+    private report;
+    private backoff;
+    /** A created object goes to the subscribers of its component and epoch, as it is. */
+    private deliver;
+}
+export interface Options {
+    base: number;
+    max: number;
+    /** Every n-th round of waiting is reported. */
+    warn: number;
+}
+/** A configuration and when it was created; `0` for the deployed defaults. */
+export interface Value {
+    configuration: object;
+    created: number;
+}
+export interface Fetched {
+    component: string;
+    epoch: string;
+    configuration: object | null;
+    created: number;
+}
+/** The `configuration.values.created` payload: the object as stored. */
+export interface Created {
+    component: string;
+    epoch: string;
+    configuration: object;
+    CREATED: number;
+}
+export type Listener = (value: Value) => void;