1use std::convert::Infallible;
5use std::sync::Arc;
6
7use reader::StateReader;
8use subscription::SubscriptionServiceHandle;
9use sui_http::middleware::callback::CallbackLayer;
10use sui_types::storage::RpcStateReader;
11use sui_types::transaction_executor::ProposerSelector;
12use sui_types::transaction_executor::TransactionExecutor;
13use tap::Pipe;
14use tonic::server::NamedService;
15use tower::Service;
16
17pub mod client;
18mod client_protocol_version;
19mod config;
20mod error;
21mod finality;
22pub mod grpc;
23pub mod ledger_history;
24mod metrics;
25pub mod read_mask_defaults;
26mod reader;
27mod response;
28mod service;
29#[cfg(test)]
30mod stub_store;
31pub mod subscription;
32
33pub use client::Client;
34pub use client_protocol_version::{X_SUI_CLIENT_PROTOCOL_VERSION, client_protocol_version};
35pub use config::Config;
36pub use error::{
37 CheckpointNotFoundError, EpochNotFoundError, ErrorDetails, ErrorReason, ObjectNotFoundError,
38 ObjectRemoval, Result, RpcError,
39};
40pub use finality::X_SUI_FINALITY_LEVEL;
41pub use metrics::{
42 GrpcMethodAllowlist, RpcMetrics, RpcMetricsMakeCallbackHandler,
43 grpc_method_paths_from_file_descriptor_sets,
44};
45pub use reader::AtCheckpointLowerBound;
46pub use reader::AtCheckpointUpperBound;
47pub use reader::NotReadyCause;
48pub use reader::NotServedHereCause;
49pub use reader::TransactionNotFoundError;
50pub use reader::not_ready;
51pub use reader::not_served_here;
52pub use sui_rpc::proto;
53
54#[derive(Clone)]
55pub struct ServerVersion {
56 pub bin: &'static str,
57 pub version: &'static str,
58}
59
60impl ServerVersion {
61 pub fn new(bin: &'static str, version: &'static str) -> Self {
62 Self { bin, version }
63 }
64}
65
66impl std::fmt::Display for ServerVersion {
67 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
68 f.write_str(self.bin)?;
69 f.write_str("/")?;
70 f.write_str(self.version)
71 }
72}
73
74#[derive(Clone)]
75pub struct RpcService {
76 reader: StateReader,
77 executor: Option<Arc<dyn TransactionExecutor>>,
78 proposer_selector: Option<Arc<dyn ProposerSelector>>,
79 subscription_service_handle: Option<SubscriptionServiceHandle>,
80 chain_id: sui_types::digests::ChainIdentifier,
81 server_version: Option<ServerVersion>,
82 metrics: Option<Arc<RpcMetrics>>,
83 pub(crate) list_metrics: Option<Arc<metrics::ListApiMetrics>>,
84 config: Config,
85 extra_routes: axum::Router,
86 extra_service_names: Vec<&'static str>,
87 extra_file_descriptor_sets: Vec<&'static [u8]>,
88 validator_role: bool,
90}
91
92impl RpcService {
93 pub fn new(reader: Arc<dyn RpcStateReader>) -> Self {
94 let chain_id = reader.get_chain_identifier().unwrap();
95 Self {
96 reader: StateReader::new(reader),
97 executor: None,
98 proposer_selector: None,
99 subscription_service_handle: None,
100 chain_id,
101 server_version: None,
102 metrics: None,
103 list_metrics: None,
104 config: Config::default(),
105 extra_routes: axum::Router::new(),
106 extra_service_names: Vec::new(),
107 extra_file_descriptor_sets: Vec::new(),
108 validator_role: false,
109 }
110 }
111
112 pub fn with_server_version(&mut self, server_version: ServerVersion) -> &mut Self {
113 self.server_version = Some(server_version);
114 self
115 }
116
117 pub fn with_config(&mut self, config: Config) {
118 self.config = config;
119 }
120
121 pub fn with_executor(&mut self, executor: Arc<dyn TransactionExecutor + Send + Sync>) {
122 self.executor = Some(executor);
123 }
124
125 pub fn with_proposer_selector(&mut self, proposer_selector: Arc<dyn ProposerSelector>) {
126 self.proposer_selector = Some(proposer_selector);
127 }
128
129 pub fn with_subscription_service(
130 &mut self,
131 subscription_service_handle: SubscriptionServiceHandle,
132 ) {
133 self.subscription_service_handle = Some(subscription_service_handle);
134 }
135
136 pub fn with_validator_role(&mut self) {
141 self.validator_role = true;
142 }
143
144 pub fn with_metrics(&mut self, registry: &prometheus::Registry) {
145 self.metrics = Some(Arc::new(RpcMetrics::new(registry)));
146 self.list_metrics = Some(Arc::new(metrics::ListApiMetrics::new(registry)));
147 }
148
149 pub fn with_custom_service<S>(&mut self, svc: S)
150 where
151 S: Service<
152 axum::extract::Request,
153 Response: axum::response::IntoResponse,
154 Error = Infallible,
155 > + NamedService
156 + Clone
157 + Send
158 + Sync
159 + 'static,
160 S::Future: Send + 'static,
161 S::Error: Into<grpc::BoxError> + Send,
162 {
163 self.extra_service_names.push(S::NAME);
164 self.extra_routes = std::mem::take(&mut self.extra_routes)
165 .route_service(&format!("/{}/{{*rest}}", S::NAME), svc);
166 }
167
168 pub fn with_file_descriptor_set(&mut self, encoded_fds: &'static [u8]) {
169 self.extra_file_descriptor_sets.push(encoded_fds);
170 }
171
172 pub fn chain_id(&self) -> sui_types::digests::ChainIdentifier {
173 self.chain_id
174 }
175
176 pub fn server_version(&self) -> Option<&ServerVersion> {
177 self.server_version.as_ref()
178 }
179
180 pub async fn into_router(mut self) -> axum::Router {
181 let metrics = self.metrics.clone();
182 let extra_routes = std::mem::take(&mut self.extra_routes);
183 let extra_service_names = std::mem::take(&mut self.extra_service_names);
184
185 let built_in_file_descriptor_sets: [&[u8]; 5] = [
190 sui_rpc::proto::google::protobuf::FILE_DESCRIPTOR_SET,
191 sui_rpc::proto::google::rpc::FILE_DESCRIPTOR_SET,
192 sui_rpc::proto::sui::rpc::v2::FILE_DESCRIPTOR_SET,
193 sui_rpc::proto::sui::rpc::v2alpha::FILE_DESCRIPTOR_SET,
194 tonic_health::pb::FILE_DESCRIPTOR_SET,
195 ];
196 let file_descriptor_sets: Vec<&[u8]> = built_in_file_descriptor_sets
197 .into_iter()
198 .chain(std::mem::take(&mut self.extra_file_descriptor_sets))
199 .collect();
200
201 let grpc_method_allowlist = Arc::new(
204 metrics::grpc_method_paths_from_file_descriptor_sets(&file_descriptor_sets)
205 .expect("registered FileDescriptorSet bytes must be valid protobuf"),
206 );
207
208 let request_log =
209 mysten_network::request_log::GrpcRequestLogLayer::from_encoded_file_descriptor_sets(
210 file_descriptor_sets.iter().copied(),
211 )
212 .unwrap_or_else(|e| {
213 tracing::warn!(
217 "request-log descriptor pool falling back to built-in file descriptor sets: {e}"
218 );
219 mysten_network::request_log::GrpcRequestLogLayer::from_encoded_file_descriptor_sets(
220 built_in_file_descriptor_sets,
221 )
222 .expect("built-in FileDescriptorSet bytes must be valid protobuf")
223 });
224
225 let router = {
226 let ledger_service =
227 sui_rpc::proto::sui::rpc::v2::ledger_service_server::LedgerServiceServer::new(
228 self.clone(),
229 )
230 .send_compressed(tonic::codec::CompressionEncoding::Zstd);
231 let proof_service_v2alpha =
232 sui_rpc::proto::sui::rpc::v2alpha::proof_service_server::ProofServiceServer::new(
233 self.clone(),
234 )
235 .send_compressed(tonic::codec::CompressionEncoding::Zstd);
236 let transaction_execution_service = sui_rpc::proto::sui::rpc::v2::transaction_execution_service_server::TransactionExecutionServiceServer::new(self.clone())
237 .send_compressed(tonic::codec::CompressionEncoding::Zstd);
238 let state_service =
239 sui_rpc::proto::sui::rpc::v2::state_service_server::StateServiceServer::new(
240 self.clone(),
241 )
242 .send_compressed(tonic::codec::CompressionEncoding::Zstd);
243 let signature_verification_service = sui_rpc::proto::sui::rpc::v2::signature_verification_service_server::SignatureVerificationServiceServer::new(self.clone())
244 .send_compressed(tonic::codec::CompressionEncoding::Zstd);
245 let move_package_service = sui_rpc::proto::sui::rpc::v2::move_package_service_server::MovePackageServiceServer::new(self.clone())
246 .send_compressed(tonic::codec::CompressionEncoding::Zstd);
247 let name_service =
248 sui_rpc::proto::sui::rpc::v2::name_service_server::NameServiceServer::new(
249 self.clone(),
250 )
251 .send_compressed(tonic::codec::CompressionEncoding::Zstd);
252
253 let (health_reporter, health_service) = tonic_health::server::health_reporter();
254
255 let mut reflection_v1_builder = tonic_reflection::server::Builder::configure();
256 let mut reflection_v1alpha_builder = tonic_reflection::server::Builder::configure();
257 for fds in &file_descriptor_sets {
258 reflection_v1_builder =
259 reflection_v1_builder.register_encoded_file_descriptor_set(fds);
260 reflection_v1alpha_builder =
261 reflection_v1alpha_builder.register_encoded_file_descriptor_set(fds);
262 }
263
264 let reflection_v1 = reflection_v1_builder.build_v1().unwrap();
265 let reflection_v1alpha = reflection_v1alpha_builder.build_v1alpha().unwrap();
266
267 fn service_name<S: tonic::server::NamedService>(_service: &S) -> &'static str {
268 S::NAME
269 }
270
271 for service_name in [
272 service_name(&ledger_service),
273 service_name(&signature_verification_service),
274 service_name(&move_package_service),
275 service_name(&name_service),
276 service_name(&reflection_v1),
277 service_name(&reflection_v1alpha),
278 ] {
279 health_reporter
280 .set_service_status(service_name, tonic_health::ServingStatus::Serving)
281 .await;
282 }
283
284 let transaction_execution_service =
287 (!self.validator_role).then_some(transaction_execution_service);
288 if let Some(service) = &transaction_execution_service {
289 health_reporter
290 .set_service_status(service_name(service), tonic_health::ServingStatus::Serving)
291 .await;
292 }
293
294 let status = if self.reader.inner().indexes().is_some() {
299 tonic_health::ServingStatus::Serving
300 } else {
301 tonic_health::ServingStatus::NotServing
302 };
303 for service_name in [
304 service_name(&state_service),
305 service_name(&proof_service_v2alpha),
306 ] {
307 health_reporter
308 .set_service_status(service_name, status)
309 .await;
310 }
311
312 let mut services = grpc::Services::new()
313 .timeout(self.config.grpc_timeout())
314 .add_service(ledger_service)
316 .add_service(state_service)
317 .add_service(signature_verification_service)
318 .add_service(move_package_service)
319 .add_service(name_service)
320 .add_service(proof_service_v2alpha)
322 .add_service(reflection_v1)
324 .add_service(reflection_v1alpha);
325
326 if let Some(service) = transaction_execution_service {
327 services = services.add_service(service);
328 }
329
330 if self.subscription_service_handle.is_some() {
331 let subscription_service =
332sui_rpc::proto::sui::rpc::v2::subscription_service_server::SubscriptionServiceServer::new(self.clone());
333 health_reporter
334 .set_service_status(
335 service_name(&subscription_service),
336 tonic_health::ServingStatus::Serving,
337 )
338 .await;
339
340 services = services.add_service(subscription_service);
341 }
342
343 for name in &extra_service_names {
344 health_reporter
345 .set_service_status(*name, tonic_health::ServingStatus::Serving)
346 .await;
347 }
348
349 services
350 .merge_router(extra_routes)
351 .add_service(health_service)
352 .into_router(request_log)
353 };
354
355 let health_endpoint = axum::Router::new()
356 .route("/health", axum::routing::get(service::health::health))
357 .with_state(self.clone());
358
359 let validator_requests = self
360 .validator_role
361 .then(|| finality::ValidatorRequestLayer::new(grpc_method_allowlist.clone()));
362 router
363 .merge(health_endpoint)
364 .layer(axum::middleware::map_response_with_state(
365 self,
366 response::append_info_headers,
367 ))
368 .pipe(|router| {
369 if let Some(layer) = validator_requests {
372 router.layer(layer)
373 } else {
374 router
375 }
376 })
377 .pipe(|router| {
378 if let Some(metrics) = metrics {
379 router.layer(CallbackLayer::new(
380 metrics::RpcMetricsMakeCallbackHandler::with_grpc_method_allowlist(
381 metrics,
382 grpc_method_allowlist,
383 ),
384 ))
385 } else {
386 router
387 }
388 })
389 }
390
391 pub async fn start_service(self, socket_address: std::net::SocketAddr) {
392 let listener = tokio::net::TcpListener::bind(socket_address).await.unwrap();
393 axum::serve(listener, self.into_router().await)
394 .await
395 .unwrap();
396 }
397}
398
399#[derive(Debug, Copy, Clone, serde::Serialize, serde::Deserialize)]
400#[serde(rename_all = "lowercase")]
401pub enum Direction {
402 Ascending,
403 Descending,
404}
405
406impl Direction {
407 pub fn is_descending(self) -> bool {
408 matches!(self, Self::Descending)
409 }
410}
411
412#[cfg(test)]
413mod tests {
414 #[test]
417 fn request_log_pool_builds_from_registered_file_descriptor_sets() {
418 mysten_network::request_log::GrpcRequestLogLayer::from_encoded_file_descriptor_sets([
419 sui_rpc::proto::google::protobuf::FILE_DESCRIPTOR_SET,
420 sui_rpc::proto::google::rpc::FILE_DESCRIPTOR_SET,
421 sui_rpc::proto::sui::rpc::v2::FILE_DESCRIPTOR_SET,
422 sui_rpc::proto::sui::rpc::v2alpha::FILE_DESCRIPTOR_SET,
423 tonic_health::pb::FILE_DESCRIPTOR_SET,
424 ])
425 .unwrap();
426 }
427
428 async fn health_status(
430 router: &axum::Router,
431 service: &str,
432 ) -> tonic_health::pb::health_check_response::ServingStatus {
433 use prost::Message;
434 use tower::ServiceExt;
435
436 let message = tonic_health::pb::HealthCheckRequest {
437 service: service.to_owned(),
438 }
439 .encode_to_vec();
440 let mut body = vec![0u8];
441 body.extend_from_slice(&(message.len() as u32).to_be_bytes());
442 body.extend_from_slice(&message);
443 let request = http::Request::builder()
444 .method(http::Method::POST)
445 .uri("/grpc.health.v1.Health/Check")
446 .version(http::Version::HTTP_2)
447 .header(http::header::CONTENT_TYPE, "application/grpc")
448 .body(axum::body::Body::from(body))
449 .unwrap();
450
451 let response = router.clone().oneshot(request).await.unwrap();
452 let body = axum::body::to_bytes(response.into_body(), usize::MAX)
453 .await
454 .unwrap();
455 let response = tonic_health::pb::HealthCheckResponse::decode(&body[5..]).unwrap();
457 response.status()
458 }
459
460 #[tokio::test]
463 async fn services_that_need_indexes_report_not_serving_without_them() {
464 use tonic_health::pb::health_check_response::ServingStatus;
465
466 let router = crate::stub_store::StubStore::new()
467 .into_service()
468 .into_router()
469 .await;
470
471 assert_eq!(
472 health_status(&router, "sui.rpc.v2.StateService").await,
473 ServingStatus::NotServing
474 );
475 assert_eq!(
476 health_status(&router, "sui.rpc.v2alpha.ProofService").await,
477 ServingStatus::NotServing
478 );
479 assert_eq!(
480 health_status(&router, "sui.rpc.v2.LedgerService").await,
481 ServingStatus::Serving
482 );
483 }
484}