feat: sdk improvements

Author: evansims

crates/sdk/src/client.rs

@@ -1753,6 +1753,32 @@ impl Operation {
 }
 
 impl SetCondition {
+    /// Creates a condition for compare-and-set operations from an expected
+    /// previous value.
+    ///
+    /// - `None` → [`SetCondition::NotExists`] (create-if-absent)
+    /// - `Some(value)` → [`SetCondition::ValueEquals`] (update-if-unchanged)
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use inferadb_ledger_sdk::SetCondition;
+    ///
+    /// // Insert only if key doesn't exist
+    /// let cond = SetCondition::from_expected(None::<Vec<u8>>);
+    /// assert!(matches!(cond, SetCondition::NotExists));
+    ///
+    /// // Update only if current value matches
+    /// let cond = SetCondition::from_expected(Some(b"old-value".to_vec()));
+    /// assert!(matches!(cond, SetCondition::ValueEquals(_)));
+    /// ```
+    pub fn from_expected(expected: Option<impl Into<Vec<u8>>>) -> Self {
+        match expected {
+            None => SetCondition::NotExists,
+            Some(value) => SetCondition::ValueEquals(value.into()),
+        }
+    }
+
     /// Converts to protobuf set condition.
     fn to_proto(&self) -> proto::SetCondition {
         let condition = match self {
@@ -3191,7 +3217,7 @@ impl LedgerClient {
     // Single-Operation Convenience Methods
     // =============================================================================
 
-    /// Writes a single entity (set).
+    /// Writes a single entity (set), optionally with an expiration timestamp.
     ///
     /// Convenience wrapper around [`write`](Self::write) for the common case of
     /// setting a single key-value pair. Generates an idempotency key
@@ -3203,6 +3229,8 @@ impl LedgerClient {
     /// * `vault` - Optional vault slug (omit for organization-level entities).
     /// * `key` - The entity key.
     /// * `value` - The entity value.
+    /// * `expires_at` - Optional Unix timestamp (seconds) when the entity expires. Pass `None` for
+    ///   no expiration.
     ///
     /// # Errors
     ///
@@ -3216,8 +3244,14 @@ impl LedgerClient {
     /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
     /// # let client = LedgerClient::connect("http://localhost:50051", "my-service").await?;
     /// # let (organization, vault) = (OrganizationSlug::new(1), VaultSlug::new(1));
+    /// // Without expiration:
     /// let result = client
-    ///     .set_entity(organization, Some(vault), "user:123", b"data".to_vec())
+    ///     .set_entity(organization, Some(vault), "user:123", b"data".to_vec(), None)
+    ///     .await?;
+    ///
+    /// // With expiration:
+    /// let result = client
+    ///     .set_entity(organization, Some(vault), "session:abc", b"token".to_vec(), Some(1700000000))
     ///     .await?;
     /// # Ok(())
     /// # }
@@ -3228,8 +3262,14 @@ impl LedgerClient {
         vault: Option<VaultSlug>,
         key: impl Into<String>,
         value: Vec<u8>,
+        expires_at: Option<u64>,
     ) -> Result<WriteSuccess> {
-        self.write(organization, vault, vec![Operation::set_entity(key, value)]).await
+        self.write(
+            organization,
+            vault,
+            vec![Operation::SetEntity { key: key.into(), value, expires_at, condition: None }],
+        )
+        .await
     }
 
     /// Deletes a single entity.
@@ -3268,7 +3308,7 @@ impl LedgerClient {
         self.write(organization, vault, vec![Operation::delete_entity(key)]).await
     }
 
-    /// Sets a single entity with a conditional write.
+    /// Sets a single entity with a conditional write, optionally with an expiration timestamp.
     ///
     /// Convenience wrapper around [`write`](Self::write) for conditional
     /// set operations (compare-and-swap). The write only succeeds if the
@@ -3281,6 +3321,8 @@ impl LedgerClient {
     /// * `key` - The entity key.
     /// * `value` - The entity value.
     /// * `condition` - The condition that must be satisfied for the write to succeed.
+    /// * `expires_at` - Optional Unix timestamp (seconds) when the entity expires. Pass `None` for
+    ///   no expiration.
     ///
     /// # Errors
     ///
@@ -3301,6 +3343,7 @@ impl LedgerClient {
     ///         "user:123",
     ///         b"new-data".to_vec(),
     ///         SetCondition::NotExists,
+    ///         None,
     ///     )
     ///     .await?;
     /// # Ok(())
@@ -3313,61 +3356,17 @@ impl LedgerClient {
         key: impl Into<String>,
         value: Vec<u8>,
         condition: SetCondition,
-    ) -> Result<WriteSuccess> {
-        self.write(organization, vault, vec![Operation::set_entity_if(key, value, condition)]).await
-    }
-
-    /// Sets a single entity with an expiration timestamp.
-    ///
-    /// Convenience wrapper around [`write`](Self::write) for setting a
-    /// key-value pair with a TTL. The entity is automatically removed after
-    /// the expiration time.
-    ///
-    /// # Arguments
-    ///
-    /// * `organization` - Organization slug (external identifier).
-    /// * `vault` - Optional vault slug (omit for organization-level entities).
-    /// * `key` - The entity key.
-    /// * `value` - The entity value.
-    /// * `expires_at` - Unix timestamp (seconds) when the entity expires.
-    ///
-    /// # Errors
-    ///
-    /// Returns an error if validation fails or the write fails after retry
-    /// attempts.
-    ///
-    /// # Example
-    ///
-    /// ```no_run
-    /// # use inferadb_ledger_sdk::{LedgerClient, OrganizationSlug, VaultSlug};
-    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
-    /// # let client = LedgerClient::connect("http://localhost:50051", "my-service").await?;
-    /// # let (organization, vault) = (OrganizationSlug::new(1), VaultSlug::new(1));
-    /// let expires_at = 1700000000; // Unix timestamp
-    /// let result = client
-    ///     .set_entity_with_expiry(
-    ///         organization,
-    ///         Some(vault),
-    ///         "session:abc",
-    ///         b"session-data".to_vec(),
-    ///         expires_at,
-    ///     )
-    ///     .await?;
-    /// # Ok(())
-    /// # }
-    /// ```
-    pub async fn set_entity_with_expiry(
-        &self,
-        organization: OrganizationSlug,
-        vault: Option<VaultSlug>,
-        key: impl Into<String>,
-        value: Vec<u8>,
-        expires_at: u64,
+        expires_at: Option<u64>,
     ) -> Result<WriteSuccess> {
         self.write(
             organization,
             vault,
-            vec![Operation::set_entity_with_expiry(key, value, expires_at)],
+            vec![Operation::SetEntity {
+                key: key.into(),
+                value,
+                expires_at,
+                condition: Some(condition),
+            }],
         )
         .await
     }
@@ -5769,6 +5768,31 @@ mod tests {
         }
     }
 
+    #[test]
+    fn test_set_condition_from_expected_none() {
+        let cond = SetCondition::from_expected(None::<Vec<u8>>);
+        assert!(matches!(cond, SetCondition::NotExists));
+    }
+
+    #[test]
+    fn test_set_condition_from_expected_some_vec() {
+        let cond = SetCondition::from_expected(Some(b"old-value".to_vec()));
+        match cond {
+            SetCondition::ValueEquals(v) => assert_eq!(v, b"old-value"),
+            other => panic!("Expected ValueEquals, got: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn test_set_condition_from_expected_some_slice() {
+        let slice: &[u8] = b"expected";
+        let cond = SetCondition::from_expected(Some(slice.to_vec()));
+        match cond {
+            SetCondition::ValueEquals(v) => assert_eq!(v, b"expected"),
+            other => panic!("Expected ValueEquals, got: {other:?}"),
+        }
+    }
+
     // =========================================================================
     // WriteSuccess Tests
     // =========================================================================

crates/sdk/src/error.rs

@@ -432,6 +432,30 @@ impl SdkError {
         }
     }
 
+    /// Returns `true` if the error represents a CAS (compare-and-set)
+    /// conflict — the precondition check failed because the entity was
+    /// modified since it was last read.
+    ///
+    /// This matches only [`Code::FailedPrecondition`], which the server
+    /// returns when a [`SetCondition`](crate::SetCondition) evaluates to
+    /// false. Use this to distinguish CAS conflicts from other error types
+    /// without importing [`tonic::Code`] at call sites.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # use inferadb_ledger_sdk::SdkError;
+    /// # fn example(err: SdkError) {
+    /// if err.is_cas_conflict() {
+    ///     // Re-read current value and retry the compare-and-set
+    /// }
+    /// # }
+    /// ```
+    #[must_use]
+    pub fn is_cas_conflict(&self) -> bool {
+        matches!(self, Self::Rpc { code: Code::FailedPrecondition, .. })
+    }
+
     /// Returns a short classification string for this error, suitable for
     /// use as a metrics label.
     #[must_use]
@@ -1397,4 +1421,43 @@ mod tests {
         }
         assert!(err.is_retryable());
     }
+
+    #[test]
+    fn test_is_cas_conflict_failed_precondition() {
+        let err = SdkError::Rpc {
+            code: Code::FailedPrecondition,
+            message: "condition not met".to_owned(),
+            request_id: None,
+            trace_id: None,
+            error_details: None,
+        };
+        assert!(err.is_cas_conflict());
+    }
+
+    #[test]
+    fn test_is_cas_conflict_aborted_is_false() {
+        let err = SdkError::Rpc {
+            code: Code::Aborted,
+            message: "transaction conflict".to_owned(),
+            request_id: None,
+            trace_id: None,
+            error_details: None,
+        };
+        assert!(!err.is_cas_conflict());
+    }
+
+    #[test]
+    fn test_is_cas_conflict_other_errors_are_false() {
+        let err = SdkError::Connection { message: "network down".to_owned() };
+        assert!(!err.is_cas_conflict());
+
+        let err = SdkError::Rpc {
+            code: Code::NotFound,
+            message: "not found".to_owned(),
+            request_id: None,
+            trace_id: None,
+            error_details: None,
+        };
+        assert!(!err.is_cas_conflict());
+    }
 }

crates/sdk/src/mock.rs

@@ -2166,8 +2166,10 @@ mod tests {
             let server = MockLedgerServer::start().await.unwrap();
             let client = create_client_for_mock(&server).await;
 
-            let result =
-                client.set_entity(ORG, Some(VAULT), "entity:1", b"data".to_vec()).await.unwrap();
+            let result = client
+                .set_entity(ORG, Some(VAULT), "entity:1", b"data".to_vec(), None)
+                .await
+                .unwrap();
 
             assert!(!result.tx_id.is_empty());
             assert_eq!(
@@ -2201,6 +2203,7 @@ mod tests {
                     "cond:1",
                     b"value".to_vec(),
                     crate::SetCondition::NotExists,
+                    None,
                 )
                 .await
                 .unwrap();
@@ -2218,7 +2221,7 @@ mod tests {
             let client = create_client_for_mock(&server).await;
 
             let result = client
-                .set_entity_with_expiry(ORG, Some(VAULT), "ttl:1", b"temp".to_vec(), 1_700_000_000)
+                .set_entity(ORG, Some(VAULT), "ttl:1", b"temp".to_vec(), Some(1_700_000_000))
                 .await
                 .unwrap();
 
@@ -2229,6 +2232,30 @@ mod tests {
             );
         }
 
+        #[tokio::test]
+        async fn test_set_entity_if_with_expiry_convenience() {
+            let server = MockLedgerServer::start().await.unwrap();
+            let client = create_client_for_mock(&server).await;
+
+            let result = client
+                .set_entity_if(
+                    ORG,
+                    Some(VAULT),
+                    "cond_ttl:1",
+                    b"conditional-temp".to_vec(),
+                    crate::SetCondition::NotExists,
+                    Some(1_700_000_000),
+                )
+                .await
+                .unwrap();
+
+            assert!(!result.tx_id.is_empty());
+            assert_eq!(
+                client.read(ORG, Some(VAULT), "cond_ttl:1").await.unwrap(),
+                Some(b"conditional-temp".to_vec())
+            );
+        }
+
         // ==================== Idempotency ====================
 
         #[tokio::test]