feat(io): add fd_read_into — zero-allocation incremental read from an fd

[paul-hammant]

Closes #1471.

First, a correction to the issue's premise

The issue says streaming from a run_pipe fd is impossible in pure Aether. I tested that before writing anything, and io.fd_read_n already does incremental reads. A child writing two chunks 200ms apart to fd 3:

first  -> n=6 data='chunk1'     ← returns immediately, child still running
second -> n=6 data='chunk2'     ← after the gap
eof    -> n=0

The issue looked for the call under std.net — which has fd_write and fd_close but no read — and it lives under std.io, where std.tar already uses it.

So the streaming half was already there. What was genuinely missing is the zero-allocation form, which is the half that actually matters for the video case the issue describes.

What this adds

io.fd_read_into(fd, buf, length) -> (n, err)

Mirrors fs.pread_into, which was already this shape for files — so a caller streaming from a pipe now gets the same option as one reading a file. n == 0 is EOF, 0 < n < length is a normal short read, EINTR is retried.

The key difference from fd_read_n: it returns as soon as any bytes are available rather than looping to fill the buffer. On a live pipe, waiting to fill would stall until the producer happened to send a whole buffer's worth, which defeats the purpose.

At 1080p30, one 8 MB frame per read is ~250 MB/s of allocator churn if every read mints a fresh string. One reused caller-owned buffer avoids it entirely.

A gap the issue didn't mention, left alone deliberately

run_pipe's fd is the AETHER_IPC_FD side channel on fd 3, not the child's stdout. A child must write to fd 3 deliberately, so the issue's motivating example — ffmpeg -f rawvideo -pix_fmt rgba -, which writes stdout — will not feed it as-is.

That is a separate gap (no way to capture a child's stdout incrementally) and not what was asked for, so this PR does not touch it. Recorded here and in the commit because anyone following the issue's example will hit it.

Tests

tests/regression/test_fd_read_into.ae pins the properties that matter: chunks arrive before the child exits, one buffer serves every read, EOF is n == 0 so the loop terminates, and bad arguments are refused.

Verified the test has teeth — it fails on 3 assertions when the read is made drain-to-fill, so it cannot silently rot into the behaviour it exists to prevent.

Verification

• make ci — C suite 230/230; .ae 977/978 with [PASS] regression_test_fd_read_into, count up 977 → 978. The one failure is integration_http_server_h2, pre-existing and diagnosed in pesky_bug.md.
• Valgrind clean — worth stating explicitly for an API whose entire point is not allocating.
• gcc -Werror and clang -Werror checked locally before pushing, per the lesson from fix(fs): name the path and the cause in fs.read / fs.read_binary errors #1469.
• CHANGELOG entry written before committing, not after — the omission that cost four releases their entries.

One usability trap, documented

Writing through bytes.data(buf) does not publish the buffer's length, so bytes.to_string(buf, n) returns "" with no error until bytes.set_length(buf, n) is called. I hit this writing the test; it is now called out in the wrapper's doc comment and the CHANGELOG. Callers passing the bytes to another extern never need it.

🤖 Generated with Claude Code