github.com/matrixorigin/matrixone@v0.7.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";

option (gogoproto.goproto_enum_prefix_all) = true;

// 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 DNs, a 2pc commit is performed, 
    // and the prepared status means that the transaction on a DN 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 DNs, once all DNs 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 DNs 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(DN).Status == Prepared.
    Committing = 2;
    // Committed after the Committing phase has transformed all DN 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(DN).Status != Prepared.
    Aborting  = 4;
    // Aborted after the Aborting phase, all data involved in the DN 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];
    // DNShards all DNShards that have written data. The first DN is the coordinator of the 
    // transaction
    repeated metadata.DNShard DNShards = 6 [(gogoproto.nullable) = false];
}

// CNTxnSnapshot snapshot of the cn txn operation.
message CNTxnSnapshot {
    // ID txn id
    TxnMeta                   Txn      = 1 [(gogoproto.nullable) = false];
    // ReadyOnly txn options
    bool ReadyOnly        = 2;
    // EnableCacheWrite txn options
    bool EnableCacheWrite = 3;
    // Disable1PCOpt txn options
    bool Disable1PCOpt    = 4;
}

// CNOpRequest cn read/write request, CN -> DN. If data is written to more than one DN (>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.DNShard Target  = 3 [(gogoproto.nullable) = false]; 
}

// CNOpResponse cn read/write response, DN -> 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 DN(Coordinator) receives a commit request from CN, it sends a prepare to 
    // each DN(DNShard)
    Prepare           = 4;
    // GetStatus query the status of a transaction on a DN. When a DN encounters a transaction
    // in the Prepared state, it needs to go to the DN(Coordinator) to query the status of the 
    // current transaction. When a DN encounters a transaction in the Prepared state during the 
    // recover, it needs to query the status of the transaction on each DN(DNShard) to determine
    // if the transaction is committed.
    GetStatus         = 5;
    // CommitDNShard after the 2pc transaction is committed, the temporary data on each DN needs
    // to be explicitly converted to committed data.
    CommitDNShard     = 6;
    // RollbackDNShard after the 2pc transaction is aborted, the temporary data on each DN needs
    // to cleanup.
    RollbackDNShard   = 7;
    // RemoveMedata Remove metadata for transactions on DNShard. For a 2pc distributed transaction, 
    // after all participating DNShards have Prepared successfully, the asynchronous commit process 
    // starts, sending CommitDNShard requests to all participating DNShards in parallel. After each 
    // DNShard has processed the CommitDNShard, 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 DNShards 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 dn, and received response from dn 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 -> DN (TxnMethod.Read, TxnMethod.Write, TxnMethod.Commit, TxnMethod.Rollback)
// 2. DN -> DN (TxnMethod.Prepare, TxnMethod.GetStatus, TxnMethod.CommitDNShard, TxnMethod.RollbackDNShard,
//             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;
    // TxnCommitDNShardRequest corresponds to TxnMethod.CommitDNShard
    TxnCommitDNShardRequest     CommitDNShardRequest     = 10;
    // TxnRollbackDNShardRequest corresponds to TxnMethod.RollbackDNShard
    TxnRollbackDNShardRequest   RollbackDNShardRequest   = 11;
    // TxnRemoveMetadataRequest  corresponds to TxnMethod.RemoveMetadata
    TxnRemoveMetadataRequest    RemoveMetadata           = 12;
    // TxnRequestOptions request options
    TxnRequestOptions           Options                  = 13;
}

// TxnRequestOptions txn options
message TxnRequestOptions {
    // RetryCodes when DN 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;
    // TxnCommitDNShardResponse corresponds to TxnMethod.CommitDNShard response
    TxnCommitDNShardResponse     CommitDNShardResponse     = 11;
    // TxnRollbackDNShardResponse corresponds to TxnMethod.RollbackDNShard response
    TxnRollbackDNShardResponse   RollbackDNShardResponse   = 12;
     // TxnRemoveMetadataResponse  corresponds to TxnMethod.RemoveMetadata
     TxnRemoveMetadataResponse   RemoveMetadata            = 13;
}

// TxnCommitRequest CN sent the commit request to coordinator DN.
message TxnCommitRequest {
    bool                      Disable1PCOpt = 2;
}

// TxnCommitResponse response of TxnCommitRequest. 
message TxnCommitResponse {
}

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

// TxnRollbackResponse response of TxnRollbackRequest.
message TxnRollbackResponse {
}

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

// TxnPrepareResponse response of TxnPrepareRequest
message TxnPrepareResponse {

}

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

// TxnGetStatusResponse response of TxnGetStatusRequest
message TxnGetStatusResponse {
}

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

// TxnCommitDNShardResponse response of TxnCommitDNShardRequest
message TxnCommitDNShardResponse {
}

// TxnRollbackDNShardRequest rollback txn on DNShard
message TxnRollbackDNShardRequest {
     // DNShard target DN
     metadata.DNShard DNShard = 1 [(gogoproto.nullable) = false];
}

// TxnRollbackDNShardResponse response of TxnRollbackDNShardRequest
message TxnRollbackDNShardResponse {
}


// TxnRemoveMetadataRequest remove txn metadata on DNShard
message TxnRemoveMetadataRequest {
    // DNShard target DN
    metadata.DNShard DNShard = 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 dn 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;
}