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, with 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 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]

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: 9691ff4b-8e51-47a3-b53e-e68748511b75

📥 Commits

Reviewing files that changed from the base of the PR and between d342ebe and 2a41e94.

📒 Files selected for processing (4)

• include/pingcap/coprocessor/Client.h
• include/pingcap/kv/Cluster.h
• src/test/CMakeLists.txt
• src/test/txn_protocol_rpc_test.cc

🚧 Files skipped from review as they are similar to previous changes (2)

• include/pingcap/coprocessor/Client.h
• include/pingcap/kv/Cluster.h

Included review availability: This review used your included allowance. 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 stores protocol ranges from store 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, src/test/txn_protocol_test.cc	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. Unit tests cover defaults, version selection, rejection validation, and error behavior.
Store metadata and request negotiation include/pingcap/kv/Cluster.h, src/kv/RegionCache.cc, include/pingcap/kv/Rpc.h, include/pingcap/kv/RegionClient.h, src/test/txn_protocol_rpc_test.cc, src/test/CMakeLists.txt	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 qualifying upper-bound rejection is valid. RPC tests cover request retries, metadata refresh, and related request paths.
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, src/test/terminal_error_test.cc, src/test/txn_protocol_rpc_test.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. Tests cover typed error preservation and propagation.

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

Merge Risk: ⚪ Minimal · up to 2a41e

No actionable issue is established for this change. It is ready for normal checks before merging.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 4.12% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 97 functions across 17 files. (1 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: adding compatibility protection for transaction RPCs across 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 4.12% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 97 functions across 17 files. (1 skipped: 1 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.}