github.com/matrixorigin/matrixone@v1.2.0/proto/txn.proto

/* 
 * Copyright 2021 Matrix Origin
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

syntax = "proto3";
package txn; 
option go_package = "github.com/matrixorigin/matrixone/pkg/pb/txn";

import "github.com/gogo/protobuf/gogoproto/gogo.proto";
import "timestamp.proto";
import "metadata.proto";
import "lock.proto";

option (gogoproto.goproto_enum_prefix_all) = true;

// TxnIsolation txn txn isolation
enum TxnIsolation {
    // SI snapshot isolation
    SI = 0;
    // RC read committed
    RC = 1;
}

// TxnMode txn mode
enum TxnMode {
    // Optimistic check conflict on commit.
    Optimistic    = 0;
    // Pessimistic check conflict every write
    Pessimistic = 1;
}

// TxnStatus transaction status
enum TxnStatus {
    // Active is the state of transaction creation, in this state, can execute the 
    // transaction Read/Write/Commit/Rollback.
    Active = 0;
    // Prepared for distributed transactions across TNs, a 2pc commit is performed, 
    // and the prepared status means that the transaction on a TN was executed 
    // successfully in the first phase. 
    // 
    // Note that this status needs to be saved to the LogService. Once the first 
    // phase of a transaction is successful, data cannot be lost.
    Prepared = 1;
    // Committing for distributed transactions across TNs, once all TNs have completed
    // the first phase, the transaction enters the Committing state and initiates an 
    // asynchronous process to handle the commit of temporary data.
    //
    // Note that when all TNs involved are in the prepared state, the distributed 
    // transaction can be considered committed because all data has been written 
    // successfully. The subsequent Committing process just explicitly converts these
    // writes into committed data.
    //
    // Note that the state exists only in memory and is not persisted to the LogService.
    // It can be restored through the Prepared state, if all(TN).Status == Prepared.
    Committing = 2;
    // Committed after the Committing phase has transformed all TN data involved into 
    // committed data, the status of the distributed transaction is explicitly recorded 
    // as Committed.
    //
    // Note that this status needs to be saved to the LogService
    Committed = 3;
    // Aborting a client initiating a Rollback call or a distributed transaction that has
    // any error in the first phase will enter the Aborting state. This state starts an 
    // asynchronous task to clean up the temporary data written by the transaction.
    //
    // Note that the state exists only in memory and is not persisted to the LogService.
    // It can be restored through the Prepared state, if Any(TN).Status != Prepared.
    Aborting  = 4;
    // Aborted after the Aborting phase, all data involved in the TN is cleaned up and 
    // the transaction status is explicitly recorded as Aborted.
    //
    // Note that this status needs to be saved to the LogService
    Aborted   = 5;
}

// TxnMeta transaction metadata
message TxnMeta {
    // ID transaction id, generated at the CN node at the time of transaction creation, 
    // globally unique.
    bytes                     ID           = 1;
    // Status transaction status
    TxnStatus                 Status       = 2;
    // SnapshotTS transaction read timestamp, generated at the CN node at the time of 
    // transaction creation. All data.TS < txn.SnapshotTS is visible for the current 
    // transaction.
    timestamp.Timestamp       SnapshotTS   = 3 [(gogoproto.nullable) = false];
    // PreparedTS timestamp to complete the first phase of a 2pc commit transaction.
    timestamp.Timestamp       PreparedTS   = 4 [(gogoproto.nullable) = false];
    // CommitTS transaction commit timestamp. For a 2pc transaction, commitTS = max(preparedTS).
    timestamp.Timestamp       CommitTS     = 5 [(gogoproto.nullable) = false];
    // TNShards all TNShards that have written data. The first TN is the coordinator of the 
    // transaction
    repeated metadata.TNShard TNShards     = 6 [(gogoproto.nullable) = false];
    // LockTables For pessimistic transactions, LockTables record the bind metadata of the 
    // LockTable corresponding to the successful locking of the current transaction. This data 
    // is committed to the TN at Commit time, and the TN will check once if these bindings have 
    // changed, and if they have, the transaction will be rolled back.
    repeated lock.LockTable   LockTables   = 7 [(gogoproto.nullable) = false];
    // TxnMode txn mode
    TxnMode                   Mode         = 8;
    // TxnIsolation isolation
    TxnIsolation              Isolation    = 9;
    // Mirror is mirror is true, means the current txn is not created on current node.
    bool                      Mirror       = 10;
    // LockService lock service's service address. Empty if is not pessimistic txn.
    string                    LockService  = 11;
}

// CNTxnSnapshot snapshot of the cn txn operation.
message CNTxnSnapshot {
    // ID txn id
    TxnMeta                   Txn              = 1 [(gogoproto.nullable) = false];
    // Deprecated: use TxnOptions
    bool                      ReadyOnly        = 2;
    // Deprecated: use TxnOptions
    bool                      EnableCacheWrite = 3;
    // Deprecated: use TxnOptions
    bool                      Disable1PCOpt    = 4;
    repeated lock.LockTable   LockTables       = 5 [(gogoproto.nullable) = false];
    TxnOptions                Options          = 6 [(gogoproto.nullable) = false];
}

// CNOpRequest cn read/write request, CN -> TN. If data is written to more than one TN (>1) in a 
// single transaction, then the transaction becomes a 2pc transaction.
message CNOpRequest {
    // OpCode request operation type
    uint32           OpCode  = 1;
    // Payload the content of the request, TxnClient does not perceive the exact
    // format and content
    bytes            Payload = 2;
    // Target target to which the request was sent
	metadata.TNShard Target  = 3 [(gogoproto.nullable) = false]; 
}

// CNOpResponse cn read/write response, TN -> CN. A request corresponds to a response.
message CNOpResponse {
    // Payload response payload
	bytes Payload = 1;
}

// TxnMethod transaction operations
enum TxnMethod {
    // Read transaction read
    Read              = 0;
    // Write transaction write
    Write             = 1;
    // Commit commit transaction
    Commit            = 2;
    // Rollback rollback transaction
    Rollback          = 3;
    // Prepare when TN(Coordinator) receives a commit request from CN, it sends a prepare to 
    // each TN(TNShard)
    Prepare           = 4;
    // GetStatus query the status of a transaction on a TN. When a TN encounters a transaction
    // in the Prepared state, it needs to go to the TN(Coordinator) to query the status of the 
    // current transaction. When a TN encounters a transaction in the Prepared state during the 
    // recover, it needs to query the status of the transaction on each TN(TNShard) to determine
    // if the transaction is committed.
    GetStatus         = 5;
    // CommitTNShard after the 2pc transaction is committed, the temporary data on each TN needs
    // to be explicitly converted to committed data.
    CommitTNShard     = 6;
    // RollbackTNShard after the 2pc transaction is aborted, the temporary data on each TN needs
    // to cleanup.
    RollbackTNShard   = 7;
    // RemoveMedata Remove metadata for transactions on TNShard. For a 2pc distributed transaction, 
    // after all participating TNShards have Prepared successfully, the asynchronous commit process 
    // starts, sending CommitTNShard requests to all participating TNShards in parallel. After each 
    // TNShard has processed the CommitTNShard, the metadata of the transaction cannot be deleted 
    // immediately, otherwise when the transaction coordinator node is down and restarted, the commit 
    // status of the transaction cannot be determined in the recovery process, as it is possible that
    // some participating TNShards cannot find the transaction information.
    //
    // TODO: needs to work with TAE's log compaction, not currently supported.
    RemoveMedata      = 8;
    // DEBUG used to send debug request from cn to tn, and received response from tn to cn
    DEBUG             = 9;
}

// TxnRequest transaction request. All requests for the transaction are made using TxnRequest, so that 
// the codec and logical processing of the RPC can be unified. Specific requests are selected according 
// to TxnMethod.
//
// Request flow of TxnRequest as below:
// 1. CN -> TN (TxnMethod.Read, TxnMethod.Write, TxnMethod.Commit, TxnMethod.Rollback)
// 2. TN -> TN (TxnMethod.Prepare, TxnMethod.GetStatus, TxnMethod.CommitTNShard, TxnMethod.RollbackTNShard,
//             TxnMethod.RemoveMetadata)
message TxnRequest {
    // RequestID request id
    uint64                      RequestID                = 1;
    // Txn transaction metadata
    TxnMeta                     Txn                      = 2 [(gogoproto.nullable) = false];
    // TxnMethod TxnRequest opCode, select the Request defined below according to TxnMethod.
    TxnMethod                   Method                   = 3;
    // Flag request flag
    uint32                      Flag                     = 4;
    // CNOpRequest corresponds to TxnMethod.Read, TxnMethod.Write
    CNOpRequest                 CNRequest                = 5; 
    // TxnCommitRequest corresponds to TxnMethod.Commit
    TxnCommitRequest            CommitRequest            = 6;
    // TxnRollbackRequest corresponds to TxnMethod.Rollback
    TxnRollbackRequest          RollbackRequest          = 7;
    // TxnPrepareRequest corresponds to TxnMethod.Prepare
    TxnPrepareRequest           PrepareRequest           = 8;
    // TxnGetStatusRequest corresponds to TxnMethod.GetStatus
    TxnGetStatusRequest         GetStatusRequest         = 9;
    // TxnCommitTNShardRequest corresponds to TxnMethod.CommitTNShard
    TxnCommitTNShardRequest     CommitTNShardRequest     = 10;
    // TxnRollbackTNShardRequest corresponds to TxnMethod.RollbackTNShard
    TxnRollbackTNShardRequest   RollbackTNShardRequest   = 11;
    // TxnRemoveMetadataRequest  corresponds to TxnMethod.RemoveMetadata
    TxnRemoveMetadataRequest    RemoveMetadata           = 12;
    // TxnRequestOptions request options
    TxnRequestOptions           Options                  = 13;
}

// TxnRequestOptions txn options
message TxnRequestOptions {
    // RetryCodes when TN processes TxnRequest and encounters the specified error, it needs to retry
    // on the server side. Only read and write can retry.
    repeated int32 RetryCodes    = 1;
    // RetryInterval retry interval, default is 100ms.
    int64              RetryInterval = 2;    
}

// TxnResponse response of TxnRequest.
message TxnResponse {
    // RequestID corresponding request id
    uint64                       RequestID                 = 1;
    // Txn transaction metadata. TxnResponse.TxnMeta and TxnRequest.TxnMeta may differ 
    // in that the node initiating the TxnRequest needs to process the returned TxnMeta, 
    // e.g. to determine whether the transaction is Aborted by the status of the returned 
    // TxnMeta.
    TxnMeta                      Txn                       = 2;
    // TxnMethod same as TxnRequest.TxnMethod
    TxnMethod                    Method                    = 3;
    // Flag request flag, same as the corresponding request
    uint32                       Flag                      = 4;
    // TxnError explicit error
    TxnError                     TxnError                  = 5;
    // CNOpResponse corresponds to TxnMethod.Read, TxnMethod.Write response
    CNOpResponse                 CNOpResponse              = 6; 
    // TxnCommitResponse corresponds to TxnMethod.Commit response
    TxnCommitResponse            CommitResponse            = 7;
    // TxnRollbackResponse corresponds to TxnMethod.Rollback response
    TxnRollbackResponse          RollbackResponse          = 8;
    // TxnPrepareResponse corresponds to TxnMethod.Prepare response
    TxnPrepareResponse           PrepareResponse           = 9;
    // TxnGetStatusResponse corresponds to TxnMethod.GetStatus response
    TxnGetStatusResponse         GetStatusResponse         = 10;
    // TxnCommitTNShardResponse corresponds to TxnMethod.CommitTNShard response
    TxnCommitTNShardResponse     CommitTNShardResponse     = 11;
    // TxnRollbackTNShardResponse corresponds to TxnMethod.RollbackTNShard response
    TxnRollbackTNShardResponse   RollbackTNShardResponse   = 12;
     // TxnRemoveMetadataResponse  corresponds to TxnMethod.RemoveMetadata
     TxnRemoveMetadataResponse   RemoveMetadata            = 13;
}

// TxnCommitRequest CN sent the commit request to coordinator TN.
message TxnCommitRequest {
    repeated TxnRequest       Payload = 1;
    bool                      Disable1PCOpt = 2;
}

// TxnCommitResponse response of TxnCommitRequest. 
message TxnCommitResponse {
    repeated uint64 InvalidLockTables = 1;
}

// TxnCommitRequest CN sent the rollback request to coordinator TN.
message TxnRollbackRequest {
}

// TxnRollbackResponse response of TxnRollbackRequest.
message TxnRollbackResponse {
}

// TxnPrepareRequest when a TN(coordinator) receives a Commit request from a CN, if 
// more than one TN is involved, the 2PC commit process is enabled and the first phase
// is to send prepare requests to all TNs.
message TxnPrepareRequest {
    // TNShard prepare TN
    metadata.TNShard          TNShard  = 1 [(gogoproto.nullable) = false];
}

// TxnPrepareResponse response of TxnPrepareRequest
message TxnPrepareResponse {

}

// TxnGetStatusRequest query the status of a transaction on TN
message TxnGetStatusRequest {
    // TNShard target TN
    metadata.TNShard TNShard = 1 [(gogoproto.nullable) = false];
}

// TxnGetStatusResponse response of TxnGetStatusRequest
message TxnGetStatusResponse {
}

// TxnCommitTNShardRequest commit txn on TNShard. Data needs to be written to the 
// LogService.
message TxnCommitTNShardRequest {
     // TNShard target TN
     metadata.TNShard TNShard = 1 [(gogoproto.nullable) = false];
}

// TxnCommitTNShardResponse response of TxnCommitTNShardRequest
message TxnCommitTNShardResponse {
}

// TxnRollbackTNShardRequest rollback txn on TNShard
message TxnRollbackTNShardRequest {
     // TNShard target TN
     metadata.TNShard TNShard = 1 [(gogoproto.nullable) = false];
}

// TxnRollbackTNShardResponse response of TxnRollbackTNShardRequest
message TxnRollbackTNShardResponse {
}


// TxnRemoveMetadataRequest remove txn metadata on TNShard
message TxnRemoveMetadataRequest {
    // TNShard target TN
    metadata.TNShard TNShard = 1 [(gogoproto.nullable) = false];
}

// TxnRemoveMetadataResponse response of TxnRemoveMetadataRequest
message TxnRemoveMetadataResponse {
}

// TxnError all explicit errors in transaction operations. 
message TxnError {
    // Code moerr code, used to special error handle without unmarshal moerr
    uint32 Code       = 1;
    // Error we use this field to send moerr from tn to cn. Set with 
    // moerr.MarshalBinary, and use moerr.UnmarshalBinary to restore 
    // moerr.
    bytes  Error      = 2;
    // TxnErrCode is a internal err code in the txn framework and used to indicate
    // what transaction operation failed. Usually this value is the same as the value 
    // of Code, except for the error returned by the interface call to TxnStorage.
    // Because the types of errors returned by TxnStorage's interface are unknown to the 
    // transaction framework, it is necessary to use a code for the interface call to uniformly
    // replace these error codes.
    uint32 TxnErrCode = 3;
}

message TxnOptions {
    uint32                 Features           = 1;
    string                 CN                 = 2;
    string                 SessionID          = 3;
    uint32                 AccountID          = 4;
    uint32                 ConnectionID       = 5;
    string                 UserName           = 6;
    repeated uint64        SkipLockTables     = 7;
    repeated lock.LockMode SkipLockTableModes = 8;
    string counter = 9;
    string sessionInfo = 10;
    bool inRunSql = 11;
    bool inCommit = 12;
    bool inRollback = 13;
}