Intermediate Examples

# ex-17: -v prints each captured packet's options list in full -- filtering
# to SYN packets only (tcp-syn flag set) isolates the two handshake segments
# that actually carry window-scale negotiation, so "wscale" is easy to find
# alongside "mss" and "sackOK" in the exact documented options order (co-08)
tcpdump -i eth0 -n -v 'tcp and port 443 and tcp[tcpflags] & (tcp-syn) != 0' -c 2 &
sleep 1
curl -s -o /dev/null --http1.1 https://example.com
sleep 1

tcpdump: listening on eth0, link-type EN10MB (Ethernet), snapshot length 262144 bytes
01:18:43.662122 IP (tos 0x0, ttl 64, id 45998, offset 0, flags [DF], proto TCP (6), length 60)
    172.17.0.3.49572 > 172.66.147.243.443: Flags [S], cksum 0xec78 (incorrect -> 0x7d6d), seq 3435443398, win 65495, options [mss 65495,sackOK,TS val 2642412001 ecr 0,nop,wscale 7], length 0
01:18:43.684982 IP (tos 0x0, ttl 63, id 23885, offset 0, flags [none], proto TCP (6), length 60)
    172.66.147.243.443 > 172.17.0.3.49572: Flags [S.], cksum 0x5597 (incorrect -> 0xc0d3), seq 1765133752, ack 3435443399, win 65408, options [mss 65495,sackOK,TS val 3820069439 ecr 2642412001,nop,wscale 7], length 0
2 packets captured
2 packets received by filter
0 packets dropped by kernel

# learning/code/ex-18-tcp-flow-control-window-shrink/flow_control_window_shrink.py
"""Example 18: TCP Flow Control -- a Slow Reader Blocks a Fast Writer."""  # => co-08: this file's own restated purpose, doubling as its module __doc__
 
from __future__ import annotations  # => DD-39 hygiene: postpones type-annotation evaluation, keeping this file interpreter-version-agnostic
 
import socket  # => co-08: raw sockets -- the level flow control actually operates at, below any application framing
import threading  # => co-08: runs the SLOW reader concurrently with the fast writer on one localhost connection
import time  # => co-08: sleeps simulate a receiver that is busy/slow, and times the writer's blocking send() call
 
HOST = "127.0.0.1"  # => co-08: loopback -- no real network needed, only the kernel's OWN TCP stack on both ends
CHUNK = 65536  # => co-08: 64 KiB per send() call -- large enough to fill a shrunk window in only a few calls
SLOW_READ_DELAY_SECONDS = 2.0  # => co-08: how long the "slow reader" sleeps BEFORE its first recv() call
SEND_TIMEOUT_SECONDS = 1.0  # => co-08: how long the writer waits before treating a stalled send() as "blocked by the window"
 
 
def slow_reader(server_sock: socket.socket, received: list[int]) -> None:  # => co-08: the RECEIVER side -- deliberately withholds recv()
    """Accept one connection, sleep (simulating a busy receiver), then drain everything at once."""  # => co-08: documents slow_reader's contract -- no runtime output, just sets its __doc__
    conn, _ = server_sock.accept()  # => co-08: blocks here until the client (writer) below connects
    time.sleep(SLOW_READ_DELAY_SECONDS)  # => co-08: THE key delay -- no recv() calls happen while the sender is writing
    total = 0  # => co-08: running count of bytes eventually drained, once reading finally starts
    conn.settimeout(0.5)  # => co-08: bounds the final drain loop so this thread cannot hang forever
    try:  # => co-08: the drain loop below ends naturally once the writer stops sending (timeout) or closes
        while True:  # => co-08: keep draining until no more data arrives within the timeout window
            data = conn.recv(CHUNK)  # => co-08: NOW the receiver finally starts reading -- this is what un-shrinks the window
            if not data:  # => co-08: an empty recv() means the peer closed its write side (a FIN was received)
                break  # => co-08: nothing more will ever arrive -- stop draining
            total += len(data)  # => co-08: tally every byte actually read off the socket
    except TimeoutError:  # => co-08: no more data within 0.5s -- treat this as "the writer is done sending"
        pass  # => co-08: expected end-of-burst condition, not an error
    received.append(total)  # => co-08: reports the final drained byte count back to the main thread
    conn.close()  # => co-08: releases this connection's resources on the receiver side
 
 
if __name__ == "__main__":  # => co-08: entry point -- this block runs only when the file executes directly, not on import
    server_sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)  # => co-08: the listening socket the slow reader accepts on
    server_sock.setsockopt(socket.SOL_SOCKET, socket.SO_RCVBUF, 4096)  # => co-08: request a SMALL receive buffer -- shrinks the window sooner
    server_sock.bind((HOST, 0))  # => co-08: port 0 -- let the OS pick a free ephemeral port, avoiding hardcoded-port collisions
    server_sock.listen(1)  # => co-08: one pending connection is all this single-client demo needs
    port = server_sock.getsockname()[1]  # => co-08: the OS-assigned port, needed by the client below to connect back
 
    received: list[int] = []  # => co-08: a mutable box the reader thread appends its final tally into, for the main thread to read
    reader_thread = threading.Thread(target=slow_reader, args=(server_sock, received))  # => co-08: runs slow_reader() concurrently
    reader_thread.start()  # => co-08: starts accepting (and then deliberately delaying) in the background
 
    client_sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)  # => co-08: the WRITER side -- tries to send as fast as it can
    client_sock.connect((HOST, port))  # => co-08: connects to the slow reader's listening port
    client_sock.settimeout(SEND_TIMEOUT_SECONDS)  # => co-08: without this, a full send buffer would block FOREVER, not just slow down
    payload = b"x" * CHUNK  # => co-08: one 64 KiB chunk, reused on every send() call below
 
    sent_before_block = 0  # => co-08: total bytes the writer got out BEFORE flow control first stalled it
    blocked = False  # => co-08: True once a send() call actually times out -- the moment the window is confirmed full
    start = time.monotonic()  # => co-08: wall-clock start, so the eventual stall can be reported with a real elapsed time
    for attempt in range(1, 21):  # => co-08: up to 20 chunks (1.25 MiB) -- far more than a 4 KiB-buffered window can absorb unread
        try:  # => co-08: each send() either succeeds immediately or times out once the window is exhausted
            client_sock.sendall(payload)  # => co-08: sendall() loops internally until every byte is queued -- exactly where blocking shows up
            sent_before_block += CHUNK  # => co-08: this attempt's bytes made it into the socket's own send buffer
        except TimeoutError:  # => co-08: sendall() could not queue more bytes within SEND_TIMEOUT_SECONDS -- THIS is flow control
            blocked = True  # => co-08: the defining observation this example exists to demonstrate
            print(f"send() blocked on attempt {attempt} after {sent_before_block} bytes queued -- receiver's window is full")  # => co-08
            break  # => co-08: no need to keep retrying -- the claim is already demonstrated
    elapsed = time.monotonic() - start  # => co-08: how long the writer spent before flow control kicked in
    client_sock.close()  # => co-08: releases this connection's resources on the writer side -- also unblocks the slow reader's drain
 
    reader_thread.join()  # => co-08: waits for the reader thread to finish draining and record its tally
    server_sock.close()  # => co-08: releases the listening socket
 
    print(f"writer sent {sent_before_block} bytes before blocking (elapsed {elapsed:.2f}s)")  # => co-08: the writer-side summary
    print(f"reader eventually drained {received[0]} bytes total")  # => co-08: the receiver-side summary, once it finally read
    assert blocked, "a 4 KiB receive buffer with a 2s-delayed reader must eventually block a 64 KiB-chunk sender"  # => co-08
    assert sent_before_block > 0, "at least the first chunk must have been queued before any blocking occurred"  # => co-08
    print("Flow control demonstrably slowed/blocked the fast writer: True")  # => co-08: reached only if both asserts passed
    # => co-08: this file is self-verifying: if it exits 0, every assert above passed and the demonstrated claim held

send() blocked on attempt 11 after 655360 bytes queued -- receiver's window is full
writer sent 655360 bytes before blocking (elapsed 1.00s)
reader eventually drained 686672 bytes total
Flow control demonstrably slowed/blocked the fast writer: True

# ex-20: net.ipv4.tcp_congestion_control reports which congestion-control
# algorithm the kernel applies to new TCP connections by default (co-09)
sysctl net.ipv4.tcp_congestion_control

net.ipv4.tcp_congestion_control = cubic

# learning/code/ex-23-tcp-nodelay-socket-option/tcp_nodelay_socket_option.py
"""Example 23: TCP_NODELAY -- Measuring the Nagle/Delayed-ACK Stall."""  # => co-10, co-11: this file's own restated purpose, doubling as its module __doc__
 
from __future__ import annotations  # => DD-39 hygiene: postpones type-annotation evaluation, keeping this file interpreter-version-agnostic
 
import socket  # => co-11: TCP_NODELAY (co-11) is a raw socket option -- only visible below the application layer
import statistics  # => co-11: mean() over several trials, so one lucky/unlucky run doesn't skew the reported comparison
import threading  # => co-10: runs the server concurrently with the client on one localhost connection
import time  # => co-10: monotonic() timestamps around each round trip -- what actually reveals Nagle's stall
 
HOST = "127.0.0.1"  # => co-10: loopback -- the kernel's REAL TCP stack still applies Nagle/delayed-ACK here
ITERATIONS = 20  # => co-10: enough round trips for statistics.mean() to smooth out any single-trial noise
 
 
def server(server_sock: socket.socket, iterations: int) -> None:  # => co-10: waits for the FULL 2-byte message before replying
    """Accept one connection; for each iteration, wait for 2 bytes, then reply with 1 ack byte."""  # => co-10: documents server's contract -- no runtime output, just sets its __doc__
    conn, _ = server_sock.accept()  # => co-10: blocks here until the client below connects
    for _ in range(iterations):  # => co-10: one accumulate-then-reply cycle per round trip
        received = b""  # => co-10: accumulates bytes across possibly-separate recv() calls
        while len(received) < 2:  # => co-10: keep reading until BOTH of the client's split writes have arrived
            received += conn.recv(2 - len(received))  # => co-10: never over-reads past this iteration's 2-byte message
        conn.sendall(b"K")  # => co-10: only NOW does the server reply -- nothing to piggyback an early ACK on before this
    conn.close()  # => co-10: releases this connection's resources on the server side
 
 
def measure_round_trips(nodelay: bool, iterations: int) -> list[float]:  # => co-11: runs one full trial, Nagle on or off
    """Run `iterations` split-write round trips with TCP_NODELAY either set or left at its default (Nagle-enabled)."""  # => co-11: documents measure_round_trips's contract -- no runtime output, just sets its __doc__
    server_sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)  # => co-10: a fresh listening socket per trial -- no state carries over
    server_sock.bind((HOST, 0))  # => co-10: port 0 -- let the OS pick a free ephemeral port
    server_sock.listen(1)  # => co-10: one pending connection is all this single-client demo needs
    port = server_sock.getsockname()[1]  # => co-10: the OS-assigned port, needed by the client below to connect back
    server_thread = threading.Thread(target=server, args=(server_sock, iterations))  # => co-10: runs server() concurrently
    server_thread.start()  # => co-10: starts accepting in the background
 
    client_sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)  # => co-11: the CLIENT side -- the socket TCP_NODELAY is set on
    if nodelay:  # => co-11: the ONLY difference between the two trials this function is called with
        client_sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)  # => co-11: disables Nagle -- flush every write immediately
    client_sock.connect((HOST, port))  # => co-11: connects to the server's listening port
 
    latencies_ms: list[float] = []  # => co-10: one measured round-trip time per iteration, in milliseconds
    for _ in range(iterations):  # => co-10: repeat the split-write round trip ITERATIONS times
        start = time.monotonic()  # => co-10: timestamp taken right before the first of the two split writes
        client_sock.send(b"H")  # => co-10: FIRST small write -- with Nagle enabled, this segment goes out immediately (no data in flight yet)
        client_sock.send(b"I")  # => co-10: SECOND small write, sent RIGHT AFTER -- Nagle withholds this one until the first is ACKed
        client_sock.recv(1)  # => co-10: blocks until the server's 1-byte reply arrives -- completing this iteration's round trip
        latencies_ms.append((time.monotonic() - start) * 1000)  # => co-10: elapsed time for this ENTIRE round trip, in ms
    client_sock.close()  # => co-11: releases this connection's resources on the client side
    server_thread.join()  # => co-10: waits for the server thread to finish its iterations loop
    server_sock.close()  # => co-10: releases the listening socket
    return latencies_ms  # => co-10: returns this computed value to the caller
 
 
if __name__ == "__main__":  # => co-11: entry point -- this block runs only when the file executes directly, not on import
    nagle_latencies = measure_round_trips(nodelay=False, iterations=ITERATIONS)  # => co-10: DEFAULT socket -- Nagle enabled
    nodelay_latencies = measure_round_trips(nodelay=True, iterations=ITERATIONS)  # => co-11: TCP_NODELAY set -- Nagle disabled
    nagle_mean = statistics.mean(nagle_latencies)  # => co-10: average round trip WITH Nagle -- expect it inflated by the stall
    nodelay_mean = statistics.mean(nodelay_latencies)  # => co-11: average round trip WITHOUT Nagle -- expect near-zero overhead
    print(f"Nagle (default)   mean round trip = {nagle_mean:.2f} ms  (samples: {[round(x, 1) for x in nagle_latencies[:5]]}...)")  # => co-10
    print(f"TCP_NODELAY       mean round trip = {nodelay_mean:.2f} ms  (samples: {[round(x, 1) for x in nodelay_latencies[:5]]}...)")  # => co-11
    assert nodelay_mean < nagle_mean, "TCP_NODELAY's mean round trip must be lower than Nagle's default mean"  # => co-11: the headline claim
    speedup = nagle_mean / nodelay_mean if nodelay_mean > 0 else float("inf")  # => co-10: how many times faster NODELAY was, on average
    print(f"TCP_NODELAY was ~{speedup:.0f}x faster on this split-write round trip: True")  # => co-11: reached only if the assert passed
    # => co-11: this file is self-verifying: if it exits 0, the assert above passed and the demonstrated claim held

Nagle (default)   mean round trip = 41.61 ms  (samples: [0.1, 44.1, 41.7, 44.5, 42.1]...)
TCP_NODELAY       mean round trip = 0.07 ms  (samples: [0.1, 0.1, 0.1, 0.1, 0.1]...)
TCP_NODELAY was ~603x faster on this split-write round trip: True

# learning/code/ex-24-so-reuseaddr-restart/so_reuseaddr_restart.py
"""Example 24: SO_REUSEADDR -- Rebinding a Port Still in TIME-WAIT."""  # => co-11: this file's own restated purpose, doubling as its module __doc__
 
from __future__ import annotations  # => DD-39 hygiene: postpones type-annotation evaluation, keeping this file interpreter-version-agnostic
 
import socket  # => co-11: SO_REUSEADDR is a raw socket option -- set with setsockopt() before bind(), not after
import threading  # => co-07: a real client connection is needed to put the server's port into TIME-WAIT at all
import time  # => co-07: small sleeps sequence the handshake/close so the server closes FIRST, deterministically
 
HOST = "127.0.0.1"  # => co-11: loopback -- the OS's own TIME-WAIT bookkeeping still applies here
 
 
def put_port_into_time_wait(port: int) -> None:  # => co-07: establishes a real connection, then closes the SERVER side first
    """Open a real connection to `port` and close it from the SERVER side -- leaving that port in TIME-WAIT."""  # => co-07: documents put_port_into_time_wait's contract -- no runtime output, just sets its __doc__
    server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)  # => co-07: a temporary listener, only to accept ONE connection
    server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)  # => co-11: needed for THIS setup bind only -- the real test is the rebind below
    server.bind((HOST, port))  # => co-07: binds the exact port this whole example will later try to rebind
    server.listen(1)  # => co-07: ready to accept the client thread's connection below
 
    def connect_and_close() -> None:  # => co-07: the CLIENT side -- connects, waits, then closes AFTER the server does
        time.sleep(0.1)  # => co-07: gives the server's accept() below time to be waiting first
        client = socket.socket(socket.AF_INET, socket.SOCK_STREAM)  # => co-07: a plain client socket, no special options needed
        client.connect((HOST, port))  # => co-07: a REAL three-way handshake -- co-07's TCP connection setup, exercised here
        time.sleep(0.3)  # => co-07: stays open until well after the server has closed its own side (see below)
        client.close()  # => co-07: the client closes LAST -- irrelevant to which side lands in TIME-WAIT
 
    client_thread = threading.Thread(target=connect_and_close)  # => co-07: runs the client concurrently with the server's accept()
    client_thread.start()  # => co-07: starts the client's connect/sleep/close sequence in the background
    conn, _ = server.accept()  # => co-07: blocks until the client thread's connect() above completes the handshake
    time.sleep(0.05)  # => co-07: a brief pause so the connection is genuinely established before this side closes it
    conn.close()  # => co-11: THE SERVER closes its side FIRST -- whichever side sends the first FIN lands in TIME-WAIT
    client_thread.join()  # => co-07: waits for the client thread's own (later) close to finish
    server.close()  # => co-07: releases the listening socket -- the PORT itself is now the one left in TIME-WAIT
 
 
if __name__ == "__main__":  # => co-11: entry point -- this block runs only when the file executes directly, not on import
    probe = socket.socket(socket.AF_INET, socket.SOCK_STREAM)  # => co-11: a throwaway socket -- used only to claim a free ephemeral port
    probe.bind((HOST, 0))  # => co-11: port 0 -- let the OS pick a free port, avoiding a hardcoded, possibly-taken one
    port = probe.getsockname()[1]  # => co-11: remember the OS-assigned port -- every bind below targets this SAME port
    probe.close()  # => co-11: releases the throwaway socket immediately
 
    put_port_into_time_wait(port)  # => co-07: leaves `port` in a genuine TIME-WAIT state -- not simulated, actually triggered
    print(f"port {port} closed server-side first -- now lingering in TIME-WAIT")  # => co-11: confirms the setup step completed
 
    no_reuseaddr_server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)  # => co-11: a fresh socket, SO_REUSEADDR left at its OS default
    try:  # => co-11: WITHOUT SO_REUSEADDR, binding to a TIME-WAIT port is expected to fail
        no_reuseaddr_server.bind((HOST, port))  # => co-11: attempts to bind the SAME port that's still in TIME-WAIT
        print("bind WITHOUT SO_REUSEADDR: unexpectedly succeeded")  # => co-11: would only print if TIME-WAIT had already expired
        no_reuseaddr_server.close()  # => co-11: releases the socket in this unexpected-success branch
        without_reuseaddr_failed = False  # => co-11: records that no failure occurred, for the final assert below
    except OSError as exc:  # => co-11: "Address already in use" surfaces as an OSError -- this IS the expected outcome
        print(f"bind WITHOUT SO_REUSEADDR: failed as expected -- {exc}")  # => co-11: the exact OS error text, captured live
        no_reuseaddr_server.close()  # => co-11: releases the failed socket object
        without_reuseaddr_failed = True  # => co-11: records the expected failure, for the final assert below
 
    with_reuseaddr_server = socket.socket(socket.AF_INET, socket.SOCK_STREAM)  # => co-11: a fresh socket -- SO_REUSEADDR set THIS time
    with_reuseaddr_server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)  # => co-11: THE one line this example demonstrates
    with_reuseaddr_server.bind((HOST, port))  # => co-11: binds the SAME still-in-TIME-WAIT port -- expected to succeed THIS time
    print(f"bind WITH SO_REUSEADDR on port {port}: succeeded immediately, no delay needed")  # => co-11: confirms the fix worked
    with_reuseaddr_server.listen(1)  # => co-11: proves the socket is fully usable, not merely bound
    with_reuseaddr_server.close()  # => co-11: releases the socket, cleaning up after the demonstration
 
    assert without_reuseaddr_failed, "binding a TIME-WAIT port WITHOUT SO_REUSEADDR must fail on this platform"  # => co-11
    print("SO_REUSEADDR let an immediate rebind succeed on a port still in TIME-WAIT: True")  # => co-11: both steps confirmed
    # => co-11: this file is self-verifying: if it exits 0, every assert above passed and the demonstrated claim held

port 56553 closed server-side first -- now lingering in TIME-WAIT
bind WITHOUT SO_REUSEADDR: failed as expected -- [Errno 48] Address already in use
bind WITH SO_REUSEADDR on port 56553: succeeded immediately, no delay needed
SO_REUSEADDR let an immediate rebind succeed on a port still in TIME-WAIT: True

# learning/code/ex-25-nonblocking-socket-select/nonblocking_socket_select.py
"""Example 25: Nonblocking Sockets -- setblocking(False) Polled with select.select."""  # => co-11: this file's own restated purpose, doubling as its module __doc__
 
from __future__ import annotations  # => DD-39 hygiene: postpones type-annotation evaluation, keeping this file interpreter-version-agnostic
 
import select  # => co-11: select.select() is the classic readiness-polling primitive this example demonstrates
import socket  # => co-11: setblocking(False) is a raw socket mode -- changes behavior, not the protocol on the wire
import threading  # => co-11: a delayed writer, run concurrently, is what makes "not ready yet" observable at all
import time  # => co-11: the delay itself -- long enough that an immediate (blocking) read would have nothing to return
 
HOST = "127.0.0.1"  # => co-11: loopback -- nonblocking mode and select() both work identically here as on any TCP socket
WRITE_DELAY_SECONDS = 0.3  # => co-11: how long the writer waits before sending anything at all
 
 
def delayed_writer(port: int) -> None:  # => co-11: connects immediately, but sends data only AFTER a deliberate delay
    """Connect immediately, then send one message only after a deliberate delay."""  # => co-11: documents delayed_writer's contract -- no runtime output, just sets its __doc__
    time.sleep(0.05)  # => co-11: a small head start so the reader below is already polling before this connects
    client = socket.socket(socket.AF_INET, socket.SOCK_STREAM)  # => co-11: an ordinary BLOCKING client socket -- only the reader is nonblocking here
    client.connect((HOST, port))  # => co-11: connects right away -- the CONNECTION exists well before any DATA does
    time.sleep(WRITE_DELAY_SECONDS)  # => co-11: THE deliberate gap -- during this window, a blocking recv() would just hang
    client.sendall(b"finally ready")  # => co-11: only now does data actually arrive for the reader to observe
    client.close()  # => co-11: releases this connection's resources on the writer side
 
 
if __name__ == "__main__":  # => co-11: entry point -- this block runs only when the file executes directly, not on import
    server_sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)  # => co-11: the listening socket the nonblocking reader will accept on
    server_sock.bind((HOST, 0))  # => co-11: port 0 -- let the OS pick a free ephemeral port
    server_sock.listen(1)  # => co-11: one pending connection is all this single-client demo needs
    port = server_sock.getsockname()[1]  # => co-11: the OS-assigned port, needed by the delayed writer thread to connect back
 
    writer_thread = threading.Thread(target=delayed_writer, args=(port,))  # => co-11: runs delayed_writer() concurrently
    writer_thread.start()  # => co-11: starts the connect-then-delay-then-send sequence in the background
 
    conn, _ = server_sock.accept()  # => co-11: this accept() is still BLOCKING -- only the data-read path below is nonblocking
    conn.setblocking(False)  # => co-11: THE line this example is about -- recv() now raises instead of blocking when no data is ready
 
    poll_count = 0  # => co-11: how many times select() reported "not ready yet" before data finally arrived
    data = b""  # => co-11: accumulates the eventually-received bytes
    start = time.monotonic()  # => co-11: wall-clock start, to report how long the polling loop actually ran
    while not data:  # => co-11: keep polling until SOMETHING has been read
        readable, _, _ = select.select([conn], [], [], 0.05)  # => co-11: waits UP TO 0.05s for `conn` to become readable, then returns
        if conn in readable:  # => co-11: select() says data (or EOF) is now available -- safe to recv() without blocking
            data = conn.recv(1024)  # => co-11: nonblocking recv() -- guaranteed not to block, since select() just confirmed readiness
        else:  # => co-11: select()'s timeout elapsed with nothing ready -- exactly the "would have blocked" case
            poll_count += 1  # => co-11: counts this as one confirmed "not ready yet" observation
    elapsed = time.monotonic() - start  # => co-11: total time spent polling before data finally arrived
 
    print(f"polled {poll_count} times before data was ready (elapsed {elapsed:.2f}s)")  # => co-11: the polling-loop summary
    print(f"received: {data!r}")  # => co-11: the eventually-received payload, once select() confirmed readiness
    conn.close()  # => co-11: releases this connection's resources on the reader side
    server_sock.close()  # => co-11: releases the listening socket
    writer_thread.join()  # => co-11: waits for the writer thread to finish its connect/delay/send sequence
 
    assert poll_count >= 1, "select() must have reported 'not ready' at least once before data arrived"  # => co-11
    assert data == b"finally ready", "the eventually-received payload must match exactly what the writer sent"  # => co-11
    print("select() correctly polled a nonblocking socket instead of hanging on an unready read: True")  # => co-11
    # => co-11: this file is self-verifying: if it exits 0, every assert above passed and the demonstrated claim held

polled 5 times before data was ready (elapsed 0.31s)
received: b'finally ready'
select() correctly polled a nonblocking socket instead of hanging on an unready read: True

# ex-26: +trace walks the FULL iterative resolution path -- root nameservers,
# then the .com TLD nameservers, then example.com's own authoritative
# nameservers -- printing one "Received ... bytes from ..." line per hop (co-12)
dig +trace example.com

; <<>> DiG 9.10.6 <<>> +trace example.com
;; global options: +cmd
;; Received 17 bytes from 100.100.100.100#53(100.100.100.100) in 8 ms

# ex-27: the SAME query, issued twice a few seconds apart -- the ANSWER
# section's TTL column must be strictly lower on the second query, proving
# the resolver served the second answer from its own cache instead of
# re-asking example.com's authoritative servers (co-12)
dig example.com A
sleep 2
dig example.com A

=== first query ===
 
; <<>> DiG 9.10.6 <<>> example.com A
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 28721
;; flags: qr rd; QUERY: 1, ANSWER: 2, AUTHORITY: 0, ADDITIONAL: 1
;; WARNING: recursion requested but not available
 
;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 4095
;; QUESTION SECTION:
;example.com.   IN A
 
;; ANSWER SECTION:
example.com.  150 IN A 104.20.23.154
example.com.  150 IN A 172.66.147.243
 
;; Query time: 2 msec
;; SERVER: 100.100.100.100#53(100.100.100.100)
;; WHEN: Sat Jul 18 08:17:17 WIB 2026
;; MSG SIZE  rcvd: 72
 
=== second query (~2s later) ===
 
; <<>> DiG 9.10.6 <<>> example.com A
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 63178
;; flags: qr rd; QUERY: 1, ANSWER: 2, AUTHORITY: 0, ADDITIONAL: 1
;; WARNING: recursion requested but not available
 
;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 4095
;; QUESTION SECTION:
;example.com.   IN A
 
;; ANSWER SECTION:
example.com.  148 IN A 172.66.147.243
example.com.  148 IN A 104.20.23.154
 
;; Query time: 2 msec
;; SERVER: 100.100.100.100#53(100.100.100.100)
;; WHEN: Sat Jul 18 08:17:19 WIB 2026
;; MSG SIZE  rcvd: 72

# ex-28: +dnssec asks the resolver to return signature data alongside the
# answer -- an RRSIG record proves the ANSWER section was validated.
#
# This sandbox's default resolver (100.100.100.100, an internal recursive
# resolver) answers with "recursion requested but not available" and omits
# the RRSIG for this particular query, even though the OPT PSEUDOSECTION
# shows "do" (DNSSEC OK) was honored. Querying a public DNSSEC-validating
# resolver directly (@8.8.8.8) gets a genuine signed answer -- example.com
# IS DNSSEC-signed, confirmed live below, not a reconstruction.
dig +dnssec example.com A @8.8.8.8

; <<>> DiG 9.10.6 <<>> +dnssec example.com A @8.8.8.8
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 19597
;; flags: qr rd ra ad; QUERY: 1, ANSWER: 3, AUTHORITY: 0, ADDITIONAL: 1
 
;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags: do; udp: 4096
;; QUESTION SECTION:
;example.com.   IN A
 
;; ANSWER SECTION:
example.com.  300 IN A 172.66.147.243
example.com.  300 IN A 104.20.23.154
example.com.  300 IN RRSIG A 13 2 300 20260719021719 20260717001719 34505 example.com. 40EbrUaIDZK7NEHnxpsSlSuVOWgjo8v218u5GaJQ1m/ArVvvl+/cpTPm 8b2eXZzZ/hXf1F6UYNyYEj8NYaXqjw==
 
;; Query time: 92 msec
;; SERVER: 8.8.8.8#53(8.8.8.8)
;; WHEN: Sat Jul 18 08:17:19 WIB 2026
;; MSG SIZE  rcvd: 179

# ex-30: this reuses Example 1's exact command -- same curl -v transcript --
# examining the "* SSL connection using TLSv1.3 ..." line instead of the
# DNS/TCP/HTTP stages Example 1 focused on (co-14)
curl -s -v --http1.1 https://example.com

* ALPN: curl offers http/1.1
* (304) (OUT), TLS handshake, Client hello (1):
} [313 bytes data]
*  CAfile: /etc/ssl/cert.pem
*  CApath: none
* (304) (IN), TLS handshake, Server hello (2):
{ [122 bytes data]
* (304) (IN), TLS handshake, Unknown (8):
{ [25 bytes data]
* (304) (IN), TLS handshake, Certificate (11):
{ [3687 bytes data]
* (304) (IN), TLS handshake, CERT verify (15):
{ [80 bytes data]
* (304) (IN), TLS handshake, Finished (20):
{ [36 bytes data]
* (304) (OUT), TLS handshake, Finished (20):
} [36 bytes data]
* SSL connection using TLSv1.3 / AEAD-CHACHA20-POLY1305-SHA256 / [blank] / UNDEF
* ALPN: server accepted http/1.1

# ex-33: --http2 forces curl's HTTP/2 code path even on a host it would
# otherwise negotiate down from -- the [HTTP/2] stream-negotiation lines
# and the space-suffixed "HTTP/2 200" status line are curl's own frame
# -level indicators that the exchange really ran over HTTP/2 (co-15)
curl -s -v --http2 https://example.com

* Host example.com:443 was resolved.
* IPv6: 2606:4700:10::6814:179a, 2606:4700:10::ac42:93f3
* IPv4: 172.66.147.243, 104.20.23.154
*   Trying 172.66.147.243:443...
* Connected to example.com (172.66.147.243) port 443
* ALPN: curl offers h2,http/1.1
* (304) (OUT), TLS handshake, Client hello (1):
} [316 bytes data]
*  CAfile: /etc/ssl/cert.pem
*  CApath: none
* (304) (IN), TLS handshake, Server hello (2):
{ [122 bytes data]
* (304) (IN), TLS handshake, Unknown (8):
{ [19 bytes data]
* (304) (IN), TLS handshake, Certificate (11):
{ [3687 bytes data]
* (304) (IN), TLS handshake, CERT verify (15):
{ [78 bytes data]
* (304) (IN), TLS handshake, Finished (20):
{ [36 bytes data]
* (304) (OUT), TLS handshake, Finished (20):
} [36 bytes data]
* SSL connection using TLSv1.3 / AEAD-CHACHA20-POLY1305-SHA256 / [blank] / UNDEF
* ALPN: server accepted h2
* Server certificate:
*  subject: CN=example.com
*  start date: May 31 21:39:12 2026 GMT
*  expire date: Aug 29 21:41:26 2026 GMT
*  subjectAltName: host "example.com" matched cert's "example.com"
*  issuer: C=US; O=SSL Corporation; CN=Cloudflare TLS Issuing ECC CA 3
*  SSL certificate verify ok.
* using HTTP/2
* [HTTP/2] [1] OPENED stream for https://example.com/
* [HTTP/2] [1] [:method: GET]
* [HTTP/2] [1] [:scheme: https]
* [HTTP/2] [1] [:authority: example.com]
* [HTTP/2] [1] [:path: /]
* [HTTP/2] [1] [user-agent: curl/8.7.1]
* [HTTP/2] [1] [accept: */*]
> GET / HTTP/2
> Host: example.com
> User-Agent: curl/8.7.1
> Accept: */*
>
* Request completely sent off
< HTTP/2 200
< date: Sat, 18 Jul 2026 01:16:49 GMT
< content-type: text/html
< server: cloudflare
< last-modified: Wed, 15 Jul 2026 18:48:48 GMT
< allow: GET, HEAD
< accept-ranges: bytes
< age: 1
< cf-cache-status: HIT
< cf-ray: a1cda4aac94c40f6-SIN
<
{ [559 bytes data]
* Connection #0 to host example.com left intact

# ex-35: --parallel fetches all 3 URLs concurrently instead of sequentially
# reusing one keep-alive connection -- this is what makes HTTP/1.1's
# multiple-connections behavior visible instead of hidden by keep-alive reuse.
# Compare the number of "Trying"/"Connected to" lines each protocol prints
# for the SAME 3 requests (co-15).
echo "=== HTTP/1.1, 3 resources, --parallel ==="
curl -s -v --http1.1 --parallel --parallel-max 3 \
  https://example.com/a https://example.com/b https://example.com/c \
  2>&1 >/dev/null | grep -iE "Trying|Connected to|^< HTTP"
 
echo
echo "=== HTTP/2, 3 resources, --parallel ==="
curl -s -v --http2 --parallel --parallel-max 3 \
  https://example.com/a https://example.com/b https://example.com/c \
  2>&1 >/dev/null | grep -iE "Trying|Connected to|using HTTP|^< HTTP"

=== HTTP/1.1, 3 resources, --parallel ===
*   Trying 104.20.23.154:443...
*   Trying 104.20.23.154:443...
*   Trying 104.20.23.154:443...
* Connected to example.com (104.20.23.154) port 443
* Connected to example.com (104.20.23.154) port 443
* Connected to example.com (104.20.23.154) port 443
< HTTP/1.1 404 Not Found
< HTTP/1.1 404 Not Found
< HTTP/1.1 404 Not Found
 
=== HTTP/2, 3 resources, --parallel ===
*   Trying 172.66.147.243:443...
* Connected to example.com (172.66.147.243) port 443
* using HTTP/2
< HTTP/2 404
< HTTP/2 404
< HTTP/2 404

# ex-36: --http3 forces QUIC and requires curl to have been built against an
# HTTP/3-capable backend (ngtcp2+nghttp3 against a QUIC-capable TLS library,
# or quiche) -- neither is compiled into this sandbox's curl 8.7.1 build
# (macOS system curl, linked against LibreSSL via SecureTransport), so this
# attempt genuinely fails at option-parsing time rather than negotiating
# HTTP/3 (co-16). See the prose below for what a successful negotiation
# would print on a curl build that DOES have HTTP/3 support.
curl --http3 -v https://example.com

curl: option --http3: the installed libcurl version doesn't support this
curl: try 'curl --help' or 'curl --manual' for more information