feat: protect transaction RPC compatibility

[zyguan]

Ref: tikv/tikv#20085

Summary

Add transaction RPC compatibility protection for mixed-version TiKV clusters.

• Negotiate a supported transaction protocol version per store and reject unsupported requests before RPC dispatch.
• Surface terminal incompatible/undetermined errors without converting them into retryable region errors.
• Preserve typed errors through coprocessor streaming responses.
• Add protocol-selection and terminal-error coverage.

Testing

• ci/build-test.sh via local/tikv-client-c-builder:latest
  • kv_client_test passed
  • bank_test passed

Summary by CodeRabbit

• New Features

  • Added transaction protocol compatibility negotiation for requests, including automatic retries when a server rejects an unsupported protocol version.
  • Added configurable request origin and default transaction protocol version settings.

• Bug Fixes

  • Terminal transaction errors, including incompatible requests and undetermined results, are now preserved and surfaced instead of being treated as ordinary retryable failures.
  • Coprocessor stream region errors are now checked for terminal transaction errors before other handling.

• Tests

  • Added coverage for protocol selection, compatibility retries, and terminal error handling.

[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 sticnarf 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]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

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: 4c624789-12a3-4dbe-b1b8-8833b086f4cd

📥 Commits

Reviewing files that changed from the base of the PR and between 5bbad98 and d342ebe.

📒 Files selected for processing (18)

• include/pingcap/Config.h
• include/pingcap/Exception.h
• include/pingcap/coprocessor/Client.h
• include/pingcap/kv/Cluster.h
• include/pingcap/kv/RegionCache.h
• include/pingcap/kv/RegionClient.h
• include/pingcap/kv/Rpc.h
• include/pingcap/kv/internal/terminal_error.h
• include/pingcap/kv/internal/txn_protocol.h
• src/coprocessor/Client.cc
• src/kv/Backoff.cc
• src/kv/LockResolver.cc
• src/kv/RegionCache.cc
• src/kv/RegionClient.cc
• src/test/CMakeLists.txt
• src/test/terminal_error_test.cc
• src/test/txn_protocol_test.cc
• third_party/kvproto

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The change adds transaction protocol version selection to unary and streaming region requests. It adds store protocol-range metadata, supports one compatibility resend after a qualifying rejection, and propagates incompatible-request and undetermined-result errors through client and lock-resolution paths.

Changes

Transaction protocol and terminal errors

Layer / File(s)	Summary
Protocol settings and selection include/pingcap/Config.h, include/pingcap/kv/RegionCache.h, include/pingcap/Exception.h, include/pingcap/kv/internal/txn_protocol.h, third_party/kvproto	Configuration and store data gain transaction protocol settings. Helpers select protocol versions and validate upper-bound rejections. Error types represent incompatible requests and undetermined results.
Store metadata and request negotiation include/pingcap/kv/Cluster.h, src/kv/RegionCache.cc, include/pingcap/kv/Rpc.h, include/pingcap/kv/RegionClient.h	The cluster validates and retains protocol settings, and the region cache records store version ranges. Unary and streaming requests set request origin and selected protocol version, and retry once when a compatible upper-bound rejection is valid.
Terminal error propagation include/pingcap/kv/internal/terminal_error.h, include/pingcap/coprocessor/Client.h, src/coprocessor/Client.cc, src/kv/Backoff.cc, src/kv/LockResolver.cc, src/kv/RegionClient.cc	Terminal errors are preserved in queued results and rethrown in region-error, backoff, coprocessor-stream, and lock-resolution paths. Parallel lock-resolution workers retain terminal errors and prioritize undetermined-result errors.
Protocol and terminal-error tests src/test/CMakeLists.txt, src/test/txn_protocol_test.cc, src/test/terminal_error_test.cc	The unit-test target adds coverage for protocol selection, compatibility rejection validation, RPC context updates, terminal error handling, and concurrent error priority.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant RegionClient
  participant Cluster
  participant RpcCall
  participant TiKV
  RegionClient->>Cluster: read request origin and protocol ceiling
  RegionClient->>RpcCall: set context with selected protocol version
  RpcCall->>TiKV: send request
  TiKV-->>RegionClient: return incompatible-request response
  RegionClient->>RegionClient: validate rejection and select compatible version
  RegionClient->>RpcCall: set context for one compatibility resend
  RpcCall->>TiKV: resend request
  TiKV-->>RegionClient: return response

Loading

Suggested reviewers: gengliqi

Merge Risk: ⚪ Minimal · up to d342e

This change negotiates a transaction protocol version with each TiKV store and rejects unsupported requests before sending them. Incompatible or undetermined results are reported as final errors instead of being retried. Stores that do not report a supported range keep the legacy protocol, and at most one downgrade resend occurs. No concrete defect remains, so the change looks ready to merge after normal CI.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 7.69% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 52 functions across 16 files. (2 skipped: …	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 clearly and concisely describes the main change: protecting transaction RPC compatibility for mixed-version TiKV clusters.
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.

Full details: Docstring Coverage

Explanation

Docstring coverage is 7.69% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 52 functions across 16 files. (2 skipped: 2 unsupported.)

• Fix all pre-merge checks with AI

---

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.}