Skip to main content

conductor/client/
task_client.rs

1// Copyright {{.Year}} Conductor OSS
2// Licensed under the Apache License, Version 2.0. See LICENSE in the project root for license information.
3
4use std::time::Duration;
5use tracing::{debug, warn};
6
7use crate::error::{ConductorError, Result};
8use crate::http::{ApiClient, ApiPath};
9use crate::models::{Task, TaskResult};
10
11/// Client for task operations (polling and updates).
12#[derive(Clone)]
13pub struct TaskClient {
14    api: ApiClient,
15}
16
17impl TaskClient {
18    /// Create a new task client.
19    #[must_use]
20    pub fn new(api: ApiClient) -> Self {
21        Self { api }
22    }
23
24    /// Poll for a single task.
25    ///
26    /// # Errors
27    ///
28    /// Returns [`crate::error::ConductorError::Http`] if the request fails at the transport level, an [`crate::error::ConductorError::Auth`]/[`crate::error::ConductorError::Api`]/[`crate::error::ConductorError::Server`] variant if the server responds with a non-2xx status, or [`crate::error::ConductorError::Json`] if the response body can't be deserialized.
29    pub async fn poll_task(
30        &self,
31        task_type: &str,
32        worker_id: Option<&str>,
33        domain: Option<&str>,
34    ) -> Result<Option<Task>> {
35        let mut params = vec![];
36
37        if let Some(wid) = worker_id {
38            params.push(("workerid", wid));
39        }
40        if let Some(d) = domain {
41            params.push(("domain", d));
42        }
43
44        let path = format!("/tasks/poll/{task_type}");
45        let result: Option<Task> = self
46            .api
47            .get_with_params(ApiPath::templated(&path, "/tasks/poll/{taskType}"), &params)
48            .await?;
49        Ok(result)
50    }
51
52    /// Batch poll for multiple tasks.
53    ///
54    /// # Errors
55    ///
56    /// Returns [`crate::error::ConductorError::Http`] if the request fails at the transport level, an [`crate::error::ConductorError::Auth`]/[`crate::error::ConductorError::Api`]/[`crate::error::ConductorError::Server`] variant if the server responds with a non-2xx status, or [`crate::error::ConductorError::Json`] if the response body can't be deserialized.
57    pub async fn batch_poll(
58        &self,
59        task_type: &str,
60        worker_id: Option<&str>,
61        domain: Option<&str>,
62        count: usize,
63        timeout: Duration,
64    ) -> Result<Vec<Task>> {
65        let count_str = count.to_string();
66        let timeout_str = timeout.as_millis().to_string();
67
68        let mut params = vec![
69            ("count", count_str.as_str()),
70            ("timeout", timeout_str.as_str()),
71        ];
72
73        if let Some(wid) = worker_id {
74            params.push(("workerid", wid));
75        }
76        if let Some(d) = domain {
77            params.push(("domain", d));
78        }
79
80        let path = format!("/tasks/poll/batch/{task_type}");
81
82        debug!(
83            task_type = task_type,
84            count = count,
85            timeout_ms = timeout.as_millis(),
86            "Batch polling tasks"
87        );
88
89        let tasks: Vec<Task> = self
90            .api
91            .get_with_params(
92                ApiPath::templated(&path, "/tasks/poll/batch/{taskType}"),
93                &params,
94            )
95            .await?;
96
97        debug!(
98            task_type = task_type,
99            tasks_received = tasks.len(),
100            "Batch poll completed"
101        );
102
103        Ok(tasks)
104    }
105
106    /// Update a task result.
107    ///
108    /// # Errors
109    ///
110    /// Returns [`crate::error::ConductorError::Http`] if the request fails at the transport level, an [`crate::error::ConductorError::Auth`]/[`crate::error::ConductorError::Api`]/[`crate::error::ConductorError::Server`] variant if the server responds with a non-2xx status, or [`crate::error::ConductorError::Json`] if the response body can't be deserialized.
111    pub async fn update_task(&self, result: &TaskResult) -> Result<String> {
112        debug!(
113            task_id = %result.task_id,
114            status = ?result.status,
115            "Updating task"
116        );
117
118        let response: String = self.api.post_text("/tasks", result).await?;
119        Ok(response)
120    }
121
122    /// Update task with retry logic.
123    ///
124    /// # Errors
125    ///
126    /// Returns [`crate::error::ConductorError::Http`] if the request fails at the transport level, an [`crate::error::ConductorError::Auth`]/[`crate::error::ConductorError::Api`]/[`crate::error::ConductorError::Server`] variant if the server responds with a non-2xx status, or [`crate::error::ConductorError::Json`] if the response body can't be deserialized.
127    pub async fn update_task_with_retry(
128        &self,
129        result: &TaskResult,
130        max_attempts: u32,
131    ) -> Result<String> {
132        let delays = [
133            Duration::from_secs(10),
134            Duration::from_secs(20),
135            Duration::from_secs(30),
136        ];
137
138        let mut last_error = None;
139
140        for attempt in 0..max_attempts {
141            match self.update_task(result).await {
142                Ok(response) => return Ok(response),
143                Err(e) => {
144                    if !e.is_retryable() {
145                        return Err(e);
146                    }
147
148                    last_error = Some(e);
149
150                    if attempt < max_attempts - 1 {
151                        let delay = delays
152                            .get(attempt as usize)
153                            .copied()
154                            .unwrap_or(Duration::from_secs(30));
155
156                        warn!(
157                            task_id = %result.task_id,
158                            attempt = attempt + 1,
159                            delay_secs = delay.as_secs(),
160                            "Task update failed, retrying"
161                        );
162
163                        tokio::time::sleep(delay).await;
164                    }
165                }
166            }
167        }
168
169        Err(last_error.unwrap_or_else(|| ConductorError::internal("Update failed with no error")))
170    }
171
172    /// Get task by ID.
173    ///
174    /// # Errors
175    ///
176    /// Returns [`crate::error::ConductorError::Http`] if the request fails at the transport level, an [`crate::error::ConductorError::Auth`]/[`crate::error::ConductorError::Api`]/[`crate::error::ConductorError::Server`] variant if the server responds with a non-2xx status, or [`crate::error::ConductorError::Json`] if the response body can't be deserialized.
177    pub async fn get_task(&self, task_id: &str) -> Result<Task> {
178        let path = format!("/tasks/{task_id}");
179        self.api
180            .get(ApiPath::templated(&path, "/tasks/{taskId}"))
181            .await
182    }
183
184    /// Get tasks in progress for a task type.
185    ///
186    /// # Errors
187    ///
188    /// Returns [`crate::error::ConductorError::Http`] if the request fails at the transport level, an [`crate::error::ConductorError::Auth`]/[`crate::error::ConductorError::Api`]/[`crate::error::ConductorError::Server`] variant if the server responds with a non-2xx status, or [`crate::error::ConductorError::Json`] if the response body can't be deserialized.
189    pub async fn get_tasks_in_progress(
190        &self,
191        task_type: &str,
192        start_key: Option<&str>,
193        count: Option<i32>,
194    ) -> Result<Vec<Task>> {
195        let mut params = vec![];
196        let count_str;
197
198        if let Some(key) = start_key {
199            params.push(("startKey", key));
200        }
201        if let Some(c) = count {
202            count_str = c.to_string();
203            params.push(("count", &count_str));
204        }
205
206        let path = format!("/tasks/in_progress/{task_type}");
207        self.api
208            .get_with_params(
209                ApiPath::templated(&path, "/tasks/in_progress/{taskType}"),
210                &params,
211            )
212            .await
213    }
214
215    /// Add a log to a task.
216    ///
217    /// # Errors
218    ///
219    /// Returns [`crate::error::ConductorError::Http`] if the request fails at the transport level, an [`crate::error::ConductorError::Auth`]/[`crate::error::ConductorError::Api`]/[`crate::error::ConductorError::Server`] variant if the server responds with a non-2xx status, or [`crate::error::ConductorError::Json`] if the response body can't be deserialized.
220    pub async fn add_task_log(&self, task_id: &str, log: &str) -> Result<()> {
221        let path = format!("/tasks/{task_id}/log");
222        let _: serde_json::Value = self
223            .api
224            .post(ApiPath::templated(&path, "/tasks/{taskId}/log"), &log)
225            .await?;
226        Ok(())
227    }
228
229    /// Get logs for a task.
230    ///
231    /// # Errors
232    ///
233    /// Returns [`crate::error::ConductorError::Http`] if the request fails at the transport level, an [`crate::error::ConductorError::Auth`]/[`crate::error::ConductorError::Api`]/[`crate::error::ConductorError::Server`] variant if the server responds with a non-2xx status, or [`crate::error::ConductorError::Json`] if the response body can't be deserialized.
234    pub async fn get_task_logs(
235        &self,
236        task_id: &str,
237    ) -> Result<Vec<crate::models::task::TaskExecLog>> {
238        let path = format!("/tasks/{task_id}/log");
239        self.api
240            .get(ApiPath::templated(&path, "/tasks/{taskId}/log"))
241            .await
242    }
243
244    /// Get task queue sizes.
245    ///
246    /// # Errors
247    ///
248    /// Returns [`crate::error::ConductorError::Http`] if the request fails at the transport level, or an [`crate::error::ConductorError::Auth`]/[`crate::error::ConductorError::Api`]/[`crate::error::ConductorError::Server`] variant if the server responds with a non-2xx status.
249    pub async fn get_queue_sizes(
250        &self,
251        task_types: &[&str],
252    ) -> Result<std::collections::HashMap<String, i64>> {
253        let params: Vec<(&str, &str)> = task_types.iter().map(|t| ("taskType", *t)).collect();
254        self.api
255            .get_with_params("/tasks/queue/sizes", &params)
256            .await
257    }
258
259    /// Remove task from queue.
260    ///
261    /// # Errors
262    ///
263    /// Returns [`crate::error::ConductorError::Http`] if the request fails at the transport level, or an [`crate::error::ConductorError::Auth`]/[`crate::error::ConductorError::Api`]/[`crate::error::ConductorError::Server`] variant if the server responds with a non-2xx status.
264    pub async fn remove_task_from_queue(&self, task_type: &str, task_id: &str) -> Result<()> {
265        let path = format!("/tasks/queue/{task_type}/{task_id}");
266        self.api
267            .delete_no_content(ApiPath::templated(
268                &path,
269                "/tasks/queue/{taskType}/{taskId}",
270            ))
271            .await
272    }
273
274    /// Update task by reference name.
275    ///
276    /// # Errors
277    ///
278    /// Returns [`crate::error::ConductorError::Http`] if the request fails at the transport level, an [`crate::error::ConductorError::Auth`]/[`crate::error::ConductorError::Api`]/[`crate::error::ConductorError::Server`] variant if the server responds with a non-2xx status, or [`crate::error::ConductorError::Json`] if the response body can't be deserialized.
279    pub async fn update_task_by_ref_name(
280        &self,
281        workflow_id: &str,
282        task_ref_name: &str,
283        status: crate::models::TaskResultStatus,
284        output: serde_json::Value,
285        worker_id: Option<&str>,
286    ) -> Result<String> {
287        let path = format!(
288            "/tasks/{}/{}/{}",
289            workflow_id,
290            task_ref_name,
291            status_to_string(status)
292        );
293        let mut params = vec![];
294        if let Some(wid) = worker_id {
295            params.push(("workerid", wid));
296        }
297
298        // POST with output as body
299        self.api
300            .post_text(
301                ApiPath::templated(&path, "/tasks/{workflowId}/{taskRefName}/{status}"),
302                &output,
303            )
304            .await
305    }
306
307    /// Update task synchronously and return the updated workflow.
308    ///
309    /// # Errors
310    ///
311    /// Returns [`crate::error::ConductorError::Http`] if the request fails at the transport level, an [`crate::error::ConductorError::Auth`]/[`crate::error::ConductorError::Api`]/[`crate::error::ConductorError::Server`] variant if the server responds with a non-2xx status, or [`crate::error::ConductorError::Json`] if the response body can't be deserialized.
312    pub async fn update_task_sync(
313        &self,
314        workflow_id: &str,
315        task_ref_name: &str,
316        status: crate::models::TaskResultStatus,
317        output: serde_json::Value,
318        worker_id: Option<&str>,
319    ) -> Result<crate::models::Workflow> {
320        let path = format!(
321            "/tasks/{}/{}/{}/sync",
322            workflow_id,
323            task_ref_name,
324            status_to_string(status)
325        );
326        let mut params: Vec<(&str, String)> = vec![];
327        if let Some(wid) = worker_id {
328            params.push(("workerid", wid.to_owned()));
329        }
330
331        let params_ref: Vec<(&str, &str)> = params.iter().map(|(k, v)| (*k, v.as_str())).collect();
332        self.api
333            .post_with_params(
334                ApiPath::templated(&path, "/tasks/{workflowId}/{taskRefName}/{status}/sync"),
335                &output,
336                &params_ref,
337            )
338            .await
339    }
340
341    /// Get queue size for a specific task type.
342    ///
343    /// # Errors
344    ///
345    /// Returns [`crate::error::ConductorError::Http`] if the request fails at the transport level, an [`crate::error::ConductorError::Auth`]/[`crate::error::ConductorError::Api`]/[`crate::error::ConductorError::Server`] variant if the server responds with a non-2xx status, or [`crate::error::ConductorError::Json`] if the response body can't be deserialized.
346    pub async fn get_queue_size_for_task(&self, task_type: &str) -> Result<i64> {
347        let sizes = self.get_queue_sizes(&[task_type]).await?;
348        Ok(*sizes.get(task_type).unwrap_or(&0))
349    }
350
351    /// Get poll data for a task type.
352    ///
353    /// # Errors
354    ///
355    /// Returns [`crate::error::ConductorError::Http`] if the request fails at the transport level, an [`crate::error::ConductorError::Auth`]/[`crate::error::ConductorError::Api`]/[`crate::error::ConductorError::Server`] variant if the server responds with a non-2xx status, or [`crate::error::ConductorError::Json`] if the response body can't be deserialized.
356    pub async fn get_task_poll_data(&self, task_type: &str) -> Result<Vec<PollData>> {
357        let path = format!("/tasks/queue/polldata/{task_type}");
358        self.api
359            .get(ApiPath::templated(
360                &path,
361                "/tasks/queue/polldata/{taskType}",
362            ))
363            .await
364    }
365
366    /// Get all poll data.
367    ///
368    /// # Errors
369    ///
370    /// Returns [`crate::error::ConductorError::Http`] if the request fails at the transport level, an [`crate::error::ConductorError::Auth`]/[`crate::error::ConductorError::Api`]/[`crate::error::ConductorError::Server`] variant if the server responds with a non-2xx status, or [`crate::error::ConductorError::Json`] if the response body can't be deserialized.
371    pub async fn get_all_poll_data(&self) -> Result<Vec<PollData>> {
372        self.api.get("/tasks/queue/polldata/all").await
373    }
374
375    /// Get poll data (alias for `get_task_poll_data`).
376    ///
377    /// # Errors
378    ///
379    /// Returns [`crate::error::ConductorError::Http`] if the request fails at the transport level, an [`crate::error::ConductorError::Auth`]/[`crate::error::ConductorError::Api`]/[`crate::error::ConductorError::Server`] variant if the server responds with a non-2xx status, or [`crate::error::ConductorError::Json`] if the response body can't be deserialized.
380    pub async fn get_poll_data(&self, task_type: &str) -> Result<Vec<PollData>> {
381        self.get_task_poll_data(task_type).await
382    }
383
384    /// Search for tasks.
385    ///
386    /// # Errors
387    ///
388    /// Returns [`crate::error::ConductorError::Http`] if the request fails at the transport level, an [`crate::error::ConductorError::Auth`]/[`crate::error::ConductorError::Api`]/[`crate::error::ConductorError::Server`] variant if the server responds with a non-2xx status, or [`crate::error::ConductorError::Json`] if the response body can't be deserialized.
389    pub async fn search_tasks(
390        &self,
391        query: Option<&str>,
392        free_text: Option<&str>,
393        start: i32,
394        size: i32,
395    ) -> Result<crate::client::workflow_client::SearchResult<Task>> {
396        let mut params = vec![("start", start.to_string()), ("size", size.to_string())];
397
398        if let Some(q) = query {
399            params.push(("query", q.to_owned()));
400        }
401        if let Some(ft) = free_text {
402            params.push(("freeText", ft.to_owned()));
403        }
404
405        let params: Vec<(&str, &str)> = params.iter().map(|(k, v)| (*k, v.as_str())).collect();
406
407        self.api.get_with_params("/tasks/search", &params).await
408    }
409
410    /// Search for tasks V2 (returns full task objects).
411    ///
412    /// # Errors
413    ///
414    /// Returns [`crate::error::ConductorError::Http`] if the request fails at the transport level, an [`crate::error::ConductorError::Auth`]/[`crate::error::ConductorError::Api`]/[`crate::error::ConductorError::Server`] variant if the server responds with a non-2xx status, or [`crate::error::ConductorError::Json`] if the response body can't be deserialized.
415    pub async fn search_tasks_v2(
416        &self,
417        query: Option<&str>,
418        free_text: Option<&str>,
419        start: i32,
420        size: i32,
421    ) -> Result<crate::client::workflow_client::SearchResult<Task>> {
422        let mut params = vec![("start", start.to_string()), ("size", size.to_string())];
423
424        if let Some(q) = query {
425            params.push(("query", q.to_owned()));
426        }
427        if let Some(ft) = free_text {
428            params.push(("freeText", ft.to_owned()));
429        }
430
431        let params: Vec<(&str, &str)> = params.iter().map(|(k, v)| (*k, v.as_str())).collect();
432
433        self.api.get_with_params("/tasks/search-v2", &params).await
434    }
435
436    /// Requeue pending tasks.
437    ///
438    /// # Errors
439    ///
440    /// Returns [`crate::error::ConductorError::Http`] if the request fails at the transport level, an [`crate::error::ConductorError::Auth`]/[`crate::error::ConductorError::Api`]/[`crate::error::ConductorError::Server`] variant if the server responds with a non-2xx status, or [`crate::error::ConductorError::Json`] if the response body can't be deserialized.
441    pub async fn requeue_pending_tasks(&self, task_type: &str) -> Result<String> {
442        let path = format!("/tasks/queue/requeue/{task_type}");
443        self.api
444            .post_text(
445                ApiPath::templated(&path, "/tasks/queue/requeue/{taskType}"),
446                &serde_json::Value::Null,
447            )
448            .await
449    }
450}
451
452/// Poll data for a task queue.
453#[derive(Debug, Clone, Default, serde::Serialize, serde::Deserialize)]
454#[serde(rename_all = "camelCase")]
455pub struct PollData {
456    /// Queue name / task type.
457    #[serde(default)]
458    pub queue_name: String,
459
460    /// Domain.
461    #[serde(skip_serializing_if = "Option::is_none")]
462    pub domain: Option<String>,
463
464    /// Worker ID that last polled.
465    #[serde(skip_serializing_if = "Option::is_none")]
466    pub worker_id: Option<String>,
467
468    /// Last poll time.
469    #[serde(default)]
470    pub last_poll_time: i64,
471}
472
473fn status_to_string(status: crate::models::TaskResultStatus) -> &'static str {
474    match status {
475        crate::models::TaskResultStatus::Completed => "COMPLETED",
476        crate::models::TaskResultStatus::Failed => "FAILED",
477        crate::models::TaskResultStatus::FailedWithTerminalError => "FAILED_WITH_TERMINAL_ERROR",
478        crate::models::TaskResultStatus::InProgress => "IN_PROGRESS",
479        crate::models::TaskResultStatus::Canceled => "CANCELED",
480    }
481}
482
483#[cfg(test)]
484mod tests {
485    use super::*;
486    use crate::models::TaskResultStatus;
487
488    #[test]
489    fn test_task_result_creation() {
490        let result = TaskResult::completed("task-1", "wf-1")
491            .with_worker_id("worker-1")
492            .with_output_value("result", "success");
493
494        assert_eq!(result.task_id, "task-1");
495        assert_eq!(result.workflow_instance_id, "wf-1");
496        assert_eq!(result.status, TaskResultStatus::Completed);
497    }
498}