Skip to main content

​
Startup flow

When the Engine starts it does a few things:
  1. It parses its command-line arguments.
  2. Loads its configuration file (typically config.yaml).
  3. Applies the worker declarations from the config (starting each declared worker process).
  4. Begins serving connections.
After this sequence the Engine is ready to accept WebSocket connections from Workers and route invocations between them.

​
Engine responsibilities

The Engine’s responsibilities cover three concerns at runtime. First, it accepts WebSocket connections from Workers and maintains the live registry of which Workers are currently connected. Second, it tracks the Functions each connected Worker has registered and the observers each Worker has created, exposing them as a unified system-wide surface. Third, it routes invocations: when a Function is called, or an observer runs its target, the Engine finds a Worker that provides the Function and dispatches the call.

​
Worker disconnect cleanup

When a Worker disconnects, the Engine cleans up the Worker’s footprint in the live registry: its Functions are removed, in-flight invocations of those Functions are cancelled, the observers it created wait as suspended, the observers of its Functions wait as pending until a Worker registers those Functions again, and the rest of the system keeps serving.
See Creating Workers / Workers / Handling Worker disconnects for the cancellation error code and the discovery events that fire (with their consistency semantics).

​
Config hot-reload

config.yaml is watched at runtime. When the file changes, the Engine parses, diffs, validates, and commits the new config. Workers that did not change in the diff stay running through the reload, so only added, removed, or changed Workers are restarted. An invalid config.yaml (parse error or validation failure) causes the Engine to exit rather than enter an indeterminate state. Worker settings are a separate layer. A Worker that registers a configuration schema reads its config: block once, at first boot, to bootstrap its entry in the configuration worker; from then on its settings are managed there and updated dynamically, without an engine reload. Settings changes are validated against the Worker’s schema: an invalid change is rejected and the previous value stays in effect, so a bad settings edit never takes the Engine down.

​
Architecture-agnostic routing

Routing is independent of language, runtime, and location. The Engine applies the same routing path whether a Function is hosted by a Python Agent on a laptop, a TypeScript Worker in a browser tab, a Rust binary in a microVM, or an OCI image on Kubernetes. This is what makes “any language, any runtime” a concrete property of iii rather than an aspiration.

​
Discovery and the live registry

The Engine maintains a registry of every connected Worker, the Functions each Worker has registered, and the observers of those Functions. Other Workers and tooling can read the registry on demand or observe its changes as it evolves.
See Creating Workers / Workers / Inspecting the live registry for the concrete engine::*::list snapshot calls and the engine::on-workers-changed, engine::on-functions-changed, and engine::on-observers-changed Functions that Workers observe for changes.
Querying traces, logs, and metrics is documented with the iii-observability Worker.