use std::{
collections::{HashMap, HashSet},
marker::PhantomData,
sync::{
Arc,
atomic::{AtomicU64, Ordering},
},
time::Duration,
};
use reqwest::{
Client,
header::{AUTHORIZATION, HeaderMap, HeaderValue},
};
use serde::{
Deserialize, Serialize,
de::{DeserializeOwned, IgnoredAny},
};
use serde_json::Value;
use tokio_util::sync::CancellationToken;
use url::Url;
use crate::{
ErpcError, JsonRpcErrorObject, Result,
config::redaction_secrets_for_headers,
error::{invalid_response, rpc_error_with_secrets, timeout},
};
#[derive(Clone, Debug, Deserialize, Eq, Hash, PartialEq, Serialize)]
#[serde(untagged)]
pub enum JsonRpcId {
Number(u64),
String(String),
}
#[derive(Clone, Debug, Serialize)]
pub struct RpcBatchCall {
pub method: String,
#[serde(skip_serializing_if = "Option::is_none")]
pub params: Option<Value>,
}
impl RpcBatchCall {
pub fn new(method: impl Into<String>, params: impl Serialize) -> Result<Self> {
Ok(Self {
method: method.into(),
params: Some(serde_json::to_value(params).map_err(|_| {
ErpcError::Config("RPC parameters could not be serialized".to_owned())
})?),
})
}
#[must_use]
pub fn without_params(method: impl Into<String>) -> Self {
Self {
method: method.into(),
params: None,
}
}
}
#[derive(Clone, Debug, Default)]
pub struct RequestOptions {
pub cancellation: Option<CancellationToken>,
}
#[derive(Clone)]
pub struct HttpTransportConfig {
pub api_key: String,
pub endpoint: Url,
pub headers: HeaderMap,
pub max_batch_size: usize,
pub timeout: Duration,
pub client: Client,
}
pub struct HttpJsonRpcTransport {
api_key: Option<String>,
endpoint: Url,
headers: HeaderMap,
redaction_secrets: Vec<String>,
max_batch_size: usize,
timeout: Duration,
client: Client,
next_id: AtomicU64,
configured: bool,
namespace: String,
response_policy: ResponsePolicy,
api_key_query: bool,
}
#[derive(Clone, Copy)]
enum ResponsePolicy {
Strict,
Bitcoin,
}
impl HttpJsonRpcTransport {
#[must_use]
pub fn new(config: HttpTransportConfig) -> Self {
let mut endpoint = config.endpoint;
let api_key = (!config.api_key.is_empty()).then_some(config.api_key);
endpoint.set_query(None);
endpoint.set_fragment(None);
let mut redaction_secrets = Vec::new();
if let Some(api_key) = &api_key {
redaction_secrets.push(api_key.clone());
}
Self::from_parts(
api_key,
endpoint,
config.headers,
redaction_secrets,
config.max_batch_size,
config.timeout,
config.client,
"RPC",
true,
ResponsePolicy::Strict,
true,
)
}
pub(crate) fn new_direct(
endpoint: Url,
headers: HeaderMap,
redaction_secrets: Vec<String>,
max_batch_size: usize,
timeout: Duration,
client: Client,
namespace: impl Into<String>,
) -> Self {
let redaction_secrets = merge_secrets(redaction_secrets, &headers);
Self::from_parts(
None,
endpoint,
headers,
redaction_secrets,
max_batch_size,
timeout,
client,
namespace,
true,
ResponsePolicy::Strict,
false,
)
}
pub(crate) fn new_direct_bitcoin(
endpoint: Url,
headers: HeaderMap,
redaction_secrets: Vec<String>,
timeout: Duration,
client: Client,
namespace: impl Into<String>,
) -> Self {
let redaction_secrets = merge_secrets(redaction_secrets, &headers);
Self::from_parts(
None,
endpoint,
headers,
redaction_secrets,
100,
timeout,
client,
namespace,
true,
ResponsePolicy::Bitcoin,
false,
)
}
pub(crate) fn new_bitcoin(
api_key: String,
endpoint: Url,
mut headers: HeaderMap,
timeout: Duration,
client: Client,
) -> Result<Self> {
let bearer = format!("Bearer {api_key}");
let bearer = HeaderValue::from_str(&bearer)
.map_err(|_| ErpcError::Config("invalid Bitcoin authorization header".to_owned()))?;
headers.remove(AUTHORIZATION);
headers.insert(AUTHORIZATION, bearer);
let mut redaction_secrets = vec![api_key.clone()];
redaction_secrets = merge_secrets(redaction_secrets, &headers);
Ok(Self::from_parts(
Some(api_key),
endpoint,
headers,
redaction_secrets,
100,
timeout,
client,
"bitcoin.rpc",
true,
ResponsePolicy::Bitcoin,
false,
))
}
pub(crate) fn unavailable(
namespace: impl Into<String>,
timeout: Duration,
client: Client,
) -> Self {
let endpoint = Url::parse("http://127.0.0.1/").expect("static unavailable endpoint");
Self::from_parts(
None,
endpoint,
HeaderMap::new(),
Vec::new(),
256,
timeout,
client,
namespace,
false,
ResponsePolicy::Strict,
false,
)
}
#[allow(clippy::too_many_arguments)]
fn from_parts(
api_key: Option<String>,
endpoint: Url,
headers: HeaderMap,
redaction_secrets: Vec<String>,
max_batch_size: usize,
timeout: Duration,
client: Client,
namespace: impl Into<String>,
configured: bool,
response_policy: ResponsePolicy,
api_key_query: bool,
) -> Self {
Self {
api_key,
endpoint,
headers,
redaction_secrets,
max_batch_size,
timeout,
client,
next_id: AtomicU64::new(1),
configured,
namespace: namespace.into(),
response_policy,
api_key_query,
}
}
#[must_use]
pub fn endpoint(&self) -> String {
if self.configured {
let mut endpoint = self.endpoint.clone();
endpoint.set_query(None);
endpoint.set_fragment(None);
endpoint.to_string()
} else {
String::new()
}
}
#[must_use]
pub const fn max_batch_size(&self) -> usize {
self.max_batch_size
}
pub async fn request<T: DeserializeOwned>(
&self,
method: &str,
params: Option<Value>,
options: &RequestOptions,
) -> Result<T> {
self.ensure_configured()?;
let id = self.id();
let request = WireRequest {
jsonrpc: "2.0",
id: id.clone(),
method,
params,
};
let response = self.post(&request, options).await?;
self.unwrap(&response, &id)
}
pub async fn batch(
&self,
calls: &[RpcBatchCall],
options: &RequestOptions,
) -> Result<Vec<Value>> {
self.ensure_configured()?;
if calls.is_empty() {
return Ok(Vec::new());
}
if calls.len() > self.max_batch_size {
return Err(invalid_response(format!(
"A batch may contain at most {} calls",
self.max_batch_size
)));
}
let requests: Vec<_> = calls
.iter()
.map(|call| WireRequest {
jsonrpc: "2.0",
id: self.id(),
method: call.method.as_str(),
params: call.params.clone(),
})
.collect();
let response = self.post(&requests, options).await?;
let Value::Array(responses) = response else {
if let Ok(failure) = serde_json::from_value::<WireFailure>(response) {
return Err(rpc_error_with_secrets(
failure.error,
&self.redaction_secrets,
));
}
return Err(invalid_response("ERPC returned a non-array batch response"));
};
let mut by_id = HashMap::new();
for response in responses {
let id = response
.get("id")
.cloned()
.ok_or_else(|| invalid_response("ERPC returned an invalid batch item"))?;
let id = parse_json_rpc_id(&id)
.map_err(|_| invalid_response("ERPC returned an invalid batch id"))?;
if by_id.insert(id, response).is_some() {
return Err(invalid_response("ERPC returned a duplicate batch id"));
}
}
let results = requests
.iter()
.map(|request| {
let response = by_id.remove(&request.id).ok_or_else(|| {
invalid_response(format!("ERPC omitted batch response id {}", request.id))
})?;
self.unwrap(&response, &request.id)
})
.collect::<Result<Vec<_>>>()?;
if !by_id.is_empty() {
return Err(invalid_response(
"ERPC returned an unexpected batch response id",
));
}
Ok(results)
}
fn id(&self) -> JsonRpcId {
let id = self.next_id.fetch_add(1, Ordering::Relaxed);
if id == u64::MAX {
self.next_id.store(1, Ordering::Relaxed);
}
JsonRpcId::Number(id)
}
async fn post(&self, body: &impl Serialize, options: &RequestOptions) -> Result<Value> {
let mut url = self.endpoint.clone();
if self.api_key_query {
if let Some(api_key) = &self.api_key {
url.query_pairs_mut().append_pair("api-key", api_key);
}
}
let operation = async {
let response = self
.client
.post(url)
.headers(self.headers.clone())
.header(reqwest::header::ACCEPT, "application/json")
.header(reqwest::header::CONTENT_TYPE, "application/json")
.json(body)
.send()
.await
.map_err(|_| ErpcError::Transport("Unable to reach ERPC".to_owned()))?;
if !response.status().is_success() {
return Err(ErpcError::Http {
status: response.status().as_u16(),
});
}
let text = response
.text()
.await
.map_err(|_| ErpcError::Transport("Unable to read ERPC response".to_owned()))?;
decode_json(&text)
};
let timed = tokio::time::timeout(self.timeout, operation);
let result = if let Some(cancellation) = &options.cancellation {
tokio::select! {
biased;
() = cancellation.cancelled() => return Err(ErpcError::Aborted),
result = timed => result,
}
} else {
timed.await
};
result.map_err(|_| timeout(self.timeout))?
}
fn unwrap<T: DeserializeOwned>(&self, response: &Value, expected: &JsonRpcId) -> Result<T> {
let object = response
.as_object()
.ok_or_else(|| invalid_response("ERPC returned an invalid response"))?;
let id = parse_json_rpc_id(
object
.get("id")
.ok_or_else(|| invalid_response("ERPC returned an invalid response"))?,
)
.map_err(|_| invalid_response("ERPC returned an invalid response id"))?;
if &id != expected {
return Err(invalid_response("ERPC returned an unexpected response id"));
}
if let Some(error) = object.get("error") {
if !matches!(self.response_policy, ResponsePolicy::Bitcoin) || !error.is_null() {
let error: JsonRpcErrorObject = serde_json::from_value(error.clone())
.map_err(|_| invalid_response("ERPC returned an invalid RPC error"))?;
return Err(rpc_error_with_secrets(error, &self.redaction_secrets));
}
}
let result = object
.get("result")
.cloned()
.ok_or_else(|| invalid_response("ERPC returned an invalid response"))?;
serde_json::from_value(result)
.map_err(|_| invalid_response("ERPC returned an unexpected result shape"))
}
pub(crate) fn ensure_configured(&self) -> Result<()> {
if self.configured {
Ok(())
} else {
Err(ErpcError::NotConfigured(self.namespace.clone()))
}
}
}
fn merge_secrets(mut secrets: Vec<String>, headers: &HeaderMap) -> Vec<String> {
for secret in redaction_secrets_for_headers(headers) {
if !secrets.contains(&secret) {
secrets.push(secret);
}
}
secrets
}
const SERDE_PRIVATE_NUMBER_KEY: &str = "$serde_json::private::Number";
const SERDE_PRIVATE_RAW_VALUE_KEY: &str = "$serde_json::private::RawValue";
pub(crate) fn decode_json<T: DeserializeOwned>(text: &str) -> Result<T> {
serde_json::from_str::<IgnoredAny>(text)
.map_err(|_| invalid_response("ERPC returned malformed JSON"))?;
reject_serde_private_keys(text)?;
serde_json::from_str(text).map_err(|_| invalid_response("ERPC returned malformed JSON"))
}
pub(crate) fn parse_json_rpc_id(value: &Value) -> Result<JsonRpcId> {
match value {
Value::Number(number) => number
.as_u64()
.map(JsonRpcId::Number)
.ok_or_else(|| invalid_response("ERPC returned an invalid response id")),
Value::String(value) => Ok(JsonRpcId::String(value.clone())),
_ => Err(invalid_response("ERPC returned an invalid response id")),
}
}
fn reject_serde_private_keys(text: &str) -> Result<()> {
let bytes = text.as_bytes();
let mut index = 0;
while index < bytes.len() {
if bytes[index] != b'"' {
index += 1;
continue;
}
let start = index;
index += 1;
let mut escaped = false;
let mut closed = false;
while index < bytes.len() {
let byte = bytes[index];
index += 1;
if escaped {
escaped = false;
} else if byte == b'\\' {
escaped = true;
} else if byte == b'"' {
closed = true;
break;
}
}
if !closed {
return Err(invalid_response("ERPC returned malformed JSON"));
}
let mut next = index;
while next < bytes.len() && is_json_whitespace(bytes[next]) {
next += 1;
}
if next >= bytes.len() || bytes[next] != b':' {
continue;
}
let decoded: String = serde_json::from_str(&text[start..index])
.map_err(|_| invalid_response("ERPC returned malformed JSON"))?;
if matches!(
decoded.as_str(),
SERDE_PRIVATE_NUMBER_KEY | SERDE_PRIVATE_RAW_VALUE_KEY
) {
return Err(invalid_response(
"ERPC returned unsupported serializer-private object key",
));
}
}
Ok(())
}
const fn is_json_whitespace(byte: u8) -> bool {
matches!(byte, b' ' | b'\n' | b'\r' | b'\t')
}
impl std::fmt::Display for JsonRpcId {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::Number(id) => id.fmt(formatter),
Self::String(id) => id.fmt(formatter),
}
}
}
#[derive(Serialize)]
struct WireRequest<'a> {
jsonrpc: &'static str,
id: JsonRpcId,
method: &'a str,
#[serde(skip_serializing_if = "Option::is_none")]
params: Option<Value>,
}
#[derive(Deserialize)]
struct WireFailure {
error: JsonRpcErrorObject,
}
pub struct PendingRpcRequest<T> {
transport: Arc<HttpJsonRpcTransport>,
method: String,
params: Option<Value>,
marker: PhantomData<fn() -> T>,
}
impl<T: DeserializeOwned> PendingRpcRequest<T> {
pub async fn send(self) -> Result<T> {
self.send_with(RequestOptions::default()).await
}
pub async fn send_with(self, options: RequestOptions) -> Result<T> {
self.transport
.request(&self.method, self.params, &options)
.await
}
}
pub struct PendingRpcBatchRequest {
transport: Arc<HttpJsonRpcTransport>,
calls: Vec<RpcBatchCall>,
}
impl PendingRpcBatchRequest {
pub async fn send(self) -> Result<Vec<Value>> {
self.send_with(RequestOptions::default()).await
}
pub async fn send_with(self, options: RequestOptions) -> Result<Vec<Value>> {
self.transport.batch(&self.calls, &options).await
}
}
#[derive(Clone, Copy)]
pub(crate) enum BatchPolicy {
Any,
SolanaStandard,
Unsupported,
}
#[derive(Clone)]
pub struct RpcNamespace {
transport: Arc<HttpJsonRpcTransport>,
policy: BatchPolicy,
}
impl RpcNamespace {
pub(crate) const fn new(transport: Arc<HttpJsonRpcTransport>, policy: BatchPolicy) -> Self {
Self { transport, policy }
}
#[must_use]
pub fn endpoint(&self) -> String {
self.transport.endpoint()
}
pub fn request<T: DeserializeOwned>(
&self,
method: impl Into<String>,
params: impl Serialize,
) -> Result<PendingRpcRequest<T>> {
Ok(PendingRpcRequest {
transport: Arc::clone(&self.transport),
method: method.into(),
params: Some(serde_json::to_value(params).map_err(|_| {
ErpcError::Config("RPC parameters could not be serialized".to_owned())
})?),
marker: PhantomData,
})
}
#[must_use]
pub fn request_without_params<T: DeserializeOwned>(
&self,
method: impl Into<String>,
) -> PendingRpcRequest<T> {
PendingRpcRequest {
transport: Arc::clone(&self.transport),
method: method.into(),
params: None,
marker: PhantomData,
}
}
pub fn raw<T: DeserializeOwned>(
&self,
method: impl Into<String>,
params: Option<Value>,
) -> PendingRpcRequest<T> {
PendingRpcRequest {
transport: Arc::clone(&self.transport),
method: method.into(),
params,
marker: PhantomData,
}
}
pub fn batch(&self, calls: Vec<RpcBatchCall>) -> Result<PendingRpcBatchRequest> {
self.transport.ensure_configured()?;
if matches!(self.policy, BatchPolicy::Unsupported) {
if !calls.is_empty() {
return Err(ErpcError::BatchPolicy(
"This RPC namespace does not support batching".to_owned(),
));
}
} else if matches!(self.policy, BatchPolicy::SolanaStandard) {
validate_solana_standard_batch(&calls)?;
}
Ok(PendingRpcBatchRequest {
transport: Arc::clone(&self.transport),
calls,
})
}
}
fn validate_solana_standard_batch(calls: &[RpcBatchCall]) -> Result<()> {
let heavy: HashSet<&str> = [
"getPriorityFeeEstimate",
"getProgramAccounts",
"getProgramAccountsV2",
"getTokenLargestAccounts",
]
.into_iter()
.collect();
let contains_heavy = calls
.iter()
.any(|call| heavy.contains(call.method.as_str()));
let contains_standard = calls
.iter()
.any(|call| !heavy.contains(call.method.as_str()));
if contains_heavy && contains_standard {
return Err(ErpcError::BatchPolicy(
"Solana indexed and standard RPC methods cannot share a batch".to_owned(),
));
}
Ok(())
}