README.md (10902B)
1 # radroots_transport 2 3 The `std` host boundary `host::websocket` exchanges owned frames, revocable 4 admission and bounded errors with concrete native or browser socket providers. 5 It owns no protocol session, reconnect policy, executor or concrete socket. 6 Browser providers keep DOM objects local and exchange safe channel handles; 7 application futures retain their target-specific host bounds. The data model 8 and source/sink SPIs remain available without `std`. 9 10 `radroots_transport` is the transport-neutral host SPI for moving verified 11 Radroots events between explicit targets. It owns extensible transport and 12 target identities, separate source and sink capabilities, bounded fetch and 13 delivery requests, bounded live subscriptions, provenance, partial outcomes, 14 and normalized errors. 15 16 The crate is `no_std` with `alloc`. It does not own network clients, storage, 17 outbox claiming, retry loops, schedulers, timers, or fallback policy. Concrete 18 adapters such as `radroots_transport_nostr` implement the SPI; applications 19 compose those adapters in `radroots_sdk` or their own host layer. 20 21 `Target::matches_nostr_relay` compares a captured relay identifier using the 22 target's original construction policy and shared canonical endpoint rules. 23 Callers preserve original signed source bytes and approve the exact selected 24 route separately; a canonical match grants no network permission. 25 26 The authoritative package charter is the 27 [`radroots_transport` section of the Release V1 specification](../../contracts/crates/release_v1/radroots_crates_release_v1.toml). 28 29 ## Typical flow 30 31 1. A host selects a validated [`TransportId`] and constructs one or more 32 canonical [`Target`] values. 33 2. [`TargetSet`] rejects an empty, oversized, or duplicate-fingerprint set. 34 3. The caller creates a bounded [`FetchRequest`], [`SubscriptionRequest`], or 35 [`DeliveryRequest`] with a request identity and absolute deadline. Inbound 36 operations may carry a validated [`FetchSelector`] for exact kinds, 37 authors, indexed single-letter tag values, and inclusive event-time bounds. 38 4. A dyn-compatible [`EventSource`], [`EventSubscriber`], or [`EventSink`] 39 implementation performs only the requested operation. 40 5. The caller validates [`FetchPage`] or [`DeliveryReceipt`] against the 41 originating request and decides whether normalized retryable outcomes merit 42 another explicit operation. 43 44 Delivery receipts and sink-wide partial failures retain the SHA-256 digest of 45 the exact original signed JSON bytes. Validation refuses another payload even 46 when request identity and targets match, including a different representation 47 of the same event ID. Serialized receipts require that digest; decoding alone 48 does not authenticate an adapter or establish a remote acknowledgement. 49 50 [`TransportId`]: crate::TransportId 51 [`Target`]: crate::Target 52 [`TargetSet`]: crate::TargetSet 53 [`FetchRequest`]: crate::FetchRequest 54 [`SubscriptionRequest`]: crate::SubscriptionRequest 55 [`FetchSelector`]: crate::source::FetchSelector 56 [`DeliveryRequest`]: crate::DeliveryRequest 57 [`EventSource`]: crate::EventSource 58 [`EventSubscriber`]: crate::EventSubscriber 59 [`EventSink`]: crate::EventSink 60 [`FetchPage`]: crate::FetchPage 61 [`DeliveryReceipt`]: crate::DeliveryReceipt 62 63 ```rust 64 use radroots_transport::{Error, Target, TargetSet, TransportId}; 65 66 let transport_id = TransportId::parse("example")?; 67 let target = Target::new(transport_id, "https://transport.example/events")?; 68 let targets = TargetSet::new(vec![target])?; 69 70 assert_eq!(targets.len(), 1); 71 # Ok::<(), Error>(()) 72 ``` 73 74 The complete externally implementable SPI example is 75 [`examples/host_transport.rs`](examples/host_transport.rs). 76 77 ## Host SPI contract 78 79 `EventSource`, `EventSubscriber`, and `EventSink` are independent, externally 80 implementable, dyn-compatible traits. Native hosts remain `Send + Sync`, with 81 movable subscriptions and boxed `Future + Send`. Browser hosts, subscriptions 82 and futures may remain local. `host::Shared` selects native `Arc` or browser 83 `Rc`. An adapter may implement any subset. This package does not select an 84 async runtime or require an async-trait macro. 85 86 - `status` is observational and must not begin fetch or delivery work. 87 - `fetch` returns one bounded page plus per-target outcomes and explicit 88 continuation state. Returned events must satisfy the request selector; 89 request-bound page validation rejects adapter drift. 90 - `subscribe` returns a sealed live-operation capability. Its `next` method 91 returns request-bound events with target checkpoints or one stable terminal 92 result; its `cancel` method returns that same terminal result once ended. 93 - `deliver` returns one receipt for the exact request and every requested 94 target; it never performs an implicit retry. 95 - Implementations must not install an executor or spawn hidden workers. The 96 composing host owns polling, scheduling, retries, and process lifecycle. 97 - Concrete backend failures are normalized to `radroots_transport::Error`. 98 Native sources may be retained by adapters, but public outcome codes and 99 messages must remain bounded and secret-safe. 100 101 `EventSink::deliver_selected` accepts an exact nonempty subset while preserving 102 the full original request and receipt target set. An adapter must not attempt 103 unselected targets. The default accepts only all original targets; a proper 104 subset returns `target_selection_unsupported` without delivery. Callers hold 105 empty selections without invoking transport. 106 107 ## Targets and extensible identity 108 109 `TransportId` is a validated open identity, not a closed enum. The built-in 110 `LOCAL`, `NOSTR`, `RETICULUM`, and `RADROOTSD` constants are conveniences; 111 future adapters can use validated custom IDs without changing this crate. 112 113 Targets contain a transport ID, canonical endpoint URI, optional scope and 114 human label, and a derived SHA-256 fingerprint. The label is descriptive and 115 does not participate in identity. The transport ID, endpoint, and scope do. 116 Target-set construction preserves caller order and rejects duplicate 117 fingerprints instead of silently deduplicating them. 118 119 The ordinary Nostr target constructor admits TLS endpoints and exact loopback 120 cleartext only. Physical-device callers must select 121 [`TargetNetworkPolicy::PrivateDevice`] explicitly; that policy admits only 122 literal RFC1918 IPv4 or ULA IPv6 endpoints. This is a passive construction 123 boundary, not connection authority. Concrete adapters must retain the selected 124 policy, revalidate every resolved address, and pin the validated destination 125 when opening a socket. This generic package does not resolve names, open 126 connections, export relay URL types, or own network fallback. 127 128 [`TargetNetworkPolicy::PrivateDevice`]: crate::TargetNetworkPolicy::PrivateDevice 129 130 ## Bounds, deadlines, cancellation, and commit points 131 132 Request IDs, endpoint values, cursors, target sets, outcome details, page 133 sizes, and live event counts are bounded by public constants. Fetch, 134 subscription, and delivery requests carry an absolute Unix-millisecond 135 deadline; constructors validate the deadline but do not read a clock. 136 137 Dropping a returned future requests cancellation. Before an adapter publishes 138 or commits a remote operation, cancellation must leave no durable effect. 139 After that boundary, cancellation does not imply rollback: the adapter must 140 preserve and report the final remote state when it can be observed. Each 141 concrete adapter documents its exact publication or commit point. 142 143 Live subscriptions additionally retain canonical per-target checkpoints in 144 request target order. Reconnect callers pass only an explicit checkpoint 145 subset; adapters must not invent hidden replay state. Once a subscription 146 returns its terminal result, subsequent `next` and `cancel` calls return the 147 same result. 148 149 ## Outcomes, partial success, and retry 150 151 Fetch pages and delivery receipts preserve target-local results. Delivery 152 satisfaction is explicit (`any`, `all`, quorum, or required fingerprints) and 153 is evaluated against the originating request. Retryability and terminality are 154 normalized data on outcomes, never an automatic loop. Authentication, 155 unavailability, rejection, cancellation, partial progress, and unknown remote 156 state must not be rewritten as success or silent fallback. 157 158 ## Serialization and provenance 159 160 With `serde`, passive identities, requests, subscriptions, pages, receipts, 161 status values, and outcomes use validated representations. Deserialization 162 rechecks canonical identity, bounds, request/result cardinality, and provenance 163 rather than trusting serialized fingerprints or counts. 164 165 Inbound events carry the transport ID, exact target fingerprint, observation 166 time, and optional continuation cursor that produced them. A page cannot claim 167 events or outcomes for targets outside its request. A live event additionally 168 binds its exact originating request and requires its resulting target 169 checkpoint to match the event's provenance cursor. 170 171 ## Security and side effects 172 173 - Target endpoint syntax is validated before an adapter receives a request; 174 adapters remain responsible for scheme, DNS/IP, TLS, and private-network 175 policy before connection. 176 - Delivery accepts a validated signed event, not arbitrary bytes. 177 - Receipt, page, and subscription constructors reject missing, duplicate, 178 unexpected, or forged target evidence. 179 - This crate forbids unsafe code and contains no socket, filesystem, database, 180 global state, timer, executor, or retry implementation. 181 - No transport may silently route through another transport. 182 183 ## Features 184 185 | Feature | Default | Contract | 186 | --- | --- | --- | 187 | `std` | yes | Enables standard-library support in canonical dependency values; it adds no I/O, runtime, or global initialization. | 188 | `serde` | yes | Adds validated serialization for passive identities, requests, subscriptions, status, provenance, pages, receipts, policies, and outcomes. | 189 190 Features are additive. `--no-default-features` provides the `no_std + alloc` 191 core, and `serde` is supported independently of `std`. 192 193 ## Intended consumers 194 195 - `radroots_transport_nostr` provides the concrete native Nostr adapter. 196 - `radroots_storage` persists transport-neutral outbox and evidence values. 197 - `radroots_sync` plans bounded operations and applies explicit retry policy. 198 - `radroots_sdk` composes storage, signing, source, and sink implementations. 199 - Service and future adapter hosts implement any of the SPIs and own runtime, 200 network, cancellation, and lifecycle behavior. 201 202 Applications that only need ordinary Radroots operations should normally use 203 `radroots` or `radroots_sdk`; implement this package directly when providing a 204 new transport adapter or advanced host composition. 205 206 ## Copyright 207 208 Except as otherwise noted, all files in the `radroots_transport` distribution are 209 210 Copyright (c) 2025 Tyson Lupul 211 212 For information on usage and redistribution, and for a DISCLAIMER OF ALL 213 WARRANTIES, see LICENSE included in the `radroots_transport` distribution.