Skip to content
Sign in

state

v0.23.1

Distributed key-value state management — registers the `state::*` functions and `state::on-changed`, a private function observers watch for every committed change.

license: Apache-2.0Used in 3 kitscachedistributedkey-valuekvstate

Install

bash
iii trigger compose::add worker=state@0.23.1

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

Functions13

state::barrier

Function

Fan-in gate for an observer condition: record one arrival and answer `skip` until the expected set has arrived, then `allow` exactly once carrying every arrival's payload.

Request
  • condition_configany of
    any of (2)
    Variant 1
    • carrystring

      JSON pointer into the event for the value to accumulate (default: the whole event).

    • expectall ofrequired

      A count, or the exact set of arrival keys.

      Show 1 nested
      all of (1)
      Variant 1
      any of (2)
      Variant 1
      valueinteger· uint641…10000
      Variant 2
      itemsstring[]
    • idstringrequired

      Barrier identity. Two observers sharing an id share the barrier — that is how several predecessors feed one downstream.

    • key_fromstring

      JSON pointer into the event for the arrival key (default `/key`); a pointer that resolves to nothing is an error.

    Variant 2
    valuenull
  • eventunknown
Response
one of (2)
Variant 1
  • decisionstringrequiredenum allow
  • payloadunknown
  • reasonstringrequired
Variant 2
  • decisionstringrequiredenum skip
  • reasonstringrequired

state::claim-namespace

Function

Reserve a private state namespace for the calling worker (its own worker name only): its scopes leave public state::* and state::on-changed, and `<prefix>::state::{get, list, compare-and-set}` accessors are registered. Idempotent.

Request
  • _caller_worker_idstring
  • functions_prefixstringrequired

    Must equal the calling worker's name.

  • scopesstring[]required

    Storage scopes to reserve for this namespace.

Response
  • claimedbooleanrequired

    False when the namespace already owned everything asked for.

  • functionsstring[]required

    The accessor ids now serving this namespace.

  • scopesstring[]required

    Every scope this namespace owns after the call.

state::compare-and-set

Function

Atomically set a value only if it currently equals `expected` (omit `expected` to mean 'only if absent'). Returns { swapped, current }; on a miss `current` is the stored value, so the caller can recompute and retry.

Request
  • expectedunknown

    The value the caller believes is there. Omit to mean "expect absent" — the set-if-absent form.

  • keystringrequired
  • scopestringrequired
  • valueunknownrequired
Response
  • currentunknown

    What is actually stored, when the swap did not happen.

  • swappedbooleanrequired

state::delete

Function

Delete the value stored at a key in a state scope

Request
  • keystringrequired

    Identifier for the value to delete within the scope.

  • scopestringrequired

    Namespace that groups related keys.

Response
valuestring

state::get

Function

Read the value stored at a key in a state scope

Request
  • keystringrequired

    Identifier for the value within the scope.

  • scopestringrequired

    Namespace that groups related keys.

Response
valuestring

state::list

Function

List every value stored in a state scope

Request
  • scopestringrequired

    Namespace whose keys should be listed as a group.

Response
valuestring

state::list_groups

Function

List all state scopes (groups) that hold values

Request
Empty object
Response
  • groupsstring[]required

state::list_keys

Function

List the keys stored in a state scope

Request
  • scopestringrequired

    Namespace whose keys should be listed as a group.

Response
  • keysstring[]required

    Keys stored in the scope, in the adapter's natural order.

state::on-changed

Function

One call per committed state change (state::set, state::update, state::delete, a swapped state::compare-and-set). The handler returns the change event it is called with, { type, event_type, scope, key, old_value, new_value }, so observers observe it as input and output. Observe it with no args and filter on input.scope / input.key / input.event_type; caller.function_id is the state function that wrote, and caller.parent the worker that called it. Private: only the state worker calls it. Private namespaces never emit, and `events_enabled: false` silences it.

Request
  • event_typeall ofrequired

    `state:created`, `state:updated` or `state:deleted`.

    all of (1)
    Variant 1
    valuestringenum state:created, state:updated, state:deleted
  • keystringrequired

    The changed key.

  • new_valueunknownrequired

    The value after the change; `null` for a deleted key.

  • old_valueunknown

    The value before the change; `null` for a created key.

  • scopestringrequired

    Scope of the changed key.

  • typestringrequired

    Always `state`.

Response
  • event_typeall ofrequired

    `state:created`, `state:updated` or `state:deleted`.

    all of (1)
    Variant 1
    valuestringenum state:created, state:updated, state:deleted
  • keystringrequired

    The changed key.

  • new_valueunknownrequired

    The value after the change; `null` for a deleted key.

  • old_valueunknown

    The value before the change; `null` for a created key.

  • scopestringrequired

    Scope of the changed key.

  • typestringrequired

    Always `state`.

state::on-config-change

Function

Internal: reload state configuration from the authoritative store on change.

Request
Empty object
Response
  • okbooleanrequired

state::set

Function

Store or write a value at a key in a state scope; it persists across sessions

Request
  • keystringrequired

    Identifier for the value within the scope.

  • scopestringrequired

    Namespace that groups related keys (e.g. `users`, `orders`).

  • valueunknownrequired

    Arbitrary JSON value to store. Replaces any existing value at `scope`/`key`.

Response
  • new_valueunknownrequired

    The value after the update

  • old_valueunknown

    Previous value (if it existed).

state::ui-content

Function

Serve the state worker's injected console UI assets (the target of its ade::ui::asset observers; the console calls it through each asset's observer with {path}).

Request
  • pathstringrequired

    The asset path from the observer's args (e.g. `state/page.js`).

Response
  • contentstringrequired

    The asset source, verbatim.

  • content_typestringrequired

    MIME type the console should serve the asset with.

state::update

Function

Update part of a stored value: set, merge, increment, append or remove fields

Request
  • keystringrequired

    Identifier for the value to update within the scope.

  • opsone of[]required

    Ordered list of update operations applied atomically to the existing value.

    one of (6)
    Variant 1
    • pathstringrequired
    • typestringrequiredenum set
    • valueunknown
    Variant 2
    • pathany of
      Show 2 nested
      any of (2)
      Variant 1
      any of (2)
      Variant 1
      valuestring
      Variant 2
      itemsstring[]
      Variant 2
      valuenull
    • typestringrequiredenum merge
    • valueunknownrequired
    Variant 3
    • byinteger· int64required
    • pathstringrequired
    • typestringrequiredenum increment
    Variant 4
    • byinteger· int64required
    • pathstringrequired
    • typestringrequiredenum decrement
    Variant 5
    • pathany of
      Show 2 nested
      any of (2)
      Variant 1
      any of (2)
      Variant 1
      valuestring
      Variant 2
      itemsstring[]
      Variant 2
      valuenull
    • typestringrequiredenum append
    • valueunknownrequired
    Variant 6
    • pathstringrequired
    • typestringrequiredenum remove
  • scopestringrequired

    Namespace that groups related keys.

Response
  • errorsobject[]

    Errors encountered while applying ops. Successfully applied ops are still reflected in `new_value`. Field is omitted from JSON when empty for backward compatibility.

    • codestringrequired

      Stable error code, e.g. `"merge.path.too_deep"`.

    • doc_urlstring

      Optional documentation URL for this error class.

    • messagestringrequired

      Human-readable description with concrete numbers when applicable.

    • op_indexinteger· uintrequiredmin 0

      Index of the offending op within the original `ops` array.

  • new_valueunknownrequired

    The value after the update

  • old_valueunknown

    Previous value (if it existed).

Search the registry

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