Skip to content

refactor: prevent future RpcError variants from breaking downstream matches#63

Merged
suchapalaver merged 1 commit into
mainfrom
refactor/non-exhaustive-rpc-error
May 26, 2026
Merged

refactor: prevent future RpcError variants from breaking downstream matches#63
suchapalaver merged 1 commit into
mainfrom
refactor/non-exhaustive-rpc-error

Conversation

@suchapalaver

Copy link
Copy Markdown
Contributor

Summary

Marks the public RpcError enum #[non_exhaustive] so that future
operational variants (further per-endpoint health/quota signals,
follow-ons to the ConflictingRateLimit variant added in this
release, etc.) can be added without forcing a major-version bump on
every downstream consumer. The cost is one-time: exhaustive matches
over RpcError written in a downstream crate need a wildcard
(_ => ...) arm. Aligns the discipline already applied to the peer
public provider-surface types RpcConfig and ChainEndpoint.

Closes #62.

What's in the diff

  • src/errors/rpc.rs — adds #[non_exhaustive] to the pub enum RpcError
    declaration plus a # Stability rustdoc section explaining the
    contract to downstream consumers.
  • CHANGELOG.md — new bullet under [Unreleased]/Breaking Changes
    spelling out the wildcard-arm requirement and the forward-compatibility
    benefit, framed in operator-facing language and linking to the
    asymmetry it resolves with the peer types.

Acceptance check (from #62)

  • #[non_exhaustive] added to pub enum RpcError (src/errors/rpc.rs).
  • Breaking change documented under [Unreleased]/Breaking Changes,
    noting the _ => ... requirement.
  • Landed in the same minor bump as the existing breaking changes,
    not spent as a standalone bump.

Test plan

  • cargo fmt --check clean
  • cargo clippy --all-targets --all-features -- -D warnings clean
  • cargo test — 97/97 pass (default features)
  • cargo test --all-features — 97/97 pass
  • cargo test --no-default-features — 97/97 pass
  • In-crate exhaustive matches over RpcError: none (verified by
    grep across src/, tests/, examples/). The only match on a
    type named RpcError lives in src/transport/retry.rs:363 but
    binds alloy's alloy_json_rpc::RpcError, a name collision with
    our type.

…atches

Marks `RpcError` `#[non_exhaustive]` so adding a new operational variant
no longer forces a major-version bump on consumers. Exhaustive matches
over `RpcError` written in a downstream crate now need a wildcard
(`_ => ...`) arm; in exchange, future variant additions (further
per-endpoint health/quota signals, follow-ons to the `ConflictingRateLimit`
variant added in this release, etc.) stop being breaking changes at this
boundary. Aligns the discipline already in place on the peer public
provider-surface types `RpcConfig` and `ChainEndpoint`.

Closes #62.
@suchapalaver

Copy link
Copy Markdown
Contributor Author

Self-review pass

Pre-commit /code-review + post-PR /pr-review, with findings triaged below.

# Finding Status
1 New # Stability rustdoc heading on RpcError (src/errors/rpc.rs:83-92) diverges from how the peer #[non_exhaustive] types document the attribute — RpcConfig (src/config/policy.rs:65-66) and ChainEndpoint (src/provider/pool.rs:490-491) use a single inline sentence at the tail of the existing rustdoc, no heading. Skipped — defensible divergence. For an enum, the wildcard-arm requirement is a contract a downstream consumer needs to discover before writing a match; a dedicated heading aids that. The struct cases are lighter (only break un-..'d struct literals) and the inline-sentence treatment is appropriately quieter. Project-wide rustdoc convention for #[non_exhaustive] documentation is not worth a follow-up issue — future authors can copy whichever neighbour is closest.

No blockers remaining. All three feature combos (cargo test, --all-features, --no-default-features) green; clippy clean under --all-targets --all-features -- -D warnings; commit signed. The breaking change is documented under [Unreleased]/Breaking Changes so it lands in the same minor bump as the other entries there rather than spending another bump.

@suchapalaver suchapalaver merged commit e8be917 into main May 26, 2026
11 checks passed
@suchapalaver suchapalaver deleted the refactor/non-exhaustive-rpc-error branch May 26, 2026 16:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Mark RpcError as #[non_exhaustive] to align with peer public types

1 participant