Merge pull request #4 from G8XSU/keys-summary-m

Add ListKeysSummary Api Signature/protos

Author: G8XSU

app/src/main/proto/vss.proto

@@ -9,7 +9,7 @@ message GetObjectRequest {
   // All APIs operate within a single store_id.
   // It is up to clients to use single or multiple stores for their use-case.
   // This can be used for client-isolation/ rate-limiting / throttling on the server-side.
-  // Authorization and billing can also be performed at the storeId level.
+  // Authorization and billing can also be performed at the store_id level.
   string store_id = 1;
 
   // Key for which the value is to be fetched.
@@ -98,6 +98,78 @@ message PutObjectRequest {
 message PutObjectResponse {
 }
 
+message ListKeyVersionsRequest {
+
+  // store_id is a keyspace identifier.
+  // Ref: https://en.wikipedia.org/wiki/Keyspace_(distributed_data_store)
+  // All APIs operate within a single store_id.
+  // It is up to clients to use single or multiple stores for their use-case.
+  // This can be used for client-isolation/ rate-limiting / throttling on the server-side.
+  // Authorization and billing can also be performed at the store_id level.
+  string store_id = 1;
+
+  // A key_prefix is a string of characters at the beginning of the key. Prefixes can be used as
+  // a way to organize key-values in a similar way to directories.
+  //
+  // If key_prefix is specified, the response results will be limited to those keys that begin with
+  // the specified prefix.
+  //
+  // If no key_prefix is specified or it is empty (""), all the keys are eligible to be returned in
+  // the response.
+  optional string key_prefix = 2;
+
+  // page_size is used by clients to specify the maximum number of results that can be returned by
+  // the server.
+  // The server may further constrain the maximum number of results returned in a single page.
+  // If the page_size is 0 or not set, the server will decide the number of results to be returned.
+  optional int32 page_size = 3;
+
+  // page_token is a pagination token.
+  //
+  // To query for the first page of ListKeyVersions, page_token must not be specified.
+  //
+  // For subsequent pages, use the value that was returned as `next_page_token` in the previous
+  // page's ListKeyVersionsResponse.
+  optional string page_token = 4;
+}
+
+message ListKeyVersionsResponse {
+
+  // Fetched keys and versions.
+  // Even though this API reuses KeyValue struct, the value sub-field will not be set by the server.
+  repeated KeyValue key_versions = 1;
+
+  // next_page_token is a pagination token, used to retrieve the next page of results.
+  // Use this value to query for next_page of paginated ListKeyVersions operation, by specifying
+  // this value as the `page_token` in the next request.
+  //
+  // If next_page_token is empty (""), then the "last page" of results has been processed and
+  // there is no more data to be retrieved.
+  //
+  // If next_page_token is not empty, it does not necessarily mean that there is more data in the
+  // result set. The only way to know when you have reached the end of the result set is when
+  // next_page_token is empty.
+  //
+  // Caution: Clients must not assume a specific number of key_versions to be present in a page for
+  // paginated response.
+  optional string next_page_token = 2;
+
+  // global_version is a sequence-number/version of the whole store.
+  //
+  // global_version is only returned in response for the first page of the ListKeyVersionsResponse
+  // and is guaranteed to be read before reading any key-versions.
+  //
+  // In case of refreshing the complete key-version view on the client-side, correct usage for
+  // the returned global_version is as following:
+  //   1. Read global_version from the first page of paginated response and save it as local variable.
+  //   2. Update all the key_versions on client-side from all the pages of paginated response.
+  //   3. Update global_version on client_side from the local variable saved in step-1.
+  // This ensures that on client-side, all current key_versions were stored at global_version or later.
+  // This guarantee is helpful for ensuring the versioning correctness if using the global_version
+  // in PutObject API and can help avoid the race conditions related to it.
+  optional int64 global_version = 3;
+}
+
 // When HttpStatusCode is not ok (200), the response `content` contains a serialized ErrorResponse
 // with the relevant ErrorCode and message
 message ErrorResponse {