Document how to close a stream correctly

quinn/src/recv_stream.rs

@@ -21,8 +21,51 @@ use crate::{
 /// - A variant of [`ReadError`] has been yielded by a read call
 /// - [`stop()`] was called explicitly
 ///
+/// # Closing a stream
+///
+/// When a stream is expected to be closed gracefully the sender should call
+/// [`SendStream::finish`].  However there is no guarantee the connected [`RecvStream`] will
+/// receive the "finished" notification in the same QUIC frame as the last frame which
+/// carried data.
+///
+/// Even if the application layer logic already knows it read all the data because it does
+/// its own framing, it should still read until it reaches the end of the [`RecvStream`].
+/// Otherwise it risks inadvertently calling [`RecvStream::stop`] if it drops the stream.
+/// And calling [`RecvStream::stop`] could result in the connected [`SendStream::finish`]
+/// call failing with a [`WriteError::Stopped`] error.
+///
+/// For example if exactly 10 bytes are to be read, you still need to explicitly read the
+/// end of the stream:
+///
+/// ```no_run
+/// # use quinn::{SendStream, RecvStream};
+/// # async fn func(
+/// #     mut send_stream: SendStream,
+/// #     mut recv_stream: RecvStream,
+/// # ) -> anyhow::Result<()>
+/// # {
+/// // In the sending task
+/// send_stream.write(&b"0123456789"[..]).await?;
+/// send_stream.finish().await?;
+///
+/// // In the receiving task
+/// let mut buf = [0u8; 10];
+/// let data = recv_stream.read_exact(&mut buf).await?;
+/// if recv_stream.read_to_end(0).await.is_err() {
+///     recv_stream.stop(0u8.into()).ok();
+/// }
+/// # Ok(())
+/// # }
+/// ```
+///
+/// Note that in this example the receiver sends an error to the sender if it received some
+/// unexpected data, interrupting any further attempts to send data.  But crucially only
+/// after it attempted to read the end of the stream.
+///
 /// [`ReadError`]: crate::ReadError
 /// [`stop()`]: RecvStream::stop
+/// [`SendStream::finish`]: crate::SendStream::finish
+/// [`WriteError::Stopped`]: crate::WriteError::Stopped
 #[derive(Debug)]
 pub struct RecvStream {
     conn: ConnectionRef,