fix(purl): define strict response semantics

Author: lelia

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "socketdev"
-version = "3.4.0"
+version = "3.4.2"
 requires-python = ">= 3.9"
 dependencies = [
     'requests',

socketdev/exceptions.py

@@ -91,9 +91,18 @@ class APIPartialResponse(APIFailure):
     to diff the response themselves.
 
     The ``missing`` attribute holds the requested purls that were absent from the
-    response (the HTTP call itself succeeded, so there is no status code).
+    response (the HTTP call itself succeeded, so there is no status code). A missing
+    row may reflect pending analysis, a malformed or unknown purl, or a response contract
+    failure, so blindly retrying is not guaranteed to succeed. Callers that need a bounded
+    wait should use ``poll=True``; callers that need omission reasons should request
+    ``alerts=True`` and/or ``purl_errors=True``.
     """
 
     def __init__(self, *args, missing=None):
         super().__init__(*args)
         self.missing = list(missing or [])
+
+    def is_transient_error(self) -> bool:
+        # The HTTP request completed successfully, and the omission reason may be
+        # permanent. Server-side polling is the explicit bounded retry mechanism.
+        return False

socketdev/purl/__init__.py

@@ -46,12 +46,15 @@ def post(
                 unresolved inputs, so callers can distinguish "no data yet" from "clean".
             purl_errors: when ``True`` (``→ purlErrors``), the server includes per-purl
                 error rows for malformed/unresolvable inputs. ``None`` omits the param.
-            strict: client-side guard. When ``True``, compares the ``purl`` of each
-                requested component against the ``inputPurl``/``purl`` of the returned
-                rows and raises :class:`~socketdev.exceptions.APIPartialResponse` (with a
-                ``missing`` list) if any requested purl is absent from the response. This
-                surfaces partial batches even without ``alerts=True``. Only components that
-                carry a ``purl`` string are checked.
+            strict: client-side guard. When ``True``, compares the exact ``purl`` string
+                of each requested component against the returned ``inputPurl`` (or the
+                ``purl`` fallback). The API defines ``inputPurl`` as the original,
+                unmodified input before server normalization, so canonicalized ``purl``
+                values do not cause false omissions. Raises
+                :class:`~socketdev.exceptions.APIPartialResponse` (with a ``missing``
+                list) if any requested purl is absent from the response. This surfaces
+                partial batches even without ``alerts=True``. Only components that carry
+                a ``purl`` string are checked.
             **kwargs: forwarded verbatim into the query string (back-compat passthrough for
                 any params not yet promoted to first-class arguments).
 
@@ -127,9 +130,11 @@ def post(
     def _raise_on_missing(components: list, results: list) -> None:
         """Raise APIPartialResponse if any requested component purl is absent from results.
 
-        Only components exposing a ``purl`` string are checked; the batch API echoes the
-        request identifier back as ``inputPurl`` (falling back to ``purl``), including
-        under ``value`` for typed ``purlError`` stream records.
+        Only components exposing a ``purl`` string are checked. The batch API contract
+        defines ``inputPurl`` as the original, unmodified input string before server-side
+        normalization, so matching it exactly preserves the caller's identity even when
+        the response's canonical ``purl`` differs. ``purl`` is retained as a fallback,
+        and typed ``purlError`` stream records carry ``inputPurl`` under ``value``.
         """
         requested = [
             c["purl"]

socketdev/version.py

@@ -1 +1 @@
-__version__ = "3.4.0"
+__version__ = "3.4.2"

tests/unit/test_all_endpoints_unit.py

@@ -528,6 +528,21 @@ def test_purl_post_strict_passes_when_complete(self):
         )
         self.assertEqual(len(result), 1)
 
+    def test_purl_post_strict_matches_original_input_before_normalization(self):
+        """strict=True matches exact inputPurl even when the canonical purl differs."""
+        requested_purl = "pkg:npm/%40scope/pkg@1.0.0"
+        server_rows = [
+            {
+                "inputPurl": requested_purl,
+                "purl": "pkg:npm/@scope/pkg@1.0.0",
+            }
+        ]
+
+        self.sdk.purl._raise_on_missing(
+            [{"purl": requested_purl}],
+            server_rows,
+        )
+
     # Quota endpoints
     def test_quota_get_unit(self):
         """Test quota retrieval."""

tests/unit/test_exceptions.py

@@ -25,6 +25,7 @@
     APIInsufficientPermissions,
     APIInsufficientQuota,
     APIOrganizationNotAllowed,
+    APIPartialResponse,
     APIResourceNotFound,
     APITimeout,
 )
@@ -51,6 +52,11 @@ def test_connection_level_classes_are_transient(self):
         self.assertTrue(APIConnectionError().is_transient_error())
         self.assertTrue(APIBadGateway().is_transient_error())
 
+    def test_partial_response_is_not_transient(self):
+        error = APIPartialResponse("incomplete", missing=["pkg:npm/missing@1.0.0"])
+        self.assertFalse(error.is_transient_error())
+        self.assertEqual(error.missing, ["pkg:npm/missing@1.0.0"])
+
     def test_bad_gateway_carries_502_by_default(self):
         self.assertEqual(APIBadGateway().status_code, 502)