From eb910dfa3abbfa162fb6140b4cebf1ccfe04819c Mon Sep 17 00:00:00 2001
From: Florian Klink <flokli@flokli.de>
Date: Mon, 8 Apr 2024 00:22:51 +0300
Subject: docs(tvix/nix-compat/wire): update docstrings

Only describe the format once (in `read_bytes`, and simplify the other
docstrings a bit.

Change-Id: Iff898f3c4173d506a357bc14bdffbf69c4c6e0e0
Reviewed-on: https://cl.tvl.fyi/c/depot/+/11374
Tested-by: BuildkiteCI
Reviewed-by: picnoir picnoir <picnoir@alternativebit.fr>
Autosubmit: flokli <flokli@flokli.de>
---
 tvix/nix-compat/src/wire/bytes.rs | 40 ++++++++++++++++++++-------------------
 1 file changed, 21 insertions(+), 19 deletions(-)

diff --git a/tvix/nix-compat/src/wire/bytes.rs b/tvix/nix-compat/src/wire/bytes.rs
index f7fb0b9c6e..e2f34ead6b 100644
--- a/tvix/nix-compat/src/wire/bytes.rs
+++ b/tvix/nix-compat/src/wire/bytes.rs
@@ -8,12 +8,23 @@ use tokio::io::{AsyncReadExt, AsyncWriteExt};
 use super::primitive;
 
 #[allow(dead_code)]
-/// Read a limited number of bytes from the AsyncRead.
+/// Read a "bytes wire packet" from the AsyncRead.
 /// Rejects reading more than `allowed_size` bytes of payload.
-/// Internally takes care of dealing with the padding, so the returned `Vec<u8>`
-/// only contains the payload.
-/// This always buffers the entire contents into memory, we'll add a streaming
-/// version later.
+///
+/// The packet is made up of three parts:
+/// - a length header, u64, LE-encoded
+/// - the payload itself
+/// - null bytes to the next 8 byte boundary
+///
+/// Ensures the payload size fits into the `allowed_size` passed,
+/// and that the padding is actual null bytes.
+///
+/// On success, the returned `Vec<u8>` only contains the payload itself.
+/// On failure (for example if a too large byte packet was sent), the reader
+/// becomes unusable.
+///
+/// This buffers the entire payload into memory, a streaming version will be
+/// added later.
 pub async fn read_bytes<R, S>(r: &mut R, allowed_size: S) -> std::io::Result<Vec<u8>>
 where
     R: AsyncReadExt + Unpin,
@@ -61,12 +72,9 @@ where
     Ok(buf)
 }
 
-/// Read a Nix daemon string from the AsyncWrite, encoded as utf8.
-/// Rejects reading more than `allowed_size` bytes
-///
-/// A Nix daemon string is made up of two distincts parts:
-/// 1. Its lenght, LE-encoded on 64 bits.
-/// 2. Its content. 0-padded on 64 bits.
+/// Read a "bytes wire packet" of from the AsyncRead and tries to parse as string.
+/// Internally uses [read_bytes].
+/// Rejects reading more than `allowed_size` bytes of payload.
 pub async fn read_string<R, S>(r: &mut R, allowed_size: S) -> std::io::Result<String>
 where
     R: AsyncReadExt + Unpin,
@@ -76,15 +84,9 @@ where
     String::from_utf8(bytes).map_err(|e| Error::new(ErrorKind::InvalidData, e))
 }
 
-/// Writes a sequence of sized bits to a (hopefully buffered)
-/// [AsyncWriteExt] handle.
-///
-/// On the wire, it looks as follows:
+/// Writes a "bytes wire packet" to a (hopefully buffered) [AsyncWriteExt].
 ///
-/// 1. Number of bytes contained in the buffer we're about to write on
-///    the wire. (LE-encoded on 64 bits)
-/// 2. Raw payload.
-/// 3. Null padding up until the next 8 bytes alignment block.
+/// See [read_bytes] for a description of the format.
 ///
 /// Note: if performance matters to you, make sure your
 /// [AsyncWriteExt] handle is buffered. This function is quite
-- 
cgit 1.4.1