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:
!Sendthroughout, errors that carryRc, 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. - Event
Group - Events that one origin-side decision appended together, and the condition it appended them under.
- Peer
Limits - What a peer can accept.
- Pull
Batch Limit - A running budget for filling one
pullresponse. - Pulled
- What one
pullreturned. - Push
Batch - A batch of events crossing the boundary, decomposed into the groups that must land atomically.
Enums§
- Sync
Error - Why a peer exchange failed for reasons no adapter owns.
- Waiting
- What the far side still holds past the token a
pullreturned, asPulled::waitingreports it.
Traits§
- Send
Sync Peer - One peer relationship.
- Sync
Peer - One peer relationship.