fips-core 0.4.0

Reusable FIPS mesh, endpoint, transport, and protocol library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140

use super::*;

impl FipsEndpoint {
    /// Snapshot signed machine-rating events for peers with enough local
    /// health evidence. Event signing remains inside the FIPS node identity.
    pub async fn peer_rating_events(
        &self,
        scope: impl Into<String>,
    ) -> Result<Vec<nostr::Event>, FipsEndpointError> {
        let (response_tx, response_rx) = oneshot::channel();
        self.control(
            "peer rating snapshot",
            NodeEndpointControlCommand::PeerRatingEvents {
                scope: scope.into(),
                response_tx,
            },
            response_rx,
        )
        .await?
        .map_err(FipsEndpointError::Node)
    }

    /// Feed a signed Nostr event received by an external adapter into FIPS.
    ///
    /// Public peer adverts and ratings enter their validated discovery caches;
    /// targeted ephemeral relay datagrams enter the Nostr relay transport.
    /// Unsupported, invalid, stale, or incorrectly addressed events return
    /// `false`.
    pub async fn ingest_nostr_event(&self, event: nostr::Event) -> Result<bool, FipsEndpointError> {
        let (response_tx, response_rx) = oneshot::channel();
        self.control(
            "Nostr event ingest",
            NodeEndpointControlCommand::IngestNostrEvent { event, response_tx },
            response_rx,
        )
        .await
    }

    /// Compatibility name for callers that only feed discovery events.
    pub async fn ingest_nostr_discovery_event(
        &self,
        event: nostr::Event,
    ) -> Result<bool, FipsEndpointError> {
        self.ingest_nostr_event(event).await
    }

    #[deprecated(since = "0.3.98", note = "use ingest_nostr_discovery_event")]
    pub async fn ingest_nostr_pubsub_event(
        &self,
        event: nostr::Event,
    ) -> Result<bool, FipsEndpointError> {
        self.ingest_nostr_event(event).await
    }

    /// Drain signed ephemeral FIPS datagram events for the external relay
    /// adapter. Relay selection remains outside FIPS.
    pub async fn drain_nostr_relay_events(
        &self,
        limit: usize,
    ) -> Result<Vec<nostr::Event>, FipsEndpointError> {
        let (response_tx, response_rx) = oneshot::channel();
        self.control(
            "Nostr relay event drain",
            NodeEndpointControlCommand::DrainNostrRelayEvents {
                limit: limit.max(1),
                response_tx,
            },
            response_rx,
        )
        .await
    }

    /// Snapshot the endpoint addresses this node is currently advertising via
    /// Nostr discovery.
    pub async fn local_advertised_endpoints(
        &self,
    ) -> Result<Vec<crate::discovery::nostr::OverlayEndpointAdvert>, FipsEndpointError> {
        let (response_tx, response_rx) = oneshot::channel();
        self.control(
            "local advert snapshot",
            NodeEndpointControlCommand::LocalAdvertSnapshot { response_tx },
            response_rx,
        )
        .await
    }

    /// Return the signed local peer advert for an external peerfinding provider.
    ///
    /// This only creates the ordinary kind 37195 event; it does not select or
    /// contact relays. `None` means advertising is disabled or no local
    /// transport currently has an advert-eligible endpoint.
    pub async fn local_nostr_discovery_advert_event(
        &self,
    ) -> Result<Option<nostr::Event>, FipsEndpointError> {
        let (response_tx, response_rx) = oneshot::channel();
        match self
            .control(
                "local Nostr discovery advert",
                NodeEndpointControlCommand::LocalNostrDiscoveryAdvertEvent { response_tx },
                response_rx,
            )
            .await?
        {
            Ok(event) => Ok(event),
            Err(error) => Err(FipsEndpointError::Node(error)),
        }
    }

    /// Snapshot live Nostr relay states used by the embedded endpoint.
    pub async fn relay_statuses(&self) -> Result<Vec<FipsEndpointRelayStatus>, FipsEndpointError> {
        let (response_tx, response_rx) = oneshot::channel();
        self.control(
            "relay snapshot",
            NodeEndpointControlCommand::RelaySnapshot { response_tx },
            response_rx,
        )
        .await
        .map(|relays| {
            relays
                .into_iter()
                .map(FipsEndpointRelayStatus::from)
                .collect()
        })
    }

    /// Replace Nostr discovery relays without rebuilding the endpoint.
    pub async fn update_relays(&self, advert_relays: Vec<String>) -> Result<(), FipsEndpointError> {
        let (response_tx, response_rx) = oneshot::channel();
        self.control(
            "relay update",
            NodeEndpointControlCommand::UpdateRelays {
                advert_relays,
                response_tx,
            },
            response_rx,
        )
        .await?
        .map_err(FipsEndpointError::Node)
    }
}