Skip to content

Consistently add ticks around identifiers #16

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 17, 2023
Merged

Consistently add ticks around identifiers #16

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
152 changes: 76 additions & 76 deletions app/src/main/proto/vss.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,103 +6,103 @@ 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;
}

// 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:
Expand All @@ -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;
}

Expand All @@ -149,79 +149,79 @@ 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;
}

// Server response for `ListKeyVersions` API.
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.
Expand All @@ -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:
Expand All @@ -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).
Expand Down