192 lines
8.6 KiB
Rust
192 lines
8.6 KiB
Rust
// file: crates/ksp-onchain-transport-lib/src/grpc_channel.rs
|
|
// version: 4
|
|
|
|
/// Prepared or connected Yellowstone gRPC channel owned by KSP Transport.
|
|
///
|
|
/// The underlying Tonic channel, endpoint URL and request metadata remain private. Callers use the KSP-owned typed Yellowstone surfaces layered on this
|
|
/// physical channel instead of receiving a raw Tonic escape hatch.
|
|
#[derive(Clone)]
|
|
pub struct YellowstoneGrpcChannel {
|
|
endpoint_name: std::string::String,
|
|
provider: crate::YellowstoneGrpcProviderName,
|
|
cluster: crate::YellowstoneGrpcClusterName,
|
|
channel: tonic::transport::Channel,
|
|
metadata: std::vec::Vec<crate::YellowstoneGrpcMetadataEntry>,
|
|
session: crate::YellowstoneGrpcSessionSettings,
|
|
}
|
|
|
|
impl YellowstoneGrpcChannel {
|
|
/// Prepares one lazy HTTP/2 channel without establishing a network connection.
|
|
///
|
|
/// HTTPS endpoints receive the KSP TLS configuration immediately, so invalid local TLS setup is rejected before a typed client is created. Tonic lazy
|
|
/// channels require an active Tokio runtime even though no socket is opened yet.
|
|
pub fn prepare(settings: &crate::YellowstoneGrpcEndpointSettings) -> ksp_core_lib::Result<Self> {
|
|
if let std::result::Result::Err(error) = settings.validate() {
|
|
return std::result::Result::Err(error);
|
|
}
|
|
if !settings.enabled() {
|
|
return std::result::Result::Err(
|
|
ksp_core_lib::Error::new(crate::ERROR_CODE_GRPC_CHANNEL_FAILED, "disabled Yellowstone gRPC endpoint cannot prepare a channel")
|
|
.with_context("endpoint_name", settings.name()),
|
|
);
|
|
}
|
|
if tokio::runtime::Handle::try_current().is_err() {
|
|
return std::result::Result::Err(grpc_channel_error(settings, "Yellowstone gRPC channel preparation requires an active Tokio runtime"));
|
|
}
|
|
let endpoint = match build_tonic_endpoint(settings) {
|
|
std::result::Result::Ok(value) => value,
|
|
std::result::Result::Err(error) => return std::result::Result::Err(error),
|
|
};
|
|
let channel = endpoint.connect_lazy();
|
|
ksp_logging_lib::debug!(
|
|
target: crate::TRACING_TARGET,
|
|
endpoint_name = settings.name(),
|
|
provider = settings.provider().as_str(),
|
|
cluster = settings.cluster().as_str(),
|
|
tls = settings.url().uses_tls(),
|
|
metadata_count = settings.metadata().len(),
|
|
"prepared lazy Yellowstone gRPC channel"
|
|
);
|
|
return std::result::Result::Ok(Self::from_parts(settings, channel));
|
|
}
|
|
|
|
/// Establishes one Yellowstone gRPC HTTP/2 channel with bounded connect timeout and configured TLS roots.
|
|
pub async fn connect(settings: &crate::YellowstoneGrpcEndpointSettings) -> ksp_core_lib::Result<Self> {
|
|
if let std::result::Result::Err(error) = settings.validate() {
|
|
return std::result::Result::Err(error);
|
|
}
|
|
if !settings.enabled() {
|
|
return std::result::Result::Err(
|
|
ksp_core_lib::Error::new(crate::ERROR_CODE_GRPC_CHANNEL_FAILED, "disabled Yellowstone gRPC endpoint cannot connect")
|
|
.with_context("endpoint_name", settings.name()),
|
|
);
|
|
}
|
|
if tokio::runtime::Handle::try_current().is_err() {
|
|
return std::result::Result::Err(grpc_channel_error(settings, "Yellowstone gRPC connection requires an active Tokio runtime"));
|
|
}
|
|
let endpoint = match build_tonic_endpoint(settings) {
|
|
std::result::Result::Ok(value) => value,
|
|
std::result::Result::Err(error) => return std::result::Result::Err(error),
|
|
};
|
|
let channel = match endpoint.connect().await {
|
|
std::result::Result::Ok(value) => value,
|
|
std::result::Result::Err(_) => {
|
|
ksp_logging_lib::warn!(
|
|
target: crate::TRACING_TARGET,
|
|
endpoint_name = settings.name(),
|
|
provider = settings.provider().as_str(),
|
|
cluster = settings.cluster().as_str(),
|
|
tls = settings.url().uses_tls(),
|
|
"Yellowstone gRPC channel connection failed"
|
|
);
|
|
return std::result::Result::Err(grpc_channel_error(settings, "Yellowstone gRPC channel connection failed"));
|
|
},
|
|
};
|
|
ksp_logging_lib::debug!(
|
|
target: crate::TRACING_TARGET,
|
|
endpoint_name = settings.name(),
|
|
provider = settings.provider().as_str(),
|
|
cluster = settings.cluster().as_str(),
|
|
tls = settings.url().uses_tls(),
|
|
"connected Yellowstone gRPC channel"
|
|
);
|
|
return std::result::Result::Ok(Self::from_parts(settings, channel));
|
|
}
|
|
|
|
/// Returns the safe logical endpoint name.
|
|
#[must_use]
|
|
pub fn endpoint_name(&self) -> &str {
|
|
return self.endpoint_name.as_str();
|
|
}
|
|
|
|
/// Returns the open provider descriptor.
|
|
#[must_use]
|
|
pub const fn provider(&self) -> &crate::YellowstoneGrpcProviderName {
|
|
return &self.provider;
|
|
}
|
|
|
|
/// Returns the open cluster descriptor.
|
|
#[must_use]
|
|
pub const fn cluster(&self) -> &crate::YellowstoneGrpcClusterName {
|
|
return &self.cluster;
|
|
}
|
|
|
|
/// Creates the standard Solana Yellowstone unary facade over this physical channel.
|
|
#[must_use]
|
|
pub fn standard_unary_client(&self) -> crate::SolanaYellowstoneGrpcUnaryClient {
|
|
return crate::SolanaYellowstoneGrpcUnaryClient::new(self.channel.clone(), self.metadata.clone(), self.session.clone());
|
|
}
|
|
|
|
/// Opens one standard Solana Yellowstone bidirectional `Subscribe` session over this physical channel.
|
|
pub async fn open_standard_subscribe(
|
|
&self,
|
|
initial_request: crate::YellowstoneSubscribeRequest,
|
|
) -> ksp_core_lib::Result<crate::SolanaYellowstoneGrpcSubscribeSession> {
|
|
return crate::open_yellowstone_subscribe_session(
|
|
self.channel.clone(),
|
|
self.metadata.clone(),
|
|
self.session.clone(),
|
|
self.endpoint_name.clone(),
|
|
self.provider.clone(),
|
|
self.cluster.clone(),
|
|
initial_request,
|
|
)
|
|
.await;
|
|
}
|
|
|
|
fn from_parts(settings: &crate::YellowstoneGrpcEndpointSettings, channel: tonic::transport::Channel) -> Self {
|
|
return Self {
|
|
endpoint_name: settings.name().to_owned(),
|
|
provider: settings.provider().clone(),
|
|
cluster: settings.cluster().clone(),
|
|
channel,
|
|
metadata: settings.metadata().to_vec(),
|
|
session: settings.session().clone(),
|
|
};
|
|
}
|
|
}
|
|
|
|
impl std::fmt::Debug for YellowstoneGrpcChannel {
|
|
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
|
|
return formatter
|
|
.debug_struct("YellowstoneGrpcChannel")
|
|
.field("endpoint_name", &self.endpoint_name)
|
|
.field("provider", &self.provider)
|
|
.field("cluster", &self.cluster)
|
|
.field("metadata_count", &self.metadata.len())
|
|
.field("channel", &"<private>")
|
|
.finish();
|
|
}
|
|
}
|
|
|
|
fn build_tonic_endpoint(settings: &crate::YellowstoneGrpcEndpointSettings) -> ksp_core_lib::Result<tonic::transport::Endpoint> {
|
|
let endpoint = match tonic::transport::Endpoint::from_shared(settings.url().as_str().to_owned()) {
|
|
std::result::Result::Ok(value) => value,
|
|
std::result::Result::Err(_) => {
|
|
return std::result::Result::Err(grpc_channel_error(settings, "Yellowstone gRPC endpoint URI cannot be prepared by the HTTP/2 transport"));
|
|
},
|
|
};
|
|
let endpoint = endpoint.connect_timeout(settings.session().connect_timeout()).buffer_size(settings.session().request_channel_capacity());
|
|
if settings.url().uses_tls() {
|
|
let tls = tonic::transport::ClientTlsConfig::new().with_webpki_roots().timeout(settings.session().connect_timeout());
|
|
return match endpoint.tls_config(tls) {
|
|
std::result::Result::Ok(value) => std::result::Result::Ok(value),
|
|
std::result::Result::Err(_) => {
|
|
std::result::Result::Err(grpc_channel_error(settings, "Yellowstone gRPC TLS configuration failed before connection"))
|
|
},
|
|
};
|
|
}
|
|
return std::result::Result::Ok(endpoint);
|
|
}
|
|
|
|
fn grpc_channel_error(settings: &crate::YellowstoneGrpcEndpointSettings, message: &str) -> ksp_core_lib::Error {
|
|
return ksp_core_lib::Error::new(crate::ERROR_CODE_GRPC_CHANNEL_FAILED, message)
|
|
.with_context("endpoint_name", settings.name())
|
|
.with_context("provider", settings.provider().as_str())
|
|
.with_context("cluster", settings.cluster().as_str());
|
|
}
|
|
|
|
#[cfg(test)]
|
|
#[path = "../unit_tests/grpc_channel.rs"]
|
|
mod tests;
|