Skip to main content

kernel_apis/
instances.rs

1//! `instances.*` (port of `ultron/instances.ts`): a completed RLM task can be retained so later invocations run on
2//! the same lane, continuing its conversation and declared `state`, while each invocation gets its own task record.
3//! An open instance pins its lane's kernel (holder `instance:<id>`); closing unpins it, and a restarted owner re-pins
4//! every open instance. Pinning is best effort: retain reports `pinned: false` when the pool has no capacity.
5
6use 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
27/// Root may inspect and drive every instance; a task only its own.
28fn 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    /// `now`: the module's clock; `None` uses the host's.
56    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                // Lane names are deterministic, so a retained lane survives an owner restart.
166                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(&current, 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(&current, 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(&current, 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}