bridge

---
name: "bridge"
description: "The bridge worker connects this iii engine to another iii instance over iii-sdk so functions on either side can call across the boundary."
license: "Apache-2.0"
---

# bridge

The `bridge` worker connects this iii engine to another iii instance over
`iii-sdk` so functions on either side can call across the boundary. It opens a
single outbound WebSocket to the configured `url`, and stays open for the
worker's lifetime — bridging is request/response over that long-lived
connection. There are no trigger types.

The worker is configuration-driven. The primary surface is two list-shaped
config fields (`forward` and `expose`) that wire stable function ids on both
sides; once configured, callers reach across the bridge by invoking those
stable ids with the normal `iii.trigger({ function_id, payload })` — no
bridge-specific call shape. Two functions (`bridge.invoke`,
`bridge.invoke_async`) are also registered as ad-hoc escape hatches for the
rare case where the remote function id is dynamic at runtime.

Install it with `iii worker add bridge`. This is a standalone replacement for
the engine builtin `iii-bridge`: the builtin must not be running on the same
engine, since both register the same `bridge.invoke` / `bridge.invoke_async`
ids (plus any forward/expose ids) — the worker refuses to boot while
`iii-bridge` is still connected.

## When to Use

- Two iii engines need to call each other's functions over a stable,
  long-lived connection.
- You want a remote function to appear as a local id (`forward:`) so the
  bridge is invisible at the call site.
- You want to expose specific local functions to a remote engine (`expose:`).
- The remote function id is dynamic, or you are prototyping / probing
  connectivity — reach for the ad-hoc `bridge.invoke` functions.

## Boundaries

- Prefer `forward:` / `expose:` aliases over `bridge.invoke`; the escape
  hatches are for dynamic ids and one-offs, not the default path.
- `bridge.invoke_async` is fire-and-forget — it ignores `timeout_ms` and
  returns `null` immediately (the SDK requires a function to return a value; a
  later remote rejection is never surfaced to the caller).
- Forward aliases and exposed ids are operator-wired per deployment through
  the `configuration` worker's `bridge` entry (Console → Configuration →
  Workers → bridge), not documented here.
- `bridge.invoke` / `bridge.invoke_async` / forward calls always collapse
  failures to a `bridge_error` code, regardless of the remote's real error —
  a successful async return only means the message was queued, not that the
  remote ran. Expose calls are the exception: they forward the local
  function's real error code/message/stacktrace untouched.

## Functions

- `bridge.invoke` — call a remote `function_id` and wait for its return value
  (returned directly, no envelope); honors an optional `timeout_ms` (default
  `30000`).
- `bridge.invoke_async` — hand a remote call to the WebSocket send queue and
  return `null` immediately; `timeout_ms` is ignored and no remote response is
  surfaced.

Both take `{ function_id, data?, timeout_ms? }`. Reach for them only when a
`forward:` alias is wrong or impossible; for repeated calls to the same
`(local, remote)` pair, configure a `forward:` alias and call the local id
instead. Failures return a stable `code` (`deserialization_error` for a
malformed input, `bridge_error` otherwise).

## Configuration

Configuration lives in the `configuration` worker's `bridge` entry (hot-reload
— no restart needed for most changes):

- `url` — WebSocket URL of the remote iii instance. Fallback chain:
  `config.url` → `III_URL` env var → `ws://0.0.0.0:49134`. Changing it
  reconnects to the new remote.
- `expose: [{ local_function, remote_function? }]` — functions on this engine
  the remote may call; `remote_function` is the name registered on the remote
  (defaults to `local_function`). Newly added entries register live on the
  current remote connection.
- `forward: [{ local_function, remote_function, timeout_ms? }]` — local
  aliases that proxy outbound to a remote function. The worker registers
  `local_function` on this engine so any caller reaches the remote's
  `remote_function`; `timeout_ms` overrides the per-call deadline (default
  `30000`). Newly added entries register live.

Removing a `forward`/`expose` entry does not un-register its handler (the SDK
has no unregister): the function id stays callable but returns a
`bridge_error` until the worker restarts.