Skip to main content

subc_client_rs/
module_subscription.rs

1//! Bounded channel-zero streams on a module's registered connection.
2
3use super::*;
4use subc_control::ScopeWatchRequest;
5
6pub(crate) struct ControlStreamSender {
7    events: mpsc::Sender<Frame>,
8    terminal: oneshot::Sender<Result<(), ScopeCallError>>,
9}
10
11struct ModuleControlSubscription {
12    shared: Arc<ModuleHandleShared>,
13    corr: u64,
14    events: mpsc::Receiver<Frame>,
15    terminal: Option<oneshot::Receiver<Result<(), ScopeCallError>>>,
16    finished: bool,
17}
18
19impl ModuleHandle {
20    /// Watch scope epochs on this registered connection. The initial snapshot
21    /// closes the gap for endings before open; subsequent events are terminal
22    /// for each selector. Drop or unsubscribe, then reopen to replace the set.
23    /// A lost connection ends the feed; open a new watch after registering again.
24    pub async fn scope_watch(
25        &self,
26        scopes: Vec<ScopeWatchSelector>,
27    ) -> Result<ScopeSubscription, ScopeCallError> {
28        if !self.shared.supports_scope_watch {
29            return Err(ScopeCallError::NotSupported {
30                op: subc_control::ops::SCOPE_WATCH,
31            });
32        }
33        let body = serde_json::to_vec(&ScopeWatchRequest::new(scopes))
34            .map_err(|err| ScopeCallError::Protocol(err.to_string()))?;
35        // One snapshot and at most 256 terminal events can arrive before the
36        // caller next polls; the reader must never block module RPC dispatch.
37        let mut inner = self.control_subscribe(body, 257).await?;
38        let first = timeout(CATALOG_UPDATE_TIMEOUT, inner.next())
39            .await
40            .map_err(|_| ScopeCallError::Timeout)??
41            .ok_or_else(|| {
42                ScopeCallError::Protocol("scope.watch ended before its snapshot".into())
43            })?;
44        if first.header.ty != FrameType::Response {
45            return Err(ScopeCallError::Protocol(
46                "scope.watch did not open with a snapshot RESPONSE".into(),
47            ));
48        }
49        let initial = serde_json::from_slice(&first.body).map_err(|err| {
50            ScopeCallError::Protocol(format!("invalid scope.watch snapshot: {err}"))
51        })?;
52        Ok(ScopeSubscription { initial, inner })
53    }
54
55    async fn control_subscribe(
56        &self,
57        body: Vec<u8>,
58        capacity: usize,
59    ) -> Result<ModuleControlSubscription, ScopeCallError> {
60        let (events, rx) = mpsc::channel(capacity);
61        let (terminal, closed) = oneshot::channel();
62        let (corr, writer) = {
63            let mut state = self.shared.lock_inner();
64            if state.closed {
65                return Err(ScopeCallError::ConnectionClosed);
66            }
67            let writer = state
68                .writer
69                .clone()
70                .ok_or(ScopeCallError::ConnectionClosed)?;
71            let corr =
72                next_module_control_corr(&mut state).ok_or(ScopeCallError::ConnectionClosed)?;
73            state
74                .pending_control_streams
75                .insert(corr, ControlStreamSender { events, terminal });
76            (corr, writer)
77        };
78        let stream = ModuleControlSubscription {
79            shared: Arc::clone(&self.shared),
80            corr,
81            events: rx,
82            terminal: Some(closed),
83            finished: false,
84        };
85        let frame = Frame::build_with_version(
86            self.shared.negotiated_ver,
87            FrameType::Request,
88            Flags(control_flags().0 | subc_protocol::FLAG_SUBSCRIPTION),
89            0,
90            0,
91            corr,
92            body,
93        )
94        .map_err(|err| ScopeCallError::Protocol(err.to_string()))?;
95        timeout(CATALOG_UPDATE_TIMEOUT, writer.send(frame))
96            .await
97            .map_err(|_| ScopeCallError::Timeout)?
98            .map_err(|_| ScopeCallError::ConnectionClosed)?;
99        Ok(stream)
100    }
101
102    pub(crate) fn handle_control_stream_frame(&self, frame: Frame) -> Option<Frame> {
103        let mut state = self.shared.lock_inner();
104        let corr = frame.header.corr;
105        let Some(stream) = state.pending_control_streams.remove(&corr) else {
106            return Some(frame);
107        };
108        let mut cancel = false;
109        let terminal = match frame.header.ty {
110            FrameType::Error => Err(match serde_json::from_slice::<ErrorBody>(&frame.body) {
111                Ok(body) => ScopeCallError::Refused {
112                    code: body.code,
113                    message: body.message,
114                },
115                Err(err) => ScopeCallError::Protocol(err.to_string()),
116            }),
117            FrameType::StreamEnd => Ok(()),
118            FrameType::Response | FrameType::StreamData => {
119                let last = frame.header.flags.is_last();
120                if stream.events.try_send(frame).is_err() {
121                    cancel = true;
122                    Err(ScopeCallError::Protocol(
123                        "module control subscription event buffer exhausted".into(),
124                    ))
125                } else if last {
126                    Ok(())
127                } else {
128                    state.pending_control_streams.insert(corr, stream);
129                    return None;
130                }
131            }
132            _ => {
133                state.pending_control_streams.insert(corr, stream);
134                return Some(frame);
135            }
136        };
137        let _ = stream.terminal.send(terminal);
138        let writer = cancel.then(|| state.writer.clone()).flatten();
139        drop(state);
140        if let Some(writer) = writer {
141            send_cancel(&self.shared, corr, writer);
142        }
143        None
144    }
145}
146
147impl ModuleControlSubscription {
148    async fn next(&mut self) -> Result<Option<Frame>, ScopeCallError> {
149        if self.finished {
150            return Ok(None);
151        }
152        if let Some(frame) = self.events.recv().await {
153            return Ok(Some(frame));
154        }
155        self.finished = true;
156        match self.terminal.take() {
157            Some(terminal) => terminal
158                .await
159                .unwrap_or(Err(ScopeCallError::ConnectionClosed))
160                .map(|()| None),
161            None => Ok(None),
162        }
163    }
164
165    fn cancel(&mut self) {
166        self.finished = true;
167        let writer = {
168            let mut state = self.shared.lock_inner();
169            if state.pending_control_streams.remove(&self.corr).is_none() {
170                return;
171            }
172            state.writer.clone()
173        };
174        if let Some(writer) = writer {
175            send_cancel(&self.shared, self.corr, writer);
176        }
177    }
178}
179
180fn send_cancel(shared: &ModuleHandleShared, corr: u64, writer: mpsc::Sender<Frame>) {
181    if let Ok(frame) = Frame::build_with_version(
182        shared.negotiated_ver,
183        FrameType::Cancel,
184        control_flags(),
185        0,
186        0,
187        corr,
188        vec![],
189    ) {
190        shared.connection_runtime.spawn(async move {
191            let _ = timeout(CATALOG_UPDATE_TIMEOUT, writer.send(frame)).await;
192        });
193    }
194}
195
196impl Drop for ModuleControlSubscription {
197    fn drop(&mut self) {
198        self.cancel();
199    }
200}
201
202/// A scope lifecycle feed on the module's registered connection. Initial
203/// states are available before any push; queued pushes precede terminal errors.
204pub struct ScopeSubscription {
205    pub initial: ScopeWatchResponse,
206    inner: ModuleControlSubscription,
207}
208
209impl ScopeSubscription {
210    pub async fn next(&mut self) -> Result<Option<ScopeWatchPush>, ScopeCallError> {
211        let Some(frame) = self.inner.next().await? else {
212            return Ok(None);
213        };
214        serde_json::from_slice(&frame.body)
215            .map(Some)
216            .map_err(|err| {
217                self.inner.cancel();
218                ScopeCallError::Protocol(format!("invalid scope.watch event: {err}"))
219            })
220    }
221
222    pub fn unsubscribe(&mut self) {
223        self.inner.cancel();
224    }
225}