lib

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

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.