datagrams: Add initial datagram draft #680
There are no files selected for viewing
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
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,101 @@ | ||||||
| # Datagrams in libp2p | ||||||
|
|
||||||
| | Lifecycle Stage | Maturity | Status | Latest Revision | | ||||||
| | --------------- | ------------- | ------ | --------------- | | ||||||
| | 1A | Working Draft | Active | r0, 2025-05-23 | | ||||||
|
|
||||||
| Authors: [@marcopolo] | ||||||
|
|
||||||
| Interest Group: [@sukunrt], [@jxs], [@raulk] | ||||||
|
|
||||||
| [@marcopolo]: https://github.com/marcopolo | ||||||
| [@sukunrt]: https://github.com/sukunrt | ||||||
| [@jxs]: https://github.com/jxs | ||||||
| [@raulk]: https://github.com/raulk | ||||||
|
|
||||||
| See the [lifecycle document][lifecycle-spec] for context about the maturity level | ||||||
| and spec status. | ||||||
|
|
||||||
| [lifecycle-spec]: https://github.com/libp2p/specs/blob/master/00-framework-01-spec-lifecycle.md | ||||||
|
|
||||||
| ## Table of Contents | ||||||
|
|
||||||
| - [Introduction](#introduction) | ||||||
| - [Native support at the transport level](#native-support-at-the-transport-level) | ||||||
| - [Datagrams on QUIC](#datagrams-on-quic) | ||||||
| - [Encoding](#encoding) | ||||||
| - [Datagrams on WebTransport](#datagrams-on-webtransport) | ||||||
| - [Datagrams on top of a multiplexed stream on top of TCP](#datagrams-on-top-of-a-multiplexed-stream-on-top-of-tcp) | ||||||
| - [Datagrams with WebRTC](#datagrams-with-webrtc) | ||||||
|
|
||||||
| ## Introduction | ||||||
|
|
||||||
| This specification defines libp2p datagrams, which enable the transmission of | ||||||
| MTU-sized, unreliable, and low latency messages between peers. | ||||||
|
|
||||||
| TODO write more about the tradeoffs here as well as the kinds of applications that would benefit from using datagrams. | ||||||
|
|
||||||
| ## Native support at the transport level | ||||||
|
|
||||||
| Some libp2p transports natively support datagrams, such as QUIC and | ||||||
| WebTransport. libp2p implementations MUST use the native datagram support to | ||||||
| send datagrams. | ||||||
|
|
||||||
| - QUIC has an Unreliable Datagram Extension [RFC 9221]. | ||||||
| - WebTransport supports Datagrams though HTTP Datagrams [WebTransport draft RFC](https://www.ietf.org/archive/id/draft-ietf-webtrans-http3-12.html#name-datagrams) | ||||||
|
|
||||||
| ## Datagrams on QUIC | ||||||
|
|
||||||
| Each datagram flow MUST be associated with a control stream. A datagram flow is | ||||||
| defined as a logical flow of datagrams related to a specific application | ||||||
| protocol. A control stream is a QUIC bidirectional stream that has negotiated | ||||||
| the libp2p datagram control stream protocol ID `/dg/1`. The initiator MUST send | ||||||
| the related application protocol ID with a [uvarint] length prefix after | ||||||
| negotiating the control stream. The control stream MUST stay open for the | ||||||
| duration of the datagram flow. Implementation MAY create the control stream and | ||||||
| start sending datagrams at once. There is currently no other use for the control | ||||||
|
There was a problem hiding this comment. What should happen to datagrams that arrive before control stream has finished |
||||||
| stream besides negotiating the application protocol ID. Receipt of a QUIC | ||||||
| DATAGRAM frame whose payload is too short to allow parsing the Control Stream ID | ||||||
| field MUST be treated as a connection error of type PROTOCOL_VIOLATION (0x1003). | ||||||
|
There was a problem hiding this comment. Perhaps something like this so the name does not clash with QUIC's own PROTOCOL_VIOLATION (0x0a) error? (also on line 71:72)
Suggested change
|
||||||
| libp2p datagrams MUST NOT be sent unless the control stream's send side is open. | ||||||
| If a datagram is received after the corresponding stream's receive side is | ||||||
| closed, the received datagrams MUST be silently dropped. | ||||||
|
|
||||||
| If a libp2p datagram is received and its Control Stream ID field maps to a | ||||||
| stream that has not yet been created, the receiver SHALL either drop that | ||||||
| datagram silently or buffer it temporarily (on the order of a round trip) while | ||||||
| awaiting the creation of the corresponding stream. | ||||||
|
|
||||||
| If a libp2p datagram is received and its Control Stream ID field maps to a | ||||||
| stream that cannot be created due to client-initiated bidirectional stream | ||||||
| limits, it MUST be treated as a connection error of type PROTOCOL_VIOLATION | ||||||
| (0x1003). | ||||||
|
Comment on lines
+69
to
+72
There was a problem hiding this comment. i'm a bit confused by the reference to "client-initiated bidirectional stream limits". Can control streams be opened by either peer? |
||||||
|
|
||||||
| ### Encoding | ||||||
|
|
||||||
| Each libp2p datagram SHALL be encoded with the following structure. | ||||||
|
|
||||||
| | Field Name | Data Type | Length (bits) | Description | | ||||||
| | ---------------- | ------------- | ------------- | --------------------------------------------------------------------- | | ||||||
| | Control StreamID | [QUIC varint] | 8..64 | The stream ID of the associated control stream for this datagram flow | | ||||||
| | Application Data | byte sequence | variable | Application payload | | ||||||
|
|
||||||
| ## Datagrams on WebTransport | ||||||
|
|
||||||
| libp2p datagrams on WebTransport behave the same as libp2p datagrams on QUIC. | ||||||
| However, the application data may be further limited by the overhead of HTTP | ||||||
| Datagram's Quarter Stream ID field. | ||||||
|
|
||||||
| In the future, a separate spec may be able to remove this overhead. | ||||||
|
Comment on lines
+85
to
+89
There was a problem hiding this comment. the quic encoding uses a stream id as the control stream identifier, but browser webtransport doesn't expose quic stream ids. If browser implementations are expected to support this, how is the control stream identified? would some specific webtransport flow identifier be needed? |
||||||
|
|
||||||
| ## Datagrams on top of a multiplexed stream on top of TCP | ||||||
|
|
||||||
| This is currently not specified. | ||||||
|
|
||||||
| ## Datagrams with WebRTC | ||||||
|
|
||||||
| This is currently not specified. | ||||||
|
|
||||||
| [RFC 9221]: https://www.rfc-editor.org/rfc/rfc9221 | ||||||
| [QUIC varint]: https://www.rfc-editor.org/rfc/rfc9000.html#name-variable-length-integer-enc | ||||||
| [uvarint]: https://github.com/multiformats/unsigned-varint | ||||||
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
i think it would help to clarify the receiver behavior if the application protocol id is unsupported or malformed. (i.e. close stream / reset?). Is this going to use multistream-select?