internetdata 2.0.0__tar.gz → 2.1.0__tar.gz

{internetdata-2.0.0 → internetdata-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: internetdata
-Version: 2.0.0
+Version: 2.1.0
 Summary: Official Python client library for the InternetData API. Download and verify licensed IP datasets.
 Project-URL: Homepage, https://internetdata.io
 Project-URL: Documentation, https://docs.internetdata.io
@@ -165,6 +165,14 @@ except InternetDataError as err:
 
 `kind` is one of `bad_request`, `unauthorized`, `forbidden`, `rate_limited`, `quota_exceeded`, `server_error` or `network`. `message` is the API's own result code, passed through as it was sent, so you can switch on `NOT_LICENSED` against `LICENSE_EXPIRED` without reading the status.
 
+A request that runs past its `timeout` fails with `network`, and is retried like any other network failure. The default is 30 seconds per attempt, body included, so a retried call can take longer in total. A database transfer is exempt, so `download` and `download_bytes` are never cut off part way through a large file. Set it on the client, in seconds, or pass `None` for no bound:
+
+```python
+client = InternetData(api_key, timeout=10)
+```
+
+**Changed in 2.1.0:** the default was 10 seconds, and it bounded each read of a response rather than the whole attempt, so a response trickling in slowly could run past it for as long as the server kept sending.
+
 Note that `rate_limited` and `quota_exceeded` both arrive as HTTP 429 and are not the same thing. A rate limit is the API facing a traffic burst, and retrying later works; a spent quota needs your allowance raised or the window to roll over. The library retries rate limits for you, and server and network failures, but never a spent quota or anything else you sent.
 
 ## Other Libraries

{internetdata-2.0.0 → internetdata-2.1.0}/README.md

@@ -131,6 +131,14 @@ except InternetDataError as err:
 
 `kind` is one of `bad_request`, `unauthorized`, `forbidden`, `rate_limited`, `quota_exceeded`, `server_error` or `network`. `message` is the API's own result code, passed through as it was sent, so you can switch on `NOT_LICENSED` against `LICENSE_EXPIRED` without reading the status.
 
+A request that runs past its `timeout` fails with `network`, and is retried like any other network failure. The default is 30 seconds per attempt, body included, so a retried call can take longer in total. A database transfer is exempt, so `download` and `download_bytes` are never cut off part way through a large file. Set it on the client, in seconds, or pass `None` for no bound:
+
+```python
+client = InternetData(api_key, timeout=10)
+```
+
+**Changed in 2.1.0:** the default was 10 seconds, and it bounded each read of a response rather than the whole attempt, so a response trickling in slowly could run past it for as long as the server kept sending.
+
 Note that `rate_limited` and `quota_exceeded` both arrive as HTTP 429 and are not the same thing. A rate limit is the API facing a traffic burst, and retrying later works; a spent quota needs your allowance raised or the window to roll over. The library retries rate limits for you, and server and network failures, but never a spent quota or anything else you sent.
 
 ## Other Libraries

{internetdata-2.0.0 → internetdata-2.1.0}/src/internetdata/__init__.py

@@ -26,7 +26,7 @@ from .models import (
     Standing,
 )
 
-__version__ = "2.0.0"
+__version__ = "2.1.0"
 
 __all__ = [
     "DEFAULT_BASE_URL",

{internetdata-2.0.0 → internetdata-2.1.0}/src/internetdata/_core.py

@@ -1,13 +1,17 @@
-"""Plumbing the sync and the async client both need: transport wiring, response
-unwrapping, and the retry policy."""
+"""Plumbing the sync and the async client both need: transport wiring, the deadline on
+each attempt, response unwrapping, and the retry policy."""
 
 from __future__ import annotations
 
+import asyncio
 import contextlib
+import contextvars
 import json
 import os
+import threading
 from collections.abc import Awaitable, Callable, Iterator
 from pathlib import Path
+from types import ModuleType
 from typing import IO, Any, TypeVar, cast
 
 import httpx
@@ -19,7 +23,7 @@ from .models import Database, Download, to_database, to_download
 
 DEFAULT_BASE_URL = "https://internetdata.io"
 DEFAULT_RETRIES = 2
-DEFAULT_TIMEOUT = 10.0
+DEFAULT_TIMEOUT = 30.0
 DEFAULT_DOWNLOADS_LIMIT = 50
 
 # One chunk of a transfer, and therefore the ceiling on what a download of any size
@@ -172,8 +176,10 @@ def send(call: Callable[[], Response[Any]]) -> Response[Any]:
     something this client cannot read, which is a failed request rather than a bug in the
     caller's code, so all three become the one error type here.
 
-    The lambda does nothing but call the generated function, which is what keeps this
-    catch from swallowing a fault of our own.
+    The call does nothing but build one generated request, send it and hand the answer to
+    the generated decoder, which is what keeps this catch from swallowing a fault of our own.
+    An argument is converted before it, so a format this client does not publish is the
+    caller's `ValueError` rather than the server's failure.
     """
     try:
         return call()
@@ -189,6 +195,91 @@ async def send_async(call: Callable[[], Awaitable[Response[Any]]]) -> Response[A
         raise malformed(exc) from exc
 
 
+def request(
+    endpoint: ModuleType, client: AuthenticatedClient, bound: float | None, **params: Any
+) -> Response[Any]:
+    """`send` for one generated endpoint, one attempt of it finished within `bound` seconds,
+    or unbounded when that is None.
+
+    Assembled from the endpoint module's `_get_kwargs` and `_build_response` because its
+    `sync_detailed` sends through httpx alone, and httpx has no bound on the attempt.
+    """
+
+    def call() -> Response[Any]:
+        http = client.get_httpx_client()
+        req = http.build_request(**endpoint._get_kwargs(**params), timeout=httpx.Timeout(bound))
+        res = exchange(http, req, bound)
+        return cast(Response[Any], endpoint._build_response(client=client, response=res))
+
+    return send(call)
+
+
+async def request_async(
+    endpoint: ModuleType, client: AuthenticatedClient, bound: float | None, **params: Any
+) -> Response[Any]:
+    """`request`, awaited."""
+
+    async def call() -> Response[Any]:
+        http = client.get_async_httpx_client()
+        req = http.build_request(**endpoint._get_kwargs(**params), timeout=httpx.Timeout(bound))
+        res = await exchange_async(http, req, bound)
+        return cast(Response[Any], endpoint._build_response(client=client, response=res))
+
+    return await send_async(call)
+
+
+def exchange(http: httpx.Client, req: httpx.Request, bound: float | None) -> httpx.Response:
+    """One attempt at `req`, its whole body read, finished within `bound` seconds or failed
+    as a `network` error.
+
+    httpx bounds each PHASE of a request (connect, write, every read), not the attempt, so a
+    body trickling in a byte at a time outlasts any timeout it is given. The attempt runs on
+    a thread of its own and the caller waits at most `bound` for it; one abandoned stops at
+    its next chunk, or at the per-phase bound `req` also carries.
+    """
+    if bound is None:
+        return http.send(req)
+    finished = threading.Event()
+    abandoned = threading.Event()
+    outcome: list[httpx.Response | BaseException] = []
+    context = contextvars.copy_context()
+
+    def attempt() -> None:
+        try:
+            outcome.append(context.run(_read_whole, http, req, abandoned))
+        except BaseException as exc:  # noqa: BLE001 - raised again on the caller's thread
+            outcome.append(exc)
+        finally:
+            finished.set()
+
+    threading.Thread(target=attempt, name="internetdata-attempt", daemon=True).start()
+    try:
+        if not finished.wait(bound):
+            raise _deadline_passed(bound)
+    finally:
+        abandoned.set()
+    if isinstance(outcome[0], BaseException):
+        raise outcome[0]
+    return outcome[0]
+
+
+async def exchange_async(
+    http: httpx.AsyncClient, req: httpx.Request, bound: float | None
+) -> httpx.Response:
+    """`exchange`, awaited. Cancelling the attempt closes its connection, so no thread is
+    needed to leave it behind."""
+    if bound is None:
+        return await http.send(req)
+    deadline = asyncio.timeout(bound)
+    try:
+        async with deadline:
+            return await http.send(req)
+    except TimeoutError:
+        if not deadline.expired():
+            raise
+        raise _deadline_passed(bound) from None
+
+
 def malformed(exc: Exception) -> InternetDataError:
     return InternetDataError("server_error", f"malformed response from the API: {exc}")
 
@@ -273,6 +364,41 @@ def retry_delay(err: InternetDataError, attempt: int, retries: int) -> float | N
     return _BACKOFF_BASE * (2.0**attempt)
 
 
+def _read_whole(
+    http: httpx.Client, req: httpx.Request, abandoned: threading.Event
+) -> httpx.Response:
+    res = http.send(req, stream=True)
+    try:
+        if isinstance(res.stream, httpx.SyncByteStream):
+            res.stream = _Abandonable(res.stream, abandoned, req)
+        res.read()
+    finally:
+        res.close()
+    return res
+
+
+class _Abandonable(httpx.SyncByteStream):
+    def __init__(
+        self, inner: httpx.SyncByteStream, abandoned: threading.Event, req: httpx.Request
+    ) -> None:
+        self._inner = inner
+        self._abandoned = abandoned
+        self._req = req
+
+    def __iter__(self) -> Iterator[bytes]:
+        for chunk in self._inner:
+            if self._abandoned.is_set():
+                raise httpx.ReadError("abandoned once its deadline passed", request=self._req)
+            yield chunk
+
+    def close(self) -> None:
+        self._inner.close()
+
+
+def _deadline_passed(bound: float) -> InternetDataError:
+    return InternetDataError("network", f"the request did not complete within {bound:g} seconds")
+
+
 # The generated Response declares a plain MutableMapping, but always carries httpx's
 # case-insensitive Headers. Rebuilding one keeps a header lookup case-blind whichever it
 # turns out to be, which matters for `Retry-After`.

{internetdata-2.0.0 → internetdata-2.1.0}/src/internetdata/aio.py

@@ -32,8 +32,8 @@ from ._core import (
     parse_body,
     part_file,
     redirect_location,
+    request_async,
     retry_delay,
-    send_async,
     storage_refusal,
     unwrap,
 )
@@ -76,6 +76,7 @@ class AsyncInternetData:
         self._client = build_client(api_key, base_url, timeout, transport)
         self._transfer = build_async_transfer_client(timeout, transport)
         self._retries = retries
+        self._timeout = timeout
         self.database = AsyncDatabaseApi(self)
 
     async def aclose(self) -> None:
@@ -128,7 +129,7 @@ class AsyncDatabaseApi:
         """
 
         async def call() -> builtins.list[Database]:
-            res = await send_async(lambda: list_databases.asyncio_detailed(client=self._client))
+            res = await request_async(list_databases, self._client, self._owner._timeout)
             return parse_body(unwrap(res), databases_of)
 
         return await self._retrying(call)
@@ -137,8 +138,8 @@ class AsyncDatabaseApi:
         """What is inside one database: freshness, row count, columns, samples and sizes."""
 
         async def call() -> DatabaseMetadata:
-            res = await send_async(
-                lambda: database_metadata_v2.asyncio_detailed(client=self._client, id=database_id)
+            res = await request_async(
+                database_metadata_v2, self._client, self._owner._timeout, id=database_id
             )
             return parse_body(unwrap(res), to_metadata)
 
@@ -148,12 +149,12 @@ class AsyncDatabaseApi:
         """Every checksum published for one database file, keyed by algorithm."""
 
         async def call() -> dict[str, str]:
-            res = await send_async(
-                lambda: database_checksum_v2.asyncio_detailed(
-                    client=self._client,
-                    id=database_id,
-                    format_=DatabaseFormat(format),
-                )
+            res = await request_async(
+                database_checksum_v2,
+                self._client,
+                self._owner._timeout,
+                id=database_id,
+                format_=DatabaseFormat(format),
             )
             return parse_body(unwrap(res), checksums_of)
 
@@ -163,8 +164,8 @@ class AsyncDatabaseApi:
         """Your organization's recent download attempts, newest first."""
 
         async def call() -> builtins.list[Download]:
-            res = await send_async(
-                lambda: list_downloads.asyncio_detailed(client=self._client, limit=limit)
+            res = await request_async(
+                list_downloads, self._client, self._owner._timeout, limit=limit
             )
             return parse_body(unwrap(res), downloads_of)
 
@@ -181,12 +182,12 @@ class AsyncDatabaseApi:
         """
 
         async def call() -> str:
-            res = await send_async(
-                lambda: download_database_v2.asyncio_detailed(
-                    client=self._client,
-                    id=database_id,
-                    format_=DatabaseFormat(format),
-                )
+            res = await request_async(
+                download_database_v2,
+                self._client,
+                self._owner._timeout,
+                id=database_id,
+                format_=DatabaseFormat(format),
             )
             return redirect_location(res)
 

{internetdata-2.0.0 → internetdata-2.1.0}/src/internetdata/client.py

@@ -27,8 +27,8 @@ from ._core import (
     parse_body,
     part_file,
     redirect_location,
+    request,
     retry_delay,
-    send,
     storage_refusal,
     unwrap,
 )
@@ -58,6 +58,10 @@ class InternetData:
     rather than an empty one: what this API serves without a licence is a product
     decision, not the client's to refuse.
 
+    `timeout` is how long one attempt at a request may take, in seconds, body included, so a
+    call that is retried can take longer in total; None means no bound, and a database
+    transfer is exempt.
+
     Holds an HTTP connection pool, so use it as a context manager or call `close()` when
     you are done with it.
     """
@@ -77,6 +81,7 @@ class InternetData:
         self._client = build_client(api_key, base_url, timeout, transport)
         self._transfer = build_transfer_client(timeout, transport)
         self._retries = retries
+        self._timeout = timeout
         self.database = DatabaseApi(self)
 
     def close(self) -> None:
@@ -133,7 +138,7 @@ class DatabaseApi:
         """
 
         def call() -> builtins.list[Database]:
-            res = send(lambda: list_databases.sync_detailed(client=self._client))
+            res = request(list_databases, self._client, self._owner._timeout)
             return parse_body(unwrap(res), databases_of)
 
         return self._retrying(call)
@@ -146,9 +151,7 @@ class DatabaseApi:
         """
 
         def call() -> DatabaseMetadata:
-            res = send(
-                lambda: database_metadata_v2.sync_detailed(client=self._client, id=database_id)
-            )
+            res = request(database_metadata_v2, self._client, self._owner._timeout, id=database_id)
             return parse_body(unwrap(res), to_metadata)
 
         return self._retrying(call)
@@ -161,12 +164,12 @@ class DatabaseApi:
         """
 
         def call() -> dict[str, str]:
-            res = send(
-                lambda: database_checksum_v2.sync_detailed(
-                    client=self._client,
-                    id=database_id,
-                    format_=DatabaseFormat(format),
-                )
+            res = request(
+                database_checksum_v2,
+                self._client,
+                self._owner._timeout,
+                id=database_id,
+                format_=DatabaseFormat(format),
             )
             return parse_body(unwrap(res), checksums_of)
 
@@ -180,7 +183,7 @@ class DatabaseApi:
         """
 
         def call() -> builtins.list[Download]:
-            res = send(lambda: list_downloads.sync_detailed(client=self._client, limit=limit))
+            res = request(list_downloads, self._client, self._owner._timeout, limit=limit)
             return parse_body(unwrap(res), downloads_of)
 
         return self._retrying(call)
@@ -196,12 +199,12 @@ class DatabaseApi:
         """
 
         def call() -> str:
-            res = send(
-                lambda: download_database_v2.sync_detailed(
-                    client=self._client,
-                    id=database_id,
-                    format_=DatabaseFormat(format),
-                )
+            res = request(
+                download_database_v2,
+                self._client,
+                self._owner._timeout,
+                id=database_id,
+                format_=DatabaseFormat(format),
             )
             return redirect_location(res)
 

{internetdata-2.0.0 → internetdata-2.1.0}/tests/helpers.py

@@ -10,10 +10,15 @@ from __future__ import annotations
 
 import asyncio
 import json
+import socket
+import threading
+import time
+from collections.abc import Callable
 from pathlib import Path
-from typing import Any
+from typing import Any, Self
 
 import httpx
+import pytest
 
 from internetdata import AsyncInternetData, InternetData
 
@@ -152,6 +157,138 @@ class Stub:
         return bodies[min(self._served(self.requests[-1].url.path) - 1, len(bodies) - 1)]
 
 
+class LocalServer:
+    """A real socket on 127.0.0.1, answering each connection's one request from a thread.
+
+    What a deadline is tested against: `MockTransport` never consults a timeout. Past
+    `MAX_REQUESTS` it stops accepting, so a retry loop that never ends waits for good instead
+    of spinning, and `settle` fails the test from outside it.
+    """
+
+    MAX_REQUESTS = 20
+
+    def __init__(self) -> None:
+        self._listener = socket.create_server(("127.0.0.1", 0))
+        self._listener.settimeout(0.05)
+        host, port = self._listener.getsockname()[:2]
+        self.url = f"http://{host}:{port}"
+        self.paths: list[str] = []
+        self.closed = threading.Event()
+        threading.Thread(target=self._serve, daemon=True).start()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.closed.set()
+        self._listener.close()
+
+    def answer(self, conn: socket.socket, path: str) -> None:
+        raise NotImplementedError
+
+    def _serve(self) -> None:
+        while not self.closed.is_set():
+            if len(self.paths) >= self.MAX_REQUESTS:
+                self.closed.wait(0.05)
+                continue
+            try:
+                conn, _ = self._listener.accept()
+            except TimeoutError:
+                continue
+            except OSError:
+                return
+            threading.Thread(target=self._handle, args=(conn,), daemon=True).start()
+
+    def _handle(self, conn: socket.socket) -> None:
+        with conn:
+            try:
+                conn.settimeout(3.0)
+                request_line = conn.recv(65536).decode("latin-1").split("\r\n", 1)[0]
+                path = request_line.split(" ")[1].split("?", 1)[0] if " " in request_line else ""
+                self.paths.append(path)
+                self.answer(conn, path)
+            except OSError:
+                return
+
+
+class SlowBody(LocalServer):
+    """Answers every request with a 200's headers and the first byte of its body, then a
+    byte every `trickle` seconds, or nothing more when that is None.
+
+    What httpx's own timeout cannot bound: it limits each read rather than the attempt, so a
+    trickle faster than the bound resets it forever. Each response gives up after
+    `for_at_most` seconds, so a client that stops honoring its bound fails its test instead
+    of hanging the suite.
+    """
+
+    def __init__(self, trickle: float | None, for_at_most: float = 3.0) -> None:
+        self._trickle = trickle
+        self._for_at_most = for_at_most
+        super().__init__()
+
+    def answer(self, conn: socket.socket, path: str) -> None:
+        give_up = time.monotonic() + self._for_at_most
+        conn.sendall(
+            b"HTTP/1.1 200 OK\r\nContent-Type: application/json\r\n"
+            b"Content-Length: 100000\r\nConnection: close\r\n\r\n{"
+        )
+        gap = self._for_at_most if self._trickle is None else self._trickle
+        while not self.closed.wait(gap) and time.monotonic() < give_up:
+            if self._trickle is not None:
+                conn.sendall(b" ")
+
+
+class SlowTransfer(LocalServer):
+    """The API's `302` to a blob on this same server, and that blob in two halves with
+    `pause` seconds between them.
+
+    A pause longer than a client's timeout outlasts it twice over: in total, and as the one
+    gap between two reads. So neither a deadline over the transfer nor a bound on each read
+    can pass unseen.
+    """
+
+    BODY = bytes(range(256)) * 64
+
+    def __init__(self, pause: float) -> None:
+        self._pause = pause
+        super().__init__()
+
+    def answer(self, conn: socket.socket, path: str) -> None:
+        if path == DOWNLOAD_PATH:
+            conn.sendall(
+                f"HTTP/1.1 302 Found\r\nLocation: {self.url}/blob\r\n"
+                "Content-Length: 0\r\nConnection: close\r\n\r\n".encode()
+            )
+            return
+        half = len(self.BODY) // 2
+        conn.sendall(
+            b"HTTP/1.1 200 OK\r\nContent-Type: application/octet-stream\r\n"
+            + f"Content-Length: {len(self.BODY)}\r\nConnection: close\r\n\r\n".encode()
+            + self.BODY[:half]
+        )
+        if not self.closed.wait(self._pause):
+            conn.sendall(self.BODY[half:])
+
+
+def settle(call: Callable[[], Any], within: float = 10.0) -> Any:
+    """What `call` returned, or the exception it raised, run on a thread of its own so a
+    call that never ends fails the test instead of hanging the suite."""
+    outcome: list[Any] = []
+
+    def run() -> None:
+        try:
+            outcome.append(call())
+        except BaseException as exc:  # noqa: BLE001 - the outcome under test
+            outcome.append(exc)
+
+    worker = threading.Thread(target=run, daemon=True)
+    worker.start()
+    worker.join(within)
+    if worker.is_alive():
+        pytest.fail(f"the call under test did not settle within {within}s")
+    return outcome[0]
+
+
 def database(base: str, **overrides: Any) -> dict[str, Any]:
     """One served catalog entry, in the wire shape, with the boring fields filled in."""
     entry: dict[str, Any] = {

{internetdata-2.0.0 → internetdata-2.1.0}/tests/test_client.py

@@ -4,21 +4,29 @@ from __future__ import annotations
 
 import dataclasses
 import datetime
+import inspect
+import time
+from collections.abc import Callable
+from typing import Any
 
 import httpx
 import pytest
 from helpers import (
     API,
     API_KEY,
+    CHECKSUM_PATH,
     DOWNLOADS_PATH,
     LIST_PATH,
     METADATA_PATH,
+    ClientAdapter,
     ClientFactory,
+    SlowBody,
     Stub,
     database,
+    settle,
 )
 
-from internetdata import InternetData, InternetDataError
+from internetdata import AsyncInternetData, InternetData, InternetDataError, _core
 
 METADATA = {
     "id": "bogon_ip_v1",
@@ -62,6 +70,22 @@ DOWNLOADS = {
     ]
 }
 
+# Far under SlowBody's three seconds, so a client that ignores its bound fails on how long
+# the call took rather than on the server giving up.
+TIMEOUT = 0.3
+# A byte every 20 ms, so no single read ever waits long enough for httpx's own bound.
+TRICKLE = 0.02
+# What starting a thread or an event loop may add to a deadline.
+SLACK = 0.25
+
+JSON_CALLS: dict[str, Callable[[ClientAdapter], Any]] = {
+    "list": lambda client: client.database.list(),
+    "metadata": lambda client: client.database.metadata("bogon_ip_v1"),
+    "checksums": lambda client: client.database.checksums("bogon_ip_v1", "csvgz"),
+    "downloads": lambda client: client.database.downloads(),
+    "download_url": lambda client: client.database.download_url("bogon_ip_v1", "csvgz"),
+}
+
 
 def test_metadata_is_typed_rather_than_a_bag_of_strings(make_client: ClientFactory) -> None:
     stub = Stub({METADATA_PATH: {"body": METADATA}})
@@ -212,6 +236,76 @@ def test_a_transport_failure_surfaces_as_a_network_error() -> None:
     assert caught.value.retryable is True
 
 
+@pytest.mark.parametrize("call", JSON_CALLS)
+def test_the_timeout_bounds_a_trickling_body_on_every_json_call(
+    make_client: ClientFactory, call: str
+) -> None:
+    with SlowBody(trickle=TRICKLE) as server:
+        client = make_client(base_url=server.url, timeout=TIMEOUT, retries=0)
+        elapsed, outcome = _timed(lambda: JSON_CALLS[call](client))
+
+    _assert_timed_out(outcome)
+    _assert_one_bound(elapsed)
+
+
+# httpx's per-read bound catches a full stall on its own, so this passes without the
+# deadline; the trickle above is what proves the deadline exists.
+def test_a_body_that_stalls_after_its_headers_is_bounded(make_client: ClientFactory) -> None:
+    with SlowBody(trickle=None) as server:
+        client = make_client(base_url=server.url, timeout=TIMEOUT, retries=0)
+        elapsed, outcome = _timed(client.database.list)
+
+    _assert_timed_out(outcome)
+    _assert_one_bound(elapsed)
+
+
+def test_a_second_call_is_held_to_the_clients_bound_too(make_client: ClientFactory) -> None:
+    with SlowBody(trickle=TRICKLE) as server:
+        client = make_client(base_url=server.url, timeout=TIMEOUT, retries=0)
+        first, first_outcome = _timed(client.database.list)
+        second, second_outcome = _timed(client.database.list)
+
+    _assert_timed_out(first_outcome)
+    _assert_one_bound(first)
+    _assert_timed_out(second_outcome)
+    _assert_one_bound(second)
+
+
+# The bound is on each ATTEMPT, so a retried call takes one bound per attempt in total.
+def test_a_timed_out_attempt_is_retried_under_a_bound_of_its_own(
+    make_client: ClientFactory, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setattr(_core, "_BACKOFF_BASE", 0.0)
+    with SlowBody(trickle=TRICKLE) as server:
+        client = make_client(base_url=server.url, timeout=TIMEOUT, retries=1)
+        elapsed, outcome = _timed(client.database.list)
+
+    assert server.paths == [LIST_PATH, LIST_PATH], "a timed-out attempt was not retried"
+    _assert_timed_out(outcome)
+    assert 2 * TIMEOUT - 0.05 <= elapsed < 2 * TIMEOUT + SLACK, (
+        f"two attempts took {elapsed:.2f}s, not one bound each"
+    )
+
+
+def test_the_default_timeout_is_thirty_seconds() -> None:
+    for client in (InternetData, AsyncInternetData):
+        assert inspect.signature(client).parameters["timeout"].default == 30
+
+
+# Refused before the network, and never retried: a typo is the caller's, not a failure of
+# the server's to wait out.
+def test_an_unpublished_format_is_refused_before_any_request(make_client: ClientFactory) -> None:
+    stub = Stub({CHECKSUM_PATH: {"body": {"checksums": {"sha256": "00"}}}})
+    client = make_client(transport=stub.transport, retries=2)
+
+    started = time.monotonic()
+    with pytest.raises(ValueError, match="zip"):
+        client.database.checksums("bogon_ip_v1", "zip")
+
+    assert stub.requests == []
+    assert time.monotonic() - started < 0.5, "the refusal was retried"
+
+
 def test_the_base_url_is_overridable(make_client: ClientFactory) -> None:
     stub = Stub({LIST_PATH: {"body": {"databases": []}}})
     client = make_client(transport=stub.transport)
@@ -236,3 +330,22 @@ def test_a_value_this_client_was_not_generated_for_stays_inside_the_error_type(
 
     assert caught.value.kind == "server_error"
     assert "trial" in caught.value.message, "the message does not say which value it choked on"
+
+
+def _timed(call: Callable[[], Any]) -> tuple[float, Any]:
+    """How long `call` took to settle, and what it settled with."""
+    started = time.monotonic()
+    outcome = settle(call)
+    return time.monotonic() - started, outcome
+
+
+def _assert_timed_out(outcome: Any) -> None:
+    assert isinstance(outcome, InternetDataError), f"settled with {outcome!r}"
+    assert outcome.kind == "network", outcome
+    assert outcome.retryable is True
+
+
+def _assert_one_bound(elapsed: float) -> None:
+    assert TIMEOUT - 0.05 <= elapsed < TIMEOUT + SLACK, (
+        f"gave up after {elapsed:.2f}s against a {TIMEOUT}s bound"
+    )

{internetdata-2.0.0 → internetdata-2.1.0}/tests/test_download.py

@@ -9,6 +9,7 @@ and where it did not.
 from __future__ import annotations
 
 import gzip
+import time
 import tracemalloc
 from collections.abc import AsyncIterator, Iterator
 from dataclasses import dataclass
@@ -16,9 +17,17 @@ from pathlib import Path
 
 import httpx
 import pytest
-from helpers import API, API_KEY, DOWNLOAD_PATH, ClientAdapter, ClientFactory
-
-from internetdata import InternetDataError
+from helpers import (
+    API,
+    API_KEY,
+    DOWNLOAD_PATH,
+    ClientAdapter,
+    ClientFactory,
+    SlowTransfer,
+    settle,
+)
+
+from internetdata import InternetDataError, _core
 
 STORAGE = "https://storage.example"
 BLOB = f"{STORAGE}/blob?X-Amz-Signature=deadbeef"
@@ -35,7 +44,8 @@ class Blob:
     A `size` of zero is the small CSV nearly every test wants. Above that the body is
     synthetic, and `delivered` under `size` promises a whole database and cuts it short,
     which is the silent truncation a client has to catch. `dies` makes that shortfall
-    arrive as a dropped connection instead of a clean end of body.
+    arrive as a dropped connection instead of a clean end of body. `refusals` is how many
+    requests are answered 503 before the blob is served.
     """
 
     size: int = 0
@@ -43,6 +53,7 @@ class Blob:
     dies: bool = False
     status: int = 200
     encoding: str | None = None
+    refusals: int = 0
 
 
 class Origin:
@@ -75,6 +86,8 @@ class Origin:
             return httpx.Response(302, headers={"Location": BLOB})
         if str(request.url) != BLOB:
             return httpx.Response(404, json={"rc": "UNKNOWN_DATASET"})
+        if self.paths().count("/blob") <= self.blob.refusals:
+            return httpx.Response(503)
         if self.blob.status != 200:
             return httpx.Response(self.blob.status, content=b"<Error><Code>AccessDenied</Code>")
 
@@ -118,9 +131,11 @@ class BlobStream(httpx.SyncByteStream, httpx.AsyncByteStream):
             raise httpx.ReadError("the connection dropped mid-transfer")
 
 
-def origin(make_client: ClientFactory, blob: Blob | None = None) -> Origin:
+def origin(make_client: ClientFactory, blob: Blob | None = None, retries: int = 2) -> Origin:
     served = Origin(blob or Blob())
-    served.client = make_client(api_key=API_KEY, base_url=API, transport=served.transport)
+    served.client = make_client(
+        api_key=API_KEY, base_url=API, transport=served.transport, retries=retries
+    )
     return served
 
 
@@ -289,3 +304,64 @@ def test_a_content_encoded_body_is_not_mistaken_for_a_short_one(
     served = origin(make_client, Blob(encoding="gzip"))
 
     assert served.client.database.download_bytes("bogon_ip_v1", "csvgz") == SMALL
+
+
+# Only the response HEAD of a transfer is retried. A 5xx there has written nothing, so it is
+# as transient as the API's; a body that dies part way is never fetched again, or the second
+# copy would append to the bytes already written. Each half pins the other, so neither passes
+# vacuously, and each counts storage requests before it looks at the outcome.
+def test_a_storage_5xx_before_the_body_is_retried(
+    make_client: ClientFactory, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setattr(_core, "_BACKOFF_BASE", 0.0)
+    served = origin(make_client, Blob(refusals=1), retries=2)
+
+    outcome: bytes | Exception
+    try:
+        outcome = served.client.database.download_bytes("bogon_ip_v1", "csvgz")
+    except (InternetDataError, httpx.HTTPError) as exc:
+        outcome = exc
+
+    assert served.paths().count("/blob") == 2, "object storage should see the 503 and its retry"
+    assert outcome == SMALL
+
+
+@pytest.mark.parametrize("method", ["download", "download_bytes"])
+def test_a_transfer_that_dies_part_way_is_not_fetched_again(
+    make_client: ClientFactory, tmp_path: Path, monkeypatch: pytest.MonkeyPatch, method: str
+) -> None:
+    monkeypatch.setattr(_core, "_BACKOFF_BASE", 0.0)
+    served = origin(make_client, Blob(size=4 << 20, delivered=1 << 20, dies=True), retries=2)
+    rest = (tmp_path / "dies-once.csv.gz",) if method == "download" else ()
+
+    failure: Exception | None = None
+    try:
+        getattr(served.client.database, method)("bogon_ip_v1", "csvgz", *rest)
+    except (InternetDataError, httpx.HTTPError) as exc:
+        failure = exc
+
+    assert served.paths().count("/blob") == 1, "a body that died part way was fetched again"
+    assert isinstance(failure, httpx.ReadError), f"got {failure!r}"
+
+
+# A transfer runs to gigabytes and minutes, so the timeout that bounds every JSON call must
+# cut one off neither in total nor at a gap between two reads. On a real socket, because a
+# mocked transport never consults a timeout.
+@pytest.mark.parametrize("method", ["download", "download_bytes"])
+def test_a_transfer_that_outlasts_the_timeout_still_completes(
+    make_client: ClientFactory, tmp_path: Path, method: str
+) -> None:
+    timeout = 0.3
+    path = tmp_path / "slow.mmdb"
+    rest = (path,) if method == "download" else ()
+    with SlowTransfer(pause=2 * timeout) as server:
+        client = make_client(base_url=server.url, timeout=timeout, retries=0)
+        started = time.monotonic()
+        outcome = settle(lambda: getattr(client.database, method)("bogon_ip_v1", "mmdb", *rest))
+        elapsed = time.monotonic() - started
+
+    assert server.paths == [DOWNLOAD_PATH, "/blob"]
+    assert not isinstance(outcome, BaseException), f"the transfer failed: {outcome!r}"
+    assert elapsed > 2 * timeout, f"took {elapsed:.2f}s, inside the timeout, so this proves nothing"
+    held = path.read_bytes() if method == "download" else outcome
+    assert held == SlowTransfer.BODY