feat: add connection retry support to v2 client

Large file uploads can fail partway through due to transient network
issues. This adds automatic connection-level retries using httpx's
built-in HTTPTransport(retries=N), which only retries on ConnectError
and ConnectTimeout — cases where the TCP connection was never
established, making it safe for all HTTP methods including POST.

Configurable via ClientConfig(connection_retries=N), defaulting to 3.
Set to 0 to disable.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: mhusbynflow

flowbio/v2/_transport.py

@@ -24,12 +24,16 @@ class HttpTransport:
 
     :param base_url: The base URL of the Flow API
         (e.g. ``"https://app.flow.bio/api"``).
+    :param connection_retries: Number of retries on connection failure.
+        Only retries ``ConnectError``/``ConnectTimeout`` (TCP never
+        established), so it is safe for all HTTP methods. Defaults to ``3``.
     """
 
-    def __init__(self, base_url: str) -> None:
+    def __init__(self, base_url: str, connection_retries: int = 3) -> None:
         self._base_url = base_url.rstrip("/")
         self._client = httpx.Client(
             headers={"User-Agent": f"flowbio-python/{_CLIENT_VERSION}"},
+            transport=httpx.HTTPTransport(retries=connection_retries),
         )
 
     _STATUS_TO_EXCEPTION: dict[int, type[FlowApiError]] = {

flowbio/v2/client.py

@@ -13,6 +13,11 @@ class ClientConfig:
         Defaults to 1 MB.
     :param show_progress: Whether to display progress bars during
         file uploads. Defaults to ``True``.
+    :param connection_retries: Number of times to retry on connection
+        failure (e.g. ``ConnectError``, ``ConnectTimeout``). Only retries
+        when the TCP connection was never established, so it is safe for
+        all HTTP methods including POST. Set to ``0`` to disable.
+        Defaults to ``3``.
 
     Example usage::
 
@@ -26,6 +31,7 @@ class ClientConfig:
 
     chunk_size: int = 1_000_000
     show_progress: bool = True
+    connection_retries: int = 3
 
 
 class Client:
@@ -58,8 +64,11 @@ def __init__(
         base_url: str = "https://app.flow.bio/api",
         config: ClientConfig | None = None,
     ) -> None:
-        self._transport = HttpTransport(base_url)
         self._config = config or ClientConfig()
+        self._transport = HttpTransport(
+            base_url,
+            connection_retries=self._config.connection_retries,
+        )
         self._samples = SampleResource(self._transport, self._config)
 
     @property

tests/unit/v2/test_client.py

@@ -1,4 +1,5 @@
 import json
+from unittest.mock import patch
 
 import httpx
 import pytest
@@ -111,6 +112,12 @@ def test_default_config_values(self) -> None:
 
         assert config.chunk_size == 1_000_000
         assert config.show_progress is True
+        assert config.connection_retries == 3
+
+    def test_custom_connection_retries(self) -> None:
+        config = ClientConfig(connection_retries=0)
+
+        assert config.connection_retries == 0
 
     def test_config_is_immutable(self) -> None:
         config = ClientConfig()
@@ -120,3 +127,14 @@ def test_config_is_immutable(self) -> None:
 
     def test_client_accepts_custom_config(self) -> None:
         Client(config=ClientConfig(chunk_size=5_000_000))
+
+    @patch("flowbio.v2.client.HttpTransport")
+    def test_client_passes_connection_retries_to_transport(self, mock_transport) -> None:
+        connection_retries = 5
+
+        Client(config=ClientConfig(connection_retries=connection_retries))
+
+        mock_transport.assert_called_once_with(
+            "https://app.flow.bio/api",
+            connection_retries=connection_retries,
+        )

tests/unit/v2/test_samples.py

@@ -425,6 +425,25 @@ def test_uploads_in_chunks(self, tmp_path: Path) -> None:
 
         assert route.call_count == 3
 
+    @respx.mock
+    def test_connect_error_on_chunk_propagates(self, tmp_path: Path) -> None:
+        file_path = tmp_path / "reads.fastq"
+        file_path.write_bytes(b"A" * 100)
+        route = respx.post(f"{DEFAULT_BASE_URL}/upload/sample")
+        route.side_effect = [
+            httpx.Response(200, json={"sample_id": None, "data_id": "d1"}),
+            httpx.ConnectError("Connection refused"),
+        ]
+
+        client = Client(config=ClientConfig(chunk_size=40, show_progress=False))
+
+        with pytest.raises(httpx.ConnectError):
+            client.samples.upload_sample(
+                name="My Sample",
+                sample_type="rna_seq",
+                data={"reads1": file_path},
+            )
+
     def test_rejects_invalid_reads_key(self, tmp_path: Path) -> None:
         file_path = tmp_path / "reads.fastq"
         file_path.write_bytes(b"ATCG")

tests/unit/v2/test_transport.py

@@ -1,4 +1,5 @@
 import json
+from unittest.mock import patch
 
 import httpx
 import respx
@@ -16,6 +17,29 @@
 from tests.unit.v2.conftest import DEFAULT_BASE_URL
 
 
+class TestTransportConnectionRetries:
+
+    @patch("flowbio.v2._transport.httpx.HTTPTransport")
+    def test_default_retries(self, mock_http_transport) -> None:
+        HttpTransport(DEFAULT_BASE_URL)
+
+        mock_http_transport.assert_called_once_with(retries=3)
+
+    @patch("flowbio.v2._transport.httpx.HTTPTransport")
+    def test_custom_retries(self, mock_http_transport) -> None:
+        connection_retries = 5
+
+        HttpTransport(DEFAULT_BASE_URL, connection_retries=connection_retries)
+
+        mock_http_transport.assert_called_once_with(retries=connection_retries)
+
+    @patch("flowbio.v2._transport.httpx.HTTPTransport")
+    def test_retries_disabled(self, mock_http_transport) -> None:
+        HttpTransport(DEFAULT_BASE_URL, connection_retries=0)
+
+        mock_http_transport.assert_called_once_with(retries=0)
+
+
 class TestTransportGet:
 
     @respx.mock