1use cpa_core::gostr::GoStr;
12use std::collections::{BTreeMap, HashMap, HashSet};
13use std::path::{Path, PathBuf};
14use std::sync::{Arc, Mutex, RwLock};
15use std::time::Duration;
16
17use bytes::Bytes;
18use cpa_core::config::Config;
19
20use crate::abi::method;
21use crate::api;
22use crate::callbacks::Callbacks;
23use crate::client::{CallbackHandler, CallbackInstance, GuardedClient, PluginClient};
24use crate::config::{self, ItemConfig};
25use crate::gojson::GoJson;
26use crate::platform::{self, PluginFile};
27use crate::rpc::{self, CallError, Plugin};
28
29pub trait Loader: Send + Sync + 'static {
31 fn open(
32 &self,
33 file: &PluginFile,
34 handler: Arc<dyn CallbackHandler>,
35 instance: Arc<CallbackInstance>,
36 ) -> Result<Arc<dyn PluginClient>, String>;
37}
38
39pub struct NativeLoader;
41
42impl Loader for NativeLoader {
43 #[cfg(unix)]
44 fn open(
45 &self,
46 file: &PluginFile,
47 handler: Arc<dyn CallbackHandler>,
48 instance: Arc<CallbackInstance>,
49 ) -> Result<Arc<dyn PluginClient>, String> {
50 crate::native::NativeClient::open(&file.path, &file.id, handler, instance)
51 .map(|c| Arc::new(c) as Arc<dyn PluginClient>)
52 }
53
54 #[cfg(not(unix))]
57 fn open(
58 &self,
59 file: &PluginFile,
60 _: Arc<dyn CallbackHandler>,
61 _: Arc<CallbackInstance>,
62 ) -> Result<Arc<dyn PluginClient>, String> {
63 Err(format!(
64 "standard dynamic library plugin loading requires cgo on this platform: {}",
65 file.path.display()
66 ))
67 }
68}
69
70pub fn support_plugin_header_value() -> &'static str {
72 crate::SUPPORT_PLUGIN
73}
74
75pub(crate) struct LoadedPlugin {
76 pub id: String,
77 pub path: PathBuf,
78 pub version: String,
79 pub name: String,
80 pub config_yaml: Vec<u8>,
81 pub plugin: Option<Plugin>,
82 pub registered: bool,
83 pub client: Arc<GuardedClient>,
84}
85
86#[derive(Clone)]
88pub struct Record {
89 pub id: String,
90 pub path: PathBuf,
91 pub version: String,
92 pub priority: i64,
93 pub plugin: Plugin,
94 pub client: Arc<GuardedClient>,
95}
96
97impl std::fmt::Debug for Record {
98 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
99 f.debug_struct("Record")
100 .field("id", &self.id)
101 .field("version", &self.version)
102 .field("priority", &self.priority)
103 .finish_non_exhaustive()
104 }
105}
106
107#[derive(Debug, Default)]
109pub struct Snapshot {
110 pub enabled: bool,
111 pub records: Vec<Record>,
112 pub(crate) quota_supported: Mutex<HashMap<String, Vec<String>>>,
114}
115
116#[derive(Debug, Clone, PartialEq)]
118pub struct RegisteredPluginInfo {
119 pub id: String,
120 pub priority: i64,
121 pub metadata: api::PluginMetadata,
122 pub supports_oauth: bool,
123 pub oauth_provider: String,
124 pub supports_quota: bool,
125 pub quota_provider: String,
126 pub menus: Vec<RegisteredPluginMenu>,
127}
128
129#[derive(Debug, Clone, PartialEq, Eq)]
131pub struct RegisteredPluginMenu {
132 pub path: String,
133 pub menu: String,
134 pub description: String,
135}
136
137#[derive(Default)]
138pub(crate) struct State {
139 pub loaded: HashMap<String, LoadedPlugin>,
140 pub retired: HashMap<String, Vec<LoadedPlugin>>,
141 pub loading: HashSet<String>,
142 pub fused: HashMap<String, String>,
143 pub file_versions: HashMap<PathBuf, String>,
144 pub active_versions: HashMap<String, String>,
145 pub active_paths: HashMap<String, PathBuf>,
146 pub cleanup_files_pending: bool,
147 pub config: Option<Arc<Config>>,
148 pub management_routes: BTreeMap<String, crate::management::RouteRecord>,
149 pub resource_routes: BTreeMap<String, crate::management::ResourceRecord>,
150 pub thinking_providers: BTreeMap<String, String>,
152 pub model_providers: HashMap<String, String>,
154 pub model_registrations: HashMap<String, crate::models::ModelRegistration>,
155 pub executor_providers: HashSet<String>,
156 pub executor_model_client_ids: HashSet<String>,
157 pub provider_models: BTreeMap<String, Vec<api::ModelInfo>>,
158 pub command_line_flags: BTreeMap<String, crate::cli::CliFlag>,
160 pub command_line_hits: HashSet<String>,
161}
162
163pub(crate) struct Inner {
164 apply: tokio::sync::Mutex<()>,
165 pub state: Mutex<State>,
166 snapshot: RwLock<Arc<Snapshot>>,
167 loader: Arc<dyn Loader>,
168 pub callbacks: Callbacks,
169 pub(crate) hooks_installed: std::sync::atomic::AtomicBool,
172 pub(crate) auth_parser_installed: std::sync::atomic::AtomicBool,
174 pub(crate) auth_parser: std::sync::OnceLock<Arc<dyn cpa_core::config::credentials::PluginAuthParser>>,
176 pub(crate) auth_parses: Mutex<Vec<(Arc<CallbackInstance>, PathBuf, bool)>>,
179}
180
181#[derive(Clone)]
183pub struct Host {
184 pub(crate) inner: Arc<Inner>,
185}
186
187pub(crate) fn lock<T>(m: &Mutex<T>) -> std::sync::MutexGuard<'_, T> {
188 m.lock().unwrap_or_else(std::sync::PoisonError::into_inner)
189}
190
191fn clean_path(path: &Path) -> PathBuf {
193 if path.as_os_str().is_empty() {
194 PathBuf::new()
195 } else {
196 platform::clean(path)
197 }
198}
199
200pub fn normalize_provider(provider: &str) -> String {
202 use cpa_common::gostr::GoStr;
203 provider.trim().go_lower()
204}
205
206impl Default for Host {
207 fn default() -> Self {
208 Self::new()
209 }
210}
211
212impl Host {
213 pub fn new() -> Self {
214 Self::with_loader(Arc::new(NativeLoader))
215 }
216
217 pub fn with_loader(loader: Arc<dyn Loader>) -> Self {
218 let inner = Arc::new_cyclic(|me| Inner {
219 apply: tokio::sync::Mutex::new(()),
220 state: Mutex::new(State {
221 cleanup_files_pending: true,
222 ..Default::default()
223 }),
224 snapshot: RwLock::new(Arc::default()),
225 loader,
226 callbacks: Callbacks::new(me.clone()),
227 hooks_installed: Default::default(),
228 auth_parser_installed: Default::default(),
229 auth_parser: Default::default(),
230 auth_parses: Default::default(),
231 });
232 Self { inner }
233 }
234
235 pub(crate) fn from_inner(inner: Arc<Inner>) -> Self {
236 Self { inner }
237 }
238
239 pub fn snapshot(&self) -> Arc<Snapshot> {
240 self.inner
241 .snapshot
242 .read()
243 .unwrap_or_else(std::sync::PoisonError::into_inner)
244 .clone()
245 }
246
247 fn store_snapshot(&self, state: &mut State, snapshot: Snapshot) {
251 self.publish_hook_activity(state, &snapshot.records);
252 *self
253 .inner
254 .snapshot
255 .write()
256 .unwrap_or_else(std::sync::PoisonError::into_inner) = Arc::new(snapshot);
257 }
258
259 pub(crate) fn state(&self) -> std::sync::MutexGuard<'_, State> {
260 lock(&self.inner.state)
261 }
262
263 pub fn config(&self) -> Option<Arc<Config>> {
265 self.state().config.clone()
266 }
267
268 pub fn active_records(&self) -> Vec<Record> {
271 self.current_records(&self.snapshot())
272 }
273
274 pub fn current_records(&self, snapshot: &Snapshot) -> Vec<Record> {
276 snapshot
277 .records
278 .iter()
279 .filter(|r| self.record_current(r))
280 .cloned()
281 .collect()
282 }
283
284 pub fn live(&self, record: &Record) -> bool {
287 !self.is_fused(&record.id) && self.record_current(record)
288 }
289
290 pub fn record_current(&self, record: &Record) -> bool {
292 let state = self.state();
293 let id = record.id.trim();
294 let path = clean_path(&record.path);
295 let version = record.version.trim();
296 !id.is_empty()
297 && !path.as_os_str().is_empty()
298 && state.active_paths.get(id) == Some(&path)
299 && state.file_versions.get(&path).map(String::as_str) == Some(version)
300 && state.active_versions.get(id).map(String::as_str) == Some(version)
301 }
302
303 pub fn is_fused(&self, id: &str) -> bool {
304 self.state().fused.contains_key(id)
305 }
306
307 pub fn fuse(&self, id: &str, what: &str, panic: &str) {
310 let mut state = self.state();
311 state.fused.insert(id.to_owned(), format!("{what} panic: {panic}"));
312 state.thinking_providers.retain(|_, owner| owner != id);
314 cpa_common::thinking::unregister_plugin_providers(id);
315 self.publish_hook_activity(&state, &self.snapshot().records);
316 drop(state);
317 tracing::error!(plugin_id = %id, method = %what, "pluginhost: plugin panic recovered: {panic}");
318 }
319
320 pub(crate) fn fuse_on_panic<T>(&self, id: &str, what: &str, result: Result<T, CallError>) -> Result<T, CallError> {
322 if let Err(CallError::Panic(p)) = &result {
323 self.fuse(id, what, p);
324 }
325 result
326 }
327
328 pub fn plugin_loaded(&self, id: &str) -> bool {
330 let id = id.trim();
331 let state = self.state();
332 !id.is_empty() && (state.loaded.contains_key(id) || state.retired.get(id).is_some_and(|r| !r.is_empty()))
333 }
334
335 pub fn plugin_busy(&self, id: &str) -> bool {
337 self.plugin_loaded(id) || self.state().loading.contains(id.trim())
338 }
339
340 pub fn plugin_registered(&self, id: &str) -> bool {
342 let id = id.trim();
343 !id.is_empty() && self.active_records().iter().any(|r| r.id == id)
344 }
345
346 pub fn registered_plugins(&self) -> Vec<RegisteredPluginInfo> {
348 let records = self.active_records();
349 let menus = self.registered_menus();
350 records
351 .iter()
352 .map(|r| {
353 let fused = self.is_fused(&r.id);
354 RegisteredPluginInfo {
355 id: r.id.clone(),
356 priority: r.priority,
357 metadata: r.plugin.metadata.clone(),
358 supports_oauth: r.plugin.caps.auth_provider,
359 oauth_provider: if r.plugin.caps.auth_provider && !fused {
360 normalize_provider(&r.plugin.auth_identifier)
361 } else {
362 String::new()
363 },
364 supports_quota: r.plugin.caps.quota_provider,
365 quota_provider: if r.plugin.caps.quota_provider && !fused {
366 normalize_provider(&r.plugin.quota_identifier)
367 } else {
368 String::new()
369 },
370 menus: menus.get(&r.id).cloned().unwrap_or_default(),
371 }
372 })
373 .collect()
374 }
375
376 fn registered_menus(&self) -> HashMap<String, Vec<RegisteredPluginMenu>> {
377 let state = self.state();
378 let mut out: HashMap<String, Vec<RegisteredPluginMenu>> = HashMap::new();
379 for record in state.resource_routes.values() {
380 let menu = record.route.menu.trim();
381 if menu.is_empty() {
382 continue;
383 }
384 out.entry(record.plugin_id.clone())
385 .or_default()
386 .push(RegisteredPluginMenu {
387 path: record.route.path.trim().to_owned(),
388 menu: menu.to_owned(),
389 description: record.route.description.trim().to_owned(),
390 });
391 }
392 for menus in out.values_mut() {
393 menus.sort_by(|a, b| a.path.cmp(&b.path));
394 }
395 out
396 }
397
398 pub async fn apply_config(&self, cfg: Arc<Config>) {
405 let host = self.clone();
406 let _ = tokio::spawn(async move { host.apply_config_inner(cfg).await }).await;
407 }
408
409 async fn apply_config_inner(&self, cfg: Arc<Config>) {
410 let _apply = self.inner.apply.lock().await;
411 let rc = match config::runtime_config(&cfg.document, &cfg.plugin_configs) {
412 Ok(rc) => rc,
413 Err(e) => {
414 tracing::error!("failed to apply plugin runtime config: {e}");
415 return;
416 }
417 };
418 self.state().config = Some(cfg.clone());
419 if !rc.enabled {
420 self.deactivate_all();
421 self.refresh_thinking_providers().await;
422 return;
423 }
424 let desired = config::desired_versions(&rc.items);
425 let files = match platform::discover(&rc.dir, &desired) {
426 Ok(files) => files,
427 Err(e) => {
428 tracing::warn!("pluginhost: failed to select plugin files: {e}");
429 self.deactivate_all();
430 self.refresh_thinking_providers().await;
431 return;
432 }
433 };
434 let files = self.with_loaded_fallbacks(files, &rc.items, &desired);
435
436 let mut records = Vec::new();
437 let mut loaded_files = Vec::new();
438 let mut hot_reloads = Vec::new();
439 for file in files {
440 let item = rc
441 .items
442 .get(&file.id)
443 .cloned()
444 .unwrap_or_else(|| ItemConfig::default_for(&file.id));
445 if !item.enabled {
446 continue;
447 }
448 let (existing, replaced, fused) = {
449 let state = self.state();
450 let existing = state
451 .loaded
452 .get(&file.id)
453 .map(|lp| (lp.path.clone(), lp.version.clone()));
454 let replaced = existing
455 .as_ref()
456 .is_some_and(|(path, _)| clean_path(path) != clean_path(&file.path));
457 (existing, replaced, state.fused.contains_key(&file.id))
458 };
459 if fused && !replaced {
460 continue;
461 }
462 let plugin = if existing.is_none() || replaced {
463 if !self.state().loading.insert(file.id.clone()) {
464 continue;
465 }
466 if replaced {
467 self.quiesce(&file.id).await;
468 }
469 let loaded = self.load(&file, &item).await;
470 let (lp, plugin) = match loaded {
471 Err(e) => {
472 self.state().loading.remove(&file.id);
473 if replaced {
474 self.rollback_into(&file.id, &item, &mut records, &mut loaded_files)
475 .await;
476 }
477 tracing::warn!(
478 "pluginhost: failed to load plugin {} from {}: {e}",
479 file.id,
480 file.path.display()
481 );
482 continue;
483 }
484 Ok(pair) => pair,
485 };
486 if replaced && plugin.is_none() {
487 self.discard(lp).await;
488 self.state().loading.remove(&file.id);
489 self.rollback_into(&file.id, &item, &mut records, &mut loaded_files)
490 .await;
491 continue;
492 }
493 {
494 let mut state = self.state();
495 state.loading.remove(&file.id);
496 if replaced && let Some(old) = state.loaded.remove(&file.id) {
497 hot_reloads.push((
498 file.id.clone(),
499 file.version.clone(),
500 file.path.clone(),
501 old.version.clone(),
502 old.path.clone(),
503 ));
504 state.retired.entry(file.id.clone()).or_default().push(old);
505 state.fused.remove(&file.id);
506 remove_runtime_state(&mut state, &file.id);
507 self.publish_hook_activity(&state, &self.snapshot().records);
510 }
511 state.loaded.insert(file.id.clone(), lp);
512 }
513 tracing::info!(plugin_id = %file.id, version = %file.version, path = %file.path.display(), "pluginhost: plugin loaded");
514 match plugin {
515 Some(plugin) => {
516 tracing::info!(plugin_id = %file.id, plugin_name = %plugin.metadata.name, version = %plugin.metadata.version, path = %file.path.display(), "pluginhost: plugin registered");
517 plugin
518 }
519 None => continue,
521 }
522 } else {
523 match self.call_register(&file.id, &item).await {
524 Some(plugin) => plugin,
525 None => continue,
526 }
527 };
528 records.push(Record {
529 id: file.id.clone(),
530 path: file.path.clone(),
531 version: file.version.clone(),
532 priority: item.priority,
533 client: self.client_of(&file.id).expect("loaded above"),
534 plugin,
535 });
536 loaded_files.push(file);
537 }
538
539 sort_records(&mut records);
540 let cleanup = {
541 let mut state = self.state();
542 let cleanup = state.cleanup_files_pending && !loaded_files.is_empty();
543 if !loaded_files.is_empty() {
544 state.cleanup_files_pending = false;
545 }
546 rebuild_active_maps(&mut state, &records);
547 self.store_snapshot(
548 &mut state,
549 Snapshot {
550 enabled: true,
551 records,
552 ..Default::default()
553 },
554 );
555 cleanup
556 };
557 self.refresh_thinking_providers().await;
558 for (id, version, path, old_version, old_path) in hot_reloads {
559 tracing::info!(plugin_id = %id, active_version = %version, active_path = %path.display(), retired_version = %old_version, retired_path = %old_path.display(), "pluginhost: plugin hot reloaded");
560 }
561 if cleanup && let Err(e) = platform::cleanup_unselected(&rc.dir, &loaded_files) {
562 tracing::warn!("pluginhost: failed to clean old plugin files: {e}");
563 }
564 }
565
566 fn deactivate_all(&self) {
567 let mut state = self.state();
568 state.management_routes.clear();
569 state.resource_routes.clear();
570 rebuild_active_maps(&mut state, &[]);
571 self.store_snapshot(&mut state, Snapshot::default());
572 }
573
574 fn client_of(&self, id: &str) -> Option<Arc<GuardedClient>> {
575 self.state().loaded.get(id).map(|lp| lp.client.clone())
576 }
577
578 fn with_loaded_fallbacks(
581 &self,
582 mut files: Vec<PluginFile>,
583 items: &BTreeMap<String, ItemConfig>,
584 desired: &BTreeMap<String, String>,
585 ) -> Vec<PluginFile> {
586 let mut selected: HashSet<String> = files.iter().map(|f| f.id.trim().to_owned()).collect();
587 let state = self.state();
588 for id in desired.keys() {
589 if selected.contains(id) || items.get(id).is_some_and(|item| !item.enabled) {
590 continue;
591 }
592 let Some(lp) = state.loaded.get(id) else {
593 continue;
594 };
595 if lp.path.as_os_str().is_empty() {
596 continue;
597 }
598 files.push(PluginFile {
599 id: id.clone(),
600 path: lp.path.clone(),
601 version: lp.version.trim().to_owned(),
602 });
603 selected.insert(id.clone());
604 }
605 files
606 }
607
608 async fn load(&self, file: &PluginFile, item: &ItemConfig) -> Result<(LoadedPlugin, Option<Plugin>), String> {
611 let instance = Arc::new(CallbackInstance::default());
612 let handler: Arc<dyn CallbackHandler> = Arc::new(self.inner.callbacks.handler());
613 let loader = self.inner.loader.clone();
614 let (file_owned, instance_owned) = (file.clone(), instance.clone());
615 let client = tokio::task::spawn_blocking(move || loader.open(&file_owned, handler, instance_owned))
616 .await
617 .map_err(|e| format!("plugin loader panic: {e}"))??;
618 let client = GuardedClient::new(client, instance);
619 let mut lp = LoadedPlugin {
620 id: file.id.clone(),
621 path: file.path.clone(),
622 version: file.version.clone(),
623 name: String::new(),
624 config_yaml: Vec::new(),
625 plugin: None,
626 registered: false,
627 client,
628 };
629 let plugin = self.register_loaded(&mut lp, item).await;
630 Ok((lp, plugin))
631 }
632
633 async fn register_loaded(&self, lp: &mut LoadedPlugin, item: &ItemConfig) -> Option<Plugin> {
635 let method = if lp.registered {
636 method::PLUGIN_RECONFIGURE
637 } else {
638 method::PLUGIN_REGISTER
639 };
640 let result = rpc::register(&lp.client, method, &item.config_yaml).await;
641 if let Err(CallError::Panic(p)) = &result {
642 self.fuse(&lp.id, method, p);
643 return None;
644 }
645 lp.registered = true;
646 let plugin = match result {
647 Ok(plugin) if plugin.is_valid() => plugin,
648 Ok(_) => {
649 tracing::warn!(
650 "pluginhost: plugin {} returned invalid metadata or no capabilities",
651 lp.id
652 );
653 return None;
654 }
655 Err(e) => {
656 tracing::warn!("pluginhost: plugin {} {method} failed: {e}", lp.id);
657 tracing::warn!(
658 "pluginhost: plugin {} returned invalid metadata or no capabilities",
659 lp.id
660 );
661 return None;
662 }
663 };
664 lp.name = plugin.metadata.name.trim().to_owned();
665 if lp.version.trim().is_empty() {
666 lp.version = plugin.metadata.version.trim().to_owned();
667 }
668 lp.config_yaml = item.config_yaml.clone();
669 lp.plugin = Some(plugin.clone());
670 Some(plugin)
671 }
672
673 async fn call_register(&self, id: &str, item: &ItemConfig) -> Option<Plugin> {
675 let (client, registered) = {
676 let state = self.state();
677 let lp = state.loaded.get(id)?;
678 (lp.client.clone(), lp.registered)
679 };
680 let mut scratch = LoadedPlugin {
681 id: id.to_owned(),
682 path: PathBuf::new(),
683 version: String::new(),
684 name: String::new(),
685 config_yaml: Vec::new(),
686 plugin: None,
687 registered,
688 client,
689 };
690 let plugin = self.register_loaded(&mut scratch, item).await;
691 let mut state = self.state();
692 if let Some(lp) = state.loaded.get_mut(id) {
693 lp.registered |= scratch.registered;
694 if let Some(plugin) = &plugin {
695 lp.name = scratch.name;
696 if lp.version.trim().is_empty() {
697 lp.version = plugin.metadata.version.trim().to_owned();
698 }
699 lp.config_yaml = scratch.config_yaml;
700 lp.plugin = Some(plugin.clone());
701 }
702 }
703 plugin
704 }
705
706 async fn rollback_into(&self, id: &str, item: &ItemConfig, records: &mut Vec<Record>, files: &mut Vec<PluginFile>) {
707 if let Some((record, file)) = self.rollback_replacement(id, item).await {
708 records.push(record);
709 files.push(file);
710 }
711 }
712
713 async fn rollback_replacement(&self, id: &str, item: &ItemConfig) -> Option<(Record, PluginFile)> {
716 let (path, version, previous, config_yaml) = {
717 let state = self.state();
718 let lp = state.loaded.get(id)?;
719 (
720 lp.path.clone(),
721 lp.version.clone(),
722 lp.plugin.clone(),
723 lp.config_yaml.clone(),
724 )
725 };
726 let mut item = item.clone();
727 if !config_yaml.is_empty() {
728 item.config_yaml = config_yaml;
729 }
730 let plugin = match self.call_register(id, &item).await {
731 Some(plugin) => {
732 let mut state = self.state();
733 state.fused.remove(id);
734 self.publish_hook_activity(&state, &self.snapshot().records);
735 plugin
736 }
737 None => previous?,
738 };
739 if !plugin.is_valid() {
740 return None;
741 }
742 Some((
743 Record {
744 id: id.to_owned(),
745 path: path.clone(),
746 version: version.clone(),
747 priority: item.priority,
748 client: self.client_of(id)?,
749 plugin,
750 },
751 PluginFile {
752 id: id.to_owned(),
753 path,
754 version,
755 },
756 ))
757 }
758
759 async fn quiesce(&self, id: &str) -> bool {
761 let Some(client) = self.client_of(id) else {
762 return false;
763 };
764 let result: Result<rpc::Empty, _> = rpc::call(&client, method::PLUGIN_QUIESCE, &rpc::Empty {}).await;
765 match self.fuse_on_panic(id, method::PLUGIN_QUIESCE, result) {
766 Ok(_) => true,
767 Err(e) => {
768 if quiesce_unsupported(&e) {
769 tracing::debug!(plugin_id = %id, "pluginhost: plugin quiesce unsupported: {e}");
770 } else {
771 tracing::warn!(plugin_id = %id, "pluginhost: plugin quiesce failed: {e}");
772 }
773 false
774 }
775 }
776 }
777
778 async fn discard(&self, lp: LoadedPlugin) {
779 self.inner.callbacks.close_instance(&lp.id, lp.client.instance());
780 lp.client.shutdown(None).await;
781 }
782
783 pub async fn unload_plugin(&self, id: &str, wait: Option<Duration>) -> bool {
786 self.spawn_unload(id, wait, None).await.unwrap_or(false)
787 }
788
789 pub async fn unload_plugin_until(&self, id: &str, cancel: &tokio_util::sync::CancellationToken) -> bool {
793 self.spawn_unload(id, None, Some(cancel.clone())).await.unwrap_or(false)
794 }
795
796 #[inline(never)]
799 fn spawn_unload(
800 &self,
801 id: &str,
802 wait: Option<Duration>,
803 cancel: Option<tokio_util::sync::CancellationToken>,
804 ) -> tokio::task::JoinHandle<bool> {
805 let host = self.clone();
806 let id = id.to_owned();
807 tokio::spawn(async move { host.unload_plugin_inner(&id, wait, cancel).await })
808 }
809
810 async fn unload_plugin_inner(
811 &self,
812 id: &str,
813 wait: Option<Duration>,
814 cancel: Option<tokio_util::sync::CancellationToken>,
815 ) -> bool {
816 let id = id.trim();
817 if id.is_empty() {
818 return false;
819 }
820 let cancelled = || async {
822 match &cancel {
823 Some(cancel) => cancel.cancelled().await,
824 None => std::future::pending().await,
825 }
826 };
827 let _apply = tokio::select! {
829 biased;
830 apply = self.inner.apply.lock() => apply,
831 () = cancelled() => return false,
832 };
833 let targets = {
834 let mut state = self.state();
835 let mut targets: Vec<LoadedPlugin> = state.loaded.remove(id).into_iter().collect();
836 targets.extend(state.retired.remove(id).unwrap_or_default());
837 let loading = state.loading.contains(id);
838 if targets.is_empty() && !loading {
839 return false;
840 }
841 state.fused.remove(id);
842 state.active_versions.remove(id);
843 state.active_paths.remove(id);
844 for target in &targets {
845 state.file_versions.remove(&clean_path(&target.path));
846 }
847 remove_runtime_state(&mut state, id);
848 #[cfg(test)]
849 tests::unload_hook(id);
850 let snapshot = self.snapshot();
851 let records = snapshot.records.iter().filter(|r| r.id != id).cloned().collect();
852 self.store_snapshot(
853 &mut state,
854 Snapshot {
855 enabled: snapshot.enabled,
856 records,
857 ..Default::default()
858 },
859 );
860 targets
861 };
862 self.inner.callbacks.close_plugin(id);
863 self.refresh_thinking_providers().await;
864 for target in targets {
865 let (name, version, path) = (target.name.clone(), target.version.clone(), target.path.clone());
866 self.inner.callbacks.close_instance(id, target.client.instance());
867 tokio::select! {
870 biased;
871 () = target.client.shutdown(wait) => {}
872 () = cancelled() => {}
873 }
874 tracing::info!(plugin_id = %id, plugin_name = %name, version = %version, path = %path.display(), "pluginhost: plugin unloaded");
875 }
876 true
877 }
878
879 pub async fn shutdown_all(&self, wait: Option<Duration>) {
881 let host = self.clone();
882 let _ = tokio::spawn(async move { host.shutdown_all_inner(wait).await }).await;
883 }
884
885 async fn shutdown_all_inner(&self, wait: Option<Duration>) {
886 let _apply = self.inner.apply.lock().await;
887 let targets: Vec<LoadedPlugin> = {
888 let mut state = self.state();
889 let mut targets: Vec<LoadedPlugin> = state.loaded.drain().map(|(_, lp)| lp).collect();
890 targets.extend(state.retired.drain().flat_map(|(_, lps)| lps));
891 state.management_routes.clear();
892 state.resource_routes.clear();
893 state.executor_model_client_ids.clear();
894 state.model_providers.clear();
895 state.model_registrations.clear();
896 state.provider_models.clear();
897 state.executor_providers.clear();
898 state.command_line_flags.clear();
899 state.command_line_hits.clear();
900 state.file_versions.clear();
901 state.active_versions.clear();
902 state.active_paths.clear();
903 self.store_snapshot(&mut state, Snapshot::default());
904 targets
905 };
906 self.state().thinking_providers.clear();
907 cpa_common::thinking::clear_plugin_providers();
908 self.inner.callbacks.close_all();
909 for target in targets {
910 self.inner
911 .callbacks
912 .close_instance(&target.id, target.client.instance());
913 target.client.shutdown(wait).await;
914 tracing::info!(plugin_id = %target.id, plugin_name = %target.name, version = %target.version, path = %target.path.display(), "pluginhost: plugin unloaded");
915 }
916 }
917
918 pub fn record(&self, id: &str) -> Option<Record> {
920 self.active_records()
921 .into_iter()
922 .find(|r| r.id == id && !self.is_fused(&r.id))
923 }
924
925 pub async fn call<T: GoJson, R: GoJson>(&self, record: &Record, method: &str, request: &R) -> Result<T, CallError> {
927 let result = rpc::call(&record.client, method, request).await;
928 self.fuse_on_panic(&record.id, method, result)
929 }
930
931 pub async fn call_with_callback<T: GoJson, R: crate::gojson::GoStruct>(
935 &self,
936 record: &Record,
937 method: &str,
938 request: &R,
939 scope: &crate::callbacks::RequestScope,
940 ) -> Result<T, CallError> {
941 let guard = self.open_callback(record, scope);
942 let raw = rpc::encode_with_callback(request, guard.id());
943 let result = self.call_raw(record, method, raw).await;
944 drop(guard);
945 result
946 }
947
948 pub fn call_blocking<T: GoJson, R: GoJson>(
950 &self,
951 record: &Record,
952 method: &str,
953 request: &R,
954 ) -> Result<T, CallError> {
955 let result = rpc::call_raw_blocking(&record.client, method, &crate::gojson::to_vec(request));
956 self.fuse_on_panic(&record.id, method, result)
957 }
958
959 pub fn call_with_callback_blocking<T: GoJson, R: crate::gojson::GoStruct>(
961 &self,
962 record: &Record,
963 method: &str,
964 request: &R,
965 scope: &crate::callbacks::RequestScope,
966 ) -> Result<T, CallError> {
967 let guard = self.open_callback(record, scope);
968 let raw = rpc::encode_with_callback(request, guard.id());
969 let result = rpc::call_raw_blocking(&record.client, method, &raw);
970 drop(guard);
971 self.fuse_on_panic(&record.id, method, result)
972 }
973
974 pub fn open_callback(
976 &self,
977 record: &Record,
978 scope: &crate::callbacks::RequestScope,
979 ) -> crate::callbacks::ContextGuard {
980 self.inner
981 .callbacks
982 .open(&record.id, Some(record.client.instance().clone()), scope.clone())
983 }
984
985 pub async fn call_raw<T: GoJson>(&self, record: &Record, method: &str, request: Vec<u8>) -> Result<T, CallError> {
987 let result = rpc::call_raw(&record.client, method, request).await;
988 self.fuse_on_panic(&record.id, method, result)
989 }
990}
991
992fn quiesce_unsupported(e: &CallError) -> bool {
994 if matches!(
995 e.code().to_ascii_lowercase().as_str(),
996 "unknown_method" | "method_not_found" | "unsupported_method"
997 ) {
998 return true;
999 }
1000 let message = e.to_string().trim().go_lower();
1001 [
1002 "unknown method",
1003 "method not found",
1004 "unsupported method",
1005 "method unsupported",
1006 "method is not supported",
1007 "method not supported",
1008 ]
1009 .iter()
1010 .any(|needle| message.contains(needle))
1011}
1012
1013fn sort_records(records: &mut [Record]) {
1015 records.sort_by(|a, b| b.priority.cmp(&a.priority).then_with(|| a.id.cmp(&b.id)));
1016}
1017
1018fn rebuild_active_maps(state: &mut State, records: &[Record]) {
1019 state.file_versions.clear();
1020 state.active_versions.clear();
1021 state.active_paths.clear();
1022 for record in records {
1023 let id = record.id.trim();
1024 let path = clean_path(&record.path);
1025 if id.is_empty() || path.as_os_str().is_empty() {
1026 continue;
1027 }
1028 state
1029 .file_versions
1030 .insert(path.clone(), record.version.trim().to_owned());
1031 state
1032 .active_versions
1033 .insert(id.to_owned(), record.version.trim().to_owned());
1034 state.active_paths.insert(id.to_owned(), path);
1035 }
1036}
1037
1038fn remove_runtime_state(state: &mut State, id: &str) {
1040 state.management_routes.retain(|_, r| r.plugin_id != id);
1041 state.resource_routes.retain(|_, r| r.plugin_id != id);
1042 let flags = &mut state.command_line_flags;
1043 let hits = &mut state.command_line_hits;
1044 flags.retain(|name, f| {
1045 let keep = f.plugin_id != id;
1046 if !keep {
1047 hits.remove(name);
1048 }
1049 keep
1050 });
1051 if let Some(registration) = state.model_registrations.remove(id) {
1052 state.provider_models.remove(®istration.provider);
1053 }
1054 state.model_providers.remove(id);
1055}
1056
1057pub fn bytes_of(v: &[u8]) -> Bytes {
1059 Bytes::copy_from_slice(v)
1060}
1061
1062#[cfg(test)]
1063mod tests {
1064 use super::*;
1065 use std::sync::atomic::{AtomicUsize, Ordering};
1066
1067 type Hook = Box<dyn Fn() + Send + Sync>;
1068 static UNLOAD_HOOK: Mutex<Option<(&'static str, Hook)>> = Mutex::new(None);
1070
1071 pub(super) fn unload_hook(id: &str) {
1074 if let Some((_, hook)) = lock(&UNLOAD_HOOK).as_ref().filter(|(target, _)| *target == id) {
1075 hook();
1076 }
1077 }
1078
1079 struct OneLoader(Arc<dyn PluginClient>);
1080
1081 impl Loader for OneLoader {
1082 fn open(
1083 &self,
1084 _: &PluginFile,
1085 _: Arc<dyn CallbackHandler>,
1086 _: Arc<CallbackInstance>,
1087 ) -> Result<Arc<dyn PluginClient>, String> {
1088 Ok(self.0.clone())
1089 }
1090 }
1091
1092 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
1097 async fn unload_publishes_its_snapshot_inside_the_state_lock() {
1098 let dir = std::env::temp_dir().join(format!("cpa-plugin-fence-{}", std::process::id()));
1099 std::fs::create_dir_all(&dir).unwrap();
1100 std::fs::write(dir.join(format!("fence{}", platform::extension(platform::goos()))), b"").unwrap();
1101 let host = Host::with_loader(Arc::new(OneLoader(Arc::new(FakeClient))));
1102 let yaml = format!(
1103 "plugins:\n enabled: true\n dir: {}\n configs:\n fence:\n enabled: true\n",
1104 dir.display()
1105 );
1106 host.apply_config(Arc::new(Config::parse(&yaml).unwrap())).await;
1107 assert!(host.plugin_registered("fence"));
1108 let seen = Arc::new(Mutex::new(None));
1110 *lock(&UNLOAD_HOOK) = Some({
1111 let (host, seen) = (host.clone(), seen.clone());
1112 (
1113 "fence",
1114 Box::new(move || {
1115 let stale = host.snapshot().records.iter().any(|r| r.id == "fence");
1116 let lock_free = host.inner.state.try_lock().is_ok();
1117 *lock(&seen) = Some((stale, lock_free));
1118 }),
1119 )
1120 });
1121 assert!(host.unload_plugin("fence", None).await);
1122 *lock(&UNLOAD_HOOK) = None;
1123 assert_eq!(
1124 *lock(&seen),
1125 Some((true, false)),
1126 "the old snapshot is visible only while the state lock is held"
1127 );
1128 assert!(host.snapshot().records.is_empty());
1129 let _ = std::fs::remove_dir_all(&dir);
1130 }
1131
1132 struct HeldClient {
1134 held: Arc<(Mutex<bool>, std::sync::Condvar)>,
1135 started: Arc<AtomicUsize>,
1136 }
1137
1138 impl PluginClient for HeldClient {
1139 fn call(&self, method: &str, request: &[u8]) -> Result<Bytes, String> {
1140 FakeClient.call(method, request)
1141 }
1142 fn shutdown(&self) {
1143 self.started.fetch_add(1, Ordering::SeqCst);
1144 let (held, cv) = &*self.held;
1145 let mut held = lock(held);
1146 while *held {
1147 held = cv.wait(held).unwrap();
1148 }
1149 }
1150 }
1151
1152 async fn within<T>(what: &str, fut: impl std::future::Future<Output = T>) -> T {
1153 tokio::time::timeout(Duration::from_secs(5), fut)
1154 .await
1155 .unwrap_or_else(|_| panic!("timed out waiting for {what}"))
1156 }
1157
1158 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
1163 async fn a_cancelled_home_unload_releases_the_host() {
1164 let dir = std::env::temp_dir().join(format!("cpa-plugin-held-{}", std::process::id()));
1165 std::fs::create_dir_all(&dir).unwrap();
1166 std::fs::write(dir.join(format!("held{}", platform::extension(platform::goos()))), b"").unwrap();
1167 let held = Arc::new((Mutex::new(false), std::sync::Condvar::new()));
1168 let started = Arc::new(AtomicUsize::new(0));
1169 let client = || {
1170 Arc::new(HeldClient {
1171 held: held.clone(),
1172 started: started.clone(),
1173 })
1174 };
1175 let host = Host::with_loader(Arc::new(OneLoader(client())));
1176 let config = |enabled: bool| {
1177 let yaml = format!(
1178 "plugins:\n enabled: {enabled}\n dir: {}\n configs:\n held:\n enabled: true\n",
1179 dir.display()
1180 );
1181 Arc::new(Config::parse(&yaml).unwrap())
1182 };
1183 host.apply_config(config(true)).await;
1184 assert!(host.plugin_registered("held"));
1185 let retired = LoadedPlugin {
1186 id: "held".into(),
1187 path: dir.join("held-old"),
1188 version: "0".into(),
1189 name: "n".into(),
1190 config_yaml: Vec::new(),
1191 plugin: None,
1192 registered: true,
1193 client: GuardedClient::new(client(), Arc::new(CallbackInstance::default())),
1194 };
1195 host.state().retired.entry("held".into()).or_default().push(retired);
1196 *lock(&held.0) = true;
1197 let cancel = tokio_util::sync::CancellationToken::new();
1198 let unload = tokio::spawn({
1199 let (host, cancel) = (host.clone(), cancel.clone());
1200 async move { crate::homeplugins::PluginRuntime::unload_plugin(&host, "held", &cancel).await }
1201 });
1202 within("the first shutdown", async {
1203 while started.load(Ordering::SeqCst) < 1 {
1204 tokio::time::sleep(Duration::from_millis(5)).await;
1205 }
1206 })
1207 .await;
1208 assert!(!host.plugin_registered("held"));
1209 assert!(
1210 host.inner.apply.try_lock().is_err(),
1211 "the hanging unload holds the host"
1212 );
1213 cancel.cancel();
1214 assert!(
1215 within("the cancelled unload", unload).await.unwrap(),
1216 "the cancelled unload panicked or reported nothing unloaded"
1217 );
1218 within("the retired instance's shutdown", async {
1220 while started.load(Ordering::SeqCst) < 2 {
1221 tokio::time::sleep(Duration::from_millis(5)).await;
1222 }
1223 })
1224 .await;
1225 within(
1226 "a config apply after the cancelled unload",
1227 host.apply_config(config(false)),
1228 )
1229 .await;
1230 *lock(&held.0) = false;
1231 held.1.notify_all();
1232 let _ = std::fs::remove_dir_all(&dir);
1233 }
1234
1235 struct FakeClient;
1237
1238 impl PluginClient for FakeClient {
1239 fn call(&self, method: &str, _: &[u8]) -> Result<Bytes, String> {
1240 Ok(match method {
1241 method::PLUGIN_REGISTER | method::PLUGIN_RECONFIGURE => Bytes::from_static(
1242 br#"{"ok":true,"result":{"schema_version":6,"metadata":{"Name":"n","Version":"1","Author":"a","GitHubRepository":"r"},"capabilities":{"usage_plugin":true}}}"#,
1243 ),
1244 _ => Bytes::from_static(br#"{"ok":true,"result":{}}"#),
1245 })
1246 }
1247 fn shutdown(&self) {}
1248 }
1249
1250 struct GateLoader {
1252 release: Arc<(Mutex<bool>, std::sync::Condvar)>,
1253 opens: AtomicUsize,
1254 }
1255
1256 impl Loader for GateLoader {
1257 fn open(
1258 &self,
1259 _: &PluginFile,
1260 _: Arc<dyn CallbackHandler>,
1261 _: Arc<CallbackInstance>,
1262 ) -> Result<Arc<dyn PluginClient>, String> {
1263 self.opens.fetch_add(1, Ordering::SeqCst);
1264 let (open, cv) = &*self.release;
1265 let mut open = lock(open);
1266 while !*open {
1267 open = cv.wait(open).unwrap();
1268 }
1269 Ok(Arc::new(FakeClient))
1270 }
1271 }
1272
1273 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
1276 async fn abandoned_apply_still_completes() {
1277 let dir = std::env::temp_dir().join(format!("cpa-plugin-cancel-{}", std::process::id()));
1278 std::fs::create_dir_all(&dir).unwrap();
1279 std::fs::write(dir.join(format!("p{}", platform::extension(platform::goos()))), b"").unwrap();
1280 let release = Arc::new((Mutex::new(false), std::sync::Condvar::new()));
1281 let loader = Arc::new(GateLoader {
1282 release: release.clone(),
1283 opens: AtomicUsize::new(0),
1284 });
1285 let host = Host::with_loader(loader.clone());
1286 let yaml = format!(
1287 "plugins:\n enabled: true\n dir: {}\n configs:\n p:\n enabled: true\n",
1288 dir.display()
1289 );
1290 let cfg = Arc::new(Config::parse(&yaml).unwrap());
1291 let abandoned = tokio::time::timeout(Duration::from_millis(50), host.apply_config(cfg.clone())).await;
1292 assert!(abandoned.is_err(), "open is still blocked");
1293 *lock(&release.0) = true;
1294 release.1.notify_all();
1295 host.apply_config(cfg).await;
1296 assert!(host.plugin_registered("p"));
1297 assert_eq!(
1298 loader.opens.load(Ordering::SeqCst),
1299 1,
1300 "the abandoned load was reused, not repeated"
1301 );
1302 let _ = std::fs::remove_dir_all(&dir);
1303 }
1304
1305 struct CapsClient {
1307 caps: &'static str,
1308 gate: Option<Arc<(Mutex<bool>, std::sync::Condvar)>>,
1309 }
1310
1311 impl PluginClient for CapsClient {
1312 fn call(&self, method: &str, _: &[u8]) -> Result<Bytes, String> {
1313 if method != method::PLUGIN_REGISTER && method != method::PLUGIN_RECONFIGURE {
1314 return Ok(Bytes::from_static(br#"{"ok":true,"result":{}}"#));
1315 }
1316 if let Some((open, cv)) = self.gate.as_deref() {
1317 let mut open = lock(open);
1318 while !*open {
1319 open = cv.wait(open).unwrap();
1320 }
1321 }
1322 Ok(Bytes::from(format!(
1323 r#"{{"ok":true,"result":{{"schema_version":6,"metadata":{{"Name":"n","Version":"1","Author":"a","GitHubRepository":"r"}},"capabilities":{{{}}}}}}}"#,
1324 self.caps
1325 )))
1326 }
1327 fn shutdown(&self) {}
1328 }
1329
1330 struct HookLoader(Arc<(Mutex<bool>, std::sync::Condvar)>);
1332
1333 impl Loader for HookLoader {
1334 fn open(
1335 &self,
1336 file: &PluginFile,
1337 _: Arc<dyn CallbackHandler>,
1338 _: Arc<CallbackInstance>,
1339 ) -> Result<Arc<dyn PluginClient>, String> {
1340 Ok(Arc::new(match file.id.as_str() {
1341 "a" => CapsClient {
1342 caps: r#""request_normalizer":true"#,
1343 gate: None,
1344 },
1345 _ => CapsClient {
1346 caps: r#""usage_plugin":true"#,
1347 gate: Some(self.0.clone()),
1348 },
1349 }))
1350 }
1351 }
1352
1353 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
1356 async fn a_hot_reload_unfusing_a_hook_plugin_activates_the_hooks_at_once() {
1357 let dir = std::env::temp_dir().join(format!("cpa-plugin-unfuse-{}", std::process::id()));
1358 std::fs::create_dir_all(&dir).unwrap();
1359 let ext = platform::extension(platform::goos());
1360 std::fs::write(dir.join(format!("a-v1{ext}")), b"").unwrap();
1361 std::fs::write(dir.join(format!("b{ext}")), b"").unwrap();
1362 let gate = Arc::new((Mutex::new(true), std::sync::Condvar::new()));
1363 let host = Host::with_loader(Arc::new(HookLoader(gate.clone())));
1364 let yaml = format!(
1365 "plugins:\n enabled: true\n dir: {}\n configs:\n a:\n enabled: true\n b:\n enabled: true\n",
1366 dir.display()
1367 );
1368 let cfg = Arc::new(Config::parse(&yaml).unwrap());
1369 host.apply_config(cfg.clone()).await;
1370 cpa_translate::hooks::set_plugin_hooks(Some(host.translator_hooks()));
1371 assert!(cpa_translate::hooks::plugin_hooks_active());
1372 host.fuse("a", "RequestNormalizer.NormalizeRequest", "test");
1373 assert!(!cpa_translate::hooks::plugin_hooks_active());
1374
1375 *lock(&gate.0) = false;
1376 struct Reopen(Arc<(Mutex<bool>, std::sync::Condvar)>);
1378 impl Drop for Reopen {
1379 fn drop(&mut self) {
1380 *lock(&self.0.0) = true;
1381 self.0.1.notify_all();
1382 }
1383 }
1384 let reopen = Reopen(gate.clone());
1385 std::fs::write(dir.join(format!("a-v2{ext}")), b"").unwrap();
1386 let apply = tokio::spawn({
1387 let host = host.clone();
1388 async move { host.apply_config(cfg).await }
1389 });
1390 let unfused = async {
1391 while host.is_fused("a") {
1392 tokio::time::sleep(Duration::from_millis(5)).await;
1393 }
1394 };
1395 tokio::time::timeout(Duration::from_secs(10), unfused)
1396 .await
1397 .expect("a reloads");
1398 assert!(!apply.is_finished(), "b's registration is still blocked");
1399 assert!(
1400 cpa_translate::hooks::plugin_hooks_active(),
1401 "a is eligible before b registers"
1402 );
1403
1404 drop(reopen);
1405 apply.await.unwrap();
1406 assert!(cpa_translate::hooks::plugin_hooks_active());
1407 cpa_translate::hooks::set_plugin_hooks(None);
1408 assert!(
1409 !cpa_translate::hooks::plugin_hooks_active(),
1410 "an empty slot clears the flag"
1411 );
1412 let _ = std::fs::remove_dir_all(&dir);
1413 }
1414}