etcd/Documentation/rfc/v3api.proto

syntax = "proto3";

service KV {
  // Range gets the keys in the range from the store.
  rpc Range(RangeRequest) returns (RangeResponse) {}

  // Put puts the given key into the store.
  // A put request increases the revision of the store,
  // and generates one event in the event history.
  rpc Put(PutRequest) returns (PutResponse) {}

  // Delete deletes the given range from the store.
  // A delete request increase the revision of the store,
  // and generates one event in the event history.
  rpc DeleteRange(DeleteRangeRequest) returns (DeleteRangeResponse) {}

  // Txn processes all the requests in one transaction.
  // A txn request increases the revision of the store,
  // and generates events with the same revision in the event history.
  rpc Txn(TxnRequest) returns (TxnResponse) {}

  // Compact compacts the event history in etcd. User should compact the
  // event history periodically, or it will grow infinitely.
  rpc Compact(CompactionRequest) returns (CompactionResponse) {}

  // LeaseCreate creates a lease. A lease has a TTL. The lease will expire if the
  // server does not receive a keepAlive within TTL from the lease holder.
  // All keys attached to the lease will be expired and deleted if the lease expires.
  // The key expiration generates an event in event history.
  rpc LeaseCreate(LeaseCreateRequest) returns (LeaseCreateResponse) {}

  // LeaseRevoke revokes a lease. All the key attached to the lease will be expired and deleted.
  rpc LeaseRevoke(LeaseRevokeRequest) returns (LeaseRevokeResponse) {}

  // LeaseAttach attaches keys with a lease.
  rpc LeaseAttach(LeaseAttachRequest) returns (LeaseAttachResponse) {}

  // LeaseTxn likes Txn. It has two addition success and failure LeaseAttachRequest list.
  // If the Txn is successful, then the success list will be executed. Or the failure list
  // will be executed.
  rpc LeaseTxn(LeaseTxnRequest) returns (LeaseTxnResponse) {}

  // KeepAlive keeps the lease alive.
  rpc LeaseKeepAlive(stream LeaseKeepAliveRequest) returns (stream LeaseKeepAliveResponse) {}
}

service watch {
  // Watch watches the events happening or happened. Both input and output
  // are stream. One watch rpc can watch for multiple keys or prefixs and
  // get a stream of events. The whole events history can be watched unless
  // compacted.
  rpc Watch(stream WatchRequest) returns (stream WatchResponse) {}
}

message ResponseHeader {
  // an error type message?
  string error = 1;
  uint64 cluster_id = 2;
  uint64 member_id = 3;
  // revision of the store when the request was applied.
  int64 revision = 4;
  // term of raft when the request was applied.
  uint64 raft_term = 5;
}

message RangeRequest {
  // if the range_end is not given, the request returns the key.
  bytes key = 1;
  // if the range_end is given, it gets the keys in range [key, range_end).
  bytes range_end = 2;
  // limit the number of keys returned.
  int64 limit = 3;
  // range over the store at the given revision.
  // if revision is less or equal to zero, range over the newest store.
  // if the revision has been compacted, ErrCompaction will be returned in
  // response.
  int64 revision = 4;
}

message RangeResponse {
  ResponseHeader header = 1;
  repeated storagepb.KeyValue kvs = 2;
  // more indicates if there are more keys to return in the requested range.
  bool more = 3;
}

message PutRequest {
  bytes key = 1;
  bytes value = 2;
}

message PutResponse {
  ResponseHeader header = 1;
}

message DeleteRangeRequest {
  // if the range_end is not given, the request deletes the key.
  bytes key = 1;
  // if the range_end is given, it deletes the keys in range [key, range_end).
  bytes range_end = 2;
}

message DeleteRangeResponse {
  ResponseHeader header = 1;
}

message RequestUnion {
  oneof request {
    RangeRequest request_range = 1;
    PutRequest request_put = 2;
    DeleteRangeRequest request_delete_range = 3;
  }
}

message ResponseUnion {
  oneof response {
    RangeResponse response_range = 1;
    PutResponse response_put = 2;
    DeleteRangeResponse response_delete_range = 3;
  }
}

message Compare {
  enum CompareResult {
    EQUAL = 0;
    GREATER = 1;
    LESS = 2;
  }
  enum CompareTarget {
    VERSION = 0;
    CREATE = 1;
    MOD = 2;
    VALUE= 3;
  }
  CompareResult result = 1;
  CompareTarget target = 2;
  // key path
  bytes key = 3;
  oneof target_union {
    // version of the given key
    int64 version = 4;
    // create revision of the given key
    int64 create_revision = 5;
    // last modified revision of the given key
    int64 mod_revision = 6;
    // value of the given key
    bytes value = 7;
  }
}

// If the comparisons succeed, then the success requests will be processed in order, 
// and the response will contain their respective responses in order.
// If the comparisons fail, then the failure requests will be processed in order, 
// and the response will contain their respective responses in order.

// From google paxosdb paper:
// Our implementation hinges around a powerful primitive which we call MultiOp. All other database
// operations except for iteration are implemented as a single call to MultiOp. A MultiOp is applied atomically
// and consists of three components:
// 1. A list of tests called guard. Each test in guard checks a single entry in the database. It may check
// for the absence or presence of a value, or compare with a given value. Two different tests in the guard
// may apply to the same or different entries in the database. All tests in the guard are applied and
// MultiOp returns the results. If all tests are true, MultiOp executes t op (see item 2 below), otherwise
// it executes f op (see item 3 below).
// 2. A list of database operations called t op. Each operation in the list is either an insert, delete, or
// lookup operation, and applies to a single database entry. Two different operations in the list may apply
// to the same or different entries in the database. These operations are executed
// if guard evaluates to
// true.
// 3. A list of database operations called f op. Like t op, but executed if guard evaluates to false.
message TxnRequest {
  repeated Compare compare = 1;
  repeated RequestUnion success = 2;
  repeated RequestUnion failure = 3;
}

message TxnResponse {
  ResponseHeader header = 1;
  bool succeeded = 2;
  repeated ResponseUnion responses = 3;
}

message KeyValue {
  bytes key = 1;
  int64 create_revision = 2;
  // mod_revision is the last modified revision of the key.
  int64 mod_revision = 3;
  // version is the version of the key. A deletion resets
  // the version to zero and any modification of the key
  // increases its version.
  int64 version = 4;
  bytes value = 5;
}

message WatchRequest {
  // the key to be watched
  bytes key = 1;
  // the prefix to be watched.
  bytes prefix = 2;
  // start_revision is an optional revision (including) to watch from. No start_revision is "now".
  int64 start_revision = 3;
  // TODO: support Range watch?
  // TODO: support notification every time interval or revision increase?
  // TODO: support cancel watch if the server cannot reach with majority?
}

message WatchResponse {
  ResponseHeader header = 1;
  // TODO: support batched events response?
  storagepb.Event event = 2;
}

message Event {
  enum EventType {
    PUT = 0;
    DELETE = 1;
    EXPIRE = 2;
  }
  EventType event_type = 1;
  // a put event contains the current key-value
  // a delete/expire event contains the previous
  // key-value
  KeyValue kv = 2;
}

// Compaction compacts the kv store upto the given revision (including). 
// It removes the old versions of a key. It keeps the newest version of 
// the key even if its latest modification revision is smaller than the given 
// revision.
message CompactionRequest {
  int64 revision = 1;
}

message CompactionResponse {
  ResponseHeader header = 1;
}

message LeaseCreateRequest {
  // advisory ttl in seconds
  int64 ttl = 1;
}

message LeaseCreateResponse {
  ResponseHeader header = 1;
  int64 lease_id = 2;
  // server decided ttl in second
  int64 ttl = 3;
  string error = 4;
}

message LeaseRevokeRequest {
  int64 lease_id = 1;
}

message LeaseRevokeResponse {
  ResponseHeader header = 1;
}

message LeaseTxnRequest {
  TxnRequest request = 1;
  repeated LeaseAttachRequest success = 2;
  repeated LeaseAttachRequest failure = 3;
}

message LeaseTxnResponse {
  ResponseHeader header = 1;
  TxnResponse response = 2;
  repeated LeaseAttachResponse attach_responses = 3;
}

message LeaseAttachRequest {
  int64 lease_id = 1;
  bytes key = 2;
}

message LeaseAttachResponse {
  ResponseHeader header = 1;
}

message LeaseKeepAliveRequest {
  int64 lease_id = 1;
}

message LeaseKeepAliveResponse {
  ResponseHeader header = 1;
  int64 lease_id = 2;
  int64 ttl = 3;
}