Eve library

Bridge Parallel-Operation Guide (180.C.38.02)

Guide

Revision 1

On this page

Status: 180.C.38.02 — running the OLD bridges and the NEW Remote Host simultaneously, with conflict detection and reconciliation rules.

This guide executes the parallel-operation section of the bridge coexistence and deprecation plan (180.C.16.15). It is the operational companion to:

What runs in parallel#

Surface Process Ports Owns
Legacy Blender bridge apps/bellona/bridge-blender ws://127.0.0.1:9001/blender Loopback WS command forwarding only
Legacy Unreal bridge apps/bellona/bridge-unreal ws://127.0.0.1:9003/unreal Loopback WS command forwarding only
Remote Host gateway apps/bellona/remote-gateway :4070 (POST /v1/commands, POST /v1/legacy-bridge/commands) Policy, approvals, audit, timeline, distributed locks, command envelopes

During rollout BOTH may run. The Remote Host is the single long-term authority; the legacy bridges keep working through the compatibility shim (libs/bellona/remote-protocol/src/bridge-compat.ts, translateLegacyBridgeRequest) which is reached at the gateway via POST /v1/legacy-bridge/commands (apps/bellona/remote-gateway/src/legacy-bridge.ts, acceptLegacyBridgeRequest). Every legacy call is counted by the remote_gateway.legacy_bridge.usage.count telemetry series (recordLegacyBridgeUsage, apps/bellona/remote-gateway/src/telemetry.ts).

The shared resources both surfaces contend for#

Two operations — one on each surface — can target the SAME shared resource. The contended resource kinds are defined by RemoteLockResourceKind (libs/bellona/remote-protocol/src/fleet.ts); the two that matter for engine coexistence are:

  • blender-file — a .blend file path
  • unreal-map — an Unreal map/level path (e.g. /Game/Maps/Main)

A resource is identified by (kind, key) via remoteLockResourceId(resource) (it renders as blender-file::/proj/scene.blend). Two operations address the same target iff their (kind, key) match.

The arbiter: the 30.04 distributed lock manager#

The gateway's InMemoryDistributedLockManager (apps/bellona/remote-gateway/src/distributed-lock-manager.ts, stage 180.C.30.04) is the single authority that grants/denies access to a shared resource. It is a reader/writer lock per (kind, key):

  • shared (RemoteLockMode = 'shared', read) holders coexist — any number.
  • exclusive (RemoteLockMode = 'exclusive', write) is mutually exclusive — exactly one holder, refused/queued while any other holder is present.

A host never grants its own lock; the gateway does. This is what lets the legacy bridges and the Remote Host coexist safely: BOTH write paths acquire a lock from the same gateway authority before mutating a Blender file or an Unreal map, so the gateway serializes them.

Conflict-detection rule (code, not prose)#

The coexistence rule is a real, tested helper, not a doc paragraph: detectBridgeConflict(legacyOp, remoteOp) in libs/bellona/remote-protocol/src/bridge-compat.ts (tested in bridge-compat.test.ts). Each BridgeOperation carries:

ts
interface BridgeOperation {
  origin: 'legacy-bridge' | 'remote-host';
  resource: RemoteLockResource; // { kind, key }
  mode: RemoteLockMode;         // 'shared' (read) | 'exclusive' (write)
  label?: string;
}

The rule:

  1. Different resources (remoteLockResourceId differs) → no conflict. They coexist freely.
  2. Same resource, both shared (read/read) → no conflict. Shared locks coexist; both proceed.
  3. Same resource, both exclusive (write/write) → write-write conflict, mutual exclusion. The lock manager grants whoever acquires FIRST and refuses/queues the other; they cannot run concurrently. The pure rule reports mutualExclusion: true and leaves winner undefined — the manager, with its FIFO wait queue and lease expiry, breaks the tie, not this stateless helper.
  4. Same resource, exactly one exclusive (read/write) → read-write conflict. The writer wins the exclusive lock (winner = the writer); the reader must serialize — wait for, or run before, the writer.

Who wins, concretely#

Legacy op Remote op Outcome Winner
read /proj/a.blend read /proj/a.blend coexist both
read /Game/Maps/Main write /Game/Maps/Main reader serializes behind writer Remote Host (writer)
write /proj/scene.blend read /proj/scene.blend reader serializes behind writer Legacy bridge (writer)
write /proj/scene.blend write /proj/scene.blend mutual exclusion first acquirer (lock manager FIFO)

How a conflict surfaces#

A losing acquire is fail-loud, never a silent clobber. The lock manager returns a DistributedLockGrant with granted: false, outcome: 'conflict', the blocking conflictingHolderIds, and a human reason (apps/bellona/remote-gateway/src/distributed-lock-manager.ts). A caller may instead pass wait: true to be QUEUED (FIFO) and receive its queue position; a later release or lease expiry that satisfies the head of the queue grants it.

Reconciliation rules#

  1. Single writer per engine resource. Only one write path may own mutating traffic for a given Blender file or Unreal map at a time — enforced by the exclusive lock, regardless of whether the writer is a legacy bridge or the Remote Host (this is the plan's "only one write path may own mutating traffic" rule, made executable by detectBridgeConflict + the lock manager).
  2. Prefer the future authority. When a Remote Host equivalent exists, route through it (the shim does this automatically — a translatable legacy command becomes a RemoteCommandEnvelope and acquires the gateway lock like any native command). This means legacy write traffic and native write traffic contend on the SAME lock, so they cannot both mutate the resource.
  3. Reads never block reads. Discovery/health/scene-info on either surface use shared locks and run concurrently.
  4. Leases bound a crashed holder. A bridge or host that dies without releasing has its lock reclaimed once the lease elapses, so a crash on one surface cannot permanently wedge the other.
  5. Commands without Remote Host parity stay loopback-only (e.g. blender:set-frame, unreal:load-level) until their replacement stage lands or telemetry proves zero consumers. The shim FAILS LOUD on these (UnsupportedLegacyBridgeCommandError) rather than fabricating an envelope, so they are never silently routed to a non-existent Remote Host command.

Verification#

bash
cd libs/bellona/remote-protocol && npx vitest run src/bridge-compat.test.ts
cd apps/bellona/remote-gateway && npx vitest run src/distributed-lock-manager.test.ts

The detectBridgeConflict rule above is verified by the describe('detectBridgeConflict — 180.C.38.02') block in libs/bellona/remote-protocol/src/bridge-compat.test.ts.