fix(scan): degrade proxy batch validation 400s to per-package GETs

The proxy batch endpoint validates its component list all-or-nothing,
so a single crawled PURL of a type the server doesn't recognize (e.g.
pkg:jsr/... from the Deno crawler) rejected the whole chunk and, when
every chunk contained one, flipped the entire scan to exit 1. The
docker e2e deno JSR test caught this against the production proxy:
scan crawled 4 jsr packages, the one batch POST 400'd, and the scan
errored where the old per-package GET path had quietly tolerated the
unresolvable PURLs one by one.

A validation 400 on the proxy batch POST now degrades the chunk to the
legacy per-package GET path, whose per-PURL error swallowing is the
scan semantic that predates the batch optimization: the valid subset
still resolves, the exotic PURLs stay patch-less, and the scan
succeeds. Rate limits, auth statuses, and over-capacity 503s still
surface. is_batch_unsupported keeps detecting deployment-level absence
only; the two fallback causes are logged distinctly.

Verified against the real patches-api.socket.dev with a synthetic JSR
layout: scan now exits 0 with scannedPackages=4 and the debug trace
shows batch POST -> validation 400 -> 4 tolerated per-package GETs.

Assisted-by: Claude Code:claude-fable-5

Author: mikolalysenko

CHANGELOG.md

@@ -51,10 +51,13 @@ in this file — see `.github/workflows/release.yml` (`version` job).
 - **Token-less `scan` now batch-queries the public proxy.** Proxy-mode scans
   POST `{proxy}/patch/batch` (one request per `--batch-size` chunk, mirroring
   the authenticated `/v0/orgs/{slug}/patches/batch` endpoint) instead of
-  issuing one `GET /patch/by-package/:purl` per package. Against proxies that
-  predate the batch endpoint, the client transparently degrades to the legacy
-  per-package GET path; rate limits and over-capacity 503s still surface
-  instead of silently degrading. (MINOR)
+  issuing one `GET /patch/by-package/:purl` per package. The client
+  transparently degrades to the legacy per-package GET path against proxies
+  that predate the batch endpoint, and when the all-or-nothing batch
+  validation rejects a chunk (e.g. a crawled PURL type the server doesn't
+  recognize, such as `pkg:jsr/…` — per-package queries tolerate those
+  individually, so one exotic package can't fail a whole scan). Rate limits
+  and over-capacity 503s still surface instead of silently degrading. (MINOR)
 
 ## [3.2.0] — 2026-05-29
 

crates/socket-patch-cli/CLI_CONTRACT.md

@@ -69,7 +69,7 @@ Beyond the globals above, each subcommand defines a small set of local arguments
 
 `scan --prune` opts into garbage collection. When set, `scan` removes manifest entries for packages no longer present in the crawl, then deletes orphan blob, diff, and package-archive files from `.socket/`. Off by default (v3.0) so a temporary uninstall doesn't silently destroy manifest state.
 
-`scan` queries the patch API in `--batch-size` chunks. Authenticated runs POST `/v0/orgs/{slug}/patches/batch`; token-less runs POST `{proxy}/patch/batch` on the public proxy and degrade to per-package `GET /patch/by-package/:purl` requests only when the deployed proxy predates the batch endpoint (legacy proxies answer the POST with their `400 "Unsupported endpoint"` catch-all). Validation errors, rate limits, and over-capacity 503s surface instead of silently degrading.
+`scan` queries the patch API in `--batch-size` chunks. Authenticated runs POST `/v0/orgs/{slug}/patches/batch`; token-less runs POST `{proxy}/patch/batch` on the public proxy and degrade to per-package `GET /patch/by-package/:purl` requests in two cases: the deployed proxy predates the batch endpoint (legacy proxies answer the POST with their `400 "Unsupported endpoint"` catch-all), or the all-or-nothing batch validation rejects the chunk (e.g. a crawled PURL type the server doesn't recognize, such as `pkg:jsr/…` — the per-package path tolerates those individually, preserving the pre-batch scan semantics). Rate limits and over-capacity 503s surface instead of silently degrading.
 
 `scan --sync` is sugar for `--apply --prune` — the canonical single-flag bot invocation. `scan --json --sync --yes` discovers, applies, and reconciles state in one pass.
 

crates/socket-patch-core/src/api/client.rs

@@ -297,12 +297,12 @@ impl ApiClient {
         }
 
         // Public proxy: prefer the POST /patch/batch endpoint; degrade to
-        // individual per-package GET requests against proxies that predate
-        // it (see `is_batch_unsupported`).
+        // individual per-package GET requests when the deployed proxy
+        // predates it or when batch validation rejects the chunk (see
+        // `proxy_batch_post` for the decision table).
         match self.proxy_batch_post(purls).await? {
             Some(response) => Ok(response),
             None => {
-                debug_log("proxy batch endpoint unavailable; falling back to individual queries");
                 self.search_patches_batch_via_individual_queries(purls)
                     .await
             }
@@ -312,12 +312,24 @@ impl ApiClient {
     /// Internal: POST the batch search to the public proxy's
     /// `/patch/batch` endpoint.
     ///
-    /// Returns `Ok(None)` when the deployed proxy predates the batch
-    /// endpoint (see [`is_batch_unsupported`]) so the caller can degrade to
-    /// the legacy per-package GET path. Auth / rate-limit statuses are
-    /// classified via `classify_auth_error` exactly like the JSON
-    /// transport — 401/403 keep feeding `is_fallback_candidate` and 429
-    /// stays visible — and any other failure surfaces as an error.
+    /// Returns `Ok(None)` when the caller should degrade to the legacy
+    /// per-package GET path, in two situations:
+    ///
+    /// 1. The deployed proxy predates the batch endpoint (see
+    ///    [`is_batch_unsupported`]).
+    /// 2. The batch endpoint rejected the chunk with a validation `400`.
+    ///    Batch validation is all-or-nothing, so a single crawled PURL of
+    ///    a type the server doesn't recognize (e.g. `pkg:jsr/…` from the
+    ///    Deno crawler) rejects every package in the chunk. The
+    ///    per-package GET path tolerates such PURLs individually — each
+    ///    failure is swallowed per-package — which is the scan semantic
+    ///    that predates the batch optimization and must be preserved: one
+    ///    exotic package must not turn a whole scan into an error.
+    ///
+    /// Auth / rate-limit statuses are classified via `classify_auth_error`
+    /// exactly like the JSON transport — 401/403 keep feeding
+    /// `is_fallback_candidate` and 429 stays visible — and any other
+    /// failure (including over-capacity 503s) surfaces as an error.
     async fn proxy_batch_post(
         &self,
         purls: &[String],
@@ -356,7 +368,22 @@ impl ApiClient {
         }
 
         let text = resp.text().await.unwrap_or_default();
-        if is_batch_unsupported(status, &text) {
+        let fallback_reason = if is_batch_unsupported(status, &text) {
+            Some("proxy batch endpoint unavailable")
+        } else if status == StatusCode::BAD_REQUEST {
+            // All-or-nothing batch validation rejected the chunk; the
+            // per-package path resolves the valid subset (see doc above).
+            Some("proxy batch validation rejected the chunk")
+        } else {
+            None
+        };
+        if let Some(reason) = fallback_reason {
+            debug_log(&format!(
+                "{} (status {}: {}); falling back to individual queries",
+                reason,
+                status.as_u16(),
+                text
+            ));
             return Ok(None);
         }
         Err(ApiError::Other(format!(
@@ -870,12 +897,14 @@ fn classify_auth_error(status: StatusCode, use_public_proxy: bool) -> Option<Api
 ///
 /// The `"Unsupported endpoint"` marker is a cross-repo contract with the
 /// depscan firewall-api-proxy: its catch-all answers unknown routes with
-/// `400 {"error":"Unsupported endpoint",...}`, while genuine batch
-/// validation failures use different wording and must surface to the
-/// operator instead of silently degrading. Likewise for 503, only the
-/// "Patch API is not configured" body (patch endpoints disabled) degrades —
-/// an over-capacity 503 ("Service temporarily over capacity") surfaces
-/// rather than amplifying load tenfold via the per-package fallback.
+/// `400 {"error":"Unsupported endpoint",...}`. Batch validation failures
+/// use different wording and are deliberately NOT matched here — the
+/// caller (`proxy_batch_post`) still degrades them to the per-package
+/// path, but logs them as a chunk-validation rejection rather than a
+/// missing endpoint. For 503, only the "Patch API is not configured"
+/// body (patch endpoints disabled) degrades — an over-capacity 503
+/// ("Service temporarily over capacity") surfaces rather than amplifying
+/// load tenfold via the per-package fallback.
 fn is_batch_unsupported(status: StatusCode, body: &str) -> bool {
     match status {
         StatusCode::BAD_REQUEST => body.contains("Unsupported endpoint"),
@@ -1613,7 +1642,11 @@ mod tests {
     }
 
     #[test]
-    fn is_batch_unsupported_surfaces_genuine_validation_400() {
+    fn is_batch_unsupported_does_not_match_validation_400() {
+        // Validation 400s are not "endpoint missing" — the caller still
+        // degrades them to the per-package path (all-or-nothing batch
+        // validation must not fail a whole scan over one exotic PURL),
+        // but via the chunk-validation branch with its own log line.
         assert!(!is_batch_unsupported(
             StatusCode::BAD_REQUEST,
             r#"{"error":"Invalid PURL format"}"#,

crates/socket-patch-core/tests/proxy_batch_e2e.rs

@@ -143,34 +143,78 @@ async fn proxy_batch_degrades_when_patch_api_unconfigured_503() {
 }
 
 #[tokio::test]
-async fn proxy_batch_validation_400_surfaces_without_fallback() {
+async fn proxy_batch_validation_400_degrades_to_per_package_gets() {
+    // The batch endpoint validates the component list all-or-nothing, so a
+    // chunk mixing a supported PURL with one the server doesn't recognize
+    // (e.g. pkg:jsr/… from the Deno crawler) is rejected wholesale. The
+    // valid subset must still resolve via the per-package path instead of
+    // failing the scan.
     let server = MockServer::start().await;
     Mock::given(method("POST"))
         .and(path("/patch/batch"))
-        .respond_with(
-            ResponseTemplate::new(400).set_body_json(json!({ "error": "Invalid PURL format" })),
-        )
+        .respond_with(ResponseTemplate::new(400).set_body_json(json!({
+            "error": {
+                "message": "Invalid PURL format. Must include ecosystem type and package name.",
+                "details": null
+            }
+        })))
         .expect(1)
         .mount(&server)
         .await;
-    mount_by_package(&server, by_package_response_body(), 0).await;
+    mount_by_package(&server, by_package_response_body(), 1).await;
 
     let client = proxy_client(&server.uri());
-    let err = client
+    let resp = client
         .search_patches_batch(None, &[PURL.to_string()])
         .await
-        .expect_err("a genuine validation 400 must surface, not silently degrade");
-
-    match &err {
-        ApiError::Other(msg) => {
-            assert!(msg.contains("400"), "must embed the status; got: {msg}");
-            assert!(
-                msg.contains("Invalid PURL format"),
-                "must embed the body; got: {msg}"
-            );
-        }
-        other => panic!("validation 400 must be Other; got: {other:?}"),
-    }
+        .expect("validation 400 must degrade to per-package GETs, not error");
+
+    assert_eq!(resp.packages.len(), 1, "fallback results must be assembled");
+    assert_eq!(resp.packages[0].purl, PURL);
+}
+
+#[tokio::test]
+async fn proxy_batch_validation_400_with_failing_gets_yields_empty_ok() {
+    // Regression shape of the Deno JSR docker e2e: every crawled PURL is a
+    // type the server rejects (pkg:jsr/…), so the batch 400s AND each
+    // per-package GET 400s. The per-package path swallows those individual
+    // failures, so the scan-level result is an empty success — not an
+    // error that flips the whole scan's exit code.
+    let server = MockServer::start().await;
+    Mock::given(method("POST"))
+        .and(path("/patch/batch"))
+        .respond_with(ResponseTemplate::new(400).set_body_json(json!({
+            "error": {
+                "message": "Invalid PURL format. Must include ecosystem type and package name.",
+                "details": null
+            }
+        })))
+        .expect(1)
+        .mount(&server)
+        .await;
+    Mock::given(method("GET"))
+        .and(path_regex(r"^/patch/by-package/.*$"))
+        .respond_with(ResponseTemplate::new(400).set_body_json(json!({
+            "error": {
+                "message": "Invalid PURL format. Must include ecosystem type and package name.",
+                "details": null
+            }
+        })))
+        .expect(1)
+        .mount(&server)
+        .await;
+
+    let client = proxy_client(&server.uri());
+    let resp = client
+        .search_patches_batch(None, &["pkg:jsr/@std/path@0.220.0".to_string()])
+        .await
+        .expect("per-purl failures are swallowed; the batch call must not error");
+
+    assert!(
+        resp.packages.is_empty(),
+        "an unresolvable PURL yields no packages, not an error"
+    );
+    assert!(!resp.can_access_paid_patches);
 }
 
 #[tokio::test]