Skip to main content

cpa_plugin/
callbacks.rs

1//! Host callbacks (`host.*` methods) and callback contexts
2//! (internal/pluginhost/host_callbacks.go, callback_contexts.go).
3//!
4//! A capability call that lets the plugin call back opens a callback context and sends
5//! its ID as `host_callback_id`. The context ties later callbacks to the calling plugin
6//! instance and the request they serve (request ID for logs, cancellation) and owns
7//! resources opened through it, which close with the context.
8
9use std::collections::HashMap;
10use std::sync::atomic::{AtomicU64, AtomicUsize, Ordering};
11use std::sync::{Arc, Mutex, OnceLock, Weak};
12
13use bytes::Bytes;
14
15use crate::abi::{self, method};
16use crate::client::{CallbackError, CallbackHandler, CallbackInstance};
17use crate::go_struct;
18use crate::gojson::{self, Metadata};
19use crate::host::{Host, Inner, lock};
20use crate::streams::{Chunk, StreamBridge};
21
22/// Synchronous plugin calls (translator hooks, thinking appliers) currently blocking a
23/// current-thread runtime's only thread. While any is, callbacks that would block on a
24/// current-thread runtime fail instead of hanging.
25// ponytail: process-wide, so one parked current-thread runtime also refuses callbacks
26// bound to another current-thread runtime. The binary runs multi-threaded, where
27// synchronous calls use `block_in_place` and callbacks always work; per-runtime
28// tracking is the upgrade if an embedder needs current-thread runtimes side by side.
29pub(crate) static PARKED_CURRENT_THREAD: AtomicUsize = AtomicUsize::new(0);
30
31/// What a callback context remembers about the request it serves.
32#[derive(Clone, Default)]
33pub struct RequestScope {
34    /// Go `logging.GetRequestID`, added to `host.log` entries.
35    pub request_id: String,
36    /// The request's upstream capture (Go's request-log context): `host.http.*`
37    /// records each plugin HTTP exchange in it.
38    pub capture: cpa_core::exec::CaptureSink,
39    /// The request's cancellation (Go's request context): `host.http.*` operations
40    /// opened under the context end when it fires.
41    pub cancel: tokio_util::sync::CancellationToken,
42    /// Inbound values inherited by host.model callbacks that omit overrides.
43    pub headers: gojson::Header,
44    pub query: gojson::Header,
45    /// Internal execution context; never serialized to plugin RPC requests.
46    pub pinned_auth_id: Option<String>,
47    pub execution_session: Option<String>,
48    pub request_path: String,
49    /// The client's usage identity (Go's parent callback context: `userApiKey` and
50    /// `accessProvider`), for the usage records of nested `host.model.*` calls.
51    pub api_key: String,
52    pub access_provider: String,
53}
54
55impl std::fmt::Debug for RequestScope {
56    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
57        f.debug_struct("RequestScope")
58            .field("request_id", &self.request_id)
59            .field("capture", &self.capture.enabled())
60            .field("cancelled", &self.cancel.is_cancelled())
61            .finish()
62    }
63}
64
65pub(crate) type Cleanup = Box<dyn FnOnce() + Send>;
66
67struct Context {
68    plugin_id: String,
69    instance: Option<Arc<CallbackInstance>>,
70    scope: RequestScope,
71    cleanups: Vec<(u64, Cleanup)>,
72}
73
74/// Closes its callback context when dropped (Go's `closeCallback`).
75pub struct ContextGuard {
76    id: String,
77    callbacks: Weak<Inner>,
78}
79
80impl ContextGuard {
81    pub fn id(&self) -> &str {
82        &self.id
83    }
84}
85
86impl Drop for ContextGuard {
87    fn drop(&mut self) {
88        if let Some(inner) = self.callbacks.upgrade() {
89            inner.callbacks.close_context(&self.id);
90        }
91    }
92}
93
94pub(crate) struct Callbacks {
95    host: Weak<Inner>,
96    next_context: AtomicU64,
97    next_cleanup: AtomicU64,
98    contexts: Mutex<HashMap<String, Context>>,
99    pub streams: Arc<StreamBridge>,
100    pub http: crate::hosthttp::HttpBridge,
101    /// The server's credential manager (Go `SetAuthManager`).
102    pub auth: std::sync::RwLock<Option<Arc<dyn crate::hostauth::AuthManager>>>,
103    pub model_executor: std::sync::RwLock<Option<Arc<dyn crate::hostmodel::ModelExecutor>>>,
104    pub model: crate::hostmodel::ModelBridge,
105    runtime: OnceLock<tokio::runtime::Handle>,
106}
107
108impl Callbacks {
109    pub fn new(host: Weak<Inner>) -> Self {
110        Self {
111            host,
112            next_context: AtomicU64::new(0),
113            next_cleanup: AtomicU64::new(0),
114            contexts: Mutex::default(),
115            streams: Arc::default(),
116            http: Default::default(),
117            auth: Default::default(),
118            model_executor: Default::default(),
119            model: Default::default(),
120            runtime: OnceLock::new(),
121        }
122    }
123
124    /// The handler handed to loaded plugins. Captures the current Tokio runtime, which
125    /// async callbacks run on.
126    pub fn handler(&self) -> Dispatch {
127        if let Ok(handle) = tokio::runtime::Handle::try_current() {
128            let _ = self.runtime.set(handle);
129        }
130        Dispatch {
131            host: self.host.clone(),
132        }
133    }
134
135    /// Go `openCallbackContextForPluginInstance`.
136    pub fn open(&self, plugin_id: &str, instance: Option<Arc<CallbackInstance>>, scope: RequestScope) -> ContextGuard {
137        let id = (self.next_context.fetch_add(1, Ordering::SeqCst) + 1).to_string();
138        lock(&self.contexts).insert(
139            id.clone(),
140            Context {
141                plugin_id: plugin_id.trim().to_owned(),
142                instance,
143                scope,
144                cleanups: Vec::new(),
145            },
146        );
147        ContextGuard {
148            id,
149            callbacks: self.host.clone(),
150        }
151    }
152
153    fn close_context(&self, id: &str) {
154        let ctx = lock(&self.contexts).remove(id);
155        if let Some(ctx) = ctx {
156            for (_, cleanup) in ctx.cleanups {
157                cleanup();
158            }
159        }
160    }
161
162    /// The runtime async callbacks run on (captured when plugins were handed the
163    /// dispatcher). `None` while a current-thread runtime is parked in a synchronous
164    /// plugin call ([`PARKED_CURRENT_THREAD`]): blocking on it would never finish.
165    pub fn runtime_handle(&self) -> Option<tokio::runtime::Handle> {
166        let handle = self.runtime.get()?;
167        if handle.runtime_flavor() == tokio::runtime::RuntimeFlavor::CurrentThread
168            && PARKED_CURRENT_THREAD.load(Ordering::Acquire) > 0
169        {
170            return None;
171        }
172        Some(handle.clone())
173    }
174
175    /// Go `addCallbackCleanupHandle`: runs `cleanup` when the context closes; `None`
176    /// (without running it) when the context is not open.
177    pub fn add_cleanup(&self, id: &str, cleanup: Cleanup) -> Option<u64> {
178        let handle = self.next_cleanup.fetch_add(1, Ordering::SeqCst) + 1;
179        let mut contexts = lock(&self.contexts);
180        let ctx = contexts.get_mut(id.trim())?;
181        ctx.cleanups.push((handle, cleanup));
182        Some(handle)
183    }
184
185    /// Drops a cleanup without running it.
186    pub fn remove_cleanup(&self, id: &str, handle: u64) {
187        if let Some(ctx) = lock(&self.contexts).get_mut(id.trim()) {
188            ctx.cleanups.retain(|(h, _)| *h != handle);
189        }
190    }
191
192    /// Go `callbackContextRegistry.lookup`.
193    pub fn lookup(&self, id: &str) -> Option<(String, Option<Arc<CallbackInstance>>, RequestScope)> {
194        let id = id.trim();
195        if id.is_empty() {
196            return None;
197        }
198        lock(&self.contexts)
199            .get(id)
200            .map(|c| (c.plugin_id.clone(), c.instance.clone(), c.scope.clone()))
201    }
202
203    /// Go `closeHostHTTPCallbackInstance`: rejects further callbacks from an instance
204    /// and ends its HTTP operations and streams.
205    pub fn close_instance(&self, plugin_id: &str, instance: &Arc<CallbackInstance>) {
206        instance.close();
207        if let Some(inner) = self.host.upgrade() {
208            self.http.close_instance(&Host::from_inner(inner), plugin_id, instance);
209        }
210    }
211
212    /// Go `closeHostHTTPPluginResources` for one plugin.
213    pub fn close_plugin(&self, plugin_id: &str) {
214        if let Some(inner) = self.host.upgrade() {
215            self.http.close_plugin(&Host::from_inner(inner), plugin_id);
216        }
217    }
218
219    pub fn close_all(&self) {
220        if let Some(inner) = self.host.upgrade() {
221            self.http.close_all(&Host::from_inner(inner));
222        }
223    }
224}
225
226/// The [`CallbackHandler`] plugins call into.
227pub struct Dispatch {
228    host: Weak<Inner>,
229}
230
231impl CallbackHandler for Dispatch {
232    fn call_from_plugin(
233        &self,
234        plugin_id: &str,
235        instance: &Arc<CallbackInstance>,
236        method: &str,
237        request: Bytes,
238    ) -> Result<Bytes, CallbackError> {
239        if instance.is_closed() {
240            return Err(CallbackError::new("host plugin callback instance is closed"));
241        }
242        let Some(inner) = self.host.upgrade() else {
243            return Err(CallbackError::new("host plugin callback instance is closed"));
244        };
245        let host = Host::from_inner(inner);
246        let caller = Caller {
247            plugin_id: plugin_id.to_owned(),
248            instance: instance.clone(),
249        };
250        host.call_from_plugin(&caller, method, &request)
251    }
252}
253
254/// The plugin instance making a callback.
255#[derive(Clone)]
256pub struct Caller {
257    pub plugin_id: String,
258    pub instance: Arc<CallbackInstance>,
259}
260
261go_struct! {
262    pub struct HostLogRequest("pluginhost.rpcHostLogRequest") {
263        "host_callback_id" omitempty => host_callback_id: String,
264        "level" omitempty => level: String,
265        "message" omitempty => message: String,
266        "fields" omitempty => fields: Metadata,
267    }
268}
269
270go_struct! {
271    pub struct StreamEmitRequest("pluginhost.rpcStreamEmitRequest") {
272        "stream_id" => stream_id: String,
273        "payload" omitempty => payload: Bytes,
274        "error" omitempty => error: String,
275    }
276}
277
278go_struct! {
279    pub struct StreamCloseRequest("pluginhost.rpcStreamCloseRequest") {
280        "stream_id" => stream_id: String,
281        "error" omitempty => error: String,
282    }
283}
284
285fn decode<T: gojson::GoJson>(what: &str, raw: &[u8]) -> Result<T, CallbackError> {
286    gojson::from_slice(raw).map_err(|e| CallbackError::new(format!("decode {what}: {e}")))
287}
288
289fn ok_empty() -> Result<Bytes, CallbackError> {
290    Ok(abi::ok_envelope(&crate::rpc::Empty {}))
291}
292
293impl Host {
294    /// Go `callFromPlugin`.
295    pub(crate) fn call_from_plugin(
296        &self,
297        caller: &Caller,
298        method: &str,
299        request: &[u8],
300    ) -> Result<Bytes, CallbackError> {
301        match method {
302            method::HOST_LOG => self.host_log(request),
303            method::HOST_STREAM_EMIT => {
304                let req: StreamEmitRequest = decode("stream emit request", request)?;
305                let chunk = Chunk {
306                    payload: req.payload,
307                    error: (!req.error.is_empty()).then_some(req.error),
308                };
309                self.inner
310                    .callbacks
311                    .streams
312                    .emit(&req.stream_id, chunk)
313                    .map_err(CallbackError::new)?;
314                ok_empty()
315            }
316            method::HOST_STREAM_CLOSE => {
317                let req: StreamCloseRequest = decode("stream close request", request)?;
318                self.inner.callbacks.streams.close(&req.stream_id, &req.error);
319                ok_empty()
320            }
321            other => self.call_service(caller, other, request),
322        }
323    }
324
325    /// Go `callHostLog`.
326    fn host_log(&self, request: &[u8]) -> Result<Bytes, CallbackError> {
327        let req: HostLogRequest = decode("host log request", request)?;
328        let message = match req.message.trim() {
329            "" => "plugin log",
330            m => m,
331        };
332        let mut fields: serde_json::Map<String, serde_json::Value> = req
333            .fields
334            .into_iter()
335            .filter_map(|(k, v)| (!k.trim().is_empty()).then(|| (k.trim().to_owned(), v)))
336            .collect();
337        if let Some((_, _, scope)) = self.inner.callbacks.lookup(&req.host_callback_id)
338            && !scope.request_id.is_empty()
339        {
340            fields.insert("request_id".into(), scope.request_id.into());
341        }
342        let fields = serde_json::Value::Object(fields).to_string();
343        match req.level.trim().to_ascii_lowercase().as_str() {
344            "trace" => tracing::trace!(fields = %fields, "{message}"),
345            "info" => tracing::info!(fields = %fields, "{message}"),
346            "warn" | "warning" => tracing::warn!(fields = %fields, "{message}"),
347            "error" => tracing::error!(fields = %fields, "{message}"),
348            _ => tracing::debug!(fields = %fields, "{message}"),
349        }
350        ok_empty()
351    }
352
353    fn call_service(&self, caller: &Caller, method: &str, request: &[u8]) -> Result<Bytes, CallbackError> {
354        match method {
355            method::HOST_HTTP_DO => self.host_http_do(caller, request),
356            method::HOST_HTTP_DO_STREAM => self.host_http_do_stream(caller, request),
357            method::HOST_HTTP_OPERATION_OPEN => self.host_http_operation_open(caller, request),
358            method::HOST_HTTP_CANCEL => self.host_http_cancel(caller, request),
359            method::HOST_HTTP_STREAM_READ => self.host_http_stream_read(caller, request),
360            method::HOST_HTTP_STREAM_CLOSE => self.host_http_stream_close(caller, request),
361            method::HOST_MODEL_EXECUTE => self.host_model_execute(caller, request, false),
362            method::HOST_MODEL_EXECUTE_STREAM => self.host_model_execute(caller, request, true),
363            method::HOST_MODEL_STREAM_READ => self.host_model_stream_read(request),
364            method::HOST_MODEL_STREAM_CLOSE => self.host_model_stream_close(request),
365            method::HOST_AUTH_LIST => self.host_auth_list(request),
366            method::HOST_AUTH_GET => self.host_auth_get(request),
367            method::HOST_AUTH_GET_RUNTIME => self.host_auth_get_runtime(request),
368            method::HOST_AUTH_SAVE => self.host_auth_save(caller, request),
369            method::HOST_AFFINITY_LOOKUP => self.host_affinity_lookup(request),
370            _ => Err(CallbackError::new(format!("unsupported host callback {method}"))),
371        }
372    }
373}