Skip to main content

cpa_plugin/
host.rs

1//! The plugin host lifecycle (internal/pluginhost/host.go, snapshot.go).
2//!
3//! [`Host::apply_config`] discovers plugin files, loads new ones (`dlopen` and
4//! `plugin.register`), reconfigures loaded ones (`plugin.reconfigure`), hot-reloads a
5//! changed file (`plugin.quiesce` on the old instance, rollback when the new one fails,
6//! the old instance retired but still loaded) and publishes an immutable snapshot of
7//! active plugins ordered by priority (descending) then ID. Disabling plugins globally
8//! empties the snapshot but keeps libraries loaded, as Go does. A plugin whose host-side
9//! adapter panicked is fused: skipped until its file changes.
10
11use 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
29/// Opens plugin libraries. The production loader is [`NativeLoader`].
30pub 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
39/// `dlopen`-based loader (Unix). Other platforms report plugins as unsupported.
40pub 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    // ponytail: Go's Windows loader shadow-copies the DLL and calls through
55    // syscall.NewCallback; not ported. Same error as Go builds without cgo.
56    #[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
70/// Go `SupportPluginHeaderValue`: `1` when this build can load native plugins.
71pub 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/// One active plugin in a snapshot (Go `capabilityRecord`).
87#[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/// Active plugins, highest priority first.
108#[derive(Debug, Default)]
109pub struct Snapshot {
110    pub enabled: bool,
111    pub records: Vec<Record>,
112    /// `quota.describe` supported providers per plugin, asked once per snapshot.
113    pub(crate) quota_supported: Mutex<HashMap<String, Vec<String>>>,
114}
115
116/// Go `RegisteredPluginInfo`.
117#[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/// Go `RegisteredPluginMenu`.
130#[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    /// Thinking provider name to owning plugin ID.
151    pub thinking_providers: BTreeMap<String, String>,
152    /// Go `modelProviders`: plugin ID to the provider its models registered under.
153    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    /// Go `commandLineFlags` and `commandLineHits`.
159    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    /// Set once this host's translator hooks are handed out (`translator_hooks`): from
170    /// then on its lifecycle keeps cpa-translate's hook flag current.
171    pub(crate) hooks_installed: std::sync::atomic::AtomicBool,
172    /// The same for the auth parser (`auth_parser`) and cpa-core's auth-parser flag.
173    pub(crate) auth_parser_installed: std::sync::atomic::AtomicBool,
174    /// What `auth_parser` hands out.
175    pub(crate) auth_parser: std::sync::OnceLock<Arc<dyn cpa_core::config::credentials::PluginAuthParser>>,
176    /// The `auth.parse` calls in flight: the plugin instance asked, the auth file's
177    /// cleaned absolute path, and whether a `host.auth.save` asked (`auth::Parsing`).
178    pub(crate) auth_parses: Mutex<Vec<(Arc<CallbackInstance>, PathBuf, bool)>>,
179}
180
181/// The plugin host. Cheap to clone.
182#[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
191/// Go `cleanPluginPath`.
192fn 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
200/// Go `normalizeProviderID`.
201pub 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    /// Publishes a snapshot. Takes the state guard so that publication and the active
248    /// maps change in one critical section (Go `h.mu`): a registration that compares
249    /// snapshots under the state lock then never commits against a half-applied change.
250    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    /// The config last applied.
264    pub fn config(&self) -> Option<Arc<Config>> {
265        self.state().config.clone()
266    }
267
268    /// Records still current: a record whose plugin was unloaded or replaced since the
269    /// snapshot was taken is skipped (Go `activeRecordsFromSnapshot`).
270    pub fn active_records(&self) -> Vec<Record> {
271        self.current_records(&self.snapshot())
272    }
273
274    /// Go `activeRecordsFromSnapshot`: the snapshot's records that are still current.
275    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    /// Whether a record may be called right now: not fused and still current. Go checks
285    /// this at every call, after earlier plugins in the same loop have run.
286    pub fn live(&self, record: &Record) -> bool {
287        !self.is_fused(&record.id) && self.record_current(record)
288    }
289
290    /// Go `recordCurrent` / `pluginIdentityCurrent`.
291    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    /// Go `fusePlugin`: a host-side panic while serving the plugin disables it until its
308    /// file changes.
309    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        // Go `thinking.UnregisterPluginProviders`.
313        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    /// Fuses the plugin when `result` is a panic, passing the result through.
321    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    /// Go `PluginLoaded`: a library for `id` is still loaded (active or retired).
329    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    /// Go `PluginBusy`: loaded or still loading.
336    pub fn plugin_busy(&self, id: &str) -> bool {
337        self.plugin_loaded(id) || self.state().loading.contains(id.trim())
338    }
339
340    /// Go `PluginRegistered`: active in the current snapshot.
341    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    /// Go `RegisteredPlugins`.
347    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    /// Go `ApplyConfig`.
399    ///
400    /// ponytail: runs to completion on its own task even if the caller stops waiting, so
401    /// a dropped future can never strand a half-loaded plugin; Go instead aborts on
402    /// context cancellation and rolls the load back. Add cancellation with rollback if
403    /// shutdown latency during a slow `plugin.register` ever matters.
404    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                        // The unfused plugin is eligible now, not once the remaining
508                        // plugins have registered and the snapshot is published.
509                        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                    // Loaded but not registered: stays loaded, retried on the next apply.
520                    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    /// Go `withLoadedPluginFallbacks`: keep running the loaded version of a plugin whose
579    /// desired version has no file yet.
580    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    /// Opens and registers one file. `Ok((lp, None))` is a loaded library whose
609    /// registration failed or was invalid.
610    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    /// Go `callRegister` on a plugin not yet in the loaded map.
634    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    /// Go `callRegister` for a plugin already in the loaded map.
674    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    /// Go `rollbackReplacement`: re-register the still-loaded old instance with its last
714    /// config; keep its previous registration when that fails.
715    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    /// Go `callQuiesce`, before a replacement loads.
760    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    /// Go `UnloadPluginContext`: detach `id` from the runtime, then close every loaded
784    /// instance of it, waiting up to `wait` for running calls.
785    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    /// Go `UnloadPluginContext` with a cancellable context: cancelling `cancel` stops
790    /// waiting for the apply lock (`false`) or for the plugin to shut down, and releases
791    /// the lock; the shutdown itself still completes on its own thread.
792    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    /// Not inlined, so callers in other crates share one instance of the spawned unload
797    /// instead of compiling their own (about 25 KB each in the release binary).
798    #[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        // A fresh future for each wait: one that completed must not be polled again.
821        let cancelled = || async {
822            match &cancel {
823                Some(cancel) => cancel.cancelled().await,
824                None => std::future::pending().await,
825            }
826        };
827        // Go `lockApply`: an available lock is taken even when already cancelled.
828        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            // The first poll detaches the client and starts its shutdown thread, also
868            // once cancelled.
869            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    /// Go `ShutdownAllContext`.
880    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    /// Looks up an active, unfused record by plugin ID.
919    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    /// One typed RPC to an active plugin, fusing it on a host-side panic.
926    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    /// One RPC that lets the plugin call back: opens a callback context for the record's
932    /// instance, sends its ID as `host_callback_id`, and closes it when the call returns
933    /// (Go `openHostCallbackContext` around adapter calls).
934    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    /// [`Host::call`] for synchronous callers; see [`GuardedClient::call_blocking`].
949    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    /// [`Host::call_with_callback`] for synchronous callers.
960    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    /// Opens a callback context for `record`'s instance.
975    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    /// One RPC with a pre-encoded request.
986    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
992/// Go `quiesceUnsupported`.
993fn 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
1013/// Go `sortRecords`.
1014fn 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
1038/// Go `removePluginRuntimeStateLocked`.
1039fn 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(&registration.provider);
1053    }
1054    state.model_providers.remove(id);
1055}
1056
1057/// Payload bytes for an RPC field that Go fills with `bytes.Clone`.
1058pub 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    /// Keyed by plugin ID, so another test's unload never fires it.
1069    static UNLOAD_HOOK: Mutex<Option<(&'static str, Hook)>> = Mutex::new(None);
1070
1071    /// Runs inside `unload_plugin` after its state change, before the snapshot is
1072    /// published.
1073    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    /// Go publishes the active maps and the snapshot under one lock. Registrations
1093    /// compare snapshots and commit under the state lock, so while an unload has
1094    /// changed the state but not yet published its snapshot, that lock must be held:
1095    /// otherwise a registration that took the old snapshot commits stale results.
1096    #[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        // (snapshot still lists the plugin, state lock free) observed inside the window.
1109        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    /// [`FakeClient`] whose shutdown counts its start, then blocks while `held` is set.
1133    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    /// Go `UnloadPluginContext` from a Home delete (`deletePluginArtifact`): cancelling
1159    /// the delete while the plugin's shutdown hangs ends the unload and releases the
1160    /// apply lock, so a later config apply proceeds. Every instance, the loaded one and
1161    /// a retired one still draining, is detached and has its shutdown started.
1162    #[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        // The retired instance's shutdown runs on its own thread.
1219        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    /// A plugin that registers with one capability.
1236    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    /// Blocks `open` until released; counts opens.
1251    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    /// An apply abandoned while `open` blocks must not strand the
1274    /// plugin in `loading`; it completes and the plugin is active afterwards.
1275    #[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    /// Registers with `caps`; while `gate` is closed, registration blocks.
1306    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    /// Plugin `a` offers a request normalizer; `b` registers behind `gate`.
1331    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    /// A hot reload that unfuses a translator plugin turns cpa-translate's hook flag
1354    /// on at once, while later plugins are still registering.
1355    #[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        // Reopens the gate even when an assertion fails, so the runtime can shut down.
1377        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}