From 5363f5b7e878ddd7498c3223b31cb5217f18e578 Mon Sep 17 00:00:00 2001 From: Thomas Eizinger Date: Fri, 14 Oct 2022 23:42:14 +1100 Subject: [PATCH 1/3] Add "Stream behaviour" section --- connections/README.md | 47 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/connections/README.md b/connections/README.md index 1d51b498f..a36d495e7 100644 --- a/connections/README.md +++ b/connections/README.md @@ -29,6 +29,10 @@ and spec status. - [multistream-select](#multistream-select) - [Upgrading Connections](#upgrading-connections) - [Opening New Streams Over a Connection](#opening-new-streams-over-a-connection) + - [Stream Behaviour](#stream-behaviour) + - [States](#states) + - [Resets](#resets) + - [State transition diagram](#state-transition-diagram) - [Practical Considerations](#practical-considerations) - [Interoperability](#interoperability) - [State Management](#state-management) @@ -263,6 +267,49 @@ indicating whether the handler supports the protocol. This allows more flexible behavior than exact literal matching, which is the default behavior if no match function is provided. +## Stream Behaviour + +This section specifies the expected behaviour of a libp2p stream. + +### States + +A libp2p stream can be in one of four states: + +- Open for reading and writing +- Open for reading only +- Open for writing only +- Closed + +The default state after opening a new stream is "Open for reading and writing". +Either party can at any point close the reading or writing side. + +The "Closed" state is the product of both halfs (read and write) of the stream being closed. +This can happen because one party closes both halfs but also as a combination +of both parties closing their write-half (which automatically closes other's read-half). + +Writing to a write-closed stream SHOULD fail with an error clearly signalling the closed state. + +Reading from a read-closed stream SHOULD succeed by reading 0 bytes. +This allows for a robust "read to end"-behaviour. +Layers on top of the stream MAY fail with an unexpected EOF error in case more data was expected. + +### Resets + +A stream reset is an abrupt termination of the stream. +Implementations SHOULD reset a stream to signal a non-graceful close. +Typically, this is during a resource cleanup like garbage-collection for streams +which have not been closed properly (see [States](#states) above). + +Upon receiving a stream reset, any buffered data in the stream MAY be discarded. + +Reading and writing to a reset stream SHOULD fail with an error clearly signalling the reset. + +### State transition diagram + +The following diagram illustrates the state transitions: + +![https://www.planttext.com/?text=VP8nRy8m48Nt-nKd690gUUZAK14wT6ibEZ04XXGV4CdOw7mHwh_d70XDIDB5ikzzx-xPyY9AmLAT782KuWY_XQauePQ58ku3urc1Nym0yfSj6lE6NsVo06b5m-NXAFdqnrMqLMdDfT2x2v7i79UuIxk8brJj6WvCv7kEh75e1ditEDgt1gnKwFNlqO_kRJmRYfDFcMmY6sf5aGJWppZAT94cu72uBlk8Dn8DMe_oFrytVw97azoQFz73rmSVX71Yz6onOD91MeyRR_0ZXQbheM8C5ztlf0o-5fSwkzRagBekz-ypYmqrmIBYvol0WhpLVtS5](https://www.planttext.com/api/plantuml/svg/VP8nRy8m48Nt-nKd690gUUZAK14wT6ibEZ04XXGV4CdOw7mHwh_d70XDIDB5ikzzx-xPyY9AmLAT782KuWY_XQauePQ58ku3urc1Nym0yfSj6lE6NsVo06b5m-NXAFdqnrMqLMdDfT2x2v7i79UuIxk8brJj6WvCv7kEh75e1ditEDgt1gnKwFNlqO_kRJmRYfDFcMmY6sf5aGJWppZAT94cu72uBlk8Dn8DMe_oFrytVw97azoQFz73rmSVX71Yz6onOD91MeyRR_0ZXQbheM8C5ztlf0o-5fSwkzRagBekz-ypYmqrmIBYvol0WhpLVtS5) + ## Practical Considerations This section will go over a few aspects of connection establishment and state From 1fcb6ab7039014f6df17e95ea532a3ccae7effe4 Mon Sep 17 00:00:00 2001 From: Thomas Eizinger Date: Fri, 14 Oct 2022 23:46:18 +1100 Subject: [PATCH 2/3] Update mplex spec --- mplex/README.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/mplex/README.md b/mplex/README.md index cc68b1876..e747a1ba6 100644 --- a/mplex/README.md +++ b/mplex/README.md @@ -107,9 +107,8 @@ To close a stream, send a message with a zero length body and a `CloseReceiver` ### Resetting a stream -To immediately close a stream for both reading and writing, use reset. This should generally only be used on error; during normal operation, both sides should close instead. - -To reset a stream, send a message with a zero length body and a `ResetReceiver` (5) or `ResetInitiator` (6) flag. Reset must immediately close both ends of the stream for both reading and writing. Writing to a stream after it has been reset is a protocol violation. Since reset is generally sent when an error happens, all future reads from a reset stream should return an error (*not* EOF). +To reset a stream, send a message with a zero length body and a `ResetReceiver` (5) or `ResetInitiator` (6) flag. +See [stream resets](../connections/README.md#resets) for a detailed behaviour description. ## Implementation notes From 5b033ca2dc5a14bd4654452036903ef7e3c00d82 Mon Sep 17 00:00:00 2001 From: Thomas Eizinger Date: Fri, 14 Oct 2022 23:50:04 +1100 Subject: [PATCH 3/3] Link to stream behaviour section --- connections/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/connections/README.md b/connections/README.md index a36d495e7..a974c61f4 100644 --- a/connections/README.md +++ b/connections/README.md @@ -76,7 +76,7 @@ verifiable by the other peer. libp2p connection. They must support backpressure, which prevents receivers from being flooded by data from eager senders. They can also be "half closed", meaning that a stream can be closed for writing data but still open to receiving -data and vice versa. +data and vice versa. See [Stream Behaviour](#stream-behaviour) for details. Support for multiple streams ensures that a single connection between peers can support a wide variety of interactions, each with their own protocol. This is