extern/nushell
1
0
Fork 1
mirror of https://github.com/nushell/nushell.git synced 2025-08-09 14:06:40 +02:00
Code Issues Packages Projects Releases Wiki Activity

Plugin json (#474)

Browse Source 
* json encoder

* thread to pass messages

* description for example
This commit is contained in:
Fernando Herrera
2021-12-12 11:50:35 +00:00
committed by GitHub
parent f8e6620e48
commit 4d7dd23779
30 changed files with 1010 additions and 523 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
crates/nu-plugin/src/lib.rs
View File

@ -1,7 +1,10 @@
pub mod evaluated_call;
pub mod plugin;
pub mod plugin_capnp;
pub mod serializers;
mod plugin;
mod protocol;
mod serializers;
pub use evaluated_call::EvaluatedCall;
pub use plugin::{serve_plugin, LabeledError, Plugin};
#[allow(dead_code)]
mod plugin_capnp;
pub use plugin::{get_signature, serve_plugin, Plugin, PluginDeclaration};
pub use protocol::{EvaluatedCall, LabeledError};
pub use serializers::{capnp::CapnpSerializer, json::JsonSerializer, EncodingType};

345
crates/nu-plugin/src/plugin.rs
View File

@ -1,345 +0,0 @@
use crate::serializers::{decode_call, decode_response, encode_call, encode_response};
use std::io::BufReader;
use std::path::{Path, PathBuf};
use std::process::{Command as CommandSys, Stdio};
use nu_protocol::engine::{Command, EngineState, Stack};
use nu_protocol::{ast::Call, Signature, Value};
use nu_protocol::{PipelineData, ShellError, Span};
use super::evaluated_call::EvaluatedCall;
const OUTPUT_BUFFER_SIZE: usize = 8192;
#[derive(Debug)]
pub struct CallInfo {
pub name: String,
pub call: EvaluatedCall,
pub input: Value,
}
// Information sent to the plugin
#[derive(Debug)]
pub enum PluginCall {
Signature,
CallInfo(Box<CallInfo>),
}
#[derive(Clone, Debug, PartialEq)]
pub struct LabeledError {
pub label: String,
pub msg: String,
pub span: Option<Span>,
}
impl From<LabeledError> for ShellError {
fn from(error: LabeledError) -> Self {
match error.span {
Some(span) => ShellError::SpannedLabeledError(error.label, error.msg, span),
None => ShellError::LabeledError(error.label, error.msg),
}
}
}
impl From<ShellError> for LabeledError {
fn from(error: ShellError) -> Self {
match error {
ShellError::SpannedLabeledError(label, msg, span) => LabeledError {
label,
msg,
span: Some(span),
},
ShellError::LabeledError(label, msg) => LabeledError {
label,
msg,
span: None,
},
ShellError::CantConvert(expected, input, span) => LabeledError {
label: format!("Can't convert to {}", expected),
msg: format!("can't convert {} to {}", expected, input),
span: Some(span),
},
ShellError::DidYouMean(suggestion, span) => LabeledError {
label: "Name not found".into(),
msg: format!("did you mean '{}'", suggestion),
span: Some(span),
},
ShellError::PluginFailedToLoad(msg) => LabeledError {
label: "Plugin failed to load".into(),
msg,
span: None,
},
ShellError::PluginFailedToEncode(msg) => LabeledError {
label: "Plugin failed to encode".into(),
msg,
span: None,
},
ShellError::PluginFailedToDecode(msg) => LabeledError {
label: "Plugin failed to decode".into(),
msg,
span: None,
},
err => LabeledError {
label: "Error - Add to LabeledError From<ShellError>".into(),
msg: err.to_string(),
span: None,
},
}
}
}
// Information received from the plugin
#[derive(Debug)]
pub enum PluginResponse {
Error(LabeledError),
Signature(Vec<Signature>),
Value(Box<Value>),
}
pub fn get_signature(path: &Path) -> Result<Vec<Signature>, ShellError> {
let mut plugin_cmd = create_command(path);
let mut child = plugin_cmd.spawn().map_err(|err| {
ShellError::PluginFailedToLoad(format!("Error spawning child process: {}", err))
})?;
// Create message to plugin to indicate that signature is required and
// send call to plugin asking for signature
if let Some(stdin_writer) = &mut child.stdin {
let mut writer = stdin_writer;
encode_call(&PluginCall::Signature, &mut writer)?
}
// deserialize response from plugin to extract the signature
let signature = if let Some(stdout_reader) = &mut child.stdout {
let reader = stdout_reader;
let mut buf_read = BufReader::with_capacity(OUTPUT_BUFFER_SIZE, reader);
let response = decode_response(&mut buf_read)?;
match response {
PluginResponse::Signature(sign) => Ok(sign),
PluginResponse::Error(err) => Err(err.into()),
_ => Err(ShellError::PluginFailedToLoad(
"Plugin missing signature".into(),
)),
}
} else {
Err(ShellError::PluginFailedToLoad(
"Plugin missing stdout reader".into(),
))
}?;
// There is no need to wait for the child process to finish since the
// signature has being collected
Ok(signature)
}
fn create_command(path: &Path) -> CommandSys {
//TODO. The selection of shell could be modifiable from the config file.
let mut process = if cfg!(windows) {
let mut process = CommandSys::new("cmd");
process.arg("/c").arg(path);
process
} else {
let mut process = CommandSys::new("sh");
process.arg("-c").arg(path);
process
};
// Both stdout and stdin are piped so we can receive information from the plugin
process.stdout(Stdio::piped()).stdin(Stdio::piped());
process
}
#[derive(Debug, Clone)]
pub struct PluginDeclaration {
name: String,
signature: Signature,
filename: PathBuf,
}
impl PluginDeclaration {
pub fn new(filename: PathBuf, signature: Signature) -> Self {
Self {
name: signature.name.clone(),
signature,
filename,
}
}
}
impl Command for PluginDeclaration {
fn name(&self) -> &str {
&self.name
}
fn signature(&self) -> Signature {
self.signature.clone()
}
fn usage(&self) -> &str {
self.signature.usage.as_str()
}
fn run(
&self,
engine_state: &EngineState,
stack: &mut Stack,
call: &Call,
input: PipelineData,
) -> Result<PipelineData, ShellError> {
// Call the command with self path
// Decode information from plugin
// Create PipelineData
let source_file = Path::new(&self.filename);
let mut plugin_cmd = create_command(source_file);
let mut child = plugin_cmd.spawn().map_err(|err| {
let decl = engine_state.get_decl(call.decl_id);
ShellError::SpannedLabeledError(
format!("Unable to spawn plugin for {}", decl.name()),
format!("{}", err),
call.head,
)
})?;
let input = match input {
PipelineData::Value(value, ..) => value,
PipelineData::Stream(stream, ..) => {
let values = stream.collect::<Vec<Value>>();
Value::List {
vals: values,
span: call.head,
}
}
};
// Create message to plugin to indicate that signature is required and
// send call to plugin asking for signature
if let Some(stdin_writer) = &mut child.stdin {
// PluginCall information
let plugin_call = PluginCall::CallInfo(Box::new(CallInfo {
name: self.name.clone(),
call: EvaluatedCall::try_from_call(call, engine_state, stack)?,
input,
}));
let mut writer = stdin_writer;
encode_call(&plugin_call, &mut writer).map_err(|err| {
let decl = engine_state.get_decl(call.decl_id);
ShellError::SpannedLabeledError(
format!("Unable to encode call for {}", decl.name()),
err.to_string(),
call.head,
)
})?;
}
// Deserialize response from plugin to extract the resulting value
let pipeline_data = if let Some(stdout_reader) = &mut child.stdout {
let reader = stdout_reader;
let mut buf_read = BufReader::with_capacity(OUTPUT_BUFFER_SIZE, reader);
let response = decode_response(&mut buf_read).map_err(|err| {
let decl = engine_state.get_decl(call.decl_id);
ShellError::SpannedLabeledError(
format!("Unable to decode call for {}", decl.name()),
err.to_string(),
call.head,
)
})?;
match response {
PluginResponse::Value(value) => {
Ok(PipelineData::Value(value.as_ref().clone(), None))
}
PluginResponse::Error(err) => Err(err.into()),
PluginResponse::Signature(..) => Err(ShellError::SpannedLabeledError(
"Plugin missing value".into(),
"Received a signature from plugin instead of value".into(),
call.head,
)),
}
} else {
Err(ShellError::SpannedLabeledError(
"Error with stdout reader".into(),
"no stdout reader".into(),
call.head,
))
}?;
// There is no need to wait for the child process to finish
// The response has been collected from the plugin call
Ok(pipeline_data)
}
fn is_plugin(&self) -> Option<&PathBuf> {
Some(&self.filename)
}
}
// The next trait and functions are part of the plugin that is being created
// The `Plugin` trait defines the API which plugins use to "hook" into nushell.
pub trait Plugin {
fn signature(&self) -> Vec<Signature>;
fn run(
&mut self,
name: &str,
call: &EvaluatedCall,
input: &Value,
) -> Result<Value, LabeledError>;
}
// Function used in the plugin definition for the communication protocol between
// nushell and the external plugin.
// When creating a new plugin you have to use this function as the main
// entry point for the plugin, e.g.
//
// fn main() {
// serve_plugin(plugin)
// }
//
// where plugin is your struct that implements the Plugin trait
//
// Note. When defining a plugin in other language but Rust, you will have to compile
// the plugin.capnp schema to create the object definitions that will be returned from
// the plugin.
// The object that is expected to be received by nushell is the PluginResponse struct.
// That should be encoded correctly and sent to StdOut for nushell to decode and
// and present its result
//
pub fn serve_plugin(plugin: &mut impl Plugin) {
let mut stdin_buf = BufReader::with_capacity(OUTPUT_BUFFER_SIZE, std::io::stdin());
let plugin_call = decode_call(&mut stdin_buf);
match plugin_call {
Err(err) => {
let response = PluginResponse::Error(err.into());
encode_response(&response, &mut std::io::stdout()).expect("Error encoding response");
}
Ok(plugin_call) => {
match plugin_call {
// Sending the signature back to nushell to create the declaration definition
PluginCall::Signature => {
let response = PluginResponse::Signature(plugin.signature());
encode_response(&response, &mut std::io::stdout())
.expect("Error encoding response");
}
PluginCall::CallInfo(call_info) => {
let value = plugin.run(&call_info.name, &call_info.call, &call_info.input);
let response = match value {
Ok(value) => PluginResponse::Value(Box::new(value)),
Err(err) => PluginResponse::Error(err),
};
encode_response(&response, &mut std::io::stdout())
.expect("Error encoding response");
}
}
}
}
}

137
crates/nu-plugin/src/plugin/declaration.rs Normal file
View File

@ -0,0 +1,137 @@
use crate::{EncodingType, EvaluatedCall};
use super::{create_command, OUTPUT_BUFFER_SIZE};
use crate::protocol::{CallInfo, PluginCall, PluginResponse};
use std::io::BufReader;
use std::path::{Path, PathBuf};
use nu_protocol::engine::{Command, EngineState, Stack};
use nu_protocol::{ast::Call, Signature, Value};
use nu_protocol::{PipelineData, ShellError};
#[derive(Clone)]
pub struct PluginDeclaration {
name: String,
signature: Signature,
filename: PathBuf,
encoding: EncodingType,
}
impl PluginDeclaration {
pub fn new(filename: PathBuf, signature: Signature, encoding: EncodingType) -> Self {
Self {
name: signature.name.clone(),
signature,
filename,
encoding,
}
}
}
impl Command for PluginDeclaration {
fn name(&self) -> &str {
&self.name
}
fn signature(&self) -> Signature {
self.signature.clone()
}
fn usage(&self) -> &str {
self.signature.usage.as_str()
}
fn run(
&self,
engine_state: &EngineState,
stack: &mut Stack,
call: &Call,
input: PipelineData,
) -> Result<PipelineData, ShellError> {
// Call the command with self path
// Decode information from plugin
// Create PipelineData
let source_file = Path::new(&self.filename);
let mut plugin_cmd = create_command(source_file);
let mut child = plugin_cmd.spawn().map_err(|err| {
let decl = engine_state.get_decl(call.decl_id);
ShellError::SpannedLabeledError(
format!("Unable to spawn plugin for {}", decl.name()),
format!("{}", err),
call.head,
)
})?;
let input = match input {
PipelineData::Value(value, ..) => value,
PipelineData::Stream(stream, ..) => {
let values = stream.collect::<Vec<Value>>();
Value::List {
vals: values,
span: call.head,
}
}
};
// Create message to plugin to indicate that signature is required and
// send call to plugin asking for signature
if let Some(mut stdin_writer) = child.stdin.take() {
let encoding_clone = self.encoding.clone();
let plugin_call = PluginCall::CallInfo(Box::new(CallInfo {
name: self.name.clone(),
call: EvaluatedCall::try_from_call(call, engine_state, stack)?,
input,
}));
std::thread::spawn(move || {
// PluginCall information
encoding_clone.encode_call(&plugin_call, &mut stdin_writer)
});
}
// Deserialize response from plugin to extract the resulting value
let pipeline_data = if let Some(stdout_reader) = &mut child.stdout {
let reader = stdout_reader;
let mut buf_read = BufReader::with_capacity(OUTPUT_BUFFER_SIZE, reader);
let response = self
.encoding
.decode_response(&mut buf_read)
.map_err(|err| {
let decl = engine_state.get_decl(call.decl_id);
ShellError::SpannedLabeledError(
format!("Unable to decode call for {}", decl.name()),
err.to_string(),
call.head,
)
})?;
match response {
PluginResponse::Value(value) => {
Ok(PipelineData::Value(value.as_ref().clone(), None))
}
PluginResponse::Error(err) => Err(err.into()),
PluginResponse::Signature(..) => Err(ShellError::SpannedLabeledError(
"Plugin missing value".into(),
"Received a signature from plugin instead of value".into(),
call.head,
)),
}
} else {
Err(ShellError::SpannedLabeledError(
"Error with stdout reader".into(),
"no stdout reader".into(),
call.head,
))
}?;
// There is no need to wait for the child process to finish
// The response has been collected from the plugin call
Ok(pipeline_data)
}
fn is_plugin(&self) -> Option<(&PathBuf, &str)> {
Some((&self.filename, self.encoding.to_str()))
}
}

161
crates/nu-plugin/src/plugin/mod.rs Normal file
View File

@ -0,0 +1,161 @@
mod declaration;
pub use declaration::PluginDeclaration;
use crate::protocol::{LabeledError, PluginCall, PluginResponse};
use crate::EncodingType;
use std::io::BufReader;
use std::path::Path;
use std::process::{Command as CommandSys, Stdio};
use nu_protocol::ShellError;
use nu_protocol::{Signature, Value};
use super::EvaluatedCall;
const OUTPUT_BUFFER_SIZE: usize = 8192;
pub trait PluginEncoder: Clone {
fn encode_call(
&self,
plugin_call: &PluginCall,
writer: &mut impl std::io::Write,
) -> Result<(), ShellError>;
fn decode_call(&self, reader: &mut impl std::io::BufRead) -> Result<PluginCall, ShellError>;
fn encode_response(
&self,
plugin_response: &PluginResponse,
writer: &mut impl std::io::Write,
) -> Result<(), ShellError>;
fn decode_response(
&self,
reader: &mut impl std::io::BufRead,
) -> Result<PluginResponse, ShellError>;
}
fn create_command(path: &Path) -> CommandSys {
//TODO. The selection of shell could be modifiable from the config file.
let mut process = if cfg!(windows) {
let mut process = CommandSys::new("cmd");
process.arg("/c").arg(path);
process
} else {
let mut process = CommandSys::new("sh");
process.arg("-c").arg(path);
process
};
// Both stdout and stdin are piped so we can receive information from the plugin
process.stdout(Stdio::piped()).stdin(Stdio::piped());
process
}
pub fn get_signature(path: &Path, encoding: &EncodingType) -> Result<Vec<Signature>, ShellError> {
let mut plugin_cmd = create_command(path);
let mut child = plugin_cmd.spawn().map_err(|err| {
ShellError::PluginFailedToLoad(format!("Error spawning child process: {}", err))
})?;
// Create message to plugin to indicate that signature is required and
// send call to plugin asking for signature
if let Some(mut stdin_writer) = child.stdin.take() {
let encoding_clone = encoding.clone();
std::thread::spawn(move || {
encoding_clone.encode_call(&PluginCall::Signature, &mut stdin_writer)
});
}
// deserialize response from plugin to extract the signature
let signatures = if let Some(stdout_reader) = &mut child.stdout {
let reader = stdout_reader;
let mut buf_read = BufReader::with_capacity(OUTPUT_BUFFER_SIZE, reader);
let response = encoding.decode_response(&mut buf_read)?;
match response {
PluginResponse::Signature(sign) => Ok(sign),
PluginResponse::Error(err) => Err(err.into()),
_ => Err(ShellError::PluginFailedToLoad(
"Plugin missing signature".into(),
)),
}
} else {
Err(ShellError::PluginFailedToLoad(
"Plugin missing stdout reader".into(),
))
}?;
// There is no need to wait for the child process to finish since the
// signature has being collected
Ok(signatures)
}
// The next trait and functions are part of the plugin that is being created
// The `Plugin` trait defines the API which plugins use to "hook" into nushell.
pub trait Plugin {
fn signature(&self) -> Vec<Signature>;
fn run(
&mut self,
name: &str,
call: &EvaluatedCall,
input: &Value,
) -> Result<Value, LabeledError>;
}
// Function used in the plugin definition for the communication protocol between
// nushell and the external plugin.
// When creating a new plugin you have to use this function as the main
// entry point for the plugin, e.g.
//
// fn main() {
// serve_plugin(plugin)
// }
//
// where plugin is your struct that implements the Plugin trait
//
// Note. When defining a plugin in other language but Rust, you will have to compile
// the plugin.capnp schema to create the object definitions that will be returned from
// the plugin.
// The object that is expected to be received by nushell is the PluginResponse struct.
// That should be encoded correctly and sent to StdOut for nushell to decode and
// and present its result
pub fn serve_plugin(plugin: &mut impl Plugin, encoder: impl PluginEncoder) {
let mut stdin_buf = BufReader::with_capacity(OUTPUT_BUFFER_SIZE, std::io::stdin());
let plugin_call = encoder.decode_call(&mut stdin_buf);
match plugin_call {
Err(err) => {
let response = PluginResponse::Error(err.into());
encoder
.encode_response(&response, &mut std::io::stdout())
.expect("Error encoding response");
}
Ok(plugin_call) => {
match plugin_call {
// Sending the signature back to nushell to create the declaration definition
PluginCall::Signature => {
let response = PluginResponse::Signature(plugin.signature());
encoder
.encode_response(&response, &mut std::io::stdout())
.expect("Error encoding response");
}
PluginCall::CallInfo(call_info) => {
let value = plugin.run(&call_info.name, &call_info.call, &call_info.input);
let response = match value {
Ok(value) => PluginResponse::Value(Box::new(value)),
Err(err) => PluginResponse::Error(err),
};
encoder
.encode_response(&response, &mut std::io::stdout())
.expect("Error encoding response");
}
}
}
}
}

3
crates/nu-plugin/src/evaluated_call.rs → crates/nu-plugin/src/protocol/evaluated_call.rs
View File

@ -4,12 +4,13 @@ use nu_protocol::{
engine::{EngineState, Stack},
FromValue, ShellError, Span, Spanned, Value,
};
use serde::{Deserialize, Serialize};
// The evaluated call is used with the Plugins because the plugin doesn't have
// access to the Stack and the EngineState. For that reason, before encoding the
// message to the plugin all the arguments to the original call (which are expressions)
// are evaluated and passed to Values
#[derive(Debug, Clone)]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct EvaluatedCall {
pub head: Span,
pub positional: Vec<Value>,

90
crates/nu-plugin/src/protocol/mod.rs Normal file
View File

@ -0,0 +1,90 @@
mod evaluated_call;
pub use evaluated_call::EvaluatedCall;
use nu_protocol::{ShellError, Signature, Span, Value};
use serde::{Deserialize, Serialize};
#[derive(Serialize, Deserialize, Debug)]
pub struct CallInfo {
pub name: String,
pub call: EvaluatedCall,
pub input: Value,
}
// Information sent to the plugin
#[derive(Serialize, Deserialize, Debug)]
pub enum PluginCall {
Signature,
CallInfo(Box<CallInfo>),
}
#[derive(Clone, PartialEq, Serialize, Deserialize, Debug)]
pub struct LabeledError {
pub label: String,
pub msg: String,
pub span: Option<Span>,
}
impl From<LabeledError> for ShellError {
fn from(error: LabeledError) -> Self {
match error.span {
Some(span) => ShellError::SpannedLabeledError(error.label, error.msg, span),
None => ShellError::LabeledError(error.label, error.msg),
}
}
}
impl From<ShellError> for LabeledError {
fn from(error: ShellError) -> Self {
match error {
ShellError::SpannedLabeledError(label, msg, span) => LabeledError {
label,
msg,
span: Some(span),
},
ShellError::LabeledError(label, msg) => LabeledError {
label,
msg,
span: None,
},
ShellError::CantConvert(expected, input, span) => LabeledError {
label: format!("Can't convert to {}", expected),
msg: format!("can't convert {} to {}", expected, input),
span: Some(span),
},
ShellError::DidYouMean(suggestion, span) => LabeledError {
label: "Name not found".into(),
msg: format!("did you mean '{}'", suggestion),
span: Some(span),
},
ShellError::PluginFailedToLoad(msg) => LabeledError {
label: "Plugin failed to load".into(),
msg,
span: None,
},
ShellError::PluginFailedToEncode(msg) => LabeledError {
label: "Plugin failed to encode".into(),
msg,
span: None,
},
ShellError::PluginFailedToDecode(msg) => LabeledError {
label: "Plugin failed to decode".into(),
msg,
span: None,
},
err => LabeledError {
label: "Error - Add to LabeledError From<ShellError>".into(),
msg: err.to_string(),
span: None,
},
}
}
}
// Information received from the plugin
#[derive(Serialize, Deserialize)]
pub enum PluginResponse {
Error(LabeledError),
Signature(Vec<Signature>),
Value(Box<Value>),
}

2
crates/nu-plugin/src/serializers/call.rs → crates/nu-plugin/src/serializers/capnp/call.rs
View File

@ -1,5 +1,5 @@
use super::value;
use crate::{evaluated_call::EvaluatedCall, plugin_capnp::evaluated_call};
use crate::{plugin_capnp::evaluated_call, EvaluatedCall};
use nu_protocol::{ShellError, Span, Spanned, Value};
pub(crate) fn serialize_call(

43
crates/nu-plugin/src/serializers/capnp/mod.rs Normal file
View File

@ -0,0 +1,43 @@
mod call;
mod plugin_call;
mod signature;
mod value;
use nu_protocol::ShellError;
use crate::{plugin::PluginEncoder, protocol::PluginResponse};
#[derive(Clone)]
pub struct CapnpSerializer;
impl PluginEncoder for CapnpSerializer {
fn encode_call(
&self,
plugin_call: &crate::protocol::PluginCall,
writer: &mut impl std::io::Write,
) -> Result<(), nu_protocol::ShellError> {
plugin_call::encode_call(plugin_call, writer)
}
fn decode_call(
&self,
reader: &mut impl std::io::BufRead,
) -> Result<crate::protocol::PluginCall, nu_protocol::ShellError> {
plugin_call::decode_call(reader)
}
fn encode_response(
&self,
plugin_response: &PluginResponse,
writer: &mut impl std::io::Write,
) -> Result<(), ShellError> {
plugin_call::encode_response(plugin_response, writer)
}
fn decode_response(
&self,
reader: &mut impl std::io::BufRead,
) -> Result<PluginResponse, ShellError> {
plugin_call::decode_response(reader)
}
}

9
crates/nu-plugin/src/serializers/plugin_call.rs → crates/nu-plugin/src/serializers/capnp/plugin_call.rs
View File

@ -1,7 +1,7 @@
use crate::plugin::{CallInfo, LabeledError, PluginCall, PluginResponse};
use super::signature::deserialize_signature;
use super::{call, signature, value};
use crate::plugin_capnp::{plugin_call, plugin_response};
use crate::serializers::signature::deserialize_signature;
use crate::serializers::{call, signature, value};
use crate::protocol::{CallInfo, LabeledError, PluginCall, PluginResponse};
use capnp::serialize;
use nu_protocol::{ShellError, Signature, Span};
@ -191,8 +191,7 @@ pub fn decode_response(reader: &mut impl std::io::BufRead) -> Result<PluginRespo
#[cfg(test)]
mod tests {
use super::*;
use crate::evaluated_call::EvaluatedCall;
use crate::plugin::{PluginCall, PluginResponse};
use crate::protocol::{EvaluatedCall, LabeledError, PluginCall, PluginResponse};
use nu_protocol::{Signature, Span, Spanned, SyntaxShape, Value};
#[test]

144
crates/nu-plugin/src/serializers/capnp/schema/plugin.capnp Normal file
View File

@ -0,0 +1,144 @@
@0xb299d30dc02d72bc;
# Schema representing all the structs that are used to comunicate with
# the plugins.
# This schema, together with the command capnp proto is used to generate
# the rust file that defines the serialization/deserialization objects
# required to comunicate with the plugins created for nushell
#
# If you modify the schema remember to compile it to generate the corresponding
# rust file and place that file into the main nu-plugin folder.
# After compiling, you may need to run cargo fmt on the file so it passes the CI
struct Err(T) {
union {
err @0 :Text;
ok @1 :T;
}
}
struct Map(Key, Value) {
struct Entry {
key @0 :Key;
value @1 :Value;
}
entries @0 :List(Entry);
}
# Main plugin structures
struct Span {
start @0 :UInt64;
end @1 :UInt64;
}
# Resulting value from plugin
struct Value {
span @0: Span;
union {
void @1 :Void;
bool @2 :Bool;
int @3 :Int64;
float @4 :Float64;
string @5 :Text;
list @6 :List(Value);
record @7: Record;
}
}
struct Record {
cols @0 :List(Text);
vals @1 :List(Value);
}
# Structs required to define the plugin signature
struct Signature {
name @0 :Text;
usage @1 :Text;
extraUsage @2 :Text;
requiredPositional @3 :List(Argument);
optionalPositional @4 :List(Argument);
# Optional value. Check for existence when deserializing
rest @5 :Argument;
named @6 :List(Flag);
isFilter @7 :Bool;
category @8 :Category;
}
enum Category {
default @0;
conversions @1;
core @2;
date @3;
env @4;
experimental @5;
filesystem @6;
filters @7;
formats @8;
math @9;
strings @10;
system @11;
viewers @12;
}
struct Flag {
long @0 :Text;
# Optional value. Check for existence when deserializing (has_short)
short @1 :Text;
arg @2 :Shape;
required @3 :Bool;
desc @4 :Text;
}
struct Argument {
name @0 :Text;
desc @1 :Text;
shape @2 :Shape;
}
# If we require more complex signatures for the plugins this could be
# changed to a union
enum Shape {
none @0;
any @1;
string @2;
number @3;
int @4;
boolean @5;
}
struct EvaluatedCall {
head @0: Span;
positional @1 :List(Value);
# The value in the map can be optional
# Check for existence when deserializing
named @2 :Map(Text, Value);
}
struct CallInfo {
name @0 :Text;
call @1 :EvaluatedCall;
input @2 :Value;
}
# Main communication structs with the plugin
struct PluginCall {
union {
signature @0 :Void;
callInfo @1 :CallInfo;
}
}
struct PluginResponse {
union {
error @0 :LabeledError;
signature @1 :List(Signature);
value @2 :Value;
}
}
struct LabeledError {
label @0 :Text;
msg @1 :Text;
# Optional Value. When decoding check if it exists (has_span)
span @2 :Span;
}

0
crates/nu-plugin/src/serializers/signature.rs → crates/nu-plugin/src/serializers/capnp/signature.rs
View File

0
crates/nu-plugin/src/serializers/value.rs → crates/nu-plugin/src/serializers/capnp/value.rs
View File

284
crates/nu-plugin/src/serializers/json.rs Normal file
View File

@ -0,0 +1,284 @@
use nu_protocol::ShellError;
use crate::{plugin::PluginEncoder, protocol::PluginResponse};
#[derive(Clone)]
pub struct JsonSerializer;
impl PluginEncoder for JsonSerializer {
fn encode_call(
&self,
plugin_call: &crate::protocol::PluginCall,
writer: &mut impl std::io::Write,
) -> Result<(), nu_protocol::ShellError> {
serde_json::to_writer(writer, plugin_call)
.map_err(|err| ShellError::PluginFailedToEncode(err.to_string()))
}
fn decode_call(
&self,
reader: &mut impl std::io::BufRead,
) -> Result<crate::protocol::PluginCall, nu_protocol::ShellError> {
serde_json::from_reader(reader)
.map_err(|err| ShellError::PluginFailedToEncode(err.to_string()))
}
fn encode_response(
&self,
plugin_response: &PluginResponse,
writer: &mut impl std::io::Write,
) -> Result<(), ShellError> {
serde_json::to_writer(writer, plugin_response)
.map_err(|err| ShellError::PluginFailedToEncode(err.to_string()))
}
fn decode_response(
&self,
reader: &mut impl std::io::BufRead,
) -> Result<PluginResponse, ShellError> {
serde_json::from_reader(reader)
.map_err(|err| ShellError::PluginFailedToEncode(err.to_string()))
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::protocol::{CallInfo, EvaluatedCall, LabeledError, PluginCall, PluginResponse};
use nu_protocol::{Signature, Span, Spanned, SyntaxShape, Value};
#[test]
fn callinfo_round_trip_signature() {
let plugin_call = PluginCall::Signature;
let encoder = JsonSerializer {};
let mut buffer: Vec<u8> = Vec::new();
encoder
.encode_call(&plugin_call, &mut buffer)
.expect("unable to serialize message");
let returned = encoder
.decode_call(&mut buffer.as_slice())
.expect("unable to deserialize message");
match returned {
PluginCall::Signature => {}
PluginCall::CallInfo(_) => panic!("decoded into wrong value"),
}
}
#[test]
fn callinfo_round_trip_callinfo() {
let name = "test".to_string();
let input = Value::Bool {
val: false,
span: Span { start: 1, end: 20 },
};
let call = EvaluatedCall {
head: Span { start: 0, end: 10 },
positional: vec![
Value::Float {
val: 1.0,
span: Span { start: 0, end: 10 },
},
Value::String {
val: "something".into(),
span: Span { start: 0, end: 10 },
},
],
named: vec![(
Spanned {
item: "name".to_string(),
span: Span { start: 0, end: 10 },
},
Some(Value::Float {
val: 1.0,
span: Span { start: 0, end: 10 },
}),
)],
};
let plugin_call = PluginCall::CallInfo(Box::new(CallInfo {
name: name.clone(),
call: call.clone(),
input: input.clone(),
}));
let encoder = JsonSerializer {};
let mut buffer: Vec<u8> = Vec::new();
encoder
.encode_call(&plugin_call, &mut buffer)
.expect("unable to serialize message");
let returned = encoder
.decode_call(&mut buffer.as_slice())
.expect("unable to deserialize message");
match returned {
PluginCall::Signature => panic!("returned wrong call type"),
PluginCall::CallInfo(call_info) => {
assert_eq!(name, call_info.name);
assert_eq!(input, call_info.input);
assert_eq!(call.head, call_info.call.head);
assert_eq!(call.positional.len(), call_info.call.positional.len());
call.positional
.iter()
.zip(call_info.call.positional.iter())
.for_each(|(lhs, rhs)| assert_eq!(lhs, rhs));
call.named
.iter()
.zip(call_info.call.named.iter())
.for_each(|(lhs, rhs)| {
// Comparing the keys
assert_eq!(lhs.0.item, rhs.0.item);
match (&lhs.1, &rhs.1) {
(None, None) => {}
(Some(a), Some(b)) => assert_eq!(a, b),
_ => panic!("not matching values"),
}
});
}
}
}
#[test]
fn response_round_trip_signature() {
let signature = Signature::build("nu-plugin")
.required("first", SyntaxShape::String, "first required")
.required("second", SyntaxShape::Int, "second required")
.required_named("first_named", SyntaxShape::String, "first named", Some('f'))
.required_named(
"second_named",
SyntaxShape::String,
"second named",
Some('s'),
)
.rest("remaining", SyntaxShape::Int, "remaining");
let response = PluginResponse::Signature(vec![signature.clone()]);
let encoder = JsonSerializer {};
let mut buffer: Vec<u8> = Vec::new();
encoder
.encode_response(&response, &mut buffer)
.expect("unable to serialize message");
let returned = encoder
.decode_response(&mut buffer.as_slice())
.expect("unable to deserialize message");
match returned {
PluginResponse::Error(_) => panic!("returned wrong call type"),
PluginResponse::Value(_) => panic!("returned wrong call type"),
PluginResponse::Signature(returned_signature) => {
assert!(returned_signature.len() == 1);
assert_eq!(signature.name, returned_signature[0].name);
assert_eq!(signature.usage, returned_signature[0].usage);
assert_eq!(signature.extra_usage, returned_signature[0].extra_usage);
assert_eq!(signature.is_filter, returned_signature[0].is_filter);
signature
.required_positional
.iter()
.zip(returned_signature[0].required_positional.iter())
.for_each(|(lhs, rhs)| assert_eq!(lhs, rhs));
signature
.optional_positional
.iter()
.zip(returned_signature[0].optional_positional.iter())
.for_each(|(lhs, rhs)| assert_eq!(lhs, rhs));
signature
.named
.iter()
.zip(returned_signature[0].named.iter())
.for_each(|(lhs, rhs)| assert_eq!(lhs, rhs));
assert_eq!(
signature.rest_positional,
returned_signature[0].rest_positional,
);
}
}
}
#[test]
fn response_round_trip_value() {
let value = Value::Int {
val: 10,
span: Span { start: 2, end: 30 },
};
let response = PluginResponse::Value(Box::new(value.clone()));
let encoder = JsonSerializer {};
let mut buffer: Vec<u8> = Vec::new();
encoder
.encode_response(&response, &mut buffer)
.expect("unable to serialize message");
let returned = encoder
.decode_response(&mut buffer.as_slice())
.expect("unable to deserialize message");
match returned {
PluginResponse::Error(_) => panic!("returned wrong call type"),
PluginResponse::Signature(_) => panic!("returned wrong call type"),
PluginResponse::Value(returned_value) => {
assert_eq!(&value, returned_value.as_ref())
}
}
}
#[test]
fn response_round_trip_error() {
let error = LabeledError {
label: "label".into(),
msg: "msg".into(),
span: Some(Span { start: 2, end: 30 }),
};
let response = PluginResponse::Error(error.clone());
let encoder = JsonSerializer {};
let mut buffer: Vec<u8> = Vec::new();
encoder
.encode_response(&response, &mut buffer)
.expect("unable to serialize message");
let returned = encoder
.decode_response(&mut buffer.as_slice())
.expect("unable to deserialize message");
match returned {
PluginResponse::Error(msg) => assert_eq!(error, msg),
PluginResponse::Signature(_) => panic!("returned wrong call type"),
PluginResponse::Value(_) => panic!("returned wrong call type"),
}
}
#[test]
fn response_round_trip_error_none() {
let error = LabeledError {
label: "label".into(),
msg: "msg".into(),
span: None,
};
let response = PluginResponse::Error(error.clone());
let encoder = JsonSerializer {};
let mut buffer: Vec<u8> = Vec::new();
encoder
.encode_response(&response, &mut buffer)
.expect("unable to serialize message");
let returned = encoder
.decode_response(&mut buffer.as_slice())
.expect("unable to deserialize message");
match returned {
PluginResponse::Error(msg) => assert_eq!(error, msg),
PluginResponse::Signature(_) => panic!("returned wrong call type"),
PluginResponse::Value(_) => panic!("returned wrong call type"),
}
}
}

78
crates/nu-plugin/src/serializers/mod.rs
View File

@ -1,6 +1,74 @@
mod call;
mod plugin_call;
mod signature;
mod value;
use nu_protocol::ShellError;
pub use plugin_call::*;
use crate::{
plugin::PluginEncoder,
protocol::{PluginCall, PluginResponse},
};
pub mod capnp;
pub mod json;
#[derive(Clone)]
pub enum EncodingType {
Capnp(capnp::CapnpSerializer),
Json(json::JsonSerializer),
}
impl EncodingType {
pub fn try_from_bytes(bytes: &[u8]) -> Option<Self> {
match bytes {
b"capnp" => Some(Self::Capnp(capnp::CapnpSerializer {})),
b"json" => Some(Self::Json(json::JsonSerializer {})),
_ => None,
}
}
pub fn encode_call(
&self,
plugin_call: &PluginCall,
writer: &mut impl std::io::Write,
) -> Result<(), ShellError> {
match self {
EncodingType::Capnp(encoder) => encoder.encode_call(plugin_call, writer),
EncodingType::Json(encoder) => encoder.encode_call(plugin_call, writer),
}
}
pub fn decode_call(
&self,
reader: &mut impl std::io::BufRead,
) -> Result<PluginCall, ShellError> {
match self {
EncodingType::Capnp(encoder) => encoder.decode_call(reader),
EncodingType::Json(encoder) => encoder.decode_call(reader),
}
}
pub fn encode_response(
&self,
plugin_response: &PluginResponse,
writer: &mut impl std::io::Write,
) -> Result<(), ShellError> {
match self {
EncodingType::Capnp(encoder) => encoder.encode_response(plugin_response, writer),
EncodingType::Json(encoder) => encoder.encode_response(plugin_response, writer),
}
}
pub fn decode_response(
&self,
reader: &mut impl std::io::BufRead,
) -> Result<PluginResponse, ShellError> {
match self {
EncodingType::Capnp(encoder) => encoder.decode_response(reader),
EncodingType::Json(encoder) => encoder.decode_response(reader),
}
}
pub fn to_str(&self) -> &'static str {
match self {
Self::Capnp(_) => "capnp",
Self::Json(_) => "json",
}
}
}