feat(common): report the client fingerprint like the Go SDK

The server cannot tell which SDK, version or platform a request came from, so
breaking changes can only be assessed after customers report them. Send the
same six identity headers the Go SDK already sends, plus the per-request retry
count and deadline, using its spellings so the two languages aggregate into the
same buckets.

Author: moonyue-w

src/qca/common/_base_client.py

@@ -16,6 +16,7 @@
 from ._exceptions import APIConnectionError, APIResponseValidationError, APITimeoutError, status_error
 from ._files import multipart_parts
 from ._models import parse_response
+from ._platform import platform_headers
 from ._response import (
     APIResponse,
     AsyncAPIResponse,
@@ -33,6 +34,15 @@
 DEFAULT_TIMEOUT = httpx.Timeout(60.0, connect=10.0)
 
 
+def _timeout_seconds(timeout: Any) -> int | None:
+    """The deadline the server should expect, in whole seconds like the Go SDK."""
+    if isinstance(timeout, httpx.Timeout):
+        timeout = timeout.read
+    if isinstance(timeout, bool) or not isinstance(timeout, (int, float)):
+        return None
+    return int(timeout)
+
+
 class BaseClient:
     _client: Any
     _default_base_url: str
@@ -111,7 +121,14 @@ def is_closed(self) -> bool:
         return self._client.is_closed
 
     def _headers(self, options: dict[str, Any], token: str | None) -> httpx.Headers:
-        headers = httpx.Headers({"Accept": "application/json", "User-Agent": f"qca-python/{__version__}"})
+        headers = httpx.Headers(
+            {
+                "Accept": "application/json",
+                "User-Agent": f"qca-python/{__version__}",
+                "X-Qoder-Retry-Count": "0",
+                **platform_headers(),
+            }
+        )
         if token:
             headers["Authorization"] = f"Bearer {token}"
         for source in (self.default_headers, options.get("headers", {})):
@@ -129,12 +146,17 @@ def _request_args(
     ) -> dict[str, Any]:
         headers = self._headers(options, token)
         timeout = options.get("timeout", NOT_GIVEN)
+        effective_timeout = self.timeout if isinstance(timeout, NotGiven) else timeout
+        if "X-Qoder-Timeout" not in headers:
+            seconds = _timeout_seconds(effective_timeout)
+            if seconds:
+                headers["X-Qoder-Timeout"] = str(seconds)
         args = dict(
             method=method,
             url=self.base_url.join(path.lstrip("/")),
             headers=headers,
             params=query_pairs({**self.default_query, **options.get("query", {})}),
-            timeout=self.timeout if isinstance(timeout, NotGiven) else timeout,
+            timeout=effective_timeout,
         )
         if file_fields:
             args["files"] = multipart_parts(options.get("body", {}), file_fields)
@@ -244,7 +266,10 @@ def __init__(
         self._client = http_client or httpx.Client(timeout=timeout, follow_redirects=False)
 
     def _send(self, request: httpx.Request, *, storage: bool = False) -> httpx.Response:
+        track_retries = request.headers.get("X-Qoder-Retry-Count") == "0"
         for attempt in range(self.max_retries + 1):
+            if track_retries and attempt:
+                request.headers["X-Qoder-Retry-Count"] = str(attempt)
             if (
                 not storage
                 and self.credential
@@ -359,7 +384,10 @@ def __init__(
         self._client = http_client or httpx.AsyncClient(timeout=timeout, follow_redirects=False)
 
     async def _send(self, request: httpx.Request, *, storage: bool = False) -> httpx.Response:
+        track_retries = request.headers.get("X-Qoder-Retry-Count") == "0"
         for attempt in range(self.max_retries + 1):
+            if track_retries and attempt:
+                request.headers["X-Qoder-Retry-Count"] = str(attempt)
             if (
                 not storage
                 and self.credential

src/qca/common/_platform.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import platform
+
+from qca._version import __version__
+
+# The spellings match the Go SDK's convention/requestconfig.go on purpose: the
+# server aggregates SDK usage across languages, so the same machine has to land
+# in the same bucket no matter which SDK called. platform.machine() and Go's
+# runtime.GOARCH name the same architecture differently, hence the aliases.
+_OS_NAMES = {
+    "darwin": "MacOS",
+    "windows": "Windows",
+    "linux": "Linux",
+    "ios": "iOS",
+    "android": "Android",
+    "freebsd": "FreeBSD",
+    "openbsd": "OpenBSD",
+}
+
+_ARCH_NAMES = {
+    "386": "x32",
+    "i386": "x32",
+    "i686": "x32",
+    "x86": "x32",
+    "amd64": "x64",
+    "x86_64": "x64",
+    "arm": "arm",
+    "armv7l": "arm",
+    "arm64": "arm64",
+    "aarch64": "arm64",
+}
+
+
+def platform_headers() -> dict[str, str]:
+    system = platform.system().lower()
+    machine = platform.machine().lower()
+    return {
+        "X-Qoder-Lang": "python",
+        "X-Qoder-Package-Version": __version__,
+        "X-Qoder-OS": _OS_NAMES.get(system, f"Other:{system or 'unknown'}"),
+        "X-Qoder-Arch": _ARCH_NAMES.get(machine, f"other:{machine or 'unknown'}"),
+        "X-Qoder-Runtime": platform.python_implementation(),
+        "X-Qoder-Runtime-Version": platform.python_version(),
+    }

tests/test_client.py

@@ -3,6 +3,7 @@
 import asyncio
 import io
 import json
+import platform
 from datetime import datetime, timezone
 from email.parser import BytesParser
 from email.policy import default
@@ -28,6 +29,7 @@
     PermissionDeniedError,
     RateLimitError,
     UnprocessableEntityError,
+    __version__,
 )
 
 
@@ -100,6 +102,43 @@ def test_query_arrays_and_special_headers():
     assert json.loads(requests[1].content) == {"events": []}
 
 
+def test_client_fingerprint_reports_language_version_platform_and_deadline():
+    requests = []
+    with make_client(lambda request: requests.append(request) or httpx.Response(200, json={"data": []})) as client:
+        client.models.list()
+        client.models.list(timeout=7)
+    headers = requests[0].headers
+    assert headers["user-agent"] == f"qca-python/{__version__}"
+    assert headers["x-qoder-lang"] == "python"
+    assert headers["x-qoder-package-version"] == __version__
+    assert headers["x-qoder-runtime"] == platform.python_implementation()
+    assert headers["x-qoder-runtime-version"] == platform.python_version()
+    # Normalized rather than platform.system()/machine() raw, so that the same
+    # machine lands in the same server-side bucket as the Go and TS SDKs.
+    assert headers["x-qoder-os"] in {"MacOS", "Windows", "Linux", "iOS", "Android", "FreeBSD", "OpenBSD"}
+    assert headers["x-qoder-arch"] in {"x32", "x64", "arm", "arm64"}
+    assert headers["x-qoder-retry-count"] == "0"
+    assert headers["x-qoder-timeout"] == "60"
+    assert requests[1].headers["x-qoder-timeout"] == "7"
+
+
+def test_client_fingerprint_yields_to_caller_and_omits_absent_deadline():
+    requests = []
+
+    def handle(request):
+        requests.append(request)
+        return httpx.Response(200, json={"data": []})
+
+    with make_client(handle, default_headers={"X-Qoder-Lang": "cli", "X-Qoder-Timeout": "5"}) as client:
+        client.models.list(extra_headers={"User-Agent": "caller/1.0"})
+    with make_client(handle) as client:
+        client.models.list(timeout=None)
+    assert requests[0].headers["x-qoder-lang"] == "cli"
+    assert requests[0].headers["x-qoder-timeout"] == "5"
+    assert requests[0].headers["user-agent"] == "caller/1.0"
+    assert "x-qoder-timeout" not in requests[1].headers
+
+
 def test_datetime_and_nested_query_serialization():
     requests = []
     with make_client(lambda request: requests.append(request) or httpx.Response(200, json={"data": []})) as client:
@@ -210,6 +249,22 @@ def handle(request):
     assert len(calls) == 1
 
 
+def test_retry_count_header_reports_the_attempt_number(monkeypatch):
+    monkeypatch.setattr("qca.common._base_client.time.sleep", lambda _: None)
+    counts = []
+
+    # Read inside the handler: the request object is reused across attempts, so
+    # inspecting it afterwards would only show the last value.
+    def handle(request):
+        counts.append(request.headers["x-qoder-retry-count"])
+        return httpx.Response(500, json={})
+
+    with make_client(handle) as client:
+        with pytest.raises(APIStatusError):
+            client.models.list()
+    assert counts == ["0", "1", "2"]
+
+
 def test_connection_timeout_and_non_json_error(monkeypatch):
     monkeypatch.setattr("qca.common._base_client.time.sleep", lambda _: None)
     for exc_type, expected in [(httpx.ConnectError, APIConnectionError), (httpx.ReadTimeout, APITimeoutError)]:
@@ -319,7 +374,10 @@ def handle(request):
         requests.append(request)
         if request.url.host == "api.test":
             return httpx.Response(200, json={"url": "https://storage.test/asset?signed=true"})
-        assert not any(k in request.headers for k in ("authorization", "cookie", "x-sensitive", "qoder-workspace-id"))
+        assert not any(
+            k in request.headers
+            for k in ("authorization", "cookie", "x-sensitive", "qoder-workspace-id", "x-qoder-lang")
+        )
         return httpx.Response(200, content=b"content")
 
     http = httpx.Client(
@@ -486,3 +544,21 @@ def handle(request):
     assert len(calls) == count
     assert sleeps == [0.025] * (count - 1)
     assert len({request.content for request in calls}) == 1
+
+
+async def test_async_retry_count_header_reports_the_attempt_number(monkeypatch):
+    async def pause(delay):
+        return None
+
+    monkeypatch.setattr("qca.common._base_client.anyio.sleep", pause)
+    counts = []
+
+    def handle(request):
+        counts.append(request.headers["x-qoder-retry-count"])
+        return httpx.Response(500, json={})
+
+    transport = httpx.MockTransport(handle)
+    async with AsyncForward(access_token="test", http_client=httpx.AsyncClient(transport=transport)) as client:
+        with pytest.raises(APIStatusError):
+            await client.models.list()
+    assert counts == ["0", "1", "2"]