Struct NeonReadStream
pub struct NeonReadStream<'a, T: SqlTransport> { /* private fields */ }event-store only.Expand description
The read “stream”: one round trip, then a buffer being drained.
§This is the honest part of the crate
EventStore::read’s doc comment says the stream is what “lets an adapter
stream a million-event replay without buffering it”. This adapter cannot do
that and no version of it ever will, because Neon’s /sql endpoint has no
cursor: the response is one JSON document, capped at
MAX_RESPONSE_BYTES, and it either
arrives whole or fails with NeonError::ResponseTooLarge. The Stream impl
below is therefore a shape, not a capability — it satisfies the port’s
signature exactly and honours roughly none of the port’s prose.
The one property it does honour is laziness. read is not async, so
nothing is sent when it is called; the request sits unsent in the state
machine below until the first poll_next. That is load-bearing on wasm32,
where issuing a fetch outside a polled future is not merely wasteful but
happens off the event loop the runtime owns.
§ES-11: what is free, and what the transport’s fence buys
Half of ES-11 is free here and the other half is bought, and the difference is worth stating where a caller meets it. One read is one statement, so there is no second sample for the answer to drift against: the paging defect ES-11 is mostly about — a store that re-queries per page and grows under the caller’s feet — is unreachable by construction.
The other half is that the snapshot the endpoint takes precedes an append
this caller issues immediately afterwards. The request is dispatched at the
first poll, the earliest the port permits, and on its own it is one of two
independent requests to a proxy that hands each to whichever backend it
likes: no session, no queue and no protocol ordering between them.
So the order is bought at the transport instead. A conforming
SqlTransport registers this read when the first poll dispatches it and
settles it when the endpoint answers, and
append waits on
SqlTransport::reads_settled before it sends anything. An answer follows
the statement’s execution, so the snapshot precedes the write: an order the
endpoint honours, which ADR-0061 requires and spawn order alone never gave.
The release is driven by the transport, never by polling this stream — a stream polled once and set aside does not hold an append back forever. An unpolled stream has dispatched nothing and costs an append nothing.
Without the fence the race was observed: over the conformance transport
read_result_is_stable_under_concurrent_append failed intermittently,
always with the read seeing an event appended after it was issued. ADR-0087
records the live sweep that measured the race with the fence and without it,
and the rate it found; the fence is what this crate ships since 0.4.0.
The ordering domain is one transport value: reads and appends through clones of one transport are ordered, and those through independent transports are not — a stated limit of this store’s ES-11 claim, which no rule can observe through the port. ADR-0087 records the claim as met for operations that share one transport, and stated as such.