Skip to content
Registry

configuration

v0.24.6

Register, store, and watch typed configuration values for the engine.

Engine module
Baked into the iii engine; no separate install required.

Install

bash
iii trigger compose::add worker=configuration

Run in your project with the iii engine running. Exact versions are immutable and digest-pinned.

Functions8

configuration::ensure

Function

Atomically ensure a configuration id exists with a schema, name, description, and metadata, seeding initial_value ONLY when no non-null value is stored yet. An existing non-null value (including false, 0, or empty string) is preserved verbatim and the candidate seed is ignored (and not validated). Unlike configuration::register, ensure never overwrites a stored value, so it is the race-free way for one or many workers to seed a default. Fires configuration:registered on first creation or configuration:updated when an existing entry is refreshed.

Request
  • descriptionstringrequired

    Description shown in `configuration::list`.

  • idstringrequired

    Configuration id. Must match `[a-z0-9_-]{1,64}` so it is safe as a filename in the `fs` adapter.

  • initial_valueunknown

    Optional seed value. Applied atomically ONLY when no non-null value is already stored for this id (the id is absent or its stored value is `null`). When a non-null value already exists it is preserved verbatim and this candidate is ignored — never validated. When the seed IS applied it is validated against `schema` exactly like `configuration::register` validates `initial_value`.

  • metadataunknown

    Optional opaque metadata stored alongside the entry.

  • namestringrequired

    Human-readable name shown in `configuration::list`.

  • schemaunknownrequired

    JSON Schema describing the value shape. `set` validates against this.

Response
  • actionall ofrequired

    What ensure did: seeded the candidate, preserved an existing value, or registered the entry with a null value.

    all of (1)
    Variant 1
    one of (3)
    Variant 1
    valuestringenum seeded
    Variant 2
    valuestringenum preserved
    Variant 3
    valuestringenum registered
  • entryall ofrequired

    The stored entry after ensure. Templates inside `value` are kept verbatim; expansion happens on read.

    all of (1)
    Variant 1
    • descriptionstringrequired

      One-line description of what this configuration controls.

    • idstringrequired

      Stable identifier (e.g. `iii-stream`, `iii-observability`).

    • metadataunknown

      Optional caller-supplied metadata (owner team, change ticket, etc.).

    • namestringrequired

      Human-readable display name.

    • schemaunknown

      JSON Schema describing the shape of `value`. Not persisted to disk by the fs adapter; rebuilt in-memory when the owning worker re-registers.

    • valueunknown

      Stored configuration body. May contain `${VAR:default}` placeholders.

configuration::get

Function

Read the active configuration by id (execution injection when present, otherwise the persistent base). Expands ${VAR:default} placeholders against the live process env unless raw=true is passed.

Request
  • idstringrequired
  • rawboolean

    When `true`, return the stored value verbatim (including `${VAR}` placeholders). When `false` (default), expand `${VAR:default}` against the live process env.

Response
  • idstringrequired
  • valueunknownrequired

configuration::list

Function

List every registered configuration with id, name, description, and schema. Sorted by id; never returns the stored value.

Request
Empty object
Response
  • configurationsobject[]required
    • descriptionstringrequired
    • idstringrequired
    • metadataunknown
    • namestringrequired
    • schemaunknownrequired

configuration::migrate

Function

Move an exact legacy configuration id at the authority, replacing the destination with the source and archiving the source as .yaml.bak. Active memory follows a successful move without being persisted. An absent persisted source leaves the destination unchanged and retires orphan source memory. The response contains the persisted entry. Stop consumers before migrating.

Request
  • from_idstringrequired
  • to_idstringrequired
Response
  • actionstringrequiredenum migrated, preserved, missing

    Migration never treats an existing null value as absence.

  • entryany of
    any of (2)
    Variant 1
    • descriptionstringrequired

      One-line description of what this configuration controls.

    • idstringrequired

      Stable identifier (e.g. `iii-stream`, `iii-observability`).

    • metadataunknown

      Optional caller-supplied metadata (owner team, change ticket, etc.).

    • namestringrequired

      Human-readable display name.

    • schemaunknown

      JSON Schema describing the shape of `value`. Not persisted to disk by the fs adapter; rebuilt in-memory when the owning worker re-registers.

    • valueunknown

      Stored configuration body. May contain `${VAR:default}` placeholders.

    Variant 2
    valuenull

configuration::migration-capabilities

Function

Read-only migration contract negotiation. Revision 1 guarantees source priority and source archival; it does not migrate or write configuration.

Request
valueunknown
Response
valueunknown

configuration::register

Function

Register a configuration id with a name, description, and JSON Schema. Idempotent — re-registering replaces metadata and (when initial_value is provided) the value. Validates initial_value against the schema.

Request
  • descriptionstringrequired

    Description shown in `configuration::list`.

  • idstringrequired

    Configuration id. Must match `[a-z0-9_-]{1,64}` so it is safe as a filename in the `fs` adapter.

  • initial_valueunknown

    Optional initial value to install. Validated against `schema`.

  • metadataunknown

    Optional opaque metadata stored alongside the entry.

  • namestringrequired

    Human-readable name shown in `configuration::list`.

  • schemaunknownrequired

    JSON Schema describing the value shape. `set` validates against this.

Response
  • descriptionstringrequired

    One-line description of what this configuration controls.

  • idstringrequired

    Stable identifier (e.g. `iii-stream`, `iii-observability`).

  • metadataunknown

    Optional caller-supplied metadata (owner team, change ticket, etc.).

  • namestringrequired

    Human-readable display name.

  • schemaunknown

    JSON Schema describing the shape of `value`. Not persisted to disk by the fs adapter; rebuilt in-memory when the owning worker re-registers.

  • valueunknown

    Stored configuration body. May contain `${VAR:default}` placeholders.

configuration::schema

Function

Retrieve the schema, name, and description for a configuration id. Mirrors a single entry from configuration::list.

Request
  • idstringrequired
Response
  • descriptionstringrequired
  • idstringrequired
  • metadataunknown
  • namestringrequired
  • schemaunknownrequired

configuration::set

Function

Replace the active configuration and notify consumers. flush=true (default) validates and persists the complete value for a registered id. flush=false updates memory only and may precede registration; validation uses the schema when available. No automatic later flush.

Request
  • flushboolean

    Persist the complete value (default true). False updates only active memory and permits delivery before the owning worker registers its schema.

  • idstringrequired
  • valueunknownrequired

    New configuration value. Validated against the schema when available.

Response
  • new_valueunknownrequired

    Current stored value (templates not expanded).

  • old_valueunknown

    Previous stored value, or `null` when the entry had no value yet.

Triggers0

No triggers registered

Search the registry

Find workers, kits and executables, or jump to a page.