File Descriptors & Non-Blocking I/O - Syscalls, EAGAIN, Partial Writes & Framing

# Blocking vs non-blocking fds: EAGAIN on read, and partial writes when the
# kernel socket buffer fills. Linux/macOS, Python 3.8+.
import errno, socket

a, b = socket.socketpair()
b.setblocking(False)                      # O_NONBLOCK: calls return instead of waiting

# 1) Read with no data: blocking would sleep; non-blocking fails fast with EAGAIN.
try:
    b.recv(1024)
except BlockingIOError as e:
    print("empty read  ->", errno.errorcode[e.errno])   # EAGAIN (aka EWOULDBLOCK)

# 2) Write until the kernel send buffer is full: send() returns a SHORT count,
#    then EAGAIN. Real servers must keep the leftover bytes and retry on writable.
b.setsockopt(socket.SOL_SOCKET, socket.SO_SNDBUF, 4096)
chunk = b"x" * 65536
total, partial_writes = 0, 0
while True:
    try:
        n = b.send(chunk)
        total += n
        if n < len(chunk):
            partial_writes += 1           # kernel accepted only part of our buffer
    except BlockingIOError:
        break                             # buffer full: wait for EPOLLOUT/writable
print("buffer full ->", f"accepted {total > 0}, partial_writes>=1: {partial_writes >= 1}")

# 3) The reader drains; now the writer could make progress again.
drained = 0
a.setblocking(False)
while True:
    try:
        drained += len(a.recv(65536))
    except BlockingIOError:
        break
print("drained == accepted:", drained == total)

empty read  -> EAGAIN
buffer full -> accepted True, partial_writes>=1: True
drained == accepted: True

// TCP is a byte stream: one write can arrive as many reads, or several writes as one.
// A length-prefixed frame decoder must handle both. Pure TypeScript.
class FrameDecoder {
  private buf = new Uint8Array(0);
  // Feed any chunk; returns every complete frame found so far.
  push(chunk: Uint8Array): string[] {
    const merged = new Uint8Array(this.buf.length + chunk.length);
    merged.set(this.buf); merged.set(chunk, this.buf.length);
    this.buf = merged;
    const frames: string[] = [];
    // Frame = 4-byte big-endian length + payload.
    while (this.buf.length >= 4) {
      const len = new DataView(this.buf.buffer, this.buf.byteOffset).getUint32(0);
      if (this.buf.length < 4 + len) break;          // partial frame: wait for more bytes
      frames.push(new TextDecoder().decode(this.buf.subarray(4, 4 + len)));
      this.buf = this.buf.slice(4 + len);
    }
    return frames;
  }
}

function encode(msg: string): Uint8Array {
  const body = new TextEncoder().encode(msg);
  const out = new Uint8Array(4 + body.length);
  new DataView(out.buffer).setUint32(0, body.length);
  out.set(body, 4);
  return out;
}

// Two messages concatenated, then sliced at awkward offsets (like real reads).
const wire = new Uint8Array([...encode("GET /a"), ...encode("GET /bb")]);
const cuts = [3, 7, 12, 15];          // split inside the header and inside the payload
const dec = new FrameDecoder();
let start = 0;
for (const end of [...cuts, wire.length]) {
  const got = dec.push(wire.subarray(start, end));
  console.log(`read bytes [${start},${end}) -> frames: ${JSON.stringify(got)}`);
  start = end;
}

read bytes [0,3) -> frames: []
read bytes [3,7) -> frames: []
read bytes [7,12) -> frames: ["GET /a"]
read bytes [12,15) -> frames: []
read bytes [15,21) -> frames: ["GET /bb"]