hstoreservice.proto

import "ca/evanjones/protorpc/Protocol.proto";

package edu.brown.hstore;

enum Status {
    // Everything is ok with the transaction and it is allowed
    // to proceed to the next processing stage
    OK = 0;
    // Status code indicating the stored procedure executed successfully and was
    // voluntarily aborted and rolled back by the stored procedure code
    ABORT_USER = 1;
    // Status code indicating the stored procedure failed and was rolled back. There are no negative server side
    // side effects.
    ABORT_GRACEFUL = 2;
    // Status code indicating the stored procedure failed (or may never have been successfully invoked)
    // and that there may have been negative side effects on the server
    ABORT_UNEXPECTED = 3;
    // Status code indicating the connection to the database that the invocation was queued at
    // was lost before a response was received. It is possible that the invocation was sent,
    // executed, and successfully committed before a response could be returned or the 
    // invocation may never have been sent.
    ABORT_CONNECTION_LOST = 4;
    // The transaction aborted because of a misprediction (and will be restarted)
    ABORT_MISPREDICT = 5;
    // The transaction could not be initialized because on partition rejected it.
    // The transaction will be retried at the initiaizing HStoreSite
    ABORT_RESTART = 6;
    // The transaction could not be initialized because on partition rejected it.
    // The transaction will be retried at the initiaizing HStoreSite
    ABORT_REJECT = 7;
    // The transaction was aborted because it tried to access a tuple that was
    // evicted. This is only used with the anti-caching feature.
    ABORT_EVICTEDACCESS = 8;
    // The transaction was aborted because it was speculatively executed and 
    // its parent distributed transaction aborted.
    ABORT_SPECULATIVE = 9;
}

// -----------------------------------
// GLOBAL DATA HOLDER
// -----------------------------------

// Specifies the work to be performed at a single partition.
message WorkFragment {

    // The partition that needs to execute this work fragment
    required int32 partition_id = 1;
    
    // The PlanFragment ids that this partition will execute
    repeated int32 fragment_id = 2 [packed=true];
    
    // The DependencyIds that each PlanFragment needs as input
    repeated int32 input_dep_id = 3 [packed=true];
    
    // The DependencyIds that this work message will generate as output
    repeated int32 output_dep_id = 4 [packed=true];
    
    // What ParameterSet offset do we need for each PlanFragment
    repeated int32 param_index = 5 [packed=true];

    // The number of times that we have executed this Statement in the past
    // for this transaction.
    repeated int32 stmt_counter = 6 [packed=true];
    
    // The offset of this fragment's corresponding SQLStmt in the current batch.
    repeated int32 stmt_index = 7 [packed=true];
    
    // If a value is set to true in this array, then the PartitionExecutor
    // should not execute the fragment id at the corresponding offset.
    repeated bool stmt_ignore = 8 [packed=true];

    // Are all of the PlanFragments read only?
    required bool read_only = 9;
    
    // If true, then the Work embedded in this WorkFragment needs input
    optional bool needs_input = 10 [default = false];
    
    // If true, then this is the final fragment for this transaction at this partition.
    optional bool last_fragment = 11 [default = false];

    // If true, then this is a prefetch fragment
    optional bool prefetch = 12 [default = false];
    
    // If true, then this fragment should always be executed regardless 
    // of whether its result is cached.
    optional bool force = 13 [default = false];

    // An estimate of the Statements that the transaction might
    // execute at this partition
    optional QueryEstimate future_statements = 14;
}

// The output results of WorkFragments
message WorkResult {
    // What partition produced this result
    required int32 partition_id = 1;
    
    // Unique Dependency Identifers
    repeated int32 dep_id = 2 [packed=true];
    
    // Serialized VoltTables
    repeated bytes dep_data = 3;
    
    // Status of the WorkRequest
    required Status status = 4;
    
    // If this partition hit an error, this field will contain the SerializableException
    optional bytes error = 5;
}

// Speculative Execution Estimate
message QueryEstimate {
    // An ordered list of StatementIds that the transaction might execute
    repeated int32 stmt_ids = 1 [packed=true];
    // The counter of the number of times that the transaction has executed
    // these StatementIds in the past.
    repeated int32 stmt_counters = 2 [packed=true];
    // The estimated amount of time (in milliseconds) until the transaction
    // is expected to need the results of these queries.
    optional int32 time_estimate = 3;
}

// -----------------------------------
// INITIALIZE TRANSACTION
// -----------------------------------

// Initialization request for a new transaction
message TransactionInitRequest {
    // The last distributed transaction id seen at the sending base partition
    optional int64 last_transaction_id = 1;

    // Globally unique transaction id
    required int64 transaction_id = 2;

    // The base partition
    required int32 base_partition = 3;

    // Procedure Id
    required int32 procedure_id = 4;
    
    // List of partitions at this site that are will be involved
    // with this transaction.
    repeated int32 partitions = 5 [packed=true];

    // Serialized Stored Procedure ParameterSet
    // This is optional if we are doing speculative execution
    optional bytes proc_params = 6;

    // PRE-FETCH QUERIES
    
    // The work that the HStoreSite needs to execute for this transaction
    // The work for a partition can appear only once in this list.
    repeated WorkFragment prefetch_fragments = 7;
    
    // Serialized ParameterSets (one per Statment).
    // The order of these elements must match WorkFragment.paramIndex
    repeated bytes prefetch_params = 8;
}

message TransactionInitResponse {
    required int64 transaction_id = 1;
    repeated int32 partitions = 2 [packed=true];
    required Status status = 3;
    optional int32 reject_partition = 4;
    optional int64 reject_transaction_id = 5;
}

// -----------------------------------
// TRANSACTION WORK
// -----------------------------------

message TransactionWorkRequest {
    // The last distributed transaction id seen at the sending base partition
    optional int64 last_transaction_id = 1;

    // Globally unique transaction id
    required int64 transaction_id = 2;
    
    // Where this request came from!
    required int32 source_partition = 3;
    
    // The work that the HStoreSite needs to execute for this transaction
    // The work for a partition can appear only once in this list.
    repeated WorkFragment fragments = 4;
    
    // Procedure Id
    required int32 procedure_id = 5;
    
    // Serialized ParameterSets (one per Statment).
    // The order of these elements must match WorkFragment.paramIndex
    repeated bytes params = 6;
    
    // We can attach input dependencies to each message
    // Unique Dependency Identifers
    repeated int32 attached_dep_id = 7 [packed=true];
    
    // Attached Serialized VoltTables
    repeated bytes attached_data = 8;
    
    // List of partitions that this transaction is done with
    // This allows us to piggyback on this message additional information
    repeated int32 done_partition = 9 [packed=true];

    // Serialized Stored Procedure ParameterSet
    // This is optional if we are doing speculative execution
    optional bytes proc_params = 10;
}

message TransactionWorkResponse {
    // Globally unique transaction id
    required int64 transaction_id = 1;
    
    // The results for the TransactionWorkRequest
    repeated WorkResult results = 2;
    
    // The global status for this response
    required Status status = 3;
}

// -----------------------------------
// TRANSACTION PREFETCH RESPONSE
// -----------------------------------

message TransactionPrefetchResult {
    // The last distributed transaction id seen at the sending base partition
    optional int64 last_transaction_id = 1;

    // Globally unique transaction id
    required int64 transaction_id = 2;
    
    // The partition id where this result came from
    required int32 source_partition = 3;
    
    // The results for the prefetched queries at this partition
    required WorkResult result = 4;
    
    // The global status for this response
    required Status status = 5;

    // StmtCounters + FragmentIds + ParameterSet hashes for the results
    // The offsets of these arrays will correspond with the
    // offsets in the WorkResult. I decided to put these separately
    // here because other parts of the system that use WorkResult do
    // not need this information
    repeated int32 stmt_counter = 6 [packed=true];
    repeated int32 fragment_id = 7 [packed=true];
    repeated int32 param_hash = 8 [packed=true];
}

message TransactionPrefetchAcknowledgement {
    // Globally unique transaction id
    required int64 transaction_id = 1;
    
    // The target partition id for this acknowledgement
    required int32 target_partition = 2;
}

// -----------------------------------
// MAP (MR JOB)
// -----------------------------------

message TransactionMapRequest {
    // The last distributed transaction id seen at the sending base partition
    optional int64 last_transaction_id = 1;

    // Globally unique transaction id
    required int64 transaction_id = 2;
    
    // Client Handle
    required int64 client_handle = 3;
    
    // Base Partition
    required int32 base_partition = 4;

    // Procedure Id
    required int32 procedure_id = 5;

    // Serialized Procedure ParameterSet
    required bytes params = 6;
}

message TransactionMapResponse {
    required int64 transaction_id = 1;
    repeated int32 partitions = 2 [packed=true];
    required Status status = 3;
}

// -----------------------------------
// REDUCE (MR JOB)
// -----------------------------------

message TransactionReduceRequest {
    // Globally unique transaction id
    required int64 transaction_id = 1;
}

message TransactionReduceResponse {
    // The output results of TransactionReduceRequest
    message ReduceResult {
        required int32 partition_id = 1;
        // Serialized response
        required bytes data = 2;
        // Status code 
        required Status status = 3;
        // If this partition hit an error, this field will contain the error message.
        optional bool error = 4 [default = false];
    }

    required int64 transaction_id = 1;
    repeated ReduceResult results = 2;
    required Status status = 3;
}

// -----------------------------------
// 2PC:PREPARE TRANSACTION
// -----------------------------------

// Two-Phase Commit Prepare
// The initiating HStoreSite is telling the remote sites to prepare to commit
// a distributed transaction for a select number of partitions.
message TransactionPrepareRequest {
    required int64 transaction_id = 1;
    repeated int32 partitions = 2 [packed=true];
}

message TransactionPrepareResponse {
    required int64 transaction_id = 1;
    repeated int32 partitions = 2 [packed=true];
    required Status status = 3;
}

// -----------------------------------
// 2PC:FINISH TRANSACTION
// -----------------------------------

// Two-Phase Commit Final Step
// The initiating HStoreSite is telling the remote sites that they
// they need to commit/abort their transaction. The PREPARE request
// must be sent before this one only if the status is COMMIT
message TransactionFinishRequest {
    // Globally unique transaction id
    required int64 transaction_id = 1;
    repeated int32 partitions = 2 [packed=true];
    required Status status = 3;
}

message TransactionFinishResponse {
    required int64 transaction_id = 1;
    repeated int32 partitions = 2 [packed=true];
}

// -----------------------------------
// TRANSACTION REDIRECT MESSAGE
// -----------------------------------

message TransactionRedirectRequest {
    required int32 sender_site = 1;
    required bytes work = 2;
    optional int64 orig_txn_id = 3;
}

message TransactionRedirectResponse {
    // The id of the HStoreSite is responding to this shutdown request
    required int32 sender_site = 1;
    required bytes output = 2;
}

// -----------------------------------
// TRANSACTION DEBUG MESSAGE
// -----------------------------------

message TransactionDebugRequest {
    required int32 sender_site = 1;
    required int64 transaction_id = 2;
}

message TransactionDebugResponse {
    required int32 sender_site = 1;
    required Status status = 2;
    required string debug = 3;
}

// -----------------------------------
// SEND DATA
// -----------------------------------

message SendDataRequest {
    // Globally unique transaction id
    required int64 transaction_id = 1;

    // The SiteId of the HStoreSite that sent this data
    required int32 sender_site = 2;
    
    // Set of partitions to send data to. A partition can appear only once in this list.
    // The data stored in each fragment is a serialized VoltTable
    repeated int32 dep_id = 3 [packed=true];
    
    // Attached Serialized VoltTables
    repeated bytes data = 4;
}

message SendDataResponse {
    required int64 transaction_id = 1;
    repeated int32 partitions = 2 [packed=true];
    // The SiteId of the HStoreSite that sent this data
    required int32 sender_site = 3;
    required Status status = 4;
}

// -----------------------------------
// CLUSTER INITIALIZE MESSAGE
// -----------------------------------

message InitializeRequest {
    required int32 sender_site = 1;
    required int64 instance_id = 2;
}

message InitializeResponse {
    required int32 sender_site = 1;
    required Status status = 2;
}

// -----------------------------------
// CLUSTER SHUTDOWN MESSAGE
// -----------------------------------

message ShutdownPrepareRequest {
    // The id of the HStoreSite that is wants us to shutdown
    required int32 sender_site = 1;
    optional bytes error = 2;
}

message ShutdownPrepareResponse {
    // The id of the HStoreSite is responding to this shutdown request
    required int32 sender_site = 1;
}

message ShutdownRequest {
    required int32 sender_site = 1;
    required int32 exit_status = 2;
}

message ShutdownResponse {
    required int32 sender_site = 1;
}

// -----------------------------------
// NODE HEARTBEAT MESSAGES
// -----------------------------------

message HeartbeatRequest {
    required int32 sender_site = 1;
    // This is the largest txn acked at the sender site
    required int64 last_transaction_id = 2;
}

message HeartbeatResponse {
    required int32 sender_site = 1;
    required Status status = 2;
}

// -----------------------------------
// NODE UNEVICTDATA MESSAGES
// -----------------------------------

message UnevictDataRequest {
    required int32 sender_site = 1;
    required int64 transaction_id = 2;
    required int32 partition_id = 3;
    required int32 table_id = 4;
    repeated int32 block_ids = 5 [packed=true];
    repeated int32 tuple_offsets = 6 [packed=true];
    required int64 new_transaction_id = 7;
}

message UnevictDataResponse {
    required int32 sender_site = 1;
    required Status status = 2;
    required int64 transaction_id = 3;
    required int32 partition_id = 4;
}

// -----------------------------------
// TIME SYNC MESSAGE
// -----------------------------------

message TimeSyncRequest {
    // The id of the HStoreSite sending this timesync request
    required int32 sender_site = 1;
    // The time when the local HStoreSite sent this request
    required int64 t0_s = 2;
}

message TimeSyncResponse {
    // The id of the HStoreSite responding to this timesync request
    required int32 sender_site = 1;
    // The time when the local HStoreSite sent this request
    required int64 t0_s = 2;
    // The time when the remote HStoreSite received this request
    required int64 t0_r = 3;
    // The time when the remote HStoreSite sent out the response
    required int64 t1_s = 4;
}


// -----------------------------------
// SERVICE
// -----------------------------------

service HStoreService {
    rpc TransactionInit(TransactionInitRequest) returns (TransactionInitResponse);
    rpc TransactionWork(TransactionWorkRequest) returns (TransactionWorkResponse);
    rpc TransactionPrefetch(TransactionPrefetchResult) returns (TransactionPrefetchAcknowledgement);
    rpc TransactionMap(TransactionMapRequest) returns (TransactionMapResponse);
    rpc TransactionReduce(TransactionReduceRequest) returns (TransactionReduceResponse);
    rpc TransactionPrepare(TransactionPrepareRequest) returns (TransactionPrepareResponse);
    rpc TransactionFinish(TransactionFinishRequest) returns (TransactionFinishResponse);
    rpc TransactionRedirect(TransactionRedirectRequest) returns (TransactionRedirectResponse);
    rpc TransactionDebug(TransactionDebugRequest) returns (TransactionDebugResponse);
    rpc SendData(SendDataRequest) returns (SendDataResponse);
    rpc Initialize(InitializeRequest) returns (InitializeResponse);
    rpc ShutdownPrepare(ShutdownPrepareRequest) returns (ShutdownPrepareResponse);
    rpc Shutdown(ShutdownRequest) returns (ShutdownResponse);
    rpc Heartbeat(HeartbeatRequest) returns (HeartbeatResponse);
    rpc UnevictData(UnevictDataRequest) returns (UnevictDataResponse);
    rpc TimeSync(TimeSyncRequest) returns (TimeSyncResponse);
}