Repository navigation
fix: attach consistent approval error reasons - #285
Tom Gamble (gambtho) wants to merge 1 commit into
Conversation
There was a problem hiding this comment.
🟢 Approval recommended
No active review issues block the structured approval-error changes.
No open issues 🎉
1 file not reviewed
api/genpb/session_grpc.pb.go: Generated file
What changed in this PR
Makes approval errors consistent with the existing structured error contract, addressing #261 so clients can choose recovery actions without parsing messages. Status codes, messages, and reasonless preconditions remain unchanged.
Changes:
- Attaches existing busy, checkpoint, stale-cursor, and fencing reasons to classified approval failures.
- Expands tests for reason precedence, cause preservation, reasonless errors, and contention on both approval methods.
- Documents condition-based reasons across approval methods, deletion admission, and harness registration.
| File | Description |
|---|---|
spec.md |
Clarifies where condition-based error reasons apply. |
session/approval.go |
Uses the shared status constructor to attach approval error reasons. |
session/approval_test.go |
Checks structured busy errors for both approval RPCs. |
session/approval_error_test.go |
Tests classified reasons, precedence, preserved causes, and reasonless failures. |
docs/api-reference.md |
Updates generated documentation for the broader reason contract. |
changelog/unreleased/approval-error-reasons.md |
Records the additive approval error details and documentation changes. |
api/session.proto |
Updates service comments describing error reason applicability. |
api/genpb/session_grpc.pb.go |
Reflects the updated service comments in generated Go interfaces. |
Review effort: Balanced
Anish Ramasekar (aramase)
left a comment
There was a problem hiding this comment.
nit: Approve's RPC comment (api/session.proto:440) lists ABORTED as "local contention, append-CAS conflict or superseded fence", but Approve now also reports CHECKPOINT_IN_PROGRESS while a stateful Fork holds the checkpoint mark. Could it mention the checkpoint case the way CloseApproval's comment does?
| // RESOURCE_EXHAUSTED: COMPUTE_RESOURCE_EXHAUSTED. | ||
| // DeleteSession also reports SESSION_BUSY and SESSION_DELETED for the matching conditions. | ||
| // DeleteSession reports SESSION_BUSY and SESSION_DELETED; mutation deletion-admission probes | ||
| // also report SESSION_BUSY. HarnessRegistry.RegisterHarness and HarnessRegistry.CreateHarness |
There was a problem hiding this comment.
nit: This is the only place that documents HARNESS_UNAVAILABLE for RegisterHarness/CreateHarness. The HarnessRegistry comments in harness_registry.proto still list only ALREADY_EXISTS and FAILED_PRECONDITION. Could UNAVAILABLE (HARNESS_UNAVAILABLE) go on those RPC comments too, since registry clients will look there?
| // UNAVAILABLE: CHECKPOINT_PENDING, HARNESS_UNAVAILABLE, COMPUTE_UNAVAILABLE. | ||
| // RESOURCE_EXHAUSTED: COMPUTE_RESOURCE_EXHAUSTED. | ||
| // DeleteSession also reports SESSION_BUSY and SESSION_DELETED for the matching conditions. | ||
| // DeleteSession reports SESSION_BUSY and SESSION_DELETED; mutation deletion-admission probes |
There was a problem hiding this comment.
nit: "mutation deletion-admission probes" is internal vocabulary, and every RPC that runs the probe is already named in this paragraph. Could this clause be dropped, or say "with authorization enabled, Exec, Resume, Suspend, Fork, Approve, CloseApproval and DeleteSession also report SESSION_BUSY while the session is being deleted"? The same sentence is in spec.md.
Approve and CloseApproval now attach the existing SESSION_BUSY, CHECKPOINT_IN_PROGRESS, STALE_CURSOR and FENCED reasons, so clients can choose a recovery path without parsing messages. Status codes, messages and reasonless preconditions stay unchanged.
The spec and generated API reference describe condition-based reasons, including approval methods and harness registration.
Root race/shuffle tests, focused race tests repeated 50 times, generator drift checks, Buf lint and compatibility checks, doccheck, integrity audits, fuzz targets and local release builds passed.
Fixes #261.
AI use: AI-assisted implementation and tests.