From 7071617f180fd791c0ee87708c828afe8ef1b7d9 Mon Sep 17 00:00:00 2001 From: Eric Hodel Date: Mon, 15 Jan 2024 00:59:47 -0800 Subject: [PATCH] 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`. 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 - :green_circle: `toolkit fmt` - :green_circle: `toolkit clippy` - :green_circle: `toolkit test` - :green_circle: `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 | 1 + crates/nu-plugin/src/plugin/declaration.rs | 39 +++++++++++++ crates/nu-plugin/src/plugin/mod.rs | 8 ++- crates/nu-plugin/src/protocol/mod.rs | 1 + crates/nu-plugin/src/serializers/json.rs | 1 + crates/nu-plugin/src/serializers/msgpack.rs | 1 + crates/nu-protocol/src/config/mod.rs | 24 ++++++++ crates/nu-protocol/src/engine/engine_state.rs | 31 ++++++++++ crates/nu-protocol/tests/test_config.rs | 10 ++++ .../src/sample_config/default_config.nu | 2 + crates/nu_plugin_custom_values/src/main.rs | 1 + crates/nu_plugin_example/README.md | 30 ++++++++++ crates/nu_plugin_example/src/example.rs | 16 ++++++ crates/nu_plugin_example/src/nu/mod.rs | 10 +++- crates/nu_plugin_formats/src/lib.rs | 1 + crates/nu_plugin_gstat/src/nu/mod.rs | 1 + crates/nu_plugin_inc/src/nu/mod.rs | 1 + crates/nu_plugin_query/src/nu/mod.rs | 1 + src/tests/test_config.rs | 24 +++++++- tests/plugins/config.rs | 56 +++++++++++++++++++ tests/plugins/mod.rs | 1 + 21 files changed, 256 insertions(+), 4 deletions(-) create mode 100644 tests/plugins/config.rs diff --git a/crates/nu-plugin/src/lib.rs b/crates/nu-plugin/src/lib.rs index 186652d762..eeb6fd7400 100644 --- a/crates/nu-plugin/src/lib.rs +++ b/crates/nu-plugin/src/lib.rs @@ -28,6 +28,7 @@ //! fn run( //! &mut self, //! name: &str, +//! config: &Option, //! call: &EvaluatedCall, //! input: &Value //! ) -> Result { diff --git a/crates/nu-plugin/src/plugin/declaration.rs b/crates/nu-plugin/src/plugin/declaration.rs index fb6a98f35c..da0e6dc310 100644 --- a/crates/nu-plugin/src/plugin/declaration.rs +++ b/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 = { diff --git a/crates/nu-plugin/src/plugin/mod.rs b/crates/nu-plugin/src/plugin/mod.rs index df5f652938..e30b160850 100644 --- a/crates/nu-plugin/src/plugin/mod.rs +++ b/crates/nu-plugin/src/plugin/mod.rs @@ -217,6 +217,7 @@ pub fn get_signature( /// fn run( /// &mut self, /// name: &str, +/// config: &Option, /// call: &EvaluatedCall, /// input: &Value, /// ) -> Result { @@ -246,6 +247,7 @@ pub trait Plugin { fn run( &mut self, name: &str, + config: &Option, call: &EvaluatedCall, input: &Value, ) -> Result; @@ -264,7 +266,7 @@ pub trait Plugin { /// # impl MyPlugin { fn new() -> Self { Self }} /// # impl Plugin for MyPlugin { /// # fn signature(&self) -> Vec {todo!();} -/// # fn run(&mut self, name: &str, call: &EvaluatedCall, input: &Value) +/// # fn run(&mut self, name: &str, config: &Option, call: &EvaluatedCall, input: &Value) /// # -> Result {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()), }; diff --git a/crates/nu-plugin/src/protocol/mod.rs b/crates/nu-plugin/src/protocol/mod.rs index 60fa297e9c..52b2942db9 100644 --- a/crates/nu-plugin/src/protocol/mod.rs +++ b/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, } #[derive(Serialize, Deserialize, Debug, PartialEq)] diff --git a/crates/nu-plugin/src/serializers/json.rs b/crates/nu-plugin/src/serializers/json.rs index 4944e943e3..9bd8461eb7 100644 --- a/crates/nu-plugin/src/serializers/json.rs +++ b/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 {}; diff --git a/crates/nu-plugin/src/serializers/msgpack.rs b/crates/nu-plugin/src/serializers/msgpack.rs index e88be0b209..ffcf78bb9f 100644 --- a/crates/nu-plugin/src/serializers/msgpack.rs +++ b/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 {}; diff --git a/crates/nu-protocol/src/config/mod.rs b/crates/nu-protocol/src/config/mod.rs index 1f58a2d140..4f578fb827 100644 --- a/crates/nu-protocol/src/config/mod.rs +++ b/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, } 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, diff --git a/crates/nu-protocol/src/engine/engine_state.rs b/crates/nu-protocol/src/engine/engine_state.rs index ed962ff386..b9c6d48edd 100644 --- a/crates/nu-protocol/src/engine/engine_state.rs +++ b/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" + ); + } } diff --git a/crates/nu-protocol/tests/test_config.rs b/crates/nu-protocol/tests/test_config.rs index 4f05120955..13c90379a3 100644 --- a/crates/nu-protocol/tests/test_config.rs +++ b/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}}"#); +} diff --git a/crates/nu-utils/src/sample_config/default_config.nu b/crates/nu-utils/src/sample_config/default_config.nu index d950242b14..faae590df6 100644 --- a/crates/nu-utils/src/sample_config/default_config.nu +++ b/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 diff --git a/crates/nu_plugin_custom_values/src/main.rs b/crates/nu_plugin_custom_values/src/main.rs index c36797face..27dd240210 100644 --- a/crates/nu_plugin_custom_values/src/main.rs +++ b/crates/nu_plugin_custom_values/src/main.rs @@ -27,6 +27,7 @@ impl Plugin for CustomValuePlugin { fn run( &mut self, name: &str, + _config: &Option, call: &EvaluatedCall, input: &Value, ) -> Result { diff --git a/crates/nu_plugin_example/README.md b/crates/nu_plugin_example/README.md index 54df1602b8..bb26b0c7f2 100644 --- a/crates/nu_plugin_example/README.md +++ b/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 +``` + diff --git a/crates/nu_plugin_example/src/example.rs b/crates/nu_plugin_example/src/example.rs index 2f54b1404c..226972be98 100644 --- a/crates/nu_plugin_example/src/example.rs +++ b/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, + call: &EvaluatedCall, + ) -> Result { + 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, diff --git a/crates/nu_plugin_example/src/nu/mod.rs b/crates/nu_plugin_example/src/nu/mod.rs index 2eb5dc1fd5..d8b7893d83 100644 --- a/crates/nu_plugin_example/src/nu/mod.rs +++ b/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 { @@ -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, call: &EvaluatedCall, input: &Value, ) -> Result { @@ -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(), diff --git a/crates/nu_plugin_formats/src/lib.rs b/crates/nu_plugin_formats/src/lib.rs index 142ba4b92d..26710e6abe 100644 --- a/crates/nu_plugin_formats/src/lib.rs +++ b/crates/nu_plugin_formats/src/lib.rs @@ -41,6 +41,7 @@ impl Plugin for FromCmds { fn run( &mut self, name: &str, + _config: &Option, call: &EvaluatedCall, input: &Value, ) -> Result { diff --git a/crates/nu_plugin_gstat/src/nu/mod.rs b/crates/nu_plugin_gstat/src/nu/mod.rs index 504bffbbe5..8e99ca2fa5 100644 --- a/crates/nu_plugin_gstat/src/nu/mod.rs +++ b/crates/nu_plugin_gstat/src/nu/mod.rs @@ -13,6 +13,7 @@ impl Plugin for GStat { fn run( &mut self, name: &str, + _config: &Option, call: &EvaluatedCall, input: &Value, ) -> Result { diff --git a/crates/nu_plugin_inc/src/nu/mod.rs b/crates/nu_plugin_inc/src/nu/mod.rs index 597e57e19f..b924e8e135 100644 --- a/crates/nu_plugin_inc/src/nu/mod.rs +++ b/crates/nu_plugin_inc/src/nu/mod.rs @@ -28,6 +28,7 @@ impl Plugin for Inc { fn run( &mut self, name: &str, + _config: &Option, call: &EvaluatedCall, input: &Value, ) -> Result { diff --git a/crates/nu_plugin_query/src/nu/mod.rs b/crates/nu_plugin_query/src/nu/mod.rs index afc0c203f5..11ef00d7c8 100644 --- a/crates/nu_plugin_query/src/nu/mod.rs +++ b/crates/nu_plugin_query/src/nu/mod.rs @@ -48,6 +48,7 @@ impl Plugin for Query { fn run( &mut self, name: &str, + _config: &Option, call: &EvaluatedCall, input: &Value, ) -> Result { diff --git a/src/tests/test_config.rs b/src/tests/test_config.rs index fb3526bf40..6f4230f763 100644 --- a/src/tests/test_config.rs +++ b/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") +} diff --git a/tests/plugins/config.rs b/tests/plugins/config.rs new file mode 100644 index 0000000000..656d092c5a --- /dev/null +++ b/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")); +} diff --git a/tests/plugins/mod.rs b/tests/plugins/mod.rs index a51d777eef..df130ae564 100644 --- a/tests/plugins/mod.rs +++ b/tests/plugins/mod.rs @@ -1,3 +1,4 @@ +mod config; mod core_inc; mod custom_values; mod formats;