Make truncation visible and name the cause when a request is refused for size

Two follow-on safeguards for the same failure, both aimed at CI runs where no one
is watching a terminal.

Truncation was silent: the notice sat at DEBUG, which a pipeline that does not
pass --enable-debug never prints, and the stored value gave no sign it had been
clipped. The notice moves to INFO and the value now ends in "...". The
200-character ceiling is unchanged -- the marker replaces the tail rather than
extending past it -- so the request line is no larger than before.

A request line the proxy refuses comes back as 413, 414 or 431 depending on which
limit it checks, carrying the proxy's own response body and nothing about what to
change. Those statuses now raise with the cause and the flag to change named,
keeping the SDK's original text underneath. None of them were retried before and
none are now: the same oversized URL would go back out. Any oversized query
parameter is covered, not only the commit message.

Buildkite already gets the section markers and the soft_fail hint from
_emit_infrastructure_error, which this error reaches like any other API failure,
so nothing platform-specific is added here.

Author: lelia

CHANGELOG.md

@@ -13,6 +13,18 @@
 - The cap is now an invariant of the parsed configuration and is applied to the
   git-derived value as well, so every source of `commit_message` lands under the
   limit.
+- A truncated message now ends in `...` and the notice is logged at INFO instead
+  of DEBUG, so a clipped message in the dashboard is explained by the CI log of
+  the run that produced it. The 200-character ceiling is unchanged; the marker
+  replaces the tail rather than extending past it.
+
+### Changed: name the cause when a full scan request is refused for its size
+
+- Scan metadata travels in the query string of the full scan request, so an
+  oversized value is refused by the proxy in front of the API, which reports 413,
+  414 or 431 depending on which limit it checks. Those responses previously
+  surfaced as the SDK's generic status-code error carrying the proxy's response
+  body. They now name the cause and the flag to change, and remain unretried.
 
 ## 2.9.6
 

socketsecurity/config.py

@@ -27,14 +27,21 @@ def get_plugin_config_from_env(prefix: str) -> dict:
 MAX_COMMIT_MESSAGE_LENGTH = 200
 
 
+COMMIT_MESSAGE_TRUNCATION_MARKER = "..."
+
+
 def truncate_commit_message(commit_message: Optional[str]) -> Optional[str]:
     """Cap commit_message to a length the full-scan request line can carry."""
     if commit_message and len(commit_message) > MAX_COMMIT_MESSAGE_LENGTH:
-        logging.debug(
+        # Logged at INFO rather than DEBUG: the scan record keeps the truncated value, and
+        # a CI job that never passes --enable-debug would otherwise have no way to tell why
+        # the message in the dashboard is clipped.
+        logging.info(
             f"commit_message truncated from {len(commit_message)} to "
-            f"{MAX_COMMIT_MESSAGE_LENGTH} characters to avoid API request size limits"
+            f"{MAX_COMMIT_MESSAGE_LENGTH} characters to stay within API request size limits"
         )
-        return commit_message[:MAX_COMMIT_MESSAGE_LENGTH]
+        keep = MAX_COMMIT_MESSAGE_LENGTH - len(COMMIT_MESSAGE_TRUNCATION_MARKER)
+        return commit_message[:keep] + COMMIT_MESSAGE_TRUNCATION_MARKER
     return commit_message
 
 

socketsecurity/core/__init__.py

@@ -113,6 +113,13 @@
 FULL_SCAN_UPLOAD_MAX_ATTEMPTS = len(FULL_SCAN_UPLOAD_BACKOFF_SCHEDULE_SECONDS)
 FULL_SCAN_UPLOAD_BACKOFF_JITTER_SECONDS = 2.0
 
+# Statuses that mean the request line itself was rejected before the API read it: the
+# scan metadata (commit message, branch, committers) travels in the query string of the
+# full-scan POST, so an oversized value is refused by the proxy in front of the API. The
+# proxy picks the code -- 413 (payload), 414 (URI), 431 (headers) -- so all three map to
+# the same cause. Not transient: every retry sends the same oversized URL.
+REQUEST_TOO_LARGE_STATUS_CODES = (413, 414, 431)
+
 # Diff-scan polling policy. The legacy scan comparison (fullscans.stream_diff) holds a
 # single HTTP connection open, fully idle, while the backend computes the diff; network
 # middleboxes with TCP idle timeouts (notably Azure NAT gateways, which default to
@@ -1118,6 +1125,15 @@ def create_full_scan(self, files: List[str], params: FullScanParams, base_paths:
                     res = self.sdk.fullscans.post(upload_files, params, use_types=True, use_lazy_loading=True, max_open_files=50, base_paths=base_paths)
                     break
                 except APIFailure as error:
+                    if error.status_code in REQUEST_TOO_LARGE_STATUS_CODES:
+                        raise APIFailure(
+                            f"Full scan request rejected as too large (HTTP {error.status_code}). "
+                            "Scan metadata is sent in the request URL, so an oversized value -- "
+                            "most often the commit message -- is refused by the proxy in front of "
+                            "the API before the request is read. Pass a shorter --commit-message "
+                            f"to work around it.\n{error}",
+                            status_code=error.status_code,
+                        ) from error
                     if backoff_seconds is None or not error.is_transient_error():
                         raise
                     wait_seconds = backoff_seconds + random.uniform(

tests/unit/test_cli_config.py

@@ -31,14 +31,15 @@ def test_truncated_above_limit(self):
         config = CliConfig.from_args(
             ["--api-token", "test", "--commit-message", "a" * 250]
         )
-        assert config.commit_message == "a" * 200
+        assert config.commit_message == "a" * 197 + "..."
+        assert len(config.commit_message) == 200
 
     def test_quote_strip_runs_before_truncation(self):
         quoted = '"' + ("b" * 250) + '"'
         config = CliConfig.from_args(
             ["--api-token", "test", "--commit-message", quoted]
         )
-        assert config.commit_message == "b" * 200
+        assert config.commit_message == "b" * 197 + "..."
 
 
 class TestCliConfig:

tests/unit/test_commit_message_truncation.py

@@ -3,6 +3,7 @@
 import pytest
 
 from socketsecurity.config import (
+    COMMIT_MESSAGE_TRUNCATION_MARKER,
     MAX_COMMIT_MESSAGE_LENGTH,
     CliConfig,
     truncate_commit_message,
@@ -50,19 +51,29 @@ def test_at_limit_is_unchanged(self):
         assert truncate_commit_message(msg) == msg
 
     def test_over_limit_is_capped(self):
-        assert truncate_commit_message("a" * 14_000) == "a" * MAX_COMMIT_MESSAGE_LENGTH
+        capped = truncate_commit_message("a" * 14_000)
+        assert len(capped) == MAX_COMMIT_MESSAGE_LENGTH
+        assert capped.endswith(COMMIT_MESSAGE_TRUNCATION_MARKER)
+
+    def test_marker_fits_inside_the_limit(self):
+        # The marker replaces the tail rather than extending past it, so the capped value
+        # never grows the request line beyond what the proxy accepts.
+        assert truncate_commit_message("a" * 201) == (
+            "a" * (MAX_COMMIT_MESSAGE_LENGTH - len(COMMIT_MESSAGE_TRUNCATION_MARKER))
+            + COMMIT_MESSAGE_TRUNCATION_MARKER
+        )
 
 
 class TestCliConfigInvariant:
     def test_direct_construction_is_capped(self):
         config = CliConfig(api_token="test", repo="widgets", commit_message="a" * 14_000)
-        assert config.commit_message == "a" * MAX_COMMIT_MESSAGE_LENGTH
+        assert len(config.commit_message) == MAX_COMMIT_MESSAGE_LENGTH
 
     def test_config_file_value_is_capped(self, tmp_path):
         config_file = tmp_path / "socketcli.json"
         config_file.write_text('{"commit_message": "%s"}' % ("a" * 14_000), encoding="utf-8")
         config = CliConfig.from_args(["--api-token", "test", "--config", str(config_file)])
-        assert config.commit_message == "a" * MAX_COMMIT_MESSAGE_LENGTH
+        assert len(config.commit_message) == MAX_COMMIT_MESSAGE_LENGTH
 
 
 class TestGitBackfill:
@@ -77,7 +88,8 @@ def test_message_read_from_git_is_capped(self, repo_with_large_commit_message):
         # out of the full-scan query string.
         assert len(git_repo.commit_message) > 14_000
         assert len(config.commit_message) == MAX_COMMIT_MESSAGE_LENGTH
-        assert config.commit_message == git_repo.commit_message[:MAX_COMMIT_MESSAGE_LENGTH]
+        assert config.commit_message.startswith("Release notes")
+        assert config.commit_message.endswith(COMMIT_MESSAGE_TRUNCATION_MARKER)
 
     def test_explicit_message_is_not_overwritten_by_git(self, repo_with_large_commit_message):
         config = CliConfig(

tests/unit/test_full_scan_retry.py

@@ -283,3 +283,30 @@ def test_retry_decision_delegates_to_sdk_classification(
             core_with_mock_sdk.create_full_scan([str(manifest)], MagicMock())
 
     assert core_with_mock_sdk.sdk.fullscans.post.call_count == expected_calls
+
+
+@pytest.mark.parametrize("status_code", [413, 414, 431])
+def test_oversized_request_is_not_retried_and_names_the_cause(
+    core_with_mock_sdk, tmp_path, no_sleep, status_code
+):
+    """
+    A proxy that refuses the request line reports 413, 414 or 431 depending on which limit
+    it checks. None of them are worth a retry (the same oversized URL goes back out), and
+    the SDK's own message is a status code plus the proxy's response body, which does not
+    say what to change.
+    """
+    manifest = tmp_path / "package.json"
+    manifest.write_text("{}")
+    core_with_mock_sdk.sdk.fullscans.post.side_effect = _catch_all_failure(status_code)
+
+    with pytest.raises(APIFailure) as exc_info:
+        core_with_mock_sdk.create_full_scan([str(manifest)], MagicMock())
+
+    assert core_with_mock_sdk.sdk.fullscans.post.call_count == 1
+    no_sleep.assert_not_called()
+    message = str(exc_info.value)
+    assert f"rejected as too large (HTTP {status_code})" in message
+    assert "--commit-message" in message
+    # The SDK's original text is kept so the proxy's own response stays available.
+    assert f"original_status_code:{status_code}" in message
+    assert exc_info.value.status_code == status_code