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