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