Add IBKR TCP preflight diagnostics

Author: Pigbibi

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "quant-platform-kit"
-version = "0.7.2"
+version = "0.7.3"
 description = "Shared broker adapters, domain models, execution ports, and notification utilities for QuantStrategyLab strategies."
 readme = "README.md"
 requires-python = ">=3.9"

src/quant_platform_kit/__init__.py

@@ -1,6 +1,6 @@
 """QuantPlatformKit public package surface."""
 
-__version__ = "0.7.2"
+__version__ = "0.7.3"
 
 from .common.models import (
     ExecutionReport,

src/quant_platform_kit/ibkr/connection.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import asyncio
+import socket
 from typing import Any, Callable
 
 
@@ -20,15 +21,46 @@ def ensure_event_loop() -> asyncio.AbstractEventLoop:
     return loop
 
 
+def probe_tcp_endpoint(
+    host: str,
+    port: int,
+    *,
+    timeout: float,
+    socket_create_connection: Callable[..., Any] | None = None,
+) -> None:
+    if socket_create_connection is None:
+        socket_create_connection = socket.create_connection
+
+    try:
+        connection = socket_create_connection((host, port), timeout)
+    except TimeoutError as exc:
+        raise TimeoutError(f"TCP preflight timed out for {host}:{port}") from exc
+    except OSError as exc:
+        raise ConnectionError(f"TCP preflight failed for {host}:{port}: {exc}") from exc
+
+    close = getattr(connection, "close", None)
+    if callable(close):
+        close()
+
+
 def connect_ib(
     host: str,
     port: int,
     client_id: int,
     *,
     timeout: int = 20,
+    tcp_preflight_timeout: float | None = 3.0,
+    socket_create_connection: Callable[..., Any] | None = None,
     ib_factory: Callable[[], Any] | None = None,
 ) -> Any:
     ensure_event_loop()
+    if tcp_preflight_timeout is not None and tcp_preflight_timeout > 0:
+        probe_tcp_endpoint(
+            host,
+            port,
+            timeout=min(float(timeout), float(tcp_preflight_timeout)),
+            socket_create_connection=socket_create_connection,
+        )
     if ib_factory is None:
         from ib_insync import IB
 

tests/test_ibkr_connection.py

@@ -4,7 +4,7 @@
 from concurrent.futures import ThreadPoolExecutor
 import unittest
 
-from quant_platform_kit.ibkr.connection import connect_ib, ensure_event_loop
+from quant_platform_kit.ibkr.connection import connect_ib, ensure_event_loop, probe_tcp_endpoint
 
 
 class IbkrConnectionTests(unittest.TestCase):
@@ -31,11 +31,80 @@ class FakeIB:
             def connect(self, host, port, clientId, timeout):
                 observed["args"] = (host, port, clientId, timeout)
 
-        ib = connect_ib("127.0.0.1", 4001, 9, ib_factory=FakeIB)
+        class FakeConnection:
+            def close(self):
+                observed["socket_closed"] = True
+
+        def fake_socket_create_connection(address, timeout):
+            observed["socket_args"] = (address, timeout)
+            return FakeConnection()
+
+        ib = connect_ib(
+            "127.0.0.1",
+            4001,
+            9,
+            socket_create_connection=fake_socket_create_connection,
+            ib_factory=FakeIB,
+        )
 
         self.assertIsInstance(ib, FakeIB)
         self.assertEqual(observed["args"], ("127.0.0.1", 4001, 9, 20))
 
 
+    def test_probe_tcp_endpoint_wraps_timeout(self) -> None:
+        def fake_socket_create_connection(_address, _timeout):
+            raise TimeoutError()
+
+        with self.assertRaisesRegex(TimeoutError, r'TCP preflight timed out for 10\.0\.0\.8:4002'):
+            probe_tcp_endpoint(
+                '10.0.0.8',
+                4002,
+                timeout=2.5,
+                socket_create_connection=fake_socket_create_connection,
+            )
+
+    def test_probe_tcp_endpoint_wraps_os_error(self) -> None:
+        def fake_socket_create_connection(_address, _timeout):
+            raise OSError('connection refused')
+
+        with self.assertRaisesRegex(ConnectionError, r'TCP preflight failed for 10\.0\.0\.8:4002: connection refused'):
+            probe_tcp_endpoint(
+                '10.0.0.8',
+                4002,
+                timeout=2.5,
+                socket_create_connection=fake_socket_create_connection,
+            )
+
+    def test_connect_ib_runs_tcp_preflight_before_ib_connect(self) -> None:
+        observed: dict[str, object] = {}
+
+        class FakeConnection:
+            def close(self):
+                observed['socket_closed'] = True
+
+        def fake_socket_create_connection(address, timeout):
+            observed['socket_args'] = (address, timeout)
+            return FakeConnection()
+
+        class FakeIB:
+            def connect(self, host, port, clientId, timeout):
+                observed['ib_args'] = (host, port, clientId, timeout)
+
+        ib = connect_ib(
+            '10.0.0.8',
+            4002,
+            9,
+            timeout=20,
+            tcp_preflight_timeout=3.5,
+            socket_create_connection=fake_socket_create_connection,
+            ib_factory=FakeIB,
+        )
+
+        self.assertIsInstance(ib, FakeIB)
+        self.assertEqual(observed['socket_args'], (('10.0.0.8', 4002), 3.5))
+        self.assertTrue(observed['socket_closed'])
+        self.assertEqual(observed['ib_args'], ('10.0.0.8', 4002, 9, 20))
+
+
 if __name__ == "__main__":
     unittest.main()