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 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#[derive(Deserialize, Debug, Default)]
54#[serde(default)] struct ActorScriptOptions {
56 start: Option<String>,
58 pulse: Option<u64>,
60 return_options: Option<ReturnOptions>,
62 initial: Option<serde_json::Value>,
64 topics: Option<TopicsSpec>,
67}
68
69#[derive(Deserialize, Debug)]
72#[serde(untagged)]
73enum TopicsSpec {
74 One(String),
75 Many(Vec<String>),
76}
77
78impl TopicsSpec {
79 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 nu::add_write_commands(
117 &mut engine,
118 &store,
119 nu::AppendMode::Buffered(output.clone()),
120 )?;
121
122 let nu_script_config = nu::parse_config(&mut engine, &expression)?;
124
125 let (actor_config, initial_json) = extract_actor_config(&nu_script_config)?;
127
128 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 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 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 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 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 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 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 fn run_blocking(mut self, mut recver: mpsc::Receiver<crate::store::ReadItem>, store: Store) {
297 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 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 if (frame.topic == create_topic || frame.topic == term_topic) && frame.id <= self.id {
326 continue;
327 }
328
329 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 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 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 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 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 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 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 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 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 let follow_option = self
475 .config
476 .pulse
477 .map(|pulse| FollowOption::WithHeartbeat(Duration::from_millis(pulse)))
478 .unwrap_or(FollowOption::On);
479
480 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
543fn extract_actor_config(
545 script_config: &NuScriptConfig,
546) -> Result<(ActorConfig, Option<serde_json::Value>), Error> {
547 let script_options: ActorScriptOptions = script_config.deserialize_options()?;
549
550 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(), };
560
561 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}