vss.proto

syntax = "proto3";
package vss;
option java_multiple_files = true;
option java_package = "org.vss";

// Request payload to be used for `GetObject` API call to server.
message GetObjectRequest {

  // `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;

  // The key of the value to be fetched.
  //
  // If the specified `key` does not exist, returns `ErrorCode.NO_SUCH_KEY_EXCEPTION` in the
  // the `ErrorResponse`.
  //
  // Consistency Guarantee:
  // 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.
  // 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.
  KeyValue value = 2;
}

// Request payload to be used for `PutObject` API call to server.
message PutObjectRequest {

  // `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;

  // `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 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
  // client-side increment is required to ensure matching versions. This updated global version
  // 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`.
  //
  // 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.
  //
  // 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.
  //
  // Key-level versioning (Conditional Write):
  //   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
  //   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 `PutObjectRequest`s for the keys.
  //
  //   Requests with a conflicting/mismatched version will fail with `CONFLICT_EXCEPTION` as ErrorCode
  //   for conditional writes.
  //
  // Skipping key-level versioning (Non-conditional Write):
  //   If you wish to skip key-level version checks, set the `version` against the `key` to '-1'.
  //   This will perform a non-conditional write query, after which the `version` against the `key`
  //   is reset to '1'. Hence, the next `PutObjectRequest` for the `key` can be either
  //   a non-conditional write or a conditional write with `version` set to `1`.
  //
  // 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.
  // When a write of multiple unrelated items is desired, it is recommended to use separate
  // `PutObjectRequest`s.
  //
  // Consistency guarantee:
  // 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`.
  //
  // Each item in the `delete_items` field consists of a `key` and its corresponding `version`.
  //
  // Key-Level Versioning (Conditional Delete):
  //   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.
  //
  // Skipping key-level versioning (Non-conditional Delete):
  //   If you wish to skip key-level version checks, set the `version` against the `key` to '-1'.
  //   This will perform a non-conditional delete query.
  //
  // Fails with `CONFLICT_EXCEPTION` as the ErrorCode if:
  //   * The requested item does not exist.
  //   * The requested item does exist but there is a version-number mismatch (in conditional delete)
  //     with the one in the database.
  //
  // Multiple items in the `delete_items` field, along with the `transaction_items`, are written in a
  // database transaction in an all-or-nothing fashion.
  //
  // All items within a single `PutObjectRequest` must have distinct keys.
  repeated KeyValue delete_items = 4;
}

// Server response for `PutObject` API.
message PutObjectResponse {
}

// Request payload to be used for `DeleteObject` API call to server.
message DeleteObjectRequest {
  // `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;

  // Item to be deleted as a result of this `DeleteObjectRequest`.
  //
  // An item consists of a `key` and its corresponding `version`.
  //
  // Key-level Versioning (Conditional Delete):
  //   The item is only deleted if the current database version against the `key` is the same as
  //   the `version` specified in the request.
  //
  // Skipping key-level versioning (Non-conditional Delete):
  //   If you wish to skip key-level version checks, set the `version` against the `key` to '-1'.
  //   This will perform a non-conditional delete query.
  //
  // 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.
  KeyValue key_value = 2;
}

// Server response for `DeleteObject` API.
message DeleteObjectResponse{
}

// Request payload to be used for `ListKeyVersions` API call to server.
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;
}

// Server response for `ListKeyVersions` API.
message ListKeyVersionsResponse {

  // Fetched keys and versions.
  // 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
  // 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 {

  // The error code uniquely identifying an error condition.
  // It is meant to be read and understood programmatically by code that detects/handles errors by
  // type.
  ErrorCode error_code = 1;

  // The error message containing a generic description of the error condition in English.
  // It is intended for a human audience only and should not be parsed to extract any information
  // programmatically. Client-side code may use it for logging only.
  string message = 2;
}

// ErrorCodes to be used in `ErrorResponse`
enum ErrorCode {

  // Default protobuf Enum value. Will not be used as `ErrorCode` by server.
  UNKNOWN = 0;

  // Used when the request contains mismatched version (either key or global)
  // in `PutObjectRequest`. For more info refer `PutObjectRequest`.
  CONFLICT_EXCEPTION = 1;

  // Used in the following cases:
  //   - The request was missing a required argument.
  //   - The specified argument was invalid, incomplete or in the wrong format.
  //   - The request body of api cannot be deserialized into corresponding protobuf object.
  INVALID_REQUEST_EXCEPTION = 2;

  // Used when an internal server error occurred, client is probably at no fault and can safely retry
  // this error with exponential backoff.
  INTERNAL_SERVER_EXCEPTION = 3;

  // Used when the specified `key` in a `GetObjectRequest` does not exist.
  NO_SUCH_KEY_EXCEPTION = 4;

  // Used when authentication fails or in case of an unauthorized request.
  AUTH_EXCEPTION = 5;
}

// 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
  // 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 `PutObjectRequest`s for the keys.
  int64 version = 2;

  // Object value in bytes which is stored (in put) and fetched (in get).
  // Clients must encrypt the secret contents of this blob client-side before sending it over the
  // wire to the server in order to preserve privacy and security.
  // Clients may use a `Storable` object, serialize it and set it here.
  bytes value = 3;
}

// Represents a storable object that can be serialized and stored as `value` in `PutObjectRequest`.
// Only provided as a helper object for ease of use by clients.
// Clients MUST encrypt the `PlaintextBlob` before using it as `data` in `Storable`.
// The server does not use or read anything from `Storable`, Clients may use its fields as
// required.
message Storable {

  // Represents an encrypted and serialized `PlaintextBlob`. MUST encrypt the whole `PlaintextBlob`
  // using client-side encryption before setting here.
  bytes data = 1;

  // Represents encryption related metadata
  EncryptionMetadata encryption_metadata = 2;
}

// Represents encryption related metadata
message EncryptionMetadata {
  // The encryption algorithm used for encrypting the `PlaintextBlob`.
  string cipher_format = 1;

  // The nonce used for encryption. Nonce is a random or unique value used to ensure that the same
  // plaintext results in different ciphertexts every time it is encrypted.
  bytes nonce = 2;

  // The authentication tag used for encryption. It provides integrity and authenticity assurance
  // for the encrypted data.
  bytes tag = 3;
}

// Represents a data blob, which is encrypted, serialized and later used in `Storable.data`.
// Since the whole `Storable.data` is client-side encrypted, the server cannot understand this.
message PlaintextBlob {

  // The unencrypted value.
  bytes value = 1;

  // The version of the value. Can be used by client to verify version integrity.
  int64 version = 2;
}