proto_pdk_api/
hooks.rs

1use crate::api::PluginContext;
2use rustc_hash::FxHashMap;
3use std::path::PathBuf;
4use warpgate_api::*;
5
6/// Enumeration of all available hook functions that can be implemented by plugins.
7///
8/// Hook functions are called at specific points during proto operations to allow
9/// plugins to customize behavior, perform setup/cleanup, or modify the environment.
10#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
11pub enum HookFunction {
12    /// Pre-install hook.
13    ///
14    /// Called before a tool installation begins, allowing plugins to perform setup
15    /// tasks, validate prerequisites, or modify the installation environment.
16    ///
17    /// **Input:** [`InstallHook`] | **Output:** None
18    PreInstall,
19
20    /// Post-install hook.
21    ///
22    /// Called after a tool installation completes successfully, allowing plugins
23    /// to perform cleanup tasks, configure the tool, or set up additional resources.
24    ///
25    /// **Input:** [`InstallHook`] | **Output:** None
26    PostInstall,
27
28    /// Pre-run hook.
29    ///
30    /// Called before executing a tool's executable, allowing plugins to modify environment
31    /// variables, validate runtime conditions, or perform setup.
32    ///
33    /// **Input:** [`RunHook`] | **Output:** [`RunHookResult`]
34    PreRun,
35}
36
37impl HookFunction {
38    /// Get the string representation of the hook function name.
39    ///
40    /// This returns the actual function name that should be used when calling
41    /// the hook function via WASM.
42    pub fn as_str(&self) -> &'static str {
43        match self {
44            Self::PreInstall => "pre_install",
45            Self::PostInstall => "post_install",
46            Self::PreRun => "pre_run",
47        }
48    }
49}
50
51impl AsRef<str> for HookFunction {
52    fn as_ref(&self) -> &str {
53        self.as_str()
54    }
55}
56
57api_struct!(
58    /// Input passed to the `pre_install` and `post_install` hooks,
59    /// while a `proto install` command is running.
60    pub struct InstallHook {
61        /// Current tool context.
62        pub context: PluginContext,
63
64        /// Whether the install was forced or not.
65        pub forced: bool,
66
67        /// Arguments passed after `--` that was directly passed to the tool's executable.
68        pub passthrough_args: Vec<String>,
69
70        /// Whether the resolved version was pinned.
71        pub pinned: bool,
72
73        /// Hide install output.
74        pub quiet: bool,
75    }
76);
77
78api_struct!(
79    /// Input passed to the `pre_run` hook, before a `proto run` command
80    /// or language executable is ran.
81    pub struct RunHook {
82        /// Current tool context.
83        pub context: PluginContext,
84
85        /// Path to the global packages directory for the tool, if found.
86        pub globals_dir: Option<VirtualPath>,
87
88        /// A prefix applied to the file names of globally installed packages.
89        pub globals_prefix: Option<String>,
90
91        /// Arguments passed after `--` that was directly passed to the tool's executable.
92        pub passthrough_args: Vec<String>,
93    }
94);
95
96api_struct!(
97    /// Output returned from the `pre_run` hook.
98    #[serde(default)]
99    pub struct RunHookResult {
100        /// Additional arguments to append to the running command.
101        #[serde(skip_serializing_if = "Option::is_none")]
102        pub args: Option<Vec<String>>,
103
104        /// Additional environment variables to pass to the running command.
105        /// Will overwrite any existing variables.
106        #[serde(skip_serializing_if = "Option::is_none")]
107        pub env: Option<FxHashMap<String, String>>,
108
109        /// Additional paths to prepend to `PATH` for the running command.
110        #[serde(skip_serializing_if = "Option::is_none")]
111        pub paths: Option<Vec<PathBuf>>,
112    }
113);
proto_pdk_api/hooks.rs

proto_pdk_api/
hooks.rs
