Skip to main content

cpa_plugin/
streams.rs

1//! Plugin-fed streams (internal/pluginhost/stream_bridge.go).
2//!
3//! `executor.execute_stream` hands the plugin a `stream_id`; the plugin pushes chunks
4//! with `host.stream.emit` (blocking while 16 are queued) and ends with
5//! `host.stream.close`, optionally with an error that becomes the final chunk. The host
6//! side reads chunks asynchronously; dropping the reader aborts the stream so a pending
7//! emit returns "stream is not open".
8
9use std::collections::{HashMap, VecDeque};
10use std::sync::atomic::{AtomicU64, Ordering};
11use std::sync::{Arc, Condvar, Mutex};
12
13use bytes::Bytes;
14
15use crate::host::lock;
16
17const BUFFER: usize = 16;
18
19/// One chunk (`pluginapi.ExecutorStreamChunk`): a payload and, when set, an error that
20/// ends the stream after it. A plugin may send both in one emit.
21#[derive(Debug, Clone, Default, PartialEq, Eq)]
22pub struct Chunk {
23    pub payload: Bytes,
24    pub error: Option<String>,
25}
26
27impl Chunk {
28    pub fn data(payload: Bytes) -> Self {
29        Self { payload, error: None }
30    }
31
32    pub fn error(message: impl Into<String>) -> Self {
33        Self {
34            payload: Bytes::new(),
35            error: Some(message.into()),
36        }
37    }
38}
39
40#[derive(Default)]
41struct Queue {
42    items: VecDeque<Chunk>,
43    closed: bool,
44    aborted: bool,
45}
46
47struct Stream {
48    queue: Mutex<Queue>,
49    space: Condvar,
50    ready: tokio::sync::Notify,
51}
52
53impl Stream {
54    fn emit(&self, chunk: Chunk) -> Result<(), ()> {
55        let mut q = lock(&self.queue);
56        loop {
57            if q.closed || q.aborted {
58                return Err(());
59            }
60            if q.items.len() < BUFFER {
61                q.items.push_back(chunk);
62                self.ready.notify_one();
63                return Ok(());
64            }
65            q = self.space.wait(q).unwrap_or_else(std::sync::PoisonError::into_inner);
66        }
67    }
68
69    fn close(&self, error: &str) {
70        let mut q = lock(&self.queue);
71        if q.closed || q.aborted {
72            return;
73        }
74        q.closed = true;
75        if !error.is_empty() {
76            q.items.push_back(Chunk::error(error));
77        }
78        // Terminal: wake every pending reader, as closing Go's channel does.
79        self.ready.notify_waiters();
80        self.space.notify_all();
81    }
82
83    fn abort(&self) {
84        let mut q = lock(&self.queue);
85        q.aborted = true;
86        q.items.clear();
87        self.ready.notify_waiters();
88        self.space.notify_all();
89    }
90
91    async fn next(&self) -> Option<Chunk> {
92        loop {
93            let notified = self.ready.notified();
94            tokio::pin!(notified);
95            notified.as_mut().enable();
96            {
97                let mut q = lock(&self.queue);
98                if let Some(chunk) = q.items.pop_front() {
99                    self.space.notify_one();
100                    return Some(chunk);
101                }
102                if q.closed || q.aborted {
103                    return None;
104                }
105            }
106            notified.await;
107        }
108    }
109}
110
111/// Go `streamBridge`.
112#[derive(Default)]
113pub struct StreamBridge {
114    next: AtomicU64,
115    streams: Mutex<HashMap<String, Arc<Stream>>>,
116}
117
118/// The reading side of one bridged stream. Dropping it aborts the stream.
119pub struct Reader {
120    id: String,
121    stream: Arc<Stream>,
122    bridge: std::sync::Weak<StreamBridge>,
123}
124
125impl Reader {
126    pub fn id(&self) -> &str {
127        &self.id
128    }
129
130    /// The next chunk; `None` once the plugin closed the stream and it drained.
131    pub async fn next(&self) -> Option<Chunk> {
132        self.stream.next().await
133    }
134}
135
136impl Drop for Reader {
137    fn drop(&mut self) {
138        if let Some(bridge) = self.bridge.upgrade() {
139            let mut streams = lock(&bridge.streams);
140            if streams.get(&self.id).is_some_and(|s| Arc::ptr_eq(s, &self.stream)) {
141                streams.remove(&self.id);
142            }
143        }
144        self.stream.abort();
145    }
146}
147
148impl StreamBridge {
149    /// Go `streamBridge.open`: IDs are decimal counters from 1.
150    pub fn open(self: &Arc<Self>) -> Reader {
151        let id = (self.next.fetch_add(1, Ordering::SeqCst) + 1).to_string();
152        let stream = Arc::new(Stream {
153            queue: Mutex::default(),
154            space: Condvar::new(),
155            ready: tokio::sync::Notify::new(),
156        });
157        lock(&self.streams).insert(id.clone(), stream.clone());
158        Reader {
159            id,
160            stream,
161            bridge: Arc::downgrade(self),
162        }
163    }
164
165    /// Go `streamBridge.emit`. Blocks while the stream is full.
166    pub fn emit(&self, id: &str, chunk: Chunk) -> Result<(), String> {
167        if id.is_empty() {
168            return Err("stream id is required".into());
169        }
170        let stream = lock(&self.streams).get(id).cloned();
171        let Some(stream) = stream else {
172            return Err(format!("stream {id} is not open"));
173        };
174        stream.emit(chunk).map_err(|()| format!("stream {id} is not open"))
175    }
176
177    /// Go `streamBridge.close`.
178    pub fn close(&self, id: &str, error: &str) {
179        if id.is_empty() {
180            return;
181        }
182        let stream = lock(&self.streams).remove(id);
183        if let Some(stream) = stream {
184            stream.close(error);
185        }
186    }
187}
188
189#[cfg(test)]
190mod tests {
191    use super::*;
192
193    /// Go `TestStreamBridgeCloseUnblocksPendingEmit` and ordering: a full stream blocks
194    /// the emitter until the reader takes a chunk; close appends the error chunk; a
195    /// dropped reader makes pending emits fail.
196    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
197    async fn backpressure_close_and_abort() {
198        let bridge = Arc::new(StreamBridge::default());
199        let reader = bridge.open();
200        let id = reader.id().to_owned();
201        let emitter = {
202            let bridge = bridge.clone();
203            let id = id.clone();
204            tokio::task::spawn_blocking(move || {
205                for i in 0..20u8 {
206                    bridge.emit(&id, Chunk::data(Bytes::from(vec![i]))).unwrap();
207                }
208                bridge.close(&id, "boom");
209            })
210        };
211        let mut got = Vec::new();
212        while let Some(chunk) = reader.next().await {
213            got.push(chunk);
214        }
215        emitter.await.unwrap();
216        assert_eq!(got.len(), 21);
217        assert_eq!(got[0], Chunk::data(Bytes::from_static(&[0])));
218        assert_eq!(got[20], Chunk::error("boom"));
219        assert_eq!(
220            bridge.emit(&id, Chunk::default()),
221            Err(format!("stream {id} is not open"))
222        );
223
224        let reader = bridge.open();
225        let id = reader.id().to_owned();
226        for _ in 0..BUFFER {
227            bridge.emit(&id, Chunk::default()).unwrap();
228        }
229        let blocked = {
230            let bridge = bridge.clone();
231            let id = id.clone();
232            tokio::task::spawn_blocking(move || bridge.emit(&id, Chunk::default()))
233        };
234        tokio::time::sleep(std::time::Duration::from_millis(20)).await;
235        drop(reader);
236        assert_eq!(blocked.await.unwrap(), Err(format!("stream {id} is not open")));
237
238        // Closing wakes every pending reader; notify_one would leave one asleep.
239        let reader = Arc::new(bridge.open());
240        let id = reader.id().to_owned();
241        let waiters: Vec<_> = (0..2)
242            .map(|_| {
243                let reader = reader.clone();
244                tokio::spawn(async move { reader.next().await })
245            })
246            .collect();
247        tokio::time::sleep(std::time::Duration::from_millis(20)).await;
248        bridge.close(&id, "");
249        for waiter in waiters {
250            let got = tokio::time::timeout(std::time::Duration::from_secs(5), waiter).await;
251            assert_eq!(got.expect("reader woke").unwrap(), None);
252        }
253    }
254}