*: split ExtractedErrors into MultipleKeyErrors and MultipleRegionErrors

[eduralph]

Stacked on #544 — please review the last commit only. Until #544 merges, the diff below also
contains its two-line fix.

Follows @pingyu's suggestion on #544. Thanks for it — the problem turned out to be a bit worse than
redundancy.

Why. ExtractedErrors carried either key errors or region errors, so a caller had to pop an
element and type-test it to learn which it was holding. Worse, which variant reached the caller was
decided by plan shape, not by what the server reported:

• no collapsing merge → ExtractError sees the per-shard Vec<Result<_>> and normalizes to
  ExtractedErrors;
• with merge(CollectSingle) → the merge pops the single Result out first, so MultipleKeyErrors
  becomes the plan's own error and ExtractError re-raises it without ever calling key_errors().

That is exactly the bug #544 fixes, and it is already visible in the public raw API for the same
class of failure:

method	plan shape	error the user sees today
delete, put_with_ttl	retry_multi_region → merge(CollectSingle) → extract_error	MultipleKeyErrors
batch_delete, batch_put_with_ttl, delete_range	retry_multi_region → extract_error	ExtractedErrors

What. ExtractedErrors is removed. ExtractError now reports key errors as MultipleKeyErrors
and region errors as a new MultipleRegionErrors, so the variant names what the server said and is
independent of how the plan was composed. #544's two-variant match arm collapses back to one.

A latent bug this removes. CleanupLocks::execute popped the last error to type-test it and, on
the key-error path, assigned the remaining vec to key_error — so a lone key error was dropped and
key_errors() went on to report Some(vec![]), an error carrying no errors. With the kind known
from the variant, neither arm pops to decide.

One wrinkle the split exposes rather than creates. HasKeyErrors for Result<T, Error> reports
any per-shard Err as a key error — that is how a plan keeping its Vec<Result<_>> carries a hard
failure through. Naming the variant MultipleKeyErrors would then be a lie for a gRPC or
exhausted-retry error, so ExtractError wraps only what the response reported and propagates
anything else unchanged. "Reported by the response" means the two error types the HasKeyErrors
response impls construct: KeyError from a kvrpcpb::KeyError field, and KvError from a raw
endpoint's string error field — both count, since testing for KeyError alone would leave raw
operations plan-shape-dependent, which is the very thing being removed. No current plan composes
retry_multi_region_preserve_results with extract_error, so this changes no existing behaviour; it
keeps the new variant honest for the compositions that could.

Breaking. Error::ExtractedErrors is removed. Callers matching it should match
Error::MultipleKeyErrors (what the server said about the request) or Error::MultipleRegionErrors
(region failures); callers that inspected the payload's type to tell them apart can now match the
variant instead. Per @pingyu's note on #544, the next release looks like a semver-major anyway.

Verification. 4 new tests. One pins the invariant this buys — a response key error surfaces as
MultipleKeyErrors both with and without a collapsing merge, so recomposing a plan can no longer flip
the variant under a distant match arm. One pins the region side on the shape that actually reaches
ExtractError (a plan with no retry layer above it, as in resolve_lock_with_retry, since
RetryableMultiRegion consumes region errors itself). One pins that a hard per-shard error keeps its
own class. One pins that a raw endpoint's string error is classified the same way under either plan
shape. 72 lib tests; make check green; txn/raw/failpoint integration suites green against a local
api-v2 cluster.

Summary by CodeRabbit

• Bug Fixes

  • Fixed an issue where key errors could be lost during cleanup, ensuring they are correctly reported.
  • Improved lock recovery when the primary record was never written, allowing affected transactions to resolve correctly.
  • Preserved non-key and transport failures instead of misclassifying them as key errors.

• Improvements

  • Separated key-related and region-related error reporting for clearer diagnostics.
  • Expanded error documentation and coverage for transactional, raw endpoint, retry, and region failure scenarios.

[ti-chi-bot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign niedhui for approval. For more information see the Code Review Process.
Please ensure that each of them provides their approval before proceeding.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 2cba0dcc-6fa9-4027-ad94-6b212dcbab56

📥 Commits

Reviewing files that changed from the base of the PR and between ab4be1c and 6908ad3.

📒 Files selected for processing (4)

• src/common/errors.rs
• src/request/plan.rs
• src/transaction/lock.rs
• src/transaction/transaction.rs

Included review availability: Your plan provides up to 2 included reviews per hour; 1 remains after this review.

---

📝 Walkthrough

Walkthrough

The change replaces Error::ExtractedErrors with separate key and region error variants. Request planning now preserves non-key failures and classifies response errors. Cleanup, lock handling, transaction status checks, commit retries, and tests use the new variants.

Changes

Error variant split

Layer / File(s)	Summary
Error variants and extraction classification src/common/errors.rs, src/request/plan.rs	The error enum adds MultipleRegionErrors and removes ExtractedErrors. ExtractError classifies response key errors as MultipleKeyErrors and propagates other failures unchanged.
Cleanup handling and classification tests src/request/plan.rs	CleanupLocks handles key and region errors separately. Tests cover merged and unmerged plans, raw errors, region errors, and non-key failures.
Transaction error consumers src/transaction/lock.rs, src/transaction/transaction.rs	Lock resolution, transaction status checks, and commit retries match the new variants. A lock-resolution test covers rollback when the primary transaction is missing.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Severity of issue fixed: Low

Merge Risk: ⚪ Minimal · up to 6908a

The split key and region error handling is covered across request cleanup and transaction paths, with no unresolved merge-blocking behavior identified.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 45.83% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 24 functions across 4 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and concisely describes the main change: splitting ExtractedErrors into MultipleKeyErrors and MultipleRegionErrors. The leading '*:' is minor noise but does not make the title unc…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

• Fix all pre-merge checks with AI

Warning

Some tools did not complete. Review the errors below.

🔧 Clippy (1.97.1)

Clippy execution failed

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}