@toa.io/extensions.configuration 1.0.0-alpha.272 → 1.0.0-alpha.274

package/CHANGELOG.md

@@ -3,6 +3,216 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [1.0.0-alpha.274](https://github.com/toa-io/toa/compare/v1.0.0-alpha.273...v1.0.0-alpha.274) (2026-09-02)
+
+
+* Configuration is served by a component, followed live, and kept per epoch (#1017) ([b05997d](https://github.com/toa-io/toa/commit/b05997d3adb784f238a222cb46878b23859339a2)), closes [#1017](https://github.com/toa-io/toa/issues/1017)
+
+
+### Features
+
+* **configuration:** drop the label from the epoch ([4baaff5](https://github.com/toa-io/toa/commit/4baaff5b22d00719142a65d56b50a1b100b29fbd))
+
+
+### BREAKING CHANGES
+
+* a secret configuration value is an object, not a string;
+read it with `unwrap()`.
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
+
+* test(configuration): wait for the second round rather than assume it
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
+
+* refactor(configuration)!: read a secret with its own unwrap
+
+Component code depends on no Toa package, so a secret is read as
+`context.configuration.apiKey.unwrap()` and the helper in `@toa.io/generic`
+goes. A value a component reads as a secret is therefore given as a reference:
+`identity.basic` no longer defaults `pepper` to `''`, the development context
+and the feature harness give the token keys, the federation client secret and
+the signing key as references, and the harness has a step for the secrets a
+scenario refers to. CONTRIBUTING states the rule.
+* `identity.basic` `pepper` has no default; a value read as a
+secret must be given as a `$NAME` reference.
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
+
+* feat(configuration): list the configurations
+
+`configuration.values.list` returns every component's configuration for its
+deployed epoch, by component name, and `GET /configuration/values/` serves it
+behind `system:configuration:get`.
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
+
+* fix(exposition): write a value in YAML the way its toJSON says
+
+A redacted secret in a reply was dumped as an empty object; it is written as
+`<REDACTED>`, as JSON and msgpack already write it.
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
+
+* test(configuration): a secret is an object, and stays redacted in a reply
+
+A component with `{ a: 1, b: $SECRET_B }` returns its configuration as
+`{ a: 1, b: '<REDACTED>' }` and the secret itself through `unwrap()`. The reply
+step also accepts a reply as a caller across a process boundary receives it,
+since a call within the process hands the object over as it is.
+
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
+
+* chore(schemas): bump the dependencies
+
+ajv 8.18.0 to 8.20.0, ajv-formats 2.1.1 to 3.0.1, better-ajv-errors 1.2.0
+to 2.0.3, fast-glob 3.2.12 to 3.3.3 and js-yaml 4.3.1 to 5.4.1 — the version
+exposition already uses. The three majors keep the CommonJS entry points this
+library calls: ajv-formats as a function, better-ajv-errors as .default, and
+js-yaml's load.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+
+* feat(configuration)!: serve the schema with the value
+
+GET /configuration/values/:component/ answers { configuration, schema, epoch }
+where it answered with the configuration alone, and list carries the schema of
+every component. Nothing reads a configuration without needing to know what it
+is checked against, and the schema was only ever on the values service.
+
+An epoch the deployment does not know has no schema; the value stored for it
+is still returned.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+
+* feat(configuration): publish a configuration UI
+
+The values service serves a page at /.configuration on port 8003, out of the
+directory ui builds: the configured components, a screen per component showing
+what it holds now, and a dialog creating the next one. Reading needs
+system:configuration:get and creating needs system:configuration:create.
+
+A configuration is immutable, so the dialog opens on the current value and what
+is left out of it is left out of the component. The editor takes YAML, the
+schema is applied before anything is sent, and a secret is a reference the page
+never shows.
+
+The page is always published: the annotation is the per-component values map
+and has nowhere to carry a switch.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+
+* feat(introspection): link a component to its configuration
+
+A card carrying @toa.io/extensions.configuration reads that extension as a link
+to the configuration UI rather than as a name, and configuration joins the
+namespaces the runtime provides, so its components band under System.
+
+Deployed, both pages sit behind the same ingress and the path alone is right;
+locally each console has its own port.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+
+* feat(introspection): scroll the map, zoom with a modifier
+
+The map was grabbed to move and zoomed with a bare wheel, which is neither what
+a page does nor what the wheel does anywhere else. A plain scroll now pans on
+both axes and the wheel scales only with the modifier held — a trackpad pinch
+arrives as one of those on every platform.
+
+A card's own scrollable box keeps its wheel, in both paths.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+
+* refactor(introspection): centre the filter in the header
+
+The sides take equal space, which is what leaves the filter between them.
+Neither side may shrink under what it holds, or the tabs run out from under
+their side and across the filter, and the filter across the sign-out button;
+the title gives way instead.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+
+* fix(configuration): connect the UI to the values service
+
+The page was declared as a dependency from inside `open`, and a connector connects
+what it depends on before `open` runs — so the server was constructed and never
+listened. Nothing caught it: the UI feature builds the server itself.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+
+* feat(configuration)!: reserve resources in the annotation
+
+The values service deploys like any other and must state what it may take, but the
+annotation is a map of component ids and had nowhere to put it — so `toa env` failed
+for every context using configuration unless it declared a context-wide `resources`.
+
+`resources` is now the service's own, read the way `introspection` and `realtime` read
+theirs. A component actually named `resources` is written `default.resources`, which is
+what its id is anyway.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+
+* feat(configuration): follow the system colour scheme
+
+The dark tokens were behind a `.dark` class nothing sets, and the `dark:` variant was
+pointed at that class too — so a component's own dark styling never applied either.
+Both now key off `prefers-color-scheme`, and `color-scheme` hands the native chrome
+the same answer.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+
+* feat(introspection): follow the system colour scheme
+
+The dark tokens were behind a `.dark` class nothing sets, and the `dark:` variant was
+pointed at that class too — so a component's own dark styling never applied either.
+Both now key off `prefers-color-scheme`, and `color-scheme` hands the native chrome
+the same answer.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+
+* feat(configuration): present a change as an edit of what is there
+
+A configuration is immutable and creating one replaces the whole of it, but the dialog
+opens on the current value and the page never shows an older one — so what the reader
+does is edit. The words follow: Edit rather than New, Update rather than Create, and
+the paragraph explaining the model goes, along with the field's label, which the title
+above it already said.
+
+The editor also stayed as wide as its longest line — `field-sizing: content` sizes to
+content, and no `max-width` clamps that — so a long value painted outside the dialog.
+It is fixed now, the dialog takes the width the screen has rather than a fixed step,
+and the band held for errors no longer leaves a gap when there are none.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+
+* feat(configuration): mark a component that keeps a secret
+
+A key after the name on the row, wherever the configuration holds a reference, however
+deep. The predicate reads the same lines the value screen renders, so the two cannot
+disagree about what counts as a secret.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+
+* feat(configuration): lead back to the list from the title
+
+Every address ends in a slash, so the way up is the address itself on the list and one
+level above it on a component's screen — which holds wherever the page is mounted.
+
+Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
+
+
+
+
+
+# [1.0.0-alpha.273](https://github.com/toa-io/toa/compare/v1.0.0-alpha.272...v1.0.0-alpha.273) (2026-09-02)
+
+**Note:** Version bump only for package @toa.io/extensions.configuration
+
+
+
+
+
 # [1.0.0-alpha.272](https://github.com/toa-io/toa/compare/v1.0.0-alpha.271...v1.0.0-alpha.272) (2026-09-01)
 
 **Note:** Version bump only for package @toa.io/extensions.configuration

package/components/configuration.values/manifest.toa.yaml

@@ -0,0 +1,158 @@
+namespace: configuration
+name: values
+
+# One document per configuration created. Documents are immutable: a change is a new
+# document, and the latest one for a component and an epoch is the last created.
+# What every component's epoch, schema and defaults are, the service is told on
+# deployment (`TOA_CONFIGURATION_VALUES`). A created object is published as the
+# prototype's `created` event.
+
+entity:
+  schema:
+    type: object
+    properties:
+      component:
+        type: string
+      epoch:
+        type: string
+      configuration:
+        type: object
+      originator:
+        type: string
+    required:
+      - component
+      - epoch
+      - configuration
+      - originator
+  index:
+    lookup:
+      component: asc
+      epoch: asc
+      _created: desc
+
+operations:
+  # the latest configuration of a component: created, else deployed defaults, else none
+  get:
+    query: false
+    input:
+      type: object
+      properties:
+        component:
+          type: string
+        epoch:
+          type: string
+      required:
+        - component
+    # the value and the schema it is checked against, so a caller can show and check it
+    output:
+      type: object
+      nullable: true
+      properties:
+        configuration:
+          type: object
+        schema:
+          type: object
+        epoch:
+          type: string
+      required:
+        - configuration
+        - epoch
+  # the same for many at once, as the aspects of one process ask
+  fetch:
+    query: false
+    input:
+      type: array
+      items:
+        type: object
+        properties:
+          component:
+            type: string
+          epoch:
+            type: string
+        required:
+          - component
+          - epoch
+    output:
+      type: array
+      items:
+        type: object
+        properties:
+          component:
+            type: string
+          epoch:
+            type: string
+          configuration:
+            type: object
+            nullable: true
+          created:
+            type: integer
+        required:
+          - component
+          - epoch
+          - configuration
+          - created
+  # every component's configuration for its deployed epoch, by component name
+  list:
+    query: false
+    output:
+      type: array
+      items:
+        type: object
+        properties:
+          component:
+            type: string
+          epoch:
+            type: string
+          schema:
+            type: object
+          configuration:
+            type: object
+        required:
+          - component
+          - epoch
+          - schema
+          - configuration
+  create:
+    query: false
+    input:
+      type: object
+      properties:
+        component:
+          type: string
+        configuration:
+          type: object
+        originator:
+          type: object
+          properties:
+            id:
+              type: string
+          required:
+            - id
+      required:
+        - component
+        - configuration
+        - originator
+    errors:
+      - UNKNOWN_COMPONENT
+      - INVALID_CONFIGURATION
+
+exposition:
+  isolated: true
+  /:
+    GET:
+      io:output: true
+      auth:role: system:configuration:get
+      endpoint: list
+  /:component:
+    map:segments:
+      component: component
+    GET:
+      io:output: true
+      auth:role: system:configuration:get
+      endpoint: get
+    POST:
+      io:output: [id, epoch]
+      auth:rule:
+        role: system:configuration:create
+        delegate: originator
+      endpoint: create

package/components/configuration.values/source/create.ts

@@ -0,0 +1,56 @@
+import * as schemas from '@toa.io/schemas'
+import { entry } from './lib/map'
+import type { Schema } from '@toa.io/schemas'
+
+export async function transition (input: Input, object: Entity): Promise<Entity | Error> {
+  const known = entry(input.component)
+
+  if (known === undefined)
+    return new UnknownComponentError(input.component)
+
+  // the schema fills its defaults, so what is stored is whole
+  const configuration = structuredClone(input.configuration)
+
+  const schema: Schema<any> = schemas.schema(known.schema)
+
+  try {
+    schema.validate(configuration)
+  } catch (error) {
+    return new InvalidConfigurationError((error as Error).message)
+  }
+
+  object.component = input.component
+  object.epoch = known.epoch
+  object.configuration = configuration
+  object.originator = input.originator.id
+
+  return object
+}
+
+class UnknownComponentError extends Error {
+  public readonly code = 'UNKNOWN_COMPONENT'
+
+  public constructor (component: string) {
+    super(`Component '${component}' is not configured`)
+  }
+}
+
+class InvalidConfigurationError extends Error {
+  public readonly code = 'INVALID_CONFIGURATION'
+}
+
+interface Input {
+  component: string
+  configuration: object
+  originator: {
+    id: string
+  }
+}
+
+interface Entity {
+  id: string
+  component: string
+  epoch: string
+  configuration: object
+  originator: string
+}

package/components/configuration.values/source/fetch.ts

@@ -0,0 +1,24 @@
+import { resolve, type Context } from './lib/resolve'
+
+export async function computation (input: Pair[], context: Context): Promise<Fetched[]> {
+  return await Promise.all(input.map(async ({ component, epoch }) => {
+    const value = await resolve(context, component, epoch)
+
+    return {
+      component,
+      epoch,
+      configuration: value === null ? null : value.configuration,
+      created: value === null ? 0 : value.created
+    }
+  }))
+}
+
+interface Pair {
+  component: string
+  epoch: string
+}
+
+interface Fetched extends Pair {
+  configuration: object | null
+  created: number
+}

package/components/configuration.values/source/get.ts

@@ -0,0 +1,33 @@
+import { entry } from './lib/map'
+import { resolve, type Context } from './lib/resolve'
+
+/**
+ * The latest configuration of a component, with the schema it is checked against. The
+ * schema is the deployment's, so an epoch the deployment does not know has none — the
+ * value is still what was stored for it.
+ */
+export async function computation (input: Input, context: Context): Promise<Item | null> {
+  const value = await resolve(context, input.component, input.epoch)
+
+  if (value === null)
+    return null
+
+  const known = entry(input.component)
+
+  return {
+    configuration: value.configuration,
+    schema: known?.schema,
+    epoch: input.epoch ?? known!.epoch
+  }
+}
+
+interface Input {
+  component: string
+  epoch?: string
+}
+
+interface Item {
+  configuration: object
+  schema?: object
+  epoch: string
+}

package/components/configuration.values/source/lib/map.test.ts

@@ -0,0 +1,34 @@
+import { VARIABLE, components, entry } from './map'
+
+afterEach(() => {
+  delete process.env[VARIABLE]
+})
+
+it('should be empty without the variable', () => {
+  expect(entry('a.b')).toBeUndefined()
+})
+
+it('should read the variable', () => {
+  const values = { 'a.b': { epoch: 'e', schema: { type: 'object' }, defaults: { foo: 1 } } }
+
+  process.env[VARIABLE] = JSON.stringify(values)
+
+  expect(entry('a.b')).toStrictEqual(values['a.b'])
+  expect(entry('a.c')).toBeUndefined()
+})
+
+it('should follow the variable', () => {
+  process.env[VARIABLE] = JSON.stringify({ 'a.b': { epoch: 'e1', schema: {} } })
+
+  expect(entry('a.b')?.epoch).toStrictEqual('e1')
+
+  process.env[VARIABLE] = JSON.stringify({ 'a.b': { epoch: 'e2', schema: {} } })
+
+  expect(entry('a.b')?.epoch).toStrictEqual('e2')
+})
+
+it('should list the components by name', () => {
+  process.env[VARIABLE] = JSON.stringify({ 'b.two': { epoch: 'e', schema: {} }, 'a.one': { epoch: 'e', schema: {} } })
+
+  expect(components()).toStrictEqual(['a.one', 'b.two'])
+})

package/components/configuration.values/source/lib/map.ts

@@ -0,0 +1,34 @@
+/** What the deployment told the service about every configured component. */
+export function entry (component: string): Entry | undefined {
+  return read()[component]
+}
+
+/** The configured components, by name. */
+export function components (): string[] {
+  return Object.keys(read()).sort()
+}
+
+function read (): Values {
+  const source = process.env[VARIABLE] ?? '{}'
+
+  // read again once the variable changes, as it does between scenarios of one process
+  if (source !== parsed) {
+    values = JSON.parse(source) as Values
+    parsed = source
+  }
+
+  return values
+}
+
+let parsed: string | null = null
+let values: Values = {}
+
+export const VARIABLE = 'TOA_CONFIGURATION_VALUES'
+
+export interface Entry {
+  epoch: string
+  schema: object
+  defaults?: object
+}
+
+export type Values = Record<string, Entry>

package/components/configuration.values/source/lib/resolve.ts

@@ -0,0 +1,54 @@
+import { entry } from './map'
+
+/**
+ * The latest configuration created for the component and the epoch; the deployed
+ * defaults when none was; `null` when the epoch is not the one deployed.
+ */
+export async function resolve (context: Context, component: string, epoch?: string): Promise<Value | null> {
+  const known = entry(component)
+
+  epoch ??= known?.epoch
+
+  if (epoch === undefined)
+    return null
+
+  // one query per pair, so that a component's latest is never behind another's newer ones
+  const query: Query = {
+    criteria: `component=="${component}";epoch=="${epoch}"`,
+    sort: ['_created:desc'],
+    limit: 1
+  }
+
+  const objects = await context.local.enumerate({ query })
+
+  if (objects.length > 0)
+    return { configuration: objects[0].configuration, created: objects[0]._created }
+
+  if (known !== undefined && known.epoch === epoch)
+    return { configuration: known.defaults ?? {}, created: 0 }
+
+  return null
+}
+
+/** A configuration and when it was created; `0` for the deployed defaults. */
+export interface Value {
+  configuration: object
+  created: number
+}
+
+export interface Context {
+  local: {
+    enumerate: (request: { query: Query }) => Promise<Stored[]>
+  }
+}
+
+interface Query {
+  criteria: string
+  sort: string[]
+  limit: number
+}
+
+interface Stored {
+  configuration: object
+  _created: number
+}

package/components/configuration.values/source/list.ts

@@ -0,0 +1,19 @@
+import { components, entry } from './lib/map'
+import { resolve, type Context } from './lib/resolve'
+
+/** The configuration of every component for its deployed epoch, by component name. */
+export async function computation (_: null, context: Context): Promise<Item[]> {
+  return await Promise.all(components().map(async (component) => {
+    const { epoch, schema } = entry(component)!
+    const value = await resolve(context, component, epoch)
+
+    return { component, epoch, schema, configuration: value!.configuration }
+  }))
+}
+
+interface Item {
+  component: string
+  epoch: string
+  schema: object
+  configuration: object
+}

package/components/configuration.values/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./operations",
+  },
+  "include": [
+    "source"
+  ]
+}

package/cucumber.js

@@ -0,0 +1,8 @@
+module.exports = {
+  default: {
+    paths: ['features/**/*.feature'],
+    requireModule: ['ts-node/register'],
+    require: ['./features/**/*.ts'],
+    failFast: true
+  }
+}

package/features/site/_app/immutable/asset.js

@@ -0,0 +1 @@
+export const hashed = true

package/features/site/index.html

@@ -0,0 +1,6 @@
+<!doctype html>
+<!-- stands in for what `ui` builds; the scenarios are about the server, not the page -->
+<html lang="en">
+  <head><title>fixture</title></head>
+  <body>the page</body>
+</html>