From 46623fac5f74e9e6ae9143504e37f6759bea45c1 Mon Sep 17 00:00:00 2001 From: zyguan Date: Wed, 4 Nov 2026 17:46:07 +0000 Subject: [PATCH 1/5] *: handle transaction protocol compatibility in request plans Declare per-client request origins and transaction protocol versions, select compatible versions per destination, and handle admission rejections with a bounded resend. Preserve protocol errors through retries and cleanup. Update kvproto, coordinate store metadata refreshes, reject invalid ranges, and add metrics, documentation, and regression coverage. Signed-off-by: zyguan --- proto/VERSION | 6 +- proto/apipb.proto | 24 + proto/autoid.proto | 14 +- proto/cdcpb.proto | 9 + proto/coprocessor.proto | 40 + proto/disaggregated.proto | 7 +- proto/errorpb.proto | 32 + proto/keyspacepb.proto | 113 ++- proto/kvrpcpb.proto | 189 ++++- proto/metapb.proto | 12 + proto/mpp.proto | 7 +- proto/pdpb.proto | 125 ++- proto/resource_manager.proto | 45 +- proto/resource_usage_agent.proto | 3 + proto/schedulingpb.proto | 1 + proto/tsopb.proto | 28 +- src/common/errors.rs | 29 + src/common/mod.rs | 1 + src/config.rs | 115 +++ src/generated/apipb.rs | 14 + src/generated/autoid.rs | 32 +- src/generated/cdcpb.rs | 32 + src/generated/coprocessor.rs | 43 + src/generated/disaggregated.rs | 18 +- src/generated/errorpb.rs | 63 ++ src/generated/keyspacepb.rs | 410 ++++++++- src/generated/kvrpcpb.rs | 305 ++++++- src/generated/metapb.rs | 16 + src/generated/mod.rs | 3 + src/generated/mpp.rs | 18 +- src/generated/pdpb.rs | 223 ++++- src/generated/resource_manager.rs | 54 +- src/generated/resource_usage_agent.rs | 4 + src/generated/schedulingpb.rs | 1 + src/generated/tsopb.rs | 57 +- src/lib.rs | 2 +- src/mock.rs | 17 + src/pd/client.rs | 13 +- src/raw/client.rs | 4 +- src/raw/requests.rs | 4 + src/region_cache.rs | 398 ++++++++- src/request/keyspace.rs | 35 + src/request/mod.rs | 59 +- src/request/plan.rs | 1057 +++++++++++++++++++++++- src/request/plan_builder.rs | 69 +- src/request/shard.rs | 38 + src/stats.rs | 35 + src/store/errors.rs | 19 +- src/store/mod.rs | 3 + src/store/request.rs | 6 + src/transaction/client.rs | 31 +- src/transaction/lock.rs | 215 ++++- src/transaction/requests.rs | 72 +- src/transaction/transaction.rs | 226 ++++- src/transaction/transaction/scanner.rs | 62 +- 55 files changed, 4166 insertions(+), 292 deletions(-) create mode 100644 proto/apipb.proto create mode 100644 src/generated/apipb.rs diff --git a/proto/VERSION b/proto/VERSION index 6af27a69c..625684a13 100644 --- a/proto/VERSION +++ b/proto/VERSION @@ -1,3 +1,3 @@ -pingcap/kvproto b41e86365ce0e0fba482005c0dfa5e2ca967d74c (2026-06-22) -Matches client-go v2.0.8-0.20260708122311-01bd8f99f4da (go.mod: kvproto v0.0.0-20260622063236-b41e86365ce0). -Re-vendor: copy proto/*.proto (matching names only) and include/ from that revision, then `make generate`. +pingcap/kvproto 121875fd9777 (2026-10-06) +Go module: github.com/pingcap/kvproto v0.0.0-20261006010420-121875fd9777. +Re-vendor: copy existing proto/*.proto, any new imported schemas, and include/ from that revision, then `make generate`. diff --git a/proto/apipb.proto b/proto/apipb.proto new file mode 100644 index 000000000..0f7f6aa4f --- /dev/null +++ b/proto/apipb.proto @@ -0,0 +1,24 @@ +syntax = "proto3"; +package apipb; + +import "gogoproto/gogo.proto"; +import "rustproto.proto"; + +option java_package = "org.tikv.kvproto"; +option (gogoproto.goproto_sizecache_all) = false; +option (gogoproto.goproto_unkeyed_all) = false; +option (gogoproto.goproto_unrecognized_all) = false; +option (gogoproto.marshaler_all) = true; +option (gogoproto.sizer_all) = true; +option (gogoproto.unmarshaler_all) = true; +option (rustproto.lite_runtime_all) = true; + +// KeyspaceIdentity identifies a V3 tenant keyspace. +// +// For V3 tenant-scoped APIs, namespace_id must be non-zero and keyspace_id must +// satisfy 0 < keyspace_id < 2^24. Namespace 0 and keyspace 0 mean +// missing/invalid identity and must be rejected by V3 validators. +message KeyspaceIdentity { + uint32 namespace_id = 1; + uint32 keyspace_id = 2; +} diff --git a/proto/autoid.proto b/proto/autoid.proto index 869b640d8..e5df5fcbb 100644 --- a/proto/autoid.proto +++ b/proto/autoid.proto @@ -1,6 +1,7 @@ syntax = "proto3"; package autoid; +import "apipb.proto"; import "gogoproto/gogo.proto"; import "rustproto.proto"; @@ -20,7 +21,12 @@ message AutoIDRequest { uint64 n = 4; int64 increment = 5; int64 offset = 6; - uint32 keyspaceID = 7; + oneof keyspace { + // V1/V2 compatibility keyspace id. V3 should use keyspace_identity. + uint32 keyspaceID = 7; + // V3 keyspace identity. + apipb.KeyspaceIdentity keyspace_identity = 8; + } } message AutoIDResponse { @@ -36,6 +42,12 @@ message RebaseRequest { bool isUnsigned = 3; int64 base = 4; bool force = 5; + oneof keyspace { + // V1/V2 compatibility keyspace id. V3 should use keyspace_identity. + uint32 keyspaceID = 6; + // V3 keyspace identity. + apipb.KeyspaceIdentity keyspace_identity = 7; + } } message RebaseResponse { diff --git a/proto/cdcpb.proto b/proto/cdcpb.proto index 3a89a2040..e3e310672 100644 --- a/proto/cdcpb.proto +++ b/proto/cdcpb.proto @@ -145,6 +145,12 @@ message ResolvedTs { uint64 request_id = 3; } +enum ScanPriority { + SCAN_PRIORITY_UNKNOWN = 0; + SCAN_PRIORITY_LOW = 1; + SCAN_PRIORITY_HIGH = 2; +} + message ChangeDataRequest { message Register {} @@ -191,6 +197,9 @@ message ChangeDataRequest { // Whether to filter out the value write by cdc itself. bool filter_loop = 12; + + // ScanPriority tells the CDC service how to schedule the initial scan. + ScanPriority scan_priority = 14; } service ChangeData { diff --git a/proto/coprocessor.proto b/proto/coprocessor.proto index 222f0e53a..a872ff7c1 100644 --- a/proto/coprocessor.proto +++ b/proto/coprocessor.proto @@ -72,6 +72,33 @@ message Request { // (paging_size). The two fields target different scenarios and may be set // independently. uint64 paging_size_bytes = 17; + // Signals that the client can handle results of the batched tasks in `tasks` + // being merged into `Response.data` instead of each task returning its result + // in its own `StoreBatchTaskResponse.data`. Merging lets the store combine + // mergeable payloads, such as per-region ANALYZE sampling statistics, into + // one result, reducing the response size and the client's decode and merge + // work. See the batched ANALYZE design for the motivating use case: + // https://github.com/pingcap/tidb/pull/70355. + // + // For every merged task, the store still adds a `StoreBatchTaskResponse` + // with `data_merged_into_response` set. The store may return some or all task + // results separately even when this field is set, for example when a task + // fails, when its result is not mergeable, or when the store predates this + // field, so the client must handle both merged and per-task results. + // + // This field only negotiates the response shape. It does not affect task + // scheduling and may be set independently of `execute_batch_tasks_serially`. + bool allow_batch_task_data_merge = 18; + // When true, the store executes the primary task and all tasks in `tasks` one + // at a time, so at most one task of this request is running at any moment. + // Task execution order is not guaranteed. + // + // Clients that already bound their per-store concurrency by the number of + // in-flight requests, such as batched ANALYZE, set this so that batching more + // tasks into one request does not multiply that concurrency. The trade-off is + // a longer-lived request. This field only affects task scheduling and may be + // set independently of `allow_batch_task_data_merge`. + bool execute_batch_tasks_serially = 19; } message Response { @@ -195,6 +222,19 @@ message StoreBatchTaskResponse { string other_error = 4; uint64 task_id = 5; kvrpcpb.ExecDetailsV2 exec_details_v2 = 6; + // Indicates that this task's result was merged into the enclosing + // `Response.data`, so this message's `data` is empty. The store sets this + // field only when the client enables `Request.allow_batch_task_data_merge`, + // and only for a task that succeeded: a failed or non-mergeable task is + // returned as a normal per-task response with this field unset. + // + // Merging is atomic. If the store fails while merging, it returns no partial + // merged data and no response with this field set, so the client can safely + // retry the entire batch without losing or double-counting any task's result. + // + // This message still identifies the merged task by `task_id` and carries its + // execution details. + bool data_merged_into_response = 7; } message DelegateRequest { diff --git a/proto/disaggregated.proto b/proto/disaggregated.proto index 445e8ffdb..eef7244ea 100644 --- a/proto/disaggregated.proto +++ b/proto/disaggregated.proto @@ -1,6 +1,7 @@ syntax = "proto3"; package disaggregated; +import "apipb.proto"; import "coprocessor.proto"; import "gogoproto/gogo.proto"; import "kvrpcpb.proto"; @@ -81,7 +82,11 @@ message DisaggTaskMeta { uint64 local_query_id = 4; // unique local query_id if tidb don't restart. int64 task_id = 5; // if task id is -1 , it indicates a tidb task. string executor_id = 6; // the exectuor id - uint32 keyspace_id = 7; // keyspace id of the request + oneof keyspace { + uint32 keyspace_id = 7; // V1/V2 compatibility keyspace id of the request. V3 should use keyspace_identity. + // V3 keyspace identity of the request. + apipb.KeyspaceIdentity keyspace_identity = 12; + } kvrpcpb.APIVersion api_version = 8; // API version of the request uint64 connection_id = 10; // This is the session id between a client and tidb string connection_alias = 11; // This is the session alias between a client and tidb diff --git a/proto/errorpb.proto b/proto/errorpb.proto index f05368e04..0f0675d4d 100644 --- a/proto/errorpb.proto +++ b/proto/errorpb.proto @@ -88,8 +88,30 @@ message EpochNotMatch { repeated metapb.Region current_regions = 1; } +// Reasons for rejecting an incompatible transaction protocol request. +enum IncompatibleRequestReason { + IncompatibleRequestReasonUnknown = 0; + // The declared version is outside the compatible range returned in the error. + IncompatibleRequestReasonTxnProtocolVersionOutOfRange = 1; +} + +// A transaction protocol compatibility rejection. +// The compatible range is inclusive: admission reports the store's global range; +// feature checks report [required feature version, store's maximum version]. +message IncompatibleRequest { + IncompatibleRequestReason reason = 1; + // Diagnostic text; clients must use structured fields for control flow. + string message = 2; + // The request's declaration; missing and explicit zero both mean legacy. + uint32 provided_txn_protocol_version = 3; + uint32 min_compatible_txn_protocol_version = 4; + uint32 max_compatible_txn_protocol_version = 5; +} + // ServerIsBusy is the error variant that tells the server is too busy to response. message ServerIsBusy { + // "txn_protocol_incompatible" is a legacy fallback for IncompatibleRequest, + // not an overload signal. string reason = 1; // The suggested backoff time uint64 backoff_ms = 2; @@ -214,4 +236,14 @@ message Error { // UndeterminedResult is the error variant that tells the result is not determined yet. UndeterminedResult undetermined_result = 22; + + // A compatibility rejection with no usable business result. + // For a zero declaration, also set server_is_busy.reason to + // "txn_protocol_incompatible"; omit that fallback for nonzero declarations. + // Clients must handle this error before fallback or ordinary retry logic. + // Only client-c may reselect and resend when the reason is version out of range, + // the returned range is valid, and provided > max. The selected version must + // satisfy the request's requirements. Such admission rejections must have no + // transaction side effects. All other incompatibilities are terminal. + IncompatibleRequest incompatible_request = 23; } diff --git a/proto/keyspacepb.proto b/proto/keyspacepb.proto index 033c01e50..3bf0ca6be 100644 --- a/proto/keyspacepb.proto +++ b/proto/keyspacepb.proto @@ -1,6 +1,7 @@ syntax = "proto3"; package keyspacepb; +import "apipb.proto"; import "gogoproto/gogo.proto"; import "pdpb.proto"; import "rustproto.proto"; @@ -14,9 +15,18 @@ option (gogoproto.sizer_all) = true; option (gogoproto.unmarshaler_all) = true; option (rustproto.lite_runtime_all) = true; +// Namespace provides services to manage namespaces. +service Namespace { + rpc CreateNamespace(CreateNamespaceRequest) returns (CreateNamespaceResponse) {} + rpc LoadNamespace(LoadNamespaceRequest) returns (LoadNamespaceResponse) {} + rpc GetAllNamespaces(GetAllNamespacesRequest) returns (GetAllNamespacesResponse) {} + rpc UpdateNamespaceState(UpdateNamespaceStateRequest) returns (UpdateNamespaceStateResponse) {} +} + // Keyspace provides services to manage keyspaces. service Keyspace { rpc LoadKeyspace(LoadKeyspaceRequest) returns (LoadKeyspaceResponse) {} + rpc LookupKeyspace(LookupKeyspaceRequest) returns (LookupKeyspaceResponse) {} rpc LoadKeyspaceByID(LoadKeyspaceByIDRequest) returns (LoadKeyspaceResponse) {} // WatchKeyspaces first return all current keyspaces' metadata as its first response. // Then, it returns responses containing keyspaces that had their metadata changed. @@ -26,7 +36,12 @@ service Keyspace { } message KeyspaceMeta { - uint32 id = 1; + oneof keyspace { + // V1/V2 compatibility keyspace id. V3 should read keyspace_identity instead. + uint32 id = 1; + // Canonical V3 keyspace identity. + apipb.KeyspaceIdentity keyspace_identity = 8; + } string name = 2; KeyspaceState state = 3; int64 created_at = 4; @@ -41,14 +56,82 @@ enum KeyspaceState { TOMBSTONE = 3; } +message NamespaceMeta { + uint32 id = 1; + string name = 2; + KeyspaceState state = 3; + int64 created_at = 4; + int64 state_changed_at = 5; + map config = 7; +} + +message NamespaceRef { + oneof namespace { + // API V3 namespace id. + uint32 namespace_id = 1; + // API V3 namespace name. + string namespace_name = 2; + } +} + +message CreateNamespaceRequest { + pdpb.RequestHeader header = 1; + string name = 2; + map config = 3; +} + +message CreateNamespaceResponse { + pdpb.ResponseHeader header = 1; + NamespaceMeta namespace = 2; +} + +message LoadNamespaceRequest { + pdpb.RequestHeader header = 1; + NamespaceRef namespace = 2; +} + +message LoadNamespaceResponse { + pdpb.ResponseHeader header = 1; + NamespaceMeta namespace = 2; +} + +message GetAllNamespacesRequest { + pdpb.RequestHeader header = 1; + uint32 start_id = 2; + uint32 limit = 3; +} + +message GetAllNamespacesResponse { + pdpb.ResponseHeader header = 1; + repeated NamespaceMeta namespaces = 2; +} + +message UpdateNamespaceStateRequest { + pdpb.RequestHeader header = 1; + NamespaceRef namespace = 2; + KeyspaceState state = 3; +} + +message UpdateNamespaceStateResponse { + pdpb.ResponseHeader header = 1; + NamespaceMeta namespace = 2; +} + message LoadKeyspaceRequest { pdpb.RequestHeader header = 1; string name = 2; + // V3 namespace-scoped name lookup. If unset, V3 name-only lookup should use LookupKeyspace and may return multiple keyspaces. + NamespaceRef namespace = 3; } message LoadKeyspaceByIDRequest { pdpb.RequestHeader header = 1; - uint32 id = 2; + oneof keyspace { + // V1/V2 compatibility keyspace id. V3 should use keyspace_identity. + uint32 id = 2; + // V3 keyspace identity. + apipb.KeyspaceIdentity keyspace_identity = 3; + } } message LoadKeyspaceResponse { @@ -56,6 +139,16 @@ message LoadKeyspaceResponse { KeyspaceMeta keyspace = 2; } +message LookupKeyspaceRequest { + pdpb.RequestHeader header = 1; + string name = 2; +} + +message LookupKeyspaceResponse { + pdpb.ResponseHeader header = 1; + repeated KeyspaceMeta keyspaces = 2; +} + message WatchKeyspacesRequest { pdpb.RequestHeader header = 1; } @@ -67,7 +160,12 @@ message WatchKeyspacesResponse { message UpdateKeyspaceStateRequest { pdpb.RequestHeader header = 1; - uint32 id = 2; + oneof keyspace { + // V1/V2 compatibility keyspace id. V3 should use keyspace_identity. + uint32 id = 2; + // V3 keyspace identity. + apipb.KeyspaceIdentity keyspace_identity = 4; + } KeyspaceState state = 3; } @@ -78,8 +176,15 @@ message UpdateKeyspaceStateResponse { message GetAllKeyspacesRequest { pdpb.RequestHeader header = 1; - uint32 start_id = 2; + oneof start_keyspace { + // V1/V2 compatibility pagination cursor. V3 should use namespace_id and start_keyspace_identity. + uint32 start_id = 2; + // V3 pagination cursor within namespace_id. + apipb.KeyspaceIdentity start_keyspace_identity = 5; + } uint32 limit = 3; + // V3 namespace-scoped pagination. Must be non-zero in V3. + NamespaceRef namespace = 4; } message GetAllKeyspacesResponse { diff --git a/proto/kvrpcpb.proto b/proto/kvrpcpb.proto index d2398e8de..be6c3a43b 100644 --- a/proto/kvrpcpb.proto +++ b/proto/kvrpcpb.proto @@ -1,6 +1,7 @@ syntax = "proto3"; package kvrpcpb; +import "apipb.proto"; import "deadlock.proto"; import "errorpb.proto"; import "gogoproto/gogo.proto"; @@ -853,9 +854,16 @@ message MvccGetByStartTsResponse { // Helper messages. +// Client-provided process/product identity for auditing, not authentication or +// authorization. TiDB includes embedded BR; standalone BR uses RequestOriginBR. +// Audit unknown values without mapping them to a known origin or rejecting +// requests solely because of their origin in the initial rollout. enum RequestOrigin { RequestOriginUnknown = 0; RequestOriginTiDB = 1; + RequestOriginTiCDC = 2; + RequestOriginBR = 3; + RequestOriginTiFlash = 4; } // Miscellaneous metadata attached to most requests. @@ -928,20 +936,23 @@ message Context { // Some information used for resource control. ResourceControlContext resource_control_context = 28; - // The declared origin of the request. TiDB server requests set this to TIDB. - // This field is client-provided metadata; consumers should rely on it only when - // the caller is authenticated/authorized by the transport or deployment boundary. - // UNKNOWN means the origin is unset or not recognized by this protocol version. - // Other components should add dedicated enum variants when they need origin-specific behavior. + // Declared process/product origin; see RequestOrigin. RequestOrigin request_origin = 29; // The keyspace that the request is sent to. // NOTE: This field is only meaningful while the api_version is V2. string keyspace_name = 31; - // The keyspace that the request is sent to. - // NOTE: This field is only meaningful while the api_version is V2. - uint32 keyspace_id = 32; + oneof keyspace { + // The keyspace that the request is sent to. + // NOTE: This field is only meaningful while the api_version is V2. + // V3 uses keyspace_identity and must not read this legacy field as the full identity. + uint32 keyspace_id = 32; + // The V3 keyspace identity that the request is sent to. + // V3 RPC key fields carry user key bytes; TiKV encodes the physical + // mode + namespace + keyspace prefix at the serving boundary. + apipb.KeyspaceIdentity keyspace_identity = 38; + } // The buckets version that the request is sent to. // NOTE: This field is only meaningful while enable buckets. @@ -966,9 +977,12 @@ message Context { // This field is set by client-go based on an extractor function provided by TiDB. uint64 trace_control_flags = 37; - // TODO(slock): tidb should send requests with a feature flag to indicate whether it - // supports shared locks, so that tikv can fail the requests from old tidb versions - // when needed. + // Transaction protocol version declared for this request; see TxnProtocolVersion. + // Missing or zero means legacy. Any nonzero value promises structured + // IncompatibleRequest handling. BatchCommands declares this per inner request. + // This is a compatibility declaration, not a binary version or authorization. + // Keep uint32 so future version values remain representable. + uint32 txn_protocol_version = 39; } message ResourceControlContext { @@ -1037,6 +1051,26 @@ enum APIVersion { // V2 server accpets V2 requests and V1 transactional requests that statrts with TiDB key // prefix (`m` and `t`). V2 = 2; + // + // `V3` uses user-key wire semantics for normal KV RPCs. Servers encode an + // 8-byte physical prefix at the serving boundary: + // mode(1) + namespace_id(4 bytes, big endian) + keyspace_id(3 bytes, big endian). + // The keyspace identity is carried by Context.keyspace_identity. + V3 = 3; +} + +// Transaction protocol version registry. Each version includes all earlier +// semantics. Keep values stable; new versions require joint review by TiKV, +// TiDB and relevant client owners. This registry sets neither client defaults +// nor the store's admission range. +enum TxnProtocolVersion { + // No promise to handle IncompatibleRequest. + TXN_VER_LEGACY = 0; + // Handles IncompatibleRequest according to its error contract. + TXN_VER_SUPPORT_INCOMPATIBLE_ERROR_HANDLING = 1; + // Also supports shared wrapper parsing and expansion, nested lock information + // preservation, and shared-lock pagination and resolve semantics. + TXN_VER_SUPPORT_SHARED_LOCK = 2; } message SourceStmt { @@ -1067,9 +1101,8 @@ message LockInfo { // When lock_type is SharedLock, this describes transactions holding the shared lock. // Important: when lock_type is SharedLock, all shared locks must use shared_lock_infos; // DO NOT read from the wrapper LockInfo. - // TODO(slock): tidb should send requests with a feature flag to indicate whether it - // supports shared locks, so that tikv can fail the requests from old tidb versions - // when needed. + // Before returning a shared lock wrapper, the server must check the caller's + // txn_protocol_version and return IncompatibleRequest if support is insufficient. repeated LockInfo shared_lock_infos = 12; // Reserved for file based transaction. @@ -1089,6 +1122,9 @@ message KeyError { AssertionFailed assertion_failed = 10; // Assertion of a `Mutation` is evaluated as a failure. PrimaryMismatch primary_mismatch = 11; // CheckTxnStatus is sent to a lock that's not the primary. TxnLockNotFound txn_lock_not_found = 12; // TxnLockNotFound indicates the txn lock is not found. + LockUpgradeConflict lock_upgrade_conflict = 13; // LockUpgradeConflict indicates a shared-lock upgrade protocol conflict. + // SharedLockLost deterministically confirms that the transaction's shared-lock ownership was lost. + SharedLockLost shared_lock_lost = 14; // Extra information for error debugging DebugInfo debug_info = 100; @@ -1113,6 +1149,26 @@ message WriteConflict { Reason reason = 6; } +message LockUpgradeConflict { + enum Reason { + Unknown = 0; + DuplicateInFlight = 1; + SecondUpgrader = 2; + } + + bytes key = 1; + uint64 start_ts = 2; + uint64 owner_start_ts = 3; + Reason reason = 4; +} + +// SharedLockLost means the pending upgrade did not acquire the exclusive lock. +// The transaction must not continue, but rollback remains valid. +message SharedLockLost { + bytes key = 1; + uint64 start_ts = 2; +} + message AlreadyExist { bytes key = 1; } @@ -1341,6 +1397,87 @@ message ExecDetailsV2 { // RU (Request Unit) consumption details. RUV2 ru_v2 = 5; + + // Scheduling and execution details for the request's read-pool task. + // Available when read-pool task tracking is enabled in TiKV. + PoolTaskDetails read_pool_task_details = 6; +} + +// Scheduling and execution details collected across all polls of one task running in a pool. +// The timing model is: +// total_wall_nanos +// <---------------------------------------------------------------------> +// +// submitted worker starts async event worker starts done +// │ │ completes │ │ +// ▼ ▼ ▼ ▼ ▼ +// ┌──────────────┬─────────────────┬─────────────────┬──────────────┬──────┐ +// │ Queue Wait │ Poll Execution │ Async/Wake Wait │ Queue Wait │ Poll │ +// │ │ │ │ │ Exec │ +// │ task is │ Future::poll │ Future is │ task is │ │ +// │ runnable, │ returns Pending │ Pending, waiting│ runnable, │Ready │ +// │ waiting for │ │ for I/O, timer, │ waiting for │ │ +// │ a worker │ │ lock, etc. │ a worker │ │ +// └──────────────┴─────────────────┴─────────────────┴──────────────┴──────┘ +// │ │ │ +// │ │ └─ total/max/min_wake_wait_nanos +// │ │ +// │ ├─ poll_wall_nanos +// │ └─ poll_cpu_nanos +// │ +// ├─ total/max/min_queue_wait_nanos +// └─ fair_queue_waited_task_slices +message PoolTaskDetails { + // Number of Future::poll calls, including immediate repolls within one worker dispatch. + uint64 poll_count = 1; + + // Number of worker dispatches. Immediate repolls in one dispatch are not counted separately. + uint64 dispatch_count = 2; + + // Wall time from immediately before the initial pool submission until the final poll completes. + uint64 total_wall_nanos = 3; + + // Total time from enqueueing a ready task until a worker starts dispatching it. + // Zero when no queue-wait sample was recorded. + uint64 total_queue_wait_nanos = 4; + // Maximum queue wait time among all dispatches. + uint64 max_queue_wait_nanos = 5; + // Minimum queue wait time among all dispatches. + uint64 min_queue_wait_nanos = 6; + + // Total time from a pending poll's completion until the task is scheduled again. + // Zero when no wake-wait sample was recorded. + uint64 total_wake_wait_nanos = 7; + // Maximum wake wait time among all wakeups. + uint64 max_wake_wait_nanos = 8; + // Minimum wake wait time among all wakeups. + uint64 min_wake_wait_nanos = 9; + + // Whether fair-queue waited-slice data was collected for this task. + bool fair_queue_enabled = 10; + // Total number of task slices dispatched ahead of this task while it waited in the fair queue. + // Zero when no fair-queue wait sample was recorded. + uint64 total_fair_queue_waited_task_slices = 11; + // Maximum number of task slices dispatched ahead of this task during one fair-queue wait. + uint64 max_fair_queue_waited_task_slices = 12; + // Minimum number of task slices dispatched ahead of this task during one fair-queue wait. + uint64 min_fair_queue_waited_task_slices = 13; + + // Total thread CPU time consumed by Future::poll calls. + // Zero when no poll sample was recorded. + uint64 poll_cpu_nanos = 14; + // Maximum thread CPU time consumed by one Future::poll call. + uint64 max_poll_cpu_nanos = 15; + // Minimum thread CPU time consumed by one Future::poll call. + uint64 min_poll_cpu_nanos = 16; + + // Total wall time consumed by Future::poll calls. + // Zero when no poll sample was recorded. + uint64 poll_wall_nanos = 17; + // Minimum wall time consumed by one Future::poll call. + uint64 min_poll_wall_nanos = 18; + // Maximum wall time consumed by one Future::poll call. + uint64 max_poll_wall_nanos = 19; } message RUV2 { @@ -1701,8 +1838,14 @@ message CompactRequest { // API version of the request APIVersion api_version = 7; - // Keyspace of the table located in. - uint32 keyspace_id = 8; + oneof keyspace { + // Keyspace of the table located in. + // NOTE: This field is only meaningful for V1/V2 compatibility. V3 uses + // keyspace_identity and must not read this field as the full identity. + uint32 keyspace_id = 8; + // V3 keyspace identity of the table located in. + apipb.KeyspaceIdentity keyspace_identity = 9; + } } message CompactResponse { @@ -1789,6 +1932,20 @@ message HealthFeedback { // The slow_score calculated in raftstore module. Due to some limitations of slow score, this would // be replaced by `SlowTrend` in the future. int32 slow_score = 3; + // The resource groups that the store currently blames for its own overload, if it reports them + // at all. A store that does not support reporting them leaves this field unset, which is why + // this is a message rather than a bare repeated field: an unset field and an empty list have + // to mean different things to the client. + NoisyGroups noisy_groups = 4; +} + +// NoisyGroups is the set of resource groups a store holds responsible for its own overload, as +// judged by that store alone at the time the feedback was generated. +// +// An empty `names` is a positive statement that the store currently blames nobody, so a client can +// treat each message as replacing whatever it previously knew about that store. +message NoisyGroups { + repeated string names = 1; } message BroadcastTxnStatusRequest { diff --git a/proto/metapb.proto b/proto/metapb.proto index 4e38559ec..8c7f79841 100644 --- a/proto/metapb.proto +++ b/proto/metapb.proto @@ -67,6 +67,18 @@ message Store { bool physically_destroyed = 12; // NodeState is used to replace StoreState which will be deprecated in the future. NodeState node_state = 13; + // The store's current transaction RPC admission range, not a feature switch or + // a value derived from Store.version. Absence means legacy/unknown; clients + // conservatively use [0, 0] while preserving absence versus an explicit [0, 0]. + // Consumers must fail closed if min > max. TiKV reports this on every startup, + // including upgrades and rollbacks; PD updates and persists it. + TxnProtocolVersionRange txn_protocol_version_range = 14; +} + +// Inclusive transaction protocol version bounds; see kvrpcpb.TxnProtocolVersion. +message TxnProtocolVersionRange { + uint32 min = 1; + uint32 max = 2; } message RegionEpoch { diff --git a/proto/mpp.proto b/proto/mpp.proto index 1035ac003..f47d2d395 100644 --- a/proto/mpp.proto +++ b/proto/mpp.proto @@ -1,6 +1,7 @@ syntax = "proto3"; package mpp; +import "apipb.proto"; import "coprocessor.proto"; import "gogoproto/gogo.proto"; import "kvrpcpb.proto"; @@ -27,7 +28,11 @@ message TaskMeta { uint64 local_query_id = 7; // unique local query_id if tidb don't restart. So we can use gather_id + query_ts + local_query_id + server_id to represent a global unique query. uint64 server_id = 8; // TiDB server id int64 mpp_version = 9; // mpp version - uint32 keyspace_id = 10; // keyspace id of the request + oneof keyspace { + uint32 keyspace_id = 10; // V1/V2 compatibility keyspace id of the request. V3 should use keyspace_identity. + // V3 keyspace identity of the request. + apipb.KeyspaceIdentity keyspace_identity = 22; + } string coordinator_address = 11; // coordinator_address of this query bool report_execution_summary = 12; // Only when coordinator_address is not empty, this flag can be true. When set to true, TiFlash only report execution summary through ReportMPPTaskStatus service, don't include summaries in MppDataPacket kvrpcpb.APIVersion api_version = 16; // API version of the request diff --git a/proto/pdpb.proto b/proto/pdpb.proto index 5142625ee..675f96253 100644 --- a/proto/pdpb.proto +++ b/proto/pdpb.proto @@ -1,6 +1,7 @@ syntax = "proto3"; package pdpb; +import "apipb.proto"; import "eraftpb.proto"; import "gogoproto/gogo.proto"; import "metapb.proto"; @@ -111,6 +112,8 @@ service PD { rpc GetAllKeyspacesGCStates(GetAllKeyspacesGCStatesRequest) returns (GetAllKeyspacesGCStatesResponse) {} + rpc WatchGCStates(WatchGCStatesRequest) returns (stream WatchGCStatesResponse) {} + rpc SyncRegions(stream SyncRegionRequest) returns (stream SyncRegionResponse) {} rpc GetOperator(GetOperatorRequest) returns (GetOperatorResponse) {} @@ -231,6 +234,7 @@ message Error { string message = 2; } +// This message intentionally omits namespace/keyspace-related fields because API v2 never supported keyspaces when routing TSO requests through the PD API server. message TsoRequest { RequestHeader header = 1; @@ -336,6 +340,7 @@ message GetAllStoresResponse { message GetRegionRequest { RequestHeader header = 1; + // Physical key bytes used for Region lookup. bytes region_key = 2; bool need_buckets = 3; } @@ -370,9 +375,9 @@ message QueryRegionRequest { bool need_buckets = 2; // The region IDs to query. repeated uint64 ids = 3; - // The region keys to query. + // Physical key bytes to query. repeated bytes keys = 4; - // The previous region keys to query. + // Previous physical key bytes to query. repeated bytes prev_keys = 5; } @@ -402,9 +407,10 @@ message RegionResponse { message ScanRegionsRequest { RequestHeader header = 1; + // Physical start key bytes. bytes start_key = 2; int32 limit = 3; // no limit when limit <= 0. - bytes end_key = 4; // end_key is +inf when it is empty. + bytes end_key = 4; // Physical end key bytes. end_key is +inf when it is empty. } message Region { @@ -431,15 +437,16 @@ message ScanRegionsResponse { } message KeyRange { + // Physical start key bytes. bytes start_key = 1; - bytes end_key = 2; // end_key is +inf when it is empty. + bytes end_key = 2; // Physical end key bytes. end_key is +inf when it is empty. } message BatchScanRegionsRequest { RequestHeader header = 1; bool need_buckets = 2; - repeated KeyRange ranges = 3; // the given ranges must be in order. + repeated KeyRange ranges = 3; // Physical key ranges. The given ranges must be in order. int32 limit = 4; // limit the total number of regions to scan. // If contain_all_key_range is true, the output must contain all // key ranges in the request. @@ -568,6 +575,9 @@ message RegionHeartbeatRequest { // Approximate size of column-based key-value pairs for billing. // It's counted on size of user key & value (excluding metadata fields), before compression, and latest versions only. uint64 approximate_columnar_kv_size = 19; + // Approximate size of row-based key-value pairs stored in the IA tier for billing. + // It is a subset of approximate_kv_size and follows the same size accounting rules. + uint64 approximate_ia_kv_size = 22; // BucketMeta is the bucket version and keys of this region if TiKV enabled the bucket feature metapb.BucketMeta bucket_meta = 20; @@ -594,6 +604,7 @@ message Merge { message SplitRegion { CheckPolicy policy = 1; + // Physical split key bytes. repeated bytes keys = 2; } @@ -816,9 +827,12 @@ message DfsStatScope { // When true, the statistic is not tied to any keyspace. bool is_global = 1; // The keyspace of this statistic. Ignore when is_global is true. + // NOTE: This field is only meaningful for V1/V2 compatibility. V3 should use keyspace_identities. uint32 keyspace_id = 2; // The component that provides the statistic. string component = 3; + // V3 multi-keyspace statistic scope. Ignore when is_global is true. + repeated apipb.KeyspaceIdentity keyspace_identities = 4; } message DfsStatItem { @@ -1005,7 +1019,12 @@ message UpdateServiceGCSafePointResponse { message GetGCSafePointV2Request { RequestHeader header = 1; - uint32 keyspace_id = 2; + oneof keyspace { + // V1/V2 compatibility keyspace id. V3 should use keyspace_identity. + uint32 keyspace_id = 2; + // V3 keyspace identity. + apipb.KeyspaceIdentity keyspace_identity = 3; + } } message GetGCSafePointV2Response { @@ -1021,7 +1040,12 @@ message WatchGCSafePointV2Request { // SafePointEvent is for the rpc WatchGCSafePointV2. message SafePointEvent { - uint32 keyspace_id = 1; + oneof keyspace { + // V1/V2 compatibility keyspace id. V3 should use keyspace_identity. + uint32 keyspace_id = 1; + // V3 keyspace identity served by this event. + apipb.KeyspaceIdentity keyspace_identity = 4; + } uint64 safe_point = 2; EventType type = 3; } @@ -1035,7 +1059,12 @@ message WatchGCSafePointV2Response { message UpdateGCSafePointV2Request { RequestHeader header = 1; - uint32 keyspace_id = 2; + oneof keyspace { + // V1/V2 compatibility keyspace id. V3 should use keyspace_identity. + uint32 keyspace_id = 2; + // V3 keyspace identity. + apipb.KeyspaceIdentity keyspace_identity = 4; + } uint64 safe_point = 3; } @@ -1048,7 +1077,12 @@ message UpdateGCSafePointV2Response { message UpdateServiceSafePointV2Request { RequestHeader header = 1; - uint32 keyspace_id = 2; + oneof keyspace { + // V1/V2 compatibility keyspace id. V3 should use keyspace_identity. + uint32 keyspace_id = 2; + // V3 keyspace identity. + apipb.KeyspaceIdentity keyspace_identity = 6; + } bytes service_id = 3; uint64 safe_point = 4; // Safe point will be set to expire on (PD Server time + TTL), @@ -1072,7 +1106,12 @@ message GetAllGCSafePointV2Request { } message GCSafePointV2 { - uint32 keyspace_id = 1; + oneof keyspace { + // V1/V2 compatibility keyspace id. V3 should use keyspace_identity. + uint32 keyspace_id = 1; + // V3 keyspace identity. + apipb.KeyspaceIdentity keyspace_identity = 3; + } uint64 gc_safe_point = 2; } @@ -1082,12 +1121,15 @@ message GetAllGCSafePointV2Response { int64 revision = 3; } -// A wrapper over keyspace_id. -// When a field is not specified in proto3, its value will be regarded as 0; however, keyspace_id = 0 is regarded as a valid keyspace (which -// is the "DEFAULT" keyspace). To distinguish unspecified keyspace (NullKeyspace, 0xffffffff) and the default keyspace in some APIs as well -// as preventing potential misuse, we wrap the keyspace_id into a message type which is nullable. +// A wrapper over keyspace scope. +// keyspace_id is kept for V1/V2 compatibility. V3 should use keyspace_identity and reject +// missing/invalid namespace or keyspace IDs in tenant-scoped requests. message KeyspaceScope { - uint32 keyspace_id = 1; + oneof keyspace { + uint32 keyspace_id = 1; + // V3 keyspace identity. + apipb.KeyspaceIdentity keyspace_identity = 2; + } } message AdvanceGCSafePointRequest { @@ -1188,6 +1230,13 @@ message GetGCStateRequest { KeyspaceScope keyspace_scope = 2; bool exclude_gc_barriers = 3; + // Include all stored global GC barriers in the response. + // + // This uses an include flag, unlike exclude_gc_barriers, because proto3 bool + // fields default to false. GetGCState historically omitted global GC + // barriers, so false preserves both the existing response and the + // no-extra-read path. + bool include_global_gc_barriers = 4; } message GCState { @@ -1199,10 +1248,34 @@ message GCState { repeated GCBarrierInfo gc_barriers = 5; } +// GCStateChange describes a change to a keyspace's effective GC state. +// GCState values sent by WatchGCStates omit gc_barriers because barriers are +// internal inputs used by PD to calculate effective safe points; the stream +// reports only changes to the resulting effective state. +message GCStateChange { + oneof change { + // Insert or replace the complete GC state of this keyspace. + GCState upsert = 1; + + // Remove this keyspace from the client's materialized GC-state view. + // This does not necessarily mean the keyspace metadata was physically deleted. + KeyspaceScope removed = 2; + } +} + +// GlobalGCBarriersInfo carries presence independently from the barrier list. +message GlobalGCBarriersInfo { + repeated GlobalGCBarrierInfo barriers = 1; +} + message GetGCStateResponse { ResponseHeader header = 1; GCState gc_state = 2; + // Absent when globals were not requested or the server does not support + // this extension. Present-empty when the request was fulfilled but no + // global GC barriers are stored. + GlobalGCBarriersInfo global_gc_barriers = 3; } message GetAllKeyspacesGCStatesRequest { @@ -1219,6 +1292,26 @@ message GetAllKeyspacesGCStatesResponse { repeated GlobalGCBarrierInfo global_gc_barriers = 3; } +message WatchGCStatesRequest { + RequestHeader header = 1; + + // If false, when the stream is established, the server first sends the current + // GC states of all keyspaces. + bool skip_loading_initial = 2; +} + +message WatchGCStatesResponse { + ResponseHeader header = 1; + + // Clients apply changes in order within this response and across successive + // responses on the stream. A client must not observe an older state for a + // keyspace after a newer update. After disconnection, the client reconnects + // and reloads the initial state. The stream omits GC barrier details and does + // not emit changes for barrier-only updates. If a barrier update changes an + // effective GC state, the resulting state change is emitted. + repeated GCStateChange changes = 2; +} + message RegionStat { // Bytes read/written during this period. uint64 bytes_written = 1; @@ -1294,6 +1387,7 @@ message SyncMaxTSResponse { message SplitRegionsRequest { RequestHeader header = 1; + // Physical split key bytes. repeated bytes split_keys = 2; uint64 retry_limit = 3; } @@ -1306,6 +1400,7 @@ message SplitRegionsResponse { message SplitAndScatterRegionsRequest { RequestHeader header = 1; + // Physical split key bytes. repeated bytes split_keys = 2; string group = 3; uint64 retry_limit = 4; diff --git a/proto/resource_manager.proto b/proto/resource_manager.proto index 302efc9de..1bd265ae4 100644 --- a/proto/resource_manager.proto +++ b/proto/resource_manager.proto @@ -1,6 +1,7 @@ syntax = "proto3"; package resource_manager; +import "apipb.proto"; import "gogoproto/gogo.proto"; import "rustproto.proto"; @@ -26,19 +27,24 @@ service ResourceManager { rpc AcquireTokenBuckets(stream TokenBucketsRequest) returns (stream TokenBucketsResponse) {} } -// KeyspaceIDValue is a wrapper for the value of keyspace ID. -// Because the 0 value is a valid keyspace ID, we need to use a wrapper to distinguish it from the null keyspace ID. +// KeyspaceIDValue carries the versioned identity of a keyspace. The message +// name is retained for compatibility with existing ResourceManager APIs. message KeyspaceIDValue { - uint32 value = 1; + oneof keyspace { + // V1/V2 compatibility keyspace ID. The wrapper distinguishes a valid zero + // value from an unset keyspace, which represents the null keyspace ID. + uint32 value = 1; + // V3 keyspace identity. + apipb.KeyspaceIdentity keyspace_identity = 2; + } } message ListResourceGroupsRequest { bool with_ru_stats = 1; // There're two cases for this field: - // - If the keyspace ID is not set, it means this may be a message from an older version. + // - If the keyspace is not set, it means this may be a message from an older version. // To maintain compatibility, we will treat it as a null keyspace ID, which is uint32.Max. - // - If the keyspace ID is set to a valid value, the listed resource groups will be filtered - // by the given keyspace ID. + // - If the keyspace is set, the listed resource groups will be filtered by the given keyspace. KeyspaceIDValue keyspace_id = 2; } @@ -51,10 +57,9 @@ message GetResourceGroupRequest { string resource_group_name = 1; bool with_ru_stats = 2; // There're two cases for this field: - // - If the keyspace ID is not set, it means this may be a message from an older version. + // - If the keyspace is not set, it means this may be a message from an older version. // To maintain compatibility, we will treat it as a null keyspace ID, which is uint32.Max. - // - If the keyspace ID is set to a valid value, it will try to get the resource group within - // the given keyspace ID. + // - If the keyspace is set, it will try to get the resource group within the given keyspace. KeyspaceIDValue keyspace_id = 3; } @@ -66,10 +71,9 @@ message GetResourceGroupResponse { message DeleteResourceGroupRequest { string resource_group_name = 1; // There're two cases for this field: - // - If the keyspace ID is not set, it means this may be a message from an older version. + // - If the keyspace is not set, it means this may be a message from an older version. // To maintain compatibility, we will treat it as a null keyspace ID, which is uint32.Max. - // - If the keyspace ID is set to a valid value, it will try to delete the resource group within - // the given keyspace ID. + // - If the keyspace is set, it will try to delete the resource group within the given keyspace. KeyspaceIDValue keyspace_id = 2; } @@ -114,10 +118,10 @@ message TokenBucketRequest { bool is_background = 5; bool is_tiflash = 6; // There're two cases for this field: - // - If the keyspace ID is not set, it means this may be a message from an older version. + // - If the keyspace is not set, it means this may be a message from an older version. // To maintain compatibility, we will treat it as a null keyspace ID, which is uint32.Max. - // - If the keyspace ID is set to a valid value, it will try to request the token bucket from - // the resource group within the given keyspace ID. + // - If the keyspace is set, it will try to request the token bucket from the resource group + // within the given keyspace. KeyspaceIDValue keyspace_id = 7; } @@ -133,10 +137,9 @@ message TokenBucketResponse { // Raw mode repeated GrantedRawResourceTokenBucket granted_resource_tokens = 3; // There're two cases for this field: - // - If the keyspace ID is not set, it means this may be a message from an older version, + // - If the keyspace is not set, it means this may be a message from an older version, // which can be safely ignored to keep compatibility. - // - If the keyspace ID is set to a valid value, it means this response is from the resource - // group within this keyspace ID. + // - If the keyspace is set, it means this response is from the resource group within this keyspace. KeyspaceIDValue keyspace_id = 4; } @@ -213,11 +216,11 @@ message ResourceGroup { BackgroundSettings background_settings = 7; // RU consumption statistics. Consumption RUStats = 8; - // The keyspace ID that the resource group belongs to. + // The keyspace that the resource group belongs to. // There're two cases for this field: - // - If the keyspace ID is not set, it means this may be a message from an older version. + // - If the keyspace is not set, it means this may be a message from an older version. // To maintain compatibility, we will treat it as a null keyspace ID, which is uint32.Max. - // - If the keyspace ID is set to a valid value, it will directly be used. + // - If the keyspace is set, it will directly be used. KeyspaceIDValue keyspace_id = 9; } diff --git a/proto/resource_usage_agent.proto b/proto/resource_usage_agent.proto index 576ab9264..4accc20ff 100644 --- a/proto/resource_usage_agent.proto +++ b/proto/resource_usage_agent.proto @@ -54,6 +54,9 @@ message GroupTagRecordItem { uint64 network_out_bytes = 6; uint64 logical_read_bytes = 7; uint64 logical_write_bytes = 8; + // RocksDB block reads used for downstream read_iops relative attribution. + // This is not a device-level IOPS measurement. + uint64 rocksdb_block_read_count = 9; } // RegionRecord is a set of resource usage data grouped by region. diff --git a/proto/schedulingpb.proto b/proto/schedulingpb.proto index 9167a3ae5..ad3b3d9dd 100644 --- a/proto/schedulingpb.proto +++ b/proto/schedulingpb.proto @@ -168,6 +168,7 @@ message ScatterRegionsResponse { message SplitRegionsRequest { RequestHeader header = 1; + // Physical split key bytes. repeated bytes split_keys = 2; uint64 retry_limit = 3; } diff --git a/proto/tsopb.proto b/proto/tsopb.proto index 7a8f6a481..5032a5b90 100644 --- a/proto/tsopb.proto +++ b/proto/tsopb.proto @@ -1,6 +1,7 @@ syntax = "proto3"; package tsopb; +import "apipb.proto"; import "gogoproto/gogo.proto"; import "pdpb.proto"; import "rustproto.proto"; @@ -16,7 +17,7 @@ option (rustproto.lite_runtime_all) = true; service TSO { rpc Tso(stream TsoRequest) returns (stream TsoResponse) {} - // Find the keyspace group that the keyspace belongs to by keyspace id. + // Find the keyspace group that the keyspace belongs to. rpc FindGroupByKeyspaceID(FindGroupByKeyspaceIDRequest) returns (FindGroupByKeyspaceIDResponse) {} // Get the minimum timestamp across all keyspace groups served by the TSO server who receives // and handle the request. If the TSO server/pod is not serving any keyspace group, return @@ -31,8 +32,13 @@ message RequestHeader { // sender_id is the ID of the sender server. uint64 sender_id = 2; - // keyspace_id is the unique id of the tenant/keyspace. - uint32 keyspace_id = 3; + oneof keyspace { + // keyspace_id is the unique id of the tenant/keyspace in V1/V2. + // V3 should use keyspace_identity and must not read this legacy field as the full identity. + uint32 keyspace_id = 3; + // V3 keyspace identity of the request. + apipb.KeyspaceIdentity keyspace_identity = 6; + } // keyspace_group_id is the unique id of the keyspace group to which the tenant/keyspace belongs. uint32 keyspace_group_id = 4; // callee_id is the ID of the server which the client expects to receive the request. @@ -47,8 +53,13 @@ message ResponseHeader { uint64 cluster_id = 1; Error error = 2; - // keyspace_id is the unique id of the tenant/keyspace as the response receiver. - uint32 keyspace_id = 3; + oneof keyspace { + // keyspace_id is the unique id of the tenant/keyspace as the response receiver in V1/V2. + // V3 should use keyspace_identity and must not read this legacy field as the full identity. + uint32 keyspace_id = 3; + // V3 keyspace identity served by this response. + apipb.KeyspaceIdentity keyspace_identity = 5; + } // keyspace_group_id is the unique id of the keyspace group to which the tenant/keyspace belongs. uint32 keyspace_group_id = 4; } @@ -109,7 +120,12 @@ message KeyspaceGroup { message FindGroupByKeyspaceIDRequest { RequestHeader header = 1; - uint32 keyspace_id = 2; + oneof keyspace { + // V1/V2 compatibility keyspace id. V3 should use keyspace_identity. + uint32 keyspace_id = 2; + // V3 keyspace identity. + apipb.KeyspaceIdentity keyspace_identity = 4; + } uint64 mod_revision = 3; } diff --git a/src/common/errors.rs b/src/common/errors.rs index fb0780e52..581b79b23 100644 --- a/src/common/errors.rs +++ b/src/common/errors.rs @@ -78,6 +78,11 @@ pub enum Error { /// Errors caused by changes of region information #[error("Region error: {0:?}")] RegionError(Box), + /// Terminal local or server protocol rejection, preserving its structured fields. + /// Local failures use reason `Unknown`; undetermined outcomes take precedence + /// and retain their original [`Error::RegionError`] envelope. + #[error("Incompatible transaction request: {0:?}")] + IncompatibleRequest(Box), /// Whether the transaction is committed or not is undetermined #[error("Whether the transaction is committed or not is undetermined")] UndeterminedError(Box), @@ -152,6 +157,30 @@ Use the async TransactionClient instead, or create and use SyncTransactionClient NestedRuntimeError(String), } +/// Precedence when independent RPC or cleanup failures must be combined. +/// Lower values win. Error wrapping remains the caller's responsibility. +#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)] +pub(crate) enum ErrorPriority { + Undetermined, + Incompatible, + Ordinary, +} + +impl Error { + pub(crate) fn priority(&self) -> ErrorPriority { + match self { + Self::RegionError(error) if error.undetermined_result.is_some() => { + ErrorPriority::Undetermined + } + Self::IncompatibleRequest(_) => ErrorPriority::Incompatible, + Self::RegionError(error) if error.incompatible_request.is_some() => { + ErrorPriority::Incompatible + } + _ => ErrorPriority::Ordinary, + } + } +} + impl From for Error { fn from(e: ProtoRegionError) -> Error { Error::RegionError(Box::new(e)) diff --git a/src/common/mod.rs b/src/common/mod.rs index 06236c64b..d9f58c856 100644 --- a/src/common/mod.rs +++ b/src/common/mod.rs @@ -4,6 +4,7 @@ mod errors; pub mod security; pub use self::errors::Error; +pub(crate) use self::errors::ErrorPriority; pub use self::errors::ProtoKeyError; pub use self::errors::ProtoRegionError; pub use self::errors::Result; diff --git a/src/config.rs b/src/config.rs index 92a67e65d..51b821596 100644 --- a/src/config.rs +++ b/src/config.rs @@ -6,6 +6,34 @@ use std::time::Duration; use serde_derive::Deserialize; use serde_derive::Serialize; +pub use crate::proto::kvrpcpb::{RequestOrigin, TxnProtocolVersion}; + +/// Per-client policy inherited by transactions and lock resolvers. +/// Supports `0` (legacy) and `1` (structured incompatibility handling), defaulting +/// to `1`. Shared-lock version `2` is unsupported. Direct callers must choose a +/// supported version; transactional client construction validates [`Config`]. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct TxnRequestPolicy { + /// Product identity for auditing. + pub origin: RequestOrigin, + /// Configured version; each destination may select a lower compatible version. + pub protocol_version: TxnProtocolVersion, +} + +impl TxnRequestPolicy { + /// Default transactional request origin (`Unknown`) and protocol version (`1`). + pub const DEFAULT: Self = Self { + origin: RequestOrigin::Unknown, + protocol_version: TxnProtocolVersion::TxnVerSupportIncompatibleErrorHandling, + }; +} + +impl Default for TxnRequestPolicy { + fn default() -> Self { + Self::DEFAULT + } +} + /// The configuration for either a [`RawClient`](crate::RawClient) or a /// [`TransactionClient`](crate::TransactionClient). /// @@ -26,6 +54,12 @@ pub struct Config { pub timeout: Duration, pub grpc_max_decoding_message_size: usize, pub keyspace: Option, + /// Product origin for transactional requests, encoded as a protobuf enum value. + /// Defaults to [`RequestOrigin::Unknown`]. + pub request_origin: i32, + /// Configured transaction protocol version, encoded as a protobuf enum value. + /// Defaults to `1`; transactional client construction accepts only `0` and `1`. + pub txn_protocol_version: i32, } const DEFAULT_REQUEST_TIMEOUT: Duration = Duration::from_secs(2); @@ -40,11 +74,51 @@ impl Default for Config { timeout: DEFAULT_REQUEST_TIMEOUT, grpc_max_decoding_message_size: DEFAULT_GRPC_MAX_DECODING_MESSAGE_SIZE, keyspace: None, + request_origin: TxnRequestPolicy::DEFAULT.origin as i32, + txn_protocol_version: TxnRequestPolicy::DEFAULT.protocol_version as i32, } } } impl Config { + /// Set the transactional request origin; defaults to [`RequestOrigin::Unknown`]. + #[must_use] + pub fn with_request_origin(mut self, origin: RequestOrigin) -> Self { + self.request_origin = origin as i32; + self + } + + /// Set the transaction protocol version; defaults to `1`. + /// Transactional client construction validates this setting; the setter does not. + /// See [`TxnRequestPolicy`] for supported versions. + #[must_use] + pub fn with_txn_protocol_version(mut self, version: TxnProtocolVersion) -> Self { + self.txn_protocol_version = version as i32; + self + } + + pub(crate) fn txn_request_policy(&self) -> crate::Result { + let origin = RequestOrigin::try_from(self.request_origin).map_err(|_| { + crate::Error::StringError(format!("unknown request origin: {}", self.request_origin)) + })?; + let protocol_version = + TxnProtocolVersion::try_from(self.txn_protocol_version).map_err(|_| { + crate::Error::StringError(format!( + "unknown transaction protocol version: {}", + self.txn_protocol_version + )) + })?; + if protocol_version == TxnProtocolVersion::TxnVerSupportSharedLock { + return Err(crate::Error::StringError( + "shared-lock transaction protocol version is not supported".to_owned(), + )); + } + Ok(TxnRequestPolicy { + origin, + protocol_version, + }) + } + /// Set the certificate authority, certificate, and key locations for clients. /// /// By default, this client will use an insecure connection over instead of one protected by @@ -118,3 +192,44 @@ impl Config { self } } + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn transaction_policy_defaults_and_configured_values_are_preserved() { + assert_eq!( + Config::default().txn_request_policy().unwrap(), + TxnRequestPolicy::DEFAULT + ); + let config = Config::default() + .with_request_origin(RequestOrigin::TiFlash) + .with_txn_protocol_version(TxnProtocolVersion::TxnVerLegacy); + assert_eq!( + config.txn_request_policy().unwrap(), + TxnRequestPolicy { + origin: RequestOrigin::TiFlash, + protocol_version: TxnProtocolVersion::TxnVerLegacy, + } + ); + let restored: Config = + serde_json::from_str(&serde_json::to_string(&config).unwrap()).unwrap(); + assert_eq!( + restored.txn_request_policy().unwrap(), + config.txn_request_policy().unwrap() + ); + } + + #[test] + fn transaction_policy_rejects_unsupported_versions_and_unknown_origins() { + for version in [-1, 2, 42] { + let mut config = Config::default(); + config.txn_protocol_version = version; + assert!(config.txn_request_policy().is_err()); + } + let mut config = Config::default(); + config.request_origin = 42; + assert!(config.txn_request_policy().is_err()); + } +} diff --git a/src/generated/apipb.rs b/src/generated/apipb.rs new file mode 100644 index 000000000..e24432bf5 --- /dev/null +++ b/src/generated/apipb.rs @@ -0,0 +1,14 @@ +// This file is @generated by prost-build. +/// KeyspaceIdentity identifies a V3 tenant keyspace. +/// +/// For V3 tenant-scoped APIs, namespace_id must be non-zero and keyspace_id must +/// satisfy 0 \< keyspace_id \< 2^24. Namespace 0 and keyspace 0 mean +/// missing/invalid identity and must be rejected by V3 validators. +#[allow(clippy::derive_partial_eq_without_eq)] +#[derive(Clone, PartialEq, ::prost::Message)] +pub struct KeyspaceIdentity { + #[prost(uint32, tag = "1")] + pub namespace_id: u32, + #[prost(uint32, tag = "2")] + pub keyspace_id: u32, +} diff --git a/src/generated/autoid.rs b/src/generated/autoid.rs index 503024aba..f2ec05718 100644 --- a/src/generated/autoid.rs +++ b/src/generated/autoid.rs @@ -14,8 +14,21 @@ pub struct AutoIdRequest { pub increment: i64, #[prost(int64, tag = "6")] pub offset: i64, - #[prost(uint32, tag = "7")] - pub keyspace_id: u32, + #[prost(oneof = "auto_id_request::Keyspace", tags = "7, 8")] + pub keyspace: ::core::option::Option, +} +/// Nested message and enum types in `AutoIDRequest`. +pub mod auto_id_request { + #[allow(clippy::derive_partial_eq_without_eq)] + #[derive(Clone, PartialEq, ::prost::Oneof)] + pub enum Keyspace { + /// V1/V2 compatibility keyspace id. V3 should use keyspace_identity. + #[prost(uint32, tag = "7")] + KeyspaceId(u32), + /// V3 keyspace identity. + #[prost(message, tag = "8")] + KeyspaceIdentity(super::super::apipb::KeyspaceIdentity), + } } #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] @@ -40,6 +53,21 @@ pub struct RebaseRequest { pub base: i64, #[prost(bool, tag = "5")] pub force: bool, + #[prost(oneof = "rebase_request::Keyspace", tags = "6, 7")] + pub keyspace: ::core::option::Option, +} +/// Nested message and enum types in `RebaseRequest`. +pub mod rebase_request { + #[allow(clippy::derive_partial_eq_without_eq)] + #[derive(Clone, PartialEq, ::prost::Oneof)] + pub enum Keyspace { + /// V1/V2 compatibility keyspace id. V3 should use keyspace_identity. + #[prost(uint32, tag = "6")] + KeyspaceId(u32), + /// V3 keyspace identity. + #[prost(message, tag = "7")] + KeyspaceIdentity(super::super::apipb::KeyspaceIdentity), + } } #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] diff --git a/src/generated/cdcpb.rs b/src/generated/cdcpb.rs index 5d2a993ff..fc2f4a52a 100644 --- a/src/generated/cdcpb.rs +++ b/src/generated/cdcpb.rs @@ -302,6 +302,9 @@ pub struct ChangeDataRequest { /// Whether to filter out the value write by cdc itself. #[prost(bool, tag = "12")] pub filter_loop: bool, + /// ScanPriority tells the CDC service how to schedule the initial scan. + #[prost(enumeration = "ScanPriority", tag = "14")] + pub scan_priority: i32, #[prost(oneof = "change_data_request::Request", tags = "9, 10, 13")] pub request: ::core::option::Option, } @@ -374,6 +377,35 @@ pub mod change_data_request { Deregister(Deregister), } } +#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, ::prost::Enumeration)] +#[repr(i32)] +pub enum ScanPriority { + Unknown = 0, + Low = 1, + High = 2, +} +impl ScanPriority { + /// String value of the enum field names used in the ProtoBuf definition. + /// + /// The values are not transformed in any way and thus are considered stable + /// (if the ProtoBuf definition does not change) and safe for programmatic use. + pub fn as_str_name(&self) -> &'static str { + match self { + ScanPriority::Unknown => "SCAN_PRIORITY_UNKNOWN", + ScanPriority::Low => "SCAN_PRIORITY_LOW", + ScanPriority::High => "SCAN_PRIORITY_HIGH", + } + } + /// Creates an enum from field names used in the ProtoBuf definition. + pub fn from_str_name(value: &str) -> ::core::option::Option { + match value { + "SCAN_PRIORITY_UNKNOWN" => Some(Self::Unknown), + "SCAN_PRIORITY_LOW" => Some(Self::Low), + "SCAN_PRIORITY_HIGH" => Some(Self::High), + _ => None, + } + } +} /// Generated client implementations. pub mod change_data_client { #![allow(unused_variables, dead_code, missing_docs, clippy::let_unit_value)] diff --git a/src/generated/coprocessor.rs b/src/generated/coprocessor.rs index 16676352d..d1e2744c2 100644 --- a/src/generated/coprocessor.rs +++ b/src/generated/coprocessor.rs @@ -81,6 +81,35 @@ pub struct Request { /// independently. #[prost(uint64, tag = "17")] pub paging_size_bytes: u64, + /// Signals that the client can handle results of the batched tasks in `tasks` + /// being merged into `Response.data` instead of each task returning its result + /// in its own `StoreBatchTaskResponse.data`. Merging lets the store combine + /// mergeable payloads, such as per-region ANALYZE sampling statistics, into + /// one result, reducing the response size and the client's decode and merge + /// work. See the batched ANALYZE design for the motivating use case: + /// + /// + /// For every merged task, the store still adds a `StoreBatchTaskResponse` + /// with `data_merged_into_response` set. The store may return some or all task + /// results separately even when this field is set, for example when a task + /// fails, when its result is not mergeable, or when the store predates this + /// field, so the client must handle both merged and per-task results. + /// + /// This field only negotiates the response shape. It does not affect task + /// scheduling and may be set independently of `execute_batch_tasks_serially`. + #[prost(bool, tag = "18")] + pub allow_batch_task_data_merge: bool, + /// When true, the store executes the primary task and all tasks in `tasks` one + /// at a time, so at most one task of this request is running at any moment. + /// Task execution order is not guaranteed. + /// + /// Clients that already bound their per-store concurrency by the number of + /// in-flight requests, such as batched ANALYZE, set this so that batching more + /// tasks into one request does not multiply that concurrency. The trade-off is + /// a longer-lived request. This field only affects task scheduling and may be + /// set independently of `allow_batch_task_data_merge`. + #[prost(bool, tag = "19")] + pub execute_batch_tasks_serially: bool, } #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] @@ -264,6 +293,20 @@ pub struct StoreBatchTaskResponse { pub task_id: u64, #[prost(message, optional, tag = "6")] pub exec_details_v2: ::core::option::Option, + /// Indicates that this task's result was merged into the enclosing + /// `Response.data`, so this message's `data` is empty. The store sets this + /// field only when the client enables `Request.allow_batch_task_data_merge`, + /// and only for a task that succeeded: a failed or non-mergeable task is + /// returned as a normal per-task response with this field unset. + /// + /// Merging is atomic. If the store fails while merging, it returns no partial + /// merged data and no response with this field set, so the client can safely + /// retry the entire batch without losing or double-counting any task's result. + /// + /// This message still identifies the merged task by `task_id` and carries its + /// execution details. + #[prost(bool, tag = "7")] + pub data_merged_into_response: bool, } #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] diff --git a/src/generated/disaggregated.rs b/src/generated/disaggregated.rs index 0b24ba7a3..d5184117b 100644 --- a/src/generated/disaggregated.rs +++ b/src/generated/disaggregated.rs @@ -111,9 +111,6 @@ pub struct DisaggTaskMeta { /// the exectuor id #[prost(string, tag = "6")] pub executor_id: ::prost::alloc::string::String, - /// keyspace id of the request - #[prost(uint32, tag = "7")] - pub keyspace_id: u32, /// API version of the request #[prost(enumeration = "super::kvrpcpb::ApiVersion", tag = "8")] pub api_version: i32, @@ -123,6 +120,21 @@ pub struct DisaggTaskMeta { /// This is the session alias between a client and tidb #[prost(string, tag = "11")] pub connection_alias: ::prost::alloc::string::String, + #[prost(oneof = "disagg_task_meta::Keyspace", tags = "7, 12")] + pub keyspace: ::core::option::Option, +} +/// Nested message and enum types in `DisaggTaskMeta`. +pub mod disagg_task_meta { + #[allow(clippy::derive_partial_eq_without_eq)] + #[derive(Clone, PartialEq, ::prost::Oneof)] + pub enum Keyspace { + /// V1/V2 compatibility keyspace id of the request. V3 should use keyspace_identity. + #[prost(uint32, tag = "7")] + KeyspaceId(u32), + /// V3 keyspace identity of the request. + #[prost(message, tag = "12")] + KeyspaceIdentity(super::super::apipb::KeyspaceIdentity), + } } #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] diff --git a/src/generated/errorpb.rs b/src/generated/errorpb.rs index ddba0b602..33cf36f81 100644 --- a/src/generated/errorpb.rs +++ b/src/generated/errorpb.rs @@ -98,10 +98,31 @@ pub struct EpochNotMatch { #[prost(message, repeated, tag = "1")] pub current_regions: ::prost::alloc::vec::Vec, } +/// A transaction protocol compatibility rejection. +/// The compatible range is inclusive: admission reports the store's global range; +/// feature checks report \[required feature version, store's maximum version\]. +#[allow(clippy::derive_partial_eq_without_eq)] +#[derive(Clone, PartialEq, ::prost::Message)] +pub struct IncompatibleRequest { + #[prost(enumeration = "IncompatibleRequestReason", tag = "1")] + pub reason: i32, + /// Diagnostic text; clients must use structured fields for control flow. + #[prost(string, tag = "2")] + pub message: ::prost::alloc::string::String, + /// The request's declaration; missing and explicit zero both mean legacy. + #[prost(uint32, tag = "3")] + pub provided_txn_protocol_version: u32, + #[prost(uint32, tag = "4")] + pub min_compatible_txn_protocol_version: u32, + #[prost(uint32, tag = "5")] + pub max_compatible_txn_protocol_version: u32, +} /// ServerIsBusy is the error variant that tells the server is too busy to response. #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] pub struct ServerIsBusy { + /// "txn_protocol_incompatible" is a legacy fallback for IncompatibleRequest, + /// not an overload signal. #[prost(string, tag = "1")] pub reason: ::prost::alloc::string::String, /// The suggested backoff time @@ -274,4 +295,46 @@ pub struct Error { /// UndeterminedResult is the error variant that tells the result is not determined yet. #[prost(message, optional, tag = "22")] pub undetermined_result: ::core::option::Option, + /// A compatibility rejection with no usable business result. + /// For a zero declaration, also set server_is_busy.reason to + /// "txn_protocol_incompatible"; omit that fallback for nonzero declarations. + /// Clients must handle this error before fallback or ordinary retry logic. + /// Only client-c may reselect and resend when the reason is version out of range, + /// the returned range is valid, and provided > max. The selected version must + /// satisfy the request's requirements. Such admission rejections must have no + /// transaction side effects. All other incompatibilities are terminal. + #[prost(message, optional, tag = "23")] + pub incompatible_request: ::core::option::Option, +} +/// Reasons for rejecting an incompatible transaction protocol request. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, ::prost::Enumeration)] +#[repr(i32)] +pub enum IncompatibleRequestReason { + Unknown = 0, + /// The declared version is outside the compatible range returned in the error. + TxnProtocolVersionOutOfRange = 1, +} +impl IncompatibleRequestReason { + /// String value of the enum field names used in the ProtoBuf definition. + /// + /// The values are not transformed in any way and thus are considered stable + /// (if the ProtoBuf definition does not change) and safe for programmatic use. + pub fn as_str_name(&self) -> &'static str { + match self { + IncompatibleRequestReason::Unknown => "IncompatibleRequestReasonUnknown", + IncompatibleRequestReason::TxnProtocolVersionOutOfRange => { + "IncompatibleRequestReasonTxnProtocolVersionOutOfRange" + } + } + } + /// Creates an enum from field names used in the ProtoBuf definition. + pub fn from_str_name(value: &str) -> ::core::option::Option { + match value { + "IncompatibleRequestReasonUnknown" => Some(Self::Unknown), + "IncompatibleRequestReasonTxnProtocolVersionOutOfRange" => { + Some(Self::TxnProtocolVersionOutOfRange) + } + _ => None, + } + } } diff --git a/src/generated/keyspacepb.rs b/src/generated/keyspacepb.rs index 53e3bb003..19c88cfc8 100644 --- a/src/generated/keyspacepb.rs +++ b/src/generated/keyspacepb.rs @@ -2,6 +2,38 @@ #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] pub struct KeyspaceMeta { + #[prost(string, tag = "2")] + pub name: ::prost::alloc::string::String, + #[prost(enumeration = "KeyspaceState", tag = "3")] + pub state: i32, + #[prost(int64, tag = "4")] + pub created_at: i64, + #[prost(int64, tag = "5")] + pub state_changed_at: i64, + #[prost(map = "string, string", tag = "7")] + pub config: ::std::collections::HashMap< + ::prost::alloc::string::String, + ::prost::alloc::string::String, + >, + #[prost(oneof = "keyspace_meta::Keyspace", tags = "1, 8")] + pub keyspace: ::core::option::Option, +} +/// Nested message and enum types in `KeyspaceMeta`. +pub mod keyspace_meta { + #[allow(clippy::derive_partial_eq_without_eq)] + #[derive(Clone, PartialEq, ::prost::Oneof)] + pub enum Keyspace { + /// V1/V2 compatibility keyspace id. V3 should read keyspace_identity instead. + #[prost(uint32, tag = "1")] + Id(u32), + /// Canonical V3 keyspace identity. + #[prost(message, tag = "8")] + KeyspaceIdentity(super::super::apipb::KeyspaceIdentity), + } +} +#[allow(clippy::derive_partial_eq_without_eq)] +#[derive(Clone, PartialEq, ::prost::Message)] +pub struct NamespaceMeta { #[prost(uint32, tag = "1")] pub id: u32, #[prost(string, tag = "2")] @@ -20,19 +52,127 @@ pub struct KeyspaceMeta { } #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] +pub struct NamespaceRef { + #[prost(oneof = "namespace_ref::Namespace", tags = "1, 2")] + pub namespace: ::core::option::Option, +} +/// Nested message and enum types in `NamespaceRef`. +pub mod namespace_ref { + #[allow(clippy::derive_partial_eq_without_eq)] + #[derive(Clone, PartialEq, ::prost::Oneof)] + pub enum Namespace { + /// API V3 namespace id. + #[prost(uint32, tag = "1")] + NamespaceId(u32), + /// API V3 namespace name. + #[prost(string, tag = "2")] + NamespaceName(::prost::alloc::string::String), + } +} +#[allow(clippy::derive_partial_eq_without_eq)] +#[derive(Clone, PartialEq, ::prost::Message)] +pub struct CreateNamespaceRequest { + #[prost(message, optional, tag = "1")] + pub header: ::core::option::Option, + #[prost(string, tag = "2")] + pub name: ::prost::alloc::string::String, + #[prost(map = "string, string", tag = "3")] + pub config: ::std::collections::HashMap< + ::prost::alloc::string::String, + ::prost::alloc::string::String, + >, +} +#[allow(clippy::derive_partial_eq_without_eq)] +#[derive(Clone, PartialEq, ::prost::Message)] +pub struct CreateNamespaceResponse { + #[prost(message, optional, tag = "1")] + pub header: ::core::option::Option, + #[prost(message, optional, tag = "2")] + pub namespace: ::core::option::Option, +} +#[allow(clippy::derive_partial_eq_without_eq)] +#[derive(Clone, PartialEq, ::prost::Message)] +pub struct LoadNamespaceRequest { + #[prost(message, optional, tag = "1")] + pub header: ::core::option::Option, + #[prost(message, optional, tag = "2")] + pub namespace: ::core::option::Option, +} +#[allow(clippy::derive_partial_eq_without_eq)] +#[derive(Clone, PartialEq, ::prost::Message)] +pub struct LoadNamespaceResponse { + #[prost(message, optional, tag = "1")] + pub header: ::core::option::Option, + #[prost(message, optional, tag = "2")] + pub namespace: ::core::option::Option, +} +#[allow(clippy::derive_partial_eq_without_eq)] +#[derive(Clone, PartialEq, ::prost::Message)] +pub struct GetAllNamespacesRequest { + #[prost(message, optional, tag = "1")] + pub header: ::core::option::Option, + #[prost(uint32, tag = "2")] + pub start_id: u32, + #[prost(uint32, tag = "3")] + pub limit: u32, +} +#[allow(clippy::derive_partial_eq_without_eq)] +#[derive(Clone, PartialEq, ::prost::Message)] +pub struct GetAllNamespacesResponse { + #[prost(message, optional, tag = "1")] + pub header: ::core::option::Option, + #[prost(message, repeated, tag = "2")] + pub namespaces: ::prost::alloc::vec::Vec, +} +#[allow(clippy::derive_partial_eq_without_eq)] +#[derive(Clone, PartialEq, ::prost::Message)] +pub struct UpdateNamespaceStateRequest { + #[prost(message, optional, tag = "1")] + pub header: ::core::option::Option, + #[prost(message, optional, tag = "2")] + pub namespace: ::core::option::Option, + #[prost(enumeration = "KeyspaceState", tag = "3")] + pub state: i32, +} +#[allow(clippy::derive_partial_eq_without_eq)] +#[derive(Clone, PartialEq, ::prost::Message)] +pub struct UpdateNamespaceStateResponse { + #[prost(message, optional, tag = "1")] + pub header: ::core::option::Option, + #[prost(message, optional, tag = "2")] + pub namespace: ::core::option::Option, +} +#[allow(clippy::derive_partial_eq_without_eq)] +#[derive(Clone, PartialEq, ::prost::Message)] pub struct LoadKeyspaceRequest { #[prost(message, optional, tag = "1")] pub header: ::core::option::Option, #[prost(string, tag = "2")] pub name: ::prost::alloc::string::String, + /// V3 namespace-scoped name lookup. If unset, V3 name-only lookup should use LookupKeyspace and may return multiple keyspaces. + #[prost(message, optional, tag = "3")] + pub namespace: ::core::option::Option, } #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] pub struct LoadKeyspaceByIdRequest { #[prost(message, optional, tag = "1")] pub header: ::core::option::Option, - #[prost(uint32, tag = "2")] - pub id: u32, + #[prost(oneof = "load_keyspace_by_id_request::Keyspace", tags = "2, 3")] + pub keyspace: ::core::option::Option, +} +/// Nested message and enum types in `LoadKeyspaceByIDRequest`. +pub mod load_keyspace_by_id_request { + #[allow(clippy::derive_partial_eq_without_eq)] + #[derive(Clone, PartialEq, ::prost::Oneof)] + pub enum Keyspace { + /// V1/V2 compatibility keyspace id. V3 should use keyspace_identity. + #[prost(uint32, tag = "2")] + Id(u32), + /// V3 keyspace identity. + #[prost(message, tag = "3")] + KeyspaceIdentity(super::super::apipb::KeyspaceIdentity), + } } #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] @@ -44,6 +184,22 @@ pub struct LoadKeyspaceResponse { } #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] +pub struct LookupKeyspaceRequest { + #[prost(message, optional, tag = "1")] + pub header: ::core::option::Option, + #[prost(string, tag = "2")] + pub name: ::prost::alloc::string::String, +} +#[allow(clippy::derive_partial_eq_without_eq)] +#[derive(Clone, PartialEq, ::prost::Message)] +pub struct LookupKeyspaceResponse { + #[prost(message, optional, tag = "1")] + pub header: ::core::option::Option, + #[prost(message, repeated, tag = "2")] + pub keyspaces: ::prost::alloc::vec::Vec, +} +#[allow(clippy::derive_partial_eq_without_eq)] +#[derive(Clone, PartialEq, ::prost::Message)] pub struct WatchKeyspacesRequest { #[prost(message, optional, tag = "1")] pub header: ::core::option::Option, @@ -61,10 +217,23 @@ pub struct WatchKeyspacesResponse { pub struct UpdateKeyspaceStateRequest { #[prost(message, optional, tag = "1")] pub header: ::core::option::Option, - #[prost(uint32, tag = "2")] - pub id: u32, #[prost(enumeration = "KeyspaceState", tag = "3")] pub state: i32, + #[prost(oneof = "update_keyspace_state_request::Keyspace", tags = "2, 4")] + pub keyspace: ::core::option::Option, +} +/// Nested message and enum types in `UpdateKeyspaceStateRequest`. +pub mod update_keyspace_state_request { + #[allow(clippy::derive_partial_eq_without_eq)] + #[derive(Clone, PartialEq, ::prost::Oneof)] + pub enum Keyspace { + /// V1/V2 compatibility keyspace id. V3 should use keyspace_identity. + #[prost(uint32, tag = "2")] + Id(u32), + /// V3 keyspace identity. + #[prost(message, tag = "4")] + KeyspaceIdentity(super::super::apipb::KeyspaceIdentity), + } } #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] @@ -79,10 +248,26 @@ pub struct UpdateKeyspaceStateResponse { pub struct GetAllKeyspacesRequest { #[prost(message, optional, tag = "1")] pub header: ::core::option::Option, - #[prost(uint32, tag = "2")] - pub start_id: u32, #[prost(uint32, tag = "3")] pub limit: u32, + /// V3 namespace-scoped pagination. Must be non-zero in V3. + #[prost(message, optional, tag = "4")] + pub namespace: ::core::option::Option, + #[prost(oneof = "get_all_keyspaces_request::StartKeyspace", tags = "2, 5")] + pub start_keyspace: ::core::option::Option, +} +/// Nested message and enum types in `GetAllKeyspacesRequest`. +pub mod get_all_keyspaces_request { + #[allow(clippy::derive_partial_eq_without_eq)] + #[derive(Clone, PartialEq, ::prost::Oneof)] + pub enum StartKeyspace { + /// V1/V2 compatibility pagination cursor. V3 should use namespace_id and start_keyspace_identity. + #[prost(uint32, tag = "2")] + StartId(u32), + /// V3 pagination cursor within namespace_id. + #[prost(message, tag = "5")] + StartKeyspaceIdentity(super::super::apipb::KeyspaceIdentity), + } } #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] @@ -125,6 +310,194 @@ impl KeyspaceState { } } /// Generated client implementations. +pub mod namespace_client { + #![allow(unused_variables, dead_code, missing_docs, clippy::let_unit_value)] + use tonic::codegen::*; + use tonic::codegen::http::Uri; + /// Namespace provides services to manage namespaces. + #[derive(Debug, Clone)] + pub struct NamespaceClient { + inner: tonic::client::Grpc, + } + impl NamespaceClient { + /// Attempt to create a new client by connecting to a given endpoint. + pub async fn connect(dst: D) -> Result + where + D: TryInto, + D::Error: Into, + { + let conn = tonic::transport::Endpoint::new(dst)?.connect().await?; + Ok(Self::new(conn)) + } + } + impl NamespaceClient + where + T: tonic::client::GrpcService, + T::Error: Into, + T::ResponseBody: Body + Send + 'static, + ::Error: Into + Send, + { + pub fn new(inner: T) -> Self { + let inner = tonic::client::Grpc::new(inner); + Self { inner } + } + pub fn with_origin(inner: T, origin: Uri) -> Self { + let inner = tonic::client::Grpc::with_origin(inner, origin); + Self { inner } + } + pub fn with_interceptor( + inner: T, + interceptor: F, + ) -> NamespaceClient> + where + F: tonic::service::Interceptor, + T::ResponseBody: Default, + T: tonic::codegen::Service< + http::Request, + Response = http::Response< + >::ResponseBody, + >, + >, + , + >>::Error: Into + Send + Sync, + { + NamespaceClient::new(InterceptedService::new(inner, interceptor)) + } + /// Compress requests with the given encoding. + /// + /// This requires the server to support it otherwise it might respond with an + /// error. + #[must_use] + pub fn send_compressed(mut self, encoding: CompressionEncoding) -> Self { + self.inner = self.inner.send_compressed(encoding); + self + } + /// Enable decompressing responses. + #[must_use] + pub fn accept_compressed(mut self, encoding: CompressionEncoding) -> Self { + self.inner = self.inner.accept_compressed(encoding); + self + } + /// Limits the maximum size of a decoded message. + /// + /// Default: `4MB` + #[must_use] + pub fn max_decoding_message_size(mut self, limit: usize) -> Self { + self.inner = self.inner.max_decoding_message_size(limit); + self + } + /// Limits the maximum size of an encoded message. + /// + /// Default: `usize::MAX` + #[must_use] + pub fn max_encoding_message_size(mut self, limit: usize) -> Self { + self.inner = self.inner.max_encoding_message_size(limit); + self + } + pub async fn create_namespace( + &mut self, + request: impl tonic::IntoRequest, + ) -> std::result::Result< + tonic::Response, + tonic::Status, + > { + self.inner + .ready() + .await + .map_err(|e| { + tonic::Status::new( + tonic::Code::Unknown, + format!("Service was not ready: {}", e.into()), + ) + })?; + let codec = tonic::codec::ProstCodec::default(); + let path = http::uri::PathAndQuery::from_static( + "/keyspacepb.Namespace/CreateNamespace", + ); + let mut req = request.into_request(); + req.extensions_mut() + .insert(GrpcMethod::new("keyspacepb.Namespace", "CreateNamespace")); + self.inner.unary(req, path, codec).await + } + pub async fn load_namespace( + &mut self, + request: impl tonic::IntoRequest, + ) -> std::result::Result< + tonic::Response, + tonic::Status, + > { + self.inner + .ready() + .await + .map_err(|e| { + tonic::Status::new( + tonic::Code::Unknown, + format!("Service was not ready: {}", e.into()), + ) + })?; + let codec = tonic::codec::ProstCodec::default(); + let path = http::uri::PathAndQuery::from_static( + "/keyspacepb.Namespace/LoadNamespace", + ); + let mut req = request.into_request(); + req.extensions_mut() + .insert(GrpcMethod::new("keyspacepb.Namespace", "LoadNamespace")); + self.inner.unary(req, path, codec).await + } + pub async fn get_all_namespaces( + &mut self, + request: impl tonic::IntoRequest, + ) -> std::result::Result< + tonic::Response, + tonic::Status, + > { + self.inner + .ready() + .await + .map_err(|e| { + tonic::Status::new( + tonic::Code::Unknown, + format!("Service was not ready: {}", e.into()), + ) + })?; + let codec = tonic::codec::ProstCodec::default(); + let path = http::uri::PathAndQuery::from_static( + "/keyspacepb.Namespace/GetAllNamespaces", + ); + let mut req = request.into_request(); + req.extensions_mut() + .insert(GrpcMethod::new("keyspacepb.Namespace", "GetAllNamespaces")); + self.inner.unary(req, path, codec).await + } + pub async fn update_namespace_state( + &mut self, + request: impl tonic::IntoRequest, + ) -> std::result::Result< + tonic::Response, + tonic::Status, + > { + self.inner + .ready() + .await + .map_err(|e| { + tonic::Status::new( + tonic::Code::Unknown, + format!("Service was not ready: {}", e.into()), + ) + })?; + let codec = tonic::codec::ProstCodec::default(); + let path = http::uri::PathAndQuery::from_static( + "/keyspacepb.Namespace/UpdateNamespaceState", + ); + let mut req = request.into_request(); + req.extensions_mut() + .insert(GrpcMethod::new("keyspacepb.Namespace", "UpdateNamespaceState")); + self.inner.unary(req, path, codec).await + } + } +} +/// Generated client implementations. pub mod keyspace_client { #![allow(unused_variables, dead_code, missing_docs, clippy::let_unit_value)] use tonic::codegen::*; @@ -235,6 +608,31 @@ pub mod keyspace_client { .insert(GrpcMethod::new("keyspacepb.Keyspace", "LoadKeyspace")); self.inner.unary(req, path, codec).await } + pub async fn lookup_keyspace( + &mut self, + request: impl tonic::IntoRequest, + ) -> std::result::Result< + tonic::Response, + tonic::Status, + > { + self.inner + .ready() + .await + .map_err(|e| { + tonic::Status::new( + tonic::Code::Unknown, + format!("Service was not ready: {}", e.into()), + ) + })?; + let codec = tonic::codec::ProstCodec::default(); + let path = http::uri::PathAndQuery::from_static( + "/keyspacepb.Keyspace/LookupKeyspace", + ); + let mut req = request.into_request(); + req.extensions_mut() + .insert(GrpcMethod::new("keyspacepb.Keyspace", "LookupKeyspace")); + self.inner.unary(req, path, codec).await + } pub async fn load_keyspace_by_id( &mut self, request: impl tonic::IntoRequest, diff --git a/src/generated/kvrpcpb.rs b/src/generated/kvrpcpb.rs index 89f2d472d..4847ac1d8 100644 --- a/src/generated/kvrpcpb.rs +++ b/src/generated/kvrpcpb.rs @@ -1290,21 +1290,13 @@ pub struct Context { /// Some information used for resource control. #[prost(message, optional, tag = "28")] pub resource_control_context: ::core::option::Option, - /// The declared origin of the request. TiDB server requests set this to TIDB. - /// This field is client-provided metadata; consumers should rely on it only when - /// the caller is authenticated/authorized by the transport or deployment boundary. - /// UNKNOWN means the origin is unset or not recognized by this protocol version. - /// Other components should add dedicated enum variants when they need origin-specific behavior. + /// Declared process/product origin; see RequestOrigin. #[prost(enumeration = "RequestOrigin", tag = "29")] pub request_origin: i32, /// The keyspace that the request is sent to. /// NOTE: This field is only meaningful while the api_version is V2. #[prost(string, tag = "31")] pub keyspace_name: ::prost::alloc::string::String, - /// The keyspace that the request is sent to. - /// NOTE: This field is only meaningful while the api_version is V2. - #[prost(uint32, tag = "32")] - pub keyspace_id: u32, /// The buckets version that the request is sent to. /// NOTE: This field is only meaningful while enable buckets. #[prost(uint64, tag = "33")] @@ -1328,6 +1320,32 @@ pub struct Context { /// This field is set by client-go based on an extractor function provided by TiDB. #[prost(uint64, tag = "37")] pub trace_control_flags: u64, + /// Transaction protocol version declared for this request; see TxnProtocolVersion. + /// Missing or zero means legacy. Any nonzero value promises structured + /// IncompatibleRequest handling. BatchCommands declares this per inner request. + /// This is a compatibility declaration, not a binary version or authorization. + /// Keep uint32 so future version values remain representable. + #[prost(uint32, tag = "39")] + pub txn_protocol_version: u32, + #[prost(oneof = "context::Keyspace", tags = "32, 38")] + pub keyspace: ::core::option::Option, +} +/// Nested message and enum types in `Context`. +pub mod context { + #[allow(clippy::derive_partial_eq_without_eq)] + #[derive(Clone, PartialEq, ::prost::Oneof)] + pub enum Keyspace { + /// The keyspace that the request is sent to. + /// NOTE: This field is only meaningful while the api_version is V2. + /// V3 uses keyspace_identity and must not read this legacy field as the full identity. + #[prost(uint32, tag = "32")] + KeyspaceId(u32), + /// The V3 keyspace identity that the request is sent to. + /// V3 RPC key fields carry user key bytes; TiKV encodes the physical + /// mode + namespace + keyspace prefix at the serving boundary. + #[prost(message, tag = "38")] + KeyspaceIdentity(super::super::apipb::KeyspaceIdentity), + } } #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] @@ -1390,9 +1408,8 @@ pub struct LockInfo { /// When lock_type is SharedLock, this describes transactions holding the shared lock. /// Important: when lock_type is SharedLock, all shared locks must use shared_lock_infos; /// DO NOT read from the wrapper LockInfo. - /// TODO(slock): tidb should send requests with a feature flag to indicate whether it - /// supports shared locks, so that tikv can fail the requests from old tidb versions - /// when needed. + /// Before returning a shared lock wrapper, the server must check the caller's + /// txn_protocol_version and return IncompatibleRequest if support is insufficient. #[prost(message, repeated, tag = "12")] pub shared_lock_infos: ::prost::alloc::vec::Vec, /// Reserved for file based transaction. @@ -1438,6 +1455,12 @@ pub struct KeyError { /// TxnLockNotFound indicates the txn lock is not found. #[prost(message, optional, tag = "12")] pub txn_lock_not_found: ::core::option::Option, + /// LockUpgradeConflict indicates a shared-lock upgrade protocol conflict. + #[prost(message, optional, tag = "13")] + pub lock_upgrade_conflict: ::core::option::Option, + /// SharedLockLost deterministically confirms that the transaction's shared-lock ownership was lost. + #[prost(message, optional, tag = "14")] + pub shared_lock_lost: ::core::option::Option, /// Extra information for error debugging #[prost(message, optional, tag = "100")] pub debug_info: ::core::option::Option, @@ -1520,6 +1543,70 @@ pub mod write_conflict { } #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] +pub struct LockUpgradeConflict { + #[prost(bytes = "vec", tag = "1")] + pub key: ::prost::alloc::vec::Vec, + #[prost(uint64, tag = "2")] + pub start_ts: u64, + #[prost(uint64, tag = "3")] + pub owner_start_ts: u64, + #[prost(enumeration = "lock_upgrade_conflict::Reason", tag = "4")] + pub reason: i32, +} +/// Nested message and enum types in `LockUpgradeConflict`. +pub mod lock_upgrade_conflict { + #[derive( + Clone, + Copy, + Debug, + PartialEq, + Eq, + Hash, + PartialOrd, + Ord, + ::prost::Enumeration + )] + #[repr(i32)] + pub enum Reason { + Unknown = 0, + DuplicateInFlight = 1, + SecondUpgrader = 2, + } + impl Reason { + /// String value of the enum field names used in the ProtoBuf definition. + /// + /// The values are not transformed in any way and thus are considered stable + /// (if the ProtoBuf definition does not change) and safe for programmatic use. + pub fn as_str_name(&self) -> &'static str { + match self { + Reason::Unknown => "Unknown", + Reason::DuplicateInFlight => "DuplicateInFlight", + Reason::SecondUpgrader => "SecondUpgrader", + } + } + /// Creates an enum from field names used in the ProtoBuf definition. + pub fn from_str_name(value: &str) -> ::core::option::Option { + match value { + "Unknown" => Some(Self::Unknown), + "DuplicateInFlight" => Some(Self::DuplicateInFlight), + "SecondUpgrader" => Some(Self::SecondUpgrader), + _ => None, + } + } + } +} +/// SharedLockLost means the pending upgrade did not acquire the exclusive lock. +/// The transaction must not continue, but rollback remains valid. +#[allow(clippy::derive_partial_eq_without_eq)] +#[derive(Clone, PartialEq, ::prost::Message)] +pub struct SharedLockLost { + #[prost(bytes = "vec", tag = "1")] + pub key: ::prost::alloc::vec::Vec, + #[prost(uint64, tag = "2")] + pub start_ts: u64, +} +#[allow(clippy::derive_partial_eq_without_eq)] +#[derive(Clone, PartialEq, ::prost::Message)] pub struct AlreadyExist { #[prost(bytes = "vec", tag = "1")] pub key: ::prost::alloc::vec::Vec, @@ -1784,6 +1871,102 @@ pub struct ExecDetailsV2 { /// RU (Request Unit) consumption details. #[prost(message, optional, tag = "5")] pub ru_v2: ::core::option::Option, + /// Scheduling and execution details for the request's read-pool task. + /// Available when read-pool task tracking is enabled in TiKV. + #[prost(message, optional, tag = "6")] + pub read_pool_task_details: ::core::option::Option, +} +/// Scheduling and execution details collected across all polls of one task running in a pool. +/// The timing model is: +/// total_wall_nanos +/// \<---------------------------------------------------------------------> +/// +/// ```text +/// submitted worker starts async event worker starts done +/// │ │ completes │ │ +/// ▼ ▼ ▼ ▼ ▼ +/// ┌──────────────┬─────────────────┬─────────────────┬──────────────┬──────┐ +/// │ Queue Wait │ Poll Execution │ Async/Wake Wait │ Queue Wait │ Poll │ +/// │ │ │ │ │ Exec │ +/// │ task is │ Future::poll │ Future is │ task is │ │ +/// │ runnable, │ returns Pending │ Pending, waiting│ runnable, │Ready │ +/// │ waiting for │ │ for I/O, timer, │ waiting for │ │ +/// │ a worker │ │ lock, etc. │ a worker │ │ +/// └──────────────┴─────────────────┴─────────────────┴──────────────┴──────┘ +/// │ │ │ +/// │ │ └─ total/max/min_wake_wait_nanos +/// │ │ +/// │ ├─ poll_wall_nanos +/// │ └─ poll_cpu_nanos +/// │ +/// ├─ total/max/min_queue_wait_nanos +/// └─ fair_queue_waited_task_slices +/// ``` +#[allow(clippy::derive_partial_eq_without_eq)] +#[derive(Clone, PartialEq, ::prost::Message)] +pub struct PoolTaskDetails { + /// Number of Future::poll calls, including immediate repolls within one worker dispatch. + #[prost(uint64, tag = "1")] + pub poll_count: u64, + /// Number of worker dispatches. Immediate repolls in one dispatch are not counted separately. + #[prost(uint64, tag = "2")] + pub dispatch_count: u64, + /// Wall time from immediately before the initial pool submission until the final poll completes. + #[prost(uint64, tag = "3")] + pub total_wall_nanos: u64, + /// Total time from enqueueing a ready task until a worker starts dispatching it. + /// Zero when no queue-wait sample was recorded. + #[prost(uint64, tag = "4")] + pub total_queue_wait_nanos: u64, + /// Maximum queue wait time among all dispatches. + #[prost(uint64, tag = "5")] + pub max_queue_wait_nanos: u64, + /// Minimum queue wait time among all dispatches. + #[prost(uint64, tag = "6")] + pub min_queue_wait_nanos: u64, + /// Total time from a pending poll's completion until the task is scheduled again. + /// Zero when no wake-wait sample was recorded. + #[prost(uint64, tag = "7")] + pub total_wake_wait_nanos: u64, + /// Maximum wake wait time among all wakeups. + #[prost(uint64, tag = "8")] + pub max_wake_wait_nanos: u64, + /// Minimum wake wait time among all wakeups. + #[prost(uint64, tag = "9")] + pub min_wake_wait_nanos: u64, + /// Whether fair-queue waited-slice data was collected for this task. + #[prost(bool, tag = "10")] + pub fair_queue_enabled: bool, + /// Total number of task slices dispatched ahead of this task while it waited in the fair queue. + /// Zero when no fair-queue wait sample was recorded. + #[prost(uint64, tag = "11")] + pub total_fair_queue_waited_task_slices: u64, + /// Maximum number of task slices dispatched ahead of this task during one fair-queue wait. + #[prost(uint64, tag = "12")] + pub max_fair_queue_waited_task_slices: u64, + /// Minimum number of task slices dispatched ahead of this task during one fair-queue wait. + #[prost(uint64, tag = "13")] + pub min_fair_queue_waited_task_slices: u64, + /// Total thread CPU time consumed by Future::poll calls. + /// Zero when no poll sample was recorded. + #[prost(uint64, tag = "14")] + pub poll_cpu_nanos: u64, + /// Maximum thread CPU time consumed by one Future::poll call. + #[prost(uint64, tag = "15")] + pub max_poll_cpu_nanos: u64, + /// Minimum thread CPU time consumed by one Future::poll call. + #[prost(uint64, tag = "16")] + pub min_poll_cpu_nanos: u64, + /// Total wall time consumed by Future::poll calls. + /// Zero when no poll sample was recorded. + #[prost(uint64, tag = "17")] + pub poll_wall_nanos: u64, + /// Minimum wall time consumed by one Future::poll call. + #[prost(uint64, tag = "18")] + pub min_poll_wall_nanos: u64, + /// Maximum wall time consumed by one Future::poll call. + #[prost(uint64, tag = "19")] + pub max_poll_wall_nanos: u64, } #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] @@ -2251,9 +2434,23 @@ pub struct CompactRequest { /// API version of the request #[prost(enumeration = "ApiVersion", tag = "7")] pub api_version: i32, - /// Keyspace of the table located in. - #[prost(uint32, tag = "8")] - pub keyspace_id: u32, + #[prost(oneof = "compact_request::Keyspace", tags = "8, 9")] + pub keyspace: ::core::option::Option, +} +/// Nested message and enum types in `CompactRequest`. +pub mod compact_request { + #[allow(clippy::derive_partial_eq_without_eq)] + #[derive(Clone, PartialEq, ::prost::Oneof)] + pub enum Keyspace { + /// Keyspace of the table located in. + /// NOTE: This field is only meaningful for V1/V2 compatibility. V3 uses + /// keyspace_identity and must not read this field as the full identity. + #[prost(uint32, tag = "8")] + KeyspaceId(u32), + /// V3 keyspace identity of the table located in. + #[prost(message, tag = "9")] + KeyspaceIdentity(super::super::apipb::KeyspaceIdentity), + } } #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] @@ -2375,6 +2572,23 @@ pub struct HealthFeedback { /// be replaced by `SlowTrend` in the future. #[prost(int32, tag = "3")] pub slow_score: i32, + /// The resource groups that the store currently blames for its own overload, if it reports them + /// at all. A store that does not support reporting them leaves this field unset, which is why + /// this is a message rather than a bare repeated field: an unset field and an empty list have + /// to mean different things to the client. + #[prost(message, optional, tag = "4")] + pub noisy_groups: ::core::option::Option, +} +/// NoisyGroups is the set of resource groups a store holds responsible for its own overload, as +/// judged by that store alone at the time the feedback was generated. +/// +/// An empty `names` is a positive statement that the store currently blames nobody, so a client can +/// treat each message as replacing whatever it previously knew about that store. +#[allow(clippy::derive_partial_eq_without_eq)] +#[derive(Clone, PartialEq, ::prost::Message)] +pub struct NoisyGroups { + #[prost(string, repeated, tag = "1")] + pub names: ::prost::alloc::vec::Vec<::prost::alloc::string::String>, } #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] @@ -2503,11 +2717,18 @@ impl CommitRole { } } } +/// Client-provided process/product identity for auditing, not authentication or +/// authorization. TiDB includes embedded BR; standalone BR uses RequestOriginBR. +/// Audit unknown values without mapping them to a known origin or rejecting +/// requests solely because of their origin in the initial rollout. #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, ::prost::Enumeration)] #[repr(i32)] pub enum RequestOrigin { Unknown = 0, TiDb = 1, + TiCdc = 2, + Br = 3, + TiFlash = 4, } impl RequestOrigin { /// String value of the enum field names used in the ProtoBuf definition. @@ -2518,6 +2739,9 @@ impl RequestOrigin { match self { RequestOrigin::Unknown => "RequestOriginUnknown", RequestOrigin::TiDb => "RequestOriginTiDB", + RequestOrigin::TiCdc => "RequestOriginTiCDC", + RequestOrigin::Br => "RequestOriginBR", + RequestOrigin::TiFlash => "RequestOriginTiFlash", } } /// Creates an enum from field names used in the ProtoBuf definition. @@ -2525,6 +2749,9 @@ impl RequestOrigin { match value { "RequestOriginUnknown" => Some(Self::Unknown), "RequestOriginTiDB" => Some(Self::TiDb), + "RequestOriginTiCDC" => Some(Self::TiCdc), + "RequestOriginBR" => Some(Self::Br), + "RequestOriginTiFlash" => Some(Self::TiFlash), _ => None, } } @@ -2583,6 +2810,11 @@ pub enum ApiVersion { /// V2 server accpets V2 requests and V1 transactional requests that statrts with TiDB key /// prefix (`m` and `t`). V2 = 2, + /// `V3` uses user-key wire semantics for normal KV RPCs. Servers encode an + /// 8-byte physical prefix at the serving boundary: + /// mode(1) + namespace_id(4 bytes, big endian) + keyspace_id(3 bytes, big endian). + /// The keyspace identity is carried by Context.keyspace_identity. + V3 = 3, } impl ApiVersion { /// String value of the enum field names used in the ProtoBuf definition. @@ -2594,6 +2826,7 @@ impl ApiVersion { ApiVersion::V1 => "V1", ApiVersion::V1ttl => "V1TTL", ApiVersion::V2 => "V2", + ApiVersion::V3 => "V3", } } /// Creates an enum from field names used in the ProtoBuf definition. @@ -2602,6 +2835,48 @@ impl ApiVersion { "V1" => Some(Self::V1), "V1TTL" => Some(Self::V1ttl), "V2" => Some(Self::V2), + "V3" => Some(Self::V3), + _ => None, + } + } +} +/// Transaction protocol version registry. Each version includes all earlier +/// semantics. Keep values stable; new versions require joint review by TiKV, +/// TiDB and relevant client owners. This registry sets neither client defaults +/// nor the store's admission range. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, ::prost::Enumeration)] +#[repr(i32)] +pub enum TxnProtocolVersion { + /// No promise to handle IncompatibleRequest. + TxnVerLegacy = 0, + /// Handles IncompatibleRequest according to its error contract. + TxnVerSupportIncompatibleErrorHandling = 1, + /// Also supports shared wrapper parsing and expansion, nested lock information + /// preservation, and shared-lock pagination and resolve semantics. + TxnVerSupportSharedLock = 2, +} +impl TxnProtocolVersion { + /// String value of the enum field names used in the ProtoBuf definition. + /// + /// The values are not transformed in any way and thus are considered stable + /// (if the ProtoBuf definition does not change) and safe for programmatic use. + pub fn as_str_name(&self) -> &'static str { + match self { + TxnProtocolVersion::TxnVerLegacy => "TXN_VER_LEGACY", + TxnProtocolVersion::TxnVerSupportIncompatibleErrorHandling => { + "TXN_VER_SUPPORT_INCOMPATIBLE_ERROR_HANDLING" + } + TxnProtocolVersion::TxnVerSupportSharedLock => "TXN_VER_SUPPORT_SHARED_LOCK", + } + } + /// Creates an enum from field names used in the ProtoBuf definition. + pub fn from_str_name(value: &str) -> ::core::option::Option { + match value { + "TXN_VER_LEGACY" => Some(Self::TxnVerLegacy), + "TXN_VER_SUPPORT_INCOMPATIBLE_ERROR_HANDLING" => { + Some(Self::TxnVerSupportIncompatibleErrorHandling) + } + "TXN_VER_SUPPORT_SHARED_LOCK" => Some(Self::TxnVerSupportSharedLock), _ => None, } } diff --git a/src/generated/metapb.rs b/src/generated/metapb.rs index 7ee897eb8..575c9080e 100644 --- a/src/generated/metapb.rs +++ b/src/generated/metapb.rs @@ -57,6 +57,22 @@ pub struct Store { /// NodeState is used to replace StoreState which will be deprecated in the future. #[prost(enumeration = "NodeState", tag = "13")] pub node_state: i32, + /// The store's current transaction RPC admission range, not a feature switch or + /// a value derived from Store.version. Absence means legacy/unknown; clients + /// conservatively use \[0, 0\] while preserving absence versus an explicit \[0, 0\]. + /// Consumers must fail closed if min > max. TiKV reports this on every startup, + /// including upgrades and rollbacks; PD updates and persists it. + #[prost(message, optional, tag = "14")] + pub txn_protocol_version_range: ::core::option::Option, +} +/// Inclusive transaction protocol version bounds; see kvrpcpb.TxnProtocolVersion. +#[allow(clippy::derive_partial_eq_without_eq)] +#[derive(Clone, PartialEq, ::prost::Message)] +pub struct TxnProtocolVersionRange { + #[prost(uint32, tag = "1")] + pub min: u32, + #[prost(uint32, tag = "2")] + pub max: u32, } #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] diff --git a/src/generated/mod.rs b/src/generated/mod.rs index da3c98ea3..8478a732f 100644 --- a/src/generated/mod.rs +++ b/src/generated/mod.rs @@ -1,4 +1,7 @@ // This file is @generated by prost-build. +pub mod apipb { + include!("apipb.rs"); +} pub mod autoid { include!("autoid.rs"); } diff --git a/src/generated/mpp.rs b/src/generated/mpp.rs index 2ee84475e..b90360733 100644 --- a/src/generated/mpp.rs +++ b/src/generated/mpp.rs @@ -30,9 +30,6 @@ pub struct TaskMeta { /// mpp version #[prost(int64, tag = "9")] pub mpp_version: i64, - /// keyspace id of the request - #[prost(uint32, tag = "10")] - pub keyspace_id: u32, /// coordinator_address of this query #[prost(string, tag = "11")] pub coordinator_address: ::prost::alloc::string::String, @@ -54,6 +51,21 @@ pub struct TaskMeta { pub sql_digest: ::prost::alloc::string::String, #[prost(string, tag = "21")] pub plan_digest: ::prost::alloc::string::String, + #[prost(oneof = "task_meta::Keyspace", tags = "10, 22")] + pub keyspace: ::core::option::Option, +} +/// Nested message and enum types in `TaskMeta`. +pub mod task_meta { + #[allow(clippy::derive_partial_eq_without_eq)] + #[derive(Clone, PartialEq, ::prost::Oneof)] + pub enum Keyspace { + /// V1/V2 compatibility keyspace id of the request. V3 should use keyspace_identity. + #[prost(uint32, tag = "10")] + KeyspaceId(u32), + /// V3 keyspace identity of the request. + #[prost(message, tag = "22")] + KeyspaceIdentity(super::super::apipb::KeyspaceIdentity), + } } #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] diff --git a/src/generated/pdpb.rs b/src/generated/pdpb.rs index 771870565..a2a897e70 100644 --- a/src/generated/pdpb.rs +++ b/src/generated/pdpb.rs @@ -100,6 +100,7 @@ pub struct Error { #[prost(string, tag = "2")] pub message: ::prost::alloc::string::String, } +/// This message intentionally omits namespace/keyspace-related fields because API v2 never supported keyspaces when routing TSO requests through the PD API server. #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] pub struct TsoRequest { @@ -256,6 +257,7 @@ pub struct GetAllStoresResponse { pub struct GetRegionRequest { #[prost(message, optional, tag = "1")] pub header: ::core::option::Option, + /// Physical key bytes used for Region lookup. #[prost(bytes = "vec", tag = "2")] pub region_key: ::prost::alloc::vec::Vec, #[prost(bool, tag = "3")] @@ -302,10 +304,10 @@ pub struct QueryRegionRequest { /// The region IDs to query. #[prost(uint64, repeated, tag = "3")] pub ids: ::prost::alloc::vec::Vec, - /// The region keys to query. + /// Physical key bytes to query. #[prost(bytes = "vec", repeated, tag = "4")] pub keys: ::prost::alloc::vec::Vec<::prost::alloc::vec::Vec>, - /// The previous region keys to query. + /// Previous physical key bytes to query. #[prost(bytes = "vec", repeated, tag = "5")] pub prev_keys: ::prost::alloc::vec::Vec<::prost::alloc::vec::Vec>, } @@ -347,12 +349,13 @@ pub struct RegionResponse { pub struct ScanRegionsRequest { #[prost(message, optional, tag = "1")] pub header: ::core::option::Option, + /// Physical start key bytes. #[prost(bytes = "vec", tag = "2")] pub start_key: ::prost::alloc::vec::Vec, /// no limit when limit \<= 0. #[prost(int32, tag = "3")] pub limit: i32, - /// end_key is +inf when it is empty. + /// Physical end key bytes. end_key is +inf when it is empty. #[prost(bytes = "vec", tag = "4")] pub end_key: ::prost::alloc::vec::Vec, } @@ -391,9 +394,10 @@ pub struct ScanRegionsResponse { #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] pub struct KeyRange { + /// Physical start key bytes. #[prost(bytes = "vec", tag = "1")] pub start_key: ::prost::alloc::vec::Vec, - /// end_key is +inf when it is empty. + /// Physical end key bytes. end_key is +inf when it is empty. #[prost(bytes = "vec", tag = "2")] pub end_key: ::prost::alloc::vec::Vec, } @@ -404,7 +408,7 @@ pub struct BatchScanRegionsRequest { pub header: ::core::option::Option, #[prost(bool, tag = "2")] pub need_buckets: bool, - /// the given ranges must be in order. + /// Physical key ranges. The given ranges must be in order. #[prost(message, repeated, tag = "3")] pub ranges: ::prost::alloc::vec::Vec, /// limit the total number of regions to scan. @@ -591,6 +595,10 @@ pub struct RegionHeartbeatRequest { /// It's counted on size of user key & value (excluding metadata fields), before compression, and latest versions only. #[prost(uint64, tag = "19")] pub approximate_columnar_kv_size: u64, + /// Approximate size of row-based key-value pairs stored in the IA tier for billing. + /// It is a subset of approximate_kv_size and follows the same size accounting rules. + #[prost(uint64, tag = "22")] + pub approximate_ia_kv_size: u64, /// BucketMeta is the bucket version and keys of this region if TiKV enabled the bucket feature #[prost(message, optional, tag = "20")] pub bucket_meta: ::core::option::Option, @@ -629,6 +637,7 @@ pub struct Merge { pub struct SplitRegion { #[prost(enumeration = "CheckPolicy", tag = "1")] pub policy: i32, + /// Physical split key bytes. #[prost(bytes = "vec", repeated, tag = "2")] pub keys: ::prost::alloc::vec::Vec<::prost::alloc::vec::Vec>, } @@ -928,11 +937,15 @@ pub struct DfsStatScope { #[prost(bool, tag = "1")] pub is_global: bool, /// The keyspace of this statistic. Ignore when is_global is true. + /// NOTE: This field is only meaningful for V1/V2 compatibility. V3 should use keyspace_identities. #[prost(uint32, tag = "2")] pub keyspace_id: u32, /// The component that provides the statistic. #[prost(string, tag = "3")] pub component: ::prost::alloc::string::String, + /// V3 multi-keyspace statistic scope. Ignore when is_global is true. + #[prost(message, repeated, tag = "4")] + pub keyspace_identities: ::prost::alloc::vec::Vec, } #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] @@ -1198,8 +1211,21 @@ pub struct UpdateServiceGcSafePointResponse { pub struct GetGcSafePointV2Request { #[prost(message, optional, tag = "1")] pub header: ::core::option::Option, - #[prost(uint32, tag = "2")] - pub keyspace_id: u32, + #[prost(oneof = "get_gc_safe_point_v2_request::Keyspace", tags = "2, 3")] + pub keyspace: ::core::option::Option, +} +/// Nested message and enum types in `GetGCSafePointV2Request`. +pub mod get_gc_safe_point_v2_request { + #[allow(clippy::derive_partial_eq_without_eq)] + #[derive(Clone, PartialEq, ::prost::Oneof)] + pub enum Keyspace { + /// V1/V2 compatibility keyspace id. V3 should use keyspace_identity. + #[prost(uint32, tag = "2")] + KeyspaceId(u32), + /// V3 keyspace identity. + #[prost(message, tag = "3")] + KeyspaceIdentity(super::super::apipb::KeyspaceIdentity), + } } #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] @@ -1221,12 +1247,25 @@ pub struct WatchGcSafePointV2Request { #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] pub struct SafePointEvent { - #[prost(uint32, tag = "1")] - pub keyspace_id: u32, #[prost(uint64, tag = "2")] pub safe_point: u64, #[prost(enumeration = "EventType", tag = "3")] pub r#type: i32, + #[prost(oneof = "safe_point_event::Keyspace", tags = "1, 4")] + pub keyspace: ::core::option::Option, +} +/// Nested message and enum types in `SafePointEvent`. +pub mod safe_point_event { + #[allow(clippy::derive_partial_eq_without_eq)] + #[derive(Clone, PartialEq, ::prost::Oneof)] + pub enum Keyspace { + /// V1/V2 compatibility keyspace id. V3 should use keyspace_identity. + #[prost(uint32, tag = "1")] + KeyspaceId(u32), + /// V3 keyspace identity served by this event. + #[prost(message, tag = "4")] + KeyspaceIdentity(super::super::apipb::KeyspaceIdentity), + } } #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] @@ -1243,10 +1282,23 @@ pub struct WatchGcSafePointV2Response { pub struct UpdateGcSafePointV2Request { #[prost(message, optional, tag = "1")] pub header: ::core::option::Option, - #[prost(uint32, tag = "2")] - pub keyspace_id: u32, #[prost(uint64, tag = "3")] pub safe_point: u64, + #[prost(oneof = "update_gc_safe_point_v2_request::Keyspace", tags = "2, 4")] + pub keyspace: ::core::option::Option, +} +/// Nested message and enum types in `UpdateGCSafePointV2Request`. +pub mod update_gc_safe_point_v2_request { + #[allow(clippy::derive_partial_eq_without_eq)] + #[derive(Clone, PartialEq, ::prost::Oneof)] + pub enum Keyspace { + /// V1/V2 compatibility keyspace id. V3 should use keyspace_identity. + #[prost(uint32, tag = "2")] + KeyspaceId(u32), + /// V3 keyspace identity. + #[prost(message, tag = "4")] + KeyspaceIdentity(super::super::apipb::KeyspaceIdentity), + } } #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] @@ -1261,8 +1313,6 @@ pub struct UpdateGcSafePointV2Response { pub struct UpdateServiceSafePointV2Request { #[prost(message, optional, tag = "1")] pub header: ::core::option::Option, - #[prost(uint32, tag = "2")] - pub keyspace_id: u32, #[prost(bytes = "vec", tag = "3")] pub service_id: ::prost::alloc::vec::Vec, #[prost(uint64, tag = "4")] @@ -1274,6 +1324,21 @@ pub struct UpdateServiceSafePointV2Request { /// cluster garbage collection. #[prost(int64, tag = "5")] pub ttl: i64, + #[prost(oneof = "update_service_safe_point_v2_request::Keyspace", tags = "2, 6")] + pub keyspace: ::core::option::Option, +} +/// Nested message and enum types in `UpdateServiceSafePointV2Request`. +pub mod update_service_safe_point_v2_request { + #[allow(clippy::derive_partial_eq_without_eq)] + #[derive(Clone, PartialEq, ::prost::Oneof)] + pub enum Keyspace { + /// V1/V2 compatibility keyspace id. V3 should use keyspace_identity. + #[prost(uint32, tag = "2")] + KeyspaceId(u32), + /// V3 keyspace identity. + #[prost(message, tag = "6")] + KeyspaceIdentity(super::super::apipb::KeyspaceIdentity), + } } #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] @@ -1296,10 +1361,23 @@ pub struct GetAllGcSafePointV2Request { #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] pub struct GcSafePointV2 { - #[prost(uint32, tag = "1")] - pub keyspace_id: u32, #[prost(uint64, tag = "2")] pub gc_safe_point: u64, + #[prost(oneof = "gc_safe_point_v2::Keyspace", tags = "1, 3")] + pub keyspace: ::core::option::Option, +} +/// Nested message and enum types in `GCSafePointV2`. +pub mod gc_safe_point_v2 { + #[allow(clippy::derive_partial_eq_without_eq)] + #[derive(Clone, PartialEq, ::prost::Oneof)] + pub enum Keyspace { + /// V1/V2 compatibility keyspace id. V3 should use keyspace_identity. + #[prost(uint32, tag = "1")] + KeyspaceId(u32), + /// V3 keyspace identity. + #[prost(message, tag = "3")] + KeyspaceIdentity(super::super::apipb::KeyspaceIdentity), + } } #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] @@ -1311,15 +1389,26 @@ pub struct GetAllGcSafePointV2Response { #[prost(int64, tag = "3")] pub revision: i64, } -/// A wrapper over keyspace_id. -/// When a field is not specified in proto3, its value will be regarded as 0; however, keyspace_id = 0 is regarded as a valid keyspace (which -/// is the "DEFAULT" keyspace). To distinguish unspecified keyspace (NullKeyspace, 0xffffffff) and the default keyspace in some APIs as well -/// as preventing potential misuse, we wrap the keyspace_id into a message type which is nullable. +/// A wrapper over keyspace scope. +/// keyspace_id is kept for V1/V2 compatibility. V3 should use keyspace_identity and reject +/// missing/invalid namespace or keyspace IDs in tenant-scoped requests. #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] pub struct KeyspaceScope { - #[prost(uint32, tag = "1")] - pub keyspace_id: u32, + #[prost(oneof = "keyspace_scope::Keyspace", tags = "1, 2")] + pub keyspace: ::core::option::Option, +} +/// Nested message and enum types in `KeyspaceScope`. +pub mod keyspace_scope { + #[allow(clippy::derive_partial_eq_without_eq)] + #[derive(Clone, PartialEq, ::prost::Oneof)] + pub enum Keyspace { + #[prost(uint32, tag = "1")] + KeyspaceId(u32), + /// V3 keyspace identity. + #[prost(message, tag = "2")] + KeyspaceIdentity(super::super::apipb::KeyspaceIdentity), + } } #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] @@ -1468,6 +1557,14 @@ pub struct GetGcStateRequest { pub keyspace_scope: ::core::option::Option, #[prost(bool, tag = "3")] pub exclude_gc_barriers: bool, + /// Include all stored global GC barriers in the response. + /// + /// This uses an include flag, unlike exclude_gc_barriers, because proto3 bool + /// fields default to false. GetGCState historically omitted global GC + /// barriers, so false preserves both the existing response and the + /// no-extra-read path. + #[prost(bool, tag = "4")] + pub include_global_gc_barriers: bool, } #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] @@ -1483,6 +1580,37 @@ pub struct GcState { #[prost(message, repeated, tag = "5")] pub gc_barriers: ::prost::alloc::vec::Vec, } +/// GCStateChange describes a change to a keyspace's effective GC state. +/// GCState values sent by WatchGCStates omit gc_barriers because barriers are +/// internal inputs used by PD to calculate effective safe points; the stream +/// reports only changes to the resulting effective state. +#[allow(clippy::derive_partial_eq_without_eq)] +#[derive(Clone, PartialEq, ::prost::Message)] +pub struct GcStateChange { + #[prost(oneof = "gc_state_change::Change", tags = "1, 2")] + pub change: ::core::option::Option, +} +/// Nested message and enum types in `GCStateChange`. +pub mod gc_state_change { + #[allow(clippy::derive_partial_eq_without_eq)] + #[derive(Clone, PartialEq, ::prost::Oneof)] + pub enum Change { + /// Insert or replace the complete GC state of this keyspace. + #[prost(message, tag = "1")] + Upsert(super::GcState), + /// Remove this keyspace from the client's materialized GC-state view. + /// This does not necessarily mean the keyspace metadata was physically deleted. + #[prost(message, tag = "2")] + Removed(super::KeyspaceScope), + } +} +/// GlobalGCBarriersInfo carries presence independently from the barrier list. +#[allow(clippy::derive_partial_eq_without_eq)] +#[derive(Clone, PartialEq, ::prost::Message)] +pub struct GlobalGcBarriersInfo { + #[prost(message, repeated, tag = "1")] + pub barriers: ::prost::alloc::vec::Vec, +} #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] pub struct GetGcStateResponse { @@ -1490,6 +1618,11 @@ pub struct GetGcStateResponse { pub header: ::core::option::Option, #[prost(message, optional, tag = "2")] pub gc_state: ::core::option::Option, + /// Absent when globals were not requested or the server does not support + /// this extension. Present-empty when the request was fulfilled but no + /// global GC barriers are stored. + #[prost(message, optional, tag = "3")] + pub global_gc_barriers: ::core::option::Option, } #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] @@ -1513,6 +1646,30 @@ pub struct GetAllKeyspacesGcStatesResponse { } #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] +pub struct WatchGcStatesRequest { + #[prost(message, optional, tag = "1")] + pub header: ::core::option::Option, + /// If false, when the stream is established, the server first sends the current + /// GC states of all keyspaces. + #[prost(bool, tag = "2")] + pub skip_loading_initial: bool, +} +#[allow(clippy::derive_partial_eq_without_eq)] +#[derive(Clone, PartialEq, ::prost::Message)] +pub struct WatchGcStatesResponse { + #[prost(message, optional, tag = "1")] + pub header: ::core::option::Option, + /// Clients apply changes in order within this response and across successive + /// responses on the stream. A client must not observe an older state for a + /// keyspace after a newer update. After disconnection, the client reconnects + /// and reloads the initial state. The stream omits GC barrier details and does + /// not emit changes for barrier-only updates. If a barrier update changes an + /// effective GC state, the resulting state change is emitted. + #[prost(message, repeated, tag = "2")] + pub changes: ::prost::alloc::vec::Vec, +} +#[allow(clippy::derive_partial_eq_without_eq)] +#[derive(Clone, PartialEq, ::prost::Message)] pub struct RegionStat { /// Bytes read/written during this period. #[prost(uint64, tag = "1")] @@ -1620,6 +1777,7 @@ pub struct SyncMaxTsResponse { pub struct SplitRegionsRequest { #[prost(message, optional, tag = "1")] pub header: ::core::option::Option, + /// Physical split key bytes. #[prost(bytes = "vec", repeated, tag = "2")] pub split_keys: ::prost::alloc::vec::Vec<::prost::alloc::vec::Vec>, #[prost(uint64, tag = "3")] @@ -1640,6 +1798,7 @@ pub struct SplitRegionsResponse { pub struct SplitAndScatterRegionsRequest { #[prost(message, optional, tag = "1")] pub header: ::core::option::Option, + /// Physical split key bytes. #[prost(bytes = "vec", repeated, tag = "2")] pub split_keys: ::prost::alloc::vec::Vec<::prost::alloc::vec::Vec>, #[prost(string, tag = "3")] @@ -3118,6 +3277,28 @@ pub mod pd_client { .insert(GrpcMethod::new("pdpb.PD", "GetAllKeyspacesGCStates")); self.inner.unary(req, path, codec).await } + pub async fn watch_gc_states( + &mut self, + request: impl tonic::IntoRequest, + ) -> std::result::Result< + tonic::Response>, + tonic::Status, + > { + self.inner + .ready() + .await + .map_err(|e| { + tonic::Status::new( + tonic::Code::Unknown, + format!("Service was not ready: {}", e.into()), + ) + })?; + let codec = tonic::codec::ProstCodec::default(); + let path = http::uri::PathAndQuery::from_static("/pdpb.PD/WatchGCStates"); + let mut req = request.into_request(); + req.extensions_mut().insert(GrpcMethod::new("pdpb.PD", "WatchGCStates")); + self.inner.server_streaming(req, path, codec).await + } pub async fn sync_regions( &mut self, request: impl tonic::IntoStreamingRequest, diff --git a/src/generated/resource_manager.rs b/src/generated/resource_manager.rs index e093c6f0e..172e9e342 100644 --- a/src/generated/resource_manager.rs +++ b/src/generated/resource_manager.rs @@ -1,11 +1,25 @@ // This file is @generated by prost-build. -/// KeyspaceIDValue is a wrapper for the value of keyspace ID. -/// Because the 0 value is a valid keyspace ID, we need to use a wrapper to distinguish it from the null keyspace ID. +/// KeyspaceIDValue carries the versioned identity of a keyspace. The message +/// name is retained for compatibility with existing ResourceManager APIs. #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] pub struct KeyspaceIdValue { - #[prost(uint32, tag = "1")] - pub value: u32, + #[prost(oneof = "keyspace_id_value::Keyspace", tags = "1, 2")] + pub keyspace: ::core::option::Option, +} +/// Nested message and enum types in `KeyspaceIDValue`. +pub mod keyspace_id_value { + #[allow(clippy::derive_partial_eq_without_eq)] + #[derive(Clone, PartialEq, ::prost::Oneof)] + pub enum Keyspace { + /// V1/V2 compatibility keyspace ID. The wrapper distinguishes a valid zero + /// value from an unset keyspace, which represents the null keyspace ID. + #[prost(uint32, tag = "1")] + Value(u32), + /// V3 keyspace identity. + #[prost(message, tag = "2")] + KeyspaceIdentity(super::super::apipb::KeyspaceIdentity), + } } #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] @@ -14,10 +28,9 @@ pub struct ListResourceGroupsRequest { pub with_ru_stats: bool, /// There're two cases for this field: /// - /// * If the keyspace ID is not set, it means this may be a message from an older version. + /// * If the keyspace is not set, it means this may be a message from an older version. /// To maintain compatibility, we will treat it as a null keyspace ID, which is uint32.Max. - /// * If the keyspace ID is set to a valid value, the listed resource groups will be filtered - /// by the given keyspace ID. + /// * If the keyspace is set, the listed resource groups will be filtered by the given keyspace. #[prost(message, optional, tag = "2")] pub keyspace_id: ::core::option::Option, } @@ -38,10 +51,9 @@ pub struct GetResourceGroupRequest { pub with_ru_stats: bool, /// There're two cases for this field: /// - /// * If the keyspace ID is not set, it means this may be a message from an older version. + /// * If the keyspace is not set, it means this may be a message from an older version. /// To maintain compatibility, we will treat it as a null keyspace ID, which is uint32.Max. - /// * If the keyspace ID is set to a valid value, it will try to get the resource group within - /// the given keyspace ID. + /// * If the keyspace is set, it will try to get the resource group within the given keyspace. #[prost(message, optional, tag = "3")] pub keyspace_id: ::core::option::Option, } @@ -60,10 +72,9 @@ pub struct DeleteResourceGroupRequest { pub resource_group_name: ::prost::alloc::string::String, /// There're two cases for this field: /// - /// * If the keyspace ID is not set, it means this may be a message from an older version. + /// * If the keyspace is not set, it means this may be a message from an older version. /// To maintain compatibility, we will treat it as a null keyspace ID, which is uint32.Max. - /// * If the keyspace ID is set to a valid value, it will try to delete the resource group within - /// the given keyspace ID. + /// * If the keyspace is set, it will try to delete the resource group within the given keyspace. #[prost(message, optional, tag = "2")] pub keyspace_id: ::core::option::Option, } @@ -114,10 +125,10 @@ pub struct TokenBucketRequest { pub is_tiflash: bool, /// There're two cases for this field: /// - /// * If the keyspace ID is not set, it means this may be a message from an older version. + /// * If the keyspace is not set, it means this may be a message from an older version. /// To maintain compatibility, we will treat it as a null keyspace ID, which is uint32.Max. - /// * If the keyspace ID is set to a valid value, it will try to request the token bucket from - /// the resource group within the given keyspace ID. + /// * If the keyspace is set, it will try to request the token bucket from the resource group + /// within the given keyspace. #[prost(message, optional, tag = "7")] pub keyspace_id: ::core::option::Option, #[prost(oneof = "token_bucket_request::Request", tags = "2, 3")] @@ -169,10 +180,9 @@ pub struct TokenBucketResponse { pub granted_resource_tokens: ::prost::alloc::vec::Vec, /// There're two cases for this field: /// - /// * If the keyspace ID is not set, it means this may be a message from an older version, + /// * If the keyspace is not set, it means this may be a message from an older version, /// which can be safely ignored to keep compatibility. - /// * If the keyspace ID is set to a valid value, it means this response is from the resource - /// group within this keyspace ID. + /// * If the keyspace is set, it means this response is from the resource group within this keyspace. #[prost(message, optional, tag = "4")] pub keyspace_id: ::core::option::Option, } @@ -271,12 +281,12 @@ pub struct ResourceGroup { /// RU consumption statistics. #[prost(message, optional, tag = "8")] pub ru_stats: ::core::option::Option, - /// The keyspace ID that the resource group belongs to. + /// The keyspace that the resource group belongs to. /// There're two cases for this field: /// - /// * If the keyspace ID is not set, it means this may be a message from an older version. + /// * If the keyspace is not set, it means this may be a message from an older version. /// To maintain compatibility, we will treat it as a null keyspace ID, which is uint32.Max. - /// * If the keyspace ID is set to a valid value, it will directly be used. + /// * If the keyspace is set, it will directly be used. #[prost(message, optional, tag = "9")] pub keyspace_id: ::core::option::Option, } diff --git a/src/generated/resource_usage_agent.rs b/src/generated/resource_usage_agent.rs index 26f04ac66..7a85ede7d 100644 --- a/src/generated/resource_usage_agent.rs +++ b/src/generated/resource_usage_agent.rs @@ -50,6 +50,10 @@ pub struct GroupTagRecordItem { pub logical_read_bytes: u64, #[prost(uint64, tag = "8")] pub logical_write_bytes: u64, + /// RocksDB block reads used for downstream read_iops relative attribution. + /// This is not a device-level IOPS measurement. + #[prost(uint64, tag = "9")] + pub rocksdb_block_read_count: u64, } /// RegionRecord is a set of resource usage data grouped by region. #[allow(clippy::derive_partial_eq_without_eq)] diff --git a/src/generated/schedulingpb.rs b/src/generated/schedulingpb.rs index e4efe1441..02df732cc 100644 --- a/src/generated/schedulingpb.rs +++ b/src/generated/schedulingpb.rs @@ -185,6 +185,7 @@ pub struct ScatterRegionsResponse { pub struct SplitRegionsRequest { #[prost(message, optional, tag = "1")] pub header: ::core::option::Option, + /// Physical split key bytes. #[prost(bytes = "vec", repeated, tag = "2")] pub split_keys: ::prost::alloc::vec::Vec<::prost::alloc::vec::Vec>, #[prost(uint64, tag = "3")] diff --git a/src/generated/tsopb.rs b/src/generated/tsopb.rs index fd84ab116..3c57fec9c 100644 --- a/src/generated/tsopb.rs +++ b/src/generated/tsopb.rs @@ -8,9 +8,6 @@ pub struct RequestHeader { /// sender_id is the ID of the sender server. #[prost(uint64, tag = "2")] pub sender_id: u64, - /// keyspace_id is the unique id of the tenant/keyspace. - #[prost(uint32, tag = "3")] - pub keyspace_id: u32, /// keyspace_group_id is the unique id of the keyspace group to which the tenant/keyspace belongs. #[prost(uint32, tag = "4")] pub keyspace_group_id: u32, @@ -20,6 +17,22 @@ pub struct RequestHeader { /// If it is not matched, the server will return an error. #[prost(string, tag = "5")] pub callee_id: ::prost::alloc::string::String, + #[prost(oneof = "request_header::Keyspace", tags = "3, 6")] + pub keyspace: ::core::option::Option, +} +/// Nested message and enum types in `RequestHeader`. +pub mod request_header { + #[allow(clippy::derive_partial_eq_without_eq)] + #[derive(Clone, PartialEq, ::prost::Oneof)] + pub enum Keyspace { + /// keyspace_id is the unique id of the tenant/keyspace in V1/V2. + /// V3 should use keyspace_identity and must not read this legacy field as the full identity. + #[prost(uint32, tag = "3")] + KeyspaceId(u32), + /// V3 keyspace identity of the request. + #[prost(message, tag = "6")] + KeyspaceIdentity(super::super::apipb::KeyspaceIdentity), + } } #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] @@ -29,12 +42,25 @@ pub struct ResponseHeader { pub cluster_id: u64, #[prost(message, optional, tag = "2")] pub error: ::core::option::Option, - /// keyspace_id is the unique id of the tenant/keyspace as the response receiver. - #[prost(uint32, tag = "3")] - pub keyspace_id: u32, /// keyspace_group_id is the unique id of the keyspace group to which the tenant/keyspace belongs. #[prost(uint32, tag = "4")] pub keyspace_group_id: u32, + #[prost(oneof = "response_header::Keyspace", tags = "3, 5")] + pub keyspace: ::core::option::Option, +} +/// Nested message and enum types in `ResponseHeader`. +pub mod response_header { + #[allow(clippy::derive_partial_eq_without_eq)] + #[derive(Clone, PartialEq, ::prost::Oneof)] + pub enum Keyspace { + /// keyspace_id is the unique id of the tenant/keyspace as the response receiver in V1/V2. + /// V3 should use keyspace_identity and must not read this legacy field as the full identity. + #[prost(uint32, tag = "3")] + KeyspaceId(u32), + /// V3 keyspace identity served by this response. + #[prost(message, tag = "5")] + KeyspaceIdentity(super::super::apipb::KeyspaceIdentity), + } } #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] @@ -109,10 +135,23 @@ pub struct KeyspaceGroup { pub struct FindGroupByKeyspaceIdRequest { #[prost(message, optional, tag = "1")] pub header: ::core::option::Option, - #[prost(uint32, tag = "2")] - pub keyspace_id: u32, #[prost(uint64, tag = "3")] pub mod_revision: u64, + #[prost(oneof = "find_group_by_keyspace_id_request::Keyspace", tags = "2, 4")] + pub keyspace: ::core::option::Option, +} +/// Nested message and enum types in `FindGroupByKeyspaceIDRequest`. +pub mod find_group_by_keyspace_id_request { + #[allow(clippy::derive_partial_eq_without_eq)] + #[derive(Clone, PartialEq, ::prost::Oneof)] + pub enum Keyspace { + /// V1/V2 compatibility keyspace id. V3 should use keyspace_identity. + #[prost(uint32, tag = "2")] + KeyspaceId(u32), + /// V3 keyspace identity. + #[prost(message, tag = "4")] + KeyspaceIdentity(super::super::apipb::KeyspaceIdentity), + } } #[allow(clippy::derive_partial_eq_without_eq)] #[derive(Clone, PartialEq, ::prost::Message)] @@ -291,7 +330,7 @@ pub mod tso_client { req.extensions_mut().insert(GrpcMethod::new("tsopb.TSO", "Tso")); self.inner.streaming(req, path, codec).await } - /// Find the keyspace group that the keyspace belongs to by keyspace id. + /// Find the keyspace group that the keyspace belongs to. pub async fn find_group_by_keyspace_id( &mut self, request: impl tonic::IntoRequest, diff --git a/src/lib.rs b/src/lib.rs index 89b25f458..cdefef5f3 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -129,7 +129,7 @@ pub use common::ProtoRegionError; #[doc(inline)] pub use common::Result; #[doc(inline)] -pub use config::Config; +pub use config::{Config, RequestOrigin, TxnProtocolVersion, TxnRequestPolicy}; #[doc(inline)] pub use crate::backoff::Backoff; diff --git a/src/mock.rs b/src/mock.rs index 0a1c1b774..cd2292d31 100644 --- a/src/mock.rs +++ b/src/mock.rs @@ -93,6 +93,8 @@ pub struct MockPdClient { /// Optional observer for region cache invalidations. #[new(default)] invalidate_region_hook: Option>, + #[new(default)] + reload_store_hook: Option Result + Send + Sync + 'static>>, } #[async_trait] @@ -118,6 +120,14 @@ impl KvConnect for MockKvConnect { } impl MockPdClient { + pub fn with_reload_store_hook(mut self, hook: F) -> Self + where + F: Fn(u64) -> Result + Send + Sync + 'static, + { + self.reload_store_hook = Some(Arc::new(hook)); + self + } + pub fn default() -> MockPdClient { MockPdClient::new(MockKvClient::default()) } @@ -218,6 +228,13 @@ impl MockPdClient { impl PdClient for MockPdClient { type KvClient = MockKvClient; + async fn reload_store(&self, id: u64) -> Result { + match &self.reload_store_hook { + Some(hook) => hook(id), + None => panic!("unexpected store metadata reload"), + } + } + async fn map_region_to_store(self: Arc, region: RegionWithLeader) -> Result { if let Some(hook) = &self.map_region_to_store_hook { return hook(region); diff --git a/src/pd/client.rs b/src/pd/client.rs index b89658751..996c541e0 100644 --- a/src/pd/client.rs +++ b/src/pd/client.rs @@ -54,6 +54,11 @@ use crate::Timestamp; pub trait PdClient: Send + Sync + 'static { type KvClient: KvClient + Send + Sync + 'static; + /// Reload store metadata from PD, coalescing concurrent refreshes. + async fn reload_store(&self, _store_id: StoreId) -> Result { + Err(crate::Error::Unimplemented) + } + /// In transactional API, `region` is decoded (keys in raw format). async fn map_region_to_store(self: Arc, region: RegionWithLeader) -> Result; @@ -223,11 +228,17 @@ pub struct PdRpcClient PdClient for PdRpcClient { type KvClient = KvC::KvClient; + async fn reload_store(&self, store_id: StoreId) -> Result { + self.region_cache.reload_store(store_id).await + } + async fn map_region_to_store(self: Arc, region: RegionWithLeader) -> Result { let store_id = region.get_store_id()?; let store = self.region_cache.get_store_by_id(store_id).await?; let kv_client = self.kv_client(&store.address).await?; - Ok(RegionStore::new(region, Arc::new(kv_client))) + let mut region_store = RegionStore::new(region, Arc::new(kv_client)); + region_store.meta = store; + Ok(region_store) } async fn region_for_key(&self, key: &Key) -> Result { diff --git a/src/raw/client.rs b/src/raw/client.rs index 9dab092db..67ada14d1 100644 --- a/src/raw/client.rs +++ b/src/raw/client.rs @@ -114,9 +114,7 @@ impl Client { let keyspace = match config.keyspace { Some(name) => { let keyspace = rpc.load_keyspace(&name).await?; - Keyspace::Enable { - keyspace_id: keyspace.id, - } + Keyspace::from_metadata(keyspace)? } None => Keyspace::Disable, }; diff --git a/src/raw/requests.rs b/src/raw/requests.rs index 1f018184c..cd0576af5 100644 --- a/src/raw/requests.rs +++ b/src/raw/requests.rs @@ -521,6 +521,10 @@ pub struct RawCoprocessorRequest { #[async_trait] impl Request for RawCoprocessorRequest { + fn context_mut(&mut self) -> &mut kvrpcpb::Context { + self.inner.context_mut() + } + async fn dispatch( &self, client: &TikvClient, diff --git a/src/region_cache.rs b/src/region_cache.rs index 2a4b0fbbd..33a992f4d 100644 --- a/src/region_cache.rs +++ b/src/region_cache.rs @@ -4,10 +4,13 @@ use std::collections::BTreeMap; use std::collections::HashMap; use std::collections::HashSet; use std::sync::Arc; +use std::time::Duration; -use log::debug; -use tokio::sync::Notify; +use tokio::time::Instant; + +use log::{debug, warn}; use tokio::sync::RwLock; +use tokio::sync::{watch, Mutex, Notify}; use crate::common::Error; use crate::pd::Cluster; @@ -52,9 +55,16 @@ impl RegionCacheMap { } } +// A refresh is shared independently of any individual caller's cancellation. +struct StoreReload { + started_at: Instant, + result: watch::Receiver>>, +} + pub struct RegionCache> { region_cache: RwLock, - store_cache: RwLock>, + store_cache: Arc>>, + store_reloads: Mutex>, inner_client: Arc, } @@ -62,7 +72,8 @@ impl RegionCache { pub fn new(inner_client: Arc) -> RegionCache { RegionCache { region_cache: RwLock::new(RegionCacheMap::new()), - store_cache: RwLock::new(HashMap::new()), + store_cache: Arc::new(RwLock::new(HashMap::new())), + store_reloads: Mutex::new(HashMap::new()), inner_client, } } @@ -124,7 +135,12 @@ impl RegionCache { } pub async fn get_store_by_id(&self, id: StoreId) -> Result { - let store = self.store_cache.read().await.get(&id).cloned(); + let store = self + .store_cache + .read() + .await + .get(&id) + .map(|(_, store)| store.clone()); match store { Some(store) => Ok(store), None => self.read_through_store_by_id(id).await, @@ -161,9 +177,89 @@ impl RegionCache { } async fn read_through_store_by_id(&self, id: StoreId) -> Result { + let started_at = Instant::now(); let store = self.inner_client.clone().get_store(id).await?; - self.store_cache.write().await.insert(id, store.clone()); - Ok(store) + let mut cache = self.store_cache.write().await; + Ok(publish_store(&mut cache, started_at, store)) + } + + /// Reload from PD at most once per second per store. Running refreshes are + /// joined even after cooldown; canceling a waiter does not cancel the fetch. + pub async fn reload_store(&self, id: StoreId) -> Result + where + C: Send + Sync + 'static, + { + let mut reloads = self.store_reloads.lock().await; + let reuse = reloads.get(&id).is_some_and(|reload| { + // A stopped task may leave an empty result behind. Only an open + // channel represents an in-flight fetch; stopped tasks still enter + // cooldown but must not prevent subsequent reloads indefinitely. + let running = reload.result.borrow().is_none() && reload.result.has_changed().is_ok(); + if running { + crate::stats::txn_protocol_store_reload("joined"); + true + } else if reload.started_at.elapsed() < Duration::from_secs(1) { + crate::stats::txn_protocol_store_reload("suppressed"); + true + } else { + false + } + }); + if !reuse { + let started_at = Instant::now(); + let (sender, receiver) = watch::channel(None); + reloads.insert( + id, + StoreReload { + started_at, + result: receiver, + }, + ); + let client = self.inner_client.clone(); + let cache = self.store_cache.clone(); + tokio::spawn(async move { + crate::stats::txn_protocol_store_reload("started"); + let fetched = match tokio::time::timeout( + Duration::from_secs(5), + client.get_store(id), + ) + .await + { + Ok(result) => result.map_err(|error| error.to_string()), + Err(error) => Err(error.to_string()), + }; + let result = match fetched { + Ok(store) => { + let mut cache = cache.write().await; + let published = publish_store(&mut cache, started_at, store); + crate::stats::txn_protocol_store_reload("success"); + Ok(published) + } + Err(error) => { + crate::stats::txn_protocol_store_reload("failure"); + debug!("store metadata refresh failed for {}: {}", id, error); + Err(error) + } + }; + sender.send_replace(Some(result)); + }); + } + let mut receiver = reloads.get(&id).unwrap().result.clone(); + drop(reloads); + loop { + let result = receiver.borrow().clone(); + if let Some(result) = result { + // Other metadata fetches may have published a newer snapshot while + // this refresh was running, including after a failed refresh. + if let Some((_, store)) = self.store_cache.read().await.get(&id) { + return Ok(store.clone()); + } + return result.map_err(Error::StringError); + } + receiver.changed().await.map_err(|_| { + Error::StringError("store metadata refresh task stopped".to_owned()) + })?; + } } pub async fn add_region(&self, region: RegionWithLeader) { @@ -238,7 +334,7 @@ impl RegionCache { pub async fn invalidate_store_cache(&self, store_id: StoreId) -> Option { let mut cache = self.store_cache.write().await; - let removed = cache.remove(&store_id); + let removed = cache.remove(&store_id).map(|(_, store)| store); if removed.is_some() { debug!("invalidated store cache entry, store: {:?}", store_id); } @@ -246,7 +342,8 @@ impl RegionCache { } pub async fn read_through_all_stores(&self) -> Result> { - let stores = self + let started_at = Instant::now(); + let mut stores = self .inner_client .clone() .get_all_stores() @@ -254,16 +351,44 @@ impl RegionCache { .into_iter() .filter(is_valid_tikv_store) .collect::>(); - for store in &stores { - self.store_cache - .write() - .await - .insert(store.id, store.clone()); + let mut cache = self.store_cache.write().await; + for store in &mut stores { + *store = publish_store(&mut cache, started_at, store.clone()); } Ok(stores) } } +/// Publish metadata consistently for cache misses, conditional reloads, and +/// full-store fetches. Invalid protocol ranges retain the last valid range (or +/// unknown); an absent range is a legitimate downgrade and replaces it. +fn publish_store( + cache: &mut HashMap, + fetched_at: Instant, + mut store: Store, +) -> Store { + let previous = cache.get(&store.id); + if let Some((published_at, cached)) = previous { + if fetched_at < *published_at { + return cached.clone(); + } + } + if let Some(range) = store.txn_protocol_version_range.as_ref() { + if range.min > range.max { + warn!( + "ignoring invalid transaction protocol range [{}, {}] for store {}", + range.min, range.max, store.id, + ); + store.txn_protocol_version_range = + previous.and_then(|(_, cached)| cached.txn_protocol_version_range.clone()); + } + } + // Advance the fetch timestamp even when retaining the previous range, so + // an older in-flight lookup cannot replace it after this publication. + cache.insert(store.id, (fetched_at, store.clone())); + store +} + const ENGINE_LABEL_KEY: &str = "engine"; const ENGINE_LABEL_TIFLASH: &str = "tiflash"; const ENGINE_LABEL_TIFLASH_COMPUTE: &str = "tiflash_compute"; @@ -307,6 +432,10 @@ mod test { struct MockRetryClient { pub regions: Mutex>, pub get_region_count: AtomicU64, + pub stores: Mutex>, + pub get_store_count: AtomicU64, + pub fail_get_store: std::sync::atomic::AtomicBool, + pub get_store_gate: Option>, } #[async_trait] @@ -343,13 +472,25 @@ mod test { async fn get_store( self: Arc, - _id: crate::region::StoreId, + id: crate::region::StoreId, ) -> Result { - todo!() + self.get_store_count.fetch_add(1, SeqCst); + if let Some(gate) = &self.get_store_gate { + gate.acquire().await.unwrap().forget(); + } + if self.fail_get_store.load(SeqCst) { + return Err(Error::StringError("PD unavailable".into())); + } + self.stores + .lock() + .await + .get(&id) + .cloned() + .ok_or_else(|| Error::StringError("store not found".into())) } async fn get_all_stores(self: Arc) -> Result> { - todo!() + Ok(self.stores.lock().await.values().cloned().collect()) } async fn get_timestamp(self: Arc) -> Result { @@ -593,4 +734,227 @@ mod test { store.labels[1].value = "other".to_string(); assert!(is_valid_tikv_store(&store)); } + + fn store_metadata(id: u64, range: Option<(u32, u32)>) -> metapb::Store { + metapb::Store { + id, + txn_protocol_version_range: range + .map(|(min, max)| metapb::TxnProtocolVersionRange { min, max }), + ..Default::default() + } + } + + #[tokio::test] + async fn protocol_metadata_is_validated_on_every_fetch_path() { + let pd = Arc::new(MockRetryClient::default()); + pd.stores + .lock() + .await + .insert(7, store_metadata(7, Some((0, 1)))); + let cache = RegionCache::new(pd.clone()); + let initial = cache.get_store_by_id(7).await.unwrap(); + pd.stores + .lock() + .await + .insert(7, store_metadata(7, Some((2, 1)))); + assert_eq!( + cache + .reload_store(7) + .await + .unwrap() + .txn_protocol_version_range, + initial.txn_protocol_version_range + ); + assert_eq!( + cache.read_through_all_stores().await.unwrap()[0].txn_protocol_version_range, + initial.txn_protocol_version_range + ); + // Absence legitimately downgrades a previously advertised range. + pd.stores.lock().await.insert(7, store_metadata(7, None)); + assert!(cache.read_through_all_stores().await.unwrap()[0] + .txn_protocol_version_range + .is_none()); + assert!(cache + .get_store_by_id(7) + .await + .unwrap() + .txn_protocol_version_range + .is_none()); + // An invalid initial fetch must publish unknown rather than invalid bounds. + pd.stores + .lock() + .await + .insert(8, store_metadata(8, Some((3, 1)))); + assert!(cache + .get_store_by_id(8) + .await + .unwrap() + .txn_protocol_version_range + .is_none()); + } + + #[test] + fn protocol_publication_keeps_last_valid_range_and_orders_fetches() { + let mut cache = HashMap::new(); + let now = super::Instant::now(); + let valid = store_metadata(7, Some((0, 1))); + super::publish_store(&mut cache, now, valid.clone()); + let newer = now + std::time::Duration::from_secs(2); + let retained = super::publish_store(&mut cache, newer, store_metadata(7, Some((3, 1)))); + assert_eq!( + retained.txn_protocol_version_range, + valid.txn_protocol_version_range + ); + // Even an invalid newer fetch advances publication ordering. + let late = super::publish_store( + &mut cache, + now + std::time::Duration::from_secs(1), + store_metadata(7, None), + ); + assert_eq!( + late.txn_protocol_version_range, + valid.txn_protocol_version_range + ); + let legacy = super::publish_store( + &mut cache, + newer + std::time::Duration::from_secs(1), + store_metadata(7, None), + ); + assert!(legacy.txn_protocol_version_range.is_none()); + } + + #[tokio::test] + async fn protocol_reload_is_shared_survives_cancellation_and_respects_cooldown() { + let gate = Arc::new(tokio::sync::Semaphore::new(0)); + let pd = Arc::new(MockRetryClient { + get_store_gate: Some(gate.clone()), + ..Default::default() + }); + pd.stores + .lock() + .await + .insert(7, store_metadata(7, Some((0, 1)))); + let cache = Arc::new(RegionCache::new(pd.clone())); + let owner_cache = cache.clone(); + let owner = tokio::spawn(async move { owner_cache.reload_store(7).await }); + tokio::time::timeout(std::time::Duration::from_secs(2), async { + while pd.get_store_count.load(SeqCst) == 0 { + tokio::task::yield_now().await; + } + }) + .await + .unwrap(); + let mut waiter = Box::pin(cache.reload_store(7)); + assert!(futures::poll!(waiter.as_mut()).is_pending()); + owner.abort(); + assert!(owner.await.unwrap_err().is_cancelled()); + // A long-running fetch remains shared even after cooldown expires. + cache + .store_reloads + .lock() + .await + .get_mut(&7) + .unwrap() + .started_at = super::Instant::now() - std::time::Duration::from_secs(2); + let mut late_waiter = Box::pin(cache.reload_store(7)); + assert!(futures::poll!(late_waiter.as_mut()).is_pending()); + assert_eq!(pd.get_store_count.load(SeqCst), 1); + gate.add_permits(1); + let first = waiter.await.unwrap(); + assert_eq!(late_waiter.await.unwrap(), first); + assert_eq!(pd.get_store_count.load(SeqCst), 1); + // Completed results are reused inside cooldown, then refreshed afterward. + cache + .store_reloads + .lock() + .await + .get_mut(&7) + .unwrap() + .started_at = super::Instant::now(); + pd.stores + .lock() + .await + .insert(7, store_metadata(7, Some((0, 0)))); + assert_eq!(cache.reload_store(7).await.unwrap(), first); + assert_eq!(pd.get_store_count.load(SeqCst), 1); + cache + .store_reloads + .lock() + .await + .get_mut(&7) + .unwrap() + .started_at = super::Instant::now() - std::time::Duration::from_secs(2); + gate.add_permits(1); + assert_eq!( + cache.reload_store(7).await.unwrap(), + store_metadata(7, Some((0, 0))) + ); + assert_eq!(pd.get_store_count.load(SeqCst), 2); + } + + #[tokio::test] + async fn protocol_failed_reload_preserves_cache_and_enters_cooldown() { + let pd = Arc::new(MockRetryClient::default()); + let original = store_metadata(7, Some((0, 1))); + pd.stores.lock().await.insert(7, original.clone()); + let cache = RegionCache::new(pd.clone()); + assert_eq!(cache.get_store_by_id(7).await.unwrap(), original); + pd.fail_get_store.store(true, SeqCst); + assert_eq!(cache.reload_store(7).await.unwrap(), original); + assert_eq!(cache.reload_store(7).await.unwrap(), original); + assert_eq!(pd.get_store_count.load(SeqCst), 2); // Initial fetch + one failed reload. + } + + #[tokio::test] + async fn protocol_stopped_reload_can_restart_after_cooldown() { + let pd = Arc::new(MockRetryClient::default()); + pd.stores.lock().await.insert(7, store_metadata(7, None)); + let cache = RegionCache::new(pd.clone()); + let (sender, receiver) = tokio::sync::watch::channel(None); + drop(sender); + cache.store_reloads.lock().await.insert( + 7, + super::StoreReload { + started_at: super::Instant::now(), + result: receiver, + }, + ); + assert!(cache.reload_store(7).await.is_err()); + assert_eq!(pd.get_store_count.load(SeqCst), 0); + cache + .store_reloads + .lock() + .await + .get_mut(&7) + .unwrap() + .started_at = super::Instant::now() - std::time::Duration::from_secs(2); + assert_eq!( + cache.reload_store(7).await.unwrap(), + store_metadata(7, None) + ); + assert_eq!(pd.get_store_count.load(SeqCst), 1); + } + + #[tokio::test] + async fn protocol_reload_timeout_does_not_poison_later_attempts() { + let gate = Arc::new(tokio::sync::Semaphore::new(0)); + let pd = Arc::new(MockRetryClient { + get_store_gate: Some(gate.clone()), + ..Default::default() + }); + pd.stores.lock().await.insert(7, store_metadata(7, None)); + let cache = RegionCache::new(pd.clone()); + let failed = tokio::time::timeout(std::time::Duration::from_secs(6), cache.reload_store(7)) + .await + .unwrap(); + assert!(failed.is_err()); + assert_eq!(pd.get_store_count.load(SeqCst), 1); + // Cooldown starts with the attempt, so the timed-out fetch can be retried. + gate.add_permits(1); + assert_eq!( + cache.reload_store(7).await.unwrap(), + store_metadata(7, None) + ); + assert_eq!(pd.get_store_count.load(SeqCst), 2); + } } diff --git a/src/request/keyspace.rs b/src/request/keyspace.rs index ce568d1e4..2c8d61192 100644 --- a/src/request/keyspace.rs +++ b/src/request/keyspace.rs @@ -34,6 +34,20 @@ pub enum KeyMode { } impl Keyspace { + pub(crate) fn from_metadata( + meta: crate::proto::keyspacepb::KeyspaceMeta, + ) -> crate::Result { + use crate::proto::keyspacepb::keyspace_meta::Keyspace as MetaKeyspace; + + match meta.keyspace { + Some(MetaKeyspace::Id(keyspace_id)) => Ok(Self::Enable { keyspace_id }), + None => Ok(Self::Enable { keyspace_id: 0 }), + Some(MetaKeyspace::KeyspaceIdentity(_)) => Err(crate::Error::StringError( + "API V3 keyspace identities are not supported by this client".to_owned(), + )), + } + } + pub fn api_version(&self) -> kvrpcpb::ApiVersion { match self { Keyspace::Disable => kvrpcpb::ApiVersion::V1, @@ -292,6 +306,27 @@ fn pretruncate_bytes(vec: &mut Vec) { mod tests { use super::*; + #[test] + fn keyspace_metadata_preserves_legacy_ids_and_rejects_v3() { + use crate::proto::keyspacepb::KeyspaceMeta; + use prost::Message; + + // Field 1 remains the V1/V2 keyspace ID on the wire. + let legacy = KeyspaceMeta::decode(&[0x08, 42][..]).unwrap(); + assert_eq!( + Keyspace::from_metadata(legacy).unwrap(), + Keyspace::Enable { keyspace_id: 42 } + ); + let default_id = KeyspaceMeta::decode(&[][..]).unwrap(); + assert_eq!( + Keyspace::from_metadata(default_id).unwrap(), + Keyspace::Enable { keyspace_id: 0 } + ); + // Field 8 is a V3 identity; an empty identity must not become a V2 ID of zero. + let v3 = KeyspaceMeta::decode(&[0x42, 0x00][..]).unwrap(); + assert!(Keyspace::from_metadata(v3).is_err()); + } + #[test] fn test_keyspace_prefix() { let key_mode = KeyMode::Raw; diff --git a/src/request/mod.rs b/src/request/mod.rs index 4cac6c506..f90cb741d 100644 --- a/src/request/mod.rs +++ b/src/request/mod.rs @@ -22,6 +22,7 @@ pub use self::plan::ProcessResponse; pub use self::plan::ResolveLock; pub use self::plan::ResponseWithShard; pub use self::plan::RetryableMultiRegion; +pub use self::plan::TxnProtocolCompatibility; pub use self::plan_builder::PlanBuilder; pub use self::plan_builder::SingleKey; pub use self::shard::Batchable; @@ -34,7 +35,7 @@ use crate::backoff::DEFAULT_REGION_BACKOFF; use crate::backoff::OPTIMISTIC_BACKOFF; use crate::backoff::PESSIMISTIC_BACKOFF; use crate::store::Request; -use crate::store::{HasKeyErrors, Store}; +use crate::store::{HasKeyErrors, HasRegionError, Store}; use crate::transaction::HasLocks; mod keyspace; @@ -46,7 +47,7 @@ mod shard; #[async_trait] pub trait KvRequest: Request + Sized + Clone + Sync + Send + 'static { /// The expected response to the request. - type Response: HasKeyErrors + HasLocks + Clone + Send + 'static; + type Response: HasKeyErrors + HasRegionError + HasLocks + Clone + Send + 'static; } /// For requests or plans which are handled at TiKV store (other than region) level. @@ -116,8 +117,10 @@ mod test { #[tokio::test] async fn test_region_retry() { - #[derive(Debug, Clone)] - struct MockRpcResponse; + #[derive(Debug, Clone, Default)] + struct MockRpcResponse { + region_error: crate::proto::errorpb::Error, + } impl HasKeyErrors for MockRpcResponse { fn key_errors(&mut self) -> Option> { @@ -126,8 +129,12 @@ mod test { } impl HasRegionError for MockRpcResponse { + fn region_error_ref(&self) -> Option<&crate::proto::errorpb::Error> { + Some(&self.region_error) + } + fn region_error(&mut self) -> Option { - Some(crate::proto::errorpb::Error::default()) + Some(self.region_error.clone()) } } @@ -135,13 +142,17 @@ mod test { #[derive(Clone)] struct MockKvRequest { + context: kvrpcpb::Context, test_invoking_count: Arc, } #[async_trait] impl Request for MockKvRequest { + fn context_mut(&mut self) -> &mut kvrpcpb::Context { + &mut self.context + } async fn dispatch(&self, _: &TikvClient, _: Duration) -> Result> { - Ok(Box::new(MockRpcResponse {})) + Ok(Box::new(MockRpcResponse::default())) } fn label(&self) -> &'static str { @@ -193,11 +204,12 @@ mod test { let invoking_count = Arc::new(AtomicUsize::new(0)); let request = MockKvRequest { + context: kvrpcpb::Context::default(), test_invoking_count: invoking_count.clone(), }; let pd_client = Arc::new(MockPdClient::new(MockKvClient::with_dispatch_hook( - |_: &dyn Any| Ok(Box::new(MockRpcResponse) as Box), + |_: &dyn Any| Ok(Box::new(MockRpcResponse::default()) as Box), ))); let plan = crate::request::PlanBuilder::new(pd_client.clone(), Keyspace::Disable, request) @@ -222,6 +234,10 @@ mod test { } impl HasRegionError for MockOkResponse { + fn region_error_ref(&self) -> Option<&crate::proto::errorpb::Error> { + None + } + fn region_error(&mut self) -> Option { None } @@ -335,11 +351,15 @@ mod test { #[derive(Clone)] struct MockKvRequest { + context: kvrpcpb::Context, shard_invoking_count: Arc, } #[async_trait] impl Request for MockKvRequest { + fn context_mut(&mut self) -> &mut kvrpcpb::Context { + &mut self.context + } async fn dispatch(&self, _: &TikvClient, _: Duration) -> Result> { Ok(Box::new(MockOkResponse)) } @@ -408,6 +428,7 @@ mod test { }); let request = MockKvRequest { + context: kvrpcpb::Context::default(), shard_invoking_count: shard_invoking_count.clone(), }; @@ -530,6 +551,10 @@ mod test { } impl HasRegionError for MockOkResponse { + fn region_error_ref(&self) -> Option<&crate::proto::errorpb::Error> { + None + } + fn region_error(&mut self) -> Option { None } @@ -617,10 +642,15 @@ mod test { } #[derive(Clone)] - struct MockKvRequest; + struct MockKvRequest { + context: kvrpcpb::Context, + } #[async_trait] impl Request for MockKvRequest { + fn context_mut(&mut self) -> &mut kvrpcpb::Context { + &mut self.context + } async fn dispatch(&self, _: &TikvClient, _: Duration) -> Result> { Ok(Box::new(MockOkResponse)) } @@ -683,10 +713,15 @@ mod test { invalidate_store_count: AtomicUsize::new(0), }); - let plan = - crate::request::PlanBuilder::new(pd_client.clone(), Keyspace::Disable, MockKvRequest) - .retry_multi_region(Backoff::no_jitter_backoff(1, 1, 1)) - .plan(); + let plan = crate::request::PlanBuilder::new( + pd_client.clone(), + Keyspace::Disable, + MockKvRequest { + context: kvrpcpb::Context::default(), + }, + ) + .retry_multi_region(Backoff::no_jitter_backoff(1, 1, 1)) + .plan(); let response = plan.execute().await; assert!(response.is_ok()); assert_eq!(pd_client.invalidate_region_count.load(Ordering::SeqCst), 1); diff --git a/src/request/plan.rs b/src/request/plan.rs index 3c460143f..b18a3be80 100644 --- a/src/request/plan.rs +++ b/src/request/plan.rs @@ -1,6 +1,7 @@ // Copyright 2021 TiKV Project Authors. Licensed under Apache-2.0. use std::marker::PhantomData; +use std::sync::atomic::{AtomicBool, Ordering}; use std::sync::Arc; use async_recursion::async_recursion; @@ -16,6 +17,7 @@ use tokio::time::sleep; use tonic::Code; use crate::backoff::Backoff; +use crate::common::ErrorPriority; use crate::pd::PdClient; use crate::proto::errorpb; use crate::proto::errorpb::EpochNotMatch; @@ -92,6 +94,164 @@ impl StoreRequest for Dispatch { const MULTI_REGION_CONCURRENCY: usize = 16; const MULTI_STORES_CONCURRENCY: usize = 16; +/// Declares origin and selects a compatible version per destination. +/// Wraps [`Dispatch`] inside lock and routing retries. Missing store ranges mean +/// `[0, 0]`; a potentially stale maximum permits one metadata reload. +/// +/// A valid upper-bound rejection permits one immediate resend to the same store +/// using its returned range, without updating the cache. Routing retries and +/// re-sharding preserve spent allowances; advancing to a new scan page renews it. +/// Undetermined outcomes take precedence; other compatibility rejections are terminal. +pub struct TxnProtocolCompatibility { + pub(super) inner: Dispatch, + pub(super) pd_client: Arc, + pub(super) policy: crate::TxnRequestPolicy, + pub(super) store: Option, + pub(super) resend_used: Arc, +} + +impl Clone for TxnProtocolCompatibility { + fn clone(&self) -> Self { + Self { + inner: self.inner.clone(), + pd_client: self.pd_client.clone(), + policy: self.policy, + store: self.store.clone(), + // Execution clones (e.g. cleanup pagination) share their shard's allowance. + resend_used: self.resend_used.clone(), + } + } +} + +impl TxnProtocolCompatibility { + pub(super) fn apply_region_store(&mut self, store: &RegionStore) -> Result<()> { + self.inner.request.set_leader(&store.region_with_leader)?; + self.inner.kv_client = Some(store.client.clone()); + self.store = Some(store.meta.clone()); + Ok(()) + } + + fn required_version(&self) -> u32 { + let request = self.inner.request.as_any(); + let shared = request + .downcast_ref::() + .is_some_and(|r| { + r.mutations + .iter() + .any(|m| m.op == kvrpcpb::Op::SharedLock as i32) + }) + || request + .downcast_ref::() + .is_some_and(|r| { + r.mutations + .iter() + .any(|m| m.op == kvrpcpb::Op::SharedPessimisticLock as i32) + }); + if shared { + kvrpcpb::TxnProtocolVersion::TxnVerSupportSharedLock as u32 + } else { + kvrpcpb::TxnProtocolVersion::TxnVerLegacy as u32 + } + } + + fn select_version(&self, range: &metapb::TxnProtocolVersionRange) -> Option { + let selected = (self.policy.protocol_version as u32).min(range.max); + (range.min <= range.max && selected >= range.min && selected >= self.required_version()) + .then_some(selected) + } +} + +#[async_trait] +impl Plan for TxnProtocolCompatibility { + type Result = Req::Response; + + async fn execute(&self) -> Result { + let mut store = self.store.clone().ok_or_else(|| { + Error::StringError("transaction protocol plan has no destination store".to_owned()) + })?; + let mut range = store.txn_protocol_version_range.clone().unwrap_or_default(); + let mut selected = self.select_version(&range); + if selected.is_none() + && range.min <= range.max + && self.required_version() > range.max + && self.required_version() <= self.policy.protocol_version as u32 + { + // Refresh once when only a stale maximum could block this payload. + // A failed refresh keeps the cached range and local rejection semantics. + match self.pd_client.reload_store(store.id).await { + Ok(fresh) => { + store = fresh; + range = store.txn_protocol_version_range.clone().unwrap_or_default(); + selected = self.select_version(&range); + } + Err(error) => debug!("store protocol refresh failed: {:?}", error), + } + } + let mut version = selected.ok_or_else(|| { + crate::stats::txn_protocol_rejection("local"); + Error::IncompatibleRequest(Box::new(errorpb::IncompatibleRequest { + reason: errorpb::IncompatibleRequestReason::Unknown as i32, + message: format!( + "store {} range [{}, {}], configured version {}, payload requires {}", + store.id, + range.min, + range.max, + self.policy.protocol_version as u32, + self.required_version(), + ), + provided_txn_protocol_version: (self.policy.protocol_version as u32).min(range.max), + min_compatible_txn_protocol_version: range.min, + max_compatible_txn_protocol_version: range.max, + })) + })?; + let mut dispatch = self.inner.clone(); + loop { + let context = dispatch.request.context_mut(); + context.request_origin = self.policy.origin as i32; + context.txn_protocol_version = version; + let mut response = dispatch.execute().await?; + let Some(error) = response.region_error_ref() else { + return Ok(response); + }; + let undetermined = error.undetermined_result.is_some(); + if !undetermined && error.incompatible_request.is_none() { + return Ok(response); + } + let error = response + .region_error() + .expect("region error was just inspected"); + // An unknown apply outcome stops this send before compatibility, + // lock-resolution, or region retry handling. Preserve the complete + // envelope so the transaction layer can classify commit uncertainty. + if undetermined { + return Err(Error::RegionError(Box::new(error))); + } + let rejection = error + .incompatible_request + .expect("incompatible request was just inspected"); + crate::stats::txn_protocol_rejection("server"); + let returned_range = metapb::TxnProtocolVersionRange { + min: rejection.min_compatible_txn_protocol_version, + max: rejection.max_compatible_txn_protocol_version, + }; + let replacement = self.select_version(&returned_range); + if rejection.reason + != errorpb::IncompatibleRequestReason::TxnProtocolVersionOutOfRange as i32 + || returned_range.min > returned_range.max + || rejection.provided_txn_protocol_version != version + || version <= returned_range.max + || replacement.is_none() + || self.resend_used.swap(true, Ordering::Relaxed) + { + return Err(Error::IncompatibleRequest(Box::new(rejection))); + } + // Only this resend uses the returned range; never publish it to the cache. + crate::stats::txn_protocol_resend(); + version = replacement.unwrap(); + } + } +} + pub(crate) fn is_grpc_error(e: &Error) -> bool { matches!(e, Error::GrpcAPI(_) | Error::Grpc(_)) } @@ -217,19 +377,17 @@ where fn is_fallback_not_leader(&self) -> bool { self.used_fallback && self.key_errors.is_none() - && self - .region_error - .as_ref() - .is_some_and(|error| error.not_leader.is_some()) + && self.region_error.as_ref().is_some_and(|error| { + error.not_leader.is_some() && error.undetermined_result.is_none() + }) } fn is_fallback_server_busy(&self) -> bool { self.used_fallback && self.key_errors.is_none() - && self - .region_error - .as_ref() - .is_some_and(|error| error.server_is_busy.is_some()) + && self.region_error.as_ref().is_some_and(|error| { + error.server_is_busy.is_some() && error.undetermined_result.is_none() + }) } fn accepted_fallback_leader(&self) -> Option { @@ -422,27 +580,25 @@ where }) .collect()) } else { - // A terminal undetermined outcome must never be masked by another shard's - // determinate error. `collect::>()` would return the first error - // by shard index, so if a lower-index shard failed with (say) a gRPC error - // while a higher-index shard reported `UndeterminedResult`, the caller would - // be told the request definitely failed — and might replay a transaction - // that may already be durable. So an undetermined error - // from ANY shard wins over a determinate one. + // Unknown apply outcomes and compatibility rejections must survive + // ordinary failures from other shards. Equal priorities retain the + // first error by shard index. let mut oks = Vec::with_capacity(results.len()); - let mut first_err: Option = None; - let mut undetermined: Option = None; + let mut selected_error: Option = None; for r in results { match r { Ok(v) => oks.push(v), - Err(e) if undetermined.is_none() && is_undetermined_region_error(&e) => { - undetermined = Some(e) + Err(e) + if selected_error + .as_ref() + .is_none_or(|selected| e.priority() < selected.priority()) => + { + selected_error = Some(e) } - Err(e) if first_err.is_none() => first_err = Some(e), Err(_) => {} } } - if let Some(e) = undetermined.or(first_err) { + if let Some(e) = selected_error { return Err(e); } Ok(oks.into_iter().flatten().collect()) @@ -811,7 +967,11 @@ where return Ok(vec![Ok(response)]); }; - if let Some(server_is_busy) = error.server_is_busy.as_ref() { + if let Some(server_is_busy) = error + .server_is_busy + .as_ref() + .filter(|_| error.undetermined_result.is_none()) + { if !used_fallback && server_is_busy.estimated_wait_ms == 0 { let mut candidate_state = candidate_state; if let Some(peer) = region_store.region_with_leader.leader.as_ref() { @@ -925,6 +1085,17 @@ pub(crate) async fn handle_region_error( let ver_id = region_store.region_with_leader.ver_id(); let store_id = region_store.region_with_leader.get_store_id(); debug!("handling region error: {:?}, region: {:?}", e, ver_id); + if e.undetermined_result.is_some() { + // The apply outcome is UNKNOWN (a raft timeout, errorpb.UndeterminedResult). + // Default: retry — matching client-go's ACTION layers (ordinary prewrites and + // secondary commits back off and re-send; re-applying an idempotent request + // resolves the uncertainty). Routing is not suspect, so nothing is + // invalidated. On backoff exhaustion the error escapes UNCHANGED, and commit + // paths classify it via `is_undetermined_region_error`. Plans for which a + // replay is unsafe never reach this arm — see `terminal_on_undetermined`. + // This outcome takes precedence over other fields in the envelope. + return Ok(false); + } if let Some(not_leader) = e.not_leader { if let Some(leader) = not_leader.leader { match pd_client @@ -956,15 +1127,6 @@ pub(crate) async fn handle_region_error( } else if e.stale_command.is_some() || e.region_not_found.is_some() { pd_client.invalidate_region_cache(ver_id).await; Ok(false) - } else if e.undetermined_result.is_some() { - // The apply outcome is UNKNOWN (a raft timeout, errorpb.UndeterminedResult). - // Default: retry — matching client-go's ACTION layers (ordinary prewrites and - // secondary commits back off and re-send; re-applying an idempotent request - // resolves the uncertainty). Routing is not suspect, so nothing is - // invalidated. On backoff exhaustion the error escapes UNCHANGED, and commit - // paths classify it via `is_undetermined_region_error`. Plans for which a - // replay is unsafe never reach this arm — see `terminal_on_undetermined`. - Ok(false) } else if e.server_is_busy.is_some() { // ServerIsBusy is a definitive rejection, so retrying is safe. The // cached leader remains valid; the caller applies the normal Region @@ -1249,6 +1411,7 @@ pub struct ResolveLock { pub pd_client: Arc, pub backoff: Backoff, pub keyspace: Keyspace, + pub request_policy: crate::TxnRequestPolicy, } impl Clone for ResolveLock { @@ -1259,6 +1422,7 @@ impl Clone for ResolveLock { pd_client: self.pd_client.clone(), backoff: self.backoff.clone(), keyspace: self.keyspace, + request_policy: self.request_policy, } } } @@ -1289,6 +1453,7 @@ where self.timestamp.clone(), pd_client.clone(), self.keyspace, + self.request_policy, ) .await?; if live_locks.is_empty() { @@ -1323,6 +1488,10 @@ impl Clone for CleanupLocksResult { } impl HasRegionError for CleanupLocksResult { + fn region_error_ref(&self) -> Option<&errorpb::Error> { + self.region_error.as_ref() + } + fn region_error(&mut self) -> Option { self.region_error.take() } @@ -1356,6 +1525,7 @@ pub struct CleanupLocks { pub store: Option, pub pd_client: Arc, pub keyspace: Keyspace, + pub request_policy: crate::TxnRequestPolicy, pub backoff: Backoff, } @@ -1368,6 +1538,7 @@ impl Clone for CleanupLocks { store: None, pd_client: self.pd_client.clone(), keyspace: self.keyspace, + request_policy: self.request_policy, backoff: self.backoff.clone(), } } @@ -1383,7 +1554,8 @@ where async fn execute(&self) -> Result { let mut result = CleanupLocksResult::default(); let mut inner = self.inner.clone(); - let mut lock_resolver = crate::transaction::LockResolver::new(self.ctx.clone()); + let mut lock_resolver = + crate::transaction::LockResolver::new(self.ctx.clone(), self.request_policy); let region = &self.store.as_ref().unwrap().region_with_leader; let mut has_more_batch = true; @@ -1504,12 +1676,35 @@ where async fn execute(&self) -> Result { let mut result = self.inner.execute().await?; + let mut key_errors = result.key_errors(); + let mut region_errors = result + .region_errors() + .map(|errors| errors.into_iter().map(Error::from).collect::>()); + // Preserved shard failures arrive through key_errors(), while bare + // responses can carry region errors. Inspect both sources before applying + // the ordinary wrapping rules, so neither can mask a protocol outcome. + let selected = region_errors + .iter() + .flatten() + .chain(key_errors.iter().flatten()) + .enumerate() + .filter(|(_, error)| error.priority() != ErrorPriority::Ordinary) + .min_by_key(|(_, error)| error.priority()) + .map(|(index, _)| index); + if let Some(index) = selected { + let region_count = region_errors.as_ref().map_or(0, Vec::len); + return Err(if index < region_count { + region_errors.as_mut().unwrap().remove(index) + } else { + key_errors.as_mut().unwrap().remove(index - region_count) + }); + } // Each branch names what it found. Previously both produced one // `ExtractedErrors`, so a caller had to pop an element and inspect its type to // learn which kind it was holding — and whether a caller saw that variant at // all depended on whether a collapsing merge sat between the retry layer and // this plan (see `MultipleKeyErrors`' docs). - if let Some(errors) = result.key_errors() { + if let Some(errors) = key_errors { // `HasKeyErrors for Result` yields *any* per-shard `Err`, not only // errors the response carried — that is how a plan keeping its // `Vec>` (see `retry_multi_region_preserve_results`) carries a hard @@ -1530,13 +1725,8 @@ where .find(|e| !is_response_error(e)) .expect("a non-response error exists: the all() test above failed")) } - } else if let Some(errors) = result.region_errors() { - Err(Error::MultipleRegionErrors( - errors - .into_iter() - .map(|e| Error::RegionError(Box::new(e))) - .collect(), - )) + } else if let Some(errors) = region_errors { + Err(Error::MultipleRegionErrors(errors)) } else { Ok(result) } @@ -1597,6 +1787,10 @@ impl HasLocks for ResponseWithShard { } impl HasRegionError for ResponseWithShard { + fn region_error_ref(&self) -> Option<&errorpb::Error> { + self.0.region_error_ref() + } + fn region_error(&mut self) -> Option { self.0.region_error() } @@ -1738,6 +1932,7 @@ mod test { backoff: Backoff::no_backoff(), pd_client: Arc::new(MockPdClient::default()), keyspace: Keyspace::Disable, + request_policy: crate::TxnRequestPolicy::default(), }, pd_client: Arc::new(MockPdClient::default()), backoff: Backoff::no_backoff(), @@ -2266,4 +2461,786 @@ mod test { other => panic!("want MultipleRegionErrors, got {other:?}"), } } + + fn protocol_store(client: crate::mock::MockKvClient, range: Option<(u32, u32)>) -> RegionStore { + let mut store = RegionStore::new(MockPdClient::region1(), Arc::new(client)); + store.meta = metapb::Store { + id: store.region_with_leader.get_store_id().unwrap(), + txn_protocol_version_range: range + .map(|(min, max)| metapb::TxnProtocolVersionRange { min, max }), + ..Default::default() + }; + store + } + + fn admission_rejection() -> errorpb::IncompatibleRequest { + errorpb::IncompatibleRequest { + reason: errorpb::IncompatibleRequestReason::TxnProtocolVersionOutOfRange as i32, + message: "admission rejection".into(), + provided_txn_protocol_version: 1, + min_compatible_txn_protocol_version: 0, + max_compatible_txn_protocol_version: 0, + } + } + + #[rstest::rstest] + #[case(None, 1, Some(0))] + #[case(Some((0, 0)), 1, Some(0))] + #[case(Some((0, 2)), 1, Some(1))] + #[case(Some((1, 1)), 1, Some(1))] + #[case(Some((0, 1)), 0, Some(0))] + #[case(Some((1, 1)), 0, None)] + #[case(Some((2, 3)), 1, None)] + #[case(Some((2, 1)), 1, None)] + #[tokio::test] + async fn protocol_selection_declares_origin_and_version_before_dispatch( + #[case] range: Option<(u32, u32)>, + #[case] configured: i32, + #[case] expected: Option, + ) { + let calls = Arc::new(AtomicUsize::new(0)); + let observed = calls.clone(); + let client = crate::mock::MockKvClient::with_dispatch_hook(move |request| { + observed.fetch_add(1, Ordering::SeqCst); + let context = request + .downcast_ref::() + .unwrap() + .context + .as_ref() + .unwrap(); + assert_eq!(Some(context.txn_protocol_version), expected); + assert_eq!(context.request_origin, crate::RequestOrigin::TiFlash as i32); + Ok(Box::new(kvrpcpb::GetResponse { + value: b"value".to_vec(), + ..Default::default() + })) + }); + let policy = crate::TxnRequestPolicy { + origin: crate::RequestOrigin::TiFlash, + protocol_version: crate::TxnProtocolVersion::try_from(configured).unwrap(), + }; + let plan = crate::request::PlanBuilder::new( + Arc::new(MockPdClient::default()), + Keyspace::Disable, + kvrpcpb::GetRequest::default(), + ) + .txn_protocol_compatibility(policy) + .single_region_with_store(protocol_store(client, range)) + .await + .unwrap() + .plan(); + let result = plan.execute().await; + if expected.is_some() { + assert_eq!(result.unwrap().value, b"value"); + assert_eq!(calls.load(Ordering::SeqCst), 1); + } else { + let Err(Error::IncompatibleRequest(error)) = result else { + panic!("expected a local rejection") + }; + assert_eq!( + error.reason, + errorpb::IncompatibleRequestReason::Unknown as i32 + ); + assert_eq!(calls.load(Ordering::SeqCst), 0); + } + } + + #[rstest::rstest] + #[case("upper", true)] + #[case("unknown_reason", false)] + #[case("invalid_range", false)] + #[case("wrong_echo", false)] + #[case("lower_bound", false)] + #[case("in_range", false)] + #[tokio::test] + async fn protocol_rejection_resends_only_valid_upper_overflow( + #[case] scenario: &str, + #[case] resend: bool, + ) { + let mut rejection = admission_rejection(); + match scenario { + "unknown_reason" => rejection.reason = 42, + "invalid_range" => rejection.min_compatible_txn_protocol_version = 2, + "wrong_echo" => rejection.provided_txn_protocol_version = 0, + "lower_bound" => { + rejection.min_compatible_txn_protocol_version = 2; + rejection.max_compatible_txn_protocol_version = 2; + } + "in_range" => rejection.max_compatible_txn_protocol_version = 1, + "upper" => {} + _ => unreachable!(), + } + let original = rejection.clone(); + let versions = Arc::new(std::sync::Mutex::new(Vec::new())); + let observed = versions.clone(); + let client = crate::mock::MockKvClient::with_dispatch_hook(move |request| { + let version = request + .downcast_ref::() + .unwrap() + .context + .as_ref() + .unwrap() + .txn_protocol_version; + let mut sent = observed.lock().unwrap(); + sent.push(version); + Ok(Box::new(kvrpcpb::GetResponse { + region_error: (sent.len() == 1).then(|| errorpb::Error { + incompatible_request: Some(rejection.clone()), + not_leader: Some(Default::default()), + server_is_busy: Some(Default::default()), + ..Default::default() + }), + ..Default::default() + })) + }); + let routed = client.clone(); + let pd = Arc::new( + MockPdClient::new(client) + .with_map_region_to_store_hook(move |region| { + let mut store = protocol_store(routed.clone(), Some((0, 1))); + store.region_with_leader = region; + Ok(store) + }) + .with_invalidate_region_hook(|_| { + panic!("compatibility rejection invalidated routing") + }), + ); + let plan = crate::request::PlanBuilder::new( + pd, + Keyspace::Disable, + kvrpcpb::GetRequest { + key: vec![1], + ..Default::default() + }, + ) + .txn_protocol_compatibility(crate::TxnRequestPolicy::default()) + .retry_multi_region(Backoff::no_jitter_backoff(1, 1, 3)) + .plan(); + let result = plan.execute().await; + if resend { + assert!(result.is_ok()); + assert_eq!(*versions.lock().unwrap(), vec![1, 0]); + } else { + let Err(Error::IncompatibleRequest(error)) = result else { + panic!("expected terminal server rejection") + }; + assert_eq!(*error, original); + assert_eq!(*versions.lock().unwrap(), vec![1]); + } + } + + #[tokio::test] + async fn protocol_undetermined_envelope_stops_before_other_errors_or_retries() { + let original = errorpb::Error { + message: "unknown apply outcome".into(), + undetermined_result: Some(Default::default()), + incompatible_request: Some(admission_rejection()), + not_leader: Some(Default::default()), + server_is_busy: Some(Default::default()), + ..Default::default() + }; + let envelope = original.clone(); + let calls = Arc::new(AtomicUsize::new(0)); + let observed = calls.clone(); + let client = crate::mock::MockKvClient::with_dispatch_hook(move |_| { + observed.fetch_add(1, Ordering::SeqCst); + Ok(Box::new(kvrpcpb::GetResponse { + region_error: Some(envelope.clone()), + error: Some(kvrpcpb::KeyError { + abort: "must not mask unknown outcome".into(), + ..Default::default() + }), + ..Default::default() + })) + }); + let routed = client.clone(); + let pd = Arc::new( + MockPdClient::new(client) + .with_map_region_to_store_hook(move |region| { + let mut store = protocol_store(routed.clone(), Some((0, 1))); + store.region_with_leader = region; + Ok(store) + }) + .with_invalidate_region_hook(|_| panic!("unknown outcome invalidated routing")), + ); + let plan = crate::request::PlanBuilder::new( + pd, + Keyspace::Disable, + kvrpcpb::GetRequest { + key: vec![1], + ..Default::default() + }, + ) + .txn_protocol_compatibility(crate::TxnRequestPolicy::default()) + .resolve_lock( + Timestamp::default(), + Backoff::no_jitter_backoff(1, 1, 3), + Keyspace::Disable, + ) + .retry_multi_region(Backoff::no_jitter_backoff(1, 1, 3)) + .plan(); + let Err(Error::RegionError(error)) = plan.execute().await else { + panic!("expected original unknown outcome") + }; + assert_eq!(*error, original); + assert_eq!(calls.load(Ordering::SeqCst), 1); + } + + #[tokio::test] + async fn protocol_allowances_are_independent_for_siblings_and_fresh_sends() { + let versions = Arc::new(std::sync::Mutex::new(Vec::new())); + let observed = versions.clone(); + let client = crate::mock::MockKvClient::with_dispatch_hook(move |request| { + let request = request.downcast_ref::().unwrap(); + let version = request.context.as_ref().unwrap().txn_protocol_version; + observed + .lock() + .unwrap() + .push((request.keys.clone(), version)); + Ok(Box::new(kvrpcpb::BatchGetResponse { + region_error: (version == 1).then(|| errorpb::Error { + incompatible_request: Some(admission_rejection()), + ..Default::default() + }), + ..Default::default() + })) + }); + let routed = client.clone(); + let pd = Arc::new( + MockPdClient::new(client).with_map_region_to_store_hook(move |region| { + let mut store = protocol_store(routed.clone(), Some((0, 1))); + store.region_with_leader = region; + Ok(store) + }), + ); + let plan = crate::request::PlanBuilder::new( + pd, + Keyspace::Disable, + kvrpcpb::BatchGetRequest { + keys: vec![vec![1], vec![11]], + ..Default::default() + }, + ) + .txn_protocol_compatibility(crate::TxnRequestPolicy::default()) + .retry_multi_region(Backoff::no_backoff()) + .plan(); + for _ in 0..2 { + assert!(plan.execute().await.unwrap().iter().all(Result::is_ok)); + } + let mut sent = versions.lock().unwrap().clone(); + sent.sort(); + assert_eq!( + sent, + vec![ + (vec![vec![1]], 0), + (vec![vec![1]], 0), + (vec![vec![1]], 1), + (vec![vec![1]], 1), + (vec![vec![11]], 0), + (vec![vec![11]], 0), + (vec![vec![11]], 1), + (vec![vec![11]], 1), + ] + ); + } + + #[rstest::rstest] + #[case(1, false)] + #[case(2, false)] + #[case(2, true)] + #[tokio::test] + async fn protocol_payload_requirement_controls_reload_and_dispatch( + #[case] configured: i32, + #[case] reload_succeeds: bool, + ) { + let reloads = Arc::new(AtomicUsize::new(0)); + let observed = reloads.clone(); + let pd = Arc::new(MockPdClient::default().with_reload_store_hook(move |id| { + observed.fetch_add(1, Ordering::SeqCst); + if !reload_succeeds { + return Err(Error::Unimplemented); + } + Ok(metapb::Store { + id, + txn_protocol_version_range: Some(metapb::TxnProtocolVersionRange { + min: 0, + max: 2, + }), + ..Default::default() + }) + })); + let calls = Arc::new(AtomicUsize::new(0)); + let sent = calls.clone(); + let client = crate::mock::MockKvClient::with_dispatch_hook(move |request| { + sent.fetch_add(1, Ordering::SeqCst); + assert_eq!( + request + .downcast_ref::() + .unwrap() + .context + .as_ref() + .unwrap() + .txn_protocol_version, + 2 + ); + Ok(Box::new(kvrpcpb::PrewriteResponse::default())) + }); + // Direct policies let the test exercise future shared-lock payload negotiation. + let policy = crate::TxnRequestPolicy { + protocol_version: crate::TxnProtocolVersion::try_from(configured).unwrap(), + ..Default::default() + }; + let plan = crate::request::PlanBuilder::new( + pd, + Keyspace::Disable, + kvrpcpb::PrewriteRequest { + mutations: vec![kvrpcpb::Mutation { + op: kvrpcpb::Op::SharedLock as i32, + ..Default::default() + }], + ..Default::default() + }, + ) + .txn_protocol_compatibility(policy) + .single_region_with_store(protocol_store(client, Some((0, 1)))) + .await + .unwrap() + .plan(); + let result = plan.execute().await; + assert_eq!(reloads.load(Ordering::SeqCst), usize::from(configured == 2)); + let should_send = configured == 2 && reload_succeeds; + assert_eq!(calls.load(Ordering::SeqCst), usize::from(should_send)); + if should_send { + assert!(result.is_ok()); + } else { + let Err(Error::IncompatibleRequest(error)) = result else { + panic!("expected local rejection") + }; + assert_eq!( + error.reason, + errorpb::IncompatibleRequestReason::Unknown as i32 + ); + assert_eq!(error.max_compatible_txn_protocol_version, 1); + } + } + + #[tokio::test] + async fn protocol_allowance_survives_region_retry_and_resharding() { + let versions = Arc::new(std::sync::Mutex::new(Vec::new())); + let observed = versions.clone(); + let invalidations = Arc::new(AtomicUsize::new(0)); + let invalidated = invalidations.clone(); + let client = crate::mock::MockKvClient::with_dispatch_hook(move |request| { + let version = request + .downcast_ref::() + .unwrap() + .context + .as_ref() + .unwrap() + .txn_protocol_version; + let mut sent = observed.lock().unwrap(); + sent.push(version); + let error = if sent.len() == 2 { + errorpb::Error { + region_not_found: Some(Default::default()), + ..Default::default() + } + } else { + errorpb::Error { + incompatible_request: Some(admission_rejection()), + ..Default::default() + } + }; + Ok(Box::new(kvrpcpb::GetResponse { + region_error: Some(error), + ..Default::default() + })) + }); + let routed = client.clone(); + let pd = Arc::new( + MockPdClient::new(client) + .with_map_region_to_store_hook(move |region| { + let mut store = protocol_store(routed.clone(), Some((0, 1))); + store.region_with_leader = region; + Ok(store) + }) + .with_invalidate_region_hook(move |_| { + invalidated.fetch_add(1, Ordering::SeqCst); + }), + ); + let plan = crate::request::PlanBuilder::new( + pd, + Keyspace::Disable, + kvrpcpb::GetRequest { + key: vec![1], + ..Default::default() + }, + ) + .txn_protocol_compatibility(crate::TxnRequestPolicy::default()) + .retry_multi_region(Backoff::no_jitter_backoff(1, 1, 3)) + .plan(); + let Err(Error::IncompatibleRequest(error)) = plan.execute().await else { + panic!("expected exhausted compatibility allowance") + }; + assert_eq!(*error, admission_rejection()); + assert_eq!(*versions.lock().unwrap(), vec![1, 0, 1]); + assert_eq!(invalidations.load(Ordering::SeqCst), 1); + } + + #[rstest::rstest] + #[case(false, false)] + #[case(true, false)] + #[case(false, true)] + #[case(true, true)] + #[tokio::test] + async fn protocol_error_extraction_preserves_priority_across_sources( + #[case] reverse: bool, + #[case] undetermined: bool, + ) { + #[derive(Clone)] + struct Errors { + reverse: bool, + undetermined: bool, + } + #[async_trait] + impl Plan for Errors { + type Result = Vec>; + async fn execute(&self) -> Result { + let mut errors = vec![ + Err(Error::Unimplemented), + Ok(kvrpcpb::GetResponse { + region_error: Some(errorpb::Error { + incompatible_request: Some(admission_rejection()), + ..Default::default() + }), + ..Default::default() + }), + ]; + if self.undetermined { + errors.push(Err(Error::RegionError(Box::new(errorpb::Error { + message: "original unknown outcome".into(), + undetermined_result: Some(Default::default()), + ..Default::default() + })))); + } + if self.reverse { + errors.reverse(); + } + Ok(errors) + } + } + let error = ExtractError { + inner: Errors { + reverse, + undetermined, + }, + } + .execute() + .await + .unwrap_err(); + assert_eq!( + error.priority(), + if undetermined { + ErrorPriority::Undetermined + } else { + ErrorPriority::Incompatible + } + ); + let Error::RegionError(error) = error else { + panic!("original region envelope must be preserved") + }; + if undetermined { + assert_eq!(error.message, "original unknown outcome"); + } else { + assert_eq!(error.incompatible_request, Some(admission_rejection())); + } + } + + #[rstest::rstest] + #[case(ErrorPriority::Ordinary, ErrorPriority::Incompatible)] + #[case(ErrorPriority::Incompatible, ErrorPriority::Ordinary)] + #[case(ErrorPriority::Incompatible, ErrorPriority::Undetermined)] + #[case(ErrorPriority::Undetermined, ErrorPriority::Incompatible)] + #[case(ErrorPriority::Ordinary, ErrorPriority::Ordinary)] + #[tokio::test] + async fn protocol_shard_aggregation_preserves_highest_priority( + #[case] first: ErrorPriority, + #[case] second: ErrorPriority, + ) { + #[derive(Clone)] + struct ShardErrors { + index: usize, + priorities: [ErrorPriority; 2], + } + #[async_trait] + impl Plan for ShardErrors { + type Result = kvrpcpb::GetResponse; + async fn execute(&self) -> Result { + Err(match self.priorities[self.index] { + ErrorPriority::Ordinary => Error::StringError(format!("shard {}", self.index)), + ErrorPriority::Incompatible => { + Error::IncompatibleRequest(Box::new(admission_rejection())) + } + ErrorPriority::Undetermined => Error::RegionError(Box::new(errorpb::Error { + undetermined_result: Some(Default::default()), + ..Default::default() + })), + }) + } + } + impl Shardable for ShardErrors { + type Shard = usize; + fn shards( + &self, + _: &Arc, + ) -> BoxStream<'static, Result<(usize, RegionWithLeader)>> { + Box::pin(stream::iter(vec![ + Ok((0, MockPdClient::region1())), + Ok((1, MockPdClient::region2())), + ])) + } + fn apply_shard(&mut self, index: usize) { + self.index = index; + } + fn apply_store(&mut self, _: &RegionStore) -> Result<()> { + Ok(()) + } + } + let plan = RetryableMultiRegion { + inner: ShardErrors { + index: 0, + priorities: [first, second], + }, + pd_client: Arc::new(MockPdClient::default()), + backoff: Backoff::no_backoff(), + preserve_region_results: false, + terminal_on_undetermined: false, + terminal_on_dispatch_error: false, + }; + let error = plan.execute().await.unwrap_err(); + assert_eq!(error.priority(), first.min(second)); + if first == ErrorPriority::Ordinary && second == ErrorPriority::Ordinary { + assert!(matches!(error, Error::StringError(message) if message == "shard 0")); + } + } + + #[tokio::test] + async fn protocol_version_is_reselected_for_a_fallback_store() { + let sent = Arc::new(std::sync::Mutex::new(Vec::new())); + let observed = sent.clone(); + let client = crate::mock::MockKvClient::with_dispatch_hook(move |request| { + let context = request + .downcast_ref::() + .unwrap() + .context + .as_ref() + .unwrap(); + let store = context.peer.as_ref().unwrap().store_id; + observed + .lock() + .unwrap() + .push((store, context.txn_protocol_version)); + if store == 41 { + return Err(Error::GrpcAPI(tonic::Status::unavailable( + "leader unavailable", + ))); + } + Ok(Box::new(kvrpcpb::GetResponse::default())) + }); + let mut region = MockPdClient::region1(); + region.region.peers = vec![ + region.leader.clone().unwrap(), + metapb::Peer { + id: 2, + store_id: 44, + ..Default::default() + }, + ]; + let located = region.clone(); + let routed = client.clone(); + let pd = Arc::new( + MockPdClient::new(client) + .with_region_for_key_hook(move |_| Ok(located.clone())) + .with_map_region_to_store_hook(move |region| { + let id = region.get_store_id().unwrap(); + let mut store = protocol_store(routed.clone(), Some((0, u32::from(id == 41)))); + store.meta.id = id; + store.region_with_leader = region; + Ok(store) + }) + .with_update_leader_hook(|_, leader| { + assert_eq!(leader.store_id, 44); + Ok(()) + }), + ); + let plan = crate::request::PlanBuilder::new( + pd, + Keyspace::Disable, + kvrpcpb::GetRequest { + key: vec![1], + ..Default::default() + }, + ) + .txn_protocol_compatibility(crate::TxnRequestPolicy::default()) + .retry_multi_region(Backoff::no_backoff()) + .plan(); + assert!(plan.execute().await.is_ok()); + assert_eq!(*sent.lock().unwrap(), vec![(41, 1), (44, 0)]); + } + + #[tokio::test] + async fn protocol_shared_pessimistic_payload_cannot_be_declared_legacy() { + let client = crate::mock::MockKvClient::with_dispatch_hook(|_| { + panic!("unsupported payload reached dispatch") + }); + let plan = crate::request::PlanBuilder::new( + Arc::new(MockPdClient::default()), + Keyspace::Disable, + kvrpcpb::PessimisticLockRequest { + mutations: vec![kvrpcpb::Mutation { + op: kvrpcpb::Op::SharedPessimisticLock as i32, + ..Default::default() + }], + ..Default::default() + }, + ) + .txn_protocol_compatibility(crate::TxnRequestPolicy::default()) + .single_region_with_store(protocol_store(client, Some((0, 2)))) + .await + .unwrap() + .plan(); + let Err(Error::IncompatibleRequest(error)) = plan.execute().await else { + panic!("expected payload rejection") + }; + assert_eq!(error.provided_txn_protocol_version, 1); + assert_eq!(error.max_compatible_txn_protocol_version, 2); + } + + #[test] + fn protocol_error_borrow_preserves_response_and_wrapper_state() { + let original = errorpb::Error { + message: "ordinary region error".into(), + not_leader: Some(Default::default()), + ..Default::default() + }; + let mut wrapped: Result>> = + Ok(ResponseWithShard( + kvrpcpb::GetResponse { + value: b"value".to_vec(), + region_error: Some(original.clone()), + ..Default::default() + }, + vec![1], + )); + assert_eq!(wrapped.region_error_ref(), Some(&original)); + assert_eq!(wrapped.region_error_ref(), Some(&original)); + assert_eq!(wrapped.region_error(), Some(original)); + assert!(wrapped.region_error_ref().is_none()); + let ResponseWithShard(response, shard) = wrapped.unwrap(); + assert_eq!(response.value, b"value"); + assert_eq!(shard, vec![1]); + let mut failed: Result = Err(Error::Unimplemented); + assert!(failed.region_error_ref().is_none()); + assert!(failed.region_error().is_none()); + assert!(matches!(failed, Err(Error::Unimplemented))); + } + #[rstest::rstest] + #[case(false)] + #[case(true)] + #[tokio::test] + async fn protocol_cleanup_pages_renew_allowance_but_page_retries_do_not( + #[case] second_page_routing_error: bool, + ) { + let sent = Arc::new(std::sync::Mutex::new(Vec::new())); + let observed = sent.clone(); + let client = crate::mock::MockKvClient::with_dispatch_hook(move |request| { + let request = request.downcast_ref::().unwrap(); + let version = request.context.as_ref().unwrap().txn_protocol_version; + observed + .lock() + .unwrap() + .push((request.start_key.clone(), version)); + let response = if version == 1 { + kvrpcpb::ScanLockResponse { + region_error: Some(errorpb::Error { + incompatible_request: Some(admission_rejection()), + ..Default::default() + }), + ..Default::default() + } + } else if request.start_key == vec![1] { + kvrpcpb::ScanLockResponse { + // A full page advances the scan. The async-only cleanup + // filter excludes this lock, keeping this test about pagination. + locks: vec![kvrpcpb::LockInfo { + key: vec![1], + ..Default::default() + }], + ..Default::default() + } + } else { + assert_eq!(request.start_key, vec![1, 0]); + kvrpcpb::ScanLockResponse { + region_error: second_page_routing_error.then(|| errorpb::Error { + region_not_found: Some(Default::default()), + ..Default::default() + }), + ..Default::default() + } + }; + Ok(Box::new(response)) + }); + let routed = client.clone(); + let invalidations = Arc::new(AtomicUsize::new(0)); + let invalidated = invalidations.clone(); + let pd = Arc::new( + MockPdClient::new(client) + .with_map_region_to_store_hook(move |region| { + let mut store = protocol_store(routed.clone(), Some((0, 1))); + store.region_with_leader = region; + Ok(store) + }) + .with_invalidate_region_hook(move |_| { + invalidated.fetch_add(1, Ordering::SeqCst); + }), + ); + let plan = crate::request::PlanBuilder::new( + pd, + Keyspace::Disable, + kvrpcpb::ScanLockRequest { + start_key: vec![1], + end_key: vec![9], + limit: 1, + ..Default::default() + }, + ) + .txn_protocol_compatibility(crate::TxnRequestPolicy::default()) + .cleanup_locks( + crate::transaction::ResolveLocksContext::default(), + crate::transaction::ResolveLocksOptions { + async_commit_only: true, + batch_size: 1, + }, + Backoff::no_backoff(), + Keyspace::Disable, + ) + .retry_multi_region(Backoff::no_jitter_backoff(1, 1, 1)) + .plan(); + let result = plan.execute().await; + let mut expected = vec![(vec![1], 1), (vec![1], 0), (vec![1, 0], 1), (vec![1, 0], 0)]; + if second_page_routing_error { + // Region retry restarts the scan, but cannot replenish the allowance + // spent by the failed page's resend. + let Err(Error::IncompatibleRequest(error)) = result else { + panic!("expected spent page allowance") + }; + assert_eq!(*error, admission_rejection()); + expected.push((vec![1], 1)); + assert_eq!(invalidations.load(Ordering::SeqCst), 1); + } else { + assert!(result.unwrap().iter().all(Result::is_ok)); + assert_eq!(invalidations.load(Ordering::SeqCst), 0); + } + assert_eq!(*sent.lock().unwrap(), expected); + } } diff --git a/src/request/plan_builder.rs b/src/request/plan_builder.rs index 183c3e6b6..e97f09075 100644 --- a/src/request/plan_builder.rs +++ b/src/request/plan_builder.rs @@ -1,6 +1,7 @@ // Copyright 2021 TiKV Project Authors. Licensed under Apache-2.0. use std::marker::PhantomData; +use std::sync::atomic::AtomicBool; use std::sync::Arc; use super::plan::PreserveShard; @@ -26,7 +27,6 @@ use crate::store::HasKeyErrors; use crate::store::HasRegionError; use crate::store::HasRegionErrors; use crate::store::RegionStore; -use crate::transaction::HasLocks; use crate::transaction::ResolveLocksContext; use crate::transaction::ResolveLocksOptions; use crate::Result; @@ -59,6 +59,52 @@ impl PlanBuilder, NoTarget> { phantom: PhantomData, } } + + /// Install [`super::TxnProtocolCompatibility`] before lock resolution or routing. + /// Creates a fresh resend allowance. High-level transactional APIs install this + /// automatically; lower-level transactional callers must add it explicitly. + pub fn txn_protocol_compatibility( + self, + policy: crate::TxnRequestPolicy, + ) -> PlanBuilder, NoTarget> { + self.txn_protocol_compatibility_with_allowance(policy, Arc::new(AtomicBool::new(false))) + } + + /// Preserve a logical send's allowance when a caller rebuilds plans during retries. + pub(crate) fn txn_protocol_compatibility_with_allowance( + self, + policy: crate::TxnRequestPolicy, + allowance: Arc, + ) -> PlanBuilder, NoTarget> { + PlanBuilder { + pd_client: self.pd_client.clone(), + plan: super::TxnProtocolCompatibility { + inner: self.plan, + pd_client: self.pd_client, + policy, + store: None, + resend_used: allowance, + }, + phantom: PhantomData, + } + } +} + +impl + PlanBuilder, NoTarget> +{ + /// Direct region targeting also prepares compatibility against that store. + pub async fn single_region_with_store( + mut self, + store: RegionStore, + ) -> Result, Targetted>> { + self.plan.apply_region_store(&store)?; + Ok(PlanBuilder { + pd_client: self.pd_client, + plan: self.plan, + phantom: PhantomData, + }) + } } impl PlanBuilder { @@ -69,17 +115,17 @@ impl PlanBuilder { } } -impl PlanBuilder { +impl + PlanBuilder, Ph> +{ /// If there is a lock error, then resolve the lock and retry the request. pub fn resolve_lock( self, timestamp: Timestamp, backoff: Backoff, keyspace: Keyspace, - ) -> PlanBuilder, Ph> - where - P::Result: HasLocks, - { + ) -> PlanBuilder, PdC>, Ph> { + let request_policy = self.plan.policy; PlanBuilder { pd_client: self.pd_client.clone(), plan: ResolveLock { @@ -88,6 +134,7 @@ impl PlanBuilder { backoff, pd_client: self.pd_client, keyspace, + request_policy, }, phantom: PhantomData, } @@ -99,11 +146,12 @@ impl PlanBuilder { options: ResolveLocksOptions, backoff: Backoff, keyspace: Keyspace, - ) -> PlanBuilder, Ph> + ) -> PlanBuilder, PdC>, Ph> where - P: Shardable + NextBatch, - P::Result: HasLocks + HasNextBatch + HasRegionError + HasKeyErrors, + Req: Shardable + NextBatch, + Req::Response: HasNextBatch, { + let request_policy = self.plan.policy; PlanBuilder { pd_client: self.pd_client.clone(), plan: CleanupLocks { @@ -114,11 +162,14 @@ impl PlanBuilder { backoff, pd_client: self.pd_client, keyspace, + request_policy, }, phantom: PhantomData, } } +} +impl PlanBuilder { /// Merge the results of a request. Usually used where a request is sent to multiple regions /// to combine the responses from each region. pub fn merge>(self, merge: M) -> PlanBuilder, Ph> diff --git a/src/request/shard.rs b/src/request/shard.rs index 1bac69e42..3c08505d6 100644 --- a/src/request/shard.rs +++ b/src/request/shard.rs @@ -135,6 +135,44 @@ impl NextBatch for Dispatch { } } +impl Shardable + for super::TxnProtocolCompatibility +{ + type Shard = Req::Shard; + + fn shards( + &self, + pd_client: &Arc, + ) -> BoxStream<'static, Result<(Self::Shard, RegionWithLeader)>> { + self.inner.shards(pd_client) + } + + fn apply_shard(&mut self, shard: Self::Shard) { + // Initial siblings fork independently. Re-sharded descendants inherit + // an already spent allowance rather than replenishing it. + self.resend_used = Arc::new(std::sync::atomic::AtomicBool::new( + self.resend_used.load(std::sync::atomic::Ordering::Relaxed), + )); + self.inner.apply_shard(shard); + } + + fn apply_store(&mut self, store: &RegionStore) -> Result<()> { + self.apply_region_store(store) + } +} + +impl NextBatch + for super::TxnProtocolCompatibility +{ + fn next_batch(&mut self, range: (Vec, Vec)) { + self.inner.next_batch(range); + // A new page starts a new send. Keep the shared flag so execution + // clones and outer retries observe this page's allowance together. + self.resend_used + .store(false, std::sync::atomic::Ordering::Relaxed); + } +} + impl Shardable for PreserveShard

{ type Shard = P::Shard; diff --git a/src/stats.rs b/src/stats.rs index 9f4bd1052..17fae0d16 100644 --- a/src/stats.rs +++ b/src/stats.rs @@ -5,9 +5,11 @@ use std::time::Instant; use prometheus::register_histogram; use prometheus::register_histogram_vec; +use prometheus::register_int_counter; use prometheus::register_int_counter_vec; use prometheus::Histogram; use prometheus::HistogramVec; +use prometheus::IntCounter; use prometheus::IntCounterVec; use crate::Result; @@ -78,7 +80,40 @@ pub fn observe_tso_batch(batch_size: usize) { PD_TSO_BATCH_SIZE_HISTOGRAM.observe(batch_size as f64); } +pub(crate) fn txn_protocol_rejection(source: &'static str) { + TXN_PROTOCOL_REJECTION_COUNTER + .with_label_values(&[source]) + .inc(); +} + +pub(crate) fn txn_protocol_resend() { + TXN_PROTOCOL_RESEND_COUNTER.inc(); +} + +pub(crate) fn txn_protocol_store_reload(event: &'static str) { + TXN_PROTOCOL_STORE_RELOAD_COUNTER + .with_label_values(&[event]) + .inc(); +} + lazy_static::lazy_static! { + static ref TXN_PROTOCOL_REJECTION_COUNTER: IntCounterVec = register_int_counter_vec!( + "tikv_txn_protocol_rejection_total", + "Transaction protocol rejections by source: local or server", + &["source"] + ) + .unwrap(); + static ref TXN_PROTOCOL_RESEND_COUNTER: IntCounter = register_int_counter!( + "tikv_txn_protocol_resend_total", + "Transaction RPC resends attempted after compatibility rejections" + ) + .unwrap(); + static ref TXN_PROTOCOL_STORE_RELOAD_COUNTER: IntCounterVec = register_int_counter_vec!( + "tikv_txn_protocol_store_reload_total", + "Store metadata reload events: started, success, failure, joined or suppressed", + &["event"] + ) + .unwrap(); static ref TIKV_REQUEST_DURATION_HISTOGRAM_VEC: HistogramVec = register_histogram_vec!( "tikv_request_duration_seconds", "Bucketed histogram of TiKV requests duration", diff --git a/src/store/errors.rs b/src/store/errors.rs index 06a490633..4f61f3c32 100644 --- a/src/store/errors.rs +++ b/src/store/errors.rs @@ -5,6 +5,9 @@ use crate::Error; // Those that can have a single region error pub trait HasRegionError { + /// Borrow the same error as [`Self::region_error`] without consuming it. + fn region_error_ref(&self) -> Option<&crate::proto::errorpb::Error>; + /// Take ownership of the region error. fn region_error(&mut self) -> Option; } @@ -26,6 +29,10 @@ impl HasRegionErrors for T { macro_rules! has_region_error { ($type:ty) => { impl HasRegionError for $type { + fn region_error_ref(&self) -> Option<&crate::proto::errorpb::Error> { + self.region_error.as_ref() + } + fn region_error(&mut self) -> Option { self.region_error.take().map(|e| e.into()) } @@ -175,17 +182,21 @@ impl HasKeyErrors for Result { impl HasKeyErrors for Vec { fn key_errors(&mut self) -> Option> { + let mut errors = None; for t in self { - if let Some(e) = t.key_errors() { - return Some(e); + if let Some(mut next) = t.key_errors() { + errors.get_or_insert_with(Vec::new).append(&mut next); } } - - None + errors } } impl HasRegionError for Result { + fn region_error_ref(&self) -> Option<&crate::proto::errorpb::Error> { + self.as_ref().ok().and_then(|t| t.region_error_ref()) + } + fn region_error(&mut self) -> Option { self.as_mut().ok().and_then(|t| t.region_error()) } diff --git a/src/store/mod.rs b/src/store/mod.rs index fb6ed7094..80d8bf453 100644 --- a/src/store/mod.rs +++ b/src/store/mod.rs @@ -30,6 +30,9 @@ use crate::Result; pub struct RegionStore { pub region_with_leader: RegionWithLeader, pub client: Arc, + // Default metadata preserves the constructor used by mock routing clients. + #[new(default)] + pub meta: crate::proto::metapb::Store, } #[derive(new, Clone)] diff --git a/src/store/request.rs b/src/store/request.rs index 2d9c29ad6..3279371c6 100644 --- a/src/store/request.rs +++ b/src/store/request.rs @@ -22,6 +22,8 @@ pub trait Request: Any + Sync + Send + 'static { ) -> Result>; fn label(&self) -> &'static str; fn as_any(&self) -> &dyn Any; + /// Borrow the context, creating it if absent. Wrappers delegate to their request. + fn context_mut(&mut self) -> &mut kvrpcpb::Context; fn set_leader(&mut self, leader: &RegionWithLeader) -> Result<()>; fn set_api_version(&mut self, api_version: kvrpcpb::ApiVersion); } @@ -53,6 +55,10 @@ macro_rules! impl_request { self } + fn context_mut(&mut self) -> &mut kvrpcpb::Context { + self.context.get_or_insert_with(Default::default) + } + fn set_leader(&mut self, leader: &RegionWithLeader) -> Result<()> { let ctx = self.context.get_or_insert(kvrpcpb::Context::default()); let leader_peer = leader.leader.as_ref().ok_or(Error::LeaderNotFound { diff --git a/src/transaction/client.rs b/src/transaction/client.rs index 62f248593..00ebd2180 100644 --- a/src/transaction/client.rs +++ b/src/transaction/client.rs @@ -57,6 +57,7 @@ const SCAN_LOCK_BATCH_SIZE: u32 = 1024; pub struct Client { pd: Arc, keyspace: Keyspace, + request_policy: crate::TxnRequestPolicy, } impl Clone for Client { @@ -64,6 +65,7 @@ impl Clone for Client { Self { pd: self.pd.clone(), keyspace: self.keyspace, + request_policy: self.request_policy, } } } @@ -114,18 +116,21 @@ impl Client { config: Config, ) -> Result { debug!("creating new transactional client"); + let request_policy = config.txn_request_policy()?; let pd_endpoints: Vec = pd_endpoints.into_iter().map(Into::into).collect(); let pd = Arc::new(PdRpcClient::connect(&pd_endpoints, config.clone(), true).await?); let keyspace = match config.keyspace { Some(name) => { let keyspace = pd.load_keyspace(&name).await?; - Keyspace::Enable { - keyspace_id: keyspace.id, - } + Keyspace::from_metadata(keyspace)? } None => Keyspace::Disable, }; - Ok(Client { pd, keyspace }) + Ok(Client { + pd, + keyspace, + request_policy, + }) } /// Create a transactional [`Client`] that uses API V2 without adding or removing any API V2 @@ -136,6 +141,7 @@ impl Client { pd_endpoints: Vec, config: Config, ) -> Result { + let request_policy = config.txn_request_policy()?; if config.keyspace.is_some() { return Err(crate::Error::StringError( "config.keyspace must be unset when using api-v2-no-prefix mode".to_owned(), @@ -148,6 +154,7 @@ impl Client { Ok(Client { pd, keyspace: Keyspace::ApiV2NoPrefix, + request_policy, }) } @@ -302,6 +309,7 @@ impl Client { let range = range.into().encode_keyspace(self.keyspace, KeyMode::Txn); let req = new_scan_lock_request(range, safepoint, options.batch_size); let plan = crate::request::PlanBuilder::new(self.pd.clone(), self.keyspace, req) + .txn_protocol_compatibility(self.request_policy) .cleanup_locks(ctx.clone(), options, backoff, self.keyspace) .retry_multi_region(DEFAULT_REGION_BACKOFF) .extract_error() @@ -322,6 +330,7 @@ impl Client { let range = range.into().encode_keyspace(self.keyspace, KeyMode::Txn); let req = new_scan_lock_request(range, safepoint, batch_size); let plan = crate::request::PlanBuilder::new(self.pd.clone(), self.keyspace, req) + .txn_protocol_compatibility(self.request_policy) .retry_multi_region(DEFAULT_REGION_BACKOFF) .merge(crate::request::Collect) .plan(); @@ -348,6 +357,7 @@ impl Client { timestamp.clone(), self.pd.clone(), self.keyspace, + self.request_policy, ) .await?; live_locks = resolved_locks.truncate_keyspace(self.keyspace); @@ -373,7 +383,12 @@ impl Client { /// This interface is intended for special scenarios that resemble operations like "drop table" or "drop database" in TiDB. pub async fn unsafe_destroy_range(&self, range: impl Into) -> Result<()> { let range = range.into().encode_keyspace(self.keyspace, KeyMode::Txn); - let req = new_unsafe_destroy_range_request(range); + let mut req = new_unsafe_destroy_range_request(range); + // This store-level RPC is outside transaction protocol admission, matching + // client-go. It still identifies the initiating product for auditing. + req.context + .get_or_insert_with(Default::default) + .request_origin = self.request_policy.origin as i32; let plan = crate::request::PlanBuilder::new(self.pd.clone(), self.keyspace, req) .all_stores(DEFAULT_STORE_BACKOFF) .merge(crate::request::Collect) @@ -383,5 +398,11 @@ impl Client { fn new_transaction(&self, timestamp: Timestamp, options: TransactionOptions) -> Transaction { Transaction::new(timestamp, self.pd.clone(), options, self.keyspace) + .with_request_policy(self.request_policy) + } + + /// Return this client's immutable transactional request policy. + pub fn request_policy(&self) -> crate::TxnRequestPolicy { + self.request_policy } } diff --git a/src/transaction/lock.rs b/src/transaction/lock.rs index 29d245404..d334e65d8 100644 --- a/src/transaction/lock.rs +++ b/src/transaction/lock.rs @@ -2,6 +2,7 @@ use std::collections::HashMap; use std::collections::HashSet; +use std::sync::atomic::AtomicBool; use std::sync::Arc; use fail::fail_point; @@ -88,6 +89,7 @@ pub async fn resolve_locks( timestamp: Timestamp, pd_client: Arc, keyspace: Keyspace, + request_policy: crate::TxnRequestPolicy, ) -> Result /* live_locks */> { debug!("resolving locks"); reject_shared_locks(&locks)?; @@ -98,7 +100,7 @@ pub async fn resolve_locks( let mut live_locks = Vec::new(); // Final transaction statuses are cached in the resolver's context, so a transaction met // through several locks is queried (or recovered) only once. - let mut lock_resolver = LockResolver::new(ResolveLocksContext::default()); + let mut lock_resolver = LockResolver::new(ResolveLocksContext::default(), request_policy); // Regions already swept by ResolveLock, per transaction. let mut clean_regions: HashMap> = HashMap::new(); // We must check txn status for *all* locks, not only TTL-expired ones. @@ -143,6 +145,7 @@ pub async fn resolve_locks( keyspace, OPTIMISTIC_BACKOFF, regions, + request_policy, ) .await?; } @@ -190,6 +193,7 @@ async fn pessimistic_rollback_lock( lock: &kvrpcpb::LockInfo, pd_client: Arc, keyspace: Keyspace, + request_policy: crate::TxnRequestPolicy, ) -> Result<()> { if lock.key == lock.primary_lock { // The lock is its transaction's primary: the CheckTxnStatus just sent to this very @@ -209,6 +213,7 @@ async fn pessimistic_rollback_lock( for_update_ts, ); let plan = crate::request::PlanBuilder::new(pd_client, keyspace, req) + .txn_protocol_compatibility(request_policy) .retry_multi_region(DEFAULT_REGION_BACKOFF) .extract_error() .plan(); @@ -229,8 +234,11 @@ async fn resolve_lock_with_retry( keyspace: Keyspace, mut backoff: Backoff, clean_regions: &mut HashSet, + request_policy: crate::TxnRequestPolicy, ) -> Result<()> { debug!("resolving locks with retry"); + // Routing retries rebuild the plan but must not replenish its resend allowance. + let allowance = Arc::new(AtomicBool::new(false)); let mut attempt = 0; loop { attempt += 1; @@ -244,6 +252,7 @@ async fn resolve_lock_with_retry( requests::new_resolve_lock_request(start_version, commit_version, is_txn_file); let plan_builder = match crate::request::PlanBuilder::new(pd_client.clone(), keyspace, request) + .txn_protocol_compatibility_with_allowance(request_policy, allowance.clone()) .single_region_with_store(store.clone()) .await { @@ -368,11 +377,22 @@ impl ResolveLocksContext { pub struct LockResolver { ctx: ResolveLocksContext, + request_policy: crate::TxnRequestPolicy, } impl LockResolver { - pub fn new(ctx: ResolveLocksContext) -> Self { - Self { ctx } + /// Create a resolver using the initiating client's + /// [`request_policy`](crate::TransactionClient::request_policy). + pub fn new(ctx: ResolveLocksContext, request_policy: crate::TxnRequestPolicy) -> Self { + Self { + ctx, + request_policy, + } + } + + /// Return this resolver's immutable transactional request policy. + pub fn request_policy(&self) -> crate::TxnRequestPolicy { + self.request_policy } /// Decide what `resolve_locks` has to do about `lock`: query its transaction's status and, @@ -407,7 +427,7 @@ impl LockResolver { // changed its primary after writing this lock (pingcap/tidb#42937). Roll back // only this stale lock — the transaction itself may still be alive, and a // region-wide ResolveLock could roll back its other, legitimate locks. - pessimistic_rollback_lock(lock, pd_client, keyspace).await?; + pessimistic_rollback_lock(lock, pd_client, keyspace, self.request_policy).await?; return Ok(LockAction::Done); } Err(err) => return Err(err), @@ -429,7 +449,7 @@ impl LockResolver { // encountered lock itself may be removed — a region-wide ResolveLock could roll // back the transaction's legitimate locks, prewrite locks included. Pessimistic // locks never block reads, so nothing else is waiting on this region either. - pessimistic_rollback_lock(lock, pd_client, keyspace).await?; + pessimistic_rollback_lock(lock, pd_client, keyspace, self.request_policy).await?; return Ok(LockAction::Done); } _ => return Ok(LockAction::from_status(&status)), @@ -648,6 +668,7 @@ impl LockResolver { is_txn_file, ); let plan = crate::request::PlanBuilder::new(pd_client.clone(), keyspace, req) + .txn_protocol_compatibility(self.request_policy) .retry_multi_region(DEFAULT_REGION_BACKOFF) .merge(CollectSingle) .extract_error() @@ -697,6 +718,7 @@ impl LockResolver { ) -> Result { let req = new_check_secondary_locks_request(keys, txn_id); let plan = crate::request::PlanBuilder::new(pd_client.clone(), keyspace, req) + .txn_protocol_compatibility(self.request_policy) .preserve_shard() .retry_multi_region(DEFAULT_REGION_BACKOFF) .extract_error() @@ -717,6 +739,7 @@ impl LockResolver { let ver_id = store.region_with_leader.ver_id(); let request = requests::new_batch_resolve_lock_request(txn_infos.clone()); let plan = crate::request::PlanBuilder::new(pd_client.clone(), keyspace, request) + .txn_protocol_compatibility(self.request_policy) .single_region_with_store(store.clone()) .await? .extract_error() @@ -968,6 +991,7 @@ mod tests { keyspace, backoff.clone(), &mut clean_regions, + crate::TxnRequestPolicy::default(), ) .await .unwrap(); @@ -989,6 +1013,7 @@ mod tests { keyspace, backoff, &mut clean_regions, + crate::TxnRequestPolicy::default(), ) .await .expect_err("should return error"); @@ -1027,9 +1052,15 @@ mod tests { lock.lock_version = 1; lock.lock_ttl = 100; // not expired under MockPdClient's Timestamp::default() - let live_locks = resolve_locks(vec![lock], Timestamp::default(), client, Keyspace::Disable) - .await - .unwrap(); + let live_locks = resolve_locks( + vec![lock], + Timestamp::default(), + client, + Keyspace::Disable, + crate::TxnRequestPolicy::default(), + ) + .await + .unwrap(); assert!(live_locks.is_empty()); assert_eq!(check_txn_status_count.load(Ordering::SeqCst), 1); @@ -1104,9 +1135,15 @@ mod tests { }) .collect(); - let live_locks = resolve_locks(locks, Timestamp::default(), client, keyspace) - .await - .unwrap(); + let live_locks = resolve_locks( + locks, + Timestamp::default(), + client, + keyspace, + crate::TxnRequestPolicy::default(), + ) + .await + .unwrap(); assert!(live_locks.is_empty()); assert_eq!(check_secondary_count.load(Ordering::SeqCst), 1); @@ -1158,9 +1195,15 @@ mod tests { let lock = async_commit_primary_lock(PRIMARY_KEY, 42, vec![SECONDARY_KEY.to_vec()]); - let live_locks = resolve_locks(vec![lock], Timestamp::default(), client, Keyspace::Disable) - .await - .unwrap(); + let live_locks = resolve_locks( + vec![lock], + Timestamp::default(), + client, + Keyspace::Disable, + crate::TxnRequestPolicy::default(), + ) + .await + .unwrap(); assert!(live_locks.is_empty()); assert_eq!(check_secondary_count.load(Ordering::SeqCst), 1); @@ -1233,9 +1276,15 @@ mod tests { let lock = async_commit_primary_lock(PRIMARY_KEY, 42, vec![SECONDARY_KEY.to_vec()]); - let live_locks = resolve_locks(vec![lock], Timestamp::default(), client, Keyspace::Disable) - .await - .unwrap(); + let live_locks = resolve_locks( + vec![lock], + Timestamp::default(), + client, + Keyspace::Disable, + crate::TxnRequestPolicy::default(), + ) + .await + .unwrap(); assert_eq!(check_txn_status_count.load(Ordering::SeqCst), 2); assert_eq!(force_sync_count.load(Ordering::SeqCst), 1); @@ -1344,9 +1393,15 @@ mod tests { let lock = async_commit_primary_lock(&[1], 40, vec![vec![2], vec![3]]); - let live_locks = resolve_locks(vec![lock], Timestamp::default(), client, Keyspace::Disable) - .await - .unwrap(); + let live_locks = resolve_locks( + vec![lock], + Timestamp::default(), + client, + Keyspace::Disable, + crate::TxnRequestPolicy::default(), + ) + .await + .unwrap(); assert!(live_locks.is_empty()); // One failed pre-split request plus one per post-split region. @@ -1400,9 +1455,15 @@ mod tests { ..Default::default() }; - let live_locks = resolve_locks(vec![lock], Timestamp::default(), client, Keyspace::Disable) - .await - .unwrap(); + let live_locks = resolve_locks( + vec![lock], + Timestamp::default(), + client, + Keyspace::Disable, + crate::TxnRequestPolicy::default(), + ) + .await + .unwrap(); assert!(live_locks.is_empty()); assert_eq!(check_txn_status_count.load(Ordering::SeqCst), 2); @@ -1464,9 +1525,15 @@ mod tests { // Two stale pessimistic locks of the same transaction in the same mock region. let locks = vec![make_lock(1), make_lock(2)]; - let live_locks = resolve_locks(locks, Timestamp::default(), client, Keyspace::Disable) - .await - .unwrap(); + let live_locks = resolve_locks( + locks, + Timestamp::default(), + client, + Keyspace::Disable, + crate::TxnRequestPolicy::default(), + ) + .await + .unwrap(); assert!(live_locks.is_empty()); assert_eq!( @@ -1553,9 +1620,15 @@ mod tests { ..Default::default() }; - let live_locks = resolve_locks(vec![lock], Timestamp::default(), client, Keyspace::Disable) - .await - .unwrap(); + let live_locks = resolve_locks( + vec![lock], + Timestamp::default(), + client, + Keyspace::Disable, + crate::TxnRequestPolicy::default(), + ) + .await + .unwrap(); assert!(live_locks.is_empty()); assert_eq!(*rolled_back_keys.lock().unwrap(), vec![vec![1]]); @@ -1596,9 +1669,15 @@ mod tests { ..Default::default() }; - let live_locks = resolve_locks(vec![lock], Timestamp::default(), client, Keyspace::Disable) - .await - .unwrap(); + let live_locks = resolve_locks( + vec![lock], + Timestamp::default(), + client, + Keyspace::Disable, + crate::TxnRequestPolicy::default(), + ) + .await + .unwrap(); assert!(live_locks.is_empty()); assert_eq!(check_txn_status_count.load(Ordering::SeqCst), 1); @@ -1690,6 +1769,7 @@ mod tests { Timestamp::default(), client, Keyspace::Disable, + crate::TxnRequestPolicy::default(), ) .await .unwrap(); @@ -1737,8 +1817,14 @@ mod tests { ..Default::default() }; - let result = - resolve_locks(vec![lock], Timestamp::default(), client, Keyspace::Disable).await; + let result = resolve_locks( + vec![lock], + Timestamp::default(), + client, + Keyspace::Disable, + crate::TxnRequestPolicy::default(), + ) + .await; assert!(matches!(result, Err(Error::KeyError(_)))); } @@ -1755,4 +1841,65 @@ mod tests { "len=20, prefix=000102030405060708090A0B0C0D0E0F" ); } + + #[tokio::test] + async fn protocol_resolve_lock_retry_does_not_replenish_allowance() { + let versions = Arc::new(std::sync::Mutex::new(Vec::new())); + let observed = versions.clone(); + let rejection = errorpb::IncompatibleRequest { + reason: errorpb::IncompatibleRequestReason::TxnProtocolVersionOutOfRange as i32, + message: "original rejection".into(), + provided_txn_protocol_version: 1, + min_compatible_txn_protocol_version: 0, + max_compatible_txn_protocol_version: 0, + }; + let original = rejection.clone(); + let client = MockKvClient::with_dispatch_hook(move |request| { + let request = request + .downcast_ref::() + .unwrap(); + let mut sent = observed.lock().unwrap(); + sent.push(request.context.as_ref().unwrap().txn_protocol_version); + let error = if sent.len() == 2 { + errorpb::Error { + region_not_found: Some(Default::default()), + ..Default::default() + } + } else { + errorpb::Error { + incompatible_request: Some(rejection.clone()), + ..Default::default() + } + }; + Ok(Box::new(kvrpcpb::ResolveLockResponse { + region_error: Some(error), + ..Default::default() + }) as Box) + }); + let routed = client.clone(); + let pd = Arc::new( + MockPdClient::new(client).with_map_region_to_store_hook(move |region| { + let mut store = crate::store::RegionStore::new(region, Arc::new(routed.clone())); + store.meta.id = store.region_with_leader.get_store_id().unwrap(); + store.meta.txn_protocol_version_range = + Some(metapb::TxnProtocolVersionRange { min: 0, max: 1 }); + Ok(store) + }), + ); + let error = resolve_lock_with_retry( + &Key::from(vec![1]), + 1, + 2, + false, + pd, + Keyspace::Disable, + Backoff::no_jitter_backoff(1, 1, 3), + &mut HashSet::new(), + crate::TxnRequestPolicy::default(), + ) + .await + .unwrap_err(); + assert!(matches!(error, Error::IncompatibleRequest(error) if *error == original)); + assert_eq!(*versions.lock().unwrap(), vec![1, 0, 1]); + } } diff --git a/src/transaction/requests.rs b/src/transaction/requests.rs index 1c884ae60..db8cbd0e5 100644 --- a/src/transaction/requests.rs +++ b/src/transaction/requests.rs @@ -458,9 +458,15 @@ impl Merge, ) -> Result { if input.iter().any(Result::is_err) { - let (success, mut errors): (Vec<_>, Vec<_>) = - input.into_iter().partition(Result::is_ok); - let first_err = errors.pop().unwrap(); + let (success, errors): (Vec<_>, Vec<_>) = input.into_iter().partition(Result::is_ok); + // Preserve the previous last-error choice among equal priorities, + // while preventing ordinary failures from masking protocol outcomes. + let selected_error = errors + .into_iter() + .rev() + .map(Result::unwrap_err) + .min_by_key(Error::priority) + .expect("at least one shard failed"); let success_keys = success .into_iter() .map(Result::unwrap) @@ -469,7 +475,7 @@ impl Merge { rpc: Arc, options: TransactionOptions, keyspace: Keyspace, + request_policy: crate::TxnRequestPolicy, is_heartbeat_started: bool, /// Set once the transaction enters the commit path (`StartedCommit`), where /// prewrite may place 2PC locks. Kept as a dedicated flag because the status @@ -116,12 +118,23 @@ impl Transaction { rpc, options, keyspace, + request_policy: crate::TxnRequestPolicy::default(), is_heartbeat_started: false, prewritten: false, start_instant: std::time::Instant::now(), } } + pub(crate) fn with_request_policy(mut self, policy: crate::TxnRequestPolicy) -> Self { + self.request_policy = policy; + self + } + + /// Return the transactional request policy inherited from the client. + pub fn request_policy(&self) -> crate::TxnRequestPolicy { + self.request_policy + } + /// Create a new 'get' request /// /// Once resolved this request will result in the fetching of the value associated with the @@ -148,11 +161,13 @@ impl Transaction { let key = key.into().encode_keyspace(self.keyspace, KeyMode::Txn); let retry_options = self.options.retry_options.clone(); let keyspace = self.keyspace; + let request_policy = self.request_policy; self.buffer .get_or_else(key, |key| async move { let request = new_get_request(key, timestamp.clone()); let plan = PlanBuilder::new(rpc, keyspace, request) + .txn_protocol_compatibility(request_policy) .resolve_lock(timestamp, retry_options.lock_backoff, keyspace) .retry_multi_region(DEFAULT_REGION_BACKOFF) .merge(CollectSingle) @@ -279,6 +294,7 @@ impl Transaction { let timestamp = self.timestamp.clone(); let rpc = self.rpc.clone(); let keyspace = self.keyspace; + let request_policy = self.request_policy; let keys = keys .into_iter() .map(move |k| k.into().encode_keyspace(keyspace, KeyMode::Txn)); @@ -288,6 +304,7 @@ impl Transaction { .batch_get_or_else(keys, move |keys| async move { let request = new_batch_get_request(keys, timestamp.clone()); let plan = PlanBuilder::new(rpc, keyspace, request) + .txn_protocol_compatibility(request_policy) .resolve_lock(timestamp, retry_options.lock_backoff, keyspace) .retry_multi_region(retry_options.region_backoff) .merge(Collect) @@ -687,6 +704,7 @@ impl Transaction { self.rpc.clone(), self.options.clone(), self.keyspace, + self.request_policy, self.buffer.get_write_size() as u64, self.start_instant, ) @@ -756,6 +774,7 @@ impl Transaction { self.rpc.clone(), self.options.clone(), self.keyspace, + self.request_policy, self.buffer.get_write_size() as u64, self.start_instant, ) @@ -794,6 +813,7 @@ impl Transaction { self.start_instant.elapsed().as_millis() as u64 + MAX_TTL, ); let plan = PlanBuilder::new(self.rpc.clone(), self.keyspace, request) + .txn_protocol_compatibility(self.request_policy) .resolve_lock( self.timestamp.clone(), self.options.retry_options.lock_backoff.clone(), @@ -819,6 +839,7 @@ impl Transaction { let rpc = self.rpc.clone(); let retry_options = self.options.retry_options.clone(); let keyspace = self.keyspace; + let request_policy = self.request_policy; let range = range.into().encode_keyspace(self.keyspace, KeyMode::Txn); self.buffer @@ -836,6 +857,7 @@ impl Transaction { reverse, ); let plan = PlanBuilder::new(rpc, keyspace, request) + .txn_protocol_compatibility(request_policy) .resolve_lock(timestamp, retry_options.lock_backoff, keyspace) .retry_multi_region(retry_options.region_backoff) .merge(Collect) @@ -895,6 +917,7 @@ impl Transaction { need_value, ); let plan = PlanBuilder::new(self.rpc.clone(), self.keyspace, request) + .txn_protocol_compatibility(self.request_policy) .resolve_lock( self.timestamp.clone(), self.options.retry_options.lock_backoff.clone(), @@ -919,9 +942,28 @@ impl Transaction { for_update_ts.version(), ); let keys = success_keys.into_iter().map(Key::from); - self.pessimistic_lock_rollback(keys, self.timestamp.clone(), for_update_ts) - .await?; - Err(*inner) + match self + .pessimistic_lock_rollback(keys, self.timestamp.clone(), for_update_ts) + .await + { + Ok(()) => Err(*inner), + Err(rollback_error) => { + warn!( + "partial pessimistic lock rollback failed, start_ts: {}, original error: {}, rollback error: {}", + self.timestamp.version(), inner, rollback_error, + ); + // Original protocol outcomes survive cleanup failures + // unless cleanup reports a higher-priority outcome. + // Ordinary original errors retain rollback's failure. + if inner.priority() != ErrorPriority::Ordinary + && inner.priority() <= rollback_error.priority() + { + Err(*inner) + } else { + Err(rollback_error) + } + } + } } _ => Err(err), } @@ -963,6 +1005,7 @@ impl Transaction { for_update_ts, ); let plan = PlanBuilder::new(self.rpc.clone(), self.keyspace, req) + .txn_protocol_compatibility(self.request_policy) .resolve_lock( start_version, self.options.retry_options.lock_backoff.clone(), @@ -1015,6 +1058,7 @@ impl Transaction { }; let start_instant = self.start_instant; let keyspace = self.keyspace; + let request_policy = self.request_policy; debug!( "starting auto-heartbeat, start_ts: {}, interval: {:?}", self.timestamp.version(), @@ -1041,6 +1085,7 @@ impl Transaction { start_instant.elapsed().as_millis() as u64 + MAX_TTL, ); let plan = PlanBuilder::new(rpc.clone(), keyspace, request) + .txn_protocol_compatibility(request_policy) .retry_multi_region(region_backoff.clone()) .merge(CollectSingle) .plan(); @@ -1330,6 +1375,7 @@ struct Committer { rpc: Arc, options: TransactionOptions, keyspace: Keyspace, + request_policy: crate::TxnRequestPolicy, #[new(default)] undetermined: bool, write_size: u64, @@ -1441,15 +1487,17 @@ impl Committer { .collect(); // FIXME set max_commit_ts and min_commit_ts - let builder = PlanBuilder::new(self.rpc.clone(), self.keyspace, request).resolve_lock( - self.start_version.clone(), - self.options.retry_options.lock_backoff.clone(), - self.keyspace, - ); - // With async commit or 1PC this prewrite IS the commit point, so an unknown - // apply outcome must not be retried away or overwritten by a later error - // (stricter than client-go, in the safe direction; commit() classifies it). - // An ordinary 2PC prewrite retries, as client-go's does. + let builder = PlanBuilder::new(self.rpc.clone(), self.keyspace, request) + .txn_protocol_compatibility(self.request_policy) + .resolve_lock( + self.start_version.clone(), + self.options.retry_options.lock_backoff.clone(), + self.keyspace, + ); + // With async commit or 1PC this prewrite IS the commit point; commit() + // classifies an unknown apply outcome as transaction uncertainty. + // Ordinary 2PC prewrites use normal routing retries, but the compatibility + // plan also stops their send on an unknown apply outcome. let builder = if self.options.async_commit || self.options.try_one_pc { builder.retry_multi_region_terminal_on_undetermined( self.options.retry_options.region_backoff.clone(), @@ -1496,6 +1544,7 @@ impl Committer { commit_version.clone(), ); let plan = PlanBuilder::new(self.rpc.clone(), self.keyspace, req) + .txn_protocol_compatibility(self.request_policy) .resolve_lock( self.start_version.clone(), self.options.retry_options.lock_backoff.clone(), @@ -1635,6 +1684,7 @@ impl Committer { new_commit_request(keys, start_version.clone(), commit_version) }; let plan = PlanBuilder::new(self.rpc, self.keyspace, req) + .txn_protocol_compatibility(self.request_policy) .resolve_lock( start_version, self.options.retry_options.lock_backoff, @@ -1682,11 +1732,13 @@ impl Committer { let region_backoff = self.options.retry_options.region_backoff.clone(); let rpc = self.rpc; let keyspace = self.keyspace; + let request_policy = self.request_policy; match self.options.kind { TransactionKind::Pessimistic(for_update_ts) if !prewritten => { let req = new_pessimistic_rollback_request(keys, start_version.clone(), for_update_ts); let plan = PlanBuilder::new(rpc, keyspace, req) + .txn_protocol_compatibility(request_policy) .resolve_lock(start_version, lock_backoff, keyspace) .retry_multi_region(region_backoff) .extract_error() @@ -1698,6 +1750,7 @@ impl Committer { _ => { let req = new_batch_rollback_request(keys, start_version.clone()); let plan = PlanBuilder::new(rpc, keyspace, req) + .txn_protocol_compatibility(request_policy) .resolve_lock(start_version, lock_backoff, keyspace) .retry_multi_region(region_backoff) .extract_error() @@ -1768,6 +1821,7 @@ impl From for TransactionStatus { #[cfg(test)] mod tests { + use crate::common::ErrorPriority; use std::any::Any; use std::io; use std::sync::atomic::AtomicUsize; @@ -1966,4 +2020,152 @@ mod tests { }) ))); } + + #[derive(Clone, Copy)] + enum LockRollbackOutcome { + Success, + Grpc, + Incompatible, + Undetermined, + } + + #[rstest::rstest] + #[case(ErrorPriority::Incompatible, LockRollbackOutcome::Success, true)] + #[case(ErrorPriority::Incompatible, LockRollbackOutcome::Grpc, true)] + #[case(ErrorPriority::Incompatible, LockRollbackOutcome::Incompatible, true)] + #[case(ErrorPriority::Incompatible, LockRollbackOutcome::Undetermined, false)] + #[case(ErrorPriority::Undetermined, LockRollbackOutcome::Success, true)] + #[case(ErrorPriority::Undetermined, LockRollbackOutcome::Grpc, true)] + #[case(ErrorPriority::Undetermined, LockRollbackOutcome::Incompatible, true)] + #[case(ErrorPriority::Undetermined, LockRollbackOutcome::Undetermined, true)] + #[case(ErrorPriority::Ordinary, LockRollbackOutcome::Success, true)] + #[case(ErrorPriority::Ordinary, LockRollbackOutcome::Grpc, false)] + #[case(ErrorPriority::Ordinary, LockRollbackOutcome::Incompatible, false)] + #[case(ErrorPriority::Ordinary, LockRollbackOutcome::Undetermined, false)] + #[tokio::test] + async fn partial_pessimistic_lock_preserves_error_priority_after_rollback( + #[case] original_priority: ErrorPriority, + #[case] rollback: LockRollbackOutcome, + #[case] preserve_original: bool, + ) { + fn region_error(priority: ErrorPriority, message: &str) -> crate::proto::errorpb::Error { + let mut error = crate::proto::errorpb::Error { + message: message.into(), + ..Default::default() + }; + match priority { + ErrorPriority::Undetermined => error.undetermined_result = Some(Default::default()), + ErrorPriority::Incompatible => { + error.incompatible_request = Some(crate::proto::errorpb::IncompatibleRequest { + message: message.into(), + ..Default::default() + }); + } + ErrorPriority::Ordinary => unreachable!(), + } + error + } + + let lock_keys = Arc::new(Mutex::new(Vec::new())); + let locked = lock_keys.clone(); + let rollback_keys = Arc::new(Mutex::new(Vec::new())); + let rolled_back = rollback_keys.clone(); + let client = MockKvClient::with_dispatch_hook(move |request| { + if let Some(request) = request.downcast_ref::() { + let keys = request + .mutations + .iter() + .map(|m| m.key.clone()) + .collect::>(); + locked.lock().unwrap().extend(keys.clone()); + assert_eq!(keys.len(), 1); + let mut response = kvrpcpb::PessimisticLockResponse::default(); + if keys[0] == vec![11] { + if original_priority == ErrorPriority::Ordinary { + response.errors.push(kvrpcpb::KeyError { + abort: "original lock error".into(), + ..Default::default() + }); + } else { + response.region_error = + Some(region_error(original_priority, "original lock error")); + } + } else { + assert_eq!(keys[0], vec![1]); + } + return Ok(Box::new(response) as Box); + } + let request = request + .downcast_ref::() + .expect("expected a rollback of the successfully locked shard"); + rolled_back.lock().unwrap().push(request.keys.clone()); + let mut response = kvrpcpb::PessimisticRollbackResponse::default(); + match rollback { + LockRollbackOutcome::Success => {} + LockRollbackOutcome::Grpc => { + return Err(crate::Error::GrpcAPI(tonic::Status::unavailable( + "rollback error", + ))); + } + LockRollbackOutcome::Incompatible => { + response.region_error = + Some(region_error(ErrorPriority::Incompatible, "rollback error")); + } + LockRollbackOutcome::Undetermined => { + response.region_error = + Some(region_error(ErrorPriority::Undetermined, "rollback error")); + } + } + Ok(Box::new(response) as Box) + }); + let mut txn = Transaction::new( + Timestamp::from_version(123), + Arc::new(MockPdClient::new(client)), + TransactionOptions::new_pessimistic() + .no_resolve_locks() + .no_resolve_regions() + .heartbeat_option(HeartbeatOption::NoHeartbeat) + .drop_check(super::CheckLevel::None), + Keyspace::Disable, + ); + let error = txn.lock_keys([vec![1], vec![11]]).await.unwrap_err(); + + let expected_message = if preserve_original { + "original lock error" + } else { + "rollback error" + }; + let expected_priority = if preserve_original { + original_priority + } else { + match rollback { + LockRollbackOutcome::Grpc => ErrorPriority::Ordinary, + LockRollbackOutcome::Incompatible => ErrorPriority::Incompatible, + LockRollbackOutcome::Undetermined => ErrorPriority::Undetermined, + LockRollbackOutcome::Success => unreachable!(), + } + }; + assert_eq!(error.priority(), expected_priority); + match error { + crate::Error::IncompatibleRequest(error) => assert_eq!(error.message, expected_message), + crate::Error::RegionError(error) => { + assert!(error.undetermined_result.is_some()); + assert_eq!(error.message, expected_message); + } + crate::Error::GrpcAPI(status) => { + assert_eq!(status.code(), tonic::Code::Unavailable); + assert_eq!(status.message(), expected_message); + } + crate::Error::MultipleKeyErrors(errors) => { + assert_eq!(errors.len(), 1); + assert!(matches!(&errors[0], crate::Error::KeyError(error) + if error.abort == expected_message)); + } + error => panic!("unexpected error: {error:?}"), + } + let mut keys = lock_keys.lock().unwrap().clone(); + keys.sort(); + assert_eq!(keys, vec![vec![1], vec![11]]); + assert_eq!(*rollback_keys.lock().unwrap(), vec![vec![vec![1]]]); + } } diff --git a/src/transaction/transaction/scanner.rs b/src/transaction/transaction/scanner.rs index 67959f30d..12d17d305 100644 --- a/src/transaction/transaction/scanner.rs +++ b/src/transaction/transaction/scanner.rs @@ -2,7 +2,7 @@ use std::cmp::Ordering; use std::sync::atomic; -use std::sync::atomic::AtomicU8; +use std::sync::atomic::{AtomicBool, AtomicU8}; use std::sync::Arc; use log::debug; @@ -130,6 +130,7 @@ struct RemoteScanner { status: Arc, pd_client: Arc, keyspace: Keyspace, + request_policy: crate::TxnRequestPolicy, timestamp: Timestamp, retry_options: RetryOptions, end: Option, @@ -263,6 +264,7 @@ impl RemoteScanner { status: txn.status.clone(), pd_client: txn.rpc.clone(), keyspace: txn.keyspace, + request_policy: txn.request_policy, timestamp: txn.timestamp.clone(), retry_options: txn.options.retry_options.clone(), end, @@ -322,6 +324,8 @@ impl RemoteScanner { self.check_allow_operation()?; let keyspace = self.keyspace; let mut region_backoff = self.retry_options.region_backoff.clone(); + // One allowance per page, preserved across location and transport retries. + let allowance = Arc::new(AtomicBool::new(false)); loop { let range: BoundRange = (self.next_start.clone(), self.end.clone()).into(); @@ -379,6 +383,7 @@ impl RemoteScanner { false, ); let plan = match PlanBuilder::new(self.pd_client.clone(), keyspace, request) + .txn_protocol_compatibility_with_allowance(self.request_policy, allowance.clone()) .single_region_with_store(region_store.clone()) .await { @@ -1096,4 +1101,59 @@ mod tests { txn.rollback().await.unwrap(); } + + #[tokio::test] + async fn protocol_scanner_page_retry_does_not_replenish_allowance() { + let versions = Arc::new(Mutex::new(Vec::new())); + let observed = versions.clone(); + let rejection = errorpb::IncompatibleRequest { + reason: errorpb::IncompatibleRequestReason::TxnProtocolVersionOutOfRange as i32, + message: "original rejection".into(), + provided_txn_protocol_version: 1, + min_compatible_txn_protocol_version: 0, + max_compatible_txn_protocol_version: 0, + }; + let original = rejection.clone(); + let client = MockKvClient::with_dispatch_hook(move |request| { + let request = request.downcast_ref::().unwrap(); + let mut sent = observed.lock().unwrap(); + sent.push(request.context.as_ref().unwrap().txn_protocol_version); + let error = if sent.len() == 2 { + errorpb::Error { + region_not_found: Some(Default::default()), + ..Default::default() + } + } else { + errorpb::Error { + incompatible_request: Some(rejection.clone()), + ..Default::default() + } + }; + Ok(Box::new(kvrpcpb::ScanResponse { + region_error: Some(error), + ..Default::default() + }) as Box) + }); + let routed = client.clone(); + let pd = Arc::new( + MockPdClient::new(client).with_map_region_to_store_hook(move |region| { + let mut store = RegionStore::new(region, Arc::new(routed.clone())); + store.meta.id = store.region_with_leader.get_store_id().unwrap(); + store.meta.txn_protocol_version_range = + Some(metapb::TxnProtocolVersionRange { min: 0, max: 1 }); + Ok(store) + }), + ); + let mut txn = Transaction::new( + Timestamp::default(), + pd, + TransactionOptions::new_optimistic().drop_check(super::super::CheckLevel::None), + Keyspace::Disable, + ); + let Err(error) = txn.scanner(..).await else { + panic!("expected exhausted page allowance") + }; + assert!(matches!(error, crate::Error::IncompatibleRequest(error) if *error == original)); + assert_eq!(*versions.lock().unwrap(), vec![1, 0, 1]); + } } From 28003153c05b364e090df0a5f3e2eb0d56ff72a5 Mon Sep 17 00:00:00 2001 From: zyguan Date: Wed, 4 Nov 2026 21:38:40 +0000 Subject: [PATCH 2/5] request: preserve retry policy for undetermined transaction responses Signed-off-by: zyguan --- src/request/plan.rs | 166 +++++++++++++++++++++++++++++++++++++------- 1 file changed, 141 insertions(+), 25 deletions(-) diff --git a/src/request/plan.rs b/src/request/plan.rs index b18a3be80..dae9591c7 100644 --- a/src/request/plan.rs +++ b/src/request/plan.rs @@ -213,19 +213,13 @@ impl Plan for TxnProtocolCompatibility let Some(error) = response.region_error_ref() else { return Ok(response); }; - let undetermined = error.undetermined_result.is_some(); - if !undetermined && error.incompatible_request.is_none() { + // Leave unknown apply outcomes to the retry plan's terminal policy. + if error.undetermined_result.is_some() || error.incompatible_request.is_none() { return Ok(response); } let error = response .region_error() .expect("region error was just inspected"); - // An unknown apply outcome stops this send before compatibility, - // lock-resolution, or region retry handling. Preserve the complete - // envelope so the transaction layer can classify commit uncertainty. - if undetermined { - return Err(Error::RegionError(Box::new(error))); - } let rejection = error .incompatible_request .expect("incompatible request was just inspected"); @@ -959,6 +953,20 @@ where used_fallback, } = response; + if region_error + .as_ref() + .is_some_and(|error| error.undetermined_result.is_some()) + { + return Self::handle_region_response( + context, + plan, + region.ver_id(), + region_store, + backoff, + region_error.unwrap(), + ) + .await; + } if let Some(error) = key_errors { debug!("single_shard_handler:execute: key errors: {:?}", error); return Ok(vec![Err(Error::MultipleKeyErrors(error))]); @@ -1430,7 +1438,7 @@ impl Clone for ResolveLock { #[async_trait] impl Plan for ResolveLock where - P::Result: HasLocks, + P::Result: HasLocks + HasRegionError, { type Result = P::Result; @@ -1438,6 +1446,9 @@ where let mut result = self.inner.execute().await?; let mut clone = self.clone(); loop { + if result.region_error_ref().is_some() { + return Ok(result); + } let locks = result.take_locks(); if locks.is_empty() { return Ok(result); @@ -1563,13 +1574,10 @@ where let mut scan_lock_resp = inner.execute().await?; // Propagate errors to `retry_multi_region` for retry. - if let Some(e) = scan_lock_resp.key_errors() { - info!("CleanupLocks::execute, inner key errors:{:?}", e); - result.key_error = Some(e); - return Ok(result); - } else if let Some(e) = scan_lock_resp.region_error() { - info!("CleanupLocks::execute, inner region error:{}", e.message); - result.region_error = Some(e); + result.region_error = scan_lock_resp.region_error(); + result.key_error = scan_lock_resp.key_errors(); + if result.region_error.is_some() || result.key_error.is_some() { + info!("CleanupLocks::execute, inner errors:{:?}", result); return Ok(result); } @@ -2629,8 +2637,16 @@ mod test { } } + #[rstest::rstest] + #[case(false, true, 2)] + #[case(false, false, 4)] + #[case(true, true, 1)] #[tokio::test] - async fn protocol_undetermined_envelope_stops_before_other_errors_or_retries() { + async fn protocol_undetermined_envelope_obeys_retry_policy( + #[case] terminal: bool, + #[case] recover: bool, + #[case] expected_calls: usize, + ) { let original = errorpb::Error { message: "unknown apply outcome".into(), undetermined_result: Some(Default::default()), @@ -2642,12 +2658,27 @@ mod test { let envelope = original.clone(); let calls = Arc::new(AtomicUsize::new(0)); let observed = calls.clone(); - let client = crate::mock::MockKvClient::with_dispatch_hook(move |_| { - observed.fetch_add(1, Ordering::SeqCst); + let client = crate::mock::MockKvClient::with_dispatch_hook(move |request| { + // Lock resolution and compatibility recovery must not handle this + // mixed response before the retry policy sees the unknown outcome. + let request = request.downcast_ref::().unwrap(); + assert_eq!(request.context.as_ref().unwrap().txn_protocol_version, 1); + let call = observed.fetch_add(1, Ordering::SeqCst); + if recover && call > 0 { + return Ok(Box::new(kvrpcpb::GetResponse { + value: b"recovered".to_vec(), + ..Default::default() + })); + } Ok(Box::new(kvrpcpb::GetResponse { region_error: Some(envelope.clone()), error: Some(kvrpcpb::KeyError { abort: "must not mask unknown outcome".into(), + locked: Some(kvrpcpb::LockInfo { + key: vec![1], + primary_lock: vec![1], + ..Default::default() + }), ..Default::default() }), ..Default::default() @@ -2676,14 +2707,24 @@ mod test { Timestamp::default(), Backoff::no_jitter_backoff(1, 1, 3), Keyspace::Disable, - ) - .retry_multi_region(Backoff::no_jitter_backoff(1, 1, 3)) + ); + let backoff = Backoff::no_jitter_backoff(1, 1, 3); + let plan = if terminal { + plan.retry_multi_region_terminal_on_undetermined(backoff) + } else { + plan.retry_multi_region(backoff) + } .plan(); - let Err(Error::RegionError(error)) = plan.execute().await else { - panic!("expected original unknown outcome") + let result = plan.execute().await; + if recover && !terminal { + assert_eq!(result.unwrap().pop().unwrap().unwrap().value, b"recovered"); + } else { + let Err(Error::RegionError(error)) = result else { + panic!("expected original unknown outcome") + }; + assert_eq!(*error, original); }; - assert_eq!(*error, original); - assert_eq!(calls.load(Ordering::SeqCst), 1); + assert_eq!(calls.load(Ordering::SeqCst), expected_calls); } #[tokio::test] @@ -3144,6 +3185,81 @@ mod test { assert!(failed.region_error().is_none()); assert!(matches!(failed, Err(Error::Unimplemented))); } + #[rstest::rstest] + #[case(false)] + #[case(true)] + #[tokio::test] + async fn protocol_cleanup_undetermined_response_reaches_retry_policy(#[case] recover: bool) { + let original = errorpb::Error { + undetermined_result: Some(Default::default()), + incompatible_request: Some(admission_rejection()), + ..Default::default() + }; + let envelope = original.clone(); + let calls = Arc::new(AtomicUsize::new(0)); + let observed = calls.clone(); + let client = crate::mock::MockKvClient::with_dispatch_hook(move |request| { + let request = request.downcast_ref::().unwrap(); + assert_eq!(request.context.as_ref().unwrap().txn_protocol_version, 1); + let call = observed.fetch_add(1, Ordering::SeqCst); + if recover && call > 0 { + return Ok(Box::new(kvrpcpb::ScanLockResponse::default())); + } + Ok(Box::new(kvrpcpb::ScanLockResponse { + region_error: Some(envelope.clone()), + error: Some(kvrpcpb::KeyError { + abort: "must not mask unknown outcome".into(), + ..Default::default() + }), + locks: vec![kvrpcpb::LockInfo { + key: vec![1], + primary_lock: vec![1], + ..Default::default() + }], + ..Default::default() + })) + }); + let routed = client.clone(); + let pd = Arc::new( + MockPdClient::new(client) + .with_map_region_to_store_hook(move |region| { + let mut store = protocol_store(routed.clone(), Some((0, 1))); + store.region_with_leader = region; + Ok(store) + }) + .with_invalidate_region_hook(|_| panic!("unknown outcome invalidated routing")), + ); + let plan = crate::request::PlanBuilder::new( + pd, + Keyspace::Disable, + kvrpcpb::ScanLockRequest { + start_key: vec![1], + end_key: vec![9], + limit: 1, + ..Default::default() + }, + ) + .txn_protocol_compatibility(crate::TxnRequestPolicy::default()) + .cleanup_locks( + crate::transaction::ResolveLocksContext::default(), + crate::transaction::ResolveLocksOptions::default(), + Backoff::no_backoff(), + Keyspace::Disable, + ) + .retry_multi_region(Backoff::no_jitter_backoff(1, 1, 1)) + .plan(); + let result = plan.execute().await; + if recover { + assert!(result.unwrap().iter().all(Result::is_ok)); + } else { + let Err(Error::RegionError(error)) = result else { + panic!("expected original unknown outcome") + }; + assert_eq!(*error, original); + } + assert_eq!(calls.load(Ordering::SeqCst), 2); + } + #[rstest::rstest] #[case(false)] #[case(true)] From b1e8dd702f6a579e79f00499a2db9bbe13bbbe34 Mon Sep 17 00:00:00 2001 From: zyguan Date: Wed, 4 Nov 2026 22:53:00 +0000 Subject: [PATCH 3/5] request: preserve explicit transaction request origins Signed-off-by: zyguan --- src/config.rs | 2 +- src/request/plan.rs | 63 ++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 63 insertions(+), 2 deletions(-) diff --git a/src/config.rs b/src/config.rs index 51b821596..018cd9271 100644 --- a/src/config.rs +++ b/src/config.rs @@ -14,7 +14,7 @@ pub use crate::proto::kvrpcpb::{RequestOrigin, TxnProtocolVersion}; /// supported version; transactional client construction validates [`Config`]. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub struct TxnRequestPolicy { - /// Product identity for auditing. + /// Default product identity for auditing, applied when the request origin is `Unknown`. pub origin: RequestOrigin, /// Configured version; each destination may select a lower compatible version. pub protocol_version: TxnProtocolVersion, diff --git a/src/request/plan.rs b/src/request/plan.rs index dae9591c7..11e19a3af 100644 --- a/src/request/plan.rs +++ b/src/request/plan.rs @@ -207,7 +207,9 @@ impl Plan for TxnProtocolCompatibility let mut dispatch = self.inner.clone(); loop { let context = dispatch.request.context_mut(); - context.request_origin = self.policy.origin as i32; + if context.request_origin == crate::RequestOrigin::Unknown as i32 { + context.request_origin = self.policy.origin as i32; + } context.txn_protocol_version = version; let mut response = dispatch.execute().await?; let Some(error) = response.region_error_ref() else { @@ -1816,6 +1818,7 @@ mod test { use super::*; use crate::mock::MockPdClient; use crate::proto::kvrpcpb::BatchGetResponse; + use crate::RequestOrigin; #[test] fn grpc_statuses_are_classified_without_cache_churn_for_deadlines() { @@ -2553,6 +2556,64 @@ mod test { } } + #[rstest::rstest] + #[case(None, RequestOrigin::TiFlash, 4)] + #[case(Some(RequestOrigin::Unknown as i32), RequestOrigin::TiFlash, 4)] + #[case(Some(RequestOrigin::TiDb as i32), RequestOrigin::TiFlash, 1)] + #[case(Some(RequestOrigin::TiDb as i32), RequestOrigin::Unknown, 1)] + #[case(Some(42), RequestOrigin::TiFlash, 42)] + #[case(Some(RequestOrigin::Unknown as i32), RequestOrigin::Unknown, 0)] + #[tokio::test] + async fn protocol_origin_defaults_only_unknown_through_resend( + #[case] request_origin: Option, + #[case] policy_origin: RequestOrigin, + #[case] expected_origin: i32, + ) { + let versions = Arc::new(std::sync::Mutex::new(Vec::new())); + let observed = versions.clone(); + let client = crate::mock::MockKvClient::with_dispatch_hook(move |request| { + let context = request + .downcast_ref::() + .unwrap() + .context + .as_ref() + .unwrap(); + assert_eq!(context.request_origin, expected_origin); + let mut sent = observed.lock().unwrap(); + sent.push(context.txn_protocol_version); + Ok(Box::new(kvrpcpb::GetResponse { + region_error: (sent.len() == 1).then(|| errorpb::Error { + incompatible_request: Some(admission_rejection()), + ..Default::default() + }), + ..Default::default() + })) + }); + let plan = crate::request::PlanBuilder::new( + Arc::new(MockPdClient::default()), + Keyspace::Disable, + kvrpcpb::GetRequest { + context: request_origin.map(|request_origin| kvrpcpb::Context { + request_origin, + // Caller-supplied versions must still be replaced per attempt. + txn_protocol_version: 2, + ..Default::default() + }), + ..Default::default() + }, + ) + .txn_protocol_compatibility(crate::TxnRequestPolicy { + origin: policy_origin, + ..Default::default() + }) + .single_region_with_store(protocol_store(client, Some((0, 1)))) + .await + .unwrap() + .plan(); + assert!(plan.execute().await.is_ok()); + assert_eq!(*versions.lock().unwrap(), vec![1, 0]); + } + #[rstest::rstest] #[case("upper", true)] #[case("unknown_reason", false)] From 2e764bf37ee766ca8024f4c60adf076a3daa0e4a Mon Sep 17 00:00:00 2001 From: zyguan Date: Thu, 5 Nov 2026 03:30:28 +0000 Subject: [PATCH 4/5] transaction: retry undetermined lock resolution results Signed-off-by: zyguan --- src/request/plan.rs | 99 ++++++++++++++++++++++++++++++++++++++--- src/transaction/lock.rs | 84 +++++++++++++++++++++++++++------- 2 files changed, 161 insertions(+), 22 deletions(-) diff --git a/src/request/plan.rs b/src/request/plan.rs index 11e19a3af..91c1d08dd 100644 --- a/src/request/plan.rs +++ b/src/request/plan.rs @@ -1625,13 +1625,11 @@ where Ok(()) => { result.resolved_locks += lock_size; } - // Propagate errors to `retry_multi_region` for retry. The variant now - // says which kind arrived, so neither arm has to pop an element to find - // out. That also fixes a real leak in the old single-variant code: it - // 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. + // Propagate both direct and wrapped region errors to the retry plan. + Err(Error::RegionError(e)) => { + result.region_error = Some(*e); + return Ok(result); + } Err(Error::MultipleRegionErrors(mut errors)) => { if let Some(Error::RegionError(e)) = errors.pop() { result.region_error = Some(*e); @@ -3321,6 +3319,93 @@ mod test { assert_eq!(calls.load(Ordering::SeqCst), 2); } + #[rstest::rstest] + #[case(false)] + #[case(true)] + #[tokio::test] + async fn cleanup_retries_undetermined_batch_resolve_results(#[case] recover: bool) { + let original = errorpb::Error { + message: "unknown batch resolve outcome".into(), + undetermined_result: Some(Default::default()), + incompatible_request: Some(admission_rejection()), + region_not_found: Some(Default::default()), + ..Default::default() + }; + let envelope = original.clone(); + let calls = Arc::new(AtomicUsize::new(0)); + let observed = calls.clone(); + let client = crate::mock::MockKvClient::with_dispatch_hook(move |request| { + if request.is::() { + return Ok(Box::new(kvrpcpb::ScanLockResponse { + locks: vec![kvrpcpb::LockInfo { + key: vec![1], + primary_lock: vec![1], + lock_version: 1, + ..Default::default() + }], + ..Default::default() + })); + } + if request.is::() { + return Ok(Box::new(kvrpcpb::CheckTxnStatusResponse::default())); + } + let request = request + .downcast_ref::() + .unwrap(); + assert_eq!(request.txn_infos.len(), 1); + assert_eq!(request.txn_infos[0].txn, 1); + let call = observed.fetch_add(1, Ordering::SeqCst); + Ok(Box::new(kvrpcpb::ResolveLockResponse { + region_error: (!recover || call == 0).then(|| envelope.clone()), + ..Default::default() + })) + }); + let pd = Arc::new( + MockPdClient::new(client) + .with_invalidate_region_hook(|_| panic!("unknown outcome invalidated routing")), + ); + let ctx = crate::transaction::ResolveLocksContext::default(); + let plan = crate::request::PlanBuilder::new( + pd, + Keyspace::Disable, + kvrpcpb::ScanLockRequest { + start_key: vec![1], + end_key: vec![9], + limit: 2, + ..Default::default() + }, + ) + .txn_protocol_compatibility(crate::TxnRequestPolicy::default()) + .cleanup_locks( + ctx.clone(), + crate::transaction::ResolveLocksOptions::default(), + Backoff::no_backoff(), + Keyspace::Disable, + ) + .retry_multi_region(Backoff::no_jitter_backoff(0, 0, 1)) + .plan(); + let result = plan.execute().await; + if recover { + let results = result.unwrap(); + assert_eq!(results.len(), 1); + assert_eq!( + results.into_iter().next().unwrap().unwrap().resolved_locks, + 1 + ); + } else { + let Err(Error::RegionError(error)) = result else { + panic!("expected original unknown outcome") + }; + assert_eq!(*error, original); + } + assert_eq!(calls.load(Ordering::SeqCst), 2); + assert_eq!( + ctx.is_region_cleaned(1, &MockPdClient::region1().ver_id()) + .await, + recover + ); + } + #[rstest::rstest] #[case(false)] #[case(true)] diff --git a/src/transaction/lock.rs b/src/transaction/lock.rs index d334e65d8..3b4ef706c 100644 --- a/src/transaction/lock.rs +++ b/src/transaction/lock.rs @@ -270,26 +270,15 @@ async fn resolve_lock_with_retry( Err(err) => return Err(err), }; let plan = plan_builder.extract_error().plan(); - match plan.execute().await { + let region_error = match plan.execute().await { Ok(_) => { clean_regions.insert(ver_id); return Ok(()); } - // Retry on region error. `ResolveLockResponse` can have at most 1 error, and - // the variant now says which kind it is rather than requiring a type test on - // a popped element. + // ExtractError returns priority region errors directly and wraps ordinary ones. + Err(Error::RegionError(e)) => e, Err(Error::MultipleRegionErrors(mut errors)) => match errors.pop() { - Some(Error::RegionError(e)) => match backoff.next_delay_duration() { - Some(duration) => { - let region_error_resolved = - handle_region_error(pd_client.clone(), *e, store.clone()).await?; - if !region_error_resolved { - sleep(duration).await; - } - continue; - } - None => return Err(Error::RegionError(e)), - }, + Some(Error::RegionError(e)) => e, Some(e) => return Err(e), None => unreachable!(), }, @@ -321,6 +310,16 @@ async fn resolve_lock_with_retry( None => return Err(e), }, Err(e) => return Err(e), + }; + match backoff.next_delay_duration() { + Some(duration) => { + let region_error_resolved = + handle_region_error(pd_client.clone(), *region_error, store).await?; + if !region_error_resolved { + sleep(duration).await; + } + } + None => return Err(Error::RegionError(region_error)), } } } @@ -1842,6 +1841,61 @@ mod tests { ); } + #[rstest::rstest] + #[case(true)] + #[case(false)] + #[tokio::test] + async fn resolve_lock_retries_undetermined_results(#[case] recover: bool) { + let original = errorpb::Error { + message: "unknown resolve outcome".into(), + undetermined_result: Some(Default::default()), + incompatible_request: Some(Default::default()), + region_not_found: Some(Default::default()), + ..Default::default() + }; + let envelope = original.clone(); + let calls = Arc::new(AtomicUsize::new(0)); + let observed = calls.clone(); + let client = Arc::new( + MockPdClient::new(MockKvClient::with_dispatch_hook(move |request| { + assert!(request.is::()); + let call = observed.fetch_add(1, Ordering::SeqCst); + Ok(Box::new(kvrpcpb::ResolveLockResponse { + region_error: (!recover || call == 0).then(|| envelope.clone()), + ..Default::default() + }) as Box) + })) + .with_invalidate_region_hook(|_| panic!("unknown outcome invalidated routing")), + ); + let mut clean_regions = HashSet::new(); + let result = resolve_lock_with_retry( + &Key::from(vec![1]), + 1, + 2, + false, + client, + Keyspace::Disable, + Backoff::no_jitter_backoff(0, 0, 1), + &mut clean_regions, + crate::TxnRequestPolicy::default(), + ) + .await; + if recover { + result.unwrap(); + assert_eq!( + clean_regions, + HashSet::from([MockPdClient::region1().ver_id()]) + ); + } else { + let Err(Error::RegionError(error)) = result else { + panic!("expected original unknown outcome") + }; + assert_eq!(*error, original); + assert!(clean_regions.is_empty()); + } + assert_eq!(calls.load(Ordering::SeqCst), 2); + } + #[tokio::test] async fn protocol_resolve_lock_retry_does_not_replenish_allowance() { let versions = Arc::new(std::sync::Mutex::new(Vec::new())); From 622f2ed19adb45b86db37d08b564b9bee7b461a8 Mon Sep 17 00:00:00 2001 From: zyguan Date: Thu, 5 Nov 2026 04:01:16 +0000 Subject: [PATCH 5/5] request: cover cleanup batch resend allowance boundaries Signed-off-by: zyguan --- src/request/plan.rs | 127 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 127 insertions(+) diff --git a/src/request/plan.rs b/src/request/plan.rs index 91c1d08dd..82dc7c44f 100644 --- a/src/request/plan.rs +++ b/src/request/plan.rs @@ -3406,6 +3406,133 @@ mod test { ); } + #[rstest::rstest] + #[case(true, 1)] + #[case(false, 2)] + #[case(false, 0)] + #[tokio::test] + async fn protocol_cleanup_rebuilt_batches_get_fresh_allowances( + #[case] recover: bool, + #[case] retries: u32, + ) { + let routing_error = errorpb::Error { + message: "retry the cleanup batch".into(), + region_not_found: Some(Default::default()), + ..Default::default() + }; + let envelope = routing_error.clone(); + let attempts = if recover { 2 } else { retries as usize + 1 }; + let versions = Arc::new(std::sync::Mutex::new(Vec::new())); + let observed_versions = versions.clone(); + let scan_starts = Arc::new(std::sync::Mutex::new(Vec::new())); + let observed_starts = scan_starts.clone(); + let client = crate::mock::MockKvClient::with_dispatch_hook(move |request| { + if let Some(request) = request.downcast_ref::() { + observed_starts + .lock() + .unwrap() + .push(request.start_key.clone()); + return Ok(Box::new(kvrpcpb::ScanLockResponse { + locks: vec![kvrpcpb::LockInfo { + key: vec![1], + primary_lock: vec![1], + lock_version: 1, + ..Default::default() + }], + ..Default::default() + })); + } + if request.is::() { + return Ok(Box::new(kvrpcpb::CheckTxnStatusResponse::default())); + } + let request = request + .downcast_ref::() + .unwrap(); + assert_eq!(request.txn_infos.len(), 1); + assert_eq!(request.txn_infos[0].txn, 1); + assert_eq!(request.txn_infos[0].status, 0); + let version = request.context.as_ref().unwrap().txn_protocol_version; + let mut sent = observed_versions.lock().unwrap(); + sent.push(version); + assert!( + sent.len() <= attempts * 2, + "cleanup exceeded its retry budget" + ); + let error = if version == 1 { + Some(errorpb::Error { + incompatible_request: Some(admission_rejection()), + ..Default::default() + }) + } else if recover && sent.len() == 4 { + None + } else { + Some(envelope.clone()) + }; + Ok(Box::new(kvrpcpb::ResolveLockResponse { + region_error: error, + ..Default::default() + })) + }); + let routed = client.clone(); + let invalidations = Arc::new(AtomicUsize::new(0)); + let invalidated = invalidations.clone(); + let pd = Arc::new( + MockPdClient::new(client) + .with_map_region_to_store_hook(move |region| { + let mut store = protocol_store(routed.clone(), Some((0, 1))); + store.region_with_leader = region; + Ok(store) + }) + .with_invalidate_region_hook(move |_| { + invalidated.fetch_add(1, Ordering::SeqCst); + }), + ); + let ctx = crate::transaction::ResolveLocksContext::default(); + let plan = crate::request::PlanBuilder::new( + pd, + Keyspace::Disable, + kvrpcpb::ScanLockRequest { + start_key: vec![1], + end_key: vec![9], + limit: 2, + ..Default::default() + }, + ) + .txn_protocol_compatibility(crate::TxnRequestPolicy::default()) + .cleanup_locks( + ctx.clone(), + crate::transaction::ResolveLocksOptions::default(), + Backoff::no_backoff(), + Keyspace::Disable, + ) + .retry_multi_region(Backoff::no_jitter_backoff(0, 0, retries)) + .plan(); + let result = plan.execute().await; + if recover { + let results = result.unwrap(); + assert_eq!(results.len(), 1); + assert_eq!( + results.into_iter().next().unwrap().unwrap().resolved_locks, + 1 + ); + } else { + let Err(Error::RegionError(error)) = result else { + panic!("expected the routing error after exhausting cleanup retries") + }; + assert_eq!(*error, routing_error); + } + // Outer cleanup rebuilds the same page and transaction batch. Each new + // batch send gets one compatibility resend, matching client-go's SendReq. + assert_eq!(*versions.lock().unwrap(), [1, 0].repeat(attempts)); + assert_eq!(*scan_starts.lock().unwrap(), vec![vec![1]; attempts]); + assert_eq!(invalidations.load(Ordering::SeqCst), attempts - 1); + assert_eq!( + ctx.is_region_cleaned(1, &MockPdClient::region1().ver_id()) + .await, + recover + ); + } + #[rstest::rstest] #[case(false)] #[case(true)]