Initial Commit of Alvarium Annotator traits package

Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "alvarium-annotator"
+version = "0.1.0"
+edition = "2021"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+serde = { version = "1.0.143", features = ["derive"]}
+serde_json = "1.0.96"
+thiserror = "1.0.40"
+ulid = "1.0.0"
+chrono = "0.4.22"
+async-trait = "0.1.68"
+lazy_static = "1.4.0"

README.md

@@ -1 +1,11 @@
-# alvarium_annotator
+# Alvarium Annotator Core
+
+This crate contains traits, types and constants for use in the Alvarium SDK. 
+This includes interface definitions for [Annotators](src/annotator.rs) and 
+[Annotations](src/annotations.rs), as well as Hash, Signature, and Stream 
+[Providers](src/providers.rs). 
+
+The type definitions such as HashType and KeyAlgorithm provided flexible 
+wrappers that can be expanded beyond the preset constants. This allows for 
+custom annotators to be developed that still conforms to the interface 
+patterns required for use within the SDK. 

src/annotations.rs

@@ -0,0 +1,60 @@
+use crate::constants::{self, AnnotationType, HashType};
+use serde::{Deserialize, Serialize};
+
+#[derive(Clone, PartialEq, Eq, Debug, Serialize, Deserialize)]
+pub struct Annotation {
+ pub id: String,
+ pub key: String,
+ pub hash: HashType,
+ pub host: String,
+ pub kind: AnnotationType,
+ pub signature: String,
+ #[serde(rename = "isSatisfied")]
+ pub is_satisfied: bool,
+ pub timestamp: String,
+}
+
+#[derive(Clone, PartialEq, Default, Serialize, Deserialize)]
+pub struct AnnotationList {
+ pub items: Vec<Annotation>,
+}
+
+impl Annotation {
+ pub fn new(
+ key: &str,
+ hash: HashType,
+ host: &str,
+ kind: AnnotationType,
+ is_satisfied: bool,
+ ) -> Self {
+ let timestamp = chrono::Local::now().to_rfc3339();
+ Annotation {
+ id: ulid::Ulid::new().to_string(),
+ key: key.to_string(),
+ hash,
+ host: host.to_string(),
+ kind,
+ signature: String::new(),
+ is_satisfied,
+ timestamp,
+ }
+ }
+
+ pub fn with_signature(&mut self, signature: &str) {
+ self.signature = signature.to_string()
+ }
+
+ pub fn validate_base(&self) -> bool {
+ self.hash.is_base_hash_type() && self.kind.is_base_annotation_type()
+ }
+}
+
+pub fn mock_annotation() -> Annotation {
+ let key = "The hash of the contents";
+ let hash = constants::SHA256_HASH.clone();
+ let host = "Host Device";
+ let kind = constants::ANNOTATION_SOURCE.clone();
+ let satisfied = true;
+
+ Annotation::new(key, hash, host, kind, satisfied)
+}

src/annotator.rs

@@ -0,0 +1,6 @@
+use crate::Annotation;
+
+pub trait Annotator {
+ type Error: std::error::Error;
+ fn annotate(&mut self, data: &[u8]) -> Result<Annotation, Self::Error>;
+}

src/constants.rs

@@ -0,0 +1,104 @@
+use crate::errors::{Error, Result};
+use lazy_static::lazy_static;
+use serde::{Deserialize, Serialize};
+use std::ops::Deref;
+
+pub trait Validate {
+ fn validate(&self) -> bool;
+}
+
+#[derive(PartialEq, Eq, Clone, Debug, Serialize, Deserialize)]
+pub struct HashType(pub String);
+
+lazy_static! {
+ pub static ref MD5_HASH: HashType = HashType(String::from("md5"));
+ pub static ref SHA256_HASH: HashType = HashType(String::from("sha256"));
+ pub static ref NO_HASH: HashType = HashType(String::from("none"));
+}
+
+impl HashType {
+ pub fn is_base_hash_type(&self) -> bool {
+ self == MD5_HASH.deref() || self == SHA256_HASH.deref() || self == NO_HASH.deref()
+ }
+}
+
+#[derive(PartialEq, Eq, Clone, Debug, Serialize, Deserialize)]
+pub struct KeyAlgorithm(pub String);
+
+lazy_static! {
+ pub static ref ED25519_KEY: KeyAlgorithm = KeyAlgorithm(String::from("ed25519"));
+}
+
+impl KeyAlgorithm {
+ pub fn is_base_key_algorithm(&self) -> bool {
+ self == ED25519_KEY.deref()
+ }
+}
+
+#[derive(PartialEq, Eq, Clone, Debug, Serialize, Deserialize)]
+pub struct StreamType(pub String);
+
+lazy_static! {
+ pub static ref DEMIA_STREAM: StreamType = StreamType(String::from("demia"));
+ pub static ref MOCK_STREAM: StreamType = StreamType(String::from("mock"));
+ pub static ref MQTT_STREAM: StreamType = StreamType(String::from("mqtt"));
+}
+
+impl StreamType {
+ pub fn is_base_stream_type(&self) -> bool {
+ self == DEMIA_STREAM.deref() || self == MOCK_STREAM.deref() || self == MQTT_STREAM.deref()
+ }
+}
+#[derive(PartialEq, Eq, Clone, Debug, Serialize, Deserialize)]
+pub struct AnnotationType(pub String);
+
+lazy_static! {
+ pub static ref ANNOTATION_PKI: AnnotationType = AnnotationType(String::from("pki"));
+ pub static ref ANNOTATION_SOURCE: AnnotationType = AnnotationType(String::from("source"));
+ pub static ref ANNOTATION_TLS: AnnotationType = AnnotationType(String::from("tls"));
+ pub static ref ANNOTATION_TPM: AnnotationType = AnnotationType(String::from("tpm"));
+}
+
+impl AnnotationType {
+ pub fn kind(&self) -> &str {
+ &self.0
+ }
+ pub fn is_base_annotation_type(&self) -> bool {
+ self == ANNOTATION_PKI.deref()
+ || self == ANNOTATION_SOURCE.deref()
+ || self == ANNOTATION_TLS.deref()
+ || self == ANNOTATION_TPM.deref()
+ }
+}
+
+impl TryFrom<&str> for AnnotationType {
+ type Error = Error;
+ fn try_from(kind: &str) -> Result<Self> {
+ match kind {
+ "source" => Ok(ANNOTATION_SOURCE.clone()),
+ "pki" => Ok(ANNOTATION_PKI.clone()),
+ "tls" => Ok(ANNOTATION_TLS.clone()),
+ "tpm" => Ok(ANNOTATION_TPM.clone()),
+ _ => Err(Error::UnknownAnnotation),
+ }
+ }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct SdkAction(pub String);
+
+lazy_static! {
+ pub static ref ACTION_CREATE: SdkAction = SdkAction(String::from("create"));
+ pub static ref ACTION_MUTATE: SdkAction = SdkAction(String::from("mutate"));
+ pub static ref ACTION_TRANSIT: SdkAction = SdkAction(String::from("transit"));
+ pub static ref ACTION_PUBLISH: SdkAction = SdkAction(String::from("publish"));
+}
+
+impl SdkAction {
+ pub fn is_base_action(&self) -> bool {
+ self == ACTION_CREATE.deref()
+ || self == ACTION_MUTATE.deref()
+ || self == ACTION_TRANSIT.deref()
+ || self == ACTION_PUBLISH.deref()
+ }
+}

src/errors.rs

@@ -0,0 +1,24 @@
+use thiserror::Error;
+
+pub type Result<T> = core::result::Result<T, Error>;
+
+#[derive(Debug, Error)]
+pub enum Error {
+ #[error("unknown annotation type")]
+ UnknownAnnotation,
+ #[error("annotation failed to serialize: {0}")]
+ AnnotationSerialize(serde_json::Error),
+
+ #[cfg(test)]
+ #[error("provider failed to sign")]
+ SignatureError,
+ #[cfg(test)]
+ #[error("provider failed to verify")]
+ VerificationError,
+}
+
+impl From<serde_json::Error> for Error {
+ fn from(err: serde_json::Error) -> Self {
+ Error::AnnotationSerialize(err)
+ }
+}

src/lib.rs

@@ -0,0 +1,17 @@
+mod annotations;
+mod annotator;
+mod errors;
+mod providers;
+mod config {
+ pub trait StreamConfigWrapper {
+ fn stream_type(&self) -> &crate::constants::StreamType;
+ }
+}
+
+pub use annotations::*;
+pub use annotator::Annotator;
+pub use config::StreamConfigWrapper;
+pub use errors::Error;
+pub use providers::*;
+
+pub mod constants;

src/providers.rs

@@ -0,0 +1,137 @@
+mod hash_providers {
+
+ pub trait HashProvider {
+ fn derive(&self, data: &[u8]) -> String;
+ }
+
+ pub fn derive_hash<H: HashProvider>(hash_type: H, data: &[u8]) -> String {
+ hash_type.derive(data)
+ }
+
+ #[cfg(test)]
+ mod hash_provider_tests {
+ use crate::HashProvider;
+
+ struct MockHashProvider {}
+
+ impl HashProvider for MockHashProvider {
+ fn derive(&self, _data: &[u8]) -> String {
+ "Derived".to_string()
+ }
+ }
+
+ #[test]
+ fn test_mock_derive() {
+ let hash_provider = MockHashProvider {};
+ let derived = hash_provider.derive("data".as_bytes());
+ assert_eq!("Derived", derived)
+ }
+ }
+}
+
+mod signature_provider {
+ use crate::Annotation;
+
+ pub trait SignProvider {
+ type Error: std::error::Error;
+ fn sign(&self, content: &[u8]) -> Result<String, Self::Error>;
+ fn verify(&self, content: &[u8], signed: &[u8]) -> Result<bool, Self::Error>;
+ }
+
+ pub fn serialise_and_sign<P>(provider: &P, annotation: &Annotation) -> Result<String, P::Error>
+ where
+ P: SignProvider,
+ <P as SignProvider>::Error: From<serde_json::Error>
+ {
+ let serialised = serde_json::to_vec(annotation)?;
+ provider.sign(&serialised)
+ }
+
+ #[cfg(test)]
+ mod annotation_utility_tests {
+ use super::serialise_and_sign;
+ use crate::annotations::mock_annotation;
+ use crate::errors::{Error, Result};
+ use crate::SignProvider;
+
+ struct MockSignProvider {
+ pub public: String,
+ pub private: String,
+ }
+
+ impl SignProvider for MockSignProvider {
+ type Error = crate::errors::Error;
+ fn sign(&self, _content: &[u8]) -> Result<String> {
+ match self.private.as_str().eq("A known and correct key") {
+ true => Ok("Signed".to_string()),
+ false => Err(Error::SignatureError),
+ }
+ }
+
+ fn verify(&self, _content: &[u8], _signed: &[u8]) -> Result<bool> {
+ match self.public.as_str().eq("A known and correct key") {
+ true => Ok(true),
+ false => Err(Error::VerificationError),
+ }
+ }
+ }
+
+ #[test]
+ fn mock_sign_provider() {
+ let correct_key = "A known and correct key".to_string();
+ let unknown_key = "An unknown key".to_string();
+
+ let mock_provider = MockSignProvider {
+ private: correct_key.clone(),
+ public: correct_key.clone(),
+ };
+
+ let bad_mock_provider = MockSignProvider {
+ private: unknown_key.clone(),
+ public: unknown_key.clone(),
+ };
+
+ let annotation = mock_annotation();
+
+ let failed_signature = serialise_and_sign(&bad_mock_provider, &annotation);
+ assert!(failed_signature.is_err());
+ let signature = serialise_and_sign(&mock_provider, &annotation);
+ assert!(signature.is_ok());
+
+ let ann_bytes = serde_json::to_vec(&annotation).unwrap();
+ let failed_verify = bad_mock_provider.verify("Content".as_bytes(), &ann_bytes);
+ assert!(failed_verify.is_err());
+ let verified = mock_provider.verify("Content".as_bytes(), &ann_bytes);
+ assert!(verified.is_ok())
+ }
+ }
+}
+
+mod stream_provider {
+ use crate::constants::SdkAction;
+ use crate::StreamConfigWrapper;
+ use serde::{Deserialize, Serialize};
+
+ #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+ pub struct MessageWrapper<'a> {
+ pub action: SdkAction,
+ #[serde(rename = "messageType")]
+ pub message_type: &'a str,
+ pub content: &'a str,
+ }
+
+ #[async_trait::async_trait]
+ pub trait Publisher: Sized {
+ type StreamConfig: StreamConfigWrapper;
+ type Error: std::error::Error;
+ async fn new(cfg: &Self::StreamConfig) -> Result<Self, Self::Error>;
+ async fn close(&mut self) -> Result<(), Self::Error>;
+ async fn connect(&mut self) -> Result<(), Self::Error>;
+ async fn reconnect(&mut self) -> Result<(), Self::Error>;
+ async fn publish(&mut self, msg: MessageWrapper<'_>) -> Result<(), Self::Error>;
+ }
+}
+
+pub use hash_providers::{derive_hash, HashProvider};
+pub use signature_provider::{serialise_and_sign, SignProvider};
+pub use stream_provider::{MessageWrapper, Publisher};