anachro_client/

table.rs

//! The Client Table Interface
//!
//! This module contains items used for defining pubsub tables, which
//! are the primary way of specifying the topics that the client is
//! interested in publishing or subscribing to.
//!
//! Each client may define their own table of publish and subscribe topics,
//! or may use a table defined by a common shared library. Different clients
//! do not need to have the same table, but for successful operation, all
//! clients must agree on the same data type used for a given path or wildcard
//! path topic.

use anachro_icd::arbitrator::SubMsg;
use postcard;

/// An error type used by the `Table` trait
#[derive(Debug, PartialEq, Eq)]
pub enum TableError {
    NoMatch,
    Postcard(postcard::Error),
}

/// A trait describing publish and subscription topics
///
/// This is used to interact with the `Client` interface.
pub trait Table: Sized {
    /// A slice of all paths that the client subscribes to
    fn sub_paths() -> &'static [&'static str];

    /// A slice of all paths that the client publishes to
    fn pub_paths() -> &'static [&'static str];

    /// Create a Table item from a given SubMsg`
    fn from_pub_sub<'a>(msg: &'a SubMsg<'a>) -> Result<Self, TableError>;
}

/// A macro for defining a publish and subscribe table
///
/// This macro assists with generating a table that defines publish
/// and subscription topics that implement the `Table` trait.
///
/// The first argument is the name of the table type. For "Subs" and "Pubs"
/// sections, the format `Variant Name: "pub/sub/path" => Variant Type` is
/// used. All Variant Names must be unique in the table. All Variant Types
/// must implement `serde::Serialize`, `serde::de::DeserializeOwned`, and
/// `Clone`.
///
/// All paths must be unique, and wildcard patterns must not overlap with
/// other wildcards or fixed paths. Publish topics must not include wildcards.
///
/// ## Example
///
/// ```rust,no_run
/// pubsub_table!{
///     AnachroTable,
///     Subs => {
///         Something: "foo/bar/baz" => Demo,
///         Else: "bib/bim/bap" => (),
///     },
///     Pubs => {
///         Etwas: "short/send" => (),
///         Anders: "send/short" => (),
///     },
/// }
#[macro_export]
macro_rules! pubsub_table {
    (
        $enum_ty:ident,
        Subs => {
            $($sub_variant_name:ident: $sub_path:expr => $sub_variant_ty:ty,)+
        },
        Pubs => {
            $($pub_variant_name:ident: $pub_path:expr => $pub_variant_ty:ty,)+
        },
    ) => {
        #[doc="
            An Anachro Protocol Client Table

            This is an Anachro Protocol Client Table generated by the
            `pubsub_table!()` macro.
        "]
        #[derive(Debug, serde::Deserialize, Clone)]
        pub enum $enum_ty {
            $($sub_variant_name($sub_variant_ty)),+,
            $($pub_variant_name($pub_variant_ty)),+,
        }

        impl $crate::Table for $enum_ty {
            fn from_pub_sub<'a>(msg: &'a $crate::SubMsg<'a>) -> core::result::Result<Self, $crate::TableError> {
                let msg_path = match msg.path {
                    $crate::anachro_icd::PubSubPath::Long(ref path) => path.as_str(),
                    $crate::anachro_icd::PubSubPath::Short(sid) => {
                        if sid < $crate::PUBLISH_SHORTCODE_OFFSET {
                            // Subscribe
                            if (sid as usize) < Self::sub_paths().len() {
                                Self::sub_paths()[(sid as usize)]
                            } else {
                                return Err($crate::TableError::NoMatch);
                            }
                        } else {
                            // publish
                            let new_sid = (sid as usize) - ($crate::PUBLISH_SHORTCODE_OFFSET as usize);
                            if new_sid < Self::pub_paths().len() {
                                Self::pub_paths()[new_sid]
                            } else {
                                return Err($crate::TableError::NoMatch);
                            }
                        }
                    },
                };
                $(
                    if $crate::anachro_icd::matches(msg_path, $sub_path) {
                        return Ok(
                            $enum_ty::$sub_variant_name(
                                $crate::from_bytes(msg.payload)
                                    .map_err(|e| $crate::TableError::Postcard(e))?
                            )
                        );
                    }
                )+
                $(
                    if $crate::anachro_icd::matches(msg_path, $pub_path) {
                        return Ok(
                            $enum_ty::$pub_variant_name(
                                $crate::from_bytes(msg.payload)
                                    .map_err(|e| $crate::TableError::Postcard(e))?
                            )
                        );
                    }
                )+
                Err($crate::TableError::NoMatch)
            }

            fn sub_paths() -> &'static [&'static str] {
                Self::sub_paths()
            }

            fn pub_paths() -> &'static [&'static str] {
                Self::pub_paths()
            }
        }

        impl $enum_ty {
            #[doc = "
                Get the publish path for a given variant.

                Returns None if the given table type is for a subscription topic
            "]
            pub fn get_pub_path(&self) -> core::option::Option<&'static str> {
                match self {
                    $(
                        $enum_ty::$pub_variant_name(_) => Some($pub_path),
                    )+
                    _ => None,
                }
            }

            #[doc = "
                Serialize the table variant to the given buffer

                This serializes the table variant into the given buffer, typically used to
                prepare a payload for publishing.

                Returns an Error if serialization failed, typically due to not enough space
                in the destination buffer.
            "]
            pub fn serialize<'a>(&self, buffer: &'a mut [u8]) -> core::result::Result<$crate::SendMsg<'a>, ()> {
                match self {
                    $(
                        $enum_ty::$pub_variant_name(msg) => {
                            Ok($crate::SendMsg {
                                buf: $crate::to_slice(msg, buffer)
                                        .map_err(drop)?,
                                path: $pub_path,
                            })
                        },
                    )+
                    _ => Err(()),
                }
            }

            #[doc = "Get a list of all subscription paths defined in the pubsub_table"]
            pub const fn sub_paths() -> &'static [&'static str] {
                const PATHS: &[&str] = &[
                    $($sub_path,)+
                ];

                PATHS
            }

            #[doc = "Get a list of all publishing paths defined in the pubsub_table"]
            pub const fn pub_paths() -> &'static [&'static str] {
                const PATHS: &[&str] = &[
                    $($pub_path,)+
                ];

                PATHS
            }
        }
    };
}