offline_protocol_transport/
lib.rs

1//! Transport abstraction layer for the Offline Protocol SDK.
2//!
3//! This crate defines the [`Transport`] trait and the transport state
4//! machines for BLE, the peer stream (the `wifi_direct` slot), Internet,
5//! Nostr, and Reticulum, plus the one Rust implementation of the
6//! peer-stream framing ([`stream_framing`]).
7//!
8//! # This crate performs no network or radio I/O
9//!
10//! No sockets are opened and no radios are touched here. Each transport is
11//! a thread-safe protocol/queue engine — status, send/receive queues,
12//! metrics, and (for BLE) fragmentation state — driven from two sides:
13//!
14//! - **The protocol engine** talks to the [`Transport`] trait: `send()`
15//!   enqueues an outbound message, `receive()` dequeues an inbound one.
16//! - **A platform bridge** (Swift/Kotlin via the UniFFI bindings, or any
17//!   host program) owns the actual sockets, relays, and radios. It drains
18//!   the outbound queue (`get_next_message()` / `get_next_signed_event()` /
19//!   `get_next_fragment()`), performs the real I/O, reports the outcome
20//!   (`confirm_sent()` / `report_send_failure()`), injects inbound bytes
21//!   (`on_data_received()` / `on_fragment_received()`), and drives
22//!   availability (`on_status_changed()`).
23//!
24//! Without a platform bridge attached, `send()` queues messages that never
25//! go anywhere — and, BLE excepted, `start()` never makes a transport
26//! `Available` in the first place, so `send()` returns
27//! `TransportNotAvailable`. A pure-Rust consumer must play the bridge role
28//! itself: mark the transport available, drain the queues, and do its own
29//! I/O.
30//!
31//! Most transports signal pending outbound work through a
32//! `set_on_messages_available` callback instead of requiring a poll timer;
33//! [`InternetTransport`] is the exception and must be polled.
34//!
35//! All code in this crate is 100% safe Rust with no unsafe blocks.
36
37#![deny(unsafe_code)]
38#![warn(missing_docs)]
39
40pub mod ble;
41pub(crate) mod common;
42pub mod constants;
43pub mod error;
44pub mod internet;
45#[cfg(any(test, feature = "test-utils"))]
46pub mod mock;
47// NIP-44 v2 is an implementation detail of the Nostr gift wrap: nothing outside
48// this crate should be able to reach the primitives directly, and in particular
49// nothing should be able to hand it a conversation key of its own choosing.
50mod nip44;
51pub mod nostr;
52pub mod nostr_crypto;
53pub mod reticulum;
54pub mod stream_framing;
55pub mod traits;
56pub mod types;
57pub mod wifi_direct;
58
59pub use ble::{
60    BleTransport, BleTransportBuilder, FragmentEvictionCallback, FragmentEvictionInfo, PeerDevice,
61};
62pub use constants::DEFAULT_MAX_MESSAGE_SIZE;
63pub use error::{Error, Result};
64pub use internet::{InternetConfig, InternetTransport};
65pub use nostr::{NostrConfig, NostrTransport, NostrTransportBuilder, SignedNostrEvent};
66pub use nostr_crypto::{routing_tag_for_address, NostrEvent, NostrKeypair};
67pub use reticulum::ReticulumTransport;
68pub use stream_framing::{frame, CloseReason, PeerStreamReader, PreambleVerifier, StreamEvent};
69pub use traits::{Transport, TransportStatus};
70pub use types::{
71    LinkQuality, PeerLink, SharedCallback, TransportMetrics, TransportType,
72    DEFAULT_LINK_QUALITY_WITHOUT_RSSI,
73};
74pub use wifi_direct::{WifiDirectConfig, WifiDirectPeer, WifiDirectTransport};
75
76// MockTransport is only available to this crate's tests or explicit test consumers.
77#[cfg(any(test, feature = "test-utils"))]
78pub use mock::MockTransport;
offline_protocol_transport/lib.rs

offline_protocol_transport/
lib.rs
