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            false,
265            sender,
266        );
267        let _job_id = {
268            let mut j = self.state.jobs.lock().unwrap();
269            j.add_job(Job::Thread(job.clone()))
270        };
271
272        // -- temporarily attach the job to self.state (boilerplate) ---
273        let saved_bg_job = self.state.current_job.background_thread_job.clone();
274        self.state.current_job.background_thread_job = Some(job.clone());
275
276        // -- prepare stack & validate/inject positional arguments ---
277        let block = self.state.get_block(closure.block_id);
278        let mut stack = Stack::new();
279        let mut stack =
280            stack.push_redirection(Some(Redirection::Pipe(OutDest::PipeSeparate)), None);
281
282        let num_required = block.signature.required_positional.len();
283        let num_optional = block.signature.optional_positional.len();
284        let total_positional = num_required + num_optional;
285
286        if args.len() > total_positional {
287            return Err(Box::new(ShellError::Generic(GenericError::new(
288                format!(
289                    "Too many arguments for job '{job_display_name}': got {}, closure accepts at most {total_positional}.",
290                    args.len()
291                ),
292                format!("Closure signature: {name}", name = block.signature.name),
293                block.span.unwrap_or_else(Span::unknown),
294            ))));
295        }
296
297        if args.len() < num_required {
298            return Err(Box::new(ShellError::Generic(GenericError::new(
299                format!(
300                    "Job '{job_display_name}' run closure expects {num_required} required argument(s), but {} were provided.",
301                    args.len()
302                ),
303                format!("Closure signature: {name}", name = block.signature.name),
304                block.span.unwrap_or_else(Span::unknown),
305            ))));
306        }
307
308        // Inject provided positional args
309        for (i, val) in args.iter().enumerate() {
310            let param = if i < num_required {
311                &block.signature.required_positional[i]
312            } else {
313                &block.signature.optional_positional[i - num_required]
314            };
315            if let Some(var_id) = param.var_id {
316                stack.add_var(var_id, val.clone());
317            }
318        }
319
320        // Set default values for optional params not covered by provided args
321        let optional_covered = args.len().saturating_sub(num_required);
322        for i in optional_covered..num_optional {
323            let param = &block.signature.optional_positional[i];
324            if let Some(var_id) = param.var_id {
325                let default = param
326                    .default_value
327                    .clone()
328                    .unwrap_or_else(|| Value::nothing(Span::unknown()));
329                stack.add_var(var_id, default);
330            }
331        }
332
333        // Determine the actual pipeline input for eval_block_with_early_return
334        let eval_pipeline_input = pipeline_input.unwrap_or_else(PipelineData::empty);
335
336        // -- run using eval_block_with_early_return ---
337        let eval_res = nu_engine::eval_block_with_early_return::<WithoutDebug>(
338            &self.state,
339            &mut stack,
340            block,
341            eval_pipeline_input,
342        );
343
344        // -- merge env, restore job, cleanup job (boilerplate, same as before) ---
345        if eval_res.is_ok() {
346            if let Err(e) = self.state.merge_env(&mut stack) {
347                tracing::error!(
348                    "Failed to merge environment from job '{}': {}",
349                    job_display_name,
350                    e
351                );
352            }
353        }
354
355        self.state.current_job.background_thread_job = saved_bg_job;
356        eval_res.map_err(Box::new)
357    }
358
359    /// Evaluate a closure WITHOUT creating and registering a fresh
360    /// `ThreadJob` per call. `run_closure_in_job` allocates an mpsc channel,
361    /// builds a `ThreadJob`, locks `self.state.jobs` and `add_job`s it -- and
362    /// never removes it -- on every invocation. In a hot per-frame actor loop
363    /// that churn (plus the unbounded jobs-table growth) dominated the cost.
364    /// The caller is expected to have attached a single long-lived background
365    /// job to `self.state` once (see the actor `EngineWorker`); this method
366    /// just sets up the stack, injects positional args, and evaluates.
367    pub fn eval_closure_no_job(
368        &mut self,
369        closure: &nu_protocol::engine::Closure,
370        args: Vec<Value>,
371        pipeline_input: Option<PipelineData>,
372    ) -> Result<PipelineData, Box<ShellError>> {
373        let block = self.state.get_block(closure.block_id);
374        let mut stack = Stack::new();
375        let mut stack =
376            stack.push_redirection(Some(Redirection::Pipe(OutDest::PipeSeparate)), None);
377
378        let num_required = block.signature.required_positional.len();
379        let num_optional = block.signature.optional_positional.len();
380        let total_positional = num_required + num_optional;
381
382        if args.len() > total_positional {
383            return Err(Box::new(ShellError::Generic(GenericError::new(
384                format!(
385                    "Too many arguments for actor closure: got {}, closure accepts at most {total_positional}.",
386                    args.len()
387                ),
388                format!("Closure signature: {name}", name = block.signature.name),
389                block.span.unwrap_or_else(Span::unknown),
390            ))));
391        }
392
393        if args.len() < num_required {
394            return Err(Box::new(ShellError::Generic(GenericError::new(
395                format!(
396                    "Actor closure expects {num_required} required argument(s), but {} were provided.",
397                    args.len()
398                ),
399                format!("Closure signature: {name}", name = block.signature.name),
400                block.span.unwrap_or_else(Span::unknown),
401            ))));
402        }
403
404        for (i, val) in args.iter().enumerate() {
405            let param = if i < num_required {
406                &block.signature.required_positional[i]
407            } else {
408                &block.signature.optional_positional[i - num_required]
409            };
410            if let Some(var_id) = param.var_id {
411                stack.add_var(var_id, val.clone());
412            }
413        }
414
415        let optional_covered = args.len().saturating_sub(num_required);
416        for i in optional_covered..num_optional {
417            let param = &block.signature.optional_positional[i];
418            if let Some(var_id) = param.var_id {
419                let default = param
420                    .default_value
421                    .clone()
422                    .unwrap_or_else(|| Value::nothing(Span::unknown()));
423                stack.add_var(var_id, default);
424            }
425        }
426
427        let eval_pipeline_input = pipeline_input.unwrap_or_else(PipelineData::empty);
428        let eval_res = nu_engine::eval_block_with_early_return::<WithoutDebug>(
429            &self.state,
430            &mut stack,
431            block,
432            eval_pipeline_input,
433        );
434
435        if eval_res.is_ok() {
436            if let Err(e) = self.state.merge_env(&mut stack) {
437                tracing::error!("Failed to merge environment from actor closure: {}", e);
438            }
439        }
440
441        eval_res.map(|exec_data| exec_data.body).map_err(Box::new)
442    }
443
444    /// Attach a single long-lived background `ThreadJob` to this engine's
445    /// state. Call once before a hot eval loop so `eval_closure_no_job` can
446    /// skip per-call job creation. Signals still propagate (the job shares
447    /// `self.state.signals()`).
448    pub fn attach_background_job(&mut self, name: impl Into<String>) {
449        let (sender, _rx) = std::sync::mpsc::channel();
450        let job = ThreadJob::new(
451            self.state.signals().clone(),
452            Some(name.into()),
453            false,
454            sender,
455        );
456        {
457            let mut j = self.state.jobs.lock().unwrap();
458            j.add_job(Job::Thread(job.clone()));
459        }
460        self.state.current_job.background_thread_job = Some(job);
461    }
462
463    /// Kill the background ThreadJob whose name equals `name`.
464    pub fn kill_job_by_name(&self, name: &str) {
465        if let Ok(mut jobs) = self.state.jobs.lock() {
466            let job_id = {
467                jobs.iter().find_map(|(jid, job)| {
468                    job.description()
469                        .and_then(|desc| if desc == name { Some(jid) } else { None })
470                })
471            };
472            if let Some(job_id) = job_id {
473                let _ = jobs.kill_and_remove(job_id);
474            }
475        }
476    }
477}
478
479/// Add core cross.stream commands that are common across all Nushell pipeline runners
480pub fn add_core_commands(engine: &mut Engine, store: &Store) -> Result<(), Error> {
481    engine.add_commands(vec![
482        Box::new(commands::cas_command::CasCommand::new(store.clone())),
483        Box::new(commands::get_command::GetCommand::new(store.clone())),
484        Box::new(commands::remove_command::RemoveCommand::new(store.clone())),
485        Box::new(commands::scru128_command::Scru128Command::new()),
486        Box::new(commands::scru128_command::Scru128UnpackCommand::new()),
487        Box::new(commands::scru128_command::Scru128PackCommand::new()),
488    ])
489}
490
491/// How `.append` behaves. This is the one store command whose behaviour
492/// genuinely varies by runner.
493pub enum AppendMode {
494    /// Write straight to the store. The per-instance base metadata is injected
495    /// via the `XS_APPEND_META` env var (see `append_command`), not baked in.
496    Direct,
497    /// Buffer appended frames into `output` for the caller to flush (actors).
498    Buffered(Arc<Mutex<Vec<Frame>>>),
499}
500
501/// Register the `.cat` and `.last` read builtins for a pipeline runner. Both
502/// commands stream through the store's runtime-backed `read()` and support
503/// `--follow`, serving historical and follow reads from a single impl.
504pub fn add_read_commands(engine: &mut Engine, store: &Store) -> Result<(), Error> {
505    engine.add_commands(vec![
506        Box::new(commands::cat_command::CatCommand::new(store.clone())),
507        Box::new(commands::last_command::LastCommand::new(store.clone())),
508    ])
509}
510
511/// Register the write builtins for a pipeline runner: `.append` (per `mode`)
512/// plus `.import` and `.cas-post`, which are identical across runners.
513pub fn add_write_commands(
514    engine: &mut Engine,
515    store: &Store,
516    mode: AppendMode,
517) -> Result<(), Error> {
518    engine.add_commands(vec![
519        Box::new(commands::import_command::ImportCommand::new(store.clone())),
520        Box::new(commands::cas_post_command::CasPostCommand::new(
521            store.clone(),
522        )),
523    ])?;
524    match mode {
525        AppendMode::Direct => engine.add_commands(vec![Box::new(
526            commands::append_command::AppendCommand::new(store.clone()),
527        )]),
528        AppendMode::Buffered(output) => engine.add_commands(vec![Box::new(
529            commands::append_command_buffered::AppendCommand::new(store.clone(), output),
530        )]),
531    }
532}
533
534/// The module-free, instance-free base engine for a runner: nushell + stdlib +
535/// the core builtins + the `.rm` alias + the read builtins, plus the `.append`
536/// write builtin for direct writers. Build this once per runner and `clone()` it per
537/// spawn or restart; `load_modules(as_of)` and `set_append_meta(..)` specialize
538/// each clone. Actors pass `direct_write: false` and add their per-instance
539/// buffered `.append` to the clone.
540pub fn prepared_base(store: &Store, direct_write: bool) -> Result<Engine, Error> {
541    // Clone the embedder's base engine when the store carries one, else build
542    // the default. See ADR 0007.
543    let mut engine = match store.base_engine() {
544        Some(base) => Engine {
545            state: base.clone(),
546        },
547        None => Engine::new()?,
548    };
549    add_core_commands(&mut engine, store)?;
550    engine.add_alias(".rm", ".remove")?;
551    add_read_commands(&mut engine, store)?;
552    if direct_write {
553        add_write_commands(&mut engine, store, AppendMode::Direct)?;
554    }
555    Ok(engine)
556}