feat(tcp): receive-buffer Dynamic Right-Sizing (autotune step 4 / R2-R4)

Fourth phase of the Tier-3 buffer auto-tuning plan
(docs/refactor/tcp_buffer_autotuning.md §4 R2-R4 / §10 step 4): grow the
advertised receive window toward the bandwidth-delay product, mirroring
Linux tcp_rcv_space_adjust. Builds on the R1 receiver-RTT estimator.

R2 (state):
- New RcvSpaceState (state/tcp__state__rcv_space.py): space (high-water
  per-RTT copied bytes) + copied_anchor + time_ms — the measurement
  window. Seeded self._rcv_space with space = initial rcv_wnd_max in
  TcpSession.__init__, plus self._rcv_copied_total bumped by byte_count
  in receive() so the policy can compute per-RTT throughput.

R3 + R4 (trigger + policy):
- TcpSession._maybe_adjust_rcv_space() runs from receive() after the
  drain (the app-thread analogue of Linux calling it from tcp_recvmsg).
  Once per receiver-RTT, when copied exceeds the last measurement, it
  computes rcvwin = 2*copied + 16*advmss plus a sender-rate headroom
  term, clamps at min(tcp.rmem.max, 0xFFFF << rcv_wsc) — the R0 WSCALE
  ceiling so the grown window stays expressible under the negotiated
  shift — and calls the existing grow-only grow_rcv_wnd_max. per_mss is
  the bare advmss (no tcp_adv_win_scale overhead — the locked Tier-1
  deviation), so window == buffer size.
- No-op until the receiver RTT exists, before one RTT elapsed, when
  tcp.moderate_rcvbuf is off, or when SO_RCVBUF is set (SOCK_RCVBUF_LOCK
  — makes DRS and the A3 mid-connection resize mutually-exclusive
  writers of rcv_wnd_max, preserving the single-writer invariant).

DRS is now functionally complete. It stays inert on the common path
until per-RTT throughput exceeds the start window; no behaviour change
for connections that never fill it or that pin SO_RCVBUF.

Tests-first: test__tcp__session__drs.py (7 cases — grow toward BDP,
cadence gate, no-RTT skip, SO_RCVBUF lock, moderate_rcvbuf off,
rmem.max clamp, receive()-path trigger). RED pre-impl: AttributeError
(_rcv_space absent). Two grow tests initially failed because the default
handshake negotiates no WSCALE, so the R0 ceiling (0xFFFF << 0) correctly
capped at 65535 — the RED step surfaced that the grow tests must
negotiate WSCALE; fixed by establishing with peer_wscale=7. Plan §4 /
§10 step 4 marked done.

Reference: RFC 9293 §3.8.6 (receive window management).
Reference: RFC 7323 §2 (window scale bounds the grown window).
Reference: Linux tcp_rcv_space_adjust / net.ipv4.tcp_moderate_rcvbuf.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: ccie18643

docs/refactor/tcp_buffer_autotuning.md

@@ -209,6 +209,23 @@ for a pure receiver.
   timestamps-gated for the first pass (Linux DRS is materially weaker
   without timestamps too).
 
+**R2 + R3 + R4 are DONE** (autotune step 4). `RcvSpaceState`
+(`state/tcp__state__rcv_space.py`: `space` / `copied_anchor` / `time_ms`)
++ `self._rcv_copied_total` bumped in `receive()`; `_rcv_space.space`
+seeded from `rcv_wnd_max` at construction.
+`TcpSession._maybe_adjust_rcv_space()` runs from `receive()` after the
+drain: gates on `_rcv_rtt.rtt_ms` present and one RTT elapsed, computes
+`2*copied + 16*advmss` + the sender-rate term, clamps at
+`min(tcp.rmem.max, 0xFFFF << rcv_wsc)` (the R0 WSCALE ceiling), and calls
+the grow-only `grow_rcv_wnd_max`; a no-op under
+`_so_rcvbuf is not None` (SOCK_RCVBUF_LOCK) or `tcp.moderate_rcvbuf == 0`.
+Tests: `test__tcp__session__drs.py` (grow, cadence gate, no-RTT skip,
+SO_RCVBUF lock, moderate_rcvbuf off, rmem.max clamp, receive()-path
+trigger). The grow tests establish with WSCALE negotiated — without a
+non-zero `rcv_wsc` the R0 ceiling correctly caps the window at 65535.
+
+Original plan text (R2/R3/R4):
+
 ### R2 — the `RcvSpaceState` struct (small)
 
 - New `state/tcp__state__rcv_space.py` `@dataclass(slots=True)`
@@ -513,7 +530,13 @@ CLAUDE.md "Linux as tiebreaker" precedence.
    `tcp__session__ack.py` phase-5 TSecr hook; timestamps-gated. Tests:
    `test__tcp__state__rcv_rtt.py`, `test__tcp__session__rcv_rtt.py`.
 4. **R2 + R3 + R4** (DRS struct, trigger, grow policy) — the large piece;
-   lands on top of R1.
+   lands on top of R1. **DONE** — `RcvSpaceState` + copied counter +
+   `_maybe_adjust_rcv_space()` fired from `receive()`, driving the
+   grow-only `grow_rcv_wnd_max`, clamped at `tcp.rmem.max` / the WSCALE
+   ceiling, gated on `tcp.moderate_rcvbuf` + `SO_RCVBUF` unset. Tests:
+   `test__tcp__session__drs.py`. **DRS is functionally complete** (still
+   inert on the common path until step 5 raises throughput enough to
+   grow, but it fires whenever per-RTT throughput exceeds the window).
 5. **The small-default switch** (§2 / §7) — flip the unset `SO_SNDBUF`
    (and optionally `rcv_wnd_max`) default to the Tier-2 `.default`,
    making auto-tuning observable. Behaviour-changing → its own deliberate

packages/pytcp/pytcp/protocols/tcp/session/tcp__session.py

@@ -63,6 +63,7 @@
 from pytcp.protocols.tcp.state.tcp__state__persist import PersistState
 from pytcp.protocols.tcp.state.tcp__state__rack_tlp import RackTlpState
 from pytcp.protocols.tcp.state.tcp__state__rcv_rtt import RcvRttState
+from pytcp.protocols.tcp.state.tcp__state__rcv_space import RcvSpaceState
 from pytcp.protocols.tcp.state.tcp__state__recv_seq import RecvSeqState
 from pytcp.protocols.tcp.state.tcp__state__rtt_sample import RttSampleState
 from pytcp.protocols.tcp.state.tcp__state__send_seq import SendSeqState
@@ -344,6 +345,13 @@ def __init__(
         # cadence). Fed from the inbound TSecr echo, so it produces an
         # RTT even on a pure receiver. See 'state/tcp__state__rcv_rtt.py'.
         self._rcv_rtt: RcvRttState = RcvRttState()
+        # Tier-3 Track R DRS measurement window. 'space' seeds from the
+        # initial 'rcv_wnd_max' (set above from SO_RCVBUF) so the first
+        # grow fires only once per-RTT throughput exceeds the start
+        # window. '_rcv_copied_total' is the cumulative count of bytes
+        # the application has drained via 'receive()'.
+        self._rcv_space: RcvSpaceState = RcvSpaceState(space=self._win.rcv_wnd_max)
+        self._rcv_copied_total: int = 0
         self._retransmit_count: int = 0
         # RFC 6298 §5.7 second-clause SYN-retransmit counter.
         # Decoupled from '_retransmit_count' (which
@@ -1304,6 +1312,9 @@ def receive(self, *, byte_count: int | None = None, timeout: float | None = None
 
             rx_buffer = self._rx_buffer[:byte_count]
             del self._rx_buffer[:byte_count]
+            # Tier-3 Track R: count bytes the application copies out so
+            # the DRS measurement can compute per-RTT throughput.
+            self._rcv_copied_total += byte_count
 
             # Clear the event only when the buffer is fully drained
             # AND the remote end is still open. When the remote
@@ -1325,8 +1336,61 @@ def receive(self, *, byte_count: int | None = None, timeout: float | None = None
                 # half (matches BSD select-on-read-EOF semantics).
                 self._socket._drain_readable()
 
+        # Tier-3 Track R DRS: the app just drained the buffer, so run
+        # the once-per-RTT receive-window adjust (Linux calls
+        # 'tcp_rcv_space_adjust' from 'tcp_recvmsg'). Outside the
+        # rx-buffer lock — it touches only app-thread DRS state and the
+        # lockless grow-only 'grow_rcv_wnd_max'.
+        self._maybe_adjust_rcv_space()
+
         return bytes(rx_buffer)
 
+    def _maybe_adjust_rcv_space(self) -> None:
+        """
+        Receive-buffer Dynamic Right-Sizing (Tier-3 Track R, mirroring
+        Linux 'tcp_rcv_space_adjust'). At most once per receiver-RTT,
+        when the application has drained more than the previously
+        measured per-RTT bytes ('space'), grow 'rcv_wnd_max' toward the
+        estimated bandwidth-delay product:
+
+            rcvwin = 2 * copied + 16 * advmss          # BDP + loss slack
+            rcvwin += 2 * rcvwin * (copied - space) // space   # sender-rate headroom
+            target = min(rcvwin, tcp.rmem.max, 0xFFFF << rcv_wsc)
+
+        'per_mss' is the bare advertised MSS (no skb-truesize / no
+        'tcp_adv_win_scale' overhead — the same deviation locked for
+        Tier-1), so the window value maps directly to the buffer size.
+        The WSCALE-ceiling clamp keeps the grown window expressible under
+        the shift negotiated at handshake (RFC 7323).
+
+        A no-op until the receiver RTT estimate exists, before one RTT
+        has elapsed since the last measurement, when 'tcp.moderate_rcvbuf'
+        is off, or when SO_RCVBUF is set (SOCK_RCVBUF_LOCK). Runs on the
+        application thread; the actuator 'grow_rcv_wnd_max' is grow-only
+        and lockless.
+        """
+
+        rtt_ms = self._rcv_rtt.rtt_ms
+        if rtt_ms is None:
+            return
+        now_ms = stack.timer.now_ms
+        if now_ms - self._rcv_space.time_ms < rtt_ms:
+            return
+
+        copied = self._rcv_copied_total - self._rcv_space.copied_anchor
+        if copied > self._rcv_space.space:
+            if self._socket._so_rcvbuf is None and tcp__constants.TCP__MODERATE_RCVBUF:
+                advmss = self._win.rcv_mss
+                rcvwin = 2 * copied + 16 * advmss
+                rcvwin += 2 * (rcvwin * (copied - self._rcv_space.space) // self._rcv_space.space)
+                target = min(rcvwin, tcp__constants.TCP__RMEM__MAX, 0xFFFF << self._win.rcv_wsc)
+                if target > self._win.rcv_wnd_max:
+                    self.grow_rcv_wnd_max(target)
+            self._rcv_space.space = copied
+
+        self._rcv_space.copied_anchor = self._rcv_copied_total
+        self._rcv_space.time_ms = now_ms
+
     def close(self) -> None:
         """
         The 'CLOSE' syscall.

packages/pytcp/pytcp/protocols/tcp/state/tcp__state__rcv_space.py

@@ -0,0 +1,63 @@
+################################################################################
+##                                                                            ##
+##   PyTCP - Python TCP/IP stack                                              ##
+##   Copyright (C) 2020-present Sebastian Majewski                            ##
+##                                                                            ##
+##   This program is free software: you can redistribute it and/or modify     ##
+##   it under the terms of the GNU General Public License as published by     ##
+##   the Free Software Foundation, either version 3 of the License, or        ##
+##   (at your option) any later version.                                      ##
+##                                                                            ##
+##   This program is distributed in the hope that it will be useful,          ##
+##   but WITHOUT ANY WARRANTY; without even the implied warranty of           ##
+##   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the             ##
+##   GNU General Public License for more details.                             ##
+##                                                                            ##
+##   You should have received a copy of the GNU General Public License        ##
+##   along with this program. If not, see <https://www.gnu.org/licenses/>.    ##
+##                                                                            ##
+##   Author's email: ccie18643@gmail.com                                      ##
+##   Github repository: https://github.com/ccie18643/PyTCP                    ##
+##                                                                            ##
+################################################################################
+
+
+"""
+This module contains the per-session receive-buffer Dynamic Right-Sizing
+(DRS) measurement state — the Tier-3 Track R analogue of Linux's
+'tcp_sock.rcvq_space'. It records the high-water-mark of bytes the
+application copied out in one receiver-RTT ('space') plus the anchor the
+next measurement is taken from ('copied_anchor' / 'time_ms'), so the
+grow policy can compare the current per-RTT throughput against the last.
+
+pytcp/protocols/tcp/state/tcp__state__rcv_space.py
+
+ver 3.0.8
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass(slots=True)
+class RcvSpaceState:
+    """
+    Per-session DRS measurement window. Owned by 'TcpSession' and
+    touched only on the application thread (inside 'receive()'), so it
+    needs no lock. 'space' is seeded from the initial 'rcv_wnd_max' so
+    the first grow fires only once per-RTT throughput exceeds the
+    starting window.
+    """
+
+    # High-water-mark of bytes copied to the application in a single
+    # receiver-RTT. The grow policy fires when the latest per-RTT
+    # 'copied' exceeds this; then 'space' rises to that 'copied'.
+    space: int = 0
+
+    # Value of the session's cumulative copied-bytes counter at the
+    # last measurement — 'copied = total - copied_anchor' is the bytes
+    # drained in the window just ending.
+    copied_anchor: int = 0
+
+    # 'stack.timer.now_ms' at the last measurement; the next adjust is
+    # gated until one receiver-RTT has elapsed past this.
+    time_ms: int = 0