Crate zenoh_backend_traits

⚠️ 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::prelude::r#async::*;
use zenoh::time::Timestamp;
use zenoh_backend_traits::*;
use zenoh_backend_traits::config::*;
use zenoh::Result as ZResult;

#[no_mangle]
pub fn create_volume(config: VolumeConfig) -> ZResult<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,
            read_cost: 0,
        }
    }

    async fn create_storage(&self, properties: StorageConfig) -> ZResult<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?))
    }

    fn incoming_data_interceptor(&self) -> Option<Arc<dyn Fn(Sample) -> Sample + Send + Sync>> {
        // No interception point for incoming data (on PUT operations)
        None
    }

    fn outgoing_data_interceptor(&self) -> Option<Arc<dyn Fn(Sample) -> Sample + Send + Sync>> {
        // No interception point for outgoing data (on GET operations)
        None
    }
}

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

impl MyStorage {
    async fn new(config: StorageConfig) -> ZResult<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>, value: Value, timestamp: Timestamp) -> ZResult<StorageInsertionResult> {
        // the key will be None if it exactly matched with the strip_prefix
        // create a storge 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) -> ZResult<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) -> ZResult<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) -> ZResult<Vec<(Option<OwnedKeyExpr>, Timestamp)>> {
        // @TODO: get the list of (key, timestamp) in the datastore
        Ok(Vec::new())
    }
}

Modules

• config

Structs

• Capability
  Capability of a storage indicates the guarantees of the storage It is used by the storage manager to take decisions on the trade-offs to ensure correct performance
• Query
  A wrapper around the zenoh::queryable::Query allowing to call the OutgoingDataInterceptor (if any) before to send the reply
• StoredData

Enums

• History
  History is the number of values that the backend is expected to save per key History::Latest saves only the latest value per key History::All saves all the values including historical values
• Persistence
  Persistence is the guarantee expected from a storage in case of failures If a storage is marked Persistent::Durable, if it restarts after a crash, it will still have all the values that were saved. This will include also persisting the metadata that Zenoh stores for the updates. If a storage is marked Persistent::Volatile, the storage will not have any guarantees on its content after a crash. This option should be used only if the storage is considered to function as a cache.
• StorageInsertionResult

Traits

• Storage
  Trait to be implemented by a Storage.
• Volume
  Trait to be implemented by a Backend.

Type Aliases

• VolumeInstance
• ZResult