Skip to main content

simpleplatform_sdk/
tasks.rs

1//! Creating tasks from a server action.
2//!
3//! The platform assigns the task to the user the action is running as and
4//! creates the task and first-message ids. An action that must not start the
5//! same work twice checks its own record before calling [`create`].
6
7use serde::Deserialize;
8use serde_json::{json, Value};
9
10use crate::codes::Code;
11use crate::error::{Error, Fault};
12use crate::host;
13
14/// The task returned after creation.
15#[derive(Clone, Debug, Deserialize, PartialEq, Eq)]
16pub struct Task {
17    /// The platform-generated task identifier.
18    pub id: String,
19    /// The task's current revision.
20    pub revision: u64,
21    /// The task's current status.
22    pub status: String,
23}
24
25/// The result of creating a task.
26#[derive(Clone, Debug, Deserialize, PartialEq, Eq)]
27pub struct CreateResult {
28    /// The created task.
29    pub task: Task,
30}
31
32/// Create a task for the user the server action is running as.
33///
34/// `input` must be a JSON object. The platform assigns both generated ids.
35/// Check the action's own record first if it must not start the same work
36/// twice.
37pub fn create(task_type_id: &str, title: &str, input: Value) -> Result<CreateResult, Error> {
38    if task_type_id.trim().is_empty() {
39        return Err(Error::invalid(
40            "task_type_id is required for task creation.",
41        ));
42    }
43    if title.trim().is_empty() {
44        return Err(Error::invalid("title is required for task creation."));
45    }
46    if !input.is_object() {
47        return Err(Error::invalid("input must be an object for task creation."));
48    }
49
50    let data = host::transport()?.call(
51        "action:tasks/create".to_string(),
52        json!({
53            "task_type_id": task_type_id,
54            "title": title,
55            "input": input,
56        }),
57    )?;
58
59    serde_json::from_value(data).map_err(|cause| {
60        Error::Host(Fault::new(
61            Code::unspecified(),
62            format!("Task creation returned an unreadable response: {cause}"),
63        ))
64    })
65}
66
67#[cfg(test)]
68mod tests {
69    use serde_json::json;
70
71    use super::{create, CreateResult, Task};
72    use crate::{testing, Error};
73
74    #[test]
75    fn creates_a_task_and_returns_the_platform_task() {
76        let session = testing::install(|name, params| {
77            assert_eq!(name, "action:tasks/create");
78            assert_eq!(
79                params,
80                json!({
81                    "task_type_id": "TTY000003",
82                    "title": "Review the invoice",
83                    "input": { "invoice_id": "INV000017" },
84                })
85            );
86            Ok(json!({ "task": { "id": "TASK000042", "revision": 0, "status": "queued" } }))
87        });
88
89        let result = create(
90            "TTY000003",
91            "Review the invoice",
92            json!({ "invoice_id": "INV000017" }),
93        )
94        .unwrap();
95
96        assert_eq!(
97            result,
98            CreateResult {
99                task: Task {
100                    id: "TASK000042".to_string(),
101                    revision: 0,
102                    status: "queued".to_string(),
103                },
104            }
105        );
106        assert_eq!(session.calls().len(), 1);
107        assert_eq!(session.calls()[0].name, "action:tasks/create");
108        assert_eq!(
109            session.calls()[0].params,
110            json!({
111                "task_type_id": "TTY000003",
112                "title": "Review the invoice",
113                "input": { "invoice_id": "INV000017" },
114            })
115        );
116        assert_eq!(
117            session.calls()[0]
118                .params
119                .as_object()
120                .unwrap()
121                .keys()
122                .cloned()
123                .collect::<Vec<_>>(),
124            ["input", "task_type_id", "title"]
125        );
126    }
127
128    #[test]
129    fn an_empty_task_type_id_is_refused_before_anything_is_sent() {
130        let session = testing::install(|_name, _params| Ok(json!({ "task": {} })));
131
132        let error = create("  ", "Review", json!({})).unwrap_err();
133
134        assert_eq!(error.code().as_str(), "INVALID_TOOL_INPUT");
135        assert!(session.calls().is_empty());
136    }
137
138    #[test]
139    fn an_empty_title_is_refused_before_anything_is_sent() {
140        let session = testing::install(|_name, _params| Ok(json!({ "task": {} })));
141
142        let error = create("TTY000003", "", json!({})).unwrap_err();
143
144        assert_eq!(error.code().as_str(), "INVALID_TOOL_INPUT");
145        assert!(session.calls().is_empty());
146    }
147
148    #[test]
149    fn a_non_object_input_is_refused_before_anything_is_sent() {
150        let session = testing::install(|_name, _params| Ok(json!({ "task": {} })));
151
152        let error = create("TTY000003", "Review", json!([])).unwrap_err();
153
154        assert_eq!(error.code().as_str(), "INVALID_TOOL_INPUT");
155        assert!(session.calls().is_empty());
156    }
157
158    #[test]
159    fn a_task_service_refusal_preserves_the_host_message() {
160        let _session =
161            testing::install(|_name, _params| Err(Error::failed("TASK_INPUT_INVALID: /title")));
162
163        let error = create("TTY000003", "Review", json!({})).unwrap_err();
164
165        assert!(matches!(error, Error::Host(_)));
166        assert_eq!(
167            error.message(),
168            "action:tasks/create failed: TASK_INPUT_INVALID: /title"
169        );
170    }
171}