Skip to main content

cpa_server/
plugins.rs

1//! The plugin host in the server (Go `sdk/cliproxy/service_plugins.go`,
2//! `internal/api/server_management.go`): one [`cpa_plugin::Host`] per runtime, synced
3//! with every published config by a single worker so the latest config always wins.
4
5use std::collections::{HashMap, HashSet};
6use std::sync::{Arc, RwLock, Weak};
7
8use axum::body::{Body, Bytes};
9use axum::extract::Request;
10use axum::http::HeaderMap;
11use cpa_common::gostr::GoStr;
12use cpa_core::config::Config;
13use cpa_core::exec::Caller;
14use tokio::sync::watch;
15
16use crate::Runtime;
17
18pub(crate) mod execution;
19pub(crate) mod interceptors;
20pub(crate) mod model_callbacks;
21pub(crate) mod refresh;
22
23/// The host plus the config it should converge on.
24pub struct PluginRuntime {
25    host: cpa_plugin::Host,
26    /// The latest published config and its publish sequence number.
27    latest: watch::Sender<Option<(u64, Arc<Config>)>>,
28    /// The sequence number of the last config the worker applied.
29    applied: watch::Sender<u64>,
30    access: RwLock<Arc<AccessRegistry>>,
31    /// Go's executor table entries owned by plugins: provider to the registered executor.
32    executors: RwLock<HashMap<String, cpa_plugin::executor::Adapter>>,
33}
34
35impl Default for PluginRuntime {
36    fn default() -> Self {
37        Self::with_host(cpa_plugin::Host::new())
38    }
39}
40
41impl PluginRuntime {
42    /// Wraps a host that is already running (the binary's, which loaded plugins for
43    /// their command-line flags before the config was read).
44    pub(crate) fn with_host(host: cpa_plugin::Host) -> Self {
45        Self {
46            host,
47            latest: watch::Sender::new(None),
48            applied: watch::Sender::new(0),
49            access: RwLock::default(),
50            executors: RwLock::default(),
51        }
52    }
53
54    pub fn host(&self) -> &cpa_plugin::Host {
55        &self.host
56    }
57
58    /// The registered plugin executor serving `credential`, if any. Go binds a
59    /// credential's executor as the credential arrives (`registerExecutorForAuth`): a
60    /// credential [`binds_native`] replaces a plugin executor registered for its
61    /// provider at once, while the table here changes only on a plugin sync. So the
62    /// table is consulted only for credentials that would leave a plugin executor bound.
63    pub(crate) fn executor(
64        &self,
65        credential: &cpa_core::credential::Credential,
66        cfg: &Config,
67    ) -> Option<cpa_plugin::executor::Adapter> {
68        let adapter = {
69            let executors = self.executors.read().unwrap_or_else(std::sync::PoisonError::into_inner);
70            executors.get(&credential.provider.trim().go_lower()).cloned()?
71        };
72        let compat_names = cpa_core::config::credentials::openai_compat_names(cfg);
73        (!binds_native(credential, &compat_names)).then_some(adapter)
74    }
75
76    /// Whether a plugin executor is registered for `provider`.
77    pub(crate) fn has_executor(&self, provider: &str) -> bool {
78        let executors = self.executors.read().unwrap_or_else(std::sync::PoisonError::into_inner);
79        executors.contains_key(&provider.trim().go_lower())
80    }
81
82    /// Records a published config; the worker started by [`start`] applies it.
83    pub(crate) fn config_published(&self, cfg: Arc<Config>) {
84        self.latest.send_modify(|latest| {
85            let seq = latest.as_ref().map_or(1, |(seq, _)| seq + 1);
86            *latest = Some((seq, cfg));
87        });
88    }
89
90    fn published_seq(&self) -> u64 {
91        self.latest.borrow().as_ref().map_or(0, |(seq, _)| *seq)
92    }
93}
94
95/// Waits until the plugin worker started by [`start`] has applied every config published
96/// so far (Go applies plugin config synchronously while it applies a config).
97pub async fn applied(rt: &Runtime) {
98    let seq = rt.plugin_runtime().published_seq();
99    let _ = rt
100        .plugin_runtime()
101        .applied
102        .subscribe()
103        .wait_for(|applied| *applied >= seq)
104        .await;
105}
106
107/// Go's startup and reload sequence (`syncPluginRuntimeConfigForConfig` and
108/// `RefreshPluginManagementRoutes`): apply the config, register the client-key and
109/// plugin frontend auth providers, then rebuild the plugin management routes around the
110/// built-in ones, then register plugin models and executors (`syncPluginModelRuntime`).
111/// Go runs that last step only once its listener is up; here it completes before
112/// serving.
113pub async fn sync(rt: &Runtime, cfg: Arc<Config>) {
114    let host = rt.plugins();
115    host.apply_config(cfg.clone()).await;
116    // Go `configaccess.Register` (reload: `ApplyAccessProviders`) runs before the plugin
117    // providers register.
118    let (providers, exclusive) = host.frontend_auth_providers().await;
119    rt.plugin_runtime()
120        .register_access(!cfg.api_keys.is_empty(), providers, exclusive);
121    host.register_management_routes(&reserved_management_routes()).await;
122    // Go `sdktranslator.SetPluginHooks(s.pluginHost)`: the hooks are skipped while no
123    // plugin offers one.
124    cpa_translate::hooks::set_plugin_hooks(Some(host.translator_hooks()));
125    // Go `registerPluginAuthParser`: auth files go to plugin auth providers first; the
126    // next auth-folder reload picks up what a newly loaded plugin parses.
127    cpa_core::config::credentials::set_plugin_auth_parser(Some(host.auth_parser()));
128    sync_models(rt).await;
129}
130
131/// Go loads plugins while it builds the service, so its first auth-folder load already
132/// asks plugin auth providers (sdk/cliproxy/builder.go `ApplyConfig`, then
133/// `coreManager.Load` in `Service.Run`). Credentials load before plugins start here, so
134/// the binary calls this once they have: while a plugin offers an auth provider, the
135/// auth folder and config credentials load again, before serving. Not in Home mode,
136/// whose credentials come from Home. Published as the watcher publishes a scan: a file
137/// changed after the scan read it (a token refresh committed meanwhile) keeps its
138/// current credential, and so does a file the scan read half-written. Plugins parse on
139/// a blocking thread, holding no lock: a parse can make host callbacks that need the
140/// async runtime, even with one worker thread. This load registers the credentials as
141/// Go's first one does, so it replaces the startup load's refresh schedules
142/// ([`crate::runtime::CredentialStore::end_bootstrap`]).
143pub async fn reload_plugin_auth_files(rt: &Arc<Runtime>) {
144    use cpa_core::config::credentials;
145    /// Ends the startup window however the load ends, a failed one included, so the
146    /// refresh loop never waits on provisional schedules. Owned by the load itself: a
147    /// dropped caller leaves the window open until the parse it started is published.
148    struct EndBootstrap(Arc<Runtime>);
149    impl Drop for EndBootstrap {
150        fn drop(&mut self) {
151            self.0.store().end_bootstrap();
152        }
153    }
154    let end = EndBootstrap(rt.clone());
155    if !credentials::plugin_auth_parser_active() {
156        return;
157    }
158    let rt = rt.clone();
159    let reload = tokio::task::spawn_blocking(move || {
160        let _end = end;
161        let cfg = rt.config();
162        credentials::preparse_auth_dir(&cfg);
163        let scan = credentials::scan_auth_dir(&cfg);
164        let mut all = scan.credentials;
165        for existing in rt.store().snapshot() {
166            if let cpa_core::credential::Source::File(path) = &existing.source
167                && scan.incomplete.contains(path)
168                && !all.iter().any(|c| c.id == existing.id)
169            {
170                all.push(cpa_core::credential::Credential::clone(&existing));
171            }
172        }
173        all.extend(credentials::from_config(&cfg));
174        rt.store().reconcile_scanned_with(all, &scan.read, |current, all| {
175            keep_deferred(current, all, &scan.deferred)
176        });
177    });
178    if let Err(e) = reload.await {
179        tracing::error!(error = %e, "reloading auth files for plugin auth providers failed");
180    }
181}
182
183/// Keeps the store's `current` credentials of the files a scan deferred (no plugin auth
184/// provider has answered for their current bytes yet) and publishes nothing new for
185/// them, as Go's watcher asks the plugin first; the watcher's next reload parses them.
186/// Run under the store's reconciliation gate
187/// ([`crate::runtime::CredentialStore::reconcile_scanned_with`]), so a refresh committed
188/// after the scan is what is kept.
189pub(crate) fn keep_deferred(
190    current: &[Arc<cpa_core::credential::Credential>],
191    all: &mut Vec<cpa_core::credential::Credential>,
192    deferred: &std::collections::HashSet<std::path::PathBuf>,
193) {
194    use cpa_core::credential::{Credential, Source};
195    if deferred.is_empty() {
196        return;
197    }
198    // Saves and uploads record absolute paths; a relative auth-dir scans relative ones.
199    let absolute = |p: &std::path::Path| std::path::absolute(p).unwrap_or_else(|_| p.to_owned());
200    let deferred: std::collections::HashSet<_> = deferred.iter().map(|p| absolute(p)).collect();
201    for existing in current {
202        if let Source::File(p) = &existing.source
203            && deferred.contains(&absolute(p))
204            && !all.iter().any(|c| c.id == existing.id)
205        {
206            all.push(Credential::clone(existing));
207        }
208    }
209}
210
211/// Go `syncPluginModelRuntime`: collects plugin catalogs, lets plugin executors claim
212/// the providers and models no built-in executor serves, then publishes the catalogs
213/// for credential-bound registration and the claimed executor models.
214async fn sync_models(rt: &Runtime) {
215    let host = rt.plugins();
216    host.register_models().await;
217    let native = native_executor_providers(rt).await;
218    // Ownership is decided against the registry, whose credentials carry the published
219    // plugin catalog. Republishing changes that registry (a removed built-in catalog
220    // frees its models), so repeat until the catalog is stable; Go decides once against
221    // the previous catalog and catches up on the next sync.
222    for _ in 0..3 {
223        let registry = rt.registry();
224        let Some(changes) = host
225            .register_executors(&|p| native.contains(p), &|m| registry.model_providers(m))
226            .await
227        else {
228            // The plugin set changed meanwhile; its own sync follows.
229            return;
230        };
231        *rt.plugin_runtime()
232            .executors
233            .write()
234            .unwrap_or_else(std::sync::PoisonError::into_inner) = changes
235            .register
236            .into_iter()
237            .map(|adapter| (adapter.provider.clone(), adapter))
238            .collect();
239        let specs = |models: &[cpa_plugin::api::ModelInfo]| models.iter().map(model_spec).collect::<Vec<_>>();
240        let changed = cpa_core::registry::dynamic::set_plugin_catalog(cpa_core::registry::dynamic::PluginCatalog {
241            providers: host
242                .provider_models()
243                .iter()
244                .map(|(provider, models)| (provider.clone(), specs(models)))
245                .collect(),
246            clients: changes
247                .clients
248                .register
249                .iter()
250                .map(|(client, provider, models)| (client.clone(), provider.clone(), specs(models)))
251                .collect(),
252        });
253        if !changed {
254            return;
255        }
256    }
257}
258
259/// Go `registerExecutorForAuth`'s built-in providers.
260const BUILTIN: [&str; 14] = [
261    "codex",
262    "claude",
263    "gemini",
264    "gemini-interactions",
265    "vertex",
266    "aistudio",
267    "antigravity",
268    "kimi",
269    "kimi-ai",
270    "kimi.ai",
271    "kimi.com",
272    "xai",
273    "devin",
274    "meta",
275];
276
277/// Whether Go binds `c` to a built-in executor even over a registered plugin executor
278/// (`registerExecutorForAuth`): an OpenAI-compatible credential
279/// (`openAICompatInfoFromAuth`; `registerOpenAICompatProviderExecutor` keeps only a bare
280/// compat executor), a built-in provider, or any other provider with a native
281/// compatibility config (`hasNativeOpenAICompatExecutorConfig`: a `base_url` attribute
282/// or an enabled `openai-compatibility` entry named after it; `OwnsExecutor` is true
283/// for this host's plugin adapter, so `shouldKeepExistingOpenAICompatExecutor` returns
284/// false and Go replaces it even with `respectNonOwned`). Otherwise a plugin executor
285/// candidate keeps the provider.
286fn binds_native(c: &cpa_core::credential::Credential, compat_names: &[String]) -> bool {
287    let attr = |k: &str| c.attributes.get(k).map(|v| v.trim()).unwrap_or_default();
288    let provider = c.provider.trim().go_lower();
289    if !attr("compat_name").is_empty() || provider == "openai-compatibility" || BUILTIN.contains(&provider.as_str()) {
290        return true;
291    }
292    let key = if provider.is_empty() {
293        "openai-compatibility"
294    } else {
295        provider.as_str()
296    };
297    !attr("base_url").is_empty()
298        || [key, &attr("provider_key").go_lower(), &provider]
299            .iter()
300            .any(|candidate| !candidate.is_empty() && compat_names.iter().any(|n| n == candidate))
301}
302
303/// Go `providerHasNativeExecutor`: providers a built-in executor is actually bound to.
304/// Go binds one per enabled credential (`registerExecutorForAuth`), plus a fixed
305/// baseline in Home mode. An OpenAI-compatible credential or a built-in provider always
306/// binds; any other provider binds the OpenAI-compatible executor unless a plugin
307/// executor is a candidate for it and no native compatibility config names it.
308/// ponytail: Go keeps a binding after its last credential goes away; here bindings are
309/// recomputed from the current credentials.
310async fn native_executor_providers(rt: &Runtime) -> HashSet<String> {
311    let cfg = rt.config();
312    let compat_names = cpa_core::config::credentials::openai_compat_names(&cfg);
313    let host = rt.plugins();
314    let mut native = HashSet::new();
315    for c in rt.store().snapshot().iter().filter(|c| !c.disabled) {
316        let provider = c.provider.trim().go_lower();
317        let key = if !c.attributes.get("compat_name").is_none_or(|v| v.trim().is_empty())
318            || provider == "openai-compatibility"
319        {
320            cpa_core::registry::dynamic::provider_key(c)
321        } else if provider.is_empty() {
322            "openai-compatibility".to_owned()
323        } else {
324            provider
325        };
326        if !binds_native(c, &compat_names) && host.has_executor_candidate_provider(&key).await {
327            continue;
328        }
329        native.insert(key);
330    }
331    if rt.remote_dispatch().is_some() {
332        // Go `baselineExecutorAuths`: the built-in providers but `kimi.com`, plus the
333        // OpenAI-compatible executor.
334        native.extend(
335            BUILTIN
336                .iter()
337                .filter(|p| **p != "kimi.com")
338                .chain(&["openai-compatibility"])
339                .map(|p| (*p).to_owned()),
340        );
341    }
342    native
343}
344
345/// The request facts a plugin scheduler receives (Go `SchedulerPickRequest.Stream` and
346/// `Options`: the client headers and the execution metadata, JSON values only).
347#[derive(Debug, Default)]
348pub struct SchedulerContext {
349    pub stream: bool,
350    pub options: cpa_plugin::api::SchedulerOptions,
351}
352
353/// Go `pickNextLegacy`'s scheduler options for a single-provider selection (Codex
354/// realtime and Alpha Search): the selection headers, the route's own metadata
355/// (`metadata`, such as a realtime call's pinned credential and execution session), the
356/// provider as the session affinity provider and `affinity_model` (Go
357/// `selectionArgForSelector`: the route model under session affinity, else empty).
358/// These routes do not run `session.Enrich`. `None` without an active plugin scheduler.
359pub(crate) fn provider_scheduler_context(
360    rt: &Runtime,
361    provider: &str,
362    headers: &HeaderMap,
363    affinity_model: &str,
364    metadata: &[(&str, &str)],
365) -> Option<Arc<SchedulerContext>> {
366    if !rt.plugins().has_scheduler() {
367        return None;
368    }
369    let string = |s: &str| serde_json::Value::String(s.to_owned());
370    let mut out: cpa_plugin::gojson::Metadata = metadata.iter().map(|(k, v)| ((*k).to_owned(), string(v))).collect();
371    out.insert("session_affinity_provider".into(), string(provider));
372    out.insert("session_affinity_model".into(), string(affinity_model));
373    Some(Arc::new(SchedulerContext {
374        stream: false,
375        options: cpa_plugin::api::SchedulerOptions {
376            headers: go_request_header(headers),
377            metadata: out,
378        },
379    }))
380}
381
382/// The plugin scheduler's request for a selection, or `None` when no plugin scheduler
383/// takes part (none active, or Home mode). Errors are the availability errors Go
384/// reports before asking the scheduler.
385pub(crate) fn scheduler_request(
386    rt: &Runtime,
387    selection: &crate::runtime::Selection,
388    policy: &crate::scheduler::Policy,
389    admit: &crate::runtime::Admit<'_>,
390) -> Result<Option<cpa_plugin::api::SchedulerPickRequest>, crate::runtime::AcquireError> {
391    let host = rt.plugins();
392    if rt.remote_dispatch().is_some() || !host.has_scheduler() {
393        return Ok(None);
394    }
395    let across = host.scheduler_wants_across_priorities();
396    let candidates = rt.store().scheduler_candidates(selection, policy, admit, across)?;
397    let mut providers: Vec<String> = Vec::new();
398    for p in selection.provider_keys() {
399        let p = p.trim().go_lower();
400        if !p.is_empty() && p != "mixed" && !providers.contains(&p) {
401            providers.push(p);
402        }
403    }
404    let context = selection.scheduler.as_deref();
405    Ok(Some(cpa_plugin::api::SchedulerPickRequest {
406        // Handlers select across providers (Go `pickNextMixed`, "mixed"), which leaves
407        // Provider empty; Codex realtime and Alpha Search select one provider (Go
408        // `pickNextLegacy`), which names it.
409        provider: if selection.providers.is_empty() {
410            selection.provider.trim().go_lower()
411        } else {
412            String::new()
413        },
414        providers,
415        model: selection.model.clone(),
416        stream: context.is_some_and(|c| c.stream),
417        options: context.map(|c| c.options.clone()).unwrap_or_default(),
418        candidates: candidates
419            .iter()
420            .map(|c| cpa_plugin::api::SchedulerAuthCandidate {
421                id: c.id.clone(),
422                provider: c.provider.trim().go_lower(),
423                priority: crate::scheduler::priority(c),
424                // ponytail: candidates are ready, which Go reports as `active` unless an
425                // earlier failure left the credential in `error`; that status is not
426                // tracked apart from cooldowns here.
427                status: "active".into(),
428                attributes: c
429                    .attributes
430                    .iter()
431                    .filter(|(k, _)| !scheduler_attribute_sensitive(k))
432                    .map(|(k, v)| (k.clone(), v.clone()))
433                    .collect(),
434                ..Default::default()
435            })
436            .collect(),
437        ..Default::default()
438    }))
439}
440
441/// Go `pickViaPluginScheduler` before native selection (`pickNextMixedLegacy`): the
442/// highest-priority active plugin scheduler chooses among the ready candidates, rejects
443/// the selection, or delegates to a built-in strategy; without an answer the configured
444/// selector chooses. Go's Home mode selects remotely and consults no plugin scheduler.
445pub(crate) async fn scheduler_pick(
446    rt: &Runtime,
447    request: Option<cpa_plugin::api::SchedulerPickRequest>,
448) -> Result<crate::runtime::Pick, crate::runtime::AcquireError> {
449    use crate::runtime::{AcquireError, Pick};
450    let Some(request) = request else {
451        return Ok(Pick::Configured);
452    };
453    let resp = match rt.plugins().pick_auth(request).await {
454        Ok(Some(resp)) => resp,
455        Ok(None) => return Ok(Pick::Configured),
456        // Go returns the plugin's error; its status, if any, decides the response.
457        Err(e) => {
458            return Err(AcquireError::Scheduler(cpa_core::exec::ExecError::local(
459                e.status(),
460                cpa_core::exec::FailureScope::Model,
461                e.to_string(),
462            )));
463        }
464    };
465    if resp.reject {
466        return Err(AcquireError::Rejected {
467            code: resp.reject_code,
468            message: resp.reject_reason,
469        });
470    }
471    if !resp.auth_id.is_empty() {
472        return Ok(Pick::Auth(resp.auth_id));
473    }
474    Ok(match resp.delegate_builtin.as_str() {
475        cpa_plugin::api::SCHEDULER_BUILTIN_ROUND_ROBIN => Pick::Builtin(crate::scheduler::Strategy::RoundRobin),
476        cpa_plugin::api::SCHEDULER_BUILTIN_FILL_FIRST => Pick::Builtin(crate::scheduler::Strategy::FillFirst),
477        _ => Pick::Configured,
478    })
479}
480
481/// Go `schedulerAttributeSensitive`: credential attributes a scheduler never sees.
482fn scheduler_attribute_sensitive(key: &str) -> bool {
483    let key = key.trim().go_lower();
484    let normalized: String = key
485        .chars()
486        .map(|c| if matches!(c, '-' | '.' | ' ') { '_' } else { c })
487        .collect();
488    let compact: String = key.chars().filter(|c| !matches!(c, '_' | '-' | '.' | ' ')).collect();
489    [
490        "api_key",
491        "apikey",
492        "token",
493        "secret",
494        "cookie",
495        "credential",
496        "password",
497        "storage",
498        "authorization",
499        "auth_header",
500        "proxy_url",
501    ]
502    .iter()
503    .any(|fragment| key.contains(fragment) || normalized.contains(fragment) || compact.contains(fragment))
504}
505
506/// Go `pluginModelInfoToRegistryModelInfo`.
507fn model_spec(m: &cpa_plugin::api::ModelInfo) -> cpa_core::registry::dynamic::Spec {
508    cpa_core::registry::dynamic::Spec {
509        id: m.id.trim().to_owned(),
510        object: m.object.clone(),
511        created: m.created,
512        owned_by: m.owned_by.clone(),
513        kind: m.model_type.clone(),
514        display_name: m.display_name.clone(),
515        name: m.name.clone(),
516        version: m.version.clone(),
517        description: m.description.clone(),
518        input_token_limit: m.input_token_limit,
519        output_token_limit: m.output_token_limit,
520        supported_generation_methods: m.supported_generation_methods.clone(),
521        context_length: m.context_length,
522        max_completion_tokens: m.max_completion_tokens,
523        supported_parameters: m.supported_parameters.clone(),
524        supported_input_modalities: m.supported_input_modalities.clone(),
525        supported_output_modalities: m.supported_output_modalities.clone(),
526        thinking: m.thinking.as_ref().map(|t| cpa_core::registry::ThinkingSupport {
527            min: t.min,
528            max: t.max,
529            zero_allowed: t.zero_allowed,
530            dynamic_allowed: t.dynamic_allowed,
531            disable_type: t.disable_type.clone(),
532            levels: t.levels.clone(),
533        }),
534        user_defined: m.user_defined,
535        ..Default::default()
536    }
537}
538
539// ---- Frontend auth (Go `sdk/access`) -------------------------------------------------
540
541/// Go `sdkaccess.AccessProviderTypeConfigAPIKey`: the client-key provider's registry key.
542const CONFIG_PROVIDER_KEY: &str = "config-api-key";
543/// Go `sdkaccess.DefaultAccessProviderName`: the client-key provider's identifier.
544pub(crate) const CONFIG_PROVIDER: &str = "config-inline";
545
546/// Go's global access provider registry as the syncs leave it: keys in first-registration
547/// order (a re-registered key keeps its place; an unregistered one loses it), the plugin
548/// behind each plugin key, and the exclusive key.
549#[derive(Default)]
550struct AccessRegistry {
551    order: Vec<String>,
552    plugins: HashMap<String, String>,
553    exclusive: Option<String>,
554}
555
556enum Provider<'a> {
557    ClientKeys,
558    Plugin(&'a str),
559}
560
561impl AccessRegistry {
562    /// Go `RegisteredProviders`. The client-key provider is present exactly when keys are
563    /// configured now; before the first sync it sits first, as Go registers it before any
564    /// plugin.
565    fn providers(&self, client_keys: bool) -> Vec<Provider<'_>> {
566        if let Some(id) = self.exclusive.as_ref().and_then(|key| self.plugins.get(key)) {
567            return vec![Provider::Plugin(id)];
568        }
569        let mut out = Vec::with_capacity(self.order.len() + 1);
570        if client_keys && !self.order.iter().any(|k| k == CONFIG_PROVIDER_KEY) {
571            out.push(Provider::ClientKeys);
572        }
573        for key in &self.order {
574            if key == CONFIG_PROVIDER_KEY {
575                if client_keys {
576                    out.push(Provider::ClientKeys);
577                }
578            } else if let Some(id) = self.plugins.get(key) {
579                out.push(Provider::Plugin(id));
580            }
581        }
582        out
583    }
584}
585
586impl PluginRuntime {
587    fn access(&self) -> Arc<AccessRegistry> {
588        self.access.read().unwrap_or_else(|e| e.into_inner()).clone()
589    }
590
591    /// Go `configaccess.Register` then `RegisterFrontendAuthProviders`: register or
592    /// unregister the client-key provider, register each plugin provider, set the
593    /// exclusive key, and drop plugin keys no longer offered.
594    pub(crate) fn register_access(
595        &self,
596        client_keys: bool,
597        providers: Vec<(String, String)>,
598        exclusive: Option<String>,
599    ) {
600        let mut slot = self.access.write().unwrap_or_else(|e| e.into_inner());
601        let mut next = AccessRegistry {
602            order: slot.order.clone(),
603            plugins: HashMap::new(),
604            exclusive,
605        };
606        let register = |order: &mut Vec<String>, key: &str| {
607            if !order.iter().any(|k| k == key) {
608                order.push(key.to_owned());
609            }
610        };
611        if client_keys {
612            register(&mut next.order, CONFIG_PROVIDER_KEY);
613        } else {
614            next.order.retain(|k| k != CONFIG_PROVIDER_KEY);
615        }
616        for (key, id) in providers {
617            register(&mut next.order, &key);
618            next.plugins.insert(key, id);
619        }
620        next.order
621            .retain(|k| k == CONFIG_PROVIDER_KEY || next.plugins.contains_key(k));
622        *slot = Arc::new(next);
623    }
624}
625
626/// A request the access providers let through.
627pub(crate) enum Access {
628    /// No provider registered: Go's manager returns no result and sets nothing.
629    Open,
630    /// Go `sdkaccess.Result`: the caller, with the provider identifier that accepted it.
631    /// ponytail: a plugin's result metadata is not kept (`Caller` has no field for it;
632    /// only Go's Home mode reads it).
633    Granted(Caller),
634}
635
636/// Go `sdkaccess.AuthError` as the middlewares answer it.
637pub(crate) struct Denied {
638    pub status: u16,
639    pub message: &'static str,
640}
641
642const MISSING_API_KEY: &str = "Missing API key";
643
644/// Go `sdkaccess.Manager.Authenticate` over the registered providers: client keys, then
645/// plugin frontend auth providers in registration order (or only the exclusive one).
646/// The first acceptance wins; afterwards "Invalid API key" if any provider saw an
647/// invalid key, else "Missing API key". The request comes back with its body intact.
648pub(crate) async fn authenticate(rt: &Runtime, req: Request) -> (Request, Result<Access, Denied>) {
649    let config = rt.config();
650    let registry = rt.plugin_runtime().access();
651    let providers = registry.providers(!config.api_keys.is_empty());
652    if providers.is_empty() {
653        // Go is open here; cliproxy-rs serves local clients only unless opted in.
654        let refused = (!crate::access::open_access(rt, &config))
655            .then(|| crate::access::refuse_nonlocal(&req))
656            .flatten();
657        return match refused {
658            Some(message) => (req, Err(Denied { status: 403, message })),
659            None => (req, Ok(Access::Open)),
660        };
661    }
662    let (parts, mut body) = req.into_parts();
663    let mut read: Option<Bytes> = None;
664    let mut invalid = false;
665    let mut outcome = None;
666    for provider in providers {
667        match provider {
668            Provider::ClientKeys => {
669                match crate::access::authenticate(
670                    &config.api_keys,
671                    &parts.headers,
672                    parts.uri.query().unwrap_or_default(),
673                ) {
674                    Ok(caller) => {
675                        outcome = Some(Ok(Access::Granted(Caller {
676                            provider: CONFIG_PROVIDER.to_owned(),
677                            ..caller
678                        })));
679                        break;
680                    }
681                    Err(message) => invalid |= message != MISSING_API_KEY,
682                }
683            }
684            Provider::Plugin(id) => {
685                // Go `readAndRestoreRequestBody`: the whole body, once. Go reads it
686                // without a bound; here it stops at MAX_REQUEST_BYTES, as the routes do.
687                let bytes = match &read {
688                    Some(bytes) => bytes.clone(),
689                    None => match read_limited(std::mem::take(&mut body)).await {
690                        Ok(Some(bytes)) => read.insert(bytes).clone(),
691                        Ok(None) => {
692                            outcome = Some(Err(Denied {
693                                status: 413,
694                                message: "request body too large",
695                            }));
696                            break;
697                        }
698                        // Go `NewRequestEntityTooLargeError` (dd7b4334).
699                        Err(error) if crate::body_limit::is_too_large(&error) => {
700                            outcome = Some(Err(Denied {
701                                status: 413,
702                                message: crate::body_limit::MESSAGE,
703                            }));
704                            break;
705                        }
706                        Err(error) => {
707                            tracing::error!(
708                                "authentication middleware error: failed to read plugin auth request body: {error}"
709                            );
710                            outcome = Some(Err(Denied {
711                                status: 500,
712                                message: "failed to read plugin auth request body",
713                            }));
714                            break;
715                        }
716                    },
717                };
718                let request = cpa_plugin::api::FrontendAuthRequest {
719                    method: parts.method.as_str().to_owned(),
720                    path: crate::management::percent_decode(parts.uri.path()),
721                    headers: go_request_header(&parts.headers),
722                    query: go_values(parts.uri.query().unwrap_or_default()),
723                    body: cpa_plugin::gojson::NonNilBytes(bytes),
724                };
725                if let Some(accepted) = rt.plugins().frontend_authenticate(id, &request).await {
726                    outcome = Some(Ok(Access::Granted(Caller {
727                        principal: accepted.principal,
728                        source: "",
729                        provider: accepted.provider,
730                    })));
731                    break;
732                }
733            }
734        }
735    }
736    let body = match read {
737        Some(bytes) => Body::from(bytes),
738        None => body,
739    };
740    let outcome = outcome.unwrap_or(Err(Denied {
741        status: 401,
742        message: if invalid { "Invalid API key" } else { MISSING_API_KEY },
743    }));
744    (Request::from_parts(parts, body), outcome)
745}
746
747/// No client-key or plugin auth provider is registered: Go's open access.
748pub(crate) fn no_providers(rt: &Runtime, config: &cpa_core::config::Config) -> bool {
749    rt.plugin_runtime()
750        .access()
751        .providers(!config.api_keys.is_empty())
752        .is_empty()
753}
754
755/// The whole body, or `None` once it passes [`crate::MAX_REQUEST_BYTES`].
756async fn read_limited(body: Body) -> Result<Option<Bytes>, axum::Error> {
757    use futures_util::StreamExt as _;
758    let mut stream = body.into_data_stream();
759    let mut out = bytes::BytesMut::new();
760    while let Some(chunk) = stream.next().await {
761        let chunk = chunk?;
762        if out.len() + chunk.len() > crate::MAX_REQUEST_BYTES {
763            return Ok(None);
764        }
765        out.extend_from_slice(&chunk);
766    }
767    Ok(Some(out.freeze()))
768}
769
770/// A server request's `http.Header` as Go's handlers see it: canonical names, values in
771/// order, and no `Host` (Go moves it to `Request.Host`). A chunked request also loses
772/// `Transfer-Encoding`, `Content-Length` and `Trailer` (Go `readTransfer`).
773pub(crate) fn go_request_header(headers: &HeaderMap) -> cpa_plugin::gojson::Header {
774    let chunked = headers.contains_key(axum::http::header::TRANSFER_ENCODING);
775    let mut out = cpa_plugin::gojson::Header::new();
776    for (name, value) in headers {
777        let dropped = name == axum::http::header::HOST
778            || (chunked
779                && (name == axum::http::header::TRANSFER_ENCODING
780                    || name == axum::http::header::CONTENT_LENGTH
781                    || name == axum::http::header::TRAILER));
782        if dropped {
783            continue;
784        }
785        out.entry(cpa_exec::proxy::canonical_header(name.as_str()))
786            .or_default()
787            .push(String::from_utf8_lossy(value.as_bytes()).into_owned());
788    }
789    out
790}
791
792/// `Request.URL.Query()` as `url.Values`.
793pub(crate) fn go_values(raw_query: &str) -> cpa_plugin::gojson::Header {
794    let mut out = cpa_plugin::gojson::Header::new();
795    for (k, v) in crate::management::go_query(raw_query) {
796        out.entry(k).or_default().push(v);
797    }
798    out
799}
800
801/// Syncs the current config now, then follows every later publish. Call once at
802/// startup, before serving (Go applies plugins before the server starts).
803pub async fn start(rt: &Arc<Runtime>) {
804    model_callbacks::attach(rt);
805    let mut rx = rt.plugin_runtime().latest.subscribe();
806    rx.mark_unchanged();
807    // At least this publish is in the current config.
808    let seq = rt.plugin_runtime().published_seq();
809    sync(rt, rt.config()).await;
810    rt.plugin_runtime().applied.send_replace(seq);
811    let weak: Weak<Runtime> = Arc::downgrade(rt);
812    tokio::spawn(async move {
813        while rx.changed().await.is_ok() {
814            let Some((seq, cfg)) = rx.borrow_and_update().clone() else {
815                continue;
816            };
817            let Some(rt) = weak.upgrade() else {
818                return;
819            };
820            sync(&rt, cfg).await;
821            rt.plugin_runtime().applied.send_replace(seq);
822        }
823    });
824}
825
826/// Go `registeredManagementRouteKeys`: every built-in `/v0/management` route as gin
827/// lists it. Plugins cannot register these keys even where this server does not
828/// implement the route, so a plugin keeps the same routes under both servers.
829/// ponytail: Go registers these only once a management secret exists; until then it
830/// lets plugins claim them. The full list is used unconditionally.
831pub fn reserved_management_routes() -> HashSet<String> {
832    GO_V0_MANAGEMENT_ROUTES.iter().map(|r| (*r).to_owned()).collect()
833}
834
835/// `internal/api/server_management.go` at 6fecc6e.
836const GO_V0_MANAGEMENT_ROUTES: [&str; 144] = [
837    "DELETE /v0/management/api-keys",
838    "DELETE /v0/management/auth-files",
839    "DELETE /v0/management/claude-api-key",
840    "DELETE /v0/management/codex-api-key",
841    "DELETE /v0/management/gemini-api-key",
842    "DELETE /v0/management/interactions-api-key",
843    "DELETE /v0/management/logs",
844    "DELETE /v0/management/meta-api-key",
845    "DELETE /v0/management/oauth-excluded-models",
846    "DELETE /v0/management/oauth-model-alias",
847    "DELETE /v0/management/oauth-request-scoped-errors",
848    "DELETE /v0/management/oauth-session",
849    "DELETE /v0/management/openai-compatibility",
850    "DELETE /v0/management/plugins/:id",
851    "DELETE /v0/management/plugins/:id/quota",
852    "DELETE /v0/management/proxy-url",
853    "DELETE /v0/management/vertex-api-key",
854    "DELETE /v0/management/xai-api-key",
855    "GET /v0/management/anthropic-auth-url",
856    "GET /v0/management/antigravity-auth-url",
857    "GET /v0/management/api-key-usage",
858    "GET /v0/management/api-keys",
859    "GET /v0/management/auth-files",
860    "GET /v0/management/auth-files/download",
861    "GET /v0/management/auth-files/models",
862    "GET /v0/management/claude-api-key",
863    "GET /v0/management/codex-api-key",
864    "GET /v0/management/codex-auth-url",
865    "GET /v0/management/config",
866    "GET /v0/management/config.yaml",
867    "GET /v0/management/debug",
868    "GET /v0/management/devin-auth-url",
869    "GET /v0/management/error-logs-max-files",
870    "GET /v0/management/force-model-prefix",
871    "GET /v0/management/gemini-api-key",
872    "GET /v0/management/get-auth-status",
873    "GET /v0/management/interactions-api-key",
874    "GET /v0/management/kimi-ai-auth-url",
875    "GET /v0/management/kimi-auth-url",
876    "GET /v0/management/latest-version",
877    "GET /v0/management/logging-to-file",
878    "GET /v0/management/logs",
879    "GET /v0/management/logs-max-total-size-mb",
880    "GET /v0/management/max-retry-credentials",
881    "GET /v0/management/max-retry-interval",
882    "GET /v0/management/meta-api-key",
883    "GET /v0/management/meta-auth-url",
884    "GET /v0/management/model-definitions/:channel",
885    "GET /v0/management/oauth-callback",
886    "GET /v0/management/oauth-excluded-models",
887    "GET /v0/management/oauth-model-alias",
888    "GET /v0/management/oauth-request-scoped-errors",
889    "GET /v0/management/openai-compatibility",
890    "GET /v0/management/plugin-store",
891    "GET /v0/management/plugins",
892    "GET /v0/management/plugins/:id/config",
893    "GET /v0/management/plugins/:id/quota",
894    "GET /v0/management/proxy-url",
895    "GET /v0/management/quota-exceeded/switch-preview-model",
896    "GET /v0/management/quota-exceeded/switch-project",
897    "GET /v0/management/quota/providers",
898    "GET /v0/management/request-error-logs",
899    "GET /v0/management/request-error-logs/:name",
900    "GET /v0/management/request-log",
901    "GET /v0/management/request-log-by-id/:id",
902    "GET /v0/management/request-retry",
903    "GET /v0/management/routing/strategy",
904    "GET /v0/management/usage-queue",
905    "GET /v0/management/usage-statistics-enabled",
906    "GET /v0/management/vertex-api-key",
907    "GET /v0/management/ws-auth",
908    "GET /v0/management/xai-api-key",
909    "GET /v0/management/xai-auth-url",
910    "PATCH /v0/management/api-keys",
911    "PATCH /v0/management/auth-files/fields",
912    "PATCH /v0/management/auth-files/status",
913    "PATCH /v0/management/claude-api-key",
914    "PATCH /v0/management/codex-api-key",
915    "PATCH /v0/management/debug",
916    "PATCH /v0/management/error-logs-max-files",
917    "PATCH /v0/management/force-model-prefix",
918    "PATCH /v0/management/gemini-api-key",
919    "PATCH /v0/management/interactions-api-key",
920    "PATCH /v0/management/logging-to-file",
921    "PATCH /v0/management/logs-max-total-size-mb",
922    "PATCH /v0/management/max-retry-credentials",
923    "PATCH /v0/management/max-retry-interval",
924    "PATCH /v0/management/meta-api-key",
925    "PATCH /v0/management/oauth-excluded-models",
926    "PATCH /v0/management/oauth-model-alias",
927    "PATCH /v0/management/oauth-request-scoped-errors",
928    "PATCH /v0/management/openai-compatibility",
929    "PATCH /v0/management/plugins/:id/config",
930    "PATCH /v0/management/plugins/:id/enabled",
931    "PATCH /v0/management/proxy-url",
932    "PATCH /v0/management/quota-exceeded/switch-preview-model",
933    "PATCH /v0/management/quota-exceeded/switch-project",
934    "PATCH /v0/management/request-log",
935    "PATCH /v0/management/request-retry",
936    "PATCH /v0/management/routing/strategy",
937    "PATCH /v0/management/usage-statistics-enabled",
938    "PATCH /v0/management/vertex-api-key",
939    "PATCH /v0/management/ws-auth",
940    "PATCH /v0/management/xai-api-key",
941    "POST /v0/management/api-call",
942    "POST /v0/management/auth-files",
943    "POST /v0/management/auth-files/refresh",
944    "POST /v0/management/oauth-callback",
945    "POST /v0/management/plugin-store/:id/install",
946    "POST /v0/management/plugins/:id/quota",
947    "POST /v0/management/plugins/:id/quota/reset",
948    "POST /v0/management/quota/fetch",
949    "POST /v0/management/quota/reset",
950    "POST /v0/management/reset-quota",
951    "POST /v0/management/vertex/import",
952    "PUT /v0/management/api-keys",
953    "PUT /v0/management/claude-api-key",
954    "PUT /v0/management/codex-api-key",
955    "PUT /v0/management/config.yaml",
956    "PUT /v0/management/debug",
957    "PUT /v0/management/error-logs-max-files",
958    "PUT /v0/management/force-model-prefix",
959    "PUT /v0/management/gemini-api-key",
960    "PUT /v0/management/interactions-api-key",
961    "PUT /v0/management/logging-to-file",
962    "PUT /v0/management/logs-max-total-size-mb",
963    "PUT /v0/management/max-retry-credentials",
964    "PUT /v0/management/max-retry-interval",
965    "PUT /v0/management/meta-api-key",
966    "PUT /v0/management/oauth-excluded-models",
967    "PUT /v0/management/oauth-model-alias",
968    "PUT /v0/management/oauth-request-scoped-errors",
969    "PUT /v0/management/openai-compatibility",
970    "PUT /v0/management/plugins/:id/config",
971    "PUT /v0/management/proxy-url",
972    "PUT /v0/management/quota-exceeded/switch-preview-model",
973    "PUT /v0/management/quota-exceeded/switch-project",
974    "PUT /v0/management/request-log",
975    "PUT /v0/management/request-retry",
976    "PUT /v0/management/routing/strategy",
977    "PUT /v0/management/usage-statistics-enabled",
978    "PUT /v0/management/vertex-api-key",
979    "PUT /v0/management/ws-auth",
980    "PUT /v0/management/xai-api-key",
981];
982
983#[cfg(test)]
984mod tests {
985    use super::*;
986
987    fn outcome(result: &Result<Access, Denied>) -> (u16, &'static str) {
988        match result {
989            Ok(_) => (200, ""),
990            Err(denied) => (denied.status, denied.message),
991        }
992    }
993
994    /// A plugin frontend auth provider reads the body even after the client keys
995    /// rejected the request, so the read stops at MAX_REQUEST_BYTES.
996    #[tokio::test]
997    async fn plugin_auth_reads_a_bounded_body() {
998        let dir = cpa_plugin::testing::scratch(&std::env::temp_dir(), "plugin-auth-body");
999        let cfg = Config::parse(&format!(
1000            "config-version: 8\nauth-dir: {}\naccess:\n  api-keys: [client-key]\n",
1001            dir.display()
1002        ))
1003        .unwrap();
1004        let rt = crate::testing::runtime(
1005            cfg,
1006            Vec::new(),
1007            cpa_exec::Executors {
1008                claude: cpa_exec::claude::ClaudeExecutor::new("http://127.0.0.1:1").unwrap(),
1009                codex: Default::default(),
1010                devices: Default::default(),
1011                openai: Default::default(),
1012                google: Default::default(),
1013            },
1014        );
1015        // A provider for a plugin that is not loaded: it never accepts.
1016        rt.plugin_runtime()
1017            .register_access(true, vec![("plugin-auth".into(), "p".into())], None);
1018        let request = |key: Option<&str>, body: Body| {
1019            let mut builder = Request::builder().method("POST").uri("/v1/chat/completions");
1020            if let Some(key) = key {
1021                builder = builder.header("authorization", format!("Bearer {key}"));
1022            }
1023            builder.body(body).unwrap()
1024        };
1025        for key in [None, Some("wrong")] {
1026            let big = Body::from(vec![b'x'; crate::MAX_REQUEST_BYTES + 1]);
1027            let (_, result) = authenticate(&rt, request(key, big)).await;
1028            assert_eq!(outcome(&result), (413, "request body too large"), "{key:?}");
1029        }
1030        // At the limit the body is read, offered and handed back whole.
1031        let (req, result) = authenticate(
1032            &rt,
1033            request(Some("wrong"), Body::from(vec![b'y'; crate::MAX_REQUEST_BYTES])),
1034        )
1035        .await;
1036        assert_eq!(outcome(&result), (401, "Invalid API key"));
1037        let body = axum::body::to_bytes(req.into_body(), usize::MAX).await.unwrap();
1038        assert_eq!(body.len(), crate::MAX_REQUEST_BYTES);
1039        let (_, result) = authenticate(&rt, request(None, Body::from("{}"))).await;
1040        assert_eq!(outcome(&result), (401, MISSING_API_KEY));
1041        let (_, result) = authenticate(&rt, request(Some("client-key"), Body::from("{}"))).await;
1042        assert_eq!(outcome(&result), (200, ""));
1043        let _ = std::fs::remove_dir_all(&dir);
1044    }
1045
1046    /// Go `TestPluginRegisteredSonnet55TurnsThinkingOffWithBetweenTools`: a plugin model's
1047    /// `DisableType` reaches the Claude applier through the registry conversion. An older
1048    /// plugin's payload without it turns thinking off with `disabled`, even on a model the
1049    /// proxy knows refuses it: plugin capabilities are authoritative, as in Go.
1050    #[test]
1051    fn plugin_registered_sonnet_5_5_turns_thinking_off_with_between_tools() {
1052        let thinking_off = |model: &str, thinking: &[u8]| {
1053            let info = model_spec(&cpa_plugin::api::ModelInfo {
1054                id: model.into(),
1055                model_type: "claude".into(),
1056                thinking: Some(cpa_plugin::gojson::from_slice(thinking).unwrap()),
1057                ..Default::default()
1058            })
1059            .to_info();
1060            let body = format!(
1061                r#"{{"model":"{model}","messages":[{{"role":"user","content":"hi"}}],"thinking":{{"type":"disabled"}}}}"#
1062            );
1063            let caps = cpa_common::thinking::ModelCaps::from(&info);
1064            let out = cpa_common::thinking::apply_thinking_with_model_info(
1065                body.as_bytes(),
1066                &[],
1067                model,
1068                "claude",
1069                "claude",
1070                "claude",
1071                Some(&caps),
1072            )
1073            .unwrap();
1074            serde_json::from_slice::<serde_json::Value>(&out).unwrap()["thinking"].clone()
1075        };
1076        let current = br#"{"ZeroAllowed":true,"Levels":["low","medium","high"],"DisableType":"between_tools"}"#;
1077        assert_eq!(
1078            thinking_off("claude-sonnet-5-5", current),
1079            serde_json::json!({"type": "between_tools"})
1080        );
1081        let older = br#"{"ZeroAllowed":true,"Levels":["low","medium","high"]}"#;
1082        assert_eq!(
1083            thinking_off("claude-opus-5-5", older),
1084            serde_json::json!({"type": "disabled"})
1085        );
1086    }
1087}