offline_protocol_core/

lib.rs

//! Core types and data structures for the Offline Protocol SDK.
//!
//! This crate provides the fundamental types used throughout the SDK:
//! - Message types and identifiers
//! - Protocol types (UserId, AppId, TTL, etc.)
//! - Error types
//!
//! All types in this crate are 100% safe Rust with no unsafe blocks.
//!
//! # Building without `std`
//!
//! This crate compiles for bare-metal targets with `--no-default-features`,
//! which is how a constrained leaf node (a Cortex-M lock or sensor that speaks
//! the protocol but cannot host the engine) links it. `alloc` is required in
//! both configurations.
//!
//! What the `std` feature adds is everything that mints state from the
//! platform, because a bare-metal target supplies none of it: a clock
//! ([`Timestamp::now`], [`WallClockTimestamp::now`], [`LocalInstant`]), an
//! entropy source ([`MessageId::new`], and so [`Message::new`] and
//! [`Message::builder`] with it), and threads (the [`sync`] module's
//! poison-recovering lock helpers). Everything that parses, validates,
//! re-encodes or compares is present in both configurations, which is the half
//! a leaf node actually needs: it receives a frame someone else minted.
//!
//! Construct messages from wire-supplied parts on the no_std path, via
//! [`MessageId::from_bytes`], [`Timestamp::from_millis`] and the struct
//! literal, rather than the `now()`/`new()` constructors.

#![cfg_attr(not(feature = "std"), no_std)]
#![deny(unsafe_code)]
#![warn(missing_docs)]

extern crate alloc;

pub mod address;
pub mod error;
pub mod message;
pub mod service;
#[cfg(feature = "std")]
pub mod sync;
#[cfg(feature = "std")]
pub mod time;
pub mod types;
pub mod username;
pub mod wire;

pub use address::{Address, AddressError};
pub use error::{Error, Result};
pub use message::{
    ContentType, ForwardInfo, MediaMetadata, Message, MessageId, MessagePriority, ReplyContext,
    WireCodec,
};
pub use service::{ServiceDescriptor, ServiceId};
#[cfg(feature = "std")]
pub use sync::{MutexExt, RwLockExt};
#[cfg(feature = "std")]
pub use types::LocalInstant;
pub use types::{
    validate_id_chars, AppId, HopCount, IdValidationError, LamportClock, MetadataMap, Timestamp,
    UserId, WallClockTimestamp, MAX_ID_LEN, TTL,
};
pub use username::{contains_control_or_format, Username, UsernameError};
pub use wire::{WIRE_V1_MAGIC, WIRE_VERSION_V1};

#[cfg(all(test, feature = "std"))]
mod manifest_guard_tests {
    /// Dependencies this crate declares locally instead of inheriting from the
    /// workspace table, and which must therefore be kept in lockstep by hand.
    /// See the comment above `[dependencies]` in this crate's `Cargo.toml` for
    /// why inheritance is not an option here.
    const LOCAL_DEPS: &[&str] = &[
        "serde",
        "serde_json",
        "base64",
        "unicode-normalization",
        "thiserror",
        "uuid",
        "tracing",
        "web-time",
    ];

    /// Extracts the version requirement a manifest states for `name`.
    ///
    /// Handles both spellings cargo accepts: `name = "1.0"` and
    /// `name = { version = "1.0", ... }`.
    fn version_req(manifest: &str, name: &str) -> Option<String> {
        let line = manifest
            .lines()
            .find(|l| l.starts_with(&format!("{name} = ")))?;
        let rest = match line.find("version = \"") {
            Some(i) => &line[i + "version = \"".len()..],
            None => {
                let i = line.find('"')?;
                &line[i + 1..]
            }
        };
        rest.find('"').map(|end| rest[..end].to_string())
    }

    /// The local dependency entries must not drift from the workspace table.
    ///
    /// Dropping inheritance is what makes `default-features = false` take
    /// effect (cargo ignores it on an inherited dependency), but it also means
    /// a workspace-wide version bump silently stops applying to this crate.
    /// This test is what turns that silence into a failure.
    #[test]
    fn local_dep_versions_match_the_workspace_table() {
        let dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR"));
        let root = dir.join("../../Cargo.toml");
        // A published .crate archive contains no workspace root. Skip rather
        // than panic: this guard protects the repo, and a packaged build that
        // panics here fails the release for a condition it cannot observe.
        let Ok(root_manifest) = std::fs::read_to_string(&root) else {
            return;
        };
        let own_manifest =
            std::fs::read_to_string(dir.join("Cargo.toml")).expect("own manifest is readable");

        for dep in LOCAL_DEPS {
            let workspace = version_req(&root_manifest, dep)
                .unwrap_or_else(|| panic!("`{dep}` not found in the workspace dependency table"));
            let own = version_req(&own_manifest, dep)
                .unwrap_or_else(|| panic!("`{dep}` not found in this crate's manifest"));
            assert_eq!(
                workspace, own,
                "`{dep}` version drifted: workspace says {workspace:?}, \
                 offline-protocol-core says {own:?}. Update both together."
            );
        }
    }

    /// The `version` of the `[workspace.package]` table.
    fn workspace_version(root_manifest: &str) -> Option<String> {
        let table = root_manifest.split("[workspace.package]").nth(1)?;
        let table = table.split("\n[").next()?;
        let line = table.lines().find(|l| l.starts_with("version = \""))?;
        let rest = &line["version = \"".len()..];
        rest.find('"').map(|end| rest[..end].to_string())
    }

    /// A crate that cannot inherit an internal dependency (the dual std/no_std
    /// crates, and the browser crate, all for the `default-features` reason
    /// above) names the sibling's version by hand. A release cut bumps the
    /// workspace version, and a missed hand-written pin fails the cut at its
    /// first cargo command, after the tag is planned. This turns that into a
    /// test failure on the bump commit itself.
    #[test]
    fn local_internal_pins_name_the_workspace_version() {
        let crates = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("..");
        let Ok(root_manifest) = std::fs::read_to_string(crates.join("../Cargo.toml")) else {
            return;
        };
        // Normalised so a Windows checkout's CRLF cannot hide a line.
        let root_manifest = root_manifest.replace("\r\n", "\n");
        let version = workspace_version(&root_manifest).expect("[workspace.package] version");
        let pinned = format!("version = \"{version}\"");

        let mut checked = 0;
        let mut drifted = Vec::new();
        for entry in std::fs::read_dir(&crates)
            .expect("crates directory")
            .flatten()
        {
            let manifest = entry.path().join("Cargo.toml");
            let Ok(text) = std::fs::read_to_string(&manifest) else {
                continue;
            };
            for line in text.lines() {
                let internal = line.starts_with("offline-protocol")
                    && line.contains("path = \"../")
                    && line.contains("version = \"");
                if !internal {
                    continue;
                }
                checked += 1;
                if !line.contains(&pinned) {
                    drifted.push(format!("{}: {}", manifest.display(), line.trim()));
                }
            }
        }
        assert!(
            checked > 0,
            "found no hand-pinned internal dependency to check"
        );
        assert!(
            drifted.is_empty(),
            "these internal dependencies must name the workspace version {version}:\n{}",
            drifted.join("\n")
        );
    }
}