feat(cerrors): ConduitError foundation (type, registry, proto mapping)#2524
Merged
Conversation
…ping)
First, no-behavior-change step of the v0.16 structured-error work: the Go
representation of Conduit's uniform, machine-actionable error, plus its wire
mapping. No existing error site is touched.
- ConduitError{Code, Message, ConfigPath, Suggestion, Fix, DocsURL} composes with
cerrors (wraps a cause, preserves stack traces; errors.As/Is work).
- New/Wrap are the only constructors. New guarantees a stack frame even for a leaf
error (a bare *ConduitError literal carries none — it is not an xerrors value;
test enforces this). Wrap honors the no-nested-code invariant: it passes an
inner ConduitError's code through unchanged rather than shadowing it.
- Code registry with an EXPLICIT gRPC category per code (not inferred from the
reason string); Codes() feeds docs/llms.txt/UI.
- ToStatus/FromStatus map to/from google.rpc.Status with an additive
google.rpc.ErrorInfo detail (verified preserved through grpc-gateway). Top-level
code/message unchanged — purely additive.
- Round-trip test keeps the Go and wire encodings from drifting; a fuzz test
found and fixed a real bug: a stray invalid-UTF-8 byte in any field made the
proto detail fail to marshal, silently dropping the whole structured error.
ToStatus now coerces wire strings to valid UTF-8.
Design: docs/design-documents/20260705-conduit-error-and-structured-output.md
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…onest docs Review fixes for the ConduitError foundation (#2524): - Sanitize Code.Reason on the wire like every other field (a stray byte would otherwise fail the detail marshal and drop the whole structured error). - Export Register with a documented init-only contract so boundary packages can register their own codes (the rollout's next step needs this). - Correct New/Wrap docstrings: the guaranteed stack frame points into the constructor, not the caller (cerrors.New uses Caller(1)); guide toward Wrap with a cerrors cause for accurate attribution. Real skip-aware fix tracked as follow-up. - Document Wrap's message-replace behavior and that its code arg is ignored when an inner ConduitError is present; comment the local-registry-authoritative GRPCCode decision; godoc on Code/Message/Error/Unwrap. - Strengthen the fuzz: vary the Code and add an idempotent relay round-trip (the check that catches a field silently failing to marshal); add an invalid-UTF-8 seed. Follow-ups (caller-accurate frames, raw-literal guard, code-override hatch): filed. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
First, no-behavior-change step of the v0.16 structured-error work (design:
docs/design-documents/20260705-conduit-error-and-structured-output.md, PR #2523). Adds theconduiterrpackage; touches no existing error site.What's here
ConduitError{Code, Message, ConfigPath, Suggestion, Fix, DocsURL}— composes withcerrors(wraps a cause, preserves stack traces;errors.As/Iswork).New/Wrapare the only constructors.Newguarantees a stack frame even for a leaf error (a bare&ConduitError{}literal carries none — it's not an xerrors value; a test enforces this).Wraphonors the no-nested-code invariant — it passes an innerConduitError's code through rather than shadowing it.Codes()feeds docs/llms.txt/UI.ToStatus/FromStatusmap to/fromgoogle.rpc.Statuswith an additivegoogle.rpc.ErrorInfodetail (the compat path verified through grpc-gateway in the design review). Top-level code/message unchanged.Tests
ToStatusnow coerces wire strings to valid UTF-8. Fuzz then ran 2.4M execs clean.-racegreen, lint clean,linux/386builds.Tier 2 (new foundation package, no data-path change, no existing behavior touched).
🤖 Generated with Claude Code