Skip to main content

nostr_pubsub_fips/
lib.rs

1//! Pubsub over authenticated peers on the `fips_core::FipsEndpoint` service API.
2
3use std::collections::{HashMap, HashSet, VecDeque};
4use std::hash::{DefaultHasher, Hash, Hasher};
5use std::sync::atomic::{AtomicU64, AtomicUsize, Ordering};
6use std::sync::{Arc, Mutex};
7use std::time::{Duration, SystemTime, UNIX_EPOCH};
8
9use async_trait::async_trait;
10use fips_core::{FipsEndpoint, PeerIdentity};
11use nostr::{JsonUtil, Kind};
12use nostr_pubsub::{
13    DEFAULT_INV_WANT_FANOUT, EventBus, EventId, EventPolicyContext, EventSource, Filter,
14    FipsPubsubWireCodec, FipsPubsubWireMessage, MeshPeerPolicy, NostrEventHandler,
15    NostrEventSubscriber, NostrEventSubscription, PolicyDecision, PublishReport, PubsubError,
16    PubsubPeerInterest, PubsubPeerSubscriptionStore, PubsubPolicy, PubsubProvider,
17    PubsubProviderMode, PubsubSubscriptionLimits, QueryEvent, QueryOptions, QueryReport, Result,
18    SOURCE_PRIORITY_FIPS_ENDPOINT, SourceId, SubscriptionDeliveryStatus, SubscriptionId,
19    VerifiedEvent,
20};
21use tokio::sync::{mpsc, oneshot};
22use tokio::task::JoinHandle;
23use tokio::time::Instant;
24
25mod anonymous_publication;
26mod client_feeds;
27mod client_inner;
28mod client_publication;
29mod client_received_event;
30pub mod feed;
31mod privacy_roles;
32pub use anonymous_publication::{FipsAnonymousPublisher, FipsRemotePublication};
33pub use privacy_roles::FipsDiscoveryScope;
34mod client_lifecycle;
35mod client_peers;
36mod client_reputation;
37mod client_transport;
38mod local_delivery;
39mod peerfinding;
40mod pending_wants;
41mod provider_behavior;
42mod recent_events;
43mod replay_source;
44mod reputation;
45mod seen_ids;
46mod stats;
47mod stream;
48mod stream_tcp;
49mod wire_tcp;
50use client_inner::{ClientInner, ConnectedPeerLink};
51use client_lifecycle::ClientTasks;
52use client_peers::PeerLinkEpoch;
53use client_transport::transport_loop;
54pub use peerfinding::*;
55use pending_wants::PendingWants;
56use recent_events::RecentEvents;
57pub use reputation::*;
58pub use stats::*;
59pub use stream::*;
60pub use stream_tcp::*;
61use wire_tcp::{WireTcpDriver, WireTcpOptions};
62
63pub const FIPS_NOSTR_PUBSUB_SERVICE_PORT: u16 = 7368;
64pub const FIPS_NOSTR_PUBSUB_CAPABILITY: &str = "nostr.pubsub/1";
65pub const FIPS_NOSTR_PUBSUB_MAX_REPLAY_EVENTS: usize = 8;
66pub const FIPS_NOSTR_PUBSUB_DEFAULT_MAX_HOPS: u8 = 4;
67/// Event IDs retained without full signed payloads for accepted-event dedup.
68pub const FIPS_NOSTR_PUBSUB_MAX_SEEN_EVENT_IDS: usize = 4_096;
69/// Unaccepted IDs retained for one authenticated peer/subscription epoch.
70pub const FIPS_NOSTR_PUBSUB_MAX_OBSERVED_IDS_PER_SCOPE: usize = 1_024;
71/// Aggregate bound across all authenticated peer/subscription observations.
72pub const FIPS_NOSTR_PUBSUB_MAX_OBSERVED_IDS: usize = 16_384;
73
74/// Maximum encoded Nostr frame carried in one reliable TCP record.
75pub const FIPS_NOSTR_PUBSUB_MAX_FRAME_BYTES: usize = u16::MAX as usize - 10;
76
77const FIPS_PEER_ADVERT_REFRESH_INTERVAL: Duration = Duration::from_mins(30);
78
79/// Resource limits and replay window for a FIPS pubsub client.
80#[derive(Debug, Clone, PartialEq, Eq)]
81pub struct FipsPubsubClientOptions {
82    /// How long an [`EventBus::query`] waits for subscribed peer replies.
83    pub query_timeout: Duration,
84    /// Maximum encoded Nostr frame accepted from or sent to a peer.
85    pub max_frame_bytes: usize,
86    /// Maximum connected FIPS peers retained by the client. A larger endpoint
87    /// mesh uses a stable bounded subset without disconnecting its other links.
88    pub max_connected_peers: usize,
89    /// Known pubsub service identities reachable through FIPS routing, even
90    /// without a direct link. These take priority within `max_connected_peers`.
91    /// Transport-restricted clients cannot use routed peers because a routed
92    /// path's underlying transports are not exposed by the endpoint API.
93    pub routed_peers: Vec<String>,
94    /// Opt in to serving previously unknown authenticated routed clients.
95    /// Zero (the default) only admits selected peers. Inbound clients share
96    /// `max_connected_peers` and all queue/subscription limits. These slots are
97    /// reserved from the outgoing peer roster; idle leases
98    /// expire and never trigger outgoing connections or subscription replay.
99    pub max_inbound_routed_peers: usize,
100    /// Admit verified one-shot EVENT submissions and return a remote OK receipt.
101    /// Requires bounded inbound slots; anonymous clients are never selected as providers.
102    pub accept_anonymous_publications: bool,
103    /// Maximum subscribed peers selected for one live inventory fanout.
104    pub fanout: usize,
105    /// Maximum simultaneous application streaming or query subscriptions.
106    ///
107    /// The client's internal FIPS peer-advert subscription is reserved in
108    /// addition to this limit.
109    pub max_active_subscriptions: usize,
110    /// Maximum Nostr filters carried by one subscription.
111    pub max_filters_per_subscription: usize,
112    /// Maximum events retained for replay, in each subscription's channel, and
113    /// in its pending FIFO. Exhausting both delivery bounds stops that wire
114    /// subscription and reports [`SubscriptionDeliveryStatus::Lagged`].
115    pub max_replay_events: usize,
116    /// Maximum TCP records drained from FIPS in one receive turn.
117    pub receive_batch_size: usize,
118    /// Maximum live inventory propagation distance through the peer mesh.
119    pub max_hops: u8,
120}
121
122impl Default for FipsPubsubClientOptions {
123    fn default() -> Self {
124        Self {
125            query_timeout: Duration::from_millis(500),
126            max_frame_bytes: FIPS_NOSTR_PUBSUB_MAX_FRAME_BYTES,
127            max_connected_peers: 64,
128            routed_peers: Vec::new(),
129            max_inbound_routed_peers: 0,
130            accept_anonymous_publications: false,
131            fanout: DEFAULT_INV_WANT_FANOUT,
132            max_active_subscriptions: 64,
133            max_filters_per_subscription: 4,
134            max_replay_events: FIPS_NOSTR_PUBSUB_MAX_REPLAY_EVENTS,
135            receive_batch_size: 64,
136            max_hops: FIPS_NOSTR_PUBSUB_DEFAULT_MAX_HOPS,
137        }
138    }
139}
140
141impl FipsPubsubClientOptions {
142    fn outbound_peer_capacity(&self) -> usize {
143        self.max_connected_peers
144            .saturating_sub(self.max_inbound_routed_peers)
145    }
146
147    fn validate_peer_transport(&self, restricted: bool) -> Result<()> {
148        self.validate()?;
149        if self.max_inbound_routed_peers != 0 && restricted {
150            return Err(invalid_option(
151                "inbound routed peers require an unrestricted FIPS client",
152            ));
153        }
154        Ok(())
155    }
156
157    fn subscription_limits(&self) -> PubsubSubscriptionLimits {
158        PubsubSubscriptionLimits {
159            max_peers: self.max_connected_peers,
160            max_subscriptions_per_peer: self.max_active_subscriptions.saturating_add(1),
161            max_filters_per_subscription: self.max_filters_per_subscription,
162        }
163    }
164
165    fn wire_tcp_options(&self) -> WireTcpOptions {
166        let records = self
167            .max_active_subscriptions
168            .saturating_add(1)
169            .saturating_add(self.max_replay_events)
170            .saturating_add(1);
171        WireTcpOptions {
172            frame_capacity: self.max_frame_bytes,
173            peer_capacity: self.max_connected_peers,
174            inbound_peer_capacity: self.max_inbound_routed_peers,
175            queue_records_per_peer: records,
176            queue_bytes_per_peer: self
177                .max_frame_bytes
178                .saturating_add(4)
179                .saturating_mul(records),
180            drive_io_bytes: 512 * 1_024,
181            drive_frames: self.receive_batch_size,
182        }
183    }
184
185    fn validate(&self) -> Result<()> {
186        if self.accept_anonymous_publications && self.max_inbound_routed_peers == 0 {
187            return Err(invalid_option(
188                "anonymous publication admission requires bounded inbound slots",
189            ));
190        }
191        if self.max_inbound_routed_peers > self.max_connected_peers {
192            return Err(invalid_option(
193                "max_inbound_routed_peers cannot exceed max_connected_peers",
194            ));
195        }
196        if self.query_timeout.is_zero() {
197            return Err(invalid_option("query_timeout must be greater than zero"));
198        }
199        for (name, value) in [
200            ("max_frame_bytes", self.max_frame_bytes),
201            ("max_connected_peers", self.max_connected_peers),
202            ("fanout", self.fanout),
203            ("max_active_subscriptions", self.max_active_subscriptions),
204            (
205                "max_filters_per_subscription",
206                self.max_filters_per_subscription,
207            ),
208            ("max_replay_events", self.max_replay_events),
209            ("receive_batch_size", self.receive_batch_size),
210        ] {
211            if value == 0 {
212                return Err(invalid_option(format!("{name} must be greater than zero")));
213            }
214        }
215        if self.max_frame_bytes > FIPS_NOSTR_PUBSUB_MAX_FRAME_BYTES {
216            return Err(invalid_option(format!(
217                "max_frame_bytes cannot exceed TCP/FIPS record limit {FIPS_NOSTR_PUBSUB_MAX_FRAME_BYTES}"
218            )));
219        }
220        if self.fanout > self.max_connected_peers {
221            return Err(invalid_option("fanout cannot exceed max_connected_peers"));
222        }
223        if self.max_hops == 0 {
224            return Err(invalid_option("max_hops must be greater than zero"));
225        }
226        Ok(())
227    }
228}
229
230pub struct FipsPubsubClient {
231    inner: Arc<ClientInner>,
232    tasks: tokio::sync::Mutex<ClientTasks>,
233}
234
235enum TransportCommand {
236    Send { peer: PeerIdentity, frame: Vec<u8> },
237    Cooldown { peer: PeerIdentity },
238}
239
240fn default_peerfinding_filter() -> Filter {
241    Filter::new()
242        .kind(Kind::Custom(fips_core::discovery::nostr::ADVERT_KIND))
243        .identifier(fips_core::discovery::nostr::ADVERT_IDENTIFIER)
244}
245
246async fn run_default_peerfinding(
247    inner: Arc<ClientInner>,
248    mut subscription: FipsPubsubSubscription,
249) {
250    loop {
251        let refresh = tokio::time::sleep(publish_local_fips_advert(&inner).await);
252        tokio::pin!(refresh);
253        loop {
254            tokio::select! {
255                delivery = subscription.recv() => {
256                    let Some(delivery) = delivery else { return; };
257                    if let Err(error) = inner.retain_peer_announcement(delivery.event.clone()).await {
258                        eprintln!("nostr-pubsub: failed to retain peer announcement: {error}");
259                    }
260                    let _ = inner
261                        .endpoint
262                        .ingest_nostr_discovery_event(delivery.event.into_event())
263                        .await;
264                }
265                () = &mut refresh => break,
266            }
267        }
268    }
269}
270
271async fn publish_local_fips_advert(inner: &ClientInner) -> Duration {
272    if !inner.role.advertises() {
273        return FIPS_PEER_ADVERT_REFRESH_INTERVAL;
274    }
275    let Ok(Some(event)) = inner.endpoint.local_nostr_discovery_advert_event().await else {
276        return FIPS_PEER_ADVERT_REFRESH_INTERVAL;
277    };
278    let refresh_after = fips_advert_refresh_delay(&event);
279    let Ok(event) = VerifiedEvent::try_from(event) else {
280        return refresh_after;
281    };
282    if let Err(error) = inner.retain_peer_announcement(event.clone()).await {
283        eprintln!("nostr-pubsub: failed to retain local peer announcement: {error}");
284    }
285    let _ = inner
286        .publish(
287            event,
288            EventSource::fips_endpoint(inner.endpoint.npub().to_string()),
289        )
290        .await;
291    refresh_after
292}
293
294fn fips_advert_refresh_delay(event: &nostr::Event) -> Duration {
295    event
296        .tags
297        .expiration()
298        .map(|expiration| {
299            expiration
300                .as_secs()
301                .saturating_sub(event.created_at.as_secs())
302        })
303        .filter(|ttl_secs| *ttl_secs > 0)
304        .map_or(FIPS_PEER_ADVERT_REFRESH_INTERVAL, |ttl_secs| {
305            Duration::from_secs((ttl_secs / 2).max(1))
306        })
307        .min(FIPS_PEER_ADVERT_REFRESH_INTERVAL)
308}
309
310/// Optional application policies. Peer preference and event admission are
311/// separate from permission to access application data. Empty policies retain
312/// the default client behavior; no external trust identity is selected here.
313#[derive(Clone)]
314pub struct FipsPubsubClientPolicies {
315    pub peers: Option<Arc<dyn MeshPeerPolicy>>,
316    pub events: Option<Arc<dyn PubsubPolicy>>,
317    /// Exploration slots when ranking direct peers and live fanout. Explicit
318    /// routed identities retain priority. Endpoint-owned links are unchanged.
319    pub unknown_peer_reserve: usize,
320}
321
322impl Default for FipsPubsubClientPolicies {
323    fn default() -> Self {
324        Self {
325            peers: None,
326            events: None,
327            unknown_peer_reserve: 1,
328        }
329    }
330}
331
332impl FipsPubsubClient {
333    pub async fn start(
334        endpoint: Arc<FipsEndpoint>,
335        options: FipsPubsubClientOptions,
336    ) -> Result<Self> {
337        Self::start_with_policies(endpoint, options, FipsPubsubClientPolicies::default()).await
338    }
339
340    /// Start with event admission applied before received events enter the
341    /// replay cache, local delivery, or multi-hop forwarding.
342    pub async fn start_with_policy(
343        endpoint: Arc<FipsEndpoint>,
344        options: FipsPubsubClientOptions,
345        policy: Arc<dyn PubsubPolicy>,
346    ) -> Result<Self> {
347        Self::start_with_policies(
348            endpoint,
349            options,
350            FipsPubsubClientPolicies {
351                events: Some(policy),
352                ..Default::default()
353            },
354        )
355        .await
356    }
357
358    /// Start with a shared peer preference and/or event-admission policy.
359    /// Changes to a policy's shared state affect existing subscriptions.
360    pub async fn start_with_policies(
361        endpoint: Arc<FipsEndpoint>,
362        options: FipsPubsubClientOptions,
363        policies: FipsPubsubClientPolicies,
364    ) -> Result<Self> {
365        Self::start_for_peer_selection(endpoint, options, None, HashSet::new(), policies).await
366    }
367
368    /// Start a client that never uses peers carried by the named FIPS
369    /// transports. This prevents a provider from recursively selecting the
370    /// transport that it is itself carrying while leaving every other
371    /// authenticated peer eligible.
372    pub async fn start_excluding_peer_transports<I, S>(
373        endpoint: Arc<FipsEndpoint>,
374        options: FipsPubsubClientOptions,
375        excluded_peer_transports: I,
376    ) -> Result<Self>
377    where
378        I: IntoIterator<Item = S>,
379        S: Into<String>,
380    {
381        let excluded_peer_transports = excluded_peer_transports
382            .into_iter()
383            .map(Into::into)
384            .collect();
385        Self::start_for_peer_selection(
386            endpoint,
387            options,
388            None,
389            excluded_peer_transports,
390            FipsPubsubClientPolicies::default(),
391        )
392        .await
393    }
394
395    #[cfg(test)]
396    async fn start_for_transport(
397        endpoint: Arc<FipsEndpoint>,
398        options: FipsPubsubClientOptions,
399        peer_transport: &'static str,
400    ) -> Result<Self> {
401        Self::start_for_peer_selection(
402            endpoint,
403            options,
404            Some(peer_transport),
405            HashSet::new(),
406            FipsPubsubClientPolicies::default(),
407        )
408        .await
409    }
410
411    #[cfg(test)]
412    async fn start_for_transport_with_policy(
413        endpoint: Arc<FipsEndpoint>,
414        options: FipsPubsubClientOptions,
415        peer_transport: &'static str,
416        policy: Arc<dyn PubsubPolicy>,
417    ) -> Result<Self> {
418        Self::start_for_peer_selection(
419            endpoint,
420            options,
421            Some(peer_transport),
422            HashSet::new(),
423            FipsPubsubClientPolicies {
424                events: Some(policy),
425                ..Default::default()
426            },
427        )
428        .await
429    }
430
431    async fn start_for_peer_selection(
432        endpoint: Arc<FipsEndpoint>,
433        options: FipsPubsubClientOptions,
434        peer_transport: Option<&'static str>,
435        excluded_peer_transports: HashSet<String>,
436        policies: FipsPubsubClientPolicies,
437    ) -> Result<Self> {
438        Self::start_for_role(
439            endpoint,
440            options,
441            peer_transport,
442            excluded_peer_transports,
443            policies,
444            privacy_roles::ClientRole::Full,
445        )
446        .await
447    }
448
449    async fn start_for_role(
450        endpoint: Arc<FipsEndpoint>,
451        options: FipsPubsubClientOptions,
452        peer_transport: Option<&'static str>,
453        excluded_peer_transports: HashSet<String>,
454        policies: FipsPubsubClientPolicies,
455        role: privacy_roles::ClientRole,
456    ) -> Result<Self> {
457        let restricted = peer_transport.is_some() || !excluded_peer_transports.is_empty();
458        options.validate_peer_transport(restricted)?;
459        let routed_peers = client_peers::validate_routed_peers(
460            options.routed_peers.clone(),
461            options.outbound_peer_capacity(),
462            endpoint.npub(),
463            restricted,
464        )?;
465        let codec = FipsPubsubWireCodec::new(options.max_frame_bytes)?;
466        let subscription_limits = options.subscription_limits();
467        let max_replay_events = options.max_replay_events;
468        let pending_wants = PendingWants::from_options(&options);
469        let driver = WireTcpDriver::bind_for_role(
470            Arc::clone(&endpoint),
471            options.wire_tcp_options(),
472            tcp_isn_seed(endpoint.npub()),
473            role.advertises(),
474        )
475        .await?;
476        let command_capacity = options
477            .max_connected_peers
478            .saturating_mul(options.receive_batch_size)
479            .max(1);
480        let (transport_tx, transport_rx) = mpsc::channel(command_capacity);
481        // A transport turn can enqueue an entire receive batch before the
482        // replay workers run. Even a one-peer provider must admit its discovery
483        // and application history requests together. Keep the existing peer
484        // bound for larger meshes and the same default queue capacity.
485        let replay_capacity = options.max_connected_peers.max(options.receive_batch_size);
486        let (replay_tx, replay_rx) = mpsc::channel(replay_capacity);
487        let inner = Arc::new(ClientInner {
488            admission: Mutex::new(true),
489            role,
490            publications: Mutex::new(HashMap::new()),
491            endpoint: Arc::clone(&endpoint),
492            codec,
493            feeds: Mutex::new(client_feeds::FeedState::new(&options)),
494            options,
495            routed_peers: Mutex::new(routed_peers),
496            peer_transport,
497            excluded_peer_transports,
498            event_policy: policies.events,
499            peer_policy: policies.peers,
500            unknown_peer_reserve: policies.unknown_peer_reserve,
501            transport_tx,
502            replay_source: Mutex::new(None),
503            peer_announcement_store: Mutex::new(None),
504            replay_tx,
505            connected_transport_peers: AtomicUsize::new(0),
506            req_frames_received: AtomicU64::new(0),
507            close_frames_received: AtomicU64::new(0),
508            event_frames_received: AtomicU64::new(0),
509            inv_frames_received: AtomicU64::new(0),
510            want_frames_received: AtomicU64::new(0),
511            want_frames_sent: AtomicU64::new(0),
512            subscription_events_received: AtomicU64::new(0),
513            expired_wants: AtomicU64::new(0),
514            provider_cooldowns: AtomicU64::new(0),
515            tcp_receive_batches: AtomicU64::new(0),
516            tcp_datagrams_received: AtomicU64::new(0),
517            tcp_datagrams_rejected: AtomicU64::new(0),
518            tcp_poll_turns: AtomicU64::new(0),
519            transport_errors: AtomicU64::new(0),
520            reputation_errors: AtomicU64::new(0),
521            next_subscription_id: AtomicU64::new(1),
522            subscriptions: Mutex::new(HashMap::new()),
523            peer_subscriptions: Mutex::new(PubsubPeerSubscriptionStore::new(subscription_limits)),
524            recent_events: Mutex::new(RecentEvents::new(
525                max_replay_events,
526                FIPS_NOSTR_PUBSUB_MAX_SEEN_EVENT_IDS,
527            )),
528            observed_inventories: Mutex::new(seen_ids::ScopedSeenIds::new(
529                FIPS_NOSTR_PUBSUB_MAX_OBSERVED_IDS_PER_SCOPE,
530                FIPS_NOSTR_PUBSUB_MAX_OBSERVED_IDS,
531            )),
532            observed_full_events: Mutex::new(seen_ids::ScopedSeenIds::new(
533                FIPS_NOSTR_PUBSUB_MAX_OBSERVED_IDS_PER_SCOPE,
534                FIPS_NOSTR_PUBSUB_MAX_OBSERVED_IDS,
535            )),
536            provider_behavior: Mutex::new(provider_behavior::ProviderBehavior::default()),
537            pending_wants: Mutex::new(pending_wants),
538        });
539        let peerfinding_subscription = inner
540            .subscribe(vec![default_peerfinding_filter()], true)
541            .await?;
542        let (transport_stop, transport_stopped) = tokio::sync::oneshot::channel();
543        let transport_task = tokio::spawn(transport_loop(
544            Arc::downgrade(&inner),
545            driver,
546            transport_rx,
547            transport_stopped,
548        ));
549        let replay_task = tokio::spawn(replay_source::run(Arc::downgrade(&inner), replay_rx));
550        let peerfinding_task = Some(tokio::spawn(run_default_peerfinding(
551            Arc::clone(&inner),
552            peerfinding_subscription,
553        )));
554        Ok(Self {
555            inner,
556            tasks: tokio::sync::Mutex::new(ClientTasks {
557                transport: Some(transport_task),
558                transport_stop: Some(transport_stop),
559                peerfinding: peerfinding_task,
560                reputation: None,
561                replay: Some(replay_task),
562            }),
563        })
564    }
565
566    #[must_use]
567    pub fn options(&self) -> &FipsPubsubClientOptions {
568        &self.inner.options
569    }
570
571    /// Replace application-known service identities without rebuilding live
572    /// subscriptions. The transport applies the bounded roster on its next
573    /// poll. Invalid input leaves the previous roster unchanged.
574    /// [`Self::options`] continues to describe the initial configuration.
575    pub fn set_routed_peers(&self, peers: Vec<String>) -> Result<()> {
576        let peers = client_peers::validate_routed_peers(
577            peers,
578            self.inner.options.outbound_peer_capacity(),
579            self.inner.endpoint.npub(),
580            self.inner.peer_transport.is_some() || !self.inner.excluded_peer_transports.is_empty(),
581        )?;
582        *self
583            .inner
584            .routed_peers
585            .lock()
586            .map_err(|_| poisoned("FIPS routed peers"))? = peers;
587        Ok(())
588    }
589
590    pub fn connected_peer_count(&self) -> Result<usize> {
591        Ok(self.inner.connected_transport_peers.load(Ordering::Relaxed))
592    }
593
594    pub fn active_subscription_count(&self) -> Result<usize> {
595        Ok(self.inner.lock_subscriptions()?.len())
596    }
597
598    pub fn peer_subscription_count(&self) -> Result<usize> {
599        self.inner
600            .peer_subscriptions
601            .lock()
602            .map(|subscriptions| subscriptions.subscription_count())
603            .map_err(|_| poisoned("FIPS peer subscription state"))
604    }
605
606    pub async fn subscribe(&self, filters: Vec<Filter>) -> Result<FipsPubsubSubscription> {
607        self.inner.subscribe(filters, true).await
608    }
609
610    /// Open a public peer feed for one filter (see [`feed`]). Events this
611    /// client publishes or receives on it fill a bounded window; a peer that
612    /// provides the feed reconciles against that window and announces only
613    /// what is missing. `peers` limits which peers get the request; `None`
614    /// sends it to every connected peer. There is no local replay.
615    pub async fn subscribe_feed(
616        &self,
617        filter: Filter,
618        peers: Option<Vec<String>>,
619    ) -> Result<FipsPubsubSubscription> {
620        self.inner
621            .subscribe_feed(filter, peers.map(|peers| peers.into_iter().collect()))
622            .await
623    }
624
625    /// A subscription provider that requires new peer observations. It shares
626    /// this client's connections, but never satisfies a subscription by replaying
627    /// its local cache. Useful when a cached announcement cannot confirm freshness.
628    #[must_use]
629    pub fn fresh_subscriber(self: &Arc<Self>) -> FipsFreshEventSubscriber {
630        FipsFreshEventSubscriber {
631            client: self.clone(),
632        }
633    }
634}
635
636/// Live peer observations over an existing FIPS client, without local replay.
637#[derive(Clone)]
638pub struct FipsFreshEventSubscriber {
639    client: Arc<FipsPubsubClient>,
640}
641
642#[async_trait]
643impl NostrEventSubscriber for FipsFreshEventSubscriber {
644    async fn subscribe(
645        &self,
646        filters: Vec<Filter>,
647        handler: NostrEventHandler,
648    ) -> Result<Box<dyn NostrEventSubscription>> {
649        Ok(forward_subscription(
650            self.client.inner.subscribe(filters, false).await?,
651            handler,
652        ))
653    }
654}
655
656#[async_trait]
657impl EventBus for FipsPubsubClient {
658    async fn publish(&self, event: VerifiedEvent, source: EventSource) -> Result<PublishReport> {
659        self.inner.publish(event, source).await
660    }
661
662    async fn query(&self, filters: Vec<Filter>, options: QueryOptions) -> Result<QueryReport> {
663        drop(self.inner.admit()?);
664        let limit = options
665            .limit
666            .or_else(|| filters.iter().filter_map(|filter| filter.limit).min())
667            .unwrap_or(self.inner.options.max_replay_events)
668            .min(self.inner.options.max_replay_events);
669        if limit == 0 {
670            return Ok(QueryReport::default());
671        }
672
673        let mut subscription = self.subscribe(filters).await?;
674        let deadline = Instant::now() + self.inner.options.query_timeout;
675        let mut events = Vec::with_capacity(limit);
676        while events.len() < limit {
677            match tokio::time::timeout_at(deadline, subscription.recv()).await {
678                Ok(Some(event)) => events.push(event),
679                Ok(None) | Err(_) => break,
680            }
681        }
682        subscription.close();
683        Ok(QueryReport { events })
684    }
685}
686
687impl PubsubProvider for FipsPubsubClient {
688    fn mode(&self) -> PubsubProviderMode {
689        PubsubProviderMode::LocalOnly
690    }
691}
692
693#[async_trait]
694impl NostrEventSubscriber for FipsPubsubClient {
695    async fn subscribe(
696        &self,
697        filters: Vec<Filter>,
698        handler: NostrEventHandler,
699    ) -> Result<Box<dyn NostrEventSubscription>> {
700        Ok(forward_subscription(
701            FipsPubsubClient::subscribe(self, filters).await?,
702            handler,
703        ))
704    }
705}
706
707fn forward_subscription(
708    mut subscription: FipsPubsubSubscription,
709    handler: NostrEventHandler,
710) -> Box<dyn NostrEventSubscription> {
711    let (close_sender, close_receiver) = oneshot::channel();
712    let delivery = Arc::clone(&subscription.delivery);
713    let task = tokio::spawn(async move {
714        tokio::select! {
715            biased;
716            _ = close_receiver => {}
717            () = async {
718                while let Some(event) = subscription.recv().await {
719                    handler(event);
720                }
721            } => {}
722        }
723        subscription.close();
724    });
725    Box::new(FipsRoutedSubscription {
726        delivery,
727        close_sender: Some(close_sender),
728        task: Some(task),
729    })
730}
731
732struct FipsRoutedSubscription {
733    delivery: Arc<local_delivery::LocalDelivery>,
734    close_sender: Option<oneshot::Sender<()>>,
735    task: Option<JoinHandle<()>>,
736}
737
738impl Drop for FipsRoutedSubscription {
739    fn drop(&mut self) {
740        self.close_sender.take();
741        if let Some(task) = self.task.take() {
742            task.abort();
743        }
744    }
745}
746
747#[async_trait]
748impl NostrEventSubscription for FipsRoutedSubscription {
749    fn delivery_status(&self) -> Option<SubscriptionDeliveryStatus> {
750        Some(self.delivery.status())
751    }
752
753    async fn close(mut self: Box<Self>) -> Result<()> {
754        // Terminal delivery has stopped accepting bodies, but may still have
755        // an admitted FIFO to drain. Only an active caller explicitly cancels.
756        if self.delivery.status() == SubscriptionDeliveryStatus::Active {
757            self.close_sender.take();
758        }
759        if let Some(task) = self.task.take() {
760            task.await
761                .map_err(|error| PubsubError::Storage(format!("close FIPS live route: {error}")))?;
762        }
763        self.close_sender.take();
764        Ok(())
765    }
766}
767
768pub struct FipsPubsubSubscription {
769    subscription_id: SubscriptionId,
770    key: String,
771    receiver: mpsc::Receiver<QueryEvent>,
772    delivery: Arc<local_delivery::LocalDelivery>,
773    inner: Arc<ClientInner>,
774    closed: bool,
775}
776
777impl FipsPubsubSubscription {
778    #[must_use]
779    pub fn id(&self) -> &SubscriptionId {
780        &self.subscription_id
781    }
782
783    pub async fn recv(&mut self) -> Option<QueryEvent> {
784        self.delivery.refill();
785        let event = self.receiver.recv().await;
786        self.delivery.refill();
787        event
788    }
789
790    pub fn try_recv(&mut self) -> std::result::Result<QueryEvent, mpsc::error::TryRecvError> {
791        self.delivery.refill();
792        let event = self.receiver.try_recv();
793        self.delivery.refill();
794        event
795    }
796
797    /// `Lagged` remains visible after close or client shutdown; admitted bodies
798    /// still drain. The caller must reconcile missed events against an
799    /// authoritative history or event store. Reopening resumes live delivery,
800    /// but cannot guarantee recovering an event after the replay cache evicts it.
801    #[must_use]
802    pub fn delivery_status(&self) -> SubscriptionDeliveryStatus {
803        self.delivery.status()
804    }
805
806    pub fn close(mut self) {
807        self.cleanup();
808    }
809
810    /// For a feed subscription, replace the peers it is sent to. Removed peers
811    /// get a `CLOSE`; newly admitted connected peers get the request.
812    pub async fn set_feed_peers(&self, peers: Option<Vec<String>>) -> Result<()> {
813        self.inner
814            .set_feed_peers(&self.key, peers.map(|peers| peers.into_iter().collect()))
815            .await
816    }
817
818    fn cleanup(&mut self) {
819        if self.closed {
820            return;
821        }
822        self.closed = true;
823        self.inner.close_subscription(&self.key);
824    }
825}
826
827impl Drop for FipsPubsubSubscription {
828    fn drop(&mut self) {
829        self.cleanup();
830    }
831}
832
833fn publish_report(sent: usize, peer_count: usize, peers: &str) -> Result<PublishReport> {
834    if sent == 0 {
835        return Err(PubsubError::Storage(format!(
836            "failed to publish to {peer_count} {peers}"
837        )));
838    }
839    Ok(PublishReport {
840        accepted: true,
841        priority: SOURCE_PRIORITY_FIPS_ENDPOINT,
842        reason: (sent < peer_count).then(|| format!("sent to {sent} of {peer_count} {peers}")),
843    })
844}
845
846fn event_payload_bytes(event: &VerifiedEvent) -> Result<u32> {
847    u32::try_from(event.as_event().as_json().len())
848        .map_err(|_| PubsubError::Validation("Nostr event payload is too large".to_string()))
849}
850
851fn now_ms() -> u64 {
852    SystemTime::now()
853        .duration_since(UNIX_EPOCH)
854        .unwrap_or_default()
855        .as_millis()
856        .try_into()
857        .unwrap_or(u64::MAX)
858}
859
860fn bounded_delivery_targets(
861    targets: Vec<(String, Vec<SubscriptionId>)>,
862    event_id: &EventId,
863    fanout: usize,
864) -> Vec<(String, Vec<SubscriptionId>)> {
865    if targets.len() <= fanout {
866        return targets;
867    }
868    let mut ranked = targets
869        .into_iter()
870        .map(|target| {
871            let mut hasher = DefaultHasher::new();
872            event_id.hash(&mut hasher);
873            target.0.hash(&mut hasher);
874            (hasher.finish(), target)
875        })
876        .collect::<Vec<_>>();
877    ranked.sort_unstable_by(|left, right| {
878        left.0.cmp(&right.0).then_with(|| left.1.0.cmp(&right.1.0))
879    });
880    ranked
881        .into_iter()
882        .take(fanout)
883        .map(|(_, target)| target)
884        .collect()
885}
886
887fn tcp_isn_seed(local_npub: &str) -> u64 {
888    let mut hasher = DefaultHasher::new();
889    local_npub.hash(&mut hasher);
890    SystemTime::now()
891        .duration_since(UNIX_EPOCH)
892        .unwrap_or_default()
893        .as_nanos()
894        .hash(&mut hasher);
895    hasher.finish()
896}
897
898fn invalid_option(message: impl Into<String>) -> PubsubError {
899    PubsubError::Validation(format!(
900        "invalid FIPS pubsub client option: {}",
901        message.into()
902    ))
903}
904
905fn no_connected_peers(transport: Option<&str>) -> PubsubError {
906    let scope = transport.map_or_else(String::new, |value| format!(" {value}"));
907    PubsubError::Storage(format!("no connected{scope} FIPS pubsub peers"))
908}
909
910fn storage_error(operation: &str, error: impl std::fmt::Display) -> PubsubError {
911    PubsubError::Storage(format!("{operation}: {error}"))
912}
913
914fn poisoned(name: &str) -> PubsubError {
915    PubsubError::Storage(format!("{name} poisoned"))
916}
917
918#[cfg(test)]
919mod peerfinding_runtime_tests;
920#[cfg(test)]
921mod tests;