diff --git a/Documentation/rfc/v3api.md b/Documentation/rfc/v3api.md index 6d13ea90a..b7e49f01c 100644 --- a/Documentation/rfc/v3api.md +++ b/Documentation/rfc/v3api.md @@ -30,7 +30,9 @@ ## Protobuf Defined API -[protobuf](./v3api.proto) +[api protobuf](../../etcdserver/etcdserverpb/rpc.proto) + +[kv protobuf](../../storage/storagepb/kv.proto) ## Examples diff --git a/Documentation/rfc/v3api.proto b/Documentation/rfc/v3api.proto deleted file mode 100644 index e1b458fb6..000000000 --- a/Documentation/rfc/v3api.proto +++ /dev/null @@ -1,290 +0,0 @@ -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. - // It is not allowed to modify the same key several times within one txn. - 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) {} -} - -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) {} -} - -service Lease { - // 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) {} - - // KeepAlive keeps the lease alive. - rpc LeaseKeepAlive(stream LeaseKeepAliveRequest) returns (stream LeaseKeepAliveResponse) {} - - // TODO(xiangli) List all existing Leases? - // TODO(xiangli) Get details information (expirations, leased keys, etc.) of a lease? -} - -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; - int64 lease = 3; -} - -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; - // lease is the ID of the lease that attached to key. - // When the attached lease expires, the key will be deleted. - int64 lease = 6; -} - -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; -}