Skip to main content

conductor/worker/
worker_trait.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 async_trait::async_trait;
5use serde_json::Value;
6use std::collections::HashMap;
7use std::future::Future;
8use std::pin::Pin;
9use std::sync::Arc;
10
11use crate::error::Result;
12use crate::models::{Task, TaskInProgress, TaskResult, TaskResultStatus};
13
14/// Output type for worker execution.
15#[derive(Debug, Clone)]
16pub enum WorkerOutput {
17    /// Task completed successfully with output.
18    Completed(HashMap<String, Value>),
19
20    /// Task failed with an error message — retried by the server per the task's retry policy.
21    Failed(String),
22
23    /// Task failed permanently and should not be retried (`FAILED_WITH_TERMINAL_ERROR`).
24    ///
25    /// Return this instead of [`WorkerOutput::Failed`] — or instead of a plain `Err` from
26    /// [`Worker::execute`], which always maps to [`WorkerOutput::Failed`] in `task_runner.rs` —
27    /// when the failure is definitively not worth retrying (a malformed input that will fail
28    /// identically every time, a missing local dependency like an interpreter binary, etc.).
29    /// There is currently no way to signal this from an `Err` return; a worker that needs it
30    /// must construct this variant directly and return it via `Ok(...)`.
31    FailedWithTerminalError(String),
32
33    /// Task is still in progress (for long-running tasks).
34    InProgress(TaskInProgress),
35}
36
37impl WorkerOutput {
38    /// Create a completed output with a single result value.
39    pub fn completed_with_result(result: impl serde::Serialize) -> Self {
40        let mut output = HashMap::new();
41        output.insert(
42            "result".to_owned(),
43            serde_json::to_value(result).unwrap_or(Value::Null),
44        );
45        WorkerOutput::Completed(output)
46    }
47
48    /// Create a completed output with a map.
49    #[must_use]
50    pub fn completed(output: HashMap<String, Value>) -> Self {
51        WorkerOutput::Completed(output)
52    }
53
54    /// Create a completed output with no data.
55    #[must_use]
56    pub fn complete() -> Self {
57        WorkerOutput::Completed(HashMap::new())
58    }
59
60    /// Create a failed output.
61    pub fn failed(reason: impl Into<String>) -> Self {
62        WorkerOutput::Failed(reason.into())
63    }
64
65    /// Create an in-progress output.
66    #[must_use]
67    pub fn in_progress(callback_after_seconds: i64) -> Self {
68        WorkerOutput::InProgress(TaskInProgress::new(callback_after_seconds))
69    }
70
71    /// Convert to `TaskResult`.
72    #[must_use]
73    pub fn into_task_result(self, task: &Task, worker_id: &str) -> TaskResult {
74        match self {
75            WorkerOutput::Completed(output) => TaskResult {
76                task_id: task.task_id.clone(),
77                workflow_instance_id: task.workflow_instance_id.clone(),
78                worker_id: Some(worker_id.to_owned()),
79                status: TaskResultStatus::Completed,
80                output_data: output,
81                ..Default::default()
82            },
83            WorkerOutput::Failed(reason) => TaskResult {
84                task_id: task.task_id.clone(),
85                workflow_instance_id: task.workflow_instance_id.clone(),
86                worker_id: Some(worker_id.to_owned()),
87                status: TaskResultStatus::Failed,
88                reason_for_incompletion: Some(reason),
89                ..Default::default()
90            },
91            WorkerOutput::FailedWithTerminalError(reason) => TaskResult {
92                task_id: task.task_id.clone(),
93                workflow_instance_id: task.workflow_instance_id.clone(),
94                worker_id: Some(worker_id.to_owned()),
95                status: TaskResultStatus::FailedWithTerminalError,
96                reason_for_incompletion: Some(reason),
97                ..Default::default()
98            },
99            WorkerOutput::InProgress(tip) => TaskResult {
100                task_id: task.task_id.clone(),
101                workflow_instance_id: task.workflow_instance_id.clone(),
102                worker_id: Some(worker_id.to_owned()),
103                status: TaskResultStatus::InProgress,
104                callback_after_seconds: tip.callback_after_seconds,
105                output_data: tip.output,
106                ..Default::default()
107            },
108        }
109    }
110}
111
112/// Trait for implementing Conductor task workers
113#[async_trait]
114pub trait Worker: Send + Sync {
115    /// Get the task definition name this worker handles
116    fn task_definition_name(&self) -> &str;
117
118    /// Execute the task and return the output
119    async fn execute(&self, task: &Task) -> Result<WorkerOutput>;
120
121    /// Get the worker identity (optional, defaults to hostname-pid)
122    fn identity(&self) -> String {
123        let hostname = hostname::get().map_or_else(
124            |_| "unknown".to_owned(),
125            |h| h.to_string_lossy().into_owned(),
126        );
127        format!("{}-{}", hostname, std::process::id())
128    }
129
130    /// Get the domain for this worker (optional)
131    fn domain(&self) -> Option<&str> {
132        None
133    }
134
135    /// Get the poll interval in milliseconds
136    fn poll_interval_millis(&self) -> u64 {
137        100
138    }
139
140    /// Get the maximum concurrent task executions
141    fn thread_count(&self) -> usize {
142        1
143    }
144
145    /// Get the input JSON Schema for this worker (optional)
146    ///
147    /// Return a JSON Schema that describes the expected input format.
148    /// Used when `register_task_def` is enabled to register input schema.
149    fn input_schema(&self) -> Option<serde_json::Value> {
150        None
151    }
152
153    /// Get the output JSON Schema for this worker (optional)
154    ///
155    /// Return a JSON Schema that describes the output format.
156    /// Used when `register_task_def` is enabled to register output schema.
157    fn output_schema(&self) -> Option<serde_json::Value> {
158        None
159    }
160
161    /// Get the names of credentials this worker declares as required (optional)
162    ///
163    /// Used when `register_task_def` is enabled to stamp `TaskDef::runtime_metadata`
164    /// so the server can resolve credentials before dispatching the task.
165    fn declared_credentials(&self) -> Vec<String> {
166        Vec::new()
167    }
168}
169
170/// Type alias for async worker functions.
171pub type WorkerFn =
172    Arc<dyn Fn(Task) -> Pin<Box<dyn Future<Output = Result<WorkerOutput>> + Send>> + Send + Sync>;
173
174/// Simple function-based worker implementation.
175pub struct FnWorker {
176    task_name: String,
177    execute_fn: WorkerFn,
178    identity: String,
179    domain: Option<String>,
180    poll_interval_millis: u64,
181    thread_count: usize,
182    input_schema: Option<serde_json::Value>,
183    output_schema: Option<serde_json::Value>,
184}
185
186impl FnWorker {
187    /// Create a new function-based worker.
188    pub fn new<F, Fut>(task_name: impl Into<String>, f: F) -> Self
189    where
190        F: Fn(Task) -> Fut + Send + Sync + 'static,
191        Fut: Future<Output = Result<WorkerOutput>> + Send + 'static,
192    {
193        let task_name = task_name.into();
194        let identity = format!(
195            "{}-{}",
196            hostname::get().map_or_else(
197                |_| "unknown".to_owned(),
198                |h| h.to_string_lossy().into_owned()
199            ),
200            std::process::id()
201        );
202
203        Self {
204            task_name,
205            execute_fn: Arc::new(move |task| Box::pin(f(task))),
206            identity,
207            domain: None,
208            poll_interval_millis: 100,
209            thread_count: 1,
210            input_schema: None,
211            output_schema: None,
212        }
213    }
214
215    /// Set the worker domain.
216    #[must_use]
217    pub fn with_domain(mut self, domain: impl Into<String>) -> Self {
218        self.domain = Some(domain.into());
219        self
220    }
221
222    /// Set the poll interval.
223    #[must_use]
224    pub fn with_poll_interval_millis(mut self, millis: u64) -> Self {
225        self.poll_interval_millis = millis;
226        self
227    }
228
229    /// Set the thread count.
230    #[must_use]
231    pub fn with_thread_count(mut self, count: usize) -> Self {
232        self.thread_count = count;
233        self
234    }
235
236    /// Set the worker identity.
237    #[must_use]
238    pub fn with_identity(mut self, identity: impl Into<String>) -> Self {
239        self.identity = identity.into();
240        self
241    }
242
243    /// Set the input JSON Schema.
244    #[must_use]
245    pub fn with_input_schema(mut self, schema: serde_json::Value) -> Self {
246        self.input_schema = Some(schema);
247        self
248    }
249
250    /// Set the output JSON Schema.
251    #[must_use]
252    pub fn with_output_schema(mut self, schema: serde_json::Value) -> Self {
253        self.output_schema = Some(schema);
254        self
255    }
256
257    /// Set input schema from a `JsonSchema` type.
258    #[must_use]
259    pub fn with_input_schema_from<T>(mut self, strict: bool) -> Self
260    where
261        T: schemars::JsonSchema,
262    {
263        self.input_schema = Some(crate::schema::generate_schema::<T>(strict));
264        self
265    }
266
267    /// Set output schema from a `JsonSchema` type.
268    #[must_use]
269    pub fn with_output_schema_from<T>(mut self, strict: bool) -> Self
270    where
271        T: schemars::JsonSchema,
272    {
273        self.output_schema = Some(crate::schema::generate_schema::<T>(strict));
274        self
275    }
276}
277
278#[async_trait]
279impl Worker for FnWorker {
280    fn task_definition_name(&self) -> &str {
281        &self.task_name
282    }
283
284    async fn execute(&self, task: &Task) -> Result<WorkerOutput> {
285        (self.execute_fn)(task.clone()).await
286    }
287
288    fn identity(&self) -> String {
289        self.identity.clone()
290    }
291
292    fn domain(&self) -> Option<&str> {
293        self.domain.as_deref()
294    }
295
296    fn poll_interval_millis(&self) -> u64 {
297        self.poll_interval_millis
298    }
299
300    fn thread_count(&self) -> usize {
301        self.thread_count
302    }
303
304    fn input_schema(&self) -> Option<serde_json::Value> {
305        self.input_schema.clone()
306    }
307
308    fn output_schema(&self) -> Option<serde_json::Value> {
309        self.output_schema.clone()
310    }
311}
312
313/// Type alias for async worker functions that use `Arc<Task>` (zero-copy).
314pub type WorkerFnArc = Arc<
315    dyn Fn(Arc<Task>) -> Pin<Box<dyn Future<Output = Result<WorkerOutput>> + Send>> + Send + Sync,
316>;
317
318/// High-performance function-based worker that uses `Arc<Task>` to avoid cloning.
319///
320/// Use this instead of `FnWorker` for high-throughput scenarios where task
321/// cloning overhead is significant.
322///
323/// # Example
324/// ```rust,ignore
325/// let worker = FnWorkerArc::new("my_task", |task: Arc<Task>| async move {
326///     let name = task.get_input_string("name").unwrap_or_default();
327///     Ok(WorkerOutput::completed_with_result(format!("Hello, {}!", name)))
328/// });
329/// ```
330pub struct FnWorkerArc {
331    task_name: String,
332    execute_fn: WorkerFnArc,
333    identity: String,
334    domain: Option<String>,
335    poll_interval_millis: u64,
336    thread_count: usize,
337    input_schema: Option<serde_json::Value>,
338    output_schema: Option<serde_json::Value>,
339}
340
341impl FnWorkerArc {
342    /// Create a new high-performance function-based worker.
343    pub fn new<F, Fut>(task_name: impl Into<String>, f: F) -> Self
344    where
345        F: Fn(Arc<Task>) -> Fut + Send + Sync + 'static,
346        Fut: Future<Output = Result<WorkerOutput>> + Send + 'static,
347    {
348        let task_name = task_name.into();
349        let identity = format!(
350            "{}-{}",
351            hostname::get().map_or_else(
352                |_| "unknown".to_owned(),
353                |h| h.to_string_lossy().into_owned()
354            ),
355            std::process::id()
356        );
357
358        Self {
359            task_name,
360            execute_fn: Arc::new(move |task| Box::pin(f(task))),
361            identity,
362            domain: None,
363            poll_interval_millis: 100,
364            thread_count: 1,
365            input_schema: None,
366            output_schema: None,
367        }
368    }
369
370    /// Set the worker domain.
371    #[must_use]
372    pub fn with_domain(mut self, domain: impl Into<String>) -> Self {
373        self.domain = Some(domain.into());
374        self
375    }
376
377    /// Set the poll interval.
378    #[must_use]
379    pub fn with_poll_interval_millis(mut self, millis: u64) -> Self {
380        self.poll_interval_millis = millis;
381        self
382    }
383
384    /// Set the thread count.
385    #[must_use]
386    pub fn with_thread_count(mut self, count: usize) -> Self {
387        self.thread_count = count;
388        self
389    }
390
391    /// Set the worker identity.
392    #[must_use]
393    pub fn with_identity(mut self, identity: impl Into<String>) -> Self {
394        self.identity = identity.into();
395        self
396    }
397
398    /// Set the input JSON Schema.
399    #[must_use]
400    pub fn with_input_schema(mut self, schema: serde_json::Value) -> Self {
401        self.input_schema = Some(schema);
402        self
403    }
404
405    /// Set the output JSON Schema.
406    #[must_use]
407    pub fn with_output_schema(mut self, schema: serde_json::Value) -> Self {
408        self.output_schema = Some(schema);
409        self
410    }
411
412    /// Set input schema from a `JsonSchema` type.
413    #[must_use]
414    pub fn with_input_schema_from<T>(mut self, strict: bool) -> Self
415    where
416        T: schemars::JsonSchema,
417    {
418        self.input_schema = Some(crate::schema::generate_schema::<T>(strict));
419        self
420    }
421
422    /// Set output schema from a `JsonSchema` type.
423    #[must_use]
424    pub fn with_output_schema_from<T>(mut self, strict: bool) -> Self
425    where
426        T: schemars::JsonSchema,
427    {
428        self.output_schema = Some(crate::schema::generate_schema::<T>(strict));
429        self
430    }
431
432    /// Execute with `Arc<Task>` directly (internal use).
433    ///
434    /// # Errors
435    ///
436    /// Propagates whatever error the worker's `execute_fn` returns.
437    pub async fn execute_arc(&self, task: Arc<Task>) -> Result<WorkerOutput> {
438        (self.execute_fn)(task).await
439    }
440}
441
442#[async_trait]
443impl Worker for FnWorkerArc {
444    fn task_definition_name(&self) -> &str {
445        &self.task_name
446    }
447
448    async fn execute(&self, task: &Task) -> Result<WorkerOutput> {
449        // Still need to clone for the trait interface, but users can use execute_arc directly
450        (self.execute_fn)(Arc::new(task.clone())).await
451    }
452
453    fn identity(&self) -> String {
454        self.identity.clone()
455    }
456
457    fn domain(&self) -> Option<&str> {
458        self.domain.as_deref()
459    }
460
461    fn poll_interval_millis(&self) -> u64 {
462        self.poll_interval_millis
463    }
464
465    fn thread_count(&self) -> usize {
466        self.thread_count
467    }
468
469    fn input_schema(&self) -> Option<serde_json::Value> {
470        self.input_schema.clone()
471    }
472
473    fn output_schema(&self) -> Option<serde_json::Value> {
474        self.output_schema.clone()
475    }
476}
477
478/// Macro to simplify worker creation from closures.
479///
480/// # Example
481/// ```rust,ignore
482/// let worker = worker_fn!("my_task", |task| async move {
483///     Ok(WorkerOutput::completed_with_result("done"))
484/// });
485/// ```
486#[macro_export]
487macro_rules! worker_fn {
488    ($task_name:expr, $handler:expr) => {
489        $crate::worker::FnWorker::new($task_name, $handler)
490    };
491}
492
493#[cfg(test)]
494mod tests {
495    use super::*;
496
497    #[tokio::test]
498    async fn test_fn_worker() {
499        let worker = FnWorker::new("test_task", |task: Task| async move {
500            let name = task
501                .get_input_string("name")
502                .unwrap_or_else(|| "World".to_owned());
503            Ok(WorkerOutput::completed_with_result(format!(
504                "Hello, {name}!"
505            )))
506        })
507        .with_thread_count(5)
508        .with_poll_interval_millis(500);
509
510        assert_eq!(worker.task_definition_name(), "test_task");
511        assert_eq!(worker.thread_count(), 5);
512        assert_eq!(worker.poll_interval_millis(), 500);
513
514        let mut task = Task::default();
515        task.input_data
516            .insert("name".to_owned(), serde_json::json!("Rust"));
517
518        let result = worker.execute(&task).await.unwrap();
519        match result {
520            WorkerOutput::Completed(output) => {
521                assert!(output.contains_key("result"));
522            }
523            _ => panic!("Expected completed output"),
524        }
525    }
526
527    #[test]
528    fn test_worker_output_conversion() {
529        let task = Task {
530            task_id: "task-1".to_owned(),
531            workflow_instance_id: "wf-1".to_owned(),
532            ..Default::default()
533        };
534
535        let output = WorkerOutput::completed_with_result("success");
536        let result = output.into_task_result(&task, "worker-1");
537
538        assert_eq!(result.task_id, "task-1");
539        assert_eq!(result.status, TaskResultStatus::Completed);
540        assert_eq!(result.worker_id, Some("worker-1".to_owned()));
541    }
542
543    #[test]
544    fn test_worker_output_failed_is_retryable_status() {
545        let task = Task::default();
546        let result =
547            WorkerOutput::Failed("transient error".to_owned()).into_task_result(&task, "worker-1");
548        assert_eq!(result.status, TaskResultStatus::Failed);
549        assert_eq!(
550            result.reason_for_incompletion,
551            Some("transient error".to_owned())
552        );
553    }
554
555    #[test]
556    fn test_worker_output_failed_with_terminal_error_conversion() {
557        let task = Task {
558            task_id: "task-1".to_owned(),
559            workflow_instance_id: "wf-1".to_owned(),
560            ..Default::default()
561        };
562
563        let output = WorkerOutput::FailedWithTerminalError("not retryable".to_owned());
564        let result = output.into_task_result(&task, "worker-1");
565
566        assert_eq!(result.task_id, "task-1");
567        assert_eq!(result.status, TaskResultStatus::FailedWithTerminalError);
568        assert_eq!(
569            result.reason_for_incompletion,
570            Some("not retryable".to_owned())
571        );
572        assert_eq!(result.worker_id, Some("worker-1".to_owned()));
573    }
574}