feat(tcp): send-buffer auto-tuning grows with cwnd (autotune step 2 / Track S)

Second phase of the Tier-3 buffer auto-tuning plan
(docs/refactor/tcp_buffer_autotuning.md §5 / §10 step 2): grow the send
buffer with the congestion window, mirroring Linux tcp_sndbuf_expand.

S1 (socket base, runtime/socket/__init__.py):
- New grow-only '_sndbuf_auto' bound + '_grow_sndbuf_auto(target)' named
  mutator (single-writer, no lock — only the owning session's RX/ACK
  thread writes it).
- '_effective_sndbuf()' now returns the explicit SO_SNDBUF when set
  (SOCK_SNDBUF_LOCK — pin wins), else max(static default, _sndbuf_auto).
  Datagram sockets keep _sndbuf_auto == 0, so their bound is unchanged.

S2 (session):
- 'TcpSession._maybe_expand_sndbuf()' computes 2 * max(RFC 6928 IW,
  cwnd) with per_mss == snd_mss (the locked no-2x / no-overhead Tier-1
  deviation; the Linux reordering+1 term is IW-dominated and omitted),
  clamps at the live 'tcp.wmem.max' (qualified-module read), and calls
  _grow_sndbuf_auto. No-op under SOCK_SNDBUF_LOCK or before MSS is known.
- Triggered from the phase-5 ACK path (tcp__session__ack.py) right after
  _wake_sndbuf_waiters(); cwnd is already grown in phase 1, so the bound
  tracks the current window. The Tier-1 wake admits any blocked writer
  against the widened bound with no new gate wiring.

The auto bound only becomes the *effective* value once it exceeds the
208 KiB static default (cwnd whose 2x tops it); it is fully observable
once step 5 lands the small default. No behaviour change for a socket
with an explicit SO_SNDBUF or for datagram sockets.

Tests-first: test__tcp__session__sndbuf_autotune.py (5 cases — ACK grows
the bound, _effective_sndbuf reflects it, tcp.wmem.max clamp, grow-only,
explicit SO_SNDBUF freezes it). RED pre-impl: AttributeError
(_maybe_expand_sndbuf / _sndbuf_auto absent) → green post-impl. The lock
test was corrected from an initial wrong assumption (auto-tuning
correctly fires on the handshake ACK, so the lock freezes an
already-grown bound, not a zero one). Plan §5 / §10 marked done.

Reference: RFC 9293 §3.9 (SEND — send-buffer flow control).
Reference: Linux tcp_sndbuf_expand / net.ipv4.tcp_wmem.

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

Author: ccie18643

docs/refactor/tcp_buffer_autotuning.md

@@ -267,6 +267,15 @@ on ACK processing, when SO_SNDBUF unset and cwnd is growing:
 
 ### S1 — the auto bound + `_effective_sndbuf` integration (small)
 
+**DONE.** `_sndbuf_auto: int` on the socket base
+(`runtime/socket/__init__.py`, init 0), grown grow-only via the named
+mutator `_grow_sndbuf_auto(target)` (single-writer, no lock).
+`_effective_sndbuf()` returns `_so_sndbuf` when set, else
+`max(SOCKET__SO_SNDBUF__DEFAULT, _sndbuf_auto)` — datagram sockets keep
+`_sndbuf_auto == 0` so their bound is unchanged.
+
+Original plan text:
+
 - Add `_sndbuf_auto: int = 0` on the socket base
   (`runtime/socket/__init__.py`, near `_so_sndbuf`), a grow-only value
   written by the RX/ACK thread and read by the app thread.
@@ -278,6 +287,23 @@ on ACK processing, when SO_SNDBUF unset and cwnd is growing:
 
 ### S2 — the expand policy + trigger (small–medium, the meat)
 
+**DONE.** `TcpSession._maybe_expand_sndbuf()` computes
+`2 * max(INITIAL_WINDOW_FACTOR * snd_mss, cwnd)` (RFC 6928 IW floor,
+`per_mss = snd_mss` per the locked no-overhead deviation, `reordering+1`
+term omitted as IW-dominated), clamps at live `tcp__constants.TCP__WMEM__MAX`
+(qualified-module read = current sysctl value), and calls
+`_grow_sndbuf_auto`; a no-op when `_so_sndbuf is not None`
+(SOCK_SNDBUF_LOCK) or `snd_mss <= 0`. Triggered from
+`tcp__session__ack.py` phase 5, right after `_wake_sndbuf_waiters()` —
+cwnd is already grown in phase 1, so the bound tracks the current window.
+Tests: `test__tcp__session__sndbuf_autotune.py` (ACK grows the bound,
+`_effective_sndbuf` reflects it, `tcp.wmem.max` clamp, grow-only, explicit
+SO_SNDBUF freezes it). Note: auto-tuning correctly fires on the handshake
+ACK too, so a mid-connection `SO_SNDBUF` freezes the *already-grown* bound
+rather than a zero one.
+
+Original plan text:
+
 - New `TcpSession._maybe_expand_sndbuf()`: implement §5's target; write
   `self._socket._sndbuf_auto = max(self._socket._sndbuf_auto,
   min(target, tcp.wmem.max))` when `self._socket._so_sndbuf is None`
@@ -460,7 +486,12 @@ CLAUDE.md "Linux as tiebreaker" precedence.
    consumer yet. Tests: `test__tcp__constants.py`.
 2. **S1 + S2** (send auto-tuning) — smaller track, exercises the sysctl
    clamp and the ACK-path trigger with low risk (grow-only widening of an
-   existing gate).
+   existing gate). **DONE** — `_sndbuf_auto` + `_grow_sndbuf_auto` on the
+   socket, `_effective_sndbuf` widened, `TcpSession._maybe_expand_sndbuf`
+   fired from the phase-5 ACK path. Observable now via `_sndbuf_auto` and
+   (for cwnd whose 2× exceeds the 208 KiB default) `_effective_sndbuf`;
+   fully observable once step 5 lands the small default. Tests:
+   `test__tcp__session__sndbuf_autotune.py`.
 3. **R1** (receiver RTT estimator) — the DRS prerequisite; self-contained,
    unit-testable in isolation.
 4. **R2 + R3 + R4** (DRS struct, trigger, grow policy) — the large piece;

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

@@ -69,7 +69,7 @@
 from pytcp.protocols.tcp.state.tcp__state__timestamps import TimestampsState
 from pytcp.protocols.tcp.state.tcp__state__tx_buffer import TxBufferState
 from pytcp.protocols.tcp.state.tcp__state__window import WindowState
-from pytcp.protocols.tcp.tcp__cwnd import compute_ecn_event_ssthresh
+from pytcp.protocols.tcp.tcp__cwnd import INITIAL_WINDOW_FACTOR, compute_ecn_event_ssthresh
 from pytcp.protocols.tcp.tcp__enums import (
     CcMode,
     ConnError,
@@ -1246,6 +1246,33 @@ def _charge_tx_buffer(self, data: bytes, /) -> int:
                 if not cond.wait(timeout=socket._so_sndtimeo):
                     raise BlockingIOError(errno.EAGAIN, os.strerror(errno.EAGAIN))
 
+    def _maybe_expand_sndbuf(self) -> None:
+        """
+        Grow the auto-tuning send-buffer bound to track the congestion
+        window (Tier-3 Track S, mirroring Linux 'tcp_sndbuf_expand').
+        Called from the inbound-ACK path after cwnd growth: the target
+        is two windows of data — '2 * max(IW, cwnd)' — floored at the
+        RFC 6928 initial window so a small-cwnd connection still queues
+        usefully, and clamped at 'tcp.wmem.max'. 'per_mss' is the bare
+        MSS (no skb-truesize overhead — the same no-2x / no-overhead
+        deviation locked for Tier-1); the Linux 'reordering + 1' term is
+        omitted (dominated by IW = 10 in practice).
+
+        A no-op when the application set SO_SNDBUF explicitly
+        (SOCK_SNDBUF_LOCK disables auto-tuning) or before the MSS is
+        known. The grow-only store lives on the socket; only the RX/ACK
+        thread writes it, so no lock is taken.
+        """
+
+        socket = self._socket
+        if socket._so_sndbuf is not None:
+            return
+        smss = self._win.snd_mss
+        if smss <= 0:
+            return
+        target = 2 * max(INITIAL_WINDOW_FACTOR * smss, self._cc.cwnd)
+        socket._grow_sndbuf_auto(min(target, tcp__constants.TCP__WMEM__MAX))
+
     def receive(self, *, byte_count: int | None = None, timeout: float | None = None) -> bytes:
         """
         The 'RECEIVE' syscall.

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

@@ -745,6 +745,10 @@ def _phase5_consume_segment_and_postprocess(self, packet_rx_md: TcpMetadata) ->
         # '_lock__tx_buffer' (both released here), so it cannot invert
         # the lock order.
         session._socket._wake_sndbuf_waiters()
+        # Linux 'tcp_sndbuf_expand': phase 1 may have grown cwnd, so
+        # grow the auto-tuning send-buffer bound to track it (Tier-3
+        # Track S). No-op when SO_SNDBUF is set (SOCK_SNDBUF_LOCK).
+        session._maybe_expand_sndbuf()
         __debug__ and log(
             "tcp-ss",
             f"[{session}] - Purged TX buffer up to SEQ {session._snd_seq.una}",

packages/pytcp/pytcp/runtime/socket/__init__.py

@@ -599,6 +599,11 @@ class socket(ABC):
     # datagram's TX completes.
     _snd_outstanding: int
     _snd_buf_cond: threading.Condition
+    # TCP send-buffer auto-tuning bound (Tier-3 Track S). Grow-only;
+    # written by the owning TcpSession on the RX/ACK thread, read by the
+    # app thread via '_effective_sndbuf()'. Stays 0 for datagram sockets
+    # (no auto-tuning), so their effective bound is the static default.
+    _sndbuf_auto: int
     _ip_ttl: int | None
     _ip_multicast_ttl: int | None
     _ip_multicast_loop: bool
@@ -673,6 +678,7 @@ def __init__(
         self._so_sndtimeo = None
         self._snd_outstanding = 0
         self._snd_buf_cond = threading.Condition()
+        self._sndbuf_auto = 0
         self._ip_ttl = None
         self._ip_multicast_ttl = None
         # Linux IP_MULTICAST_LOOP defaults on; PyTCP has no local
@@ -1443,14 +1449,29 @@ def _multicast_send_suppressed(self, remote_ip_address: Ip4Address | Ip6Address,
 
     def _effective_sndbuf(self) -> int:
         """
-        Get the SO_SNDBUF send-buffer bound: the value the
-        application set, else the 'SOCKET__SO_SNDBUF__DEFAULT'
-        stand-in for Linux 'net.core.wmem_default'. PyTCP does not
-        apply Linux's 2x doubling of the requested value — the bound
-        is the value as set.
+        Get the SO_SNDBUF send-buffer bound. An explicit application
+        value (SOCK_SNDBUF_LOCK) always wins and pins the bound. When
+        unset, the bound is the larger of the 'SOCKET__SO_SNDBUF__DEFAULT'
+        stand-in (Linux 'net.core.wmem_default') and the TCP
+        auto-tuning bound '_sndbuf_auto' (Tier-3 Track S; 0 for
+        datagram sockets, so their bound is the static default). PyTCP
+        does not apply Linux's 2x doubling of the requested value.
         """
 
-        return self._so_sndbuf if self._so_sndbuf is not None else SOCKET__SO_SNDBUF__DEFAULT
+        if self._so_sndbuf is not None:
+            return self._so_sndbuf
+        return max(SOCKET__SO_SNDBUF__DEFAULT, self._sndbuf_auto)
+
+    def _grow_sndbuf_auto(self, target: int, /) -> None:
+        """
+        Raise the auto-tuning send-buffer bound to 'target', grow-only
+        (a lower target is a no-op). Called by the owning TcpSession's
+        send-buffer expand policy on the RX/ACK thread; the app thread
+        only reads '_sndbuf_auto' via '_effective_sndbuf()', so the
+        single-writer 'max()' needs no lock.
+        """
+
+        self._sndbuf_auto = max(self._sndbuf_auto, target)
 
     def _effective_rcvbuf(self) -> int:
         """

packages/pytcp/pytcp/tests/integration/protocols/tcp/test__tcp__session__sndbuf_autotune.py

@@ -0,0 +1,221 @@
+################################################################################
+##                                                                            ##
+##   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                    ##
+##                                                                            ##
+################################################################################
+
+
+# pylint: disable=protected-access
+# pyright: reportPrivateUsage=false
+
+
+"""
+Integration tests for TCP send-buffer auto-tuning (Tier-3 Track S,
+docs/refactor/tcp_buffer_autotuning.md §5). On ACK processing the session
+grows a grow-only auto send-buffer bound toward '2 * max(IW, cwnd) *
+per_mss', clamped at 'tcp.wmem.max', mirroring Linux 'tcp_sndbuf_expand'.
+An explicit SO_SNDBUF (SOCK_SNDBUF_LOCK) disables auto-tuning. The auto
+bound feeds the Tier-1 SO_SNDBUF gate via '_effective_sndbuf()'.
+
+pytcp/tests/integration/protocols/tcp/test__tcp__session__sndbuf_autotune.py
+
+ver 3.0.8
+"""
+
+from typing import override
+
+from pytcp.protocols.tcp import tcp__constants
+from pytcp.protocols.tcp.session import TcpSession
+from pytcp.protocols.tcp.tcp__cwnd import INITIAL_WINDOW_FACTOR
+from pytcp.runtime.socket import (
+    SO_SNDBUF,
+    SOCKET__SO_SNDBUF__DEFAULT,
+    SOL_SOCKET,
+)
+from pytcp.stack import sysctl as sysctl_module
+from pytcp.tests.lib.tcp_segment_factory import build_tcp4
+from pytcp.tests.lib.tcp_testcase import TcpTestCase
+
+_LOCAL_PORT = 12345
+_REMOTE_PORT = 80
+
+
+class TestTcpSessionSndbufAutotune(TcpTestCase):
+    """
+    The send-buffer auto-tuning grow-policy tests.
+    """
+
+    @override
+    def tearDown(self) -> None:
+        """
+        Restore any sysctl overridden by a clamp test so the mutated
+        'tcp.wmem.max' cannot leak into a sibling test.
+        """
+
+        sysctl_module.reset_to_defaults()
+        super().tearDown()
+
+    def _expected_auto(self, session: TcpSession) -> int:
+        """
+        Compute the expected auto send-buffer bound for the session's
+        current cwnd / snd_mss, clamped at 'tcp.wmem.max' — the policy
+        the implementation must reproduce.
+        """
+
+        iw_floor = INITIAL_WINDOW_FACTOR * session._win.snd_mss
+        target = 2 * max(iw_floor, session._cc.cwnd)
+        return min(target, tcp__constants.TCP__WMEM__MAX)
+
+    def test__sndbuf_autotune__ack_grows_auto_bound(self) -> None:
+        """
+        Ensure processing a cumulative ACK grows the auto send-buffer
+        bound to '2 * max(IW, cwnd) * per_mss' for the current cwnd, so
+        the send buffer tracks the congestion window.
+
+        Reference: RFC 9293 §3.9 (SEND — send-buffer flow control).
+        Reference: Linux tcp_sndbuf_expand (send buffer grows with cwnd).
+        """
+
+        session = self._drive_handshake_to_established(iss=1000, peer_iss=5000)
+        session.send(data=b"A" * 1460)
+        self._advance(ms=1)
+
+        peer_ack = build_tcp4(
+            sport=_REMOTE_PORT,
+            dport=_LOCAL_PORT,
+            seq=5001,
+            ack=1000 + 1 + 1460,
+            flags=("ACK",),
+            win=64240,
+        )
+        self._drive_rx(frame=peer_ack)
+
+        self.assertEqual(
+            session._socket._sndbuf_auto,
+            self._expected_auto(session),
+            msg="The ACK must grow the auto send-buffer bound to 2 * max(IW, cwnd).",
+        )
+        self.assertGreater(
+            session._socket._sndbuf_auto,
+            0,
+            msg="Auto-tuning must have raised the bound above zero.",
+        )
+
+    def test__sndbuf_autotune__effective_reflects_grown_bound(self) -> None:
+        """
+        Ensure '_effective_sndbuf()' returns the auto bound once it
+        exceeds the static default, so the Tier-1 send gate admits the
+        larger queue.
+
+        Reference: RFC 9293 §3.9 (SEND — send-buffer flow control).
+        Reference: Linux socket(7) SO_SNDBUF (auto-tuned buffer size).
+        """
+
+        session = self._drive_handshake_to_established(iss=1000, peer_iss=5000)
+        # A cwnd whose 2x exceeds the 208 KiB static default, so the
+        # grown auto bound becomes the effective value.
+        session._cc.cwnd = 200_000
+        session._maybe_expand_sndbuf()
+
+        expected = self._expected_auto(session)
+        self.assertGreater(
+            expected,
+            SOCKET__SO_SNDBUF__DEFAULT,
+            msg="Setup: the grown bound must exceed the static default to be observable.",
+        )
+        self.assertEqual(
+            session._socket._effective_sndbuf(),
+            expected,
+            msg="'_effective_sndbuf()' must return the grown auto bound.",
+        )
+
+    def test__sndbuf_autotune__clamps_at_wmem_max(self) -> None:
+        """
+        Ensure the grow policy saturates at 'tcp.wmem.max' so a large
+        cwnd cannot push the send buffer past the operator ceiling.
+
+        Reference: RFC 9293 §3.9 (SEND — send-buffer flow control).
+        Reference: Linux net.ipv4.tcp_wmem (max bounds the auto buffer).
+        """
+
+        session = self._drive_handshake_to_established(iss=1000, peer_iss=5000)
+        sysctl_module.set("tcp.wmem.max", 50_000)
+        session._cc.cwnd = 200_000
+        session._maybe_expand_sndbuf()
+
+        self.assertEqual(
+            session._socket._sndbuf_auto,
+            50_000,
+            msg="The auto bound must saturate at 'tcp.wmem.max'.",
+        )
+
+    def test__sndbuf_autotune__grow_only(self) -> None:
+        """
+        Ensure the auto bound never shrinks — a later smaller cwnd
+        leaves the previously-grown bound in place.
+
+        Reference: RFC 9293 §3.9 (SEND — send-buffer flow control).
+        Reference: Linux tcp_sndbuf_expand (send buffer is grow-only).
+        """
+
+        session = self._drive_handshake_to_established(iss=1000, peer_iss=5000)
+        session._cc.cwnd = 200_000
+        session._maybe_expand_sndbuf()
+        grown = session._socket._sndbuf_auto
+
+        # cwnd collapses (e.g. after loss) — the bound must not shrink.
+        session._cc.cwnd = session._win.snd_mss
+        session._maybe_expand_sndbuf()
+
+        self.assertEqual(
+            session._socket._sndbuf_auto,
+            grown,
+            msg="A smaller cwnd must not shrink the auto send-buffer bound.",
+        )
+
+    def test__sndbuf_autotune__explicit_sndbuf_disables_autotune(self) -> None:
+        """
+        Ensure an explicit setsockopt(SO_SNDBUF) pins the send-buffer
+        bound and disables auto-tuning (SOCK_SNDBUF_LOCK), so cwnd
+        growth never moves the effective bound.
+
+        Reference: RFC 9293 §3.9 (SEND — send-buffer flow control).
+        Reference: Linux socket(7) SO_SNDBUF (explicit size disables
+        auto-tuning).
+        """
+
+        session = self._drive_handshake_to_established(iss=1000, peer_iss=5000)
+        # The handshake ACK already ran the expand once, so capture the
+        # current auto bound; the lock must freeze it from here.
+        auto_before = session._socket._sndbuf_auto
+        session._socket.setsockopt(SOL_SOCKET, SO_SNDBUF, 100_000)
+        session._cc.cwnd = 200_000
+        session._maybe_expand_sndbuf()
+
+        self.assertEqual(
+            session._socket._sndbuf_auto,
+            auto_before,
+            msg="Explicit SO_SNDBUF must freeze the auto bound (no further growth).",
+        )
+        self.assertEqual(
+            session._socket._effective_sndbuf(),
+            100_000,
+            msg="An explicit SO_SNDBUF must remain the effective bound across cwnd growth.",
+        )