Skip to main content

cpa_plugin/
executor.rs

1//! Plugin executors at the RPC level (internal/pluginhost/adapters_executors.go,
2//! rpc_client_stream.go, executor_route.go): format negotiation, the executor's provider,
3//! and `executor.execute` / `execute_stream` / `count_tokens` / `http_request`.
4//! Translation around the call, usage reporting and dispatch live in the server.
5
6use bytes::Bytes;
7use cpa_core::format::Format;
8use cpa_core::gostr::GoStr;
9use futures_util::stream::BoxStream;
10
11use crate::abi::method;
12use crate::api::{ExecutorHttpRequest, ExecutorHttpResponse, ExecutorRequest, ExecutorResponse, ExecutorStreamChunk};
13use crate::callbacks::{ContextGuard, RequestScope};
14use crate::gojson::{GoStruct, Header, ObjWriter};
15use crate::host::{Host, Record, normalize_provider};
16use crate::rpc::{self, CallError};
17use crate::streams::{Chunk, Reader};
18
19/// Go `normalizeExecutorFormatName`: aliases map to translator formats; anything else
20/// is kept as written (trimmed); empty and `none` mean no format.
21pub fn normalize_format(raw: &str) -> String {
22    match raw.trim().go_lower().as_str() {
23        "" | "none" => String::new(),
24        "chat-completions" | "chat_completions" | "openai-chat-completions" | "openai_chat_completions" => {
25            "openai".into()
26        }
27        "responses" | "openai-responses" | "openai_responses" => "openai-response".into(),
28        "anthropic" => "claude".into(),
29        _ => raw.trim().to_owned(),
30    }
31}
32
33/// Go `normalizeExecutorFormats`: normalized, de-duplicated, empty dropped.
34pub fn normalize_formats(raw: &[String]) -> Vec<String> {
35    let mut out: Vec<String> = Vec::new();
36    for format in raw.iter().map(|f| normalize_format(f)) {
37        if !format.is_empty() && !out.contains(&format) {
38            out.push(format);
39        }
40    }
41    out
42}
43
44/// Go `sdktranslator.HasRequestTransformer` / `HasResponseTransformer`: a registered
45/// pair between two named formats.
46pub fn translator_pair_exists(client: &str, upstream: &str) -> bool {
47    match (Format::parse(client), Format::parse(upstream)) {
48        (Some(c), Some(u)) => cpa_translate::pair(c, u).is_some(),
49        _ => false,
50    }
51}
52
53/// One plugin executor (Go `executorAdapter`).
54#[derive(Debug, Clone)]
55pub struct Adapter {
56    pub record: Record,
57    pub provider: String,
58    pub inputs: Vec<String>,
59    pub outputs: Vec<String>,
60}
61
62/// Formats chosen for one call (Go `preparedExecutorCall`).
63#[derive(Debug, Clone, PartialEq, Eq)]
64pub struct Negotiated {
65    /// The format the request arrives in.
66    pub input_requested: String,
67    /// The format the client wants back.
68    pub requested: String,
69    /// The format the plugin receives.
70    pub input: String,
71    /// The format the plugin answers in (`ExecutorRequest.Format`).
72    pub output: String,
73}
74
75impl Adapter {
76    /// Go `selectExecutorInputFormat`.
77    pub fn select_input(&self, requested: &str) -> Result<String, String> {
78        if self.inputs.is_empty() {
79            return Err(format!("plugin executor {} declares no input formats", self.provider));
80        }
81        if self.inputs.iter().any(|f| f == requested) {
82            return Ok(requested.to_owned());
83        }
84        self.inputs
85            .iter()
86            .find(|f| requested.is_empty() || translator_pair_exists(requested, f))
87            .cloned()
88            .ok_or_else(|| {
89                format!(
90                    "plugin executor {} does not support input format {requested:?}",
91                    self.provider
92                )
93            })
94    }
95
96    /// Go `selectExecutorOutputFormat`. `plugin_response_translator` is whether any
97    /// plugin offers response translation (Go `hasResponseTranslator`).
98    pub fn select_output(
99        &self,
100        requested: &str,
101        input: &str,
102        plugin_response_translator: bool,
103    ) -> Result<String, String> {
104        if self.outputs.is_empty() {
105            return Err(format!("plugin executor {} declares no output formats", self.provider));
106        }
107        let available = |from: &str, to: &str| {
108            from.is_empty()
109                || to.is_empty()
110                || from == to
111                || translator_pair_exists(to, from)
112                || plugin_response_translator
113        };
114        if self.outputs.iter().any(|f| f == requested) {
115            return Ok(requested.to_owned());
116        }
117        if self.outputs.iter().any(|f| f == input) && available(input, requested) {
118            return Ok(input.to_owned());
119        }
120        self.outputs
121            .iter()
122            .find(|f| requested.is_empty() || available(f, requested))
123            .cloned()
124            .ok_or_else(|| {
125                format!(
126                    "plugin executor {} does not support output format {requested:?}",
127                    self.provider
128                )
129            })
130    }
131
132    /// Go `prepareExecutorCall` without the translation itself. `source` and `response`
133    /// are the request's source and response formats (empty when unset).
134    pub fn negotiate(
135        &self,
136        source: &str,
137        response: &str,
138        plugin_response_translator: bool,
139    ) -> Result<Negotiated, String> {
140        let input_requested = if source.is_empty() {
141            "openai".to_owned()
142        } else {
143            normalize_format(source)
144        };
145        let requested_raw = if response.is_empty() { source } else { response };
146        let requested = if requested_raw.is_empty() {
147            "openai".to_owned()
148        } else {
149            normalize_format(requested_raw)
150        };
151        let input = self.select_input(&input_requested)?;
152        let output = self.select_output(&requested, &input, plugin_response_translator)?;
153        Ok(Negotiated {
154            input_requested,
155            requested,
156            input,
157            output,
158        })
159    }
160}
161
162/// A plugin executor's stream: headers, then chunks until the plugin closes it. Dropping
163/// it releases the stream and its callback context.
164pub struct PluginStream {
165    pub headers: Header,
166    pub chunks: BoxStream<'static, Chunk>,
167}
168
169crate::go_struct! {
170    /// `rpcExecutorStreamResponse`.
171    pub struct StreamResponse("pluginhost.rpcExecutorStreamResponse") {
172        "headers" omitempty => headers: Header,
173        "chunks" omitempty => chunks: Vec<ExecutorStreamChunk>,
174    }
175}
176
177impl Host {
178    /// Go `executorProvider`: the provider the plugin registered models for, else its
179    /// `executor.identifier`, lowercased.
180    pub async fn executor_provider(&self, record: &Record) -> Option<String> {
181        if !self.record_current(record) {
182            return None;
183        }
184        let registered = self
185            .state()
186            .model_providers
187            .get(&record.id)
188            .cloned()
189            .unwrap_or_default();
190        let provider = if registered.is_empty() {
191            rpc::identifier(&record.client, method::EXECUTOR_IDENTIFIER).await
192        } else {
193            registered
194        };
195        let provider = normalize_provider(&provider);
196        (!provider.is_empty()).then_some(provider)
197    }
198
199    /// Go `executorAdapterForPlugin`.
200    pub async fn executor_adapter(&self, plugin_id: &str) -> Result<Adapter, String> {
201        let plugin_id = plugin_id.trim();
202        if plugin_id.is_empty() {
203            return Err("target executor plugin id is required".into());
204        }
205        let Some(record) = self.active_records().into_iter().find(|r| r.id == plugin_id) else {
206            return Err(format!("plugin executor {plugin_id} not found"));
207        };
208        if self.is_fused(&record.id) {
209            return Err(format!("plugin executor {plugin_id} is unavailable"));
210        }
211        if !record.plugin.caps.executor {
212            return Err(format!("plugin {plugin_id} does not declare an executor"));
213        }
214        let Some(provider) = self.executor_provider(&record).await else {
215            return Err(format!("plugin executor {plugin_id} has no provider identifier"));
216        };
217        Ok(self.adapter_for(record, provider))
218    }
219
220    pub(crate) fn adapter_for(&self, record: Record, provider: String) -> Adapter {
221        Adapter {
222            inputs: normalize_formats(&record.plugin.caps.executor_input_formats),
223            outputs: normalize_formats(&record.plugin.caps.executor_output_formats),
224            record,
225            provider,
226        }
227    }
228
229    /// Go `executorPluginReady`: an active, unfused executor plugin that serves static
230    /// models and can take a request in `source_format`.
231    pub async fn executor_plugin_ready(&self, plugin_id: &str, source_format: &str) -> bool {
232        let plugin_id = plugin_id.trim();
233        let Some(record) = self
234            .active_records()
235            .into_iter()
236            .find(|r| r.id == plugin_id && !self.is_fused(&r.id))
237        else {
238            return false;
239        };
240        if !record.plugin.caps.executor || !record.plugin.allows_static_models() {
241            return false;
242        }
243        let Some(provider) = self.executor_provider(&record).await else {
244            return false;
245        };
246        let adapter = self.adapter_for(record, provider);
247        adapter
248            .negotiate(source_format, source_format, self.has_response_translator())
249            .is_ok()
250    }
251
252    fn adapter_usable(&self, adapter: &Adapter) -> Result<(), CallError> {
253        if self.is_fused(&adapter.record.id) || !self.record_current(&adapter.record) {
254            return Err(CallError::Other(format!(
255                "plugin executor {} is unavailable",
256                adapter.provider
257            )));
258        }
259        Ok(())
260    }
261
262    /// `executor.execute` with a callback context.
263    pub async fn executor_execute(
264        &self,
265        adapter: &Adapter,
266        req: &ExecutorRequest,
267        scope: &RequestScope,
268    ) -> Result<ExecutorResponse, CallError> {
269        self.adapter_usable(adapter)?;
270        self.call_with_callback(&adapter.record, method::EXECUTOR_EXECUTE, req, scope)
271            .await
272    }
273
274    /// `executor.count_tokens` with a callback context.
275    pub async fn executor_count_tokens(
276        &self,
277        adapter: &Adapter,
278        req: &ExecutorRequest,
279        scope: &RequestScope,
280    ) -> Result<ExecutorResponse, CallError> {
281        self.adapter_usable(adapter)?;
282        self.call_with_callback(&adapter.record, method::EXECUTOR_COUNT_TOKENS, req, scope)
283            .await
284    }
285
286    /// `executor.http_request` with a callback context.
287    pub async fn executor_http_request(
288        &self,
289        adapter: &Adapter,
290        req: &ExecutorHttpRequest,
291        scope: &RequestScope,
292    ) -> Result<ExecutorHttpResponse, CallError> {
293        self.adapter_usable(adapter)?;
294        self.call_with_callback(&adapter.record, method::EXECUTOR_HTTP_REQUEST, req, scope)
295            .await
296    }
297
298    /// Go `rpcPluginAdapter.ExecuteStream`: opens a host stream and a callback context,
299    /// sends `stream_id` and `host_callback_id`. Inline chunks in the answer are the whole
300    /// stream; otherwise chunks arrive through `host.stream.emit` until the plugin closes
301    /// the stream, and the callback context stays open until then.
302    pub async fn executor_execute_stream(
303        &self,
304        adapter: &Adapter,
305        req: &ExecutorRequest,
306        scope: &RequestScope,
307    ) -> Result<PluginStream, CallError> {
308        self.adapter_usable(adapter)?;
309        let reader = self.inner.callbacks.streams.open();
310        let guard = self.open_callback(&adapter.record, scope);
311        let mut raw = Vec::new();
312        let mut w = ObjWriter::begin(&mut raw);
313        w.embed(req);
314        w.field("stream_id", &reader.id().to_owned(), true);
315        w.field("host_callback_id", &guard.id().to_owned(), true);
316        w.end();
317        let resp: StreamResponse = self
318            .call_raw(&adapter.record, method::EXECUTOR_EXECUTE_STREAM, raw)
319            .await?;
320        if !resp.chunks.is_empty() {
321            drop((reader, guard));
322            let chunks: Vec<Chunk> = resp.chunks.into_iter().map(|c| Chunk::data(c.payload)).collect();
323            return Ok(PluginStream {
324                headers: resp.headers,
325                chunks: Box::pin(futures_util::stream::iter(chunks)),
326            });
327        }
328        Ok(PluginStream {
329            headers: resp.headers,
330            chunks: bridged(reader, guard),
331        })
332    }
333}
334
335/// Chunks from the bridge; the reader and callback context drop with the stream.
336fn bridged(reader: Reader, guard: ContextGuard) -> BoxStream<'static, Chunk> {
337    Box::pin(futures_util::stream::unfold(
338        (reader, guard),
339        |(reader, guard)| async move {
340            let chunk = reader.next().await?;
341            Some((chunk, (reader, guard)))
342        },
343    ))
344}
345
346/// Request bytes an executor plugin receives, for tests and logs.
347pub fn encode_request(req: &ExecutorRequest) -> Bytes {
348    let mut out = Vec::new();
349    let mut w = ObjWriter::begin(&mut out);
350    req.encode_fields(&mut w);
351    w.end();
352    Bytes::from(out)
353}
354
355#[cfg(test)]
356mod tests {
357    use super::*;
358
359    fn adapter(inputs: &[&str], outputs: &[&str]) -> Adapter {
360        let mut record_plugin = crate::rpc::Plugin::default();
361        record_plugin.caps.executor_input_formats = inputs.iter().map(|s| s.to_string()).collect();
362        record_plugin.caps.executor_output_formats = outputs.iter().map(|s| s.to_string()).collect();
363        Adapter {
364            inputs: normalize_formats(&record_plugin.caps.executor_input_formats),
365            outputs: normalize_formats(&record_plugin.caps.executor_output_formats),
366            provider: "p".into(),
367            record: crate::host::Record {
368                id: "x".into(),
369                path: Default::default(),
370                version: String::new(),
371                priority: 0,
372                plugin: record_plugin,
373                client: crate::client::GuardedClient::new(std::sync::Arc::new(Never), Default::default()),
374            },
375        }
376    }
377
378    struct Never;
379    impl crate::client::PluginClient for Never {
380        fn call(&self, _: &str, _: &[u8]) -> Result<Bytes, String> {
381            Err("unused".into())
382        }
383        fn shutdown(&self) {}
384    }
385
386    /// Go `selectExecutorInputFormat` / `selectExecutorOutputFormat`.
387    #[test]
388    fn negotiation_follows_go() {
389        assert_eq!(
390            normalize_formats(&[
391                "Chat-Completions".into(),
392                "openai".into(),
393                "none".into(),
394                " Custom ".into()
395            ]),
396            ["openai", "Custom"]
397        );
398        let a = adapter(&["chat-completions"], &["chat-completions"]);
399        let n = a.negotiate("claude", "", false).unwrap();
400        assert_eq!(
401            (n.input.as_str(), n.output.as_str()),
402            ("openai", "openai"),
403            "claude->openai request and openai->claude response pairs exist"
404        );
405        assert!(
406            a.negotiate("custom", "", false).is_err(),
407            "no translator from an unknown format"
408        );
409        let n = a.negotiate("", "", false).unwrap();
410        assert_eq!(n.requested, "openai");
411        let b = adapter(&["anthropic"], &["responses"]);
412        let n = b.negotiate("openai-response", "openai-response", false).unwrap();
413        assert_eq!((n.input.as_str(), n.output.as_str()), ("claude", "openai-response"));
414        assert_eq!(
415            adapter(&[], &["openai"]).select_input("openai"),
416            Err("plugin executor p declares no input formats".into())
417        );
418        // An unregistered response pair is still available when a plugin translates.
419        let c = adapter(&["openai"], &["custom"]);
420        assert!(c.negotiate("openai", "", false).is_err());
421        assert_eq!(c.negotiate("openai", "", true).unwrap().output, "custom");
422    }
423}