Allow plugins to receive configuration from the nushell configuration (#10955)

# Description

When nushell calls a plugin it now sends a configuration `Value` from
the nushell config under `$env.config.plugins.PLUGIN_SHORT_NAME`. This
allows plugin authors to read configuration provided by plugin users.

The `PLUGIN_SHORT_NAME` must match the registered filename after
`nu_plugin_`. If you register `target/debug/nu_plugin_config` the
`PLUGIN_NAME` will be `config` and the nushell config will loook like:

        $env.config = {
          # ...
          plugins: {
            config: [
              some
              values
            ]
          }
        }

Configuration may also use a closure which allows passing values from
`$env` to a plugin:

        $env.config = {
          # ...
          plugins: {
            config: {||
              $env.some_value
            }
          }
        }

This is a breaking change for the plugin API as the `Plugin::run()`
function now accepts a new configuration argument which is an
`&Option<Value>`. If no configuration was supplied the value is `None`.

Plugins compiled after this change should work with older nushell, and
will behave as if the configuration was not set.

Initially discussed in #10867

# User-Facing Changes

* Plugins can read configuration data stored in `$env.config.plugins`
* The plugin `CallInfo` now includes a `config` entry, existing plugins
will require updates

# Tests + Formatting

- 🟢 `toolkit fmt`
- 🟢 `toolkit clippy`
- 🟢 `toolkit test`
- 🟢 `toolkit test stdlib`

# After Submitting

- [ ] Update [Creating a plugin (in
Rust)](https://www.nushell.sh/contributor-book/plugins.html#creating-a-plugin-in-rust)
[source](https://github.com/nushell/nushell.github.io/blob/main/contributor-book/plugins.md)
- [ ] Add "Configuration" section to [Plugins
documentation](https://www.nushell.sh/contributor-book/plugins.html)

crates/nu-plugin/src/lib.rs

@@ -28,6 +28,7 @@
 //!     fn run(
 //!         &mut self,
 //!         name: &str,
+//!         config: &Option<Value>,
 //!         call: &EvaluatedCall,
 //!         input: &Value
 //!     ) -> Result<Value, LabeledError> {

crates/nu-plugin/src/plugin/declaration.rs

@@ -6,6 +6,7 @@ use crate::protocol::{
 };
 use std::path::{Path, PathBuf};
 
+use nu_engine::eval_block;
 use nu_protocol::engine::{Command, EngineState, Stack};
 use nu_protocol::{ast::Call, PluginSignature, Signature};
 use nu_protocol::{Example, PipelineData, ShellError, Value};
@@ -126,10 +127,48 @@ impl Command for PluginDeclaration {
             value => CallInput::Value(value),
         };
 
+        // Fetch the configuration for a plugin
+        //
+        // The `plugin` must match the registered name of a plugin.  For
+        // `register nu_plugin_example` the plugin config lookup uses `"example"`
+        let config = self
+            .filename
+            .file_stem()
+            .and_then(|file| {
+                file.to_string_lossy()
+                    .clone()
+                    .strip_prefix("nu_plugin_")
+                    .map(|name| {
+                        nu_engine::get_config(engine_state, stack)
+                            .plugins
+                            .get(name)
+                            .cloned()
+                    })
+            })
+            .flatten()
+            .map(|value| {
+                let span = value.span();
+                match value {
+                    Value::Closure { val, .. } => {
+                        let input = PipelineData::Empty;
+
+                        let block = engine_state.get_block(val.block_id).clone();
+                        let mut stack = stack.captures_to_stack(val.captures);
+
+                        match eval_block(engine_state, &mut stack, &block, input, false, false) {
+                            Ok(v) => v.into_value(span),
+                            Err(e) => Value::error(e, call.head),
+                        }
+                    }
+                    _ => value.clone(),
+                }
+            });
+
         let plugin_call = PluginCall::CallInfo(CallInfo {
             name: self.name.clone(),
             call: EvaluatedCall::try_from_call(call, engine_state, stack)?,
             input,
+            config,
         });
 
         let encoding = {

crates/nu-plugin/src/plugin/mod.rs

@@ -217,6 +217,7 @@ pub fn get_signature(
 ///     fn run(
 ///         &mut self,
 ///         name: &str,
+///         config: &Option<Value>,
 ///         call: &EvaluatedCall,
 ///         input: &Value,
 ///     ) -> Result<Value, LabeledError> {
@@ -246,6 +247,7 @@ pub trait Plugin {
     fn run(
         &mut self,
         name: &str,
+        config: &Option<Value>,
         call: &EvaluatedCall,
         input: &Value,
     ) -> Result<Value, LabeledError>;
@@ -264,7 +266,7 @@ pub trait Plugin {
 /// # impl MyPlugin { fn new() -> Self { Self }}
 /// # impl Plugin for MyPlugin {
 /// #     fn signature(&self) -> Vec<PluginSignature> {todo!();}
-/// #     fn run(&mut self, name: &str, call: &EvaluatedCall, input: &Value)
+/// #     fn run(&mut self, name: &str, config: &Option<Value>, call: &EvaluatedCall, input: &Value)
 /// #         -> Result<Value, LabeledError> {todo!();}
 /// # }
 /// fn main() {
@@ -333,7 +335,9 @@ pub fn serve_plugin(plugin: &mut impl Plugin, encoder: impl PluginEncoder) {
                     };
 
                     let value = match input {
-                        Ok(input) => plugin.run(&call_info.name, &call_info.call, &input),
+                        Ok(input) => {
+                            plugin.run(&call_info.name, &call_info.config, &call_info.call, &input)
+                        }
                         Err(err) => Err(err.into()),
                     };
 

crates/nu-plugin/src/protocol/mod.rs

@@ -13,6 +13,7 @@ pub struct CallInfo {
     pub name: String,
     pub call: EvaluatedCall,
     pub input: CallInput,
+    pub config: Option<Value>,
 }
 
 #[derive(Serialize, Deserialize, Debug, PartialEq)]

crates/nu-plugin/src/serializers/json.rs

@@ -106,6 +106,7 @@ mod tests {
             name: name.clone(),
             call: call.clone(),
             input: CallInput::Value(input.clone()),
+            config: None,
         });
 
         let encoder = JsonSerializer {};

crates/nu-plugin/src/serializers/msgpack.rs

@@ -107,6 +107,7 @@ mod tests {
             name: name.clone(),
             call: call.clone(),
             input: CallInput::Value(input.clone()),
+            config: None,
         });
 
         let encoder = MsgPackSerializer {};

crates/nu-protocol/src/config/mod.rs

@@ -73,6 +73,12 @@ pub struct Config {
     pub error_style: ErrorStyle,
     pub use_kitty_protocol: bool,
     pub highlight_resolved_externals: bool,
+    /// Configuration for plugins.
+    ///
+    /// Users can provide configuration for a plugin through this entry.  The entry name must
+    /// match the registered plugin name so `register nu_plugin_example` will be able to place
+    /// its configuration under a `nu_plugin_example` column.
+    pub plugins: HashMap<String, Value>,
 }
 
 impl Default for Config {
@@ -139,6 +145,8 @@ impl Default for Config {
 
             use_kitty_protocol: false,
             highlight_resolved_externals: false,
+
+            plugins: HashMap::new(),
         }
     }
 }
@@ -627,6 +635,22 @@ impl Value {
                     "highlight_resolved_externals" => {
                         process_bool_config(value, &mut errors, &mut config.highlight_resolved_externals);
                     }
+                    "plugins" => {
+                        if let Ok(map) = create_map(value) {
+                            config.plugins = map;
+                        } else {
+                            report_invalid_value("should be a record", span, &mut errors);
+                            // Reconstruct
+                            *value = Value::record(
+                                config
+                                    .explore
+                                    .iter()
+                                    .map(|(k, v)| (k.clone(), v.clone()))
+                                    .collect(),
+                                span,
+                            );
+                        }
+                    }
                     // Menus
                     "menus" => match create_menus(value) {
                         Ok(map) => config.menus = map,

crates/nu-protocol/src/engine/engine_state.rs

@@ -712,6 +712,14 @@ impl EngineState {
         self.config = conf;
     }
 
+    /// Fetch the configuration for a plugin
+    ///
+    /// The `plugin` must match the registered name of a plugin.  For `register nu_plugin_example`
+    /// the plugin name to use will be `"example"`
+    pub fn get_plugin_config(&self, plugin: &str) -> Option<&Value> {
+        self.config.plugins.get(plugin)
+    }
+
     pub fn get_var(&self, var_id: VarId) -> &Variable {
         self.vars
             .get(var_id)
@@ -972,4 +980,27 @@ mod engine_state_tests {
         assert_eq!(variables, vec![varname_with_sigil]);
         Ok(())
     }
+
+    #[test]
+    fn get_plugin_config() {
+        let mut engine_state = EngineState::new();
+
+        assert!(
+            engine_state.get_plugin_config("example").is_none(),
+            "Unexpected plugin configuration"
+        );
+
+        let mut plugins = HashMap::new();
+        plugins.insert("example".into(), Value::string("value", Span::test_data()));
+
+        let mut config = engine_state.get_config().clone();
+        config.plugins = plugins;
+
+        engine_state.set_config(config);
+
+        assert!(
+            engine_state.get_plugin_config("example").is_some(),
+            "Plugin configuration not found"
+        );
+    }
 }

crates/nu-protocol/tests/test_config.rs

@@ -100,3 +100,13 @@ snippet line 1: force_error "my error"
 "#,
     );
 }
+
+#[test]
+fn plugins() {
+    let code = &[
+        r#"$env.config = { plugins: { nu_plugin_config: { key: value } } }"#,
+        r#"$env.config.plugins"#,
+    ];
+    let actual = nu!(nu_repl_code(code));
+    assert_eq!(actual.out, r#"{nu_plugin_config: {key: value}}"#);
+}

crates/nu-utils/src/sample_config/default_config.nu

@@ -238,6 +238,8 @@ $env.config = {
     use_kitty_protocol: false # enables keyboard enhancement protocol implemented by kitty console, only if your terminal support this.
     highlight_resolved_externals: false # true enables highlighting of external commands in the repl resolved by which.
 
+    plugins: {} # Per-plugin configuration. See https://www.nushell.sh/contributor-book/plugins.html#configuration.
+
     hooks: {
         pre_prompt: [{ null }] # run before the prompt is shown
         pre_execution: [{ null }] # run before the repl input is run

crates/nu_plugin_custom_values/src/main.rs

@@ -27,6 +27,7 @@ impl Plugin for CustomValuePlugin {
     fn run(
         &mut self,
         name: &str,
+        _config: &Option<Value>,
         call: &EvaluatedCall,
         input: &Value,
     ) -> Result<Value, LabeledError> {

crates/nu_plugin_example/README.md

@@ -2,3 +2,33 @@
 
 Crate with a simple example of the Plugin trait that needs to be implemented
 in order to create a binary that can be registered into nushell declaration list
+
+## `example config`
+
+This subcommand demonstrates sending configuration from the nushell `$env.config` to a plugin.
+
+To register from after building `nushell` run:
+
+```nushell
+register target/debug/nu_plugin_example
+```
+
+The configuration for the plugin lives in `$env.config.plugins.example`:
+
+```nushell
+$env.config = {
+  plugins: {
+    example: [
+      some
+      values
+    ]
+  }
+}
+```
+
+To list plugin values run:
+
+```nushell
+nu-example-config
+```
+

crates/nu_plugin_example/src/example.rs

@@ -3,6 +3,22 @@ use nu_protocol::{Record, Value};
 pub struct Example;
 
 impl Example {
+    pub fn config(
+        &self,
+        config: &Option<Value>,
+        call: &EvaluatedCall,
+    ) -> Result<Value, LabeledError> {
+        match config {
+            Some(config) => Ok(config.clone()),
+            None => Err(LabeledError {
+                label: "No config sent".into(),
+                msg: "Configuration for this plugin was not found in `$env.config.plugins.example`"
+                    .into(),
+                span: Some(call.head),
+            }),
+        }
+    }
+
     fn print_values(
         &self,
         index: u32,

crates/nu_plugin_example/src/nu/mod.rs

@@ -1,6 +1,6 @@
 use crate::Example;
 use nu_plugin::{EvaluatedCall, LabeledError, Plugin};
-use nu_protocol::{Category, PluginExample, PluginSignature, SyntaxShape, Value};
+use nu_protocol::{Category, PluginExample, PluginSignature, SyntaxShape, Type, Value};
 
 impl Plugin for Example {
     fn signature(&self) -> Vec<PluginSignature> {
@@ -42,12 +42,19 @@ impl Plugin for Example {
                 .named("named", SyntaxShape::String, "named string", Some('n'))
                 .rest("rest", SyntaxShape::String, "rest value string")
                 .category(Category::Experimental),
+            PluginSignature::build("nu-example-config")
+                .usage("Show plugin configuration")
+                .extra_usage("The configuration is set under $env.config.plugins.example")
+                .category(Category::Experimental)
+                .search_terms(vec!["example".into(), "configuration".into()])
+                .input_output_type(Type::Nothing, Type::Table(vec![])),
         ]
     }
 
     fn run(
         &mut self,
         name: &str,
+        config: &Option<Value>,
         call: &EvaluatedCall,
         input: &Value,
     ) -> Result<Value, LabeledError> {
@@ -56,6 +63,7 @@ impl Plugin for Example {
             "nu-example-1" => self.test1(call, input),
             "nu-example-2" => self.test2(call, input),
             "nu-example-3" => self.test3(call, input),
+            "nu-example-config" => self.config(config, call),
             _ => Err(LabeledError {
                 label: "Plugin call with wrong name signature".into(),
                 msg: "the signature used to call the plugin does not match any name in the plugin signature vector".into(),

crates/nu_plugin_formats/src/lib.rs

@@ -41,6 +41,7 @@ impl Plugin for FromCmds {
     fn run(
         &mut self,
         name: &str,
+        _config: &Option<Value>,
         call: &EvaluatedCall,
         input: &Value,
     ) -> Result<Value, LabeledError> {

crates/nu_plugin_gstat/src/nu/mod.rs

@@ -13,6 +13,7 @@ impl Plugin for GStat {
     fn run(
         &mut self,
         name: &str,
+        _config: &Option<Value>,
         call: &EvaluatedCall,
         input: &Value,
     ) -> Result<Value, LabeledError> {

crates/nu_plugin_inc/src/nu/mod.rs

@@ -28,6 +28,7 @@ impl Plugin for Inc {
     fn run(
         &mut self,
         name: &str,
+        _config: &Option<Value>,
         call: &EvaluatedCall,
         input: &Value,
     ) -> Result<Value, LabeledError> {

crates/nu_plugin_query/src/nu/mod.rs

@@ -48,6 +48,7 @@ impl Plugin for Query {
     fn run(
         &mut self,
         name: &str,
+        _config: &Option<Value>,
         call: &EvaluatedCall,
         input: &Value,
     ) -> Result<Value, LabeledError> {

src/tests/test_config.rs

@@ -1,4 +1,4 @@
-use super::run_test_std;
+use super::{fail_test, run_test_std};
 use crate::tests::TestResult;
 
 #[test]
@@ -100,3 +100,25 @@ fn mutate_nu_config_nested_filesize() -> TestResult {
         "kb",
     )
 }
+
+#[test]
+fn mutate_nu_config_plugin() -> TestResult {
+    run_test_std(
+        r#"
+            $env.config.plugins = {
+                config: {
+                  key1: value
+                  key2: other
+                }
+            };
+            $env.config.plugins.config.key1 = 'updated'
+            $env.config.plugins.config.key1
+        "#,
+        "updated",
+    )
+}
+
+#[test]
+fn reject_nu_config_plugin_non_record() -> TestResult {
+    fail_test(r#"$env.config.plugins = 5"#, "should be a record")
+}

tests/plugins/config.rs

@@ -0,0 +1,56 @@
+use nu_test_support::nu_with_plugins;
+
+#[test]
+fn closure() {
+    let actual = nu_with_plugins!(
+        cwd: "tests",
+        plugin: ("nu_plugin_example"),
+        r#"
+            $env.env_value = "value from env"
+
+            $env.config = {
+                plugins: {
+                    example: {||
+                        $env.env_value
+                    }
+                }
+            }
+            nu-example-config
+        "#
+    );
+
+    assert!(actual.out.contains("value from env"));
+}
+
+#[test]
+fn none() {
+    let actual = nu_with_plugins!(
+        cwd: "tests",
+        plugin: ("nu_plugin_example"),
+        "nu-example-config"
+    );
+
+    assert!(actual.err.contains("No config sent"));
+}
+
+#[test]
+fn record() {
+    let actual = nu_with_plugins!(
+        cwd: "tests",
+        plugin: ("nu_plugin_example"),
+        r#"
+            $env.config = {
+                plugins: {
+                    example: {
+                        key1: "value"
+                        key2: "other"
+                    }
+                }
+            }
+            nu-example-config
+        "#
+    );
+
+    assert!(actual.out.contains("value"));
+    assert!(actual.out.contains("other"));
+}

tests/plugins/mod.rs

@@ -1,3 +1,4 @@
+mod config;
 mod core_inc;
 mod custom_values;
 mod formats;