pdk-data-storage-lib 1.7.0

// Copyright (c) 2026, Salesforce, Inc.,
// All rights reserved.
// For full license text, see the LICENSE.txt file

//! Distributed storage abstraction and client
//!
//! This module defines the high-level [`DistributedStorage`] trait and exposes the
//! default client implementation to interact with a distributed key-value store
//! used by policies. It provides primitives to create stores, list partitions/keys,
//! and perform CRUD operations with Compare-And-Swap (CAS) support.
//!
//! The concrete client [`DistributedStorageClient`] is injectable via the
//! configuration context and should be used when interacting with the platform
//! shared storage service.
//!
pub use crate::distributed::client::DistributedStorageClient;
pub use crate::distributed::error::DistributedStorageError;
pub use crate::distributed::model::{Store, StoreMode};

#[cfg(feature = "ll")]
pub use crate::distributed::client::DistributedStorageClientExtractionError;

mod client;
mod error;
mod model;

#[allow(async_fn_in_trait, dead_code)]
/// Trait describing a distributed storage client.
pub trait DistributedStorage {
    /// Creates or updates a store.
    async fn upsert_store(&self, store: &Store) -> Result<(), DistributedStorageError>;

    /// Retrieves a list of stores.
    async fn get_stores(&self) -> Result<Vec<Store>, DistributedStorageError>;

    /// Retrieves a list of keys in a given partition.
    async fn get_keys(
        &self,
        store: &str,
        partition: &str,
    ) -> Result<Vec<String>, DistributedStorageError>;

    /// Retrieves a list of partitions in a given store.
    async fn get_partitions(&self, store: &str) -> Result<Vec<String>, DistributedStorageError>;

    /// Stores an item in a partition.
    async fn store(
        &self,
        store: &str,
        partition: &str,
        key: &str,
        mode: &StoreMode,
        item: &[u8],
    ) -> Result<(), DistributedStorageError>;

    /// Returns the value and its CAS by its key in a given partition.
    async fn get(
        &self,
        store: &str,
        partition: &str,
        key: &str,
    ) -> Result<(Vec<u8>, String), DistributedStorageError>;

    /// Deletes an object by its key in a given partition.
    async fn delete(
        &self,
        store: &str,
        partition: &str,
        key: &str,
    ) -> Result<(), DistributedStorageError>;

    /// Deletes all objects in a given partition.
    async fn delete_partition(
        &self,
        store: &str,
        partition: &str,
    ) -> Result<(), DistributedStorageError>;
}