Skip to main content

Module peer

Module peer 

Expand description

The peer port, in two flavours.

§Status: sketch

This is a phase-2 instrument, not the protocol. It exists to answer one falsifiable question — can a peer be stated without naming a transport? — and it is settled against the two peers the deployment actually has, which are as unlike each other as the story allows:

  • a Cloudflare Durable Object reached over a socket: !Send throughout, errors that carry Rc, no ambient runtime to spawn into;
  • a Postgres over one-shot HTTP: Send, owns nothing between calls, cannot hold a cursor open, one round trip per operation.

Both are implemented against this trait in this crate’s tests/. What that proved, and what it did not, is written down at the bottom of this page.

§Two flavours, for the third time

SyncPeer is written without any Send requirement and trait_variant derives SendSyncPeer from it, exactly as happenstance-core does for its two ports. The scheme is not being copied for symmetry: the Durable Object peer cannot satisfy a Send bound and the HTTP peer wants one, so a single trait would exclude one of the two peers this crate exists to serve.

As everywhere else: bind SyncPeer in generic code — it is the weaker requirement and accepts both — and import only one of the two names per module, or method calls go ambiguous with error[E0034].

§Why pull returns a batch and not a stream

EventStore::read returns impl Stream at the top level, and that is load-bearing there: it is what lets the Send flavour mark the stream Send, and laziness is what buys a million-event replay without buffering.

It is the wrong shape here. A stream is a cursor, a cursor is state held between polls, and a peer reached over one-shot HTTP has nothing to hold it in: no connection, no session, no transaction. So pull returns a bounded batch and an owned resume token, and the caller loops. One round trip per call, by construction rather than by documentation.

This is not a free choice, and the type checker does not make it for us. The cursor shape was attempted, pointed at both peers, and compiled against both: the one-shot HTTP peer satisfies impl Stream by buffering a whole response into a Vec and replaying it. Legal, Send, and a lie. tests/cursor_shape_probe.rs is that experiment, kept compiling so the result cannot rot. What it means for this port is that one round trip with no held state has to be checked by a fixture peer that counts its own round trips, in the conformance suite — the port itself cannot express it.

Structs§

Ack
What the far side did with a push.
EventGroup
Events that one origin-side decision appended together, and the condition it appended them under.
PeerLimits
What a peer can accept.
PullBatchLimit
A running budget for filling one pull response.
Pulled
What one pull returned.
PushBatch
A batch of events crossing the boundary, decomposed into the groups that must land atomically.

Enums§

SyncError
Why a peer exchange failed for reasons no adapter owns.
Waiting
What the far side still holds past the token a pull returned, as Pulled::waiting reports it.

Traits§

SendSyncPeer
One peer relationship.
SyncPeer
One peer relationship.