server_rpc/
lib.rs

1//!
2//!
3//! # Note on protocol version
4//!
5//! Whenever anything changes related to the interactions between client and
6//! server, including protocol encoding versions, gRPC data fields, expected
7//! behavior etc, that is not automatically backwards compatible, the protocol
8//! version is bumped.
9//!
10//! Both the server and the client can be implemented so as to support multiple
11//! different protocol versions. This gives maximum flexibility to implement
12//! compatibility for both sides.
13//!
14//! The server advertises the protocol versions it supports and the client picks
15//! one and sets it in the header of each subsequent request.
16//!
17//! However, the server will only check the protocol version in cases where
18//! behavior can be different for different versions. This gives outdated or
19//! exotic clients an extra level of flexibility, as calls that have not
20//! changed since the latest supported protocol version might still work.
21//!
22//! This makes the server maximally flexible and puts all the responsibility
23//! on the client. Our own client implementation bails out if it cannot speak
24//! any of the supported protocol versions the server supports.
25//!
26//! ## Protocol version changelog
27//!
28//! * `1`: initial version
29
30pub extern crate tonic;
31
32// Generated gRPC method lookup from proto files (server-only)
33#[cfg(feature = "server")]
34include!(concat!(env!("OUT_DIR"), "/grpc_methods.rs"));
35
36mod convert;
37use std::borrow::BorrowMut;
38
39pub use convert::{ConvertError, TryFromBytes};
40
41pub mod client;
42pub mod protos {
43	pub mod core {
44		tonic::include_proto!("core");
45	}
46	pub use core::*;
47	pub mod bark_server {
48		tonic::include_proto!("bark_server");
49	}
50	pub use bark_server::*;
51	pub mod intman {
52		tonic::include_proto!("intman");
53	}
54	pub mod mailbox_server {
55		tonic::include_proto!("mailbox_server");
56	}
57}
58
59pub use client::ServerConnection;
60pub use crate::protos::bark_server::ark_service_client::ArkServiceClient;
61
62pub mod admin {
63	pub use crate::protos::bark_server::wallet_admin_service_client::WalletAdminServiceClient;
64	pub use crate::protos::bark_server::round_admin_service_client::RoundAdminServiceClient;
65	pub use crate::protos::bark_server::lightning_admin_service_client::LightningAdminServiceClient;
66	pub use crate::protos::bark_server::sweep_admin_service_client::SweepAdminServiceClient;
67	pub use crate::protos::bark_server::ban_admin_service_client::BanAdminServiceClient;
68}
69
70#[cfg(feature = "intman")]
71pub mod intman {
72	pub use crate::protos::intman::integration_service_client::IntegrationServiceClient;
73}
74
75#[cfg(feature = "server")]
76pub mod server {
77	pub use crate::protos::bark_server::ark_service_server::{ArkService, ArkServiceServer};
78	pub use crate::protos::bark_server::wallet_admin_service_server::{WalletAdminService, WalletAdminServiceServer};
79	pub use crate::protos::bark_server::round_admin_service_server::{RoundAdminService, RoundAdminServiceServer};
80	pub use crate::protos::bark_server::lightning_admin_service_server::{LightningAdminService, LightningAdminServiceServer};
81	pub use crate::protos::bark_server::sweep_admin_service_server::{SweepAdminService, SweepAdminServiceServer};
82	pub use crate::protos::bark_server::ban_admin_service_server::{BanAdminService, BanAdminServiceServer};
83	pub use crate::protos::intman::integration_service_server::{IntegrationService, IntegrationServiceServer};
84	pub use crate::protos::mailbox_server::mailbox_service_server::{MailboxService, MailboxServiceServer};
85}
86
87pub mod mailbox {
88	pub use crate::protos::mailbox_server::mailbox_service_client::MailboxServiceClient;
89}
90
91
92use std::str::FromStr;
93
94use bitcoin::{Address, Amount, OutPoint};
95use bitcoin::address::NetworkUnchecked;
96
97/// The string used in the gRPC HTTP header for the protocol version.
98pub const PROTOCOL_VERSION_HEADER: &str = "pver";
99
100#[derive(Debug, Clone)]
101pub struct WalletStatus {
102	pub address: Address<NetworkUnchecked>,
103	pub total_balance: Amount,
104	pub trusted_balance: Amount,
105	pub untrusted_balance: Amount,
106	pub confirmed_utxos: Vec<OutPoint>,
107	pub unconfirmed_utxos: Vec<OutPoint>,
108}
109
110/// Extension trait on [tonic::Request].
111pub trait RequestExt<T>: BorrowMut<tonic::Request<T>> {
112	/// Check for the protocol version header.
113	///
114	/// Returns None in case of missing header.
115	fn try_pver(&self) -> Result<Option<u64>, tonic::Status> {
116		self.borrow().metadata().get(PROTOCOL_VERSION_HEADER).map(|v| {
117			v.to_str().ok().and_then(|s| u64::from_str(s).ok())
118				.ok_or_else(|| tonic::Status::invalid_argument("invalid protocol version header"))
119		}).transpose()
120	}
121
122	/// Check for the protocol version header.
123	///
124	/// Returns error in case of missing header.
125	fn pver(&self) -> Result<u64, tonic::Status> {
126		self.try_pver()?.ok_or_else(|| tonic::Status::invalid_argument("missing pver header"))
127	}
128
129	/// Set the protocol version header.
130	fn set_pver(&mut self, pver: u64) {
131		self.borrow_mut().metadata_mut().insert(PROTOCOL_VERSION_HEADER, pver.into());
132	}
133}
134impl<T> RequestExt<T> for tonic::Request<T> {}
server_rpc/lib.rs

server_rpc/
lib.rs
