Skip to main content

cpa_plugin/
routing.rs

1//! Scheduler and model router capabilities (internal/pluginhost/scheduler.go,
2//! model_router.go, executor_route.go).
3
4use crate::abi::method;
5use crate::api::{
6    ModelRouteRequest, ModelRouteResponse, ROUTE_TARGET_EXECUTOR, ROUTE_TARGET_PROVIDER, ROUTE_TARGET_SELF,
7    SCHEDULER_BUILTIN_FILL_FIRST, SCHEDULER_BUILTIN_ROUND_ROBIN, SchedulerPickRequest, SchedulerPickResponse,
8};
9use crate::callbacks::RequestScope;
10use crate::host::{Host, Record};
11use crate::rpc::CallError;
12
13impl Host {
14    /// Go `schedulerRecord`: the highest-priority active scheduler.
15    fn scheduler_record(&self) -> Option<Record> {
16        self.active_records()
17            .into_iter()
18            .find(|r| r.plugin.caps.scheduler && !self.is_fused(&r.id))
19    }
20
21    /// Go `HasScheduler`.
22    pub fn has_scheduler(&self) -> bool {
23        self.scheduler_record().is_some()
24    }
25
26    /// Go `SchedulerWantsAcrossPriorities`.
27    pub fn scheduler_wants_across_priorities(&self) -> bool {
28        self.scheduler_record()
29            .is_some_and(|r| r.plugin.caps.scheduler_across_priorities)
30    }
31
32    /// Go `PickAuth`: `Ok(None)` lets the built-in scheduler choose (no scheduler, not
33    /// handled, or an invalid answer); `Err` is the plugin's RPC failure, which Go
34    /// surfaces as a selection error.
35    pub async fn pick_auth(&self, mut req: SchedulerPickRequest) -> Result<Option<SchedulerPickResponse>, CallError> {
36        let Some(record) = self.scheduler_record() else {
37            return Ok(None);
38        };
39        if !self.record_current(&record) {
40            return Ok(None);
41        }
42        req.plugin = record.plugin.metadata.clone();
43        let resp: SchedulerPickResponse = match self.call(&record, method::SCHEDULER_PICK, &req).await {
44            Ok(resp) => resp,
45            Err(CallError::Panic(_)) => return Ok(None),
46            Err(e) => {
47                tracing::warn!(plugin_id = %record.id, "pluginhost: scheduler rejected auth pick: {e}");
48                return Err(e);
49            }
50        };
51        if !resp.handled {
52            return Ok(None);
53        }
54        match normalize_scheduler_response(resp, &req) {
55            Ok(resp) => Ok(Some(resp)),
56            Err(reason) => {
57                tracing::warn!(plugin_id = %record.id, "pluginhost: scheduler returned invalid response: {reason}");
58                Ok(None)
59            }
60        }
61    }
62
63    /// Go `HasModelRouters[Except]`.
64    pub fn has_model_routers(&self, skip: &str) -> bool {
65        let skip = skip.trim();
66        self.active_records()
67            .iter()
68            .any(|r| r.plugin.caps.model_router && !self.is_fused(&r.id) && r.id != skip)
69    }
70
71    /// Go `RouteModel[Except]`: the first router (by priority) that handles the request
72    /// with a usable target. `available_providers` is the providers that currently have
73    /// credentials (Go `AuthManager.AvailableProviders`); a provider target must be one
74    /// of them. `executor_ready` reports whether a plugin executor can take the request
75    /// (format negotiation, see [`crate::executor`]).
76    pub async fn route_model(
77        &self,
78        mut req: ModelRouteRequest,
79        skip: &str,
80        available_providers: &[String],
81        scope: &RequestScope,
82    ) -> Option<ModelRouteResponse> {
83        let skip = skip.trim();
84        req.available_providers = available_providers.to_vec();
85        for record in self.active_records() {
86            if !record.plugin.caps.model_router || self.is_fused(&record.id) || record.id == skip {
87                continue;
88            }
89            let mut next = req.clone();
90            next.plugin = record.plugin.metadata.clone();
91            next.plugin_id = record.id.clone();
92            let resp: ModelRouteResponse = match self
93                .call_with_callback(&record, method::MODEL_ROUTE, &next, scope)
94                .await
95            {
96                Ok(resp) => resp,
97                Err(e) => {
98                    tracing::warn!(plugin_id = %record.id, "pluginhost: model router failed: {e}");
99                    continue;
100                }
101            };
102            if !resp.handled {
103                continue;
104            }
105            let Some(resp) = normalize_route_response(&record.id, resp.clone()) else {
106                tracing::warn!(plugin_id = %record.id, target_kind = %resp.target_kind, target = %resp.target, "pluginhost: model router returned invalid target");
107                continue;
108            };
109            match resp.target_kind.as_str() {
110                ROUTE_TARGET_PROVIDER => {
111                    if !available_providers.iter().any(|p| p == &resp.target) {
112                        tracing::warn!(plugin_id = %record.id, target_provider = %resp.target, "pluginhost: model router returned unavailable provider");
113                        continue;
114                    }
115                    return Some(resp);
116                }
117                _ => {
118                    if !self.executor_plugin_ready(&resp.target, &next.source_format).await {
119                        tracing::warn!(plugin_id = %record.id, target_plugin_id = %resp.target, "pluginhost: model router returned unavailable executor plugin");
120                        continue;
121                    }
122                    return Some(resp);
123                }
124            }
125        }
126        None
127    }
128}
129
130/// Go `normalizeSchedulerResponse`.
131pub fn normalize_scheduler_response(
132    mut resp: SchedulerPickResponse,
133    req: &SchedulerPickRequest,
134) -> Result<SchedulerPickResponse, &'static str> {
135    resp.auth_id = resp.auth_id.trim().to_owned();
136    resp.delegate_builtin = resp.delegate_builtin.trim().to_owned();
137    resp.reject_code = resp.reject_code.trim().to_owned();
138    resp.reject_reason = resp.reject_reason.trim().to_owned();
139    if resp.reject {
140        if resp.reject_code.is_empty() {
141            resp.reject_code = "auth_unavailable".into();
142        }
143        if resp.reject_reason.is_empty() {
144            resp.reject_reason = "scheduler rejected candidate selection".into();
145        }
146        return Ok(resp);
147    }
148    match (resp.auth_id.is_empty(), resp.delegate_builtin.is_empty()) {
149        (true, true) => Err("missing auth id or delegate"),
150        (false, _) => {
151            if req.candidates.iter().any(|c| c.id.trim() == resp.auth_id) {
152                Ok(resp)
153            } else {
154                Err("unknown auth id")
155            }
156        }
157        (true, false) => {
158            if matches!(
159                resp.delegate_builtin.as_str(),
160                SCHEDULER_BUILTIN_ROUND_ROBIN | SCHEDULER_BUILTIN_FILL_FIRST
161            ) {
162                Ok(resp)
163            } else {
164                Err("unknown delegate")
165            }
166        }
167    }
168}
169
170/// Go `normalizeModelRouteResponse`.
171pub fn normalize_route_response(router_id: &str, mut resp: ModelRouteResponse) -> Option<ModelRouteResponse> {
172    resp.target_model = resp.target_model.trim().to_owned();
173    resp.target = match resp.target_kind.as_str() {
174        ROUTE_TARGET_SELF => router_id.trim().to_owned(),
175        ROUTE_TARGET_EXECUTOR => resp.target.trim().to_owned(),
176        ROUTE_TARGET_PROVIDER => crate::host::normalize_provider(&resp.target),
177        _ => return None,
178    };
179    (!resp.target.is_empty()).then_some(resp)
180}
181
182#[cfg(test)]
183mod tests {
184    use super::*;
185    use crate::api::SchedulerAuthCandidate;
186
187    #[test]
188    fn scheduler_answers_are_validated_like_go() {
189        let req = SchedulerPickRequest {
190            candidates: vec![SchedulerAuthCandidate {
191                id: " a ".into(),
192                ..Default::default()
193            }],
194            ..Default::default()
195        };
196        let pick = |r: SchedulerPickResponse| normalize_scheduler_response(r, &req);
197        let base = SchedulerPickResponse {
198            handled: true,
199            ..Default::default()
200        };
201        assert_eq!(
202            pick(SchedulerPickResponse {
203                auth_id: " a".into(),
204                ..base.clone()
205            })
206            .unwrap()
207            .auth_id,
208            "a"
209        );
210        assert_eq!(
211            pick(SchedulerPickResponse {
212                auth_id: "b".into(),
213                ..base.clone()
214            }),
215            Err("unknown auth id")
216        );
217        assert_eq!(
218            pick(SchedulerPickResponse {
219                delegate_builtin: "random".into(),
220                ..base.clone()
221            }),
222            Err("unknown delegate")
223        );
224        let rejected = pick(SchedulerPickResponse {
225            reject: true,
226            ..base.clone()
227        })
228        .unwrap();
229        assert_eq!(rejected.reject_code, "auth_unavailable");
230        assert_eq!(rejected.reject_reason, "scheduler rejected candidate selection");
231        assert_eq!(pick(base), Err("missing auth id or delegate"));
232    }
233
234    #[test]
235    fn route_targets_normalize_like_go() {
236        let resp = |kind: &str, target: &str| ModelRouteResponse {
237            handled: true,
238            target_kind: kind.into(),
239            target: target.into(),
240            target_model: " m ".into(),
241            ..Default::default()
242        };
243        let own = normalize_route_response("router", resp("self", "ignored")).unwrap();
244        assert_eq!((own.target.as_str(), own.target_model.as_str()), ("router", "m"));
245        assert_eq!(
246            normalize_route_response("r", resp("provider", " Claude "))
247                .unwrap()
248                .target,
249            "claude"
250        );
251        // A provider target names the key core registers: Go lowercases both with
252        // strings.ToLower, so U+0130 becomes a plain `i` on each side.
253        assert_eq!(
254            normalize_route_response("r", resp("provider", "openai-compatible-HİGH"))
255                .unwrap()
256                .target,
257            cpa_core::config::credentials::openai_compat_provider("HİGH")
258        );
259        assert!(normalize_route_response("r", resp("executor", " ")).is_none());
260        assert!(normalize_route_response("r", resp("other", "x")).is_none());
261    }
262}