Skip to main content

xs/nu/
engine.rs

1use nu_cli::{add_cli_context, gather_parent_env_vars};
2use nu_cmd_lang::create_default_context;
3use nu_command::add_shell_command_context;
4use nu_engine::eval_block_with_early_return;
5use nu_parser::parse;
6use nu_plugin_engine::{add_plugin_to_working_set, GetPlugin, PluginDeclaration};
7use nu_protocol::debugger::WithoutDebug;
8use nu_protocol::engine::{Closure, Command, EngineState, Redirection, Stack, StateWorkingSet};
9use nu_protocol::engine::{Job, ThreadJob};
10use nu_protocol::shell_error::generic::GenericError;
11use nu_protocol::{
12    OutDest, PipelineData, PipelineExecutionData, PluginIdentity, RegisteredPlugin, ShellError,
13    Span, Value,
14};
15
16use std::path::PathBuf;
17use std::sync::{Arc, Mutex};
18
19use serde_json::Value as JsonValue;
20
21use crate::error::Error;
22use crate::nu::commands;
23use crate::store::{Frame, Store};
24
25#[derive(Clone)]
26pub struct Engine {
27    pub state: EngineState,
28}
29
30impl Engine {
31    pub fn new() -> Result<Self, Error> {
32        let mut engine_state = create_default_context();
33        engine_state = add_shell_command_context(engine_state);
34        engine_state = add_cli_context(engine_state);
35        nu_std::load_standard_library(&mut engine_state)?;
36
37        let init_cwd = std::env::current_dir()?;
38        gather_parent_env_vars(&mut engine_state, init_cwd.as_ref());
39
40        // Only xs sets the append metadata, per instance via set_append_meta.
41        // Nushell exports $env to externals, so a process started from inside
42        // a service (a shell in a pty, a nested xs) inherits the parent's
43        // identity. Left in place it would be stamped on every frame this
44        // engine appends.
45        let key = nu_protocol::engine::EnvName::from(
46            commands::append_command::APPEND_META_ENV.to_string(),
47        );
48        for vars in Arc::make_mut(&mut engine_state.env_vars).values_mut() {
49            vars.remove(&key);
50        }
51
52        Ok(Self {
53            state: engine_state,
54        })
55    }
56
57    pub fn add_commands(&mut self, commands: Vec<Box<dyn Command>>) -> Result<(), Error> {
58        let mut working_set = StateWorkingSet::new(&self.state);
59        for command in commands {
60            working_set.add_decl(command);
61        }
62        self.state.merge_delta(working_set.render())?;
63        Ok(())
64    }
65
66    /// Register Nushell plugin binaries (`nu_plugin_*`) on this engine. Each
67    /// plugin is spawned once to read its signatures, so a bad path or an
68    /// incompatible plugin fails here rather than on first use.
69    pub fn add_plugins(&mut self, paths: &[PathBuf]) -> Result<(), Error> {
70        let mut working_set = StateWorkingSet::new(&self.state);
71        for path in paths {
72            let mut load = || -> Result<(), Error> {
73                let filename = std::fs::canonicalize(path)?;
74                let identity = PluginIdentity::new(&filename, None)
75                    .map_err(|_| "file name must start with nu_plugin_")?;
76                let plugin = add_plugin_to_working_set(&mut working_set, &identity)?;
77                let interface = plugin.clone().get_plugin(None)?;
78                plugin.set_metadata(Some(interface.get_metadata()?));
79                for signature in interface.get_signature()? {
80                    working_set
81                        .add_decl(Box::new(PluginDeclaration::new(plugin.clone(), signature)));
82                }
83                Ok(())
84            };
85            load().map_err(|e| format!("failed to load plugin {}: {e}", path.display()))?;
86        }
87        self.state.merge_delta(working_set.render())?;
88        Ok(())
89    }
90
91    pub fn add_alias(&mut self, name: &str, target: &str) -> Result<(), Error> {
92        let mut working_set = StateWorkingSet::new(&self.state);
93        let _ = parse(
94            &mut working_set,
95            None,
96            format!("alias {name} = {target}").as_bytes(),
97            false,
98        );
99        self.state.merge_delta(working_set.render())?;
100        Ok(())
101    }
102
103    pub fn eval(&self, input: PipelineData, expression: String) -> Result<PipelineData, String> {
104        let mut working_set = StateWorkingSet::new(&self.state);
105        let block = parse(&mut working_set, None, expression.as_bytes(), false);
106
107        if !working_set.parse_errors.is_empty() {
108            let first_error = &working_set.parse_errors[0];
109            let formatted = nu_protocol::format_cli_error(None, &working_set, first_error, None);
110            return Err(formatted);
111        }
112
113        let mut engine_state = self.state.clone();
114        engine_state
115            .merge_delta(working_set.render())
116            .map_err(|e| {
117                let working_set = StateWorkingSet::new(&self.state);
118                nu_protocol::format_cli_error(None, &working_set, &e, None)
119            })?;
120
121        let mut stack = Stack::new();
122        let mut stack =
123            stack.push_redirection(Some(Redirection::Pipe(OutDest::PipeSeparate)), None);
124
125        eval_block_with_early_return::<WithoutDebug>(&engine_state, &mut stack, &block, input)
126            .map(|exec_data| exec_data.body)
127            .map_err(|e| {
128                let working_set = StateWorkingSet::new(&engine_state);
129                nu_protocol::format_cli_error(None, &working_set, &e, None)
130            })
131    }
132
133    pub fn parse_closure(&mut self, script: &str) -> Result<Closure, Box<ShellError>> {
134        let mut working_set = StateWorkingSet::new(&self.state);
135        let block = parse(&mut working_set, None, script.as_bytes(), false);
136        self.state
137            .merge_delta(working_set.render())
138            .map_err(Box::new)?;
139
140        let mut stack = Stack::new();
141        let result = eval_block_with_early_return::<WithoutDebug>(
142            &self.state,
143            &mut stack,
144            &block,
145            PipelineData::empty(),
146        )
147        .map_err(Box::new)?;
148        let closure = result
149            .body
150            .into_value(Span::unknown())
151            .map_err(Box::new)?
152            .into_closure()
153            .map_err(Box::new)?;
154
155        self.state.merge_env(&mut stack).map_err(Box::new)?;
156
157        Ok(closure)
158    }
159
160    pub fn add_module(&mut self, name: &str, content: &str) -> Result<(), Box<ShellError>> {
161        let mut working_set = StateWorkingSet::new(&self.state);
162
163        // Create temporary file with .nu extension that will be cleaned up when temp_dir is dropped
164        let temp_dir = tempfile::TempDir::new().map_err(|e| {
165            Box::new(ShellError::Generic(GenericError::new_internal(
166                "I/O Error",
167                format!("Failed to create temporary directory for module '{name}': {e}"),
168            )))
169        })?;
170        let module_path = temp_dir.path().join(format!("{name}.nu"));
171        std::fs::write(&module_path, content).map_err(|e| {
172            Box::new(ShellError::Generic(GenericError::new_internal(
173                "I/O Error",
174                e.to_string(),
175            )))
176        })?;
177
178        // Parse the use statement
179        let use_stmt = format!("use {}", module_path.display());
180        let _block = parse(&mut working_set, None, use_stmt.as_bytes(), false);
181
182        // Check for parse errors
183        if !working_set.parse_errors.is_empty() {
184            let first_error = &working_set.parse_errors[0];
185            return Err(Box::new(ShellError::Generic(GenericError::new(
186                "Parse error",
187                first_error.to_string(),
188                first_error.span(),
189            ))));
190        }
191
192        // Merge changes into engine state
193        self.state
194            .merge_delta(working_set.render())
195            .map_err(Box::new)?;
196
197        // Create a temporary stack and evaluate the module
198        let mut stack = Stack::new();
199        let _ = eval_block_with_early_return::<WithoutDebug>(
200            &self.state,
201            &mut stack,
202            &_block,
203            PipelineData::empty(),
204        )
205        .map_err(Box::new)?;
206
207        // Merge environment variables into engine state
208        self.state.merge_env(&mut stack).map_err(Box::new)?;
209
210        Ok(())
211    }
212
213    pub fn with_env_vars(
214        mut self,
215        vars: impl IntoIterator<Item = (String, String)>,
216    ) -> Result<Self, Error> {
217        for (key, value) in vars {
218            self.state
219                .add_env_var(key, nu_protocol::Value::string(value, Span::unknown()));
220        }
221
222        Ok(self)
223    }
224
225    /// Set the base metadata stamped on frames this engine's `.append` writes
226    /// (`service_id`, `{action_id, frame_id}`, ...). Injected as `$env` so the
227    /// `.append` decl stays instance-independent. See `append_command`.
228    pub fn set_append_meta(&mut self, meta: &JsonValue) {
229        self.state.add_env_var(
230            crate::nu::commands::append_command::APPEND_META_ENV.to_string(),
231            Value::string(meta.to_string(), Span::unknown()),
232        );
233    }
234
235    pub fn run_closure_in_job(
236        &mut self,
237        closure: &nu_protocol::engine::Closure,
238        args: Vec<Value>,
239        pipeline_input: Option<PipelineData>,
240        job_name: impl Into<String>,
241    ) -> Result<PipelineData, Box<ShellError>> {
242        self.run_closure_in_job_with_exit(closure, args, pipeline_input, job_name)
243            .map(|exec_data| exec_data.body)
244    }
245
246    /// Like `run_closure_in_job`, but keep the exit status guards of the
247    /// pipeline's external commands. The caller drains `body` and then checks
248    /// `exit` with `nu_protocol::process::check_exit_status_future`, which is
249    /// how nu reports an external that exited non-zero mid-pipeline.
250    pub fn run_closure_in_job_with_exit(
251        &mut self,
252        closure: &nu_protocol::engine::Closure,
253        args: Vec<Value>,
254        pipeline_input: Option<PipelineData>,
255        job_name: impl Into<String>,
256    ) -> Result<PipelineExecutionData, Box<ShellError>> {
257        let job_display_name = job_name.into(); // Convert job_name early for error messages
258
259        // -- create & register job (boilerplate) ---
260        let (sender, _rx) = std::sync::mpsc::channel();
261        let job = ThreadJob::new(
262            self.state.signals().clone(),
263            Some(job_display_name.clone()),
264            sender,
265        );
266        let _job_id = {
267            let mut j = self.state.jobs.lock().unwrap();
268            j.add_job(Job::Thread(job.clone()))
269        };
270
271        // -- temporarily attach the job to self.state (boilerplate) ---
272        let saved_bg_job = self.state.current_job.background_thread_job.clone();
273        self.state.current_job.background_thread_job = Some(job.clone());
274
275        // -- prepare stack & validate/inject positional arguments ---
276        let block = self.state.get_block(closure.block_id);
277        let mut stack = Stack::new();
278        let mut stack =
279            stack.push_redirection(Some(Redirection::Pipe(OutDest::PipeSeparate)), None);
280
281        let num_required = block.signature.required_positional.len();
282        let num_optional = block.signature.optional_positional.len();
283        let total_positional = num_required + num_optional;
284
285        if args.len() > total_positional {
286            return Err(Box::new(ShellError::Generic(GenericError::new(
287                format!(
288                    "Too many arguments for job '{job_display_name}': got {}, closure accepts at most {total_positional}.",
289                    args.len()
290                ),
291                format!("Closure signature: {name}", name = block.signature.name),
292                block.span.unwrap_or_else(Span::unknown),
293            ))));
294        }
295
296        if args.len() < num_required {
297            return Err(Box::new(ShellError::Generic(GenericError::new(
298                format!(
299                    "Job '{job_display_name}' run closure expects {num_required} required argument(s), but {} were provided.",
300                    args.len()
301                ),
302                format!("Closure signature: {name}", name = block.signature.name),
303                block.span.unwrap_or_else(Span::unknown),
304            ))));
305        }
306
307        // Inject provided positional args
308        for (i, val) in args.iter().enumerate() {
309            let param = if i < num_required {
310                &block.signature.required_positional[i]
311            } else {
312                &block.signature.optional_positional[i - num_required]
313            };
314            if let Some(var_id) = param.var_id {
315                stack.add_var(var_id, val.clone());
316            }
317        }
318
319        // Set default values for optional params not covered by provided args
320        let optional_covered = args.len().saturating_sub(num_required);
321        for i in optional_covered..num_optional {
322            let param = &block.signature.optional_positional[i];
323            if let Some(var_id) = param.var_id {
324                let default = param
325                    .default_value
326                    .clone()
327                    .unwrap_or_else(|| Value::nothing(Span::unknown()));
328                stack.add_var(var_id, default);
329            }
330        }
331
332        // Determine the actual pipeline input for eval_block_with_early_return
333        let eval_pipeline_input = pipeline_input.unwrap_or_else(PipelineData::empty);
334
335        // -- run using eval_block_with_early_return ---
336        let eval_res = nu_engine::eval_block_with_early_return::<WithoutDebug>(
337            &self.state,
338            &mut stack,
339            block,
340            eval_pipeline_input,
341        );
342
343        // -- merge env, restore job, cleanup job (boilerplate, same as before) ---
344        if eval_res.is_ok() {
345            if let Err(e) = self.state.merge_env(&mut stack) {
346                tracing::error!(
347                    "Failed to merge environment from job '{}': {}",
348                    job_display_name,
349                    e
350                );
351            }
352        }
353
354        self.state.current_job.background_thread_job = saved_bg_job;
355        eval_res.map_err(Box::new)
356    }
357
358    /// Evaluate a closure WITHOUT creating and registering a fresh
359    /// `ThreadJob` per call. `run_closure_in_job` allocates an mpsc channel,
360    /// builds a `ThreadJob`, locks `self.state.jobs` and `add_job`s it -- and
361    /// never removes it -- on every invocation. In a hot per-frame actor loop
362    /// that churn (plus the unbounded jobs-table growth) dominated the cost.
363    /// The caller is expected to have attached a single long-lived background
364    /// job to `self.state` once (see the actor `EngineWorker`); this method
365    /// just sets up the stack, injects positional args, and evaluates.
366    pub fn eval_closure_no_job(
367        &mut self,
368        closure: &nu_protocol::engine::Closure,
369        args: Vec<Value>,
370        pipeline_input: Option<PipelineData>,
371    ) -> Result<PipelineData, Box<ShellError>> {
372        let block = self.state.get_block(closure.block_id);
373        let mut stack = Stack::new();
374        let mut stack =
375            stack.push_redirection(Some(Redirection::Pipe(OutDest::PipeSeparate)), None);
376
377        let num_required = block.signature.required_positional.len();
378        let num_optional = block.signature.optional_positional.len();
379        let total_positional = num_required + num_optional;
380
381        if args.len() > total_positional {
382            return Err(Box::new(ShellError::Generic(GenericError::new(
383                format!(
384                    "Too many arguments for actor closure: got {}, closure accepts at most {total_positional}.",
385                    args.len()
386                ),
387                format!("Closure signature: {name}", name = block.signature.name),
388                block.span.unwrap_or_else(Span::unknown),
389            ))));
390        }
391
392        if args.len() < num_required {
393            return Err(Box::new(ShellError::Generic(GenericError::new(
394                format!(
395                    "Actor closure expects {num_required} required argument(s), but {} were provided.",
396                    args.len()
397                ),
398                format!("Closure signature: {name}", name = block.signature.name),
399                block.span.unwrap_or_else(Span::unknown),
400            ))));
401        }
402
403        for (i, val) in args.iter().enumerate() {
404            let param = if i < num_required {
405                &block.signature.required_positional[i]
406            } else {
407                &block.signature.optional_positional[i - num_required]
408            };
409            if let Some(var_id) = param.var_id {
410                stack.add_var(var_id, val.clone());
411            }
412        }
413
414        let optional_covered = args.len().saturating_sub(num_required);
415        for i in optional_covered..num_optional {
416            let param = &block.signature.optional_positional[i];
417            if let Some(var_id) = param.var_id {
418                let default = param
419                    .default_value
420                    .clone()
421                    .unwrap_or_else(|| Value::nothing(Span::unknown()));
422                stack.add_var(var_id, default);
423            }
424        }
425
426        let eval_pipeline_input = pipeline_input.unwrap_or_else(PipelineData::empty);
427        let eval_res = nu_engine::eval_block_with_early_return::<WithoutDebug>(
428            &self.state,
429            &mut stack,
430            block,
431            eval_pipeline_input,
432        );
433
434        if eval_res.is_ok() {
435            if let Err(e) = self.state.merge_env(&mut stack) {
436                tracing::error!("Failed to merge environment from actor closure: {}", e);
437            }
438        }
439
440        eval_res.map(|exec_data| exec_data.body).map_err(Box::new)
441    }
442
443    /// Attach a single long-lived background `ThreadJob` to this engine's
444    /// state. Call once before a hot eval loop so `eval_closure_no_job` can
445    /// skip per-call job creation. Signals still propagate (the job shares
446    /// `self.state.signals()`).
447    pub fn attach_background_job(&mut self, name: impl Into<String>) {
448        let (sender, _rx) = std::sync::mpsc::channel();
449        let job = ThreadJob::new(self.state.signals().clone(), Some(name.into()), sender);
450        {
451            let mut j = self.state.jobs.lock().unwrap();
452            j.add_job(Job::Thread(job.clone()));
453        }
454        self.state.current_job.background_thread_job = Some(job);
455    }
456
457    /// Kill the background ThreadJob whose name equals `name`.
458    pub fn kill_job_by_name(&self, name: &str) {
459        if let Ok(mut jobs) = self.state.jobs.lock() {
460            let job_id = {
461                jobs.iter().find_map(|(jid, job)| {
462                    job.description()
463                        .and_then(|desc| if desc == name { Some(jid) } else { None })
464                })
465            };
466            if let Some(job_id) = job_id {
467                let _ = jobs.kill_and_remove(job_id);
468            }
469        }
470    }
471}
472
473/// Add core cross.stream commands that are common across all Nushell pipeline runners
474pub fn add_core_commands(engine: &mut Engine, store: &Store) -> Result<(), Error> {
475    engine.add_commands(vec![
476        Box::new(commands::cas_command::CasCommand::new(store.clone())),
477        Box::new(commands::get_command::GetCommand::new(store.clone())),
478        Box::new(commands::remove_command::RemoveCommand::new(store.clone())),
479        Box::new(commands::scru128_command::Scru128Command::new()),
480        Box::new(commands::scru128_command::Scru128UnpackCommand::new()),
481        Box::new(commands::scru128_command::Scru128PackCommand::new()),
482    ])
483}
484
485/// How `.append` behaves. This is the one store command whose behaviour
486/// genuinely varies by runner.
487pub enum AppendMode {
488    /// Write straight to the store. The per-instance base metadata is injected
489    /// via the `XS_APPEND_META` env var (see `append_command`), not baked in.
490    Direct,
491    /// Buffer appended frames into `output` for the caller to flush (actors).
492    Buffered(Arc<Mutex<Vec<Frame>>>),
493}
494
495/// Register the `.cat` and `.last` read builtins for a pipeline runner. Both
496/// commands stream through the store's runtime-backed `read()` and support
497/// `--follow`, serving historical and follow reads from a single impl.
498pub fn add_read_commands(engine: &mut Engine, store: &Store) -> Result<(), Error> {
499    engine.add_commands(vec![
500        Box::new(commands::cat_command::CatCommand::new(store.clone())),
501        Box::new(commands::last_command::LastCommand::new(store.clone())),
502    ])
503}
504
505/// Register the write builtins for a pipeline runner: `.append` (per `mode`)
506/// plus `.import` and `.cas-post`, which are identical across runners.
507pub fn add_write_commands(
508    engine: &mut Engine,
509    store: &Store,
510    mode: AppendMode,
511) -> Result<(), Error> {
512    engine.add_commands(vec![
513        Box::new(commands::import_command::ImportCommand::new(store.clone())),
514        Box::new(commands::cas_post_command::CasPostCommand::new(
515            store.clone(),
516        )),
517    ])?;
518    match mode {
519        AppendMode::Direct => engine.add_commands(vec![Box::new(
520            commands::append_command::AppendCommand::new(store.clone()),
521        )]),
522        AppendMode::Buffered(output) => engine.add_commands(vec![Box::new(
523            commands::append_command_buffered::AppendCommand::new(store.clone(), output),
524        )]),
525    }
526}
527
528/// The module-free, instance-free base engine for a runner: nushell + stdlib +
529/// the core builtins + the `.rm` alias + the read builtins, plus the `.append`
530/// write builtin for direct writers. Build this once per runner and `clone()` it per
531/// spawn or restart; `load_modules(as_of)` and `set_append_meta(..)` specialize
532/// each clone. Actors pass `direct_write: false` and add their per-instance
533/// buffered `.append` to the clone.
534pub fn prepared_base(store: &Store, direct_write: bool) -> Result<Engine, Error> {
535    // Clone the embedder's base engine when the store carries one, else build
536    // the default. See ADR 0007.
537    let mut engine = match store.base_engine() {
538        Some(base) => Engine {
539            state: base.clone(),
540        },
541        None => Engine::new()?,
542    };
543    add_core_commands(&mut engine, store)?;
544    engine.add_alias(".rm", ".remove")?;
545    add_read_commands(&mut engine, store)?;
546    if direct_write {
547        add_write_commands(&mut engine, store, AppendMode::Direct)?;
548    }
549    Ok(engine)
550}