diff --git a/build.rs b/build.rs index 594b631..09e2db9 100644 --- a/build.rs +++ b/build.rs @@ -14,7 +14,7 @@ fn main() { #[cfg(feature = "genproto")] fn generate_protos() { download_file( - "https://raw.githubusercontent.com/lightningdevkit/vss-server/ac646dd419bc70db2b79772b1bfa1b2d9a4b8b53/app/src/main/proto/vss.proto", + "https://raw.githubusercontent.com/lightningdevkit/vss-server/e1a88afd61f56d7e8e90a32036ca12389e36fe44/app/src/main/proto/vss.proto", "src/proto/vss.proto", ).unwrap(); diff --git a/src/types.rs b/src/types.rs index f30140d..252e3aa 100644 --- a/src/types.rs +++ b/src/types.rs @@ -71,18 +71,26 @@ pub struct PutObjectRequest { /// a database-transaction in an all-or-nothing fashion. /// 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 - /// 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. + /// 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. /// - /// Requests with a conflicting version will fail with `CONFLICT_EXCEPTION` as ErrorCode. + /// 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 @@ -99,13 +107,20 @@ pub struct 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` - /// specified in the request. + /// + /// 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 with the one in the database. + /// * 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. @@ -133,8 +148,15 @@ pub struct 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` - /// specified in the request. + /// + /// 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.