Skip to content

feat(audit): record the gateway error reason of failed mutations - #5842

Merged
krishicks merged 2 commits into
mainfrom
feat/2911-record-error-reasons/krishicks
Nov 20, 2026
Merged

krishicks merged 2 commits into
mainfrom
feat/2911-record-error-reasons/krishicks

Conversation

@krishicks

Copy link
Copy Markdown
Contributor

Summary

A failed mutation's audit record carried only its gRPC code, so a RESOURCE_VERSION_CONFLICT looked like any other ABORTED and a REQUEST_OUTCOME_UNCERTAIN like any other FAILED_PRECONDITION. This PR appends the ErrorInfo reason the gateway set to status_detail, as committed on #5227. It is the last change for #2911.

Related Issue

Part of #2911. Refs #5227.

Changes

  • with_audited_request carries how a call ended, its code and the gateway's ErrorInfo reason, from the response headers, the stream's trailers, or the returned status. status_detail gains the reason as a third segment, such as rejected:aborted:RESOURCE_VERSION_CONFLICT. Failures without one are unchanged.
  • Only reasons in the openshell.nvidia.com domain shaped like one (UPPER_SNAKE_CASE, at most 64 bytes) are recorded. The status message stays out of the record, since handlers can put request content in it.
  • Docs: the status_detail description in docs/observability/ocsf-json-export.mdx mentions the reason.
  • A preceding refactor commit moves the mutation audit tests unchanged into grpc/mutation_audit/tests.rs, matching mutation_replay.

Before / after

Real OCSF output from UpdateConfig on sandbox agent-01, called through the gateway audit path:

Call → result Before (main) After
UpdateConfig with stale expected_resource_version → ABORTED, reason RESOURCE_VERSION_CONFLICT Failure, Low, rejected:aborted Failure, Low, rejected:aborted:RESOURCE_VERSION_CONFLICT
UpdateConfig on a missing sandbox → NOT_FOUND, no reason Failure, Low, rejected:not_found unchanged

The conflict's status message, which names the current resource version, appears in neither record.

Testing

  • cargo clippy -p openshell-server --all-targets and the auth, multiplex, grpc, and tracing_bus unit tests pass
  • Unit tests added: failed_mutation_records_the_gateway_error_reason covers gateway reasons, a reason from another domain, malformed and overlong reasons, each in response headers and in stream trailers
  • E2E tests added/updated (not applicable)

Checklist

  • Follows Conventional Commits
  • Commits are signed off (DCO)

The tests made up three quarters of mutation_audit.rs, burying the hooks
they cover. Move them unchanged into mutation_audit/tests.rs, matching
mutation_replay.

Signed-off-by: Kris Hicks <khicks@nvidia.com>
A failed mutation's record carried only its gRPC code, so a
RESOURCE_VERSION_CONFLICT looked like any other aborted call and a
REQUEST_OUTCOME_UNCERTAIN like any other failed precondition.

The record now appends the ErrorInfo reason the gateway set, read from the
response headers or the stream's trailers, as a third status_detail
segment, such as rejected:aborted:RESOURCE_VERSION_CONFLICT. Only reasons
in the gateway's error domain and shaped like one are recorded; the status
message stays out.

Refs #2911, #5227

Signed-off-by: Kris Hicks <khicks@nvidia.com>
@github-actions github-actions Bot added the state:accepted A maintainer decided OpenShell should pursue this issue label Nov 20, 2026
@github-actions

Copy link
Copy Markdown

@github-actions

Copy link
Copy Markdown

Compatibility review (advisory)

New or updated breaking changes; see the full report for all findings.

1. api-behavior — No explicit risk acceptance found

Gateway mutation audit status_detail changes from rejected:<code> or error:<code> to an optional three-segment form, such as rejected:aborted:RESOURCE_VERSION_CONFLICT.

Review details
  • Execution: complete
  • Candidate: PR #5842 (120863cf83eee763a0fef8bce0225525e22dd59f)
  • Baseline: fe8bd8f9b9aa7c93b695403a0f8cd3cafc503838 (fe8bd8f9b9aa7c93b695403a0f8cd3cafc503838)
  • Reviewed: rust-sdk, python-sdk, typescript-sdk, api-behavior, cli, configuration, policy, helm, state

Advisory review; publication gates are unchanged.

Branch check run

@krishicks
krishicks added this pull request to the merge queue Nov 20, 2026
Merged via the queue into main with commit 28ea481 Nov 20, 2026
90 checks passed
@krishicks
krishicks deleted the feat/2911-record-error-reasons/krishicks branch November 20, 2026 19:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

state:accepted A maintainer decided OpenShell should pursue this issue

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants