Skip to main content

sui_rpc/client/ledger_streams/adapter/
mod.rs

1use std::future::Future;
2use std::pin::Pin;
3
4use prost::Message;
5use prost::bytes::Bytes;
6use tonic::Request;
7use tonic::Status;
8use tonic::codegen::BoxStream;
9
10use super::super::Client;
11use super::super::Result;
12use super::observability::LedgerStreamFamily;
13use crate::proto::sui::rpc::v2::Ordering;
14use crate::proto::sui::rpc::v2::QueryEnd;
15use crate::proto::sui::rpc::v2::QueryOptions;
16use crate::proto::sui::rpc::v2::Watermark;
17
18mod checkpoint;
19mod event;
20mod progress;
21mod transaction;
22
23pub(super) use super::types::Position;
24pub(super) use checkpoint::CheckpointAdapter;
25pub(super) use event::EventAdapter;
26pub(super) use progress::BoundFields;
27pub(super) use progress::KeyGranularity;
28pub(super) use progress::LedgerFrame;
29pub(super) use progress::Progress;
30pub(super) use progress::RecoveryGap;
31pub(super) use progress::missing_cursor_position;
32pub(super) use transaction::TransactionAdapter;
33
34pub(super) type RpcFuture<T> = Pin<Box<dyn Future<Output = Result<BoxStream<T>>> + Send + 'static>>;
35
36/// Connects one checkpoint, transaction, or event protocol family to the shared driver.
37pub(super) trait SubscriptionAdapter: Send + Sync + 'static {
38    const FAMILY: LedgerStreamFamily;
39    /// Fields of this family's item keys and positions.
40    const GRANULARITY: KeyGranularity;
41
42    type Item: Send + 'static;
43    /// Opaque cursor carried with progress and sent back with its position.
44    type Cursor: Clone + Send + 'static;
45    type Output: Send + 'static;
46    type ListRequest: Clone + Send + Sync + 'static;
47    type ListResponse: Send + 'static;
48    type SubscribeRequest: Clone + Send + 'static;
49    type SubscribeResponse: Message + Send + 'static;
50
51    /// Returns the List request's pagination and ordering options when present.
52    fn options(request: &Self::ListRequest) -> Option<&QueryOptions>;
53    /// Returns mutable List pagination and ordering options, inserting defaults when absent.
54    fn options_mut(request: &mut Self::ListRequest) -> &mut QueryOptions;
55    /// Returns the List request's inclusive lower checkpoint bound.
56    fn start_checkpoint(request: &Self::ListRequest) -> Option<u64>;
57    /// Returns the List request's exclusive upper checkpoint bound.
58    fn end_checkpoint(request: &Self::ListRequest) -> Option<u64>;
59    /// Replaces the List request's start checkpoint and start indexes.
60    fn set_start_fields(request: &mut Self::ListRequest, fields: BoundFields);
61    /// Replaces the List request's end checkpoint and end indexes.
62    fn set_end_fields(request: &mut Self::ListRequest, fields: BoundFields);
63    /// Validates the coverage a `CheckpointBound` ending reports against the request bounds.
64    fn validate_checkpoint_bound(
65        _request: &Self::ListRequest,
66        _direction: ListScanDirection,
67        _checkpoint: Option<u64>,
68    ) -> Result<()> {
69        Ok(())
70    }
71    /// The opaque bytes to send with a position, when this family's cursor has them.
72    fn cursor_bytes(cursor: &Self::Cursor) -> Option<Bytes>;
73    /// Converts a List watermark cursor to this family's cursor.
74    fn list_cursor(cursor: Bytes) -> Self::Cursor;
75    /// Extracts `(has_item, watermark, query_end)` metadata from a list response frame.
76    fn extract_metadata(
77        response: &Self::ListResponse,
78    ) -> (bool, Option<&Watermark>, Option<&QueryEnd>);
79    /// Takes the item payload from a List response.
80    fn into_list_item(response: Self::ListResponse) -> Option<Self::Item>;
81    /// Whether successful live frames must contain a payload item.
82    fn item_required(_request: &Self::SubscribeRequest) -> bool {
83        false
84    }
85    /// Validates and converts a Subscribe response to a keyed frame.
86    fn parse_live(
87        response: Self::SubscribeResponse,
88        item_required: bool,
89    ) -> Result<LedgerFrame<Self::Item, Self::Cursor>>;
90    /// Converts an optional payload and its progress to a public frame.
91    fn into_output(item: Option<Self::Item>, progress: Progress<Self::Cursor>) -> Self::Output;
92    fn dispatch_list(
93        client: Client,
94        request: Request<Self::ListRequest>,
95    ) -> RpcFuture<Self::ListResponse>;
96    fn dispatch_subscribe(
97        client: Client,
98        request: Request<Self::SubscribeRequest>,
99    ) -> RpcFuture<Self::SubscribeResponse>;
100}
101
102/// Starts `request` at `position`, sending `cursor`, which names the same point, as
103/// `options.after`.
104pub(super) fn set_start<A: SubscriptionAdapter>(
105    request: &mut A::ListRequest,
106    position: Position,
107    cursor: Option<Bytes>,
108) {
109    A::set_start_fields(request, position.start_fields());
110    A::options_mut(request).after = cursor;
111}
112
113/// Ends `request` at `position`, sending `cursor`, which names the same point, as
114/// `options.before`.
115pub(super) fn set_end<A: SubscriptionAdapter>(
116    request: &mut A::ListRequest,
117    position: Position,
118    cursor: Option<Bytes>,
119) -> Result<()> {
120    A::set_end_fields(request, position.end_fields()?);
121    A::options_mut(request).before = cursor;
122    Ok(())
123}
124
125/// Reads an ascending subscription frame, whose watermark must carry a cursor and its position.
126fn parse_opaque_live_frame<I>(
127    item: Option<I>,
128    watermark: Option<Watermark>,
129    granularity: KeyGranularity,
130) -> Result<LedgerFrame<I, Bytes>> {
131    let watermark = watermark
132        .ok_or_else(|| Status::data_loss("subscription frame is missing its watermark"))?;
133    let position = watermark
134        .cursor_position
135        .as_ref()
136        .map(|position| granularity.position(position))
137        .ok_or_else(|| missing_cursor_position("subscription"))?;
138    let cursor = watermark
139        .cursor
140        .ok_or_else(|| Status::data_loss("subscription watermark is missing its cursor"))?;
141    let progress = Progress {
142        position,
143        cursor,
144        checkpoint: watermark.checkpoint,
145    };
146    LedgerFrame::new(item, progress, granularity)
147}
148
149#[derive(Clone, Copy, Debug, PartialEq, Eq)]
150pub(super) enum ListScanDirection {
151    Ascending,
152    Descending,
153}
154
155impl ListScanDirection {
156    pub(super) fn from_request<A: SubscriptionAdapter>(request: &A::ListRequest) -> Result<Self> {
157        match A::options(request).and_then(|options| options.ordering) {
158            None => Ok(Self::Ascending),
159            Some(ordering) => match Ordering::try_from(ordering) {
160                Ok(Ordering::Ascending) => Ok(Self::Ascending),
161                Ok(Ordering::Descending) => Ok(Self::Descending),
162                Err(_) => Err(Status::invalid_argument("List ordering is unknown")),
163            },
164        }
165    }
166
167    /// Whether `next` lies strictly further than `previous` in this scan direction.
168    pub(super) fn beyond(self, next: Position, previous: Position) -> bool {
169        match self {
170            Self::Ascending => next > previous,
171            Self::Descending => next < previous,
172        }
173    }
174
175    /// Continues `request` in this direction from `progress`: ascending, starting at its
176    /// position; descending, ending there. Sends the cursor in the matching slot.
177    pub(super) fn set_resume<A: SubscriptionAdapter>(
178        self,
179        request: &mut A::ListRequest,
180        progress: &Progress<Bytes>,
181    ) -> Result<()> {
182        match self {
183            Self::Ascending => {
184                set_start::<A>(request, progress.position, Some(progress.cursor.clone()));
185                Ok(())
186            }
187            Self::Descending => {
188                set_end::<A>(request, progress.position, Some(progress.cursor.clone()))
189            }
190        }
191    }
192
193    /// Whether `options` carries an opaque cursor in this direction's resume slot.
194    pub(super) fn has_resume_cursor(self, options: &QueryOptions) -> bool {
195        match self {
196            Self::Ascending => options.after.is_some(),
197            Self::Descending => options.before.is_some(),
198        }
199    }
200}