Skip to content

Commit 58976ce

Browse files
G8XSUG8XSU
committed
Update generated types acc. to latest vss-server api
1 parent 02d2616 commit 58976ce

File tree

2 files changed

+117
-65
lines changed

2 files changed

+117
-65
lines changed

‎build.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ fn main() {
1414
#[cfg(feature = "genproto")]
1515
fn generate_protos() {
1616
download_file(
17-
"https://raw.githubusercontent.com/lightningdevkit/vss-server/ff4b5fc6a079ed8719eb8be7ec35ca1d01c1cc55/app/src/main/proto/vss.proto",
17+
"https://raw.githubusercontent.com/lightningdevkit/vss-server/ac646dd419bc70db2b79772b1bfa1b2d9a4b8b53/app/src/main/proto/vss.proto",
1818
"src/proto/vss.proto",
1919
).unwrap();
2020

‎src/types.rs‎

Lines changed: 116 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -1,178 +1,229 @@
1+
/// Request payload to be used for `GetObject` API call to server.
12
#[allow(clippy::derive_partial_eq_without_eq)]
23
#[derive(Clone, PartialEq, ::prost::Message)]
34
pub struct GetObjectRequest {
4-
/// store_id is a keyspace identifier.
5+
/// `store_id` is a keyspace identifier.
56
/// Ref: <https://en.wikipedia.org/wiki/Keyspace_(distributed_data_store>)
6-
/// All APIs operate within a single store_id.
7+
/// All APIs operate within a single `store_id`.
78
/// It is up to clients to use single or multiple stores for their use-case.
89
/// This can be used for client-isolation/ rate-limiting / throttling on the server-side.
9-
/// Authorization and billing can also be performed at the store_id level.
10+
/// Authorization and billing can also be performed at the `store_id` level.
1011
#[prost(string, tag = "1")]
1112
pub store_id: ::prost::alloc::string::String,
12-
/// Key for which the value is to be fetched.
13+
/// `Key` for which the value is to be fetched.
1314
///
1415
/// Consistency Guarantee:
15-
/// Get(read) operations against a key are consistent reads and will reflect all previous writes,
16+
/// Get(read) operations against a `key` are consistent reads and will reflect all previous writes,
1617
/// since Put/Write provides read-after-write and read-after-update consistency guarantees.
1718
///
1819
/// Read Isolation:
19-
/// Get/Read operations against a key are ensured to have read-committed isolation.
20+
/// Get/Read operations against a `key` are ensured to have read-committed isolation.
2021
/// Ref: <https://en.wikipedia.org/wiki/Isolation_(database_systems>)#Read_committed
2122
#[prost(string, tag = "2")]
2223
pub key: ::prost::alloc::string::String,
2324
}
25+
/// Server response for `GetObject` API.
2426
#[allow(clippy::derive_partial_eq_without_eq)]
2527
#[derive(Clone, PartialEq, ::prost::Message)]
2628
pub struct GetObjectResponse {
27-
/// Fetched value and version along with the corresponding key in the request.
29+
/// Fetched `value` and `version` along with the corresponding `key` in the request.
2830
#[prost(message, optional, tag = "2")]
2931
pub value: ::core::option::Option<KeyValue>,
3032
}
33+
/// Request payload to be used for `PutObject` API call to server.
3134
#[allow(clippy::derive_partial_eq_without_eq)]
3235
#[derive(Clone, PartialEq, ::prost::Message)]
3336
pub struct PutObjectRequest {
34-
/// store_id is a keyspace identifier.
37+
/// `store_id` is a keyspace identifier.
3538
/// Ref: <https://en.wikipedia.org/wiki/Keyspace_(distributed_data_store>)
36-
/// All APIs operate within a single store_id.
39+
/// All APIs operate within a single `store_id`.
3740
/// It is up to clients to use single or multiple stores for their use-case.
3841
/// This can be used for client-isolation/ rate-limiting / throttling on the server-side.
39-
/// Authorization and billing can also be performed at the store_id level.
42+
/// Authorization and billing can also be performed at the `store_id` level.
4043
#[prost(string, tag = "1")]
4144
pub store_id: ::prost::alloc::string::String,
42-
/// global_version is a sequence-number/version of the whole store. This can be used for versioning
45+
/// `global_version` is a sequence-number/version of the whole store. This can be used for versioning
4346
/// and ensures that multiple updates in case of multiple devices can only be done linearly, even
44-
/// if those updates did not directly conflict with each other based on keys/transaction_items.
47+
/// if those updates did not directly conflict with each other based on keys/`transaction_items`.
4548
///
46-
/// If present, the write will only succeed if the current server-side global_version against
47-
/// the store_id is same as in the request.
48-
/// Clients are expected to store (client-side) the global version against store_id.
49-
/// The request must contain their client-side value of global_version if global versioning and
49+
/// If present, the write will only succeed if the current server-side `global_version` against
50+
/// the `store_id` is same as in the request.
51+
/// Clients are expected to store (client-side) the global version against `store_id`.
52+
/// The request must contain their client-side value of `global_version` if global versioning and
5053
/// conflict detection is desired.
5154
///
5255
/// For the first write of the store, global version should be '0'. If the write succeeds, clients
5356
/// must increment their global version (client-side) by 1.
54-
/// The server increments global_version (server-side) for every successful write, hence this
57+
/// The server increments `global_version` (server-side) for every successful write, hence this
5558
/// client-side increment is required to ensure matching versions. This updated global version
56-
/// should be used in subsequent PutObjectRequests for the store.
59+
/// should be used in subsequent `PutObjectRequest`s for the store.
5760
///
5861
/// Requests with a conflicting version will fail with `CONFLICT_EXCEPTION` as ErrorCode.
5962
#[prost(int64, optional, tag = "2")]
6063
pub global_version: ::core::option::Option<i64>,
61-
/// Items to be written as a result of this PutObjectRequest.
64+
/// Items to be written as a result of this `PutObjectRequest`.
6265
///
63-
/// In an item, each key is supplied with its corresponding value and version.
66+
/// In an item, each `key` is supplied with its corresponding `value` and `version`.
6467
/// Clients can choose to encrypt the keys client-side in order to obfuscate their usage patterns.
65-
/// If the write is successful, the previous value corresponding to the key will be overwritten.
68+
/// If the write is successful, the previous `value` corresponding to the `key` will be overwritten.
6669
///
67-
/// Multiple items in transaction_items of a single PutObjectRequest are written in
70+
/// Multiple items in `transaction_items` and `delete_items` of a single `PutObjectRequest` are written in
6871
/// a database-transaction in an all-or-nothing fashion.
69-
/// Items in a single PutObjectRequest must have distinct keys.
72+
/// All Items in a single `PutObjectRequest` must have distinct keys.
7073
///
71-
/// Clients are expected to store a version against every key.
72-
/// The write will succeed if the current DB version against the key is the same as in the request.
73-
/// When initiating a PutObjectRequest, the request should contain their client-side version for
74+
/// Clients are expected to store a `version` against every `key`.
75+
/// The write will succeed if the current DB version against the `key` is the same as in the request.
76+
/// When initiating a `PutObjectRequest`, the request should contain their client-side version for
7477
/// that key-value.
7578
///
76-
/// For the first write of any key, the version should be '0'. If the write succeeds, the client
79+
/// For the first write of any key, the `version` should be '0'. If the write succeeds, the client
7780
/// must increment their corresponding key versions (client-side) by 1.
7881
/// The server increments key versions (server-side) for every successful write, hence this
7982
/// client-side increment is required to ensure matching versions. These updated key versions should
80-
/// be used in subsequent PutObjectRequests for the keys.
83+
/// be used in subsequent `PutObjectRequest`s for the keys.
8184
///
8285
/// Requests with a conflicting version will fail with `CONFLICT_EXCEPTION` as ErrorCode.
8386
///
8487
/// Considerations for transactions:
8588
/// Transaction writes of multiple items have a performance overhead, hence it is recommended to use
8689
/// them only if required by the client application to ensure logic/code correctness.
87-
/// That is, transaction_items are not a substitute for batch-write of multiple unrelated items.
90+
/// That is, `transaction_items` are not a substitute for batch-write of multiple unrelated items.
8891
/// When a write of multiple unrelated items is desired, it is recommended to use separate
89-
/// PutObjectRequests.
92+
/// `PutObjectRequest`s.
9093
///
9194
/// Consistency guarantee:
92-
/// All PutObjectRequests are strongly consistent i.e. they provide read-after-write and
95+
/// All `PutObjectRequest`s are strongly consistent i.e. they provide read-after-write and
9396
/// read-after-update consistency guarantees.
9497
#[prost(message, repeated, tag = "3")]
9598
pub transaction_items: ::prost::alloc::vec::Vec<KeyValue>,
99+
/// Items to be deleted as a result of this `PutObjectRequest`.
100+
///
101+
/// Each item in the `delete_items` field consists of a `key` and its corresponding `version`.
102+
/// The `version` is used to perform a version check before deleting the item.
103+
/// The delete will only succeed if the current database version against the `key` is the same as the `version`
104+
/// specified in the request.
105+
///
106+
/// Fails with `CONFLICT_EXCEPTION` as the ErrorCode if:
107+
/// * The requested item does not exist.
108+
/// * The requested item does exist but there is a version-number mismatch with the one in the database.
109+
///
110+
/// Multiple items in the `delete_items` field, along with the `transaction_items`, are written in a
111+
/// database transaction in an all-or-nothing fashion.
112+
///
113+
/// All items within a single `PutObjectRequest` must have distinct keys.
114+
#[prost(message, repeated, tag = "4")]
115+
pub delete_items: ::prost::alloc::vec::Vec<KeyValue>,
96116
}
117+
/// Server response for `PutObject` API.
97118
#[allow(clippy::derive_partial_eq_without_eq)]
98119
#[derive(Clone, PartialEq, ::prost::Message)]
99120
pub struct PutObjectResponse {}
121+
/// Request payload to be used for `DeleteObject` API call to server.
122+
#[allow(clippy::derive_partial_eq_without_eq)]
123+
#[derive(Clone, PartialEq, ::prost::Message)]
124+
pub struct DeleteObjectRequest {
125+
/// `store_id` is a keyspace identifier.
126+
/// Ref: <https://en.wikipedia.org/wiki/Keyspace_(distributed_data_store>)
127+
/// All APIs operate within a single `store_id`.
128+
/// It is up to clients to use single or multiple stores for their use-case.
129+
/// This can be used for client-isolation/ rate-limiting / throttling on the server-side.
130+
/// Authorization and billing can also be performed at the `store_id` level.
131+
#[prost(string, tag = "1")]
132+
pub store_id: ::prost::alloc::string::String,
133+
/// Item to be deleted as a result of this `DeleteObjectRequest`.
134+
///
135+
/// An item consists of a `key` and its corresponding `version`.
136+
/// The item is only deleted if the current database version against the `key` is the same as the `version`
137+
/// specified in the request.
138+
/// This operation is idempotent, that is, multiple delete calls for the same item will not fail.
139+
///
140+
/// If the requested item does not exist, this operation will not fail.
141+
/// If you wish to perform stricter checks while deleting an item, consider using `PutObject` API.
142+
#[prost(message, optional, tag = "2")]
143+
pub key_value: ::core::option::Option<KeyValue>,
144+
}
145+
/// Server response for `DeleteObject` API.
146+
#[allow(clippy::derive_partial_eq_without_eq)]
147+
#[derive(Clone, PartialEq, ::prost::Message)]
148+
pub struct DeleteObjectResponse {}
149+
/// Request payload to be used for `ListKeyVersions` API call to server.
100150
#[allow(clippy::derive_partial_eq_without_eq)]
101151
#[derive(Clone, PartialEq, ::prost::Message)]
102152
pub struct ListKeyVersionsRequest {
103-
/// store_id is a keyspace identifier.
153+
/// `store_id` is a keyspace identifier.
104154
/// Ref: <https://en.wikipedia.org/wiki/Keyspace_(distributed_data_store>)
105-
/// All APIs operate within a single store_id.
155+
/// All APIs operate within a single `store_id`.
106156
/// It is up to clients to use single or multiple stores for their use-case.
107157
/// This can be used for client-isolation/ rate-limiting / throttling on the server-side.
108-
/// Authorization and billing can also be performed at the store_id level.
158+
/// Authorization and billing can also be performed at the `store_id` level.
109159
#[prost(string, tag = "1")]
110160
pub store_id: ::prost::alloc::string::String,
111-
/// A key_prefix is a string of characters at the beginning of the key. Prefixes can be used as
161+
/// A `key_prefix` is a string of characters at the beginning of the key. Prefixes can be used as
112162
/// a way to organize key-values in a similar way to directories.
113163
///
114-
/// If key_prefix is specified, the response results will be limited to those keys that begin with
164+
/// If `key_prefix` is specified, the response results will be limited to those keys that begin with
115165
/// the specified prefix.
116166
///
117-
/// If no key_prefix is specified or it is empty (""), all the keys are eligible to be returned in
167+
/// If no `key_prefix` is specified or it is empty (""), all the keys are eligible to be returned in
118168
/// the response.
119169
#[prost(string, optional, tag = "2")]
120170
pub key_prefix: ::core::option::Option<::prost::alloc::string::String>,
121-
/// page_size is used by clients to specify the maximum number of results that can be returned by
171+
/// `page_size` is used by clients to specify the maximum number of results that can be returned by
122172
/// the server.
123173
/// The server may further constrain the maximum number of results returned in a single page.
124-
/// If the page_size is 0 or not set, the server will decide the number of results to be returned.
174+
/// If the `page_size` is 0 or not set, the server will decide the number of results to be returned.
125175
#[prost(int32, optional, tag = "3")]
126176
pub page_size: ::core::option::Option<i32>,
127-
/// page_token is a pagination token.
177+
/// `page_token` is a pagination token.
128178
///
129-
/// To query for the first page of ListKeyVersions, page_token must not be specified.
179+
/// To query for the first page of `ListKeyVersions`, `page_token` must not be specified.
130180
///
131181
/// For subsequent pages, use the value that was returned as `next_page_token` in the previous
132-
/// page's ListKeyVersionsResponse.
182+
/// page's `ListKeyVersionsResponse`.
133183
#[prost(string, optional, tag = "4")]
134184
pub page_token: ::core::option::Option<::prost::alloc::string::String>,
135185
}
186+
/// Server response for `ListKeyVersions` API.
136187
#[allow(clippy::derive_partial_eq_without_eq)]
137188
#[derive(Clone, PartialEq, ::prost::Message)]
138189
pub struct ListKeyVersionsResponse {
139190
/// Fetched keys and versions.
140-
/// Even though this API reuses KeyValue struct, the value sub-field will not be set by the server.
191+
/// Even though this API reuses the `KeyValue` struct, the `value` sub-field will not be set by the server.
141192
#[prost(message, repeated, tag = "1")]
142193
pub key_versions: ::prost::alloc::vec::Vec<KeyValue>,
143-
/// next_page_token is a pagination token, used to retrieve the next page of results.
144-
/// Use this value to query for next_page of paginated ListKeyVersions operation, by specifying
194+
/// `next_page_token` is a pagination token, used to retrieve the next page of results.
195+
/// Use this value to query for next-page of paginated `ListKeyVersions` operation, by specifying
145196
/// this value as the `page_token` in the next request.
146197
///
147-
/// If next_page_token is empty (""), then the "last page" of results has been processed and
198+
/// If `next_page_token` is empty (""), then the "last page" of results has been processed and
148199
/// there is no more data to be retrieved.
149200
///
150-
/// If next_page_token is not empty, it does not necessarily mean that there is more data in the
201+
/// If `next_page_token` is not empty, it does not necessarily mean that there is more data in the
151202
/// result set. The only way to know when you have reached the end of the result set is when
152-
/// next_page_token is empty.
203+
/// `next_page_token` is empty.
153204
///
154205
/// Caution: Clients must not assume a specific number of key_versions to be present in a page for
155206
/// paginated response.
156207
#[prost(string, optional, tag = "2")]
157208
pub next_page_token: ::core::option::Option<::prost::alloc::string::String>,
158-
/// global_version is a sequence-number/version of the whole store.
209+
/// `global_version` is a sequence-number/version of the whole store.
159210
///
160-
/// global_version is only returned in response for the first page of the ListKeyVersionsResponse
211+
/// `global_version` is only returned in response for the first page of the `ListKeyVersionsResponse`
161212
/// and is guaranteed to be read before reading any key-versions.
162213
///
163214
/// In case of refreshing the complete key-version view on the client-side, correct usage for
164-
/// the returned global_version is as following:
165-
/// 1. Read global_version from the first page of paginated response and save it as local variable.
166-
/// 2. Update all the key_versions on client-side from all the pages of paginated response.
167-
/// 3. Update global_version on client_side from the local variable saved in step-1.
168-
/// This ensures that on client-side, all current key_versions were stored at global_version or later.
169-
/// This guarantee is helpful for ensuring the versioning correctness if using the global_version
170-
/// in PutObject API and can help avoid the race conditions related to it.
215+
/// the returned `global_version` is as following:
216+
/// 1. Read `global_version` from the first page of paginated response and save it as local variable.
217+
/// 2. Update all the `key_versions` on client-side from all the pages of paginated response.
218+
/// 3. Update `global_version` on client_side from the local variable saved in step-1.
219+
/// This ensures that on client-side, all current `key_versions` were stored at `global_version` or later.
220+
/// This guarantee is helpful for ensuring the versioning correctness if using the `global_version`
221+
/// in `PutObject` API and can help avoid the race conditions related to it.
171222
#[prost(int64, optional, tag = "3")]
172223
pub global_version: ::core::option::Option<i64>,
173224
}
174-
/// When HttpStatusCode is not ok (200), the response `content` contains a serialized ErrorResponse
175-
/// with the relevant ErrorCode and message
225+
/// When HttpStatusCode is not ok (200), the response `content` contains a serialized `ErrorResponse`
226+
/// with the relevant `ErrorCode` and `message`
176227
#[allow(clippy::derive_partial_eq_without_eq)]
177228
#[derive(Clone, PartialEq, ::prost::Message)]
178229
pub struct ErrorResponse {
@@ -187,18 +238,19 @@ pub struct ErrorResponse {
187238
#[prost(string, tag = "2")]
188239
pub message: ::prost::alloc::string::String,
189240
}
241+
/// Represents a key-value pair to be stored or retrieved.
190242
#[allow(clippy::derive_partial_eq_without_eq)]
191243
#[derive(Clone, PartialEq, ::prost::Message)]
192244
pub struct KeyValue {
193245
/// Key against which the value is stored.
194246
#[prost(string, tag = "1")]
195247
pub key: ::prost::alloc::string::String,
196248
/// Version field is used for key-level versioning.
197-
/// For first write of key, version should be '0'. If the write succeeds, clients must increment
249+
/// For first write of key, `version` should be '0'. If the write succeeds, clients must increment
198250
/// their corresponding key version (client-side) by 1.
199251
/// The server increments key version (server-side) for every successful write, hence this
200252
/// client-side increment is required to ensure matching versions. These updated key versions should
201-
/// be used in subsequent PutObjectRequests for the keys.
253+
/// be used in subsequent `PutObjectRequest`s for the keys.
202254
#[prost(int64, tag = "2")]
203255
pub version: i64,
204256
/// Object value in bytes which is stored (in put) and fetched (in get).
@@ -207,14 +259,14 @@ pub struct KeyValue {
207259
#[prost(bytes = "vec", tag = "3")]
208260
pub value: ::prost::alloc::vec::Vec<u8>,
209261
}
210-
/// ErrorCodes to be used in ErrorResponse
262+
/// ErrorCodes to be used in `ErrorResponse`
211263
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, ::prost::Enumeration)]
212264
#[repr(i32)]
213265
pub enum ErrorCode {
214-
/// Default protobuf Enum value. Will not be used as ErrorCode by server.
266+
/// Default protobuf Enum value. Will not be used as `ErrorCode` by server.
215267
Unknown = 0,
216268
/// CONFLICT_EXCEPTION is used when the request contains mismatched version (either key or global)
217-
/// in PutObjectRequest. For more info refer PutObjectRequest.
269+
/// in `PutObjectRequest`. For more info refer `PutObjectRequest`.
218270
ConflictException = 1,
219271
/// INVALID_REQUEST_EXCEPTION is used in the following cases:
220272
/// - The request was missing a required argument.

0 commit comments

Comments
 (0)