1syntax = "proto3"; 2package etcdserverpb; 3 4import "gogoproto/gogo.proto"; 5import "etcd/mvcc/mvccpb/kv.proto"; 6import "etcd/auth/authpb/auth.proto"; 7 8// for grpc-gateway 9import "google/api/annotations.proto"; 10 11option (gogoproto.marshaler_all) = true; 12option (gogoproto.unmarshaler_all) = true; 13 14service KV { 15 // Range gets the keys in the range from the key-value store. 16 rpc Range(RangeRequest) returns (RangeResponse) { 17 option (google.api.http) = { 18 post: "/v3/kv/range" 19 body: "*" 20 }; 21 } 22 23 // Put puts the given key into the key-value store. 24 // A put request increments the revision of the key-value store 25 // and generates one event in the event history. 26 rpc Put(PutRequest) returns (PutResponse) { 27 option (google.api.http) = { 28 post: "/v3/kv/put" 29 body: "*" 30 }; 31 } 32 33 // DeleteRange deletes the given range from the key-value store. 34 // A delete request increments the revision of the key-value store 35 // and generates a delete event in the event history for every deleted key. 36 rpc DeleteRange(DeleteRangeRequest) returns (DeleteRangeResponse) { 37 option (google.api.http) = { 38 post: "/v3/kv/deleterange" 39 body: "*" 40 }; 41 } 42 43 // Txn processes multiple requests in a single transaction. 44 // A txn request increments the revision of the key-value store 45 // and generates events with the same revision for every completed request. 46 // It is not allowed to modify the same key several times within one txn. 47 rpc Txn(TxnRequest) returns (TxnResponse) { 48 option (google.api.http) = { 49 post: "/v3/kv/txn" 50 body: "*" 51 }; 52 } 53 54 // Compact compacts the event history in the etcd key-value store. The key-value 55 // store should be periodically compacted or the event history will continue to grow 56 // indefinitely. 57 rpc Compact(CompactionRequest) returns (CompactionResponse) { 58 option (google.api.http) = { 59 post: "/v3/kv/compaction" 60 body: "*" 61 }; 62 } 63} 64 65service Watch { 66 // Watch watches for events happening or that have happened. Both input and output 67 // are streams; the input stream is for creating and canceling watchers and the output 68 // stream sends events. One watch RPC can watch on multiple key ranges, streaming events 69 // for several watches at once. The entire event history can be watched starting from the 70 // last compaction revision. 71 rpc Watch(stream WatchRequest) returns (stream WatchResponse) { 72 option (google.api.http) = { 73 post: "/v3/watch" 74 body: "*" 75 }; 76 } 77} 78 79service Lease { 80 // LeaseGrant creates a lease which expires if the server does not receive a keepAlive 81 // within a given time to live period. All keys attached to the lease will be expired and 82 // deleted if the lease expires. Each expired key generates a delete event in the event history. 83 rpc LeaseGrant(LeaseGrantRequest) returns (LeaseGrantResponse) { 84 option (google.api.http) = { 85 post: "/v3/lease/grant" 86 body: "*" 87 }; 88 } 89 90 // LeaseRevoke revokes a lease. All keys attached to the lease will expire and be deleted. 91 rpc LeaseRevoke(LeaseRevokeRequest) returns (LeaseRevokeResponse) { 92 option (google.api.http) = { 93 post: "/v3/lease/revoke" 94 body: "*" 95 additional_bindings { 96 post: "/v3/kv/lease/revoke" 97 body: "*" 98 } 99 }; 100 } 101 102 // LeaseKeepAlive keeps the lease alive by streaming keep alive requests from the client 103 // to the server and streaming keep alive responses from the server to the client. 104 rpc LeaseKeepAlive(stream LeaseKeepAliveRequest) returns (stream LeaseKeepAliveResponse) { 105 option (google.api.http) = { 106 post: "/v3/lease/keepalive" 107 body: "*" 108 }; 109 } 110 111 // LeaseTimeToLive retrieves lease information. 112 rpc LeaseTimeToLive(LeaseTimeToLiveRequest) returns (LeaseTimeToLiveResponse) { 113 option (google.api.http) = { 114 post: "/v3/lease/timetolive" 115 body: "*" 116 additional_bindings { 117 post: "/v3/kv/lease/timetolive" 118 body: "*" 119 } 120 }; 121 } 122 123 // LeaseLeases lists all existing leases. 124 rpc LeaseLeases(LeaseLeasesRequest) returns (LeaseLeasesResponse) { 125 option (google.api.http) = { 126 post: "/v3/lease/leases" 127 body: "*" 128 additional_bindings { 129 post: "/v3/kv/lease/leases" 130 body: "*" 131 } 132 }; 133 } 134} 135 136service Cluster { 137 // MemberAdd adds a member into the cluster. 138 rpc MemberAdd(MemberAddRequest) returns (MemberAddResponse) { 139 option (google.api.http) = { 140 post: "/v3/cluster/member/add" 141 body: "*" 142 }; 143 } 144 145 // MemberRemove removes an existing member from the cluster. 146 rpc MemberRemove(MemberRemoveRequest) returns (MemberRemoveResponse) { 147 option (google.api.http) = { 148 post: "/v3/cluster/member/remove" 149 body: "*" 150 }; 151 } 152 153 // MemberUpdate updates the member configuration. 154 rpc MemberUpdate(MemberUpdateRequest) returns (MemberUpdateResponse) { 155 option (google.api.http) = { 156 post: "/v3/cluster/member/update" 157 body: "*" 158 }; 159 } 160 161 // MemberList lists all the members in the cluster. 162 rpc MemberList(MemberListRequest) returns (MemberListResponse) { 163 option (google.api.http) = { 164 post: "/v3/cluster/member/list" 165 body: "*" 166 }; 167 } 168} 169 170service Maintenance { 171 // Alarm activates, deactivates, and queries alarms regarding cluster health. 172 rpc Alarm(AlarmRequest) returns (AlarmResponse) { 173 option (google.api.http) = { 174 post: "/v3/maintenance/alarm" 175 body: "*" 176 }; 177 } 178 179 // Status gets the status of the member. 180 rpc Status(StatusRequest) returns (StatusResponse) { 181 option (google.api.http) = { 182 post: "/v3/maintenance/status" 183 body: "*" 184 }; 185 } 186 187 // Defragment defragments a member's backend database to recover storage space. 188 rpc Defragment(DefragmentRequest) returns (DefragmentResponse) { 189 option (google.api.http) = { 190 post: "/v3/maintenance/defragment" 191 body: "*" 192 }; 193 } 194 195 // Hash computes the hash of whole backend keyspace, 196 // including key, lease, and other buckets in storage. 197 // This is designed for testing ONLY! 198 // Do not rely on this in production with ongoing transactions, 199 // since Hash operation does not hold MVCC locks. 200 // Use "HashKV" API instead for "key" bucket consistency checks. 201 rpc Hash(HashRequest) returns (HashResponse) { 202 option (google.api.http) = { 203 post: "/v3/maintenance/hash" 204 body: "*" 205 }; 206 } 207 208 // HashKV computes the hash of all MVCC keys up to a given revision. 209 // It only iterates "key" bucket in backend storage. 210 rpc HashKV(HashKVRequest) returns (HashKVResponse) { 211 option (google.api.http) = { 212 post: "/v3/maintenance/hash" 213 body: "*" 214 }; 215 } 216 217 // Snapshot sends a snapshot of the entire backend from a member over a stream to a client. 218 rpc Snapshot(SnapshotRequest) returns (stream SnapshotResponse) { 219 option (google.api.http) = { 220 post: "/v3/maintenance/snapshot" 221 body: "*" 222 }; 223 } 224 225 // MoveLeader requests current leader node to transfer its leadership to transferee. 226 rpc MoveLeader(MoveLeaderRequest) returns (MoveLeaderResponse) { 227 option (google.api.http) = { 228 post: "/v3/maintenance/transfer-leadership" 229 body: "*" 230 }; 231 } 232} 233 234service Auth { 235 // AuthEnable enables authentication. 236 rpc AuthEnable(AuthEnableRequest) returns (AuthEnableResponse) { 237 option (google.api.http) = { 238 post: "/v3/auth/enable" 239 body: "*" 240 }; 241 } 242 243 // AuthDisable disables authentication. 244 rpc AuthDisable(AuthDisableRequest) returns (AuthDisableResponse) { 245 option (google.api.http) = { 246 post: "/v3/auth/disable" 247 body: "*" 248 }; 249 } 250 251 // Authenticate processes an authenticate request. 252 rpc Authenticate(AuthenticateRequest) returns (AuthenticateResponse) { 253 option (google.api.http) = { 254 post: "/v3/auth/authenticate" 255 body: "*" 256 }; 257 } 258 259 // UserAdd adds a new user. 260 rpc UserAdd(AuthUserAddRequest) returns (AuthUserAddResponse) { 261 option (google.api.http) = { 262 post: "/v3/auth/user/add" 263 body: "*" 264 }; 265 } 266 267 // UserGet gets detailed user information. 268 rpc UserGet(AuthUserGetRequest) returns (AuthUserGetResponse) { 269 option (google.api.http) = { 270 post: "/v3/auth/user/get" 271 body: "*" 272 }; 273 } 274 275 // UserList gets a list of all users. 276 rpc UserList(AuthUserListRequest) returns (AuthUserListResponse) { 277 option (google.api.http) = { 278 post: "/v3/auth/user/list" 279 body: "*" 280 }; 281 } 282 283 // UserDelete deletes a specified user. 284 rpc UserDelete(AuthUserDeleteRequest) returns (AuthUserDeleteResponse) { 285 option (google.api.http) = { 286 post: "/v3/auth/user/delete" 287 body: "*" 288 }; 289 } 290 291 // UserChangePassword changes the password of a specified user. 292 rpc UserChangePassword(AuthUserChangePasswordRequest) returns (AuthUserChangePasswordResponse) { 293 option (google.api.http) = { 294 post: "/v3/auth/user/changepw" 295 body: "*" 296 }; 297 } 298 299 // UserGrant grants a role to a specified user. 300 rpc UserGrantRole(AuthUserGrantRoleRequest) returns (AuthUserGrantRoleResponse) { 301 option (google.api.http) = { 302 post: "/v3/auth/user/grant" 303 body: "*" 304 }; 305 } 306 307 // UserRevokeRole revokes a role of specified user. 308 rpc UserRevokeRole(AuthUserRevokeRoleRequest) returns (AuthUserRevokeRoleResponse) { 309 option (google.api.http) = { 310 post: "/v3/auth/user/revoke" 311 body: "*" 312 }; 313 } 314 315 // RoleAdd adds a new role. 316 rpc RoleAdd(AuthRoleAddRequest) returns (AuthRoleAddResponse) { 317 option (google.api.http) = { 318 post: "/v3/auth/role/add" 319 body: "*" 320 }; 321 } 322 323 // RoleGet gets detailed role information. 324 rpc RoleGet(AuthRoleGetRequest) returns (AuthRoleGetResponse) { 325 option (google.api.http) = { 326 post: "/v3/auth/role/get" 327 body: "*" 328 }; 329 } 330 331 // RoleList gets lists of all roles. 332 rpc RoleList(AuthRoleListRequest) returns (AuthRoleListResponse) { 333 option (google.api.http) = { 334 post: "/v3/auth/role/list" 335 body: "*" 336 }; 337 } 338 339 // RoleDelete deletes a specified role. 340 rpc RoleDelete(AuthRoleDeleteRequest) returns (AuthRoleDeleteResponse) { 341 option (google.api.http) = { 342 post: "/v3/auth/role/delete" 343 body: "*" 344 }; 345 } 346 347 // RoleGrantPermission grants a permission of a specified key or range to a specified role. 348 rpc RoleGrantPermission(AuthRoleGrantPermissionRequest) returns (AuthRoleGrantPermissionResponse) { 349 option (google.api.http) = { 350 post: "/v3/auth/role/grant" 351 body: "*" 352 }; 353 } 354 355 // RoleRevokePermission revokes a key or range permission of a specified role. 356 rpc RoleRevokePermission(AuthRoleRevokePermissionRequest) returns (AuthRoleRevokePermissionResponse) { 357 option (google.api.http) = { 358 post: "/v3/auth/role/revoke" 359 body: "*" 360 }; 361 } 362} 363 364message ResponseHeader { 365 // cluster_id is the ID of the cluster which sent the response. 366 uint64 cluster_id = 1; 367 // member_id is the ID of the member which sent the response. 368 uint64 member_id = 2; 369 // revision is the key-value store revision when the request was applied. 370 // For watch progress responses, the header.revision indicates progress. All future events 371 // recieved in this stream are guaranteed to have a higher revision number than the 372 // header.revision number. 373 int64 revision = 3; 374 // raft_term is the raft term when the request was applied. 375 uint64 raft_term = 4; 376} 377 378message RangeRequest { 379 enum SortOrder { 380 NONE = 0; // default, no sorting 381 ASCEND = 1; // lowest target value first 382 DESCEND = 2; // highest target value first 383 } 384 enum SortTarget { 385 KEY = 0; 386 VERSION = 1; 387 CREATE = 2; 388 MOD = 3; 389 VALUE = 4; 390 } 391 392 // key is the first key for the range. If range_end is not given, the request only looks up key. 393 bytes key = 1; 394 // range_end is the upper bound on the requested range [key, range_end). 395 // If range_end is '\0', the range is all keys >= key. 396 // If range_end is key plus one (e.g., "aa"+1 == "ab", "a\xff"+1 == "b"), 397 // then the range request gets all keys prefixed with key. 398 // If both key and range_end are '\0', then the range request returns all keys. 399 bytes range_end = 2; 400 // limit is a limit on the number of keys returned for the request. When limit is set to 0, 401 // it is treated as no limit. 402 int64 limit = 3; 403 // revision is the point-in-time of the key-value store to use for the range. 404 // If revision is less or equal to zero, the range is over the newest key-value store. 405 // If the revision has been compacted, ErrCompacted is returned as a response. 406 int64 revision = 4; 407 408 // sort_order is the order for returned sorted results. 409 SortOrder sort_order = 5; 410 411 // sort_target is the key-value field to use for sorting. 412 SortTarget sort_target = 6; 413 414 // serializable sets the range request to use serializable member-local reads. 415 // Range requests are linearizable by default; linearizable requests have higher 416 // latency and lower throughput than serializable requests but reflect the current 417 // consensus of the cluster. For better performance, in exchange for possible stale reads, 418 // a serializable range request is served locally without needing to reach consensus 419 // with other nodes in the cluster. 420 bool serializable = 7; 421 422 // keys_only when set returns only the keys and not the values. 423 bool keys_only = 8; 424 425 // count_only when set returns only the count of the keys in the range. 426 bool count_only = 9; 427 428 // min_mod_revision is the lower bound for returned key mod revisions; all keys with 429 // lesser mod revisions will be filtered away. 430 int64 min_mod_revision = 10; 431 432 // max_mod_revision is the upper bound for returned key mod revisions; all keys with 433 // greater mod revisions will be filtered away. 434 int64 max_mod_revision = 11; 435 436 // min_create_revision is the lower bound for returned key create revisions; all keys with 437 // lesser create revisions will be filtered away. 438 int64 min_create_revision = 12; 439 440 // max_create_revision is the upper bound for returned key create revisions; all keys with 441 // greater create revisions will be filtered away. 442 int64 max_create_revision = 13; 443} 444 445message RangeResponse { 446 ResponseHeader header = 1; 447 // kvs is the list of key-value pairs matched by the range request. 448 // kvs is empty when count is requested. 449 repeated mvccpb.KeyValue kvs = 2; 450 // more indicates if there are more keys to return in the requested range. 451 bool more = 3; 452 // count is set to the number of keys within the range when requested. 453 int64 count = 4; 454} 455 456message PutRequest { 457 // key is the key, in bytes, to put into the key-value store. 458 bytes key = 1; 459 // value is the value, in bytes, to associate with the key in the key-value store. 460 bytes value = 2; 461 // lease is the lease ID to associate with the key in the key-value store. A lease 462 // value of 0 indicates no lease. 463 int64 lease = 3; 464 465 // If prev_kv is set, etcd gets the previous key-value pair before changing it. 466 // The previous key-value pair will be returned in the put response. 467 bool prev_kv = 4; 468 469 // If ignore_value is set, etcd updates the key using its current value. 470 // Returns an error if the key does not exist. 471 bool ignore_value = 5; 472 473 // If ignore_lease is set, etcd updates the key using its current lease. 474 // Returns an error if the key does not exist. 475 bool ignore_lease = 6; 476} 477 478message PutResponse { 479 ResponseHeader header = 1; 480 // if prev_kv is set in the request, the previous key-value pair will be returned. 481 mvccpb.KeyValue prev_kv = 2; 482} 483 484message DeleteRangeRequest { 485 // key is the first key to delete in the range. 486 bytes key = 1; 487 // range_end is the key following the last key to delete for the range [key, range_end). 488 // If range_end is not given, the range is defined to contain only the key argument. 489 // If range_end is one bit larger than the given key, then the range is all the keys 490 // with the prefix (the given key). 491 // If range_end is '\0', the range is all keys greater than or equal to the key argument. 492 bytes range_end = 2; 493 494 // If prev_kv is set, etcd gets the previous key-value pairs before deleting it. 495 // The previous key-value pairs will be returned in the delete response. 496 bool prev_kv = 3; 497} 498 499message DeleteRangeResponse { 500 ResponseHeader header = 1; 501 // deleted is the number of keys deleted by the delete range request. 502 int64 deleted = 2; 503 // if prev_kv is set in the request, the previous key-value pairs will be returned. 504 repeated mvccpb.KeyValue prev_kvs = 3; 505} 506 507message RequestOp { 508 // request is a union of request types accepted by a transaction. 509 oneof request { 510 RangeRequest request_range = 1; 511 PutRequest request_put = 2; 512 DeleteRangeRequest request_delete_range = 3; 513 TxnRequest request_txn = 4; 514 } 515} 516 517message ResponseOp { 518 // response is a union of response types returned by a transaction. 519 oneof response { 520 RangeResponse response_range = 1; 521 PutResponse response_put = 2; 522 DeleteRangeResponse response_delete_range = 3; 523 TxnResponse response_txn = 4; 524 } 525} 526 527message Compare { 528 enum CompareResult { 529 EQUAL = 0; 530 GREATER = 1; 531 LESS = 2; 532 NOT_EQUAL = 3; 533 } 534 enum CompareTarget { 535 VERSION = 0; 536 CREATE = 1; 537 MOD = 2; 538 VALUE = 3; 539 LEASE = 4; 540 } 541 // result is logical comparison operation for this comparison. 542 CompareResult result = 1; 543 // target is the key-value field to inspect for the comparison. 544 CompareTarget target = 2; 545 // key is the subject key for the comparison operation. 546 bytes key = 3; 547 oneof target_union { 548 // version is the version of the given key 549 int64 version = 4; 550 // create_revision is the creation revision of the given key 551 int64 create_revision = 5; 552 // mod_revision is the last modified revision of the given key. 553 int64 mod_revision = 6; 554 // value is the value of the given key, in bytes. 555 bytes value = 7; 556 // lease is the lease id of the given key. 557 int64 lease = 8; 558 // leave room for more target_union field tags, jump to 64 559 } 560 561 // range_end compares the given target to all keys in the range [key, range_end). 562 // See RangeRequest for more details on key ranges. 563 bytes range_end = 64; 564 // TODO: fill out with most of the rest of RangeRequest fields when needed. 565} 566 567// From google paxosdb paper: 568// Our implementation hinges around a powerful primitive which we call MultiOp. All other database 569// operations except for iteration are implemented as a single call to MultiOp. A MultiOp is applied atomically 570// and consists of three components: 571// 1. A list of tests called guard. Each test in guard checks a single entry in the database. It may check 572// for the absence or presence of a value, or compare with a given value. Two different tests in the guard 573// may apply to the same or different entries in the database. All tests in the guard are applied and 574// MultiOp returns the results. If all tests are true, MultiOp executes t op (see item 2 below), otherwise 575// it executes f op (see item 3 below). 576// 2. A list of database operations called t op. Each operation in the list is either an insert, delete, or 577// lookup operation, and applies to a single database entry. Two different operations in the list may apply 578// to the same or different entries in the database. These operations are executed 579// if guard evaluates to 580// true. 581// 3. A list of database operations called f op. Like t op, but executed if guard evaluates to false. 582message TxnRequest { 583 // compare is a list of predicates representing a conjunction of terms. 584 // If the comparisons succeed, then the success requests will be processed in order, 585 // and the response will contain their respective responses in order. 586 // If the comparisons fail, then the failure requests will be processed in order, 587 // and the response will contain their respective responses in order. 588 repeated Compare compare = 1; 589 // success is a list of requests which will be applied when compare evaluates to true. 590 repeated RequestOp success = 2; 591 // failure is a list of requests which will be applied when compare evaluates to false. 592 repeated RequestOp failure = 3; 593} 594 595message TxnResponse { 596 ResponseHeader header = 1; 597 // succeeded is set to true if the compare evaluated to true or false otherwise. 598 bool succeeded = 2; 599 // responses is a list of responses corresponding to the results from applying 600 // success if succeeded is true or failure if succeeded is false. 601 repeated ResponseOp responses = 3; 602} 603 604// CompactionRequest compacts the key-value store up to a given revision. All superseded keys 605// with a revision less than the compaction revision will be removed. 606message CompactionRequest { 607 // revision is the key-value store revision for the compaction operation. 608 int64 revision = 1; 609 // physical is set so the RPC will wait until the compaction is physically 610 // applied to the local database such that compacted entries are totally 611 // removed from the backend database. 612 bool physical = 2; 613} 614 615message CompactionResponse { 616 ResponseHeader header = 1; 617} 618 619message HashRequest { 620} 621 622message HashKVRequest { 623 // revision is the key-value store revision for the hash operation. 624 int64 revision = 1; 625} 626 627message HashKVResponse { 628 ResponseHeader header = 1; 629 // hash is the hash value computed from the responding member's MVCC keys up to a given revision. 630 uint32 hash = 2; 631 // compact_revision is the compacted revision of key-value store when hash begins. 632 int64 compact_revision = 3; 633} 634 635message HashResponse { 636 ResponseHeader header = 1; 637 // hash is the hash value computed from the responding member's KV's backend. 638 uint32 hash = 2; 639} 640 641message SnapshotRequest { 642} 643 644message SnapshotResponse { 645 // header has the current key-value store information. The first header in the snapshot 646 // stream indicates the point in time of the snapshot. 647 ResponseHeader header = 1; 648 649 // remaining_bytes is the number of blob bytes to be sent after this message 650 uint64 remaining_bytes = 2; 651 652 // blob contains the next chunk of the snapshot in the snapshot stream. 653 bytes blob = 3; 654} 655 656message WatchRequest { 657 // request_union is a request to either create a new watcher or cancel an existing watcher. 658 oneof request_union { 659 WatchCreateRequest create_request = 1; 660 WatchCancelRequest cancel_request = 2; 661 WatchProgressRequest progress_request = 3; 662 } 663} 664 665message WatchCreateRequest { 666 // key is the key to register for watching. 667 bytes key = 1; 668 669 // range_end is the end of the range [key, range_end) to watch. If range_end is not given, 670 // only the key argument is watched. If range_end is equal to '\0', all keys greater than 671 // or equal to the key argument are watched. 672 // If the range_end is one bit larger than the given key, 673 // then all keys with the prefix (the given key) will be watched. 674 bytes range_end = 2; 675 676 // start_revision is an optional revision to watch from (inclusive). No start_revision is "now". 677 int64 start_revision = 3; 678 679 // progress_notify is set so that the etcd server will periodically send a WatchResponse with 680 // no events to the new watcher if there are no recent events. It is useful when clients 681 // wish to recover a disconnected watcher starting from a recent known revision. 682 // The etcd server may decide how often it will send notifications based on current load. 683 bool progress_notify = 4; 684 685 enum FilterType { 686 // filter out put event. 687 NOPUT = 0; 688 // filter out delete event. 689 NODELETE = 1; 690 } 691 692 // filters filter the events at server side before it sends back to the watcher. 693 repeated FilterType filters = 5; 694 695 // If prev_kv is set, created watcher gets the previous KV before the event happens. 696 // If the previous KV is already compacted, nothing will be returned. 697 bool prev_kv = 6; 698 699 // If watch_id is provided and non-zero, it will be assigned to this watcher. 700 // Since creating a watcher in etcd is not a synchronous operation, 701 // this can be used ensure that ordering is correct when creating multiple 702 // watchers on the same stream. Creating a watcher with an ID already in 703 // use on the stream will cause an error to be returned. 704 int64 watch_id = 7; 705 706 // fragment enables splitting large revisions into multiple watch responses. 707 bool fragment = 8; 708} 709 710message WatchCancelRequest { 711 // watch_id is the watcher id to cancel so that no more events are transmitted. 712 int64 watch_id = 1; 713} 714 715// Requests the a watch stream progress status be sent in the watch response stream as soon as 716// possible. 717message WatchProgressRequest { 718} 719 720message WatchResponse { 721 ResponseHeader header = 1; 722 // watch_id is the ID of the watcher that corresponds to the response. 723 int64 watch_id = 2; 724 725 // created is set to true if the response is for a create watch request. 726 // The client should record the watch_id and expect to receive events for 727 // the created watcher from the same stream. 728 // All events sent to the created watcher will attach with the same watch_id. 729 bool created = 3; 730 731 // canceled is set to true if the response is for a cancel watch request. 732 // No further events will be sent to the canceled watcher. 733 bool canceled = 4; 734 735 // compact_revision is set to the minimum index if a watcher tries to watch 736 // at a compacted index. 737 // 738 // This happens when creating a watcher at a compacted revision or the watcher cannot 739 // catch up with the progress of the key-value store. 740 // 741 // The client should treat the watcher as canceled and should not try to create any 742 // watcher with the same start_revision again. 743 int64 compact_revision = 5; 744 745 // cancel_reason indicates the reason for canceling the watcher. 746 string cancel_reason = 6; 747 748 // framgment is true if large watch response was split over multiple responses. 749 bool fragment = 7; 750 751 repeated mvccpb.Event events = 11; 752} 753 754message LeaseGrantRequest { 755 // TTL is the advisory time-to-live in seconds. Expired lease will return -1. 756 int64 TTL = 1; 757 // ID is the requested ID for the lease. If ID is set to 0, the lessor chooses an ID. 758 int64 ID = 2; 759} 760 761message LeaseGrantResponse { 762 ResponseHeader header = 1; 763 // ID is the lease ID for the granted lease. 764 int64 ID = 2; 765 // TTL is the server chosen lease time-to-live in seconds. 766 int64 TTL = 3; 767 string error = 4; 768} 769 770message LeaseRevokeRequest { 771 // ID is the lease ID to revoke. When the ID is revoked, all associated keys will be deleted. 772 int64 ID = 1; 773} 774 775message LeaseRevokeResponse { 776 ResponseHeader header = 1; 777} 778 779message LeaseCheckpoint { 780 // ID is the lease ID to checkpoint. 781 int64 ID = 1; 782 783 // Remaining_TTL is the remaining time until expiry of the lease. 784 int64 remaining_TTL = 2; 785} 786 787message LeaseCheckpointRequest { 788 repeated LeaseCheckpoint checkpoints = 1; 789} 790 791message LeaseCheckpointResponse { 792 ResponseHeader header = 1; 793} 794 795message LeaseKeepAliveRequest { 796 // ID is the lease ID for the lease to keep alive. 797 int64 ID = 1; 798} 799 800message LeaseKeepAliveResponse { 801 ResponseHeader header = 1; 802 // ID is the lease ID from the keep alive request. 803 int64 ID = 2; 804 // TTL is the new time-to-live for the lease. 805 int64 TTL = 3; 806} 807 808message LeaseTimeToLiveRequest { 809 // ID is the lease ID for the lease. 810 int64 ID = 1; 811 // keys is true to query all the keys attached to this lease. 812 bool keys = 2; 813} 814 815message LeaseTimeToLiveResponse { 816 ResponseHeader header = 1; 817 // ID is the lease ID from the keep alive request. 818 int64 ID = 2; 819 // TTL is the remaining TTL in seconds for the lease; the lease will expire in under TTL+1 seconds. 820 int64 TTL = 3; 821 // GrantedTTL is the initial granted time in seconds upon lease creation/renewal. 822 int64 grantedTTL = 4; 823 // Keys is the list of keys attached to this lease. 824 repeated bytes keys = 5; 825} 826 827message LeaseLeasesRequest { 828} 829 830message LeaseStatus { 831 int64 ID = 1; 832 // TODO: int64 TTL = 2; 833} 834 835message LeaseLeasesResponse { 836 ResponseHeader header = 1; 837 repeated LeaseStatus leases = 2; 838} 839 840message Member { 841 // ID is the member ID for this member. 842 uint64 ID = 1; 843 // name is the human-readable name of the member. If the member is not started, the name will be an empty string. 844 string name = 2; 845 // peerURLs is the list of URLs the member exposes to the cluster for communication. 846 repeated string peerURLs = 3; 847 // clientURLs is the list of URLs the member exposes to clients for communication. If the member is not started, clientURLs will be empty. 848 repeated string clientURLs = 4; 849} 850 851message MemberAddRequest { 852 // peerURLs is the list of URLs the added member will use to communicate with the cluster. 853 repeated string peerURLs = 1; 854} 855 856message MemberAddResponse { 857 ResponseHeader header = 1; 858 // member is the member information for the added member. 859 Member member = 2; 860 // members is a list of all members after adding the new member. 861 repeated Member members = 3; 862} 863 864message MemberRemoveRequest { 865 // ID is the member ID of the member to remove. 866 uint64 ID = 1; 867} 868 869message MemberRemoveResponse { 870 ResponseHeader header = 1; 871 // members is a list of all members after removing the member. 872 repeated Member members = 2; 873} 874 875message MemberUpdateRequest { 876 // ID is the member ID of the member to update. 877 uint64 ID = 1; 878 // peerURLs is the new list of URLs the member will use to communicate with the cluster. 879 repeated string peerURLs = 2; 880} 881 882message MemberUpdateResponse{ 883 ResponseHeader header = 1; 884 // members is a list of all members after updating the member. 885 repeated Member members = 2; 886} 887 888message MemberListRequest { 889} 890 891message MemberListResponse { 892 ResponseHeader header = 1; 893 // members is a list of all members associated with the cluster. 894 repeated Member members = 2; 895} 896 897message DefragmentRequest { 898} 899 900message DefragmentResponse { 901 ResponseHeader header = 1; 902} 903 904message MoveLeaderRequest { 905 // targetID is the node ID for the new leader. 906 uint64 targetID = 1; 907} 908 909message MoveLeaderResponse { 910 ResponseHeader header = 1; 911} 912 913enum AlarmType { 914 NONE = 0; // default, used to query if any alarm is active 915 NOSPACE = 1; // space quota is exhausted 916 CORRUPT = 2; // kv store corruption detected 917} 918 919message AlarmRequest { 920 enum AlarmAction { 921 GET = 0; 922 ACTIVATE = 1; 923 DEACTIVATE = 2; 924 } 925 // action is the kind of alarm request to issue. The action 926 // may GET alarm statuses, ACTIVATE an alarm, or DEACTIVATE a 927 // raised alarm. 928 AlarmAction action = 1; 929 // memberID is the ID of the member associated with the alarm. If memberID is 0, the 930 // alarm request covers all members. 931 uint64 memberID = 2; 932 // alarm is the type of alarm to consider for this request. 933 AlarmType alarm = 3; 934} 935 936message AlarmMember { 937 // memberID is the ID of the member associated with the raised alarm. 938 uint64 memberID = 1; 939 // alarm is the type of alarm which has been raised. 940 AlarmType alarm = 2; 941} 942 943message AlarmResponse { 944 ResponseHeader header = 1; 945 // alarms is a list of alarms associated with the alarm request. 946 repeated AlarmMember alarms = 2; 947} 948 949message StatusRequest { 950} 951 952message StatusResponse { 953 ResponseHeader header = 1; 954 // version is the cluster protocol version used by the responding member. 955 string version = 2; 956 // dbSize is the size of the backend database physically allocated, in bytes, of the responding member. 957 int64 dbSize = 3; 958 // leader is the member ID which the responding member believes is the current leader. 959 uint64 leader = 4; 960 // raftIndex is the current raft committed index of the responding member. 961 uint64 raftIndex = 5; 962 // raftTerm is the current raft term of the responding member. 963 uint64 raftTerm = 6; 964 // raftAppliedIndex is the current raft applied index of the responding member. 965 uint64 raftAppliedIndex = 7; 966 // errors contains alarm/health information and status. 967 repeated string errors = 8; 968 // dbSizeInUse is the size of the backend database logically in use, in bytes, of the responding member. 969 int64 dbSizeInUse = 9; 970} 971 972message AuthEnableRequest { 973} 974 975message AuthDisableRequest { 976} 977 978message AuthenticateRequest { 979 string name = 1; 980 string password = 2; 981} 982 983message AuthUserAddRequest { 984 string name = 1; 985 string password = 2; 986} 987 988message AuthUserGetRequest { 989 string name = 1; 990} 991 992message AuthUserDeleteRequest { 993 // name is the name of the user to delete. 994 string name = 1; 995} 996 997message AuthUserChangePasswordRequest { 998 // name is the name of the user whose password is being changed. 999 string name = 1; 1000 // password is the new password for the user. 1001 string password = 2; 1002} 1003 1004message AuthUserGrantRoleRequest { 1005 // user is the name of the user which should be granted a given role. 1006 string user = 1; 1007 // role is the name of the role to grant to the user. 1008 string role = 2; 1009} 1010 1011message AuthUserRevokeRoleRequest { 1012 string name = 1; 1013 string role = 2; 1014} 1015 1016message AuthRoleAddRequest { 1017 // name is the name of the role to add to the authentication system. 1018 string name = 1; 1019} 1020 1021message AuthRoleGetRequest { 1022 string role = 1; 1023} 1024 1025message AuthUserListRequest { 1026} 1027 1028message AuthRoleListRequest { 1029} 1030 1031message AuthRoleDeleteRequest { 1032 string role = 1; 1033} 1034 1035message AuthRoleGrantPermissionRequest { 1036 // name is the name of the role which will be granted the permission. 1037 string name = 1; 1038 // perm is the permission to grant to the role. 1039 authpb.Permission perm = 2; 1040} 1041 1042message AuthRoleRevokePermissionRequest { 1043 string role = 1; 1044 bytes key = 2; 1045 bytes range_end = 3; 1046} 1047 1048message AuthEnableResponse { 1049 ResponseHeader header = 1; 1050} 1051 1052message AuthDisableResponse { 1053 ResponseHeader header = 1; 1054} 1055 1056message AuthenticateResponse { 1057 ResponseHeader header = 1; 1058 // token is an authorized token that can be used in succeeding RPCs 1059 string token = 2; 1060} 1061 1062message AuthUserAddResponse { 1063 ResponseHeader header = 1; 1064} 1065 1066message AuthUserGetResponse { 1067 ResponseHeader header = 1; 1068 1069 repeated string roles = 2; 1070} 1071 1072message AuthUserDeleteResponse { 1073 ResponseHeader header = 1; 1074} 1075 1076message AuthUserChangePasswordResponse { 1077 ResponseHeader header = 1; 1078} 1079 1080message AuthUserGrantRoleResponse { 1081 ResponseHeader header = 1; 1082} 1083 1084message AuthUserRevokeRoleResponse { 1085 ResponseHeader header = 1; 1086} 1087 1088message AuthRoleAddResponse { 1089 ResponseHeader header = 1; 1090} 1091 1092message AuthRoleGetResponse { 1093 ResponseHeader header = 1; 1094 1095 repeated authpb.Permission perm = 2; 1096} 1097 1098message AuthRoleListResponse { 1099 ResponseHeader header = 1; 1100 1101 repeated string roles = 2; 1102} 1103 1104message AuthUserListResponse { 1105 ResponseHeader header = 1; 1106 1107 repeated string users = 2; 1108} 1109 1110message AuthRoleDeleteResponse { 1111 ResponseHeader header = 1; 1112} 1113 1114message AuthRoleGrantPermissionResponse { 1115 ResponseHeader header = 1; 1116} 1117 1118message AuthRoleRevokePermissionResponse { 1119 ResponseHeader header = 1; 1120} 1121