lib

Core libraries for Radroots
git clone https://radroots.dev/git/lib.git
Log | Files | Refs | README

package_boundary.rs (11465B)


      1 use std::{collections::BTreeSet, fs, path::Path};
      2 
      3 #[allow(unused_imports)]
      4 use radroots_transport::{
      5     DeliveryReceipt as _, DeliveryRequest as _, Error as _, EventSink as _, EventSource as _,
      6     EventSubscriber as _, EventSubscription as _, FetchPage as _, FetchRequest as _,
      7     SubscriptionEnd as _, SubscriptionEvent as _, SubscriptionRequest as _, Target as _,
      8     TargetNetworkPolicy as _, TargetSet as _, TransportId as _, capability as _, endpoint as _,
      9     error as _, outcome as _, policy as _, sink as _, source as _, target as _,
     10 };
     11 
     12 const MANIFEST: &str = include_str!("../Cargo.toml");
     13 const EXAMPLE: &str = include_str!("../examples/host_transport.rs");
     14 const PUBLIC_API: &str = include_str!("../../../contracts/api_baselines/radroots_transport.txt");
     15 const README: &str = include_str!("../README.md");
     16 const ROOT: &str = include_str!("../src/lib.rs");
     17 const SOURCE: &str = include_str!("../src/source.rs");
     18 const SINK: &str = include_str!("../src/sink.rs");
     19 const ID: &str = include_str!("../src/id.rs");
     20 const TARGET: &str = include_str!("../src/target.rs");
     21 const DEVIATIONS: &str = include_str!("../../../contracts/architecture/deviations.toml");
     22 
     23 #[test]
     24 fn manifest_has_final_identity_features_and_required_radroots_dependencies() {
     25     for required in [
     26         "name = \"radroots_transport\"",
     27         "version = \"0.1.0-alpha\"",
     28         "publish = [\"crates-io\"]",
     29         "[lib]\nname = \"radroots_transport\"",
     30         "default = [\"std\", \"serde\"]",
     31         "radroots_event = { workspace = true, default-features = false }",
     32         "radroots_identity = { workspace = true, default-features = false }",
     33         "radroots_protocol = { workspace = true, default-features = false }",
     34     ] {
     35         assert!(
     36             MANIFEST.contains(required),
     37             "manifest is missing {required}"
     38         );
     39     }
     40 
     41     assert_eq!(
     42         table_keys(MANIFEST, "[features]"),
     43         BTreeSet::from(["default", "serde", "std"])
     44     );
     45     assert_eq!(
     46         table_keys(MANIFEST, "[dependencies]")
     47             .into_iter()
     48             .filter(|dependency| dependency.starts_with("radroots_"))
     49             .collect::<BTreeSet<_>>(),
     50         BTreeSet::from(["radroots_event", "radroots_identity", "radroots_protocol"])
     51     );
     52 }
     53 
     54 #[test]
     55 fn crate_root_declares_the_approved_public_module_skeleton() {
     56     assert!(ROOT.contains("#![doc = include_str!(\"../README.md\")]"));
     57     assert!(ROOT.contains("#![cfg_attr(not(feature = \"std\"), no_std)]"));
     58     assert_eq!(
     59         root_declarations("pub mod "),
     60         BTreeSet::from([
     61             "capability",
     62             "endpoint",
     63             "error",
     64             "host",
     65             "outcome",
     66             "policy",
     67             "sink",
     68             "source",
     69             "target",
     70         ])
     71     );
     72 }
     73 
     74 #[test]
     75 fn package_documentation_and_reviewed_api_baseline_are_complete() {
     76     for required in [
     77         "## Typical flow",
     78         "## Host SPI contract",
     79         "## Targets and extensible identity",
     80         "## Bounds, deadlines, cancellation, and commit points",
     81         "## Outcomes, partial success, and retry",
     82         "## Serialization and provenance",
     83         "## Security and side effects",
     84         "## Features",
     85         "## Intended consumers",
     86         "radroots_crates_release_v1.toml",
     87         "examples/host_transport.rs",
     88         "indexed single-letter tag values",
     89         "TargetNetworkPolicy::PrivateDevice",
     90         "literal RFC1918 IPv4 or ULA IPv6 endpoints",
     91         "not connection authority",
     92     ] {
     93         assert!(README.contains(required), "README is missing {required}");
     94     }
     95     for required in [
     96         "impl EventSource for HostTransport",
     97         "impl EventSubscriber for HostTransport",
     98         "impl EventSink for HostTransport",
     99         "fn fetch(&self, _request: FetchRequest) -> BoxFuture",
    100         "_request: SubscriptionRequest",
    101         "_request: DeliveryRequest",
    102         "let source: &dyn EventSource",
    103         "let subscriber: &dyn EventSubscriber",
    104         "let sink: &dyn EventSink",
    105         "drop(future)",
    106     ] {
    107         assert!(EXAMPLE.contains(required), "example is missing {required}");
    108     }
    109     for required in [
    110         "pub mod radroots_transport::capability",
    111         "pub mod radroots_transport::endpoint",
    112         "pub mod radroots_transport::error",
    113         "pub mod radroots_transport::outcome",
    114         "pub mod radroots_transport::policy",
    115         "pub mod radroots_transport::sink",
    116         "pub mod radroots_transport::source",
    117         "pub mod radroots_transport::target",
    118         "pub trait radroots_transport::EventSource",
    119         "pub trait radroots_transport::EventSubscriber",
    120         "pub trait radroots_transport::EventSubscription",
    121         "pub trait radroots_transport::EventSink",
    122         "pub struct radroots_transport::source::SubscriptionBounds",
    123         "pub struct radroots_transport::source::SubscriptionCheckpoint",
    124         "pub struct radroots_transport::SubscriptionRequest",
    125         "pub enum radroots_transport::SubscriptionEndReason",
    126         "pub const radroots_transport::source::SUBSCRIPTION_MAX_EVENTS: u16",
    127         "pub const radroots_transport::source::FETCH_SELECTOR_MAX_TAG_VALUES: usize",
    128         "pub const radroots_transport::source::FETCH_SELECTOR_MAX_TAG_KEYS: usize",
    129         "pub const radroots_transport::source::FETCH_SELECTOR_TAG_VALUE_MAX_BYTES: usize",
    130         "pub fn radroots_transport::source::FetchSelector::with_exact_tag_value",
    131         "pub fn radroots_transport::source::FetchSelector::exact_tag_filters",
    132         "pub fn radroots_transport::target::Target::new(radroots_transport::TransportId",
    133         "pub fn radroots_transport::target::Target::kind(&self) -> &radroots_transport::TransportId",
    134         "pub enum radroots_transport::target::TargetNetworkPolicy",
    135         "pub fn radroots_transport::target::Target::nostr_relay_with_policy",
    136     ] {
    137         assert!(
    138             PUBLIC_API.contains(required),
    139             "public API baseline is missing {required}"
    140         );
    141     }
    142     for forbidden in [
    143         "pub trait radroots_transport::RadrootsTransport",
    144         "RadrootsTransportFuture",
    145         "RadrootsTransportKind",
    146         "RadrootsTransportTargetSet",
    147         "Target::reticulum",
    148         "TargetScope::local_reticulum",
    149     ] {
    150         assert!(
    151             !PUBLIC_API.contains(forbidden),
    152             "reviewed public API baseline still exposes `{forbidden}`"
    153         );
    154     }
    155 }
    156 
    157 #[test]
    158 fn every_public_module_has_crate_level_documentation() {
    159     let source_root = Path::new(env!("CARGO_MANIFEST_DIR")).join("src");
    160     for module in [
    161         "capability",
    162         "endpoint",
    163         "error",
    164         "host",
    165         "outcome",
    166         "policy",
    167         "sink",
    168         "source",
    169         "target",
    170     ] {
    171         let path = source_root.join(format!("{module}.rs"));
    172         let source = fs::read_to_string(&path).expect("read module source");
    173         assert!(
    174             source.starts_with("//! "),
    175             "public module {module} must start with module documentation"
    176         );
    177     }
    178 }
    179 
    180 #[test]
    181 fn source_subscription_and_sink_are_independent_dyn_compatible_host_spis() {
    182     for required in [
    183         "pub trait EventSource: crate::host::HostBound",
    184         "fn status(&self)",
    185         "fn fetch(",
    186         "Dropping a returned future requests cancellation.",
    187         "explicit request deadline",
    188     ] {
    189         assert!(
    190             SOURCE.contains(required),
    191             "source SPI is missing {required}"
    192         );
    193     }
    194     assert!(!SOURCE.contains("fn deliver("));
    195 
    196     for required in [
    197         "pub trait EventSubscriber: crate::host::HostBound",
    198         "pub trait EventSubscription: crate::host::MoveBound",
    199         "fn subscribe(",
    200         "fn next(&mut self)",
    201         "fn cancel(&mut self)",
    202         "Once [`SubscriptionNext::End`] has been",
    203         "exact same",
    204     ] {
    205         assert!(
    206             SOURCE.contains(required),
    207             "subscription SPI is missing {required}"
    208         );
    209     }
    210 
    211     for required in [
    212         "pub trait EventSink: crate::host::HostBound",
    213         "fn status(&self)",
    214         "fn deliver(",
    215         "Dropping a returned future requests cancellation.",
    216         "explicit request deadline",
    217     ] {
    218         assert!(SINK.contains(required), "sink SPI is missing {required}");
    219     }
    220     assert!(!SINK.contains("fn fetch("));
    221 
    222     for retired in [
    223         "Publish-frozen external-consumer",
    224         "pub fn reticulum(",
    225         "pub fn reticulum_with_metadata(",
    226         "pub fn local_reticulum(",
    227         "RadrootsTransportTarget",
    228     ] {
    229         assert!(
    230             !TARGET.contains(retired),
    231             "retired external-consumer surface remains: `{retired}`"
    232         );
    233     }
    234     for retired in [
    235         "RadrootsTransportKind",
    236         "pub const Local",
    237         "pub const Nostr",
    238         "pub const Reticulum",
    239     ] {
    240         assert!(
    241             !ID.contains(retired),
    242             "retired transport identity remains: `{retired}`"
    243         );
    244     }
    245     for required in [
    246         "id = \"RCRV1-DEV-007\"",
    247         "status = \"closed\"",
    248         "affected_steps = [\"122\", \"170\", \"215\", \"235\", \"305\"]",
    249         "Step 313 source census confirmed every external-consumer alias and helper is absent",
    250     ] {
    251         assert!(
    252             DEVIATIONS.contains(required),
    253             "temporary downstream ownership record is missing `{required}`"
    254         );
    255     }
    256 }
    257 
    258 #[test]
    259 fn public_api_excludes_adapter_runtime_storage_and_retry_authority() {
    260     let dependency_keys = table_keys(MANIFEST, "[dependencies]");
    261     for forbidden in [
    262         "radroots_outbox",
    263         "radroots_storage",
    264         "radroots_transport_nostr",
    265         "radroots_transport_reticulum",
    266         "nostr-sdk",
    267         "nostr_sdk",
    268         "reqwest",
    269         "sqlx",
    270         "tokio",
    271     ] {
    272         assert!(
    273             !dependency_keys.contains(forbidden),
    274             "generic transport must not depend on `{forbidden}`"
    275         );
    276     }
    277 
    278     assert!(ID.contains("pub struct TransportId("));
    279     assert!(!ID.contains("pub enum TransportId"));
    280     for forbidden in [
    281         "RADROOTS_RETICULUM_",
    282         "ReticulumDestination",
    283         "RelayUrl",
    284         "NostrRelay",
    285     ] {
    286         assert!(
    287             !ROOT.contains(forbidden),
    288             "generic transport root must not export adapter symbol `{forbidden}`"
    289         );
    290     }
    291     for source in [SOURCE, SINK] {
    292         for forbidden in [
    293             "tokio::spawn",
    294             "std::thread::spawn",
    295             "retry_loop",
    296             "fallback_transport",
    297         ] {
    298             assert!(
    299                 !source.contains(forbidden),
    300                 "transport SPI must not own runtime behavior `{forbidden}`"
    301             );
    302         }
    303     }
    304 }
    305 
    306 fn table_keys<'a>(source: &'a str, heading: &str) -> BTreeSet<&'a str> {
    307     let mut in_table = false;
    308     source
    309         .lines()
    310         .filter_map(|line| {
    311             let line = line.trim();
    312             if line == heading {
    313                 in_table = true;
    314                 return None;
    315             }
    316             if in_table && line.starts_with('[') {
    317                 in_table = false;
    318             }
    319             in_table
    320                 .then(|| line.split_once('=').map(|(key, _)| key.trim()))
    321                 .flatten()
    322         })
    323         .collect()
    324 }
    325 
    326 fn root_declarations(prefix: &str) -> BTreeSet<&str> {
    327     ROOT.lines()
    328         .map(str::trim)
    329         .filter_map(|line| line.strip_prefix(prefix))
    330         .filter_map(|line| line.strip_suffix(';'))
    331         .collect()
    332 }