65 lines
2.2 KiB
Markdown
65 lines
2.2 KiB
Markdown
|
# Driver And Pump Contract
|
||
|
|
|
||
|
|
This document defines the behavioral contract for the iroh driver, edge demux,
|
||
|
|
and send/recv pumps. The driver owns tokio, connections, streams, demux, and
|
||
|
|
byte-pump tasks.
|
||
|
|
|
||
|
|
## Driver Authority
|
||
|
|
|
||
|
|
- The driver owns one iroh endpoint.
|
||
|
|
- The driver owns connection caching.
|
||
|
|
- The driver owns edge ALPN.
|
||
|
|
- The driver owns edge-id stream demux.
|
||
|
|
- The driver owns send and recv pump tasks.
|
||
|
|
- Actors do not poll stream futures directly in the MVP.
|
||
|
|
|
||
|
|
## Connection And Stream Shape
|
||
|
|
|
||
|
|
- Each edge uses one persistent uni-stream.
|
||
|
|
- The stream starts with an `edge_id` preamble.
|
||
|
|
- After the preamble, the stream carries object records as bytes.
|
||
|
|
- The stream is not opened per object.
|
||
|
|
- Connections may be cached per `(peer_node_id, ALPN)`.
|
||
|
|
|
||
|
|
## Receive Rendezvous
|
||
|
|
|
||
|
|
- `EstablishRecv` may arrive before the stream.
|
||
|
|
- The stream may arrive before `EstablishRecv`.
|
||
|
|
- The driver stores whichever half arrives first.
|
||
|
|
- The recv pump starts only after both receive spec and stream exist.
|
||
|
|
- A pending stream is not read before the receive spec exists.
|
||
|
|
|
||
|
|
## Recv Pump
|
||
|
|
|
||
|
|
- The recv pump is byte-blind after edge demux.
|
||
|
|
- It does not parse `ObjectHeader`.
|
||
|
|
- It copies QUIC bytes into free ingress ring spans.
|
||
|
|
- It advances `commit` after bytes are in the ring.
|
||
|
|
- It emits or coalesces `RingReadable`.
|
||
|
|
- If no ring space exists, it stops reading and waits for `RingWritable`.
|
||
|
|
|
||
|
|
## Send Pump
|
||
|
|
|
||
|
|
- The send pump opens one uni-stream for the edge.
|
||
|
|
- It writes the `edge_id` preamble once.
|
||
|
|
- It writes committed egress ring bytes to QUIC.
|
||
|
|
- It advances `consume` only after `write_all` accepts bytes.
|
||
|
|
- It emits or coalesces `RingWritable`.
|
||
|
|
- If network or QUIC flow control stalls, it keeps ownership of unread ring
|
||
|
|
bytes until the write completes.
|
||
|
|
|
||
|
|
## Fault And Stop
|
||
|
|
|
||
|
|
- Read error emits `StreamFault`.
|
||
|
|
- Write error emits `StreamFault`.
|
||
|
|
- Protocol edge failure emits `StreamFault`.
|
||
|
|
- `StopEdge` stops the corresponding pump.
|
||
|
|
- Stopped pumps emit `PumpStopped`.
|
||
|
|
|
||
|
|
## Test Direction
|
||
|
|
|
||
|
|
Tests should use mock streams and rings to drive driver messages and pump wake
|
||
|
|
events. Successful tests should assert rendezvous in both arrival orders,
|
||
|
|
preamble once, byte-blind copying, cursor advancement after I/O acceptance, and
|
||
|
|
backpressure. Fault tests should inject read/write errors and stop races.
|