Crate zenoh_backend_traits

Source
Expand description

⚠️ 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:

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())
    }
}

Modules§

Structs§

  • 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

Enums§

  • 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 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.

Traits§

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

Type Aliases§