From b8d6352275998c292d0979df7c25c36ec714fb5e Mon Sep 17 00:00:00 2001 From: Gursharan Singh <3442979+G8XSU@users.noreply.github.com> Date: Sun, 6 Aug 2023 19:19:49 -0700 Subject: [PATCH] Consistently add ticks around identifiers --- app/src/main/proto/vss.proto | 152 +++++++++++++++++------------------ 1 file changed, 76 insertions(+), 76 deletions(-) diff --git a/app/src/main/proto/vss.proto b/app/src/main/proto/vss.proto index 2ce6c90..b110ac2 100644 --- a/app/src/main/proto/vss.proto +++ b/app/src/main/proto/vss.proto @@ -6,22 +6,22 @@ option java_package = "org.vss"; // Request payload to be used for `GetObject` API call to server. message GetObjectRequest { - // store_id is a keyspace identifier. + // `store_id` is a keyspace identifier. // Ref: https://en.wikipedia.org/wiki/Keyspace_(distributed_data_store) - // All APIs operate within a single store_id. + // 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. + // 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. + // `Key` for which the value is to be fetched. // // Consistency Guarantee: - // Get(read) operations against a key are consistent reads and will reflect all previous writes, + // Get(read) operations against a `key` are consistent reads and will reflect all previous writes, // since Put/Write provides read-after-write and read-after-update consistency guarantees. // // Read Isolation: - // Get/Read operations against a key are ensured to have read-committed isolation. + // Get/Read operations against a `key` are ensured to have read-committed isolation. // Ref: https://en.wikipedia.org/wiki/Isolation_(database_systems)#Read_committed string key = 2; } @@ -29,80 +29,80 @@ message GetObjectRequest { // Server response for `GetObject` API. message GetObjectResponse { - // Fetched value and version along with the corresponding key in the request. + // Fetched `value` and `version` along with the corresponding `key` in the request. KeyValue value = 2; } // Request payload to be used for `PutObject` API call to server. message PutObjectRequest { - // store_id is a keyspace identifier. + // `store_id` is a keyspace identifier. // Ref: https://en.wikipedia.org/wiki/Keyspace_(distributed_data_store) - // All APIs operate within a single store_id. + // 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. + // Authorization and billing can also be performed at the `store_id` level. string store_id = 1; - // global_version is a sequence-number/version of the whole store. This can be used for versioning + // `global_version` is a sequence-number/version of the whole store. This can be used for versioning // and ensures that multiple updates in case of multiple devices can only be done linearly, even - // if those updates did not directly conflict with each other based on keys/transaction_items. + // if those updates did not directly conflict with each other based on keys/`transaction_items`. // - // If present, the write will only succeed if the current server-side global_version against - // the store_id is same as in the request. - // Clients are expected to store (client-side) the global version against store_id. - // The request must contain their client-side value of global_version if global versioning and + // If present, the write will only succeed if the current server-side `global_version` against + // the `store_id` is same as in the request. + // Clients are expected to store (client-side) the global version against `store_id`. + // The request must contain their client-side value of `global_version` if global versioning and // conflict detection is desired. // // For the first write of the store, global version should be '0'. If the write succeeds, clients // must increment their global version (client-side) by 1. - // The server increments global_version (server-side) for every successful write, hence this + // The server increments `global_version` (server-side) for every successful write, hence this // client-side increment is required to ensure matching versions. This updated global version - // should be used in subsequent PutObjectRequests for the store. + // should be used in subsequent `PutObjectRequest`s for the store. // // Requests with a conflicting version will fail with `CONFLICT_EXCEPTION` as ErrorCode. optional int64 global_version = 2; - // Items to be written as a result of this PutObjectRequest. + // Items to be written as a result of this `PutObjectRequest`. // - // In an item, each key is supplied with its corresponding value and version. + // In an item, each `key` is supplied with its corresponding `value` and `version`. // Clients can choose to encrypt the keys client-side in order to obfuscate their usage patterns. - // If the write is successful, the previous value corresponding to the key will be overwritten. + // If the write is successful, the previous `value` corresponding to the `key` will be overwritten. // - // Multiple items in transaction_items and delete_items of a single PutObjectRequest are written in + // Multiple items in `transaction_items` and `delete_items` of a single `PutObjectRequest` are written in // a database-transaction in an all-or-nothing fashion. - // All Items in a single PutObjectRequest must have distinct keys. + // All Items in a single `PutObjectRequest` must have distinct keys. // - // Clients are expected to store a version against every key. - // The write will succeed if the current DB version against the key is the same as in the request. - // When initiating a PutObjectRequest, the request should contain their client-side version for + // Clients are expected to store a `version` against every `key`. + // The write will succeed if the current DB version against the `key` is the same as in the request. + // When initiating a `PutObjectRequest`, the request should contain their client-side version for // that key-value. // - // For the first write of any key, the version should be '0'. If the write succeeds, the client + // For the first write of any key, the `version` should be '0'. If the write succeeds, the client // must increment their corresponding key versions (client-side) by 1. // The server increments key versions (server-side) for every successful write, hence this // client-side increment is required to ensure matching versions. These updated key versions should - // be used in subsequent PutObjectRequests for the keys. + // be used in subsequent `PutObjectRequest`s for the keys. // // Requests with a conflicting version will fail with `CONFLICT_EXCEPTION` as ErrorCode. // // Considerations for transactions: // Transaction writes of multiple items have a performance overhead, hence it is recommended to use // them only if required by the client application to ensure logic/code correctness. - // That is, transaction_items are not a substitute for batch-write of multiple unrelated items. + // That is, `transaction_items` are not a substitute for batch-write of multiple unrelated items. // When a write of multiple unrelated items is desired, it is recommended to use separate - // PutObjectRequests. + // `PutObjectRequest`s. // // Consistency guarantee: - // All PutObjectRequests are strongly consistent i.e. they provide read-after-write and + // All `PutObjectRequest`s are strongly consistent i.e. they provide read-after-write and // read-after-update consistency guarantees. repeated KeyValue transaction_items = 3; - // Items to be deleted as a result of this PutObjectRequest. + // Items to be deleted as a result of this `PutObjectRequest`. // - // Each item in the `delete_items` field consists of a key and its corresponding version. - // The version is used to perform a version check before deleting the item. - // The delete will only succeed if the current database version against the key is the same as the version + // Each item in the `delete_items` field consists of a `key` and its corresponding `version`. + // The `version` is used to perform a version check before deleting the item. + // The delete will only succeed if the current database version against the `key` is the same as the `version` // specified in the request. // // Fails with `CONFLICT_EXCEPTION` as the ErrorCode if: @@ -122,23 +122,23 @@ message PutObjectResponse { // Request payload to be used for `DeleteObject` API call to server. message DeleteObjectRequest { - // store_id is a keyspace identifier. + // `store_id` is a keyspace identifier. // Ref: https://en.wikipedia.org/wiki/Keyspace_(distributed_data_store) - // All APIs operate within a single store_id. + // 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. + // Authorization and billing can also be performed at the `store_id` level. string store_id = 1; - // Item to be deleted as a result of this DeleteObjectRequest. + // Item to be deleted as a result of this `DeleteObjectRequest`. // - // An item consists of a key and its corresponding version. - // The item is only deleted if the current database version against the key is the same as the version + // An item consists of a `key` and its corresponding `version`. + // The item is only deleted if the current database version against the `key` is the same as the `version` // specified in the request. // This operation is idempotent, that is, multiple delete calls for the same item will not fail. // // If the requested item does not exist, this operation will not fail. - // If you wish to perform stricter checks while deleting an item, consider using PutObject API. + // If you wish to perform stricter checks while deleting an item, consider using `PutObject` API. KeyValue key_value = 2; } @@ -149,36 +149,36 @@ message DeleteObjectResponse{ // Request payload to be used for `ListKeyVersions` API call to server. message ListKeyVersionsRequest { - // store_id is a keyspace identifier. + // `store_id` is a keyspace identifier. // Ref: https://en.wikipedia.org/wiki/Keyspace_(distributed_data_store) - // All APIs operate within a single store_id. + // 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. + // 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 `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 + // 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 + // 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 + // `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. + // 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. + // `page_token` is a pagination token. // - // To query for the first page of ListKeyVersions, page_token must not be specified. + // 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. + // page's `ListKeyVersionsResponse`. optional string page_token = 4; } @@ -186,42 +186,42 @@ message ListKeyVersionsRequest { message ListKeyVersionsResponse { // Fetched keys and versions. - // Even though this API reuses KeyValue struct, the value sub-field will not be set by the server. + // Even though this API reuses the `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 + // `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 + // 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 + // 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. + // `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 a sequence-number/version of the whole store. // - // global_version is only returned in response for the first page of the ListKeyVersionsResponse + // `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. + // 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 +// When HttpStatusCode is not ok (200), the response `content` contains a serialized `ErrorResponse` +// with the relevant `ErrorCode` and `message` message ErrorResponse { // The error code uniquely identifying an error condition. @@ -235,14 +235,14 @@ message ErrorResponse { string message = 2; } -// ErrorCodes to be used in ErrorResponse +// ErrorCodes to be used in `ErrorResponse` enum ErrorCode { - // Default protobuf Enum value. Will not be used as ErrorCode by server. + // Default protobuf Enum value. Will not be used as `ErrorCode` by server. UNKNOWN = 0; // CONFLICT_EXCEPTION is used when the request contains mismatched version (either key or global) - // in PutObjectRequest. For more info refer PutObjectRequest. + // in `PutObjectRequest`. For more info refer `PutObjectRequest`. CONFLICT_EXCEPTION= 1; // INVALID_REQUEST_EXCEPTION is used in the following cases: @@ -256,18 +256,18 @@ enum ErrorCode { INTERNAL_SERVER_EXCEPTION = 3; } -// Represents KeyValue pair to be stored or retrieved. +// Represents a key-value pair to be stored or retrieved. message KeyValue { // Key against which the value is stored. string key = 1; // Version field is used for key-level versioning. - // For first write of key, version should be '0'. If the write succeeds, clients must increment + // For first write of key, `version` should be '0'. If the write succeeds, clients must increment // their corresponding key version (client-side) by 1. // The server increments key version (server-side) for every successful write, hence this // client-side increment is required to ensure matching versions. These updated key versions should - // be used in subsequent PutObjectRequests for the keys. + // be used in subsequent `PutObjectRequest`s for the keys. int64 version = 2; // Object value in bytes which is stored (in put) and fetched (in get).