Skip to main content

xs/processor/actor/
actor.rs

1use std::str::FromStr;
2use std::sync::{Arc, Mutex};
3use std::time::Duration;
4
5use serde::{Deserialize, Serialize};
6
7use tokio::io::AsyncReadExt;
8
9use nu_protocol::Value;
10
11use scru128::Scru128Id;
12
13use crate::error::Error;
14use crate::nu;
15use crate::nu::value_to_json;
16use crate::nu::{NuScriptConfig, ReturnOptions};
17use crate::store::{FollowOption, Frame, ReadOptions, Store};
18
19#[derive(Clone)]
20pub struct Actor {
21    pub id: Scru128Id,
22    pub topic: String,
23    config: ActorConfig,
24    engine: nu::Engine,
25    closure: nu_protocol::engine::Closure,
26    initial_state: Value,
27    output: Arc<Mutex<Vec<Frame>>>,
28}
29
30#[derive(Clone, Debug)]
31struct ActorConfig {
32    start: Start,
33    pulse: Option<u64>,
34    return_options: Option<ReturnOptions>,
35    /// Optional topic filter, normalized to one pattern per element. Applied
36    /// at the read level (see `configure_read_options`): frames whose topic
37    /// matches none of these patterns never reach the actor loop. Each
38    /// pattern is an exact topic, a `prefix.*` wildcard, or `*`, the same
39    /// pattern language as `ReadOptions::topic`. Absent means all frames.
40    topics: Option<Vec<String>>,
41}
42
43#[derive(Clone, Debug, Default, Serialize, Deserialize)]
44#[serde(rename_all = "snake_case")]
45enum Start {
46    First,
47    #[default]
48    New,
49    After(Scru128Id),
50}
51
52/// Options that can be deserialized directly from a script.
53#[derive(Deserialize, Debug, Default)]
54#[serde(default)] // Use default values when fields are missing
55struct ActorScriptOptions {
56    /// Actor can specify where to start: "first", "new", or a specific ID
57    start: Option<String>,
58    /// Optional heartbeat interval in milliseconds
59    pulse: Option<u64>,
60    /// Optional customizations for return frames
61    return_options: Option<ReturnOptions>,
62    /// Initial state for the actor closure's second parameter
63    initial: Option<serde_json::Value>,
64    /// Optional list of topic patterns the actor cares about. Accepts a
65    /// nushell list of strings or a single comma-separated string.
66    topics: Option<TopicsSpec>,
67}
68
69/// A topics spec from the actor script: a single string (commas allowed) or
70/// a list of strings.
71#[derive(Deserialize, Debug)]
72#[serde(untagged)]
73enum TopicsSpec {
74    One(String),
75    Many(Vec<String>),
76}
77
78impl TopicsSpec {
79    /// Normalize to one pattern per element, splitting comma-separated
80    /// strings and dropping empty elements.
81    fn into_patterns(self) -> Vec<String> {
82        let parts: Vec<String> = match self {
83            TopicsSpec::One(s) => vec![s],
84            TopicsSpec::Many(v) => v,
85        };
86        parts
87            .iter()
88            .flat_map(|s| s.split(','))
89            .map(|p| p.trim().to_string())
90            .filter(|p| !p.is_empty())
91            .collect()
92    }
93}
94
95pub(super) enum ClosureResult {
96    Continue {
97        output: Option<Value>,
98        next_state: Value,
99    },
100    Stop {
101        output: Option<Value>,
102    },
103}
104
105impl Actor {
106    pub async fn new(
107        id: Scru128Id,
108        topic: String,
109        mut engine: nu::Engine,
110        expression: String,
111        store: Store,
112    ) -> Result<Self, Error> {
113        let output = Arc::new(Mutex::new(Vec::new()));
114        // Reads come from the prepared base; only the per-instance buffered
115        // `.append` (for atomic batch commit) is added here.
116        nu::add_write_commands(
117            &mut engine,
118            &store,
119            nu::AppendMode::Buffered(output.clone()),
120        )?;
121
122        // Parse configuration using the new generic API
123        let nu_script_config = nu::parse_config(&mut engine, &expression)?;
124
125        // Deserialize actor-specific options from the full_config_value
126        let (actor_config, initial_json) = extract_actor_config(&nu_script_config)?;
127
128        // Validate closure signature and resolve initial state
129        let block = engine
130            .state
131            .get_block(nu_script_config.run_closure.block_id);
132        let num_required = block.signature.required_positional.len();
133        let num_optional = block.signature.optional_positional.len();
134
135        let total_positional = num_required + num_optional;
136        if total_positional != 2 {
137            return Err(format!(
138                "Closure must accept exactly 2 params (frame, state), got {total_positional}"
139            )
140            .into());
141        }
142
143        // Resolve initial state: config `initial` > param default > null
144        let span = nu_protocol::Span::unknown();
145        let initial_state = if let Some(json) = initial_json {
146            crate::nu::util::json_to_value(&json, span)
147        } else if num_optional > 0 {
148            let state_param = &block.signature.optional_positional[0];
149            state_param
150                .default_value
151                .clone()
152                .unwrap_or_else(|| Value::nothing(span))
153        } else {
154            Value::nothing(span)
155        };
156
157        Ok(Self {
158            id,
159            topic,
160            config: actor_config,
161            engine,
162            closure: nu_script_config.run_closure,
163            initial_state,
164            output,
165        })
166    }
167
168    /// Evaluate the actor closure for one frame, inline on the calling
169    /// thread. The whole actor loop runs on a dedicated OS thread (see
170    /// `run_blocking`), so there is no async->worker->oneshot handoff per
171    /// frame -- that round trip (two context switches) was the dominant
172    /// per-frame cost in backlog replay. `state` is threaded by the caller.
173    fn eval_frame(&mut self, frame: &Frame, state: &Value) -> Result<ClosureResult, Error> {
174        let frame_val = crate::nu::frame_to_value(frame, nu_protocol::Span::unknown(), false);
175        self.engine
176            .eval_closure_no_job(&self.closure, vec![frame_val, state.clone()], None)
177            .map_err(|e| {
178                let working_set = nu_protocol::engine::StateWorkingSet::new(&self.engine.state);
179                Error::from(nu_protocol::format_cli_error(None, &working_set, &*e, None))
180            })
181            .and_then(|pd| {
182                pd.into_value(nu_protocol::Span::unknown())
183                    .map_err(Error::from)
184            })
185            .and_then(interpret_closure_result)
186    }
187
188    fn process_frame(
189        &mut self,
190        frame: &Frame,
191        store: &Store,
192        state: &mut Value,
193    ) -> Result<bool, Error> {
194        let result = self.eval_frame(frame, state)?;
195
196        let (output, should_continue) = match result {
197            ClosureResult::Continue {
198                output,
199                ref next_state,
200            } => {
201                *state = next_state.clone();
202                (output, true)
203            }
204            ClosureResult::Stop { output } => (output, false),
205        };
206
207        // Check if the evaluated value is an append frame
208        let additional_frame = match output {
209            Some(ref value)
210                if !is_value_an_append_frame_from_actor(value, &self.id)
211                    && !matches!(value, Value::Nothing { .. }) =>
212            {
213                let return_options = self.config.return_options.as_ref();
214                let suffix = return_options
215                    .and_then(|ro| ro.suffix.as_deref())
216                    .unwrap_or(".out");
217                let use_cas = return_options
218                    .and_then(|ro| ro.target.as_deref())
219                    .is_some_and(|t| t == "cas");
220
221                let topic = format!("{topic}{suffix}", topic = self.topic, suffix = suffix);
222                let ttl = return_options.and_then(|ro| ro.ttl.clone());
223
224                if use_cas {
225                    let hash = match value {
226                        Value::Binary { val, .. } => store.cas_insert_sync(val)?,
227                        _ => store.cas_insert_sync(value_to_json(value).to_string())?,
228                    };
229                    Some(
230                        Frame::builder(topic)
231                            .maybe_ttl(ttl)
232                            .maybe_hash(Some(hash))
233                            .build(),
234                    )
235                } else {
236                    // Default: records go to meta, non-records are an error
237                    match value {
238                        Value::Record { .. } => {
239                            let json = value_to_json(value);
240                            Some(Frame::builder(topic).maybe_ttl(ttl).meta(json).build())
241                        }
242                        _ => {
243                            return Err(format!(
244                                "Actor output must be a record when target is not \"cas\"; got {}. \
245                                 Set return_options.target to \"cas\" for non-record output.",
246                                value.get_type()
247                            )
248                            .into());
249                        }
250                    }
251                }
252            }
253            _ => None,
254        };
255
256        // Process buffered appends and the additional frame
257        let mut output_to_process: Vec<_> = {
258            let mut output = self.output.lock().unwrap();
259            output.drain(..).chain(additional_frame).collect()
260        };
261
262        for output_frame in output_to_process.iter_mut() {
263            let meta_obj = output_frame
264                .meta
265                .get_or_insert_with(|| serde_json::Value::Object(Default::default()))
266                .as_object_mut()
267                .expect("meta should be an object");
268
269            meta_obj.insert(
270                "actor_id".to_string(),
271                serde_json::Value::String(self.id.to_string()),
272            );
273            meta_obj.insert(
274                "frame_id".to_string(),
275                serde_json::Value::String(frame.id.to_string()),
276            );
277        }
278
279        // One write for the whole step: other appends can't land between
280        // these frames, and a reader sees all of them or none. A failed write
281        // stops the actor, as a closure error does.
282        if !output_to_process.is_empty() {
283            store
284                .append_many(output_to_process)
285                .map_err(|e| format!("Failed to append actor output: {e}"))?;
286        }
287
288        Ok(should_continue)
289    }
290
291    /// The actor's hot loop, run on a dedicated OS thread. Pulls frames with
292    /// blocking_recv (no async runtime hop) and evaluates each inline -- the
293    /// per-frame async->worker->oneshot round trip is gone. State is threaded
294    /// here and passed by `&mut` into `process_frame`. All store ops on this
295    /// path (`append`, `append_many`, `cas_insert_sync`) are synchronous.
296    fn run_blocking(mut self, mut recver: mpsc::Receiver<crate::store::ReadItem>, store: Store) {
297        // One long-lived background job, so per-frame eval can skip job churn.
298        self.engine.attach_background_job("actor");
299        let mut state = self.initial_state.clone();
300
301        let create_topic = format!("xs.actor.{}.create", self.topic);
302        let term_topic = format!("xs.actor.{}.term", self.topic);
303        let store = &store;
304
305        while let Some(item) = recver.blocking_recv() {
306            // The read ended early: the actor fell behind the live stream and
307            // missed frames. Stop with an error rather than carry on as though
308            // nothing were missing.
309            let frame = match item {
310                Ok(frame) => frame,
311                Err(err) => {
312                    let _ = store.append(
313                        Frame::builder(format!("xs.actor.{}.fin.error", self.topic))
314                            .meta(serde_json::json!({
315                                "actor_id": self.id.to_string(),
316                                "error": err.to_string(),
317                            }))
318                            .build(),
319                    );
320                    break;
321                }
322            };
323
324            // Skip lifecycle activity that occurred before this actor was registered
325            if (frame.topic == create_topic || frame.topic == term_topic) && frame.id <= self.id {
326                continue;
327            }
328
329            // A newer .create wins: this actor steps aside. Emit .replaced
330            // (the successor's .active will be next).
331            if frame.topic == create_topic {
332                let _ = store.append(
333                    Frame::builder(format!("xs.actor.{}.replaced", self.topic))
334                        .meta(serde_json::json!({
335                            "actor_id": self.id.to_string(),
336                            "frame_id": frame.id.to_string(),
337                        }))
338                        .build(),
339                );
340                break;
341            }
342
343            // User-requested stop.
344            if frame.topic == term_topic {
345                let _ = store.append(
346                    Frame::builder(format!("xs.actor.{}.fin.term", self.topic))
347                        .meta(serde_json::json!({
348                            "actor_id": self.id.to_string(),
349                            "frame_id": frame.id.to_string(),
350                        }))
351                        .build(),
352                );
353                break;
354            }
355
356            // Skip frames that were generated by this actor
357            if frame
358                .meta
359                .as_ref()
360                .and_then(|meta| meta.get("actor_id"))
361                .and_then(|actor_id| actor_id.as_str())
362                .filter(|actor_id| *actor_id == self.id.to_string())
363                .is_some()
364            {
365                continue;
366            }
367
368            match self.process_frame(&frame, store, &mut state) {
369                Ok(true) => {}
370                Ok(false) => {
371                    // Actor self-terminated (natural completion).
372                    let _ = store.append(
373                        Frame::builder(format!("xs.actor.{}.fin.ok", self.topic))
374                            .meta(serde_json::json!({
375                                "actor_id": self.id.to_string(),
376                                "frame_id": frame.id.to_string(),
377                            }))
378                            .build(),
379                    );
380                    break;
381                }
382                Err(err) => {
383                    // Runtime crash.
384                    let _ = store.append(
385                        Frame::builder(format!("xs.actor.{}.fin.error", self.topic))
386                            .meta(serde_json::json!({
387                                "actor_id": self.id.to_string(),
388                                "frame_id": frame.id.to_string(),
389                                "error": err.to_string(),
390                            }))
391                            .build(),
392                    );
393                    break;
394                }
395            }
396        }
397    }
398
399    pub async fn spawn(self, store: Store) -> Result<(), Error> {
400        let options = self.configure_read_options().await;
401        // Set up the read stream on the async runtime, then run the actor's
402        // loop on a dedicated OS thread that drains it with blocking_recv.
403        // This keeps the synchronous nushell eval off the tokio runtime
404        // without paying a per-frame thread handoff.
405        let recver = store.read(options);
406
407        let _ = store.append(
408            Frame::builder(format!("xs.actor.{}.active", self.topic))
409                .meta(serde_json::json!({
410                    "actor_id": self.id.to_string(),
411                    "start": self.config.start,
412                }))
413                .build(),
414        );
415
416        let store_for_loop = store.clone();
417        std::thread::Builder::new()
418            .name(format!("actor-{}", self.topic))
419            .spawn(move || {
420                self.run_blocking(recver, store_for_loop);
421            })
422            .map_err(|e| Error::from(format!("Failed to spawn actor thread: {e}")))?;
423
424        Ok(())
425    }
426
427    pub async fn from_frame(frame: &Frame, store: &Store) -> Result<Self, Error> {
428        let topic = frame
429            .topic
430            .strip_prefix("xs.actor.")
431            .and_then(|rest| rest.strip_suffix(".create"))
432            .ok_or("Frame topic must be xs.actor.<name>.create")?;
433
434        // Get hash and read expression
435        let hash = frame.hash.as_ref().ok_or("Missing hash field")?;
436        let mut reader = store
437            .cas_reader(hash.clone())
438            .await
439            .map_err(|e| format!("Failed to get cas reader: {e}"))?;
440
441        let mut expression = String::new();
442        reader
443            .read_to_string(&mut expression)
444            .await
445            .map_err(|e| format!("Failed to read expression: {e}"))?;
446
447        // Prepared base; the actor's per-instance buffered `.append` is added
448        // in Actor::new. Modules as of this frame.
449        let mut engine = nu::prepared_base(store, false)?;
450        let modules = store.nu_modules_at(&frame.id);
451        nu::load_modules(&mut engine.state, store, &modules)?;
452
453        let actor = Actor::new(
454            frame.id,
455            topic.to_string(),
456            engine,
457            expression,
458            store.clone(),
459        )
460        .await?;
461
462        Ok(actor)
463    }
464
465    async fn configure_read_options(&self) -> ReadOptions {
466        // Determine after and new flag based on Start
467        let (after, is_new) = match &self.config.start {
468            Start::First => (None, false),
469            Start::New => (None, true),
470            Start::After(id) => (Some(*id), false),
471        };
472
473        // Configure follow option based on pulse setting
474        let follow_option = self
475            .config
476            .pulse
477            .map(|pulse| FollowOption::WithHeartbeat(Duration::from_millis(pulse)))
478            .unwrap_or(FollowOption::On);
479
480        // Apply the actor's topic filter at the read level: non-matching
481        // frames are skipped inside the store and never reach the actor
482        // loop. The actor's own lifecycle topics are always included so the
483        // loop still sees .create/.term frames; synthetic frames (the
484        // heartbeat xs.pulse when `pulse` is set, and xs.threshold) bypass
485        // read-level topic filtering entirely, so they are unaffected.
486        let topic = self.config.topics.as_ref().map(|patterns| {
487            let mut patterns = patterns.clone();
488            patterns.push(format!("xs.actor.{}.create", self.topic));
489            patterns.push(format!("xs.actor.{}.term", self.topic));
490            patterns.join(",")
491        });
492
493        ReadOptions::builder()
494            .follow(follow_option)
495            .new(is_new)
496            .maybe_after(after)
497            .maybe_topic(topic)
498            .build()
499    }
500}
501
502use tokio::sync::mpsc;
503
504fn interpret_closure_result(value: Value) -> Result<ClosureResult, Error> {
505    match value {
506        Value::Nothing { .. } => Ok(ClosureResult::Stop { output: None }),
507        Value::Record { ref val, .. } => {
508            for key in val.columns() {
509                if key != "out" && key != "next" {
510                    return Err(format!(
511                        "Unexpected key '{key}' in closure return record; only 'out' and 'next' are allowed"
512                    )
513                    .into());
514                }
515            }
516            let output = val.get("out").cloned();
517            match val.get("next").cloned() {
518                Some(next_state) => Ok(ClosureResult::Continue { output, next_state }),
519                None => Ok(ClosureResult::Stop { output }),
520            }
521        }
522        _ => Err(format!(
523            "Closure must return a record with 'out' and/or 'next' keys, or nothing; got {}",
524            value.get_type()
525        )
526        .into()),
527    }
528}
529
530fn is_value_an_append_frame_from_actor(value: &Value, actor_id: &Scru128Id) -> bool {
531    value
532        .as_record()
533        .ok()
534        .filter(|record| record.get("id").is_some() && record.get("topic").is_some())
535        .and_then(|record| record.get("meta"))
536        .and_then(|meta| meta.as_record().ok())
537        .and_then(|meta_record| meta_record.get("actor_id"))
538        .and_then(|id| id.as_str().ok())
539        .filter(|id| *id == actor_id.to_string())
540        .is_some()
541}
542
543/// Extract actor-specific configuration from the generic NuScriptConfig
544fn extract_actor_config(
545    script_config: &NuScriptConfig,
546) -> Result<(ActorConfig, Option<serde_json::Value>), Error> {
547    // Deserialize the actor script options using the deserialize_options method
548    let script_options: ActorScriptOptions = script_config.deserialize_options()?;
549
550    // Process start into the proper enum
551    let start =
552        match script_options.start.as_deref() {
553            Some("first") => Start::First,
554            Some("new") => Start::New,
555            Some(id_str) => Start::After(Scru128Id::from_str(id_str).map_err(|_| -> Error {
556                format!("Invalid scru128 ID for start: {id_str}").into()
557            })?),
558            None => Start::default(), // Default if not specified in script
559        };
560
561    // Build and return the ActorConfig and initial state
562    Ok((
563        ActorConfig {
564            start,
565            pulse: script_options.pulse,
566            return_options: script_options.return_options,
567            topics: script_options.topics.map(TopicsSpec::into_patterns),
568        },
569        script_options.initial,
570    ))
571}