⚠️ WARNING ⚠️

TODO: The example is outdated, rewrite it

This crate should be considered unstable, as in we might change the APIs anytime.

This crate provides the traits to be implemented by a zenoh backend library:

• Volume
• Storage

Such library must also declare a create_volume() operation with the #[no_mangle] attribute as an entrypoint to be called for the Backend creation.

Example

use std::sync::Arc;
use async_trait::async_trait;
use zenoh::{key_expr::OwnedKeyExpr, time::Timestamp, bytes::{ZBytes, Encoding}};
use zenoh_backend_traits::*;
use zenoh_backend_traits::config::*;

#[no_mangle]
pub fn create_volume(config: VolumeConfig) -> zenoh::Result<Box<dyn Volume>> {
    Ok(Box::new(MyVolumeType { config }))
}

// Your Backend implementation
struct MyVolumeType {
    config: VolumeConfig,
}

#[async_trait]
impl Volume for MyVolumeType {
    fn get_admin_status(&self) -> serde_json::Value {
        // This operation is called on GET operation on the admin space for the Volume
        // Here we reply with a static status (containing the configuration properties).
        // But we could add dynamic properties for Volume monitoring.
        self.config.to_json_value()
    }

    fn get_capability(&self) -> Capability {
        // This operation is used to confirm if the volume indeed supports
        // the capabilities requested by the configuration
        Capability{
            persistence: Persistence::Volatile,
            history: History::Latest,
        }
    }

    async fn create_storage(&self, properties: StorageConfig) -> zenoh::Result<Box<dyn Storage>> {
        // The properties are the ones passed via a PUT in the admin space for Storage creation.
        Ok(Box::new(MyStorage::new(properties).await?))
    }
}

// Your Storage implementation
struct MyStorage {
    config: StorageConfig,
}

impl MyStorage {
    async fn new(config: StorageConfig) -> zenoh::Result<MyStorage> {
        Ok(MyStorage { config })
    }
}

#[async_trait]
impl Storage for MyStorage {
    fn get_admin_status(&self) -> serde_json::Value {
        // This operation is called on GET operation on the admin space for the Storage
        // Here we reply with a static status (containing the configuration properties).
        // But we could add dynamic properties for Storage monitoring.
        self.config.to_json_value()
    }

    async fn put(&mut self, key: Option<OwnedKeyExpr>, payload: ZBytes, encoding: Encoding, timestamp: Timestamp) -> zenoh::Result<StorageInsertionResult> {
        // the key will be None if it exactly matched with the strip_prefix
        // create a storage specific special structure to store it
        // Store the data with timestamp
        // @TODO:
        // store (key, value, timestamp)
        return Ok(StorageInsertionResult::Inserted);
        //  - if any issue: drop
        // return Ok(StorageInsertionResult::Outdated);
    }

    async fn delete(&mut self, key: Option<OwnedKeyExpr>, timestamp: Timestamp) -> zenoh::Result<StorageInsertionResult> {
        // @TODO:
        // delete the actual entry from storage
        return Ok(StorageInsertionResult::Deleted);
    }

    // When receiving a GET operation
    async fn get(&mut self, key_expr: Option<OwnedKeyExpr>, parameters: &str) -> zenoh::Result<Vec<StoredData>> {
        // @TODO:
        // get the data associated with key_expr and return it
        // NOTE: in case parameters is not empty something smarter should be done with returned data...
        Ok(Vec::new())
    }

    // To get all entries in the datastore
    async fn get_all_entries(&self) -> zenoh::Result<Vec<(Option<OwnedKeyExpr>, Timestamp)>> {
        // @TODO: get the list of (key, timestamp) in the datastore
        Ok(Vec::new())
    }
}

⚠️ WARNING ⚠️

This crate is intended for Zenoh's internal use. It is not guaranteed that the API will remain unchanged in any version, including patch updates. It is highly recommended to depend solely on the zenoh and zenoh-ext crates and to utilize their public APIs.

• Click here for Zenoh's main repository
• Click here for Zenoh's documentation