Skip to main content

cpa_plugin/
client.rs

1//! Plugin clients and the call guard (internal/pluginhost/client_guard.go).
2//!
3//! Plugin entry points block, so every call runs on Tokio's blocking pool. A caller that
4//! stops waiting (its future is dropped) does not stop the call; the guard counts calls
5//! still running and shutdown waits for them before the library is closed, as Go's
6//! `guardedPluginClient` does.
7
8use std::sync::{Arc, Condvar, Mutex};
9use std::time::Duration;
10
11use bytes::Bytes;
12
13use std::sync::atomic::{AtomicBool, Ordering};
14
15/// Rejects callbacks from a plugin instance once its load was abandoned or it was
16/// unloaded (Go `hostCallbackInstance`).
17#[derive(Debug, Default)]
18pub struct CallbackInstance {
19    closed: AtomicBool,
20}
21
22impl CallbackInstance {
23    pub fn close(&self) {
24        self.closed.store(true, Ordering::SeqCst);
25    }
26
27    pub fn is_closed(&self) -> bool {
28        self.closed.load(Ordering::SeqCst)
29    }
30}
31
32/// A host callback failure: `host_call_failed` with an optional HTTP status.
33#[derive(Debug, Clone, PartialEq, Eq)]
34pub struct CallbackError {
35    pub message: String,
36    pub status: u16,
37}
38
39impl CallbackError {
40    pub fn new(message: impl Into<String>) -> Self {
41        Self {
42            message: message.into(),
43            status: 0,
44        }
45    }
46}
47
48/// Receives `host.*` calls from plugins. Called on the plugin's thread; implementations
49/// may block.
50pub trait CallbackHandler: Send + Sync {
51    fn call_from_plugin(
52        &self,
53        plugin_id: &str,
54        instance: &Arc<CallbackInstance>,
55        method: &str,
56        request: Bytes,
57    ) -> Result<Bytes, CallbackError>;
58}
59
60/// One loaded plugin, native or test double.
61pub trait PluginClient: Send + Sync + 'static {
62    /// Blocking RPC call: request JSON in, response envelope out.
63    fn call(&self, method: &str, request: &[u8]) -> Result<Bytes, String>;
64    /// Releases the plugin. Called once, after every call has returned.
65    fn shutdown(&self);
66}
67
68#[cfg(unix)]
69impl PluginClient for crate::native::NativeClient {
70    fn call(&self, method: &str, request: &[u8]) -> Result<Bytes, String> {
71        crate::native::NativeClient::call(self, method, request)
72    }
73    fn shutdown(&self) {
74        crate::native::NativeClient::shutdown(self)
75    }
76}
77
78/// Why a guarded call produced no response.
79#[derive(Debug, Clone, PartialEq, Eq)]
80pub enum GuardError {
81    Closed,
82    /// The call failed below the RPC layer (a non-zero return without an error envelope).
83    Transport(String),
84    /// Host-side code panicked while serving the call; the plugin gets fused.
85    Panic(String),
86}
87
88impl std::fmt::Display for GuardError {
89    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
90        match self {
91            GuardError::Closed => f.write_str("plugin client is closed"),
92            GuardError::Transport(e) => f.write_str(e),
93            GuardError::Panic(e) => write!(f, "plugin call panic: {e}"),
94        }
95    }
96}
97
98#[derive(Default)]
99struct GuardState {
100    inner: Option<Arc<dyn PluginClient>>,
101    calls: usize,
102    closed: bool,
103}
104
105/// Go `guardedPluginClient`.
106pub struct GuardedClient {
107    state: Mutex<GuardState>,
108    changed: Condvar,
109    instance: Arc<CallbackInstance>,
110    /// Flips to `true` once the plugin has been shut down.
111    done: tokio::sync::watch::Sender<bool>,
112}
113
114fn lock<T>(m: &Mutex<T>) -> std::sync::MutexGuard<'_, T> {
115    m.lock().unwrap_or_else(std::sync::PoisonError::into_inner)
116}
117
118impl GuardedClient {
119    pub fn new(inner: Arc<dyn PluginClient>, instance: Arc<CallbackInstance>) -> Arc<Self> {
120        Arc::new(Self {
121            state: Mutex::new(GuardState {
122                inner: Some(inner),
123                ..Default::default()
124            }),
125            changed: Condvar::new(),
126            instance,
127            done: tokio::sync::watch::Sender::new(false),
128        })
129    }
130
131    pub fn instance(&self) -> &Arc<CallbackInstance> {
132        &self.instance
133    }
134
135    fn acquire(&self) -> Result<Arc<dyn PluginClient>, GuardError> {
136        let mut state = lock(&self.state);
137        match (&state.inner, state.closed) {
138            (Some(inner), false) => {
139                let inner = inner.clone();
140                state.calls += 1;
141                Ok(inner)
142            }
143            _ => Err(GuardError::Closed),
144        }
145    }
146
147    fn release(&self) {
148        let mut state = lock(&self.state);
149        state.calls -= 1;
150        if state.calls == 0 {
151            self.changed.notify_all();
152        }
153    }
154
155    /// Runs one call on the blocking pool.
156    pub async fn call(self: &Arc<Self>, method: &str, request: Vec<u8>) -> Result<Bytes, GuardError> {
157        let inner = self.acquire()?;
158        let this = self.clone();
159        let method = method.to_owned();
160        let task = tokio::task::spawn_blocking(move || {
161            struct Release(Arc<GuardedClient>);
162            impl Drop for Release {
163                fn drop(&mut self) {
164                    self.0.release();
165                }
166            }
167            let _release = Release(this);
168            inner.call(&method, &request)
169        });
170        match task.await {
171            Ok(result) => result.map_err(GuardError::Transport),
172            Err(e) => Err(GuardError::Panic(e.to_string())),
173        }
174    }
175
176    /// [`GuardedClient::call`] for synchronous callers (translator hooks and thinking
177    /// appliers run inside the translation that needs them, as Go's do). The call runs
178    /// on this thread, inside `block_in_place` on a multi-threaded runtime so plugin
179    /// callbacks may block on it. From a current-thread runtime it runs on a scoped
180    /// thread while the runtime waits, so callbacks that need the runtime
181    /// (`host.http.*`, `host.model.*`) fail during the call instead of hanging.
182    pub fn call_blocking(self: &Arc<Self>, method: &str, request: &[u8]) -> Result<Bytes, GuardError> {
183        self.call_blocking_in(method, request, || ())
184    }
185
186    /// [`Self::call_blocking`] with `scope` entered, for the call's duration, on the
187    /// thread that makes the plugin call: from a current-thread runtime that is not this
188    /// thread, and a native plugin's synchronous callbacks arrive on it.
189    pub fn call_blocking_in<G>(
190        self: &Arc<Self>,
191        method: &str,
192        request: &[u8],
193        scope: impl FnOnce() -> G + Send,
194    ) -> Result<Bytes, GuardError> {
195        let inner = self.acquire()?;
196        struct Release<'a>(&'a GuardedClient);
197        impl Drop for Release<'_> {
198            fn drop(&mut self) {
199                self.0.release();
200            }
201        }
202        let _release = Release(self);
203        let call = move || {
204            let _scope = scope();
205            std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| inner.call(method, request)))
206                .map_err(|p| GuardError::Panic(panic_text(&*p)))?
207                .map_err(GuardError::Transport)
208        };
209        match tokio::runtime::Handle::try_current().map(|h| h.runtime_flavor()) {
210            Ok(tokio::runtime::RuntimeFlavor::MultiThread) => tokio::task::block_in_place(call),
211            Ok(_) => {
212                // This thread drives the runtime and now waits, so callbacks that need
213                // the runtime fail fast (see `PARKED_CURRENT_THREAD`).
214                use std::sync::atomic::Ordering;
215                struct Parked;
216                impl Drop for Parked {
217                    fn drop(&mut self) {
218                        crate::callbacks::PARKED_CURRENT_THREAD.fetch_sub(1, Ordering::AcqRel);
219                    }
220                }
221                crate::callbacks::PARKED_CURRENT_THREAD.fetch_add(1, Ordering::AcqRel);
222                let _parked = Parked;
223                std::thread::scope(|s| s.spawn(call).join().unwrap_or_else(|p| std::panic::resume_unwind(p)))
224            }
225            Err(_) => call(),
226        }
227    }
228
229    /// Detaches the client at once, then waits up to `wait` for running calls to drain
230    /// and the plugin to shut down. Shutdown itself always completes on a dedicated
231    /// thread (Go `ShutdownContext`). `None` waits indefinitely.
232    pub async fn shutdown(self: &Arc<Self>, wait: Option<Duration>) {
233        let start = {
234            let mut state = lock(&self.state);
235            !std::mem::replace(&mut state.closed, true)
236        };
237        if start {
238            let this = self.clone();
239            std::thread::spawn(move || {
240                let mut state = lock(&this.state);
241                while state.calls > 0 {
242                    state = this
243                        .changed
244                        .wait(state)
245                        .unwrap_or_else(std::sync::PoisonError::into_inner);
246                }
247                let inner = state.inner.take();
248                drop(state);
249                if let Some(inner) = inner {
250                    inner.shutdown();
251                }
252                this.done.send_replace(true);
253            });
254        }
255        let mut done = self.done.subscribe();
256        let finished = done.wait_for(|done| *done);
257        match wait {
258            Some(limit) => {
259                let _ = tokio::time::timeout(limit, finished).await;
260            }
261            None => {
262                let _ = finished.await;
263            }
264        }
265    }
266
267    /// Whether shutdown has finished (the library is closed).
268    pub fn is_shut_down(&self) -> bool {
269        *self.done.borrow()
270    }
271
272    pub fn active_calls(&self) -> usize {
273        lock(&self.state).calls
274    }
275}
276
277fn panic_text(p: &(dyn std::any::Any + Send)) -> String {
278    p.downcast_ref::<&str>()
279        .map(|s| (*s).to_owned())
280        .or_else(|| p.downcast_ref::<String>().cloned())
281        .unwrap_or_else(|| "panic".to_owned())
282}
283
284#[cfg(test)]
285mod tests {
286    use super::*;
287
288    struct Slow {
289        release: Arc<(Mutex<bool>, Condvar)>,
290        shut: Arc<AtomicBool>,
291    }
292
293    impl PluginClient for Slow {
294        fn call(&self, _: &str, _: &[u8]) -> Result<Bytes, String> {
295            let (m, c) = &*self.release;
296            let mut go = lock(m);
297            while !*go {
298                go = c.wait(go).unwrap();
299            }
300            Ok(Bytes::from_static(b"{}"))
301        }
302        fn shutdown(&self) {
303            self.shut.store(true, Ordering::SeqCst);
304        }
305    }
306
307    /// Go `TestGuardedPluginClientShutdownContextDetachesBlockedCall`: shutdown stops
308    /// waiting at its deadline, rejects new calls at once, and closes the plugin only
309    /// after the blocked call returns.
310    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
311    async fn shutdown_detaches_then_waits_for_running_calls() {
312        let release = Arc::new((Mutex::new(false), Condvar::new()));
313        let shut = Arc::new(AtomicBool::new(false));
314        let client = GuardedClient::new(
315            Arc::new(Slow {
316                release: release.clone(),
317                shut: shut.clone(),
318            }),
319            Arc::default(),
320        );
321        let running = {
322            let client = client.clone();
323            tokio::spawn(async move { client.call("m", vec![]).await })
324        };
325        while client.active_calls() == 0 {
326            tokio::task::yield_now().await;
327        }
328        client.shutdown(Some(Duration::from_millis(20))).await;
329        assert!(!shut.load(Ordering::SeqCst), "blocked call must finish before shutdown");
330        assert_eq!(client.call("m", vec![]).await, Err(GuardError::Closed));
331        *lock(&release.0) = true;
332        release.1.notify_all();
333        assert!(running.await.unwrap().is_ok());
334        client.shutdown(None).await;
335        assert!(shut.load(Ordering::SeqCst));
336    }
337}