rings_rpc/protos/
rings_node.rs

1//! Request/response message types for the rings node RPC API.
2//!
3//! These were previously generated from `rings_node.proto` via prost, but the
4//! wire format has always been JSON-RPC (never protobuf binary), so they are
5//! now plain serde structs. Field names and types are kept identical to the
6//! previous prost-generated output to preserve the on-the-wire JSON shape.
7
8use serde::Deserialize;
9use serde::Serialize;
10use serde_json::Value;
11
12/// Summary of a peer connection known by the local node.
13#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
14pub struct PeerInfo {
15    /// Decentralized identifier of the peer.
16    pub did: String,
17    /// Connection state reported by the swarm.
18    pub state: String,
19}
20
21/// Request to connect to a peer through its HTTP RPC endpoint.
22#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
23pub struct ConnectPeerViaHttpRequest {
24    /// HTTP endpoint URL exposed by the peer.
25    pub url: String,
26}
27
28/// Response returned after connecting to an HTTP-reachable peer.
29#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
30pub struct ConnectPeerViaHttpResponse {
31    /// Decentralized identifier resolved for the connected peer.
32    pub did: String,
33}
34
35/// Request to connect to a peer by decentralized identifier.
36#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
37pub struct ConnectWithDidRequest {
38    /// Decentralized identifier of the target peer.
39    pub did: String,
40}
41
42/// Empty response returned after a DID-based connection request is accepted.
43#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
44pub struct ConnectWithDidResponse {}
45
46/// Bootstrap peer descriptor used by seed connection requests.
47#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
48pub struct SeedPeer {
49    /// Decentralized identifier of the seed peer.
50    pub did: String,
51    /// HTTP endpoint URL for the seed peer.
52    pub url: String,
53}
54
55/// Request to connect to one or more bootstrap peers.
56#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
57pub struct ConnectWithSeedRequest {
58    /// Seed peers to connect through.
59    pub peers: Vec<SeedPeer>,
60}
61
62/// Empty response returned after seed connection setup is accepted.
63#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
64pub struct ConnectWithSeedResponse {}
65
66/// Request to list peers known by the local node.
67#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
68pub struct ListPeersRequest {}
69
70/// Response containing peers known by the local node.
71#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
72pub struct ListPeersResponse {
73    /// Known peer connection summaries.
74    pub peers: Vec<PeerInfo>,
75}
76
77/// Request to create a WebRTC offer for a peer.
78#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
79pub struct CreateOfferRequest {
80    /// Decentralized identifier of the peer receiving the offer.
81    pub did: String,
82}
83
84/// Response containing a serialized WebRTC offer.
85#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
86pub struct CreateOfferResponse {
87    /// Serialized session description offer.
88    pub offer: String,
89}
90
91/// Request to answer a serialized WebRTC offer.
92#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
93pub struct AnswerOfferRequest {
94    /// Serialized session description offer.
95    pub offer: String,
96}
97
98/// Response containing a serialized WebRTC answer.
99#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
100pub struct AnswerOfferResponse {
101    /// Serialized session description answer.
102    pub answer: String,
103}
104
105/// Request to accept a serialized WebRTC answer.
106#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
107pub struct AcceptAnswerRequest {
108    /// Serialized session description answer.
109    pub answer: String,
110}
111
112/// Empty response returned after an answer is accepted.
113#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
114pub struct AcceptAnswerResponse {}
115
116/// Request to disconnect from a peer.
117#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
118pub struct DisconnectRequest {
119    /// Decentralized identifier of the peer to disconnect.
120    pub did: String,
121}
122
123/// Empty response returned after a disconnect request is accepted.
124#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
125pub struct DisconnectResponse {}
126
127/// Request to send a backend protocol message to another peer.
128#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
129pub struct SendBackendMessageRequest {
130    /// Decentralized identifier of the destination peer.
131    pub destination_did: String,
132    /// Protocol namespace the payload is routed to (the extension `Envelope` namespace).
133    pub namespace: String,
134    /// Payload bytes, **base64-encoded** (standard alphabet). The `Envelope` payload is
135    /// binary (`Bytes`), so the RPC boundary base64-encodes it to stay binary-safe over the
136    /// JSON wire — do not pass raw UTF-8 here.
137    pub data: String,
138}
139
140/// Empty response returned after a backend message is queued.
141#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
142pub struct SendBackendMessageResponse {}
143
144/// Request to initiate an end-to-end encrypted handshake with a peer.
145#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
146pub struct SendE2eHandshakeRequest {
147    /// Decentralized identifier of the handshake target.
148    pub destination_did: String,
149}
150
151/// Response returned after queuing an end-to-end handshake.
152#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
153pub struct SendE2eHandshakeResponse {
154    /// Transaction identifier assigned to the handshake message.
155    pub tx_id: String,
156}
157
158/// Request to send an end-to-end encrypted message to a peer.
159#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
160pub struct SendE2eMessageRequest {
161    /// Decentralized identifier of the destination peer.
162    pub destination_did: String,
163    /// Recipient public key as a base58-check string. Hex is accepted by node implementations
164    /// for development ergonomics.
165    pub recipient_public_key: String,
166    /// Plaintext bytes, base64-encoded for the JSON RPC boundary.
167    pub data: String,
168    /// Optional plaintext frame length. `0` means the core default.
169    #[serde(default)]
170    pub max_plaintext_frame_len: u32,
171}
172
173/// Response returned after queuing an end-to-end encrypted message.
174#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
175pub struct SendE2eMessageResponse {
176    /// Stream identifier used by the encrypted message transport.
177    pub stream_id: String,
178}
179
180/// Request to publish a message to a DHT-backed topic.
181#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
182pub struct PublishMessageToTopicRequest {
183    /// Topic name receiving the message.
184    pub topic: String,
185    /// Message payload encoded for the JSON-RPC boundary.
186    pub data: String,
187}
188
189/// Empty response returned after a topic message is queued.
190#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
191pub struct PublishMessageToTopicResponse {}
192
193/// Request to fetch messages from a DHT-backed topic.
194#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
195pub struct FetchTopicMessagesRequest {
196    /// Topic name to read from.
197    pub topic: String,
198    /// Number of topic messages to skip from the start of the result set.
199    pub skip: i64,
200}
201
202/// Response containing messages fetched from a topic.
203#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
204pub struct FetchTopicMessagesResponse {
205    /// Topic message payloads encoded for the JSON-RPC boundary.
206    pub data: Vec<String>,
207}
208
209/// Request to register the local DID as a provider for a named service.
210#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
211pub struct RegisterServiceRequest {
212    /// Service name to register.
213    pub name: String,
214}
215
216/// Empty response returned after service registration is accepted.
217#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
218pub struct RegisterServiceResponse {}
219
220/// Request to resolve peers that provide a named service.
221#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
222pub struct LookupServiceRequest {
223    /// Service name to resolve.
224    pub name: String,
225}
226
227/// Response containing DIDs that provide a named service.
228#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
229pub struct LookupServiceResponse {
230    /// Decentralized identifiers of service providers.
231    pub dids: Vec<String>,
232}
233
234/// Request to list online node descriptors from the directory.
235#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
236pub struct LookupOnlineNodesRequest {
237    /// Whether expired descriptors should be included in the response.
238    #[serde(default)]
239    pub include_expired: bool,
240}
241
242/// Runtime class advertised by an online node descriptor.
243#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
244pub enum OnlineNodeTypeInfo {
245    /// Native node runtime.
246    #[default]
247    Native,
248    /// Browser node runtime.
249    Browser,
250    /// Foreign-function-interface hosted node runtime.
251    Ffi,
252}
253
254/// Public descriptor for a node currently known by the online-node directory.
255#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
256pub struct OnlineNodeDescriptorInfo {
257    /// Decentralized identifier of the advertised node.
258    pub did: String,
259    /// Verification public key encoded with the core serde shape.
260    pub public_key: Value,
261    /// Session encryption public key encoded with the core serde shape.
262    pub session_public_key: Value,
263    /// Runtime class of the advertised node.
264    pub node_type: OnlineNodeTypeInfo,
265    /// Overlay network identifier the descriptor belongs to.
266    pub network_id: u32,
267    /// Storage redundancy advertised by the node.
268    pub storage_redundancy: u16,
269    /// Number of virtual DHT nodes advertised by the node.
270    pub dht_virtual_nodes: u16,
271    /// Capability names advertised by the node.
272    pub capabilities: Vec<String>,
273    /// Optional endpoint hint clients may use for direct connection.
274    pub endpoint_hint: Option<String>,
275    /// Descriptor creation timestamp in Unix milliseconds.
276    pub started_at_ms: u64,
277    /// Last heartbeat timestamp in Unix milliseconds.
278    pub heartbeat_at_ms: u64,
279    /// Descriptor expiration timestamp in Unix milliseconds.
280    pub expires_at_ms: u64,
281    /// Rings node version that produced the descriptor.
282    pub version: String,
283    /// Descriptor signature encoded with the core serde shape.
284    pub signature: Value,
285}
286
287/// Response containing online node descriptors.
288#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
289pub struct LookupOnlineNodesResponse {
290    /// Online node descriptors returned by the directory.
291    pub nodes: Vec<OnlineNodeDescriptorInfo>,
292}
293
294/// Transport advertised by an onion exit service.
295#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
296pub enum OnionExitTransportInfo {
297    /// TCP stream exit transport.
298    #[default]
299    Tcp,
300    /// UDP datagram exit transport.
301    Udp,
302    /// WebTransport exit transport.
303    WebTransport,
304    /// Request-response protocol exit transport.
305    RequestResponse,
306    /// Legacy HTTPS exit marker retained for wire compatibility.
307    Https,
308}
309
310/// Service name and transport pair advertised by an onion exit.
311#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
312pub struct OnionExitServiceInfo {
313    /// Service name, such as `tcp` or `https`.
314    pub name: String,
315    /// Transport backing the service.
316    pub transport: OnionExitTransportInfo,
317}
318
319/// Policy advertised by an onion exit descriptor.
320#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
321pub struct OnionExitPolicyInfo {
322    /// Allowed target patterns for the exit.
323    pub allowed_targets: Vec<String>,
324    /// Denied target patterns for the exit.
325    pub denied_targets: Vec<String>,
326    /// Maximum concurrent circuits allowed by the exit.
327    pub max_circuits: u32,
328    /// Maximum concurrent streams allowed per circuit.
329    pub max_streams_per_circuit: u32,
330    /// Maximum bytes per minute allowed by the exit.
331    pub max_bytes_per_minute: u64,
332}
333
334/// Public descriptor for a node that can serve as an onion exit.
335#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
336pub struct OnionExitDescriptorInfo {
337    /// Decentralized identifier of the exit node.
338    pub did: String,
339    /// Verification public key encoded with the core serde shape.
340    pub public_key: Value,
341    /// Session encryption public key encoded with the core serde shape.
342    pub session_public_key: Value,
343    /// Runtime class of the exit node.
344    pub node_type: OnlineNodeTypeInfo,
345    /// Overlay network identifier the exit belongs to.
346    pub network_id: u32,
347    /// Services offered by the exit.
348    pub services: Vec<OnionExitServiceInfo>,
349    /// Target and resource policy enforced by the exit.
350    pub policy: OnionExitPolicyInfo,
351    /// Descriptor creation timestamp in Unix milliseconds.
352    pub started_at_ms: u64,
353    /// Last heartbeat timestamp in Unix milliseconds.
354    pub heartbeat_at_ms: u64,
355    /// Descriptor expiration timestamp in Unix milliseconds.
356    pub expires_at_ms: u64,
357    /// Rings node version that produced the descriptor.
358    pub version: String,
359    /// Descriptor signature encoded with the core serde shape.
360    pub signature: Value,
361}
362
363/// Request to lookup live or stored onion exit descriptors.
364#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
365pub struct LookupOnionExitsRequest {
366    /// Service name filter. Empty means all services.
367    #[serde(default)]
368    pub service: String,
369    /// Whether expired descriptors should be included in the response.
370    #[serde(default)]
371    pub include_expired: bool,
372}
373
374/// Response containing onion exit descriptors.
375#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
376pub struct LookupOnionExitsResponse {
377    /// Onion exit descriptors returned by the directory.
378    pub exits: Vec<OnionExitDescriptorInfo>,
379}
380
381/// Request to build an onion route for a service.
382#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
383pub struct BuildOnionRouteRequest {
384    /// Service name requested by the route.
385    pub service: String,
386    /// Desired hop count including the exit. `0` means node default.
387    #[serde(default)]
388    pub hop_count: u32,
389    /// Allow route selection to return fewer hops when too few relays are live.
390    #[serde(default)]
391    pub allow_short_paths: bool,
392}
393
394/// Response containing a selected onion route and exit.
395#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
396pub struct BuildOnionRouteResponse {
397    /// Ordered DID hops, ending with the selected exit.
398    pub hops: Vec<String>,
399    /// Service name satisfied by the selected route.
400    pub service: String,
401    /// Onion exit selected for the route.
402    pub exit: OnionExitDescriptorInfo,
403}
404
405/// Request to inspect the local node.
406#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
407pub struct NodeInfoRequest {}
408
409/// Inclusive key range covered by a DHT finger table entry.
410#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
411pub struct FingerTableRange {
412    /// DID owning the range, if a peer is known.
413    pub did: Option<String>,
414    /// Start of the key range.
415    pub start: u64,
416    /// End of the key range.
417    pub end: u64,
418}
419
420/// DHT inspection data for the local node.
421#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
422pub struct DhtInfo {
423    /// Decentralized identifier of the local node.
424    pub did: String,
425    /// Successor DIDs known by the local node.
426    pub successors: Vec<String>,
427    /// Predecessor DID known by the local node.
428    pub predecessor: Option<String>,
429    /// Finger table ranges observed by the local node.
430    pub finger_table_ranges: Vec<FingerTableRange>,
431}
432
433/// Stored value returned by node inspection.
434#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
435pub struct StorageValue {
436    /// DID associated with the stored value.
437    pub did: String,
438    /// Storage record kind.
439    pub kind: String,
440    /// Stored payload values encoded for the JSON-RPC boundary.
441    pub data: Vec<String>,
442}
443
444/// Storage item returned by node inspection.
445#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
446pub struct StorageItem {
447    /// Storage key.
448    pub key: String,
449    /// Stored value when the key is present.
450    pub value: Option<StorageValue>,
451}
452
453/// Storage inspection data for a node storage backend.
454#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
455pub struct StorageInfo {
456    /// Storage items observed in the backend.
457    pub items: Vec<StorageItem>,
458}
459
460/// Combined swarm, DHT, and storage inspection data.
461#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
462pub struct SwarmInfo {
463    /// Peer connection summaries.
464    pub peers: Vec<PeerInfo>,
465    /// DHT inspection data when the DHT is available.
466    pub dht: Option<DhtInfo>,
467    /// Persistent storage inspection data when available.
468    pub persistence_storage: Option<StorageInfo>,
469    /// Cache storage inspection data when available.
470    pub cache_storage: Option<StorageInfo>,
471}
472
473/// Response returned by node inspection.
474#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
475pub struct NodeInfoResponse {
476    /// Rings node version.
477    pub version: String,
478    /// Swarm inspection data when available.
479    pub swarm: Option<SwarmInfo>,
480}
481
482/// Request to fetch measurements for a single peer.
483#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
484pub struct PeerMeasurementRequest {
485    /// Decentralized identifier of the peer being measured.
486    pub did: String,
487}
488
489/// Request to list a bounded page of retained peer measurements.
490#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
491pub struct ListPeerMeasurementsRequest {
492    /// Maximum entries to return; omitted uses the server default.
493    pub limit: Option<u32>,
494    /// Exclusive DID cursor returned by the previous page.
495    pub cursor: Option<String>,
496}
497
498/// Counter set for peer transport measurements.
499#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
500pub struct PeerMeasurementCountersInfo {
501    /// Number of successful connection events.
502    pub connected: u64,
503    /// Number of disconnection events.
504    pub disconnected: u64,
505    /// Number of successful send events.
506    pub sent: u64,
507    /// Number of failed send events.
508    pub failed_to_send: u64,
509    /// Number of successful receive events.
510    pub received: u64,
511    /// Number of failed receive events.
512    pub failed_to_receive: u64,
513}
514
515/// Persistent local byte-credit values for one authenticated peer.
516#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
517pub struct PeerCreditInfo {
518    /// Useful payload bytes sent by the local node to the peer.
519    pub bytes_sent_to_peer: u64,
520    /// Useful payload bytes received and verified from the peer.
521    pub bytes_received_from_peer: u64,
522    /// Most recent authenticated local observation in Unix seconds.
523    pub last_seen_seconds: u64,
524    /// aMule-compatible local resource-priority multiplier in `[1, 10]`.
525    pub score: f64,
526}
527
528/// Advisory recent local reliability class.
529#[derive(Clone, Copy, PartialEq, Eq, Debug, Default, Serialize, Deserialize)]
530#[serde(rename_all = "snake_case")]
531pub enum PeerReliabilityInfo {
532    /// Enough positive recent evidence remains below failure limits.
533    Healthy,
534    /// The local node has insufficient recent evidence.
535    #[default]
536    Unknown,
537    /// Recent local evidence reached a configured failure limit.
538    Degraded,
539}
540
541/// Measurements collected for a single peer.
542#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
543pub struct PeerMeasurementInfo {
544    /// Decentralized identifier of the measured peer.
545    pub did: String,
546    /// Transport measurement counters for the peer.
547    pub counters: PeerMeasurementCountersInfo,
548    /// Persistent local byte credits, absent for counter-only custom implementations.
549    pub credit: Option<PeerCreditInfo>,
550    /// Advisory recent reliability class.
551    pub reliability: PeerReliabilityInfo,
552}
553
554/// Response containing one bounded page of measured peers.
555#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
556pub struct ListPeerMeasurementsResponse {
557    /// Per-peer measurement entries.
558    pub measurements: Vec<PeerMeasurementInfo>,
559    /// Exclusive cursor for the next page, absent at the end of the ledger.
560    pub next_cursor: Option<String>,
561}
562
563/// Response containing measurements for one peer.
564#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
565pub struct PeerMeasurementResponse {
566    /// Measurement entry for the requested peer, if present.
567    pub measurement: Option<PeerMeasurementInfo>,
568}
569
570/// Request to read the local node DID.
571#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
572pub struct NodeDidRequest {}
573
574/// Response containing the local node DID.
575#[derive(Clone, PartialEq, Debug, Default, Serialize, Deserialize)]
576pub struct NodeDidResponse {
577    /// Decentralized identifier of the local node.
578    pub did: String,
579}
rings_rpc/protos/rings_node.rs

rings_rpc/protos/
rings_node.rs
