62 lines
2.3 KiB
Markdown
62 lines
2.3 KiB
Markdown
|
# EdgeEstablisher Contract
|
||
|
|
|
||
|
|
This document defines the behavioral contract for local edge establishment. It
|
||
|
|
turns `ProvisionTx` or `ProvisionRx` into a local edge actor, arena lease,
|
||
|
|
worker ring installation, driver establishment, and ready/fault outcome.
|
||
|
|
|
||
|
|
## Provisioning
|
||
|
|
|
||
|
|
- Each node has one `EdgeEstablisher`.
|
||
|
|
- `ProvisionTx` creates a local send edge record.
|
||
|
|
- `ProvisionRx` creates a local receive edge record.
|
||
|
|
- The producer needs the consumer `node_id`.
|
||
|
|
- The consumer needs the shared `edge_id`.
|
||
|
|
- Remote actor addresses are not required for data flow.
|
||
|
|
|
||
|
|
## Lease Flow
|
||
|
|
|
||
|
|
- Establishment requests one arena lease per edge end.
|
||
|
|
- `RingLeased` matching the request advances the edge record.
|
||
|
|
- `RingLeaseRejected` matching the request fails the edge record.
|
||
|
|
- Stale lease events for stopped records do not install worker or pump state.
|
||
|
|
- An unused fresh lease granted after cancellation is released.
|
||
|
|
|
||
|
|
## Worker Ring Installation
|
||
|
|
|
||
|
|
- The edge establishes driver state only after worker or token endpoint ring
|
||
|
|
installation succeeds.
|
||
|
|
- `RingInstalled` matching the edge advances establishment.
|
||
|
|
- `RingFault` before readiness stops establishment.
|
||
|
|
- Ring installation uses the `ObjectSpec` and `RingSpec` from provisioning.
|
||
|
|
|
||
|
|
## Driver Establishment
|
||
|
|
|
||
|
|
- Send edges call `EstablishSend` with `edge_id`, consumer `node_id`, and local
|
||
|
|
ring layout.
|
||
|
|
- Receive edges call `EstablishRecv` with `edge_id` and local ring layout.
|
||
|
|
- `DriverEdgeReady` marks the local edge actor ready.
|
||
|
|
- Stream and pump behavior are driver-owned after readiness.
|
||
|
|
|
||
|
|
## Ready And Hot Path
|
||
|
|
|
||
|
|
- Ready means local actor, arena lease, worker/token ring, and driver state are
|
||
|
|
installed.
|
||
|
|
- The hot path runs without `EdgeEstablisher`.
|
||
|
|
- The establisher observes coarse ready, stopped, and fault events only.
|
||
|
|
|
||
|
|
## Stopping
|
||
|
|
|
||
|
|
- `StopEdge` cancels queued leases.
|
||
|
|
- `StopEdge` stops pumps if present.
|
||
|
|
- `StopEdge` uninstalls worker rings if installed.
|
||
|
|
- The arena lease is released only after quiescence proof.
|
||
|
|
- `Stopped` is terminal for that edge record.
|
||
|
|
|
||
|
|
## Test Direction
|
||
|
|
|
||
|
|
Tests should drive the public establishment FSM with lease, worker, driver, and
|
||
|
|
stop events. Successful tests should assert the order lease -> install ->
|
||
|
|
driver -> ready. Fault tests should inject lease rejection, ring fault, driver
|
||
|
|
fault, stale events, and stop races and assert no hot-path state survives
|
||
|
|
incorrectly.
|