fix(socket): accept sub-second float SO_RCVTIMEO / SO_SNDTIMEO

PyTCP documents SO_RCVTIMEO / SO_SNDTIMEO as "float seconds", but
setsockopt gated the SOL_SOCKET dispatch on isinstance(value, int)
so a sub-second float was rejected with ENOPROTOOPT, and
getsockopt int()-truncated the stored timeout to whole seconds. A
persistent sub-second timeout was therefore unsettable via the
public API — including the R3 blocking-send SO_SNDTIMEO.

Widen the setsockopt 'value' to int | float | bytes across the
four concrete socket classes and route a float FIRST: a float is
only valid for the SOL_SOCKET float-seconds timeouts, so it goes
straight to _sol_socket_setsockopt (which already does
float(value)) and the int / bytes option handlers below never
receive one (keeping their signatures unchanged). getsockopt now
returns the stored float verbatim (int | float | bytes) instead
of truncating.

Tests-first: TestUdpSocketTimeoutFloat — SO_RCVTIMEO=0.5 /
SO_SNDTIMEO=0.25 round-trip through getsockopt, and an integer
value is still accepted (regression). Verified red (ENOPROTOOPT)
before the widening.

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

Author: ccie18643

docs/refactor/host_refinements_backlog.md

@@ -311,12 +311,23 @@ self._signal_readable()
   all three datagram flavours. Tests: `TestRawSocketSoSndbuf` (2 —
   non-blocking EAGAIN, completion-hook release), `TestPingSocketSoSndbuf`
   (1 — charged-during / released-after balance).
-- **Still scoped out (follow-ons):** a sub-second `SO_SNDTIMEO` /
-  `SO_RCVTIMEO` via `setsockopt` (blocked today by the SOL_SOCKET int-guard
-  on the datagram sockets — float timeouts flow through `settimeout()`
-  instead); TCP `SO_SNDBUF` (TCP has its own send buffering / retransmit
-  queue, released on ACK, not on wire-write — a separate model, wrong to
-  fold into this counter); `SO_RCVBUF`-on-TCP (receive-window derivation).
+- **Shipped (sub-second timeout via setsockopt):** `SO_RCVTIMEO` /
+  `SO_SNDTIMEO` now accept and report a sub-second **float** value via
+  `setsockopt` / `getsockopt`, matching PyTCP's documented "float seconds"
+  surface. Previously the SOL_SOCKET dispatch int-guard rejected a float
+  and getsockopt `int()`-truncated the stored value. The setsockopt `value`
+  widened to `int | float | bytes`; a float is routed first to
+  `_sol_socket_setsockopt` (the only float-valid path) so the int / bytes
+  option handlers never receive one; getsockopt returns the float verbatim.
+  Tests: `TestUdpSocketTimeoutFloat` (3 — float `SO_RCVTIMEO` / `SO_SNDTIMEO`
+  round-trip + integer-still-accepted regression). This makes the R3
+  blocking-send `SO_SNDTIMEO` fully usable at sub-second granularity via
+  the public API.
+- **Still scoped out (follow-ons):** TCP `SO_SNDBUF` (TCP has its own send
+  buffering / retransmit queue, released on ACK, not on wire-write — a
+  separate model, wrong to fold into this counter); `SO_RCVBUF`-on-TCP
+  (receive-window derivation); the `X3` `listen()`-on-unbound → `EINVAL`
+  breaking change (updates `examples/`).
 
 ### R4 — IPv6 per-socket source filters = MLDv2 SSM track — DONE (P1-P5 shipped)
 

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

@@ -790,7 +790,7 @@ def _so_linger_get(self) -> bytes:
         l_onoff, l_linger = self._so_linger or (0, 0)
         return struct.pack("@ii", l_onoff, l_linger)
 
-    def _sol_socket_setsockopt(self, optname: int, value: int, /) -> bool:
+    def _sol_socket_setsockopt(self, optname: int, value: int | float, /) -> bool:
         """
         Apply a SOL_SOCKET-level setsockopt option; return True if
         handled or False if the optname is not a base-class option
@@ -1556,7 +1556,7 @@ def _effective_ip4_options(self) -> Ip4Options | None:
             return None
         return Ip4Options.from_buffer(self._ip_options)
 
-    def _sol_socket_getsockopt(self, optname: int, /) -> int | bytes | None:
+    def _sol_socket_getsockopt(self, optname: int, /) -> int | float | bytes | None:
         """
         Get a SOL_SOCKET-level option's stored value, or 'None' if
         the option is not a base-class option. Most options return an
@@ -1577,9 +1577,9 @@ def _sol_socket_getsockopt(self, optname: int, /) -> int | bytes | None:
             case _ if optname == SO_RCVBUF:
                 return self._so_rcvbuf or 0
             case _ if optname == SO_RCVTIMEO:
-                return int(self._so_rcvtimeo) if self._so_rcvtimeo else 0
+                return self._so_rcvtimeo or 0.0
             case _ if optname == SO_SNDTIMEO:
-                return int(self._so_sndtimeo) if self._so_sndtimeo else 0
+                return self._so_sndtimeo or 0.0
             case _ if optname == SO_OOBINLINE:
                 # Always 1 — PyTCP's RFC 6093 §6 universal-inline
                 # design (see the setsockopt comment above).
@@ -2114,7 +2114,7 @@ def recv__mv(
 
         raise NotImplementedError
 
-    def setsockopt(self, level: int | IpProto, optname: int, value: int | bytes, /) -> None:
+    def setsockopt(self, level: int | IpProto, optname: int, value: int | float | bytes, /) -> None:
         """
         The 'setsockopt()' socket API method placeholder. Each concrete
         IP socket implements the SOL_SOCKET / IPPROTO_* option surface;
@@ -2123,7 +2123,7 @@ def setsockopt(self, level: int | IpProto, optname: int, value: int | bytes, /)
 
         raise NotImplementedError
 
-    def getsockopt(self, level: int | IpProto, optname: int, /) -> int | bytes:
+    def getsockopt(self, level: int | IpProto, optname: int, /) -> int | float | bytes:
         """
         The 'getsockopt()' socket API method placeholder. Symmetric to
         'setsockopt'.

packages/pytcp/pytcp/runtime/socket/ping__socket.py

@@ -220,20 +220,31 @@ def getpeername(self) -> tuple[str, int]:
         return str(self._remote_ip_address), 0
 
     @override
-    def setsockopt(self, level: int | IpProto, optname: int, value: int | bytes, /) -> None:
+    def setsockopt(self, level: int | IpProto, optname: int, value: int | float | bytes, /) -> None:
         """
         Set a socket option. Supports 'IP_RECVTTL' / 'IPV6_RECVHOPLIMIT',
         which make 'recvmsg' surface the reply's TTL / Hop Limit cmsg.
         """
 
+        # A float value is only valid for the SOL_SOCKET float-seconds
+        # timeouts (SO_RCVTIMEO / SO_SNDTIMEO); route it there so the
+        # int / bytes option paths below never receive a float.
+        if isinstance(value, float):
+            if level == SOL_SOCKET and self._sol_socket_setsockopt(optname, value):
+                return
+            raise OSError(
+                errno.ENOPROTOOPT,
+                f"setsockopt: unsupported (level, optname) pair for a float value: "
+                f"level={level!r}, optname={optname!r}",
+            )
         if optname in (IP_RECVTTL, IPV6_RECVHOPLIMIT):
             self._recv_ttl = bool(value)
             return
         if isinstance(value, int) and level == SOL_SOCKET and self._sol_socket_setsockopt(optname, value):
             return
 
     @override
-    def getsockopt(self, level: int | IpProto, optname: int, /) -> int | bytes:
+    def getsockopt(self, level: int | IpProto, optname: int, /) -> int | float | bytes:
         """
         Get a socket option.
         """

packages/pytcp/pytcp/runtime/socket/raw__socket.py

@@ -156,14 +156,25 @@ def _get_ip_addresses(
         return local_ip_address, remote_ip_address  # type: ignore[return-value]
 
     @override
-    def setsockopt(self, level: int | IpProto, optname: int, value: int | bytes, /) -> None:
+    def setsockopt(self, level: int | IpProto, optname: int, value: int | float | bytes, /) -> None:
         """
         Set a socket option per the BSD 'setsockopt' API. RAW
         sockets honor SOL_SOCKET / IPPROTO_IP / IPPROTO_IPV6
         options through the base-class helpers. 'value' is 'int'
         for scalar options and 'bytes' for IP_OPTIONS.
         """
 
+        # A float value is only valid for the SOL_SOCKET float-seconds
+        # timeouts (SO_RCVTIMEO / SO_SNDTIMEO); route it there so the
+        # int / bytes option paths below never receive a float.
+        if isinstance(value, float):
+            if level == SOL_SOCKET and self._sol_socket_setsockopt(optname, value):
+                return
+            raise OSError(
+                errno.ENOPROTOOPT,
+                f"setsockopt: unsupported (level, optname) pair for a float value: "
+                f"level={level!r}, optname={optname!r}",
+            )
         if optname in (IP_RECVTTL, IPV6_RECVHOPLIMIT):
             # Make 'recvmsg' surface the received TTL / Hop Limit as an
             # 'IP_TTL' / 'IPV6_HOPLIMIT' cmsg — the only way to read the
@@ -187,7 +198,7 @@ def setsockopt(self, level: int | IpProto, optname: int, value: int | bytes, /)
         )
 
     @override
-    def getsockopt(self, level: int | IpProto, optname: int, /) -> int | bytes:
+    def getsockopt(self, level: int | IpProto, optname: int, /) -> int | float | bytes:
         """
         Get a socket option per the BSD 'getsockopt' API.
         Symmetric to 'setsockopt': 'int' for scalar options,
@@ -196,7 +207,7 @@ def getsockopt(self, level: int | IpProto, optname: int, /) -> int | bytes:
 
         if optname in (IP_RECVTTL, IPV6_RECVHOPLIMIT):
             return int(self._recv_ttl)
-        value: int | bytes | None
+        value: int | float | bytes | None
         if level == SOL_SOCKET and (value := self._sol_socket_getsockopt(optname)) is not None:
             return value
         if level == IPPROTO_IP and (value := self._ipproto_ip_getsockopt(optname)) is not None:

packages/pytcp/pytcp/runtime/socket/tcp__socket.py

@@ -335,7 +335,7 @@ def status(self) -> TcpStatus:
         )
 
     @override
-    def setsockopt(self, level: int | IpProto, optname: int, value: int | bytes, /) -> None:
+    def setsockopt(self, level: int | IpProto, optname: int, value: int | float | bytes, /) -> None:
         """
         Set a socket option per the BSD 'setsockopt' API.
 
@@ -356,6 +356,17 @@ def setsockopt(self, level: int | IpProto, optname: int, value: int | bytes, /)
             # Connection now has RFC 1122 §4.2.3.6 keep-alive enabled.
         """
 
+        # A float value is only valid for the SOL_SOCKET float-seconds
+        # timeouts (SO_RCVTIMEO / SO_SNDTIMEO); route it there so the
+        # int / bytes option paths below never receive a float.
+        if isinstance(value, float):
+            if level == SOL_SOCKET and self._sol_socket_setsockopt(optname, value):
+                return
+            raise OSError(
+                errno.ENOPROTOOPT,
+                f"setsockopt: unsupported (level, optname) pair for a float value: "
+                f"level={level!r}, optname={optname!r}",
+            )
         if isinstance(value, int) and level == SOL_SOCKET and optname == SO_KEEPALIVE:
             self._so_keepalive = bool(value)
             return
@@ -443,7 +454,7 @@ def setsockopt(self, level: int | IpProto, optname: int, value: int | bytes, /)
         )
 
     @override
-    def getsockopt(self, level: int | IpProto, optname: int, /) -> int | bytes:
+    def getsockopt(self, level: int | IpProto, optname: int, /) -> int | float | bytes:
         """
         Get a socket option per the BSD 'getsockopt' API.
 

packages/pytcp/pytcp/runtime/socket/udp__socket.py

@@ -167,7 +167,7 @@ def udp_no_check6_rx(self) -> bool:
         return self._udp_no_check6_rx
 
     @override
-    def setsockopt(self, level: int | IpProto, optname: int, value: int | bytes, /) -> None:
+    def setsockopt(self, level: int | IpProto, optname: int, value: int | float | bytes, /) -> None:
         """
         Set a socket option per the BSD 'setsockopt' API. UDP
         sockets honor SOL_SOCKET / IPPROTO_IP / IPPROTO_IPV6 /
@@ -176,6 +176,17 @@ def setsockopt(self, level: int | IpProto, optname: int, value: int | bytes, /)
         'bytes' for IP_OPTIONS (RFC 1122 §4.1.3.2 raw options block).
         """
 
+        # A float value is only valid for the SOL_SOCKET float-seconds
+        # timeouts (SO_RCVTIMEO / SO_SNDTIMEO); route it there so the
+        # int / bytes option paths below never receive a float.
+        if isinstance(value, float):
+            if level == SOL_SOCKET and self._sol_socket_setsockopt(optname, value):
+                return
+            raise OSError(
+                errno.ENOPROTOOPT,
+                f"setsockopt: unsupported (level, optname) pair for a float value: "
+                f"level={level!r}, optname={optname!r}",
+            )
         if level == SOL_SOCKET and optname == SO_BINDTODEVICE:
             self._so_bindtodevice(value)
             return
@@ -198,14 +209,14 @@ def setsockopt(self, level: int | IpProto, optname: int, value: int | bytes, /)
         )
 
     @override
-    def getsockopt(self, level: int | IpProto, optname: int, /) -> int | bytes:
+    def getsockopt(self, level: int | IpProto, optname: int, /) -> int | float | bytes:
         """
         Get a socket option per the BSD 'getsockopt' API.
         Symmetric to 'setsockopt': 'int' for scalar options,
         'bytes' for IP_OPTIONS.
         """
 
-        value: int | bytes | None
+        value: int | float | bytes | None
         if level == SOL_SOCKET and optname == SO_BINDTODEVICE:
             return self._bound_interface_name.encode() if self._bound_interface_name else bytes()
         if level == SOL_SOCKET and (value := self._sol_socket_getsockopt(optname)) is not None:

packages/pytcp/pytcp/tests/unit/runtime/socket/test__runtime__socket__udp__socket.py

@@ -3331,3 +3331,72 @@ def test__so_sndbuf__unset_default_never_blocks_normal_send(self) -> None:
 
         for _ in range(50):
             self.assertEqual(s.send(b"x" * 1000), 1000, msg="A default-SO_SNDBUF send must not block.")
+
+
+class TestUdpSocketTimeoutFloat(_UdpSocketTestCase):
+    """
+    SO_RCVTIMEO / SO_SNDTIMEO accept and report sub-second float
+    seconds via setsockopt / getsockopt, matching PyTCP's documented
+    'float seconds' surface. The setsockopt SOL_SOCKET int-guard
+    previously rejected a float value and getsockopt truncated the
+    stored timeout to whole seconds.
+    """
+
+    def test__so_rcvtimeo__accepts_and_reports_subsecond_float(self) -> None:
+        """
+        Ensure setsockopt(SO_RCVTIMEO, 0.5) stores the sub-second
+        timeout and getsockopt reports it back verbatim.
+
+        Reference: Linux SO_RCVTIMEO (struct timeval; PyTCP exposes
+        float seconds).
+        """
+
+        from pytcp.runtime.socket import SO_RCVTIMEO, SOL_SOCKET
+
+        s = UdpSocket(family=AddressFamily.INET4)
+
+        s.setsockopt(SOL_SOCKET, SO_RCVTIMEO, 0.5)
+        self.assertEqual(
+            s.getsockopt(SOL_SOCKET, SO_RCVTIMEO),
+            0.5,
+            msg="SO_RCVTIMEO must round-trip a sub-second float.",
+        )
+
+    def test__so_sndtimeo__accepts_and_reports_subsecond_float(self) -> None:
+        """
+        Ensure setsockopt(SO_SNDTIMEO, 0.25) stores the sub-second
+        timeout and getsockopt reports it back verbatim.
+
+        Reference: Linux SO_SNDTIMEO (struct timeval; PyTCP exposes
+        float seconds).
+        """
+
+        from pytcp.runtime.socket import SO_SNDTIMEO, SOL_SOCKET
+
+        s = UdpSocket(family=AddressFamily.INET4)
+
+        s.setsockopt(SOL_SOCKET, SO_SNDTIMEO, 0.25)
+        self.assertEqual(
+            s.getsockopt(SOL_SOCKET, SO_SNDTIMEO),
+            0.25,
+            msg="SO_SNDTIMEO must round-trip a sub-second float.",
+        )
+
+    def test__so_rcvtimeo__integer_seconds_still_accepted(self) -> None:
+        """
+        Ensure an integer SO_RCVTIMEO still works — regression pin
+        for the float widening.
+
+        Reference: Linux SO_RCVTIMEO (integer-second value accepted).
+        """
+
+        from pytcp.runtime.socket import SO_RCVTIMEO, SOL_SOCKET
+
+        s = UdpSocket(family=AddressFamily.INET4)
+
+        s.setsockopt(SOL_SOCKET, SO_RCVTIMEO, 3)
+        self.assertEqual(
+            s.getsockopt(SOL_SOCKET, SO_RCVTIMEO),
+            3,
+            msg="SO_RCVTIMEO must still accept an integer-second value.",
+        )