1use std::collections::HashSet;
30use std::pin::Pin;
31use std::sync::Arc;
32use std::task::Context;
33use std::task::Poll;
34
35use http::HeaderMap;
36use sui_rpc::headers::X_SUI_CHECKPOINT_HEIGHT;
37use sui_rpc::proto::sui::rpc::v2::transaction_execution_service_server::SERVICE_NAME as TRANSACTION_EXECUTION_SERVICE;
38use tonic::Code;
39use tower::Layer;
40use tower::Service;
41
42use crate::RpcError;
43use crate::reader::NotServedHereCause;
44use crate::reader::not_served_here;
45
46pub const X_SUI_FINALITY_LEVEL: &str = "x-sui-finality-level";
49
50#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)]
53enum FinalityLevel {
54 Executed,
58 Certified,
60}
61
62impl FinalityLevel {
63 fn header_value(self) -> &'static str {
64 match self {
65 Self::Executed => "executed",
66 Self::Certified => "certified",
67 }
68 }
69
70 fn from_headers(headers: &HeaderMap) -> Result<Self, RpcError> {
72 let Some(value) = headers.get(X_SUI_FINALITY_LEVEL) else {
73 return Ok(Self::Certified);
74 };
75 [Self::Executed, Self::Certified]
76 .into_iter()
77 .find(|level| value.as_bytes() == level.header_value().as_bytes())
78 .ok_or_else(|| {
79 RpcError::new(
80 Code::InvalidArgument,
81 format!(
82 "{X_SUI_FINALITY_LEVEL}: unknown level {value:?}; expected executed or \
83 certified"
84 ),
85 )
86 })
87 }
88}
89
90const VALIDATOR_METHODS: &[(&str, FinalityLevel)] = &[
93 (
94 "/sui.rpc.v2.LedgerService/GetServiceInfo",
95 FinalityLevel::Certified,
96 ),
97 (
98 "/sui.rpc.v2.LedgerService/GetCheckpoint",
99 FinalityLevel::Certified,
100 ),
101 (
102 "/sui.rpc.v2.SignatureVerificationService/VerifySignature",
103 FinalityLevel::Executed,
104 ),
105 (
106 "/sui.rpc.v2.SubscriptionService/SubscribeCheckpoints",
107 FinalityLevel::Executed,
108 ),
109 (
110 "/sui.rpc.v2.SubscriptionService/SubscribeTransactions",
111 FinalityLevel::Executed,
112 ),
113 (
114 "/sui.rpc.v2.SubscriptionService/SubscribeEvents",
115 FinalityLevel::Executed,
116 ),
117 (
118 "/sui.rpc.v2.LedgerService/GetObject",
119 FinalityLevel::Executed,
120 ),
121 (
122 "/sui.rpc.v2.LedgerService/BatchGetObjects",
123 FinalityLevel::Executed,
124 ),
125 (
126 "/sui.rpc.v2.LedgerService/GetEpoch",
127 FinalityLevel::Executed,
128 ),
129 (
130 "/sui.rpc.v2.LedgerService/GetProtocolConfig",
131 FinalityLevel::Executed,
132 ),
133 (
134 "/sui.rpc.v2.MovePackageService/GetPackage",
135 FinalityLevel::Executed,
136 ),
137 (
138 "/sui.rpc.v2.MovePackageService/GetDatatype",
139 FinalityLevel::Executed,
140 ),
141 (
142 "/sui.rpc.v2.MovePackageService/GetFunction",
143 FinalityLevel::Executed,
144 ),
145 (
146 "/sui.rpc.v2.NameService/LookupName",
147 FinalityLevel::Executed,
148 ),
149 (
150 "/sui.rpc.v2.NameService/ReverseLookupName",
151 FinalityLevel::Executed,
152 ),
153];
154
155fn is_method_of(path: &str, service: &str) -> bool {
157 path.strip_prefix('/')
158 .and_then(|path| path.strip_prefix(service))
159 .is_some_and(|method| method.starts_with('/'))
160}
161
162fn admit_on_validator(
168 path: &str,
169 headers: &HeaderMap,
170 known_methods: &HashSet<String>,
171) -> Result<Option<FinalityLevel>, RpcError> {
172 if !path.starts_with("/sui.rpc.") {
173 return Ok(None);
174 }
175 let requested = FinalityLevel::from_headers(headers)?;
176 let Some(&(_, most_settled)) = VALIDATOR_METHODS.iter().find(|(method, _)| *method == path)
177 else {
178 if !known_methods.contains(path) || is_method_of(path, TRANSACTION_EXECUTION_SERVICE) {
179 return Ok(None);
180 }
181 return Err(not_served_here(
182 NotServedHereCause::NoRpcIndexes,
183 format!("validators do not keep the rpc indexes {path} needs"),
184 ));
185 };
186 if requested > most_settled {
187 return Err(not_served_here(
188 NotServedHereCause::UncertifiedLiveState,
189 format!(
190 "validators serve {path} at finality level {served}, not {requested}: their live \
191 state includes data the network has not certified yet; send \
192 `{X_SUI_FINALITY_LEVEL}: {served}`",
193 served = most_settled.header_value(),
194 requested = requested.header_value(),
195 ),
196 ));
197 }
198 Ok(Some(most_settled))
199}
200
201#[derive(Clone)]
203pub(crate) struct ValidatorRequestLayer {
204 known_methods: Arc<HashSet<String>>,
206}
207
208impl ValidatorRequestLayer {
209 pub(crate) fn new(known_methods: Arc<HashSet<String>>) -> Self {
210 Self { known_methods }
211 }
212}
213
214impl<S> Layer<S> for ValidatorRequestLayer {
215 type Service = ValidatorRequests<S>;
216
217 fn layer(&self, inner: S) -> Self::Service {
218 ValidatorRequests {
219 inner,
220 known_methods: self.known_methods.clone(),
221 }
222 }
223}
224
225#[derive(Clone)]
227pub(crate) struct ValidatorRequests<S> {
228 inner: S,
229 known_methods: Arc<HashSet<String>>,
230}
231
232impl<S, ReqBody, ResBody> Service<http::Request<ReqBody>> for ValidatorRequests<S>
233where
234 S: Service<http::Request<ReqBody>, Response = http::Response<ResBody>> + Clone + Send + 'static,
235 S::Future: Send + 'static,
236 ReqBody: Send + 'static,
237 ResBody: Default,
238{
239 type Response = http::Response<ResBody>;
240 type Error = S::Error;
241 type Future = Pin<Box<dyn Future<Output = Result<Self::Response, Self::Error>> + Send>>;
242
243 fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
244 self.inner.poll_ready(cx)
245 }
246
247 fn call(&mut self, request: http::Request<ReqBody>) -> Self::Future {
248 let level = match admit_on_validator(
249 request.uri().path(),
250 request.headers(),
251 &self.known_methods,
252 ) {
253 Ok(level) => level,
254 Err(error) => {
255 return Box::pin(async move { Ok(tonic::Status::from(error).into_http()) });
256 }
257 };
258
259 let not_ready_inner = self.inner.clone();
263 let mut ready_inner = std::mem::replace(&mut self.inner, not_ready_inner);
264 Box::pin(async move {
265 let mut response = ready_inner.call(request).await?;
266 if level.is_some_and(|level| level < FinalityLevel::Certified) {
267 response.headers_mut().remove(X_SUI_CHECKPOINT_HEIGHT);
268 }
269 Ok(response)
270 })
271 }
272}
273
274#[cfg(test)]
275mod tests {
276 use super::*;
277
278 fn headers(level: Option<&str>) -> HeaderMap {
279 let mut headers = HeaderMap::new();
280 if let Some(level) = level {
281 headers.insert(X_SUI_FINALITY_LEVEL, level.parse().unwrap());
282 }
283 headers
284 }
285
286 #[test]
287 fn header_names_the_least_settled_level_accepted() {
288 let parse = |level| FinalityLevel::from_headers(&headers(level));
289 assert_eq!(parse(None).unwrap(), FinalityLevel::Certified);
290 assert_eq!(parse(Some("executed")).unwrap(), FinalityLevel::Executed);
291 assert_eq!(parse(Some("certified")).unwrap(), FinalityLevel::Certified);
292 for invalid in ["", "Certified", "ordered"] {
293 assert_eq!(
294 parse(Some(invalid)).unwrap_err().code(),
295 tonic::Code::InvalidArgument
296 );
297 }
298 }
299
300 fn sui_rpc_v2_methods() -> HashSet<String> {
301 crate::grpc_method_paths_from_file_descriptor_sets(&[
302 sui_rpc::proto::sui::rpc::v2::FILE_DESCRIPTOR_SET,
303 ])
304 .unwrap()
305 }
306
307 #[test]
308 fn validator_methods_exist() {
309 let methods = sui_rpc_v2_methods();
310 for (method, _) in VALIDATOR_METHODS {
311 assert!(
312 methods.contains(*method),
313 "{method} is not a sui.rpc.v2 method"
314 );
315 }
316 }
317
318 #[test]
319 fn validator_serves_each_method_up_to_its_level() {
320 let known_methods = sui_rpc_v2_methods();
321 let admit = |path, level| admit_on_validator(path, &headers(level), &known_methods);
322 let assert_refused = |path, level, cause| {
323 crate::reader::assert_not_served_here(admit(path, level).unwrap_err(), cause)
324 };
325
326 let get_checkpoint = "/sui.rpc.v2.LedgerService/GetCheckpoint";
329 for level in [None, Some("certified"), Some("executed")] {
330 assert_eq!(
331 admit(get_checkpoint, level).unwrap(),
332 Some(FinalityLevel::Certified)
333 );
334 }
335
336 for path in [
339 "/sui.rpc.v2.SubscriptionService/SubscribeCheckpoints",
340 "/sui.rpc.v2.LedgerService/GetObject",
341 "/sui.rpc.v2.SignatureVerificationService/VerifySignature",
342 ] {
343 for level in [None, Some("certified")] {
344 assert_refused(path, level, NotServedHereCause::UncertifiedLiveState);
345 }
346 assert_eq!(
347 admit(path, Some("executed")).unwrap(),
348 Some(FinalityLevel::Executed)
349 );
350 }
351
352 for path in [
355 "/sui.rpc.v2.LedgerService/GetTransaction",
356 "/sui.rpc.v2.LedgerService/ListTransactions",
357 "/sui.rpc.v2.StateService/ListOwnedObjects",
358 ] {
359 for level in [None, Some("executed")] {
360 assert_refused(path, level, NotServedHereCause::NoRpcIndexes);
361 }
362 }
363
364 for path in [
367 "/sui.rpc.v2.TransactionExecutionService/ExecuteTransaction",
368 "/sui.rpc.v2.LedgerService/NoSuchMethod",
369 ] {
370 assert_eq!(admit(path, Some("executed")).unwrap(), None);
371 }
372
373 assert_eq!(
375 admit("/sui.rpc.v2.LedgerService/GetTransaction", Some("final"))
376 .unwrap_err()
377 .code(),
378 tonic::Code::InvalidArgument
379 );
380
381 assert_eq!(
383 admit("/grpc.health.v1.Health/Check", Some("final")).unwrap(),
384 None
385 );
386 }
387}