Split the plugin crate (#12563)

# Description

This breaks `nu-plugin` up into four crates:

- `nu-plugin-protocol`: just the type definitions for the protocol, no
I/O. If someone wanted to wire up something more bare metal, maybe for
async I/O, they could use this.
- `nu-plugin-core`: the shared stuff between engine/plugin. Less stable
interface.
- `nu-plugin-engine`: everything required for the engine to talk to
plugins. Less stable interface.
- `nu-plugin`: everything required for the plugin to talk to the engine,
what plugin developers use. Should be the most stable interface.

No changes are made to the interface exposed by `nu-plugin` - it should
all still be there. Re-exports from `nu-plugin-protocol` or
`nu-plugin-core` are used as required. Plugins shouldn't ever have to
use those crates directly.

This should be somewhat faster to compile as `nu-plugin-engine` and
`nu-plugin` can compile in parallel, and the engine doesn't need
`nu-plugin` and plugins don't need `nu-plugin-engine` (except for test
support), so that should reduce what needs to be compiled too.

The only significant change here other than splitting stuff up was to
break the `source` out of `PluginCustomValue` and create a new
`PluginCustomValueWithSource` type that contains that instead. One bonus
of that is we get rid of the option and it's now more type-safe, but it
also means that the logic for that stuff (actually running the plugin
for custom value ops) can live entirely within the `nu-plugin-engine`
crate.

# User-Facing Changes
- New crates.
- Added `local-socket` feature for `nu` to try to make it possible to
compile without that support if needed.

# Tests + Formatting
- 🟢 `toolkit fmt`
- 🟢 `toolkit clippy`
- 🟢 `toolkit test`
- 🟢 `toolkit test stdlib`

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

@@ -0,0 +1,236 @@
+use std::cmp::Ordering;
+
+use nu_protocol::{ast::Operator, CustomValue, ShellError, Span, Value};
+use nu_utils::SharedCow;
+
+use serde::{Deserialize, Serialize};
+
+#[cfg(test)]
+mod tests;
+
+/// An opaque container for a custom value that is handled fully by a plugin.
+///
+/// This is the only type of custom value that is allowed to cross the plugin serialization
+/// boundary.
+///
+/// The plugin is responsible for ensuring that local plugin custom values are converted to and from
+/// [`PluginCustomValue`] on the boundary.
+///
+/// The engine is responsible for adding tracking the source of the custom value, ensuring that only
+/// [`PluginCustomValue`] is contained within any values sent, and that the source of any values
+/// sent matches the plugin it is being sent to.
+///
+/// Most of the [`CustomValue`] methods on this type will result in a panic. The source must be
+/// added (see `nu_plugin_engine::PluginCustomValueWithSource`) in order to implement the
+/// functionality via plugin calls.
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct PluginCustomValue(SharedCow<SharedContent>);
+
+/// Content shared across copies of a plugin custom value.
+#[derive(Clone, Debug, Serialize, Deserialize)]
+struct SharedContent {
+    /// The name of the type of the custom value as defined by the plugin (`type_name()`)
+    name: String,
+    /// The bincoded representation of the custom value on the plugin side
+    data: Vec<u8>,
+    /// True if the custom value should notify the source if all copies of it are dropped.
+    ///
+    /// This is not serialized if `false`, since most custom values don't need it.
+    #[serde(default, skip_serializing_if = "is_false")]
+    notify_on_drop: bool,
+}
+
+fn is_false(b: &bool) -> bool {
+    !b
+}
+
+#[typetag::serde]
+impl CustomValue for PluginCustomValue {
+    fn clone_value(&self, span: Span) -> Value {
+        self.clone().into_value(span)
+    }
+
+    fn type_name(&self) -> String {
+        self.name().to_owned()
+    }
+
+    fn to_base_value(&self, _span: Span) -> Result<Value, ShellError> {
+        panic!("to_base_value() not available on plugin custom value without source");
+    }
+
+    fn follow_path_int(
+        &self,
+        _self_span: Span,
+        _index: usize,
+        _path_span: Span,
+    ) -> Result<Value, ShellError> {
+        panic!("follow_path_int() not available on plugin custom value without source");
+    }
+
+    fn follow_path_string(
+        &self,
+        _self_span: Span,
+        _column_name: String,
+        _path_span: Span,
+    ) -> Result<Value, ShellError> {
+        panic!("follow_path_string() not available on plugin custom value without source");
+    }
+
+    fn partial_cmp(&self, _other: &Value) -> Option<Ordering> {
+        panic!("partial_cmp() not available on plugin custom value without source");
+    }
+
+    fn operation(
+        &self,
+        _lhs_span: Span,
+        _operator: Operator,
+        _op_span: Span,
+        _right: &Value,
+    ) -> Result<Value, ShellError> {
+        panic!("operation() not available on plugin custom value without source");
+    }
+
+    fn as_any(&self) -> &dyn std::any::Any {
+        self
+    }
+
+    fn as_mut_any(&mut self) -> &mut dyn std::any::Any {
+        self
+    }
+}
+
+impl PluginCustomValue {
+    /// Create a new [`PluginCustomValue`].
+    pub fn new(name: String, data: Vec<u8>, notify_on_drop: bool) -> PluginCustomValue {
+        PluginCustomValue(SharedCow::new(SharedContent {
+            name,
+            data,
+            notify_on_drop,
+        }))
+    }
+
+    /// Create a [`Value`] containing this custom value.
+    pub fn into_value(self, span: Span) -> Value {
+        Value::custom(Box::new(self), span)
+    }
+
+    /// The name of the type of the custom value as defined by the plugin (`type_name()`)
+    pub fn name(&self) -> &str {
+        &self.0.name
+    }
+
+    /// The bincoded representation of the custom value on the plugin side
+    pub fn data(&self) -> &[u8] {
+        &self.0.data
+    }
+
+    /// True if the custom value should notify the source if all copies of it are dropped.
+    pub fn notify_on_drop(&self) -> bool {
+        self.0.notify_on_drop
+    }
+
+    /// Count the number of shared copies of this [`PluginCustomValue`].
+    pub fn ref_count(&self) -> usize {
+        SharedCow::ref_count(&self.0)
+    }
+
+    /// Serialize a custom value into a [`PluginCustomValue`]. This should only be done on the
+    /// plugin side.
+    pub fn serialize_from_custom_value(
+        custom_value: &dyn CustomValue,
+        span: Span,
+    ) -> Result<PluginCustomValue, ShellError> {
+        let name = custom_value.type_name();
+        let notify_on_drop = custom_value.notify_plugin_on_drop();
+        bincode::serialize(custom_value)
+            .map(|data| PluginCustomValue::new(name, data, notify_on_drop))
+            .map_err(|err| ShellError::CustomValueFailedToEncode {
+                msg: err.to_string(),
+                span,
+            })
+    }
+
+    /// Deserialize a [`PluginCustomValue`] into a `Box<dyn CustomValue>`. This should only be done
+    /// on the plugin side.
+    pub fn deserialize_to_custom_value(
+        &self,
+        span: Span,
+    ) -> Result<Box<dyn CustomValue>, ShellError> {
+        bincode::deserialize::<Box<dyn CustomValue>>(self.data()).map_err(|err| {
+            ShellError::CustomValueFailedToDecode {
+                msg: err.to_string(),
+                span,
+            }
+        })
+    }
+    /// Convert all plugin-native custom values to [`PluginCustomValue`] within the given `value`,
+    /// recursively. This should only be done on the plugin side.
+    pub fn serialize_custom_values_in(value: &mut Value) -> Result<(), ShellError> {
+        value.recurse_mut(&mut |value| {
+            let span = value.span();
+            match value {
+                Value::Custom { ref val, .. } => {
+                    if val.as_any().downcast_ref::<PluginCustomValue>().is_some() {
+                        // Already a PluginCustomValue
+                        Ok(())
+                    } else {
+                        let serialized = Self::serialize_from_custom_value(&**val, span)?;
+                        *value = Value::custom(Box::new(serialized), span);
+                        Ok(())
+                    }
+                }
+                // Collect LazyRecord before proceeding
+                Value::LazyRecord { ref val, .. } => {
+                    *value = val.collect()?;
+                    Ok(())
+                }
+                _ => Ok(()),
+            }
+        })
+    }
+
+    /// Convert all [`PluginCustomValue`]s to plugin-native custom values within the given `value`,
+    /// recursively. This should only be done on the plugin side.
+    pub fn deserialize_custom_values_in(value: &mut Value) -> Result<(), ShellError> {
+        value.recurse_mut(&mut |value| {
+            let span = value.span();
+            match value {
+                Value::Custom { ref val, .. } => {
+                    if let Some(val) = val.as_any().downcast_ref::<PluginCustomValue>() {
+                        let deserialized = val.deserialize_to_custom_value(span)?;
+                        *value = Value::custom(deserialized, span);
+                        Ok(())
+                    } else {
+                        // Already not a PluginCustomValue
+                        Ok(())
+                    }
+                }
+                // Collect LazyRecord before proceeding
+                Value::LazyRecord { ref val, .. } => {
+                    *value = val.collect()?;
+                    Ok(())
+                }
+                _ => Ok(()),
+            }
+        })
+    }
+
+    /// Render any custom values in the `Value` using `to_base_value()`
+    pub fn render_to_base_value_in(value: &mut Value) -> Result<(), ShellError> {
+        value.recurse_mut(&mut |value| {
+            let span = value.span();
+            match value {
+                Value::Custom { ref val, .. } => {
+                    *value = val.to_base_value(span)?;
+                    Ok(())
+                }
+                // Collect LazyRecord before proceeding
+                Value::LazyRecord { ref val, .. } => {
+                    *value = val.collect()?;
+                    Ok(())
+                }
+                _ => Ok(()),
+            }
+        })
+    }
+}

crates/nu-plugin-protocol/src/plugin_custom_value/tests.rs

@@ -0,0 +1,259 @@
+use crate::test_util::{expected_test_custom_value, test_plugin_custom_value, TestCustomValue};
+
+use super::PluginCustomValue;
+use nu_protocol::{engine::Closure, record, CustomValue, ShellError, Span, Value};
+
+fn check_record_custom_values(
+    val: &Value,
+    keys: &[&str],
+    mut f: impl FnMut(&str, &dyn CustomValue) -> Result<(), ShellError>,
+) -> Result<(), ShellError> {
+    let record = val.as_record()?;
+    for key in keys {
+        let val = record
+            .get(key)
+            .unwrap_or_else(|| panic!("record does not contain '{key}'"));
+        let custom_value = val
+            .as_custom_value()
+            .unwrap_or_else(|_| panic!("'{key}' not custom value"));
+        f(key, custom_value)?;
+    }
+    Ok(())
+}
+
+fn check_list_custom_values(
+    val: &Value,
+    indices: impl IntoIterator<Item = usize>,
+    mut f: impl FnMut(usize, &dyn CustomValue) -> Result<(), ShellError>,
+) -> Result<(), ShellError> {
+    let list = val.as_list()?;
+    for index in indices {
+        let val = list
+            .get(index)
+            .unwrap_or_else(|| panic!("[{index}] not present in list"));
+        let custom_value = val
+            .as_custom_value()
+            .unwrap_or_else(|_| panic!("[{index}] not custom value"));
+        f(index, custom_value)?;
+    }
+    Ok(())
+}
+
+fn check_closure_custom_values(
+    val: &Value,
+    indices: impl IntoIterator<Item = usize>,
+    mut f: impl FnMut(usize, &dyn CustomValue) -> Result<(), ShellError>,
+) -> Result<(), ShellError> {
+    let closure = val.as_closure()?;
+    for index in indices {
+        let val = closure
+            .captures
+            .get(index)
+            .unwrap_or_else(|| panic!("[{index}] not present in closure"));
+        let custom_value = val
+            .1
+            .as_custom_value()
+            .unwrap_or_else(|_| panic!("[{index}] not custom value"));
+        f(index, custom_value)?;
+    }
+    Ok(())
+}
+
+#[test]
+fn serialize_deserialize() -> Result<(), ShellError> {
+    let original_value = TestCustomValue(32);
+    let span = Span::test_data();
+    let serialized = PluginCustomValue::serialize_from_custom_value(&original_value, span)?;
+    assert_eq!(original_value.type_name(), serialized.name());
+    let deserialized = serialized.deserialize_to_custom_value(span)?;
+    let downcasted = deserialized
+        .as_any()
+        .downcast_ref::<TestCustomValue>()
+        .expect("failed to downcast: not TestCustomValue");
+    assert_eq!(original_value, *downcasted);
+    Ok(())
+}
+
+#[test]
+fn expected_serialize_output() -> Result<(), ShellError> {
+    let original_value = expected_test_custom_value();
+    let span = Span::test_data();
+    let serialized = PluginCustomValue::serialize_from_custom_value(&original_value, span)?;
+    assert_eq!(
+        test_plugin_custom_value().data(),
+        serialized.data(),
+        "The bincode configuration is probably different from what we expected. \
+            Fix test_plugin_custom_value() to match it"
+    );
+    Ok(())
+}
+
+#[test]
+fn serialize_in_root() -> Result<(), ShellError> {
+    let span = Span::new(4, 10);
+    let mut val = Value::custom(Box::new(expected_test_custom_value()), span);
+    PluginCustomValue::serialize_custom_values_in(&mut val)?;
+
+    assert_eq!(span, val.span());
+
+    let custom_value = val.as_custom_value()?;
+    if let Some(plugin_custom_value) = custom_value.as_any().downcast_ref::<PluginCustomValue>() {
+        assert_eq!("TestCustomValue", plugin_custom_value.name());
+        assert_eq!(
+            test_plugin_custom_value().data(),
+            plugin_custom_value.data()
+        );
+    } else {
+        panic!("Failed to downcast to PluginCustomValue");
+    }
+    Ok(())
+}
+
+#[test]
+fn serialize_in_record() -> Result<(), ShellError> {
+    let orig_custom_val = Value::test_custom_value(Box::new(TestCustomValue(32)));
+    let mut val = Value::test_record(record! {
+        "foo" => orig_custom_val.clone(),
+        "bar" => orig_custom_val.clone(),
+    });
+    PluginCustomValue::serialize_custom_values_in(&mut val)?;
+
+    check_record_custom_values(&val, &["foo", "bar"], |key, custom_value| {
+        let plugin_custom_value: &PluginCustomValue = custom_value
+            .as_any()
+            .downcast_ref()
+            .unwrap_or_else(|| panic!("'{key}' not PluginCustomValue"));
+        assert_eq!(
+            "TestCustomValue",
+            plugin_custom_value.name(),
+            "'{key}' name not set correctly"
+        );
+        Ok(())
+    })
+}
+
+#[test]
+fn serialize_in_list() -> Result<(), ShellError> {
+    let orig_custom_val = Value::test_custom_value(Box::new(TestCustomValue(24)));
+    let mut val = Value::test_list(vec![orig_custom_val.clone(), orig_custom_val.clone()]);
+    PluginCustomValue::serialize_custom_values_in(&mut val)?;
+
+    check_list_custom_values(&val, 0..=1, |index, custom_value| {
+        let plugin_custom_value: &PluginCustomValue = custom_value
+            .as_any()
+            .downcast_ref()
+            .unwrap_or_else(|| panic!("[{index}] not PluginCustomValue"));
+        assert_eq!(
+            "TestCustomValue",
+            plugin_custom_value.name(),
+            "[{index}] name not set correctly"
+        );
+        Ok(())
+    })
+}
+
+#[test]
+fn serialize_in_closure() -> Result<(), ShellError> {
+    let orig_custom_val = Value::test_custom_value(Box::new(TestCustomValue(24)));
+    let mut val = Value::test_closure(Closure {
+        block_id: 0,
+        captures: vec![(0, orig_custom_val.clone()), (1, orig_custom_val.clone())],
+    });
+    PluginCustomValue::serialize_custom_values_in(&mut val)?;
+
+    check_closure_custom_values(&val, 0..=1, |index, custom_value| {
+        let plugin_custom_value: &PluginCustomValue = custom_value
+            .as_any()
+            .downcast_ref()
+            .unwrap_or_else(|| panic!("[{index}] not PluginCustomValue"));
+        assert_eq!(
+            "TestCustomValue",
+            plugin_custom_value.name(),
+            "[{index}] name not set correctly"
+        );
+        Ok(())
+    })
+}
+
+#[test]
+fn deserialize_in_root() -> Result<(), ShellError> {
+    let span = Span::new(4, 10);
+    let mut val = Value::custom(Box::new(test_plugin_custom_value()), span);
+    PluginCustomValue::deserialize_custom_values_in(&mut val)?;
+
+    assert_eq!(span, val.span());
+
+    let custom_value = val.as_custom_value()?;
+    if let Some(test_custom_value) = custom_value.as_any().downcast_ref::<TestCustomValue>() {
+        assert_eq!(expected_test_custom_value(), *test_custom_value);
+    } else {
+        panic!("Failed to downcast to TestCustomValue");
+    }
+    Ok(())
+}
+
+#[test]
+fn deserialize_in_record() -> Result<(), ShellError> {
+    let orig_custom_val = Value::test_custom_value(Box::new(test_plugin_custom_value()));
+    let mut val = Value::test_record(record! {
+        "foo" => orig_custom_val.clone(),
+        "bar" => orig_custom_val.clone(),
+    });
+    PluginCustomValue::deserialize_custom_values_in(&mut val)?;
+
+    check_record_custom_values(&val, &["foo", "bar"], |key, custom_value| {
+        let test_custom_value: &TestCustomValue = custom_value
+            .as_any()
+            .downcast_ref()
+            .unwrap_or_else(|| panic!("'{key}' not TestCustomValue"));
+        assert_eq!(
+            expected_test_custom_value(),
+            *test_custom_value,
+            "{key} not deserialized correctly"
+        );
+        Ok(())
+    })
+}
+
+#[test]
+fn deserialize_in_list() -> Result<(), ShellError> {
+    let orig_custom_val = Value::test_custom_value(Box::new(test_plugin_custom_value()));
+    let mut val = Value::test_list(vec![orig_custom_val.clone(), orig_custom_val.clone()]);
+    PluginCustomValue::deserialize_custom_values_in(&mut val)?;
+
+    check_list_custom_values(&val, 0..=1, |index, custom_value| {
+        let test_custom_value: &TestCustomValue = custom_value
+            .as_any()
+            .downcast_ref()
+            .unwrap_or_else(|| panic!("[{index}] not TestCustomValue"));
+        assert_eq!(
+            expected_test_custom_value(),
+            *test_custom_value,
+            "[{index}] name not deserialized correctly"
+        );
+        Ok(())
+    })
+}
+
+#[test]
+fn deserialize_in_closure() -> Result<(), ShellError> {
+    let orig_custom_val = Value::test_custom_value(Box::new(test_plugin_custom_value()));
+    let mut val = Value::test_closure(Closure {
+        block_id: 0,
+        captures: vec![(0, orig_custom_val.clone()), (1, orig_custom_val.clone())],
+    });
+    PluginCustomValue::deserialize_custom_values_in(&mut val)?;
+
+    check_closure_custom_values(&val, 0..=1, |index, custom_value| {
+        let test_custom_value: &TestCustomValue = custom_value
+            .as_any()
+            .downcast_ref()
+            .unwrap_or_else(|| panic!("[{index}] not TestCustomValue"));
+        assert_eq!(
+            expected_test_custom_value(),
+            *test_custom_value,
+            "[{index}] name not deserialized correctly"
+        );
+        Ok(())
+    })
+}