Stream Concepts

Data flows. It arrives from a network socket in unpredictable chunks. It leaves through a file descriptor as fast as the disk allows. It passes through encryption, compression, and framing layers—​each transforming it before handing it off to the next. Modeling this flow well is one of the most important things an I/O library can do.

Capy organizes data flow around three concepts: ReadStream, WriteStream, and Stream. The design reflects a truth about I/O that most libraries gloss over. Partial operations and complete operations are fundamentally different things, and conflating them leads to bugs.

A socket might give you 47 bytes when you asked for 1024. That is not an error—​it is the nature of the hardware. Some code needs to handle those 47 bytes immediately and ask for more. Other code needs exactly 1024 bytes and should not return until it has them (or an error occurs). Capy’s stream concepts cover the partial case directly: read_some and write_some transfer whatever the hardware allows. The complete case is a composed algorithm, not a separate concept. read, write, read_at_least, and write_at_least loop over read_some or write_some until the buffer is satisfied or an error occurs.