Skip to main content

sui_rpc_api/
lib.rs

1// Copyright (c) Mysten Labs, Inc.
2// SPDX-License-Identifier: Apache-2.0
3
4use 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    /// Set by [`RpcService::with_validator_role`].
89    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    /// Serves from a validator. Its live state includes checkpoints whose
137    /// transactions are still executing, and it keeps no rpc indexes and no
138    /// replaced object versions, so each request is served only at the
139    /// finality levels and for the methods the `finality` module describes.
140    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        // Single source of truth for every encoded FileDescriptorSet that
186        // backs a gRPC service mounted below. Consumed by the reflection
187        // services, the metrics allowlist, and the request-log layer so they
188        // cannot drift out of sync.
189        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        // Allowlist of `/Service/Method` paths used by the metrics middleware
202        // to bound prometheus label cardinality.
203        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                // Extra sets registered by embedders may not merge cleanly (e.g. missing
214                // imports). Reflection and metrics tolerate that, so don't fail startup —
215                // capture just won't decode those extra services.
216                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            // Validators execute no client transactions, so they do not mount
285            // `TransactionExecutionService`.
286            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            // Services a node never serves refuse every call with `NOT_SERVED_HERE`:
295            // `StateService` and `ProofService` without rpc indexes. They stay mounted so that
296            // calls get that refusal, and report `NotServing` so that per-service health checks
297            // route them to other nodes.
298            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                // V2
315                .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                // V2alpha
321                .add_service(proof_service_v2alpha)
322                // Reflection
323                .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                // Outside `append_info_headers`, so it can drop the checkpoint
370                // height that layer adds.
371                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    /// The request-log layer's descriptor pool is built from these sets at server startup with an
415    /// `expect`, so they must always merge into one valid pool.
416    #[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    /// `grpc.health.v1` status of `service` on `router`.
429    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        // One length-prefixed message: a compression flag byte, then a 4-byte length.
456        let response = tonic_health::pb::HealthCheckResponse::decode(&body[5..]).unwrap();
457        response.status()
458    }
459
460    /// Without rpc indexes, the services that need them report `NOT_SERVING` while the rest of the
461    /// server reports `SERVING`.
462    #[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}