jmap_tasks_server/
workflow.rs1use jmap_types::{SetError, SetErrorType};
29use serde_json::{Map, Value};
30
31pub const DEFAULT_WORKFLOW_STATUSES: &[&str] = &[
34 "completed",
35 "failed",
36 "in-process",
37 "needs-action",
38 "cancelled",
39 "pending",
40];
41
42pub const PROGRESS_VALUES: &[&str] = &[
44 "needs-action",
45 "in-process",
46 "completed",
47 "failed",
48 "cancelled",
49];
50
51fn invalid(property: &str, description: &str) -> Box<SetError> {
52 Box::new(
53 SetError::new(SetErrorType::InvalidProperties)
54 .with_properties([property])
55 .with_description(description),
56 )
57}
58
59#[derive(Debug, Clone, Copy)]
61pub enum WorkflowWrite<'a> {
62 Create,
64 Update {
67 before: &'a Map<String, Value>,
69 written: &'a [String],
71 },
72}
73
74pub fn apply_workflow_status(
87 task: &mut Map<String, Value>,
88 write: WorkflowWrite<'_>,
89 list_statuses: Option<&[String]>,
90 now: &str,
91) -> Result<bool, Box<SetError>> {
92 let wrote_progress_updated = match write {
93 WorkflowWrite::Create => task_has(task, "progressUpdated"),
94 WorkflowWrite::Update { written, .. } => written.iter().any(|w| w == "progressUpdated"),
95 };
96 let (sets_status, sets_progress, moves) = match write {
97 WorkflowWrite::Create => (true, task_has(task, "progress"), false),
98 WorkflowWrite::Update { before, written } => (
99 written.iter().any(|w| w == "workflowStatus"),
100 written.iter().any(|w| w == "progress"),
101 before.get("taskListId") != task.get("taskListId"),
102 ),
103 };
104 let Some(status) = task
105 .get("workflowStatus")
106 .and_then(Value::as_str)
107 .map(str::to_owned)
108 else {
109 return Ok(false);
110 };
111 if sets_status || moves {
112 let allowed = match list_statuses {
113 Some(list) => list.contains(&status),
114 None => DEFAULT_WORKFLOW_STATUSES.contains(&status.as_str()),
115 };
116 if !allowed {
117 return Err(invalid(
118 "workflowStatus",
119 "workflowStatus is not one of the task list's workflowStatuses",
120 ));
121 }
122 }
123 if !sets_status && !sets_progress {
124 return Ok(false);
125 }
126 let mirrored = PROGRESS_VALUES
127 .contains(&status.as_str())
128 .then(|| Value::String(status.clone()));
129 let given = task.get("progress").filter(|v| !v.is_null()).cloned();
130 if sets_progress && given != mirrored {
131 return Err(invalid(
132 "progress",
133 "progress must match workflowStatus: the workflowStatus when it is a progress value, otherwise null",
134 ));
135 }
136 let previous = match write {
137 WorkflowWrite::Create => None,
138 WorkflowWrite::Update { before, .. } => before.get("progress").filter(|v| !v.is_null()),
139 };
140 let mut changed = given != mirrored;
141 match &mirrored {
142 Some(v) => {
143 task.insert("progress".to_owned(), v.clone());
144 }
145 None => {
146 task.remove("progress");
147 }
148 }
149 if previous != mirrored.as_ref() && !wrote_progress_updated {
153 task.insert("progressUpdated".to_owned(), Value::String(now.to_owned()));
154 changed = true;
155 }
156 Ok(changed)
157}
158
159fn task_has(task: &Map<String, Value>, k: &str) -> bool {
160 task.get(k).is_some_and(|v| !v.is_null())
161}
162
163#[cfg(test)]
164mod tests {
165 use super::*;
166 use serde_json::json;
167
168 const NOW: &str = "2026-11-19T12:00:00Z";
169
170 fn map(v: Value) -> Map<String, Value> {
171 v.as_object().cloned().unwrap()
172 }
173
174 #[test]
176 fn a_progress_value_mirrors() {
177 let mut t = map(json!({ "taskListId": "L", "workflowStatus": "completed" }));
178 assert!(apply_workflow_status(&mut t, WorkflowWrite::Create, None, NOW).unwrap());
179 assert_eq!(t["progress"], "completed");
180 assert_eq!(t["progressUpdated"], NOW);
181 }
182
183 #[test]
186 fn pending_leaves_progress_null() {
187 let mut t = map(json!({ "taskListId": "L", "workflowStatus": "pending" }));
188 assert!(!apply_workflow_status(&mut t, WorkflowWrite::Create, None, NOW).unwrap());
189 assert!(t.get("progress").is_none());
190 }
191
192 #[test]
194 fn matching_progress_is_accepted() {
195 let mut t = map(json!({ "workflowStatus": "in-process", "progress": "in-process" }));
196 apply_workflow_status(&mut t, WorkflowWrite::Create, None, NOW).unwrap();
197 }
198
199 #[test]
202 fn an_unrelated_update_skips_the_list_check() {
203 let before = map(json!({ "taskListId": "L", "workflowStatus": "in-review" }));
204 let mut t = map(json!({ "taskListId": "L", "workflowStatus": "in-review", "title": "x" }));
205 let written = vec!["title".to_owned()];
206 let w = WorkflowWrite::Update {
207 before: &before,
208 written: &written,
209 };
210 assert!(!apply_workflow_status(&mut t, w, Some(&[]), NOW).unwrap());
211 }
212}