Expose QUIC datagrams on the connection surface - #30
Merged
Conversation
The datagram half of #3's connection API, driven by the mosh-over-SSP experiment: three functions on `connection`, RFC 9221 end to end. - `max-datagram-size` reports the current ceiling (path-MTU-dependent; the WIT doc states the ~1.1 KiB expectation under this package's fixed 1200-byte MTU profile) and doubles as the capability probe — `none` means the peer accepts no datagrams. - `send-datagram` is synchronous and never applies backpressure: a full send buffer drops the oldest queued datagrams (noq's `drop=true`). Ruling on #28's open question: loss is this transport's semantics and a full buffer is loss; the driving consumer (SSP) wants stale state diffs dropped, not queued, and drop keeps the call sync. Too-large and peer-accepts-none fail `invalid-argument`. - `recv-datagram` is async with the accept-family concurrency contract (concurrent callers each get one datagram). The other #28 question — a non-blocking `try-recv` companion — is deliberately absent: async recv plus concurrent calls cover pump-style consumers on the async ABI, and the function is additive latitude if a consumer shows the need. Implementation is thin by design: noq-proto queues datagrams internally in both directions, so the endpoint's `DatagramReceived` / `DatagramsUnblocked` events stay discarded — resource methods poll the queues directly under the existing bounded-polling discipline, and `recv-datagram` is the `accept-stream` pattern verbatim. The spike guest's leg is event-driven instead: its scripted exchange grows an unconditional datagram echo (client sends after the stream echo and closes only once the echo returns), which turns its former event-discard site into the handler. Both demo sides send fixed copies of one datagram rather than retrying: datagrams are lossy by contract, and duplication keeps the exchange deterministic on lossless local wires without either side cancelling a pending receive (an in-flight import subtask must resolve — the jco discipline). Conformance: the endpoint matrix rows assert the datagram echo over the relay, the UDP direct path, and the WebRTC channel (`--datagram` on the demo and both hosts' drivers; the jco endpoint driver carries the flag for when #10 unblocks); the interop rows assert it against upstream iroh in both directions — RFC 9221 wire compatibility against the real implementation, not just ourselves; and the spike rows exercise it under jco today. Full gate run: fmt, clippy, validate-wit, test, probes, matrix (17/17), bench budgets all green. Fixes #28
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The datagram half of #3's connection API, driven by the mosh-over-SSP
experiment: three functions on
connection, RFC 9221 end to end.max-datagram-sizereports the current ceiling (path-MTU-dependent;the WIT doc states the ~1.1 KiB expectation under this package's
fixed 1200-byte MTU profile) and doubles as the capability probe —
nonemeans the peer accepts no datagrams.send-datagramis synchronous and never applies backpressure: a fullsend buffer drops the oldest queued datagrams (noq's
drop=true).Ruling on Endpoint surface: expose QUIC datagrams as one-shot messages #28's open question: loss is this transport's semantics and
a full buffer is loss; the driving consumer (SSP) wants stale state
diffs dropped, not queued, and drop keeps the call sync. Too-large
and peer-accepts-none fail
invalid-argument.recv-datagramis async with the accept-family concurrency contract(concurrent callers each get one datagram). The other Endpoint surface: expose QUIC datagrams as one-shot messages #28 question —
a non-blocking
try-recvcompanion — is deliberately absent: asyncrecv plus concurrent calls cover pump-style consumers on the async
ABI, and the function is additive latitude if a consumer shows the
need.
Implementation is thin by design: noq-proto queues datagrams
internally in both directions, so the endpoint's
DatagramReceived/DatagramsUnblockedevents stay discarded — resource methods poll thequeues directly under the existing bounded-polling discipline, and
recv-datagramis theaccept-streampattern verbatim. The spikeguest's leg is event-driven instead: its scripted exchange grows an
unconditional datagram echo (client sends after the stream echo and
closes only once the echo returns), which turns its former
event-discard site into the handler.
Both demo sides send fixed copies of one datagram rather than
retrying: datagrams are lossy by contract, and duplication keeps the
exchange deterministic on lossless local wires without either side
cancelling a pending receive (an in-flight import subtask must
resolve — the jco discipline).
Conformance: the endpoint matrix rows assert the datagram echo over
the relay, the UDP direct path, and the WebRTC channel (
--datagramon the demo and both hosts' drivers; the jco endpoint driver carries
the flag for when #10 unblocks); the interop rows assert it against
upstream iroh in both directions — RFC 9221 wire compatibility against
the real implementation, not just ourselves; and the spike rows
exercise it under jco today. Full gate run: fmt, clippy, validate-wit,
test, probes, matrix (17/17), bench budgets all green.
Review notes
try-recvin v1 (async recv + the accept-family concurrency contract cover pumps; additive if a consumer shows need).endpoint/src/endpoint_impl.rskeeps discarding both datagram events — noq queues internally and the bounded-polling discipline reads the queues directly, sorecv-datagramisaccept-streamverbatim. The spike guest goes the other way (event-driven), so both plumbing styles named in Endpoint surface: expose QUIC datagrams as one-shot messages #28 are exercised.--datagramon the endpoint relay/UDP/WebRTC rows, on both interop rows (upstream iroh both directions — the RFC 9221 wire-compat claim), and unconditionally in the spike exchange (the only jco-running legs until jco: scheduler stops delivering waitable events once a detached task holds in-flight imports across export calls #10). Matrix 17/17, bench budgets hold.DATAGRAM_COPIESconvention exists because the demos must be deterministic on lossy-by-contract transport without cancelling a pending receive (jco's in-flight-subtask discipline).Fixes #28