1use crate::store::read_versioned;
7use crate::util::Clock;
8use crate::{ApiModule, Request, TaskHost};
9use kernel::store::DocumentStore;
10use serde_json::{Value, json};
11use std::collections::HashSet;
12use std::sync::{Arc, Mutex};
13
14const TERMINAL: &[&str] = &["completed", "failed", "cancelled", "interrupted"];
15
16fn text(value: Option<&Value>, name: &str) -> Result<String, String> {
17 match value.and_then(Value::as_str) {
18 Some(text) if !jsrt::string::trim(text).is_empty() => Ok(text.to_string()),
19 _ => Err(format!("{name} must be a nonempty string")),
20 }
21}
22
23fn holder(instance: &Value) -> String {
24 format!("instance:{}", instance["id"].as_str().unwrap_or(""))
25}
26
27fn assert_owner(instance: &Value, caller: Option<&str>) -> Result<(), String> {
29 match caller {
30 Some(caller) if instance["owner"] != caller => Err("Instance belongs to another task".into()),
31 _ => Ok(()),
32 }
33}
34
35fn find_index(document: &Value, id: Option<&Value>) -> Result<usize, String> {
36 let id = text(id, "id")?;
37 document["instances"]
38 .as_array()
39 .and_then(|items| items.iter().position(|item| item["id"] == id.as_str()))
40 .ok_or_else(|| "Unknown instance".to_string())
41}
42
43struct State {
44 document: Option<Value>,
45 pinned: HashSet<String>,
46}
47
48pub struct InstancesModule {
49 store: Arc<dyn DocumentStore>,
50 now: Option<Clock>,
51 state: Mutex<State>,
52}
53
54impl InstancesModule {
55 pub fn new(store: Arc<dyn DocumentStore>, now: Option<Clock>) -> Self {
57 Self {
58 store,
59 now,
60 state: Mutex::new(State {
61 document: None,
62 pinned: HashSet::new(),
63 }),
64 }
65 }
66
67 fn load(&self, state: &mut State) -> Result<Value, String> {
68 if let Some(document) = &state.document {
69 return Ok(document.clone());
70 }
71 let document = match read_versioned("ultron.module/instances", self.store.read()?, "version")? {
72 None => json!({"version": 1, "instances": []}),
73 Some(saved) => {
74 if saved["version"] != 1 || !saved["instances"].is_array() {
75 return Err("Invalid instance document".into());
76 }
77 saved
78 }
79 };
80 state.document = Some(document.clone());
81 Ok(document)
82 }
83
84 fn commit(&self, state: &mut State, next: Value) -> Result<(), String> {
85 self.store.write(&next)?;
86 state.document = Some(next);
87 Ok(())
88 }
89
90 fn pin(state: &mut State, instance: &Value, host: &dyn TaskHost) -> bool {
91 let id = instance["id"].as_str().unwrap_or("").to_string();
92 if state.pinned.contains(&id) {
93 return true;
94 }
95 let ok = host.pin_lane(instance["lane"].as_str().unwrap_or(""), &holder(instance));
96 if ok {
97 state.pinned.insert(id);
98 }
99 ok
100 }
101
102 fn unpin(state: &mut State, instance: &Value, host: &dyn TaskHost) {
103 if state.pinned.remove(instance["id"].as_str().unwrap_or("")) {
104 host.unpin_lane(instance["lane"].as_str().unwrap_or(""), &holder(instance));
105 }
106 }
107
108 fn with_pinned(mut instance: Value, pinned: bool) -> Value {
109 instance["pinned"] = pinned.into();
110 instance
111 }
112}
113
114impl ApiModule for InstancesModule {
115 fn prefixes(&self) -> &[&str] {
116 &["instances."]
117 }
118
119 fn start(&self, host: &dyn TaskHost) -> Result<(), String> {
120 let mut state = jsrt::sync::lock(&self.state);
121 let document = self.load(&mut state)?;
122 for instance in document["instances"].as_array().into_iter().flatten() {
123 if instance["state"] == "open" {
124 Self::pin(&mut state, instance, host);
125 }
126 }
127 Ok(())
128 }
129
130 fn handle(&self, request: &Request<'_>) -> Result<Value, String> {
131 let mut state = jsrt::sync::lock(&self.state);
132 let current = self.load(&mut state)?;
133 let host = request.host;
134 let caller = request.caller_task;
135 let now = self.now.as_ref().map(|now| now()).unwrap_or_else(|| host.now());
136 let payload = request.payload;
137 match request.kind {
138 "instances.retain" => {
139 kernel::ops::fields("instances.retain", payload)?;
140 let task_id = text(payload.get("task_id"), "task_id")?;
141 let existing = current["instances"]
142 .as_array()
143 .and_then(|items| items.iter().find(|item| item["task_id"] == task_id.as_str()))
144 .cloned();
145 if let Some(existing) = existing {
146 assert_owner(&existing, caller)?;
147 let pinned = existing["state"] == "open" && Self::pin(&mut state, &existing, host);
148 return Ok(Self::with_pinned(existing, pinned));
149 }
150 let task = host
151 .tasks()?
152 .into_iter()
153 .find(|task| task["id"] == task_id.as_str())
154 .ok_or("Unknown Ultron task")?;
155 if task["parentId"].as_str() != caller {
156 return Err("Only the task's parent can retain it".into());
157 }
158 if task["state"] != "completed" {
159 return Err("Only a completed task can be retained".into());
160 }
161 let definition = task["definition"].as_str().unwrap_or("").to_string();
162 if host.strategy(&definition)? != "rlm" {
163 return Err("Only RLM tasks have a lane to retain".into());
164 }
165 let lane = host
167 .task_lane(&task_id)
168 .unwrap_or_else(|| format!("ultron.{}.{task_id}", definition.split('@').next().unwrap_or("")));
169 let record = json!({
170 "id": format!("ultron-instance-{}", jsrt::random::uuid_v4()),
171 "task_id": task_id,
172 "definition": definition,
173 "lane": lane,
174 "owner": caller,
175 "state": "open",
176 "created_at": now,
177 "closed_at": null,
178 "invocations": [],
179 });
180 let mut next = current;
181 if let Some(Value::Array(items)) = next.get_mut("instances") {
182 items.push(record.clone());
183 }
184 self.commit(&mut state, next)?;
185 let pinned = Self::pin(&mut state, &record, host);
186 Ok(Self::with_pinned(record, pinned))
187 }
188 "instances.invoke" => {
189 kernel::ops::fields("instances.invoke", payload)?;
190 let index = find_index(¤t, payload.get("id"))?;
191 let instance = current["instances"][index].clone();
192 assert_owner(&instance, caller)?;
193 if instance["state"] != "open" {
194 return Err("Instance is closed".into());
195 }
196 let input = payload.get("input").ok_or("input must be JSON")?;
197 let last = instance["invocations"]
198 .as_array()
199 .and_then(|items| items.last())
200 .map(|item| item["task_id"].clone())
201 .unwrap_or_else(|| instance["task_id"].clone());
202 let last_state = host
203 .tasks()?
204 .into_iter()
205 .find(|task| task["id"] == last)
206 .map(|task| task["state"].as_str().unwrap_or("").to_string());
207 if last_state.is_some_and(|state| !TERMINAL.contains(&state.as_str())) {
208 return Err("Instance is busy with a previous invocation".into());
209 }
210 let mut spawn = json!({
211 "definition": instance["definition"],
212 "input": input,
213 "lane": instance["lane"],
214 });
215 if let Some(key) = payload.get("key").filter(|key| !key.is_null()) {
216 let key = text(Some(key), "key")?;
217 spawn["key"] = format!("instance:{}:{key}", instance["id"].as_str().unwrap_or("")).into();
218 }
219 let task = host.spawn(&spawn, caller)?;
220 let invoked = instance["invocations"]
221 .as_array()
222 .is_some_and(|items| items.iter().any(|item| item["task_id"] == task["id"]));
223 if !invoked {
224 let mut next = current.clone();
225 if let Some(Value::Array(items)) = next["instances"][index].get_mut("invocations") {
226 items.push(json!({
227 "task_id": task["id"],
228 "at": now,
229 "input_sha256": jsrt::hash::sha256_hex(jsrt::json::stringify(input).as_bytes()),
230 }));
231 }
232 self.commit(&mut state, next)?;
233 }
234 Ok(json!({"instance_id": instance["id"], "task_id": task["id"]}))
235 }
236 "instances.close" => {
237 kernel::ops::fields("instances.close", payload)?;
238 let index = find_index(¤t, payload.get("id"))?;
239 let instance = current["instances"][index].clone();
240 assert_owner(&instance, caller)?;
241 if instance["state"] == "closed" {
242 return Ok(instance);
243 }
244 let mut next = current;
245 next["instances"][index]["state"] = "closed".into();
246 next["instances"][index]["closed_at"] = now.into();
247 let closed = next["instances"][index].clone();
248 self.commit(&mut state, next)?;
249 Self::unpin(&mut state, &instance, host);
250 Ok(closed)
251 }
252 "instances.get" => {
253 kernel::ops::fields("instances.get", payload)?;
254 let index = find_index(¤t, payload.get("id"))?;
255 let instance = current["instances"][index].clone();
256 assert_owner(&instance, caller)?;
257 Ok(instance)
258 }
259 "instances.list" => {
260 kernel::ops::fields("instances.list", payload)?;
261 Ok(Value::Array(
262 current["instances"]
263 .as_array()
264 .into_iter()
265 .flatten()
266 .filter(|instance| caller.is_none_or(|caller| instance["owner"] == caller))
267 .cloned()
268 .collect(),
269 ))
270 }
271 other => Err(format!("Unknown instance request: {other}")),
272 }
273 }
274}