Skip to main content

orcher_sdk/task/
context.rs

1//! The context passed to a task while it runs.
2
3use crate::error::{Error, Result};
4use serde::Serialize;
5use std::sync::Arc;
6use std::time::{Duration, SystemTime};
7use tokio::sync::mpsc;
8
9/// The context a task runs in.
10///
11/// Through it a task reports progress with heartbeats, learns that it has been
12/// canceled, reads metadata about the attempt, and gets a logger.
13///
14/// ## Heartbeats
15///
16/// The worker heartbeats every task it runs on its own, at a third of the
17/// task's heartbeat timeout, so a long task needs no heartbeat code to stay
18/// alive, and one whose worker dies is timed out and retried. A task calls
19/// `heartbeat` to report progress: the details are sent with the next
20/// heartbeat due. They are not handed to a later attempt; a retried task
21/// starts without them, so keep anything it must resume from in its own
22/// storage. The heartbeat's answer is also how the engine asks a task to stop; see
23/// [`is_cancelled`](Self::is_cancelled).
24///
25/// ```rust
26/// # use orcher_sdk::prelude::*;
27/// async fn long_task(ctx: &TaskContext, items: Vec<String>) -> Result<()> {
28///     for (i, item) in items.iter().enumerate() {
29///         // Process item
30///         process_item(item).await?;
31///
32///         // Report progress every 10 items.
33///         if i % 10 == 0 {
34///             ctx.heartbeat().await?;
35///         }
36///     }
37///     Ok(())
38/// }
39/// # async fn process_item(item: &str) -> Result<()> { Ok(()) }
40/// ```
41pub struct TaskContext {
42    workflow_id: String,
43
44    run_id: String,
45
46    task_id: String,
47
48    /// Starts at 1.
49    attempt: i32,
50
51    heartbeat_timeout: Option<Duration>,
52
53    /// Channel to a heartbeat consumer, for contexts not run by the task driver.
54    heartbeat_tx: Option<mpsc::UnboundedSender<HeartbeatMessage>>,
55
56    /// Canceled when the task should stop.
57    cancellation_token: Arc<tokio_util::sync::CancellationToken>,
58
59    /// The worker host running the task, and the task's token: `heartbeat`
60    /// reports through it.
61    host: Option<(orcher_sdk_core::EncodedHost, Vec<u8>)>,
62}
63
64/// A heartbeat sent through `heartbeat_tx`.
65#[derive(Debug, Clone)]
66#[allow(dead_code)] // Used internally for heartbeat communication
67pub(crate) struct HeartbeatMessage {
68    /// The task sending the heartbeat.
69    pub task_id: String,
70
71    /// Progress details, serialized as JSON.
72    pub details: Option<Vec<u8>>,
73
74    /// When the heartbeat was sent.
75    pub timestamp: SystemTime,
76}
77
78/// Records a heartbeat with the worker host, as the encoded host messages
79/// carry it, and returns the host's answer. The host encodes its answer from
80/// the same protocol, so one that does not decode is a bug on one side or the
81/// other: logged as an error, and the heartbeat reported as failed.
82fn heartbeat_through(
83    host: &orcher_sdk_core::EncodedHost,
84    token: &[u8],
85    details: Option<Vec<u8>>,
86) -> Result<orcher_proto::host::v1::HeartbeatAnswer> {
87    use orcher_proto::prost::Message;
88    let heartbeat = orcher_proto::host::v1::TaskHeartbeat {
89        token: token.to_vec(),
90        details: details.map(|data| orcher_proto::kernel::v1::Payload {
91            data,
92            metadata: [("encoding".to_string(), b"json".to_vec())].into(),
93            ..Default::default()
94        }),
95        ..Default::default()
96    };
97    let failed = |message: String| {
98        tracing::error!("{message}");
99        Error::Task(crate::error::TaskError::HeartbeatFailed(message))
100    };
101    let answer = host
102        .heartbeat(&heartbeat.encode_to_vec())
103        .map_err(|e| failed(format!("The worker host refused the heartbeat: {e}")))?;
104    orcher_proto::host::v1::HeartbeatAnswer::decode(answer.as_slice()).map_err(|e| {
105        failed(format!(
106            "The worker host answered the heartbeat with bytes that are not a HeartbeatAnswer: {e}"
107        ))
108    })
109}
110
111/// The attempt a task runs, counted from 1.
112///
113/// An engine that does not number the attempt sends 0, as engines up to 0.5.4
114/// did for every attempt, retries included; that reads as 1, so a first
115/// attempt is never reported as attempt 0.
116fn counted_from_one(attempt: i32) -> i32 {
117    attempt.max(1)
118}
119
120impl TaskContext {
121    /// Create a task context with no heartbeat consumer.
122    #[cfg_attr(not(test), allow(dead_code))] // The worker builds one with its heartbeat.
123    pub(crate) fn new(
124        workflow_id: String,
125        run_id: String,
126        task_id: String,
127        attempt: i32,
128        heartbeat_timeout: Option<Duration>,
129    ) -> Self {
130        Self {
131            workflow_id,
132            run_id,
133            task_id,
134            attempt: counted_from_one(attempt),
135            heartbeat_timeout,
136            heartbeat_tx: None,
137            cancellation_token: Arc::new(tokio_util::sync::CancellationToken::new()),
138            host: None,
139        }
140    }
141
142    /// Create a task context for a task the worker host is running.
143    /// `heartbeat` reports through the host, and the context is cancelled
144    /// when the engine asks the task to stop (the host learns of it from the
145    /// heartbeats it sends) or the worker stops.
146    pub(crate) fn with_host(
147        workflow_id: String,
148        run_id: String,
149        task_id: String,
150        attempt: i32,
151        heartbeat_timeout: Option<Duration>,
152        host: orcher_sdk_core::EncodedHost,
153        token: Vec<u8>,
154    ) -> Self {
155        let cancellation_token = tokio_util::sync::CancellationToken::new();
156        {
157            let (host, token, cancel) = (host.clone(), token.clone(), cancellation_token.clone());
158            // Ends when the task is asked to stop, or once its outcome is
159            // reported.
160            tokio::spawn(async move {
161                if host.task_cancelled(&token).await {
162                    cancel.cancel();
163                }
164            });
165        }
166        Self {
167            workflow_id,
168            run_id,
169            task_id,
170            attempt: counted_from_one(attempt),
171            heartbeat_timeout,
172            heartbeat_tx: None,
173            cancellation_token: Arc::new(cancellation_token),
174            host: Some((host, token)),
175        }
176    }
177
178    /// Create a task context that sends heartbeats through `heartbeat_tx`.
179    #[allow(dead_code)] // Used by service executor for heartbeat support
180    pub(crate) fn with_heartbeat_channel(
181        workflow_id: String,
182        run_id: String,
183        task_id: String,
184        attempt: i32,
185        heartbeat_timeout: Option<Duration>,
186        heartbeat_tx: mpsc::UnboundedSender<HeartbeatMessage>,
187        cancellation_token: Arc<tokio_util::sync::CancellationToken>,
188    ) -> Self {
189        Self {
190            workflow_id,
191            run_id,
192            task_id,
193            attempt: counted_from_one(attempt),
194            heartbeat_timeout,
195            heartbeat_tx: Some(heartbeat_tx),
196            cancellation_token,
197            host: None,
198        }
199    }
200
201    // ============================================================================
202    // Heartbeat
203    // ============================================================================
204
205    /// Send a heartbeat to indicate the task is still running.
206    ///
207    /// The worker already heartbeats the task on its own while it runs; this
208    /// adds one from the task's code, folded into the same stream: it never
209    /// waits, and however often it is called no more heartbeats are sent than
210    /// the worker's timer sends. Fails once the task has been cancelled.
211    ///
212    /// # Example
213    ///
214    /// ```rust
215    /// # use orcher_sdk::prelude::*;
216    /// async fn my_task(ctx: &TaskContext) -> Result<()> {
217    ///     for i in 0..100 {
218    ///         // Do some work
219    ///         heavy_operation(i).await?;
220    ///
221    ///         // Report progress on every iteration.
222    ///         ctx.heartbeat().await?;
223    ///     }
224    ///     Ok(())
225    /// }
226    /// # async fn heavy_operation(i: i32) -> Result<()> { Ok(()) }
227    /// ```
228    pub async fn heartbeat(&self) -> Result<()> {
229        self.heartbeat_with_details::<()>(None).await
230    }
231
232    /// Send a heartbeat with optional progress details.
233    ///
234    /// The details can be any serializable value. They report progress only:
235    /// a retried attempt does not receive them.
236    ///
237    /// # Example
238    ///
239    /// ```rust
240    /// # use orcher_sdk::prelude::*;
241    /// # use serde::Serialize;
242    /// #[derive(Serialize)]
243    /// struct Progress {
244    ///     current: u32,
245    ///     total: u32,
246    /// }
247    ///
248    /// async fn my_task(ctx: &TaskContext) -> Result<()> {
249    ///     let total = 100;
250    ///     for current in 0..total {
251    ///         // Do work
252    ///         process_item(current).await?;
253    ///
254    ///         // Report how far the task has got.
255    ///         ctx.heartbeat_with_details(Some(Progress { current, total })).await?;
256    ///     }
257    ///     Ok(())
258    /// }
259    /// # async fn process_item(i: u32) -> Result<()> { Ok(()) }
260    /// ```
261    pub async fn heartbeat_with_details<T>(&self, details: Option<T>) -> Result<()>
262    where
263        T: Serialize,
264    {
265        if self.cancellation_token.is_cancelled() {
266            return Err(Error::Task(crate::error::TaskError::Canceled));
267        }
268
269        let details_bytes = match details {
270            Some(d) => {
271                let bytes = serde_json::to_vec(&d).map_err(|e| {
272                    Error::Serialization(format!("Failed to serialize heartbeat details: {}", e))
273                })?;
274                Some(bytes)
275            }
276            None => None,
277        };
278
279        // Handed to the driver, which sends it with the next heartbeat due.
280        if let Some((host, token)) = &self.host {
281            if heartbeat_through(host, token, details_bytes)?.cancel_requested {
282                self.cancellation_token.cancel();
283            }
284        } else if let Some(tx) = &self.heartbeat_tx {
285            let has_details = details_bytes.is_some();
286            let message = HeartbeatMessage {
287                task_id: self.task_id.clone(),
288                details: details_bytes,
289                timestamp: SystemTime::now(),
290            };
291
292            // The channel is unbounded, so this never blocks.
293            tx.send(message).map_err(|_| {
294                Error::Task(crate::error::TaskError::HeartbeatFailed(
295                    "Heartbeat channel closed".to_string(),
296                ))
297            })?;
298
299            tracing::debug!(
300                task_id = %self.task_id,
301                workflow_id = %self.workflow_id,
302                has_details = has_details,
303                "Heartbeat sent"
304            );
305        } else {
306            // No consumer (for example in tests): the heartbeat is dropped.
307            tracing::trace!(
308                task_id = %self.task_id,
309                "Heartbeat called but no channel configured (testing mode)"
310            );
311        }
312
313        Ok(())
314    }
315
316    // ============================================================================
317    // Metadata
318    // ============================================================================
319
320    /// Get the workflow ID this task belongs to.
321    pub fn workflow_id(&self) -> &str {
322        &self.workflow_id
323    }
324
325    /// Get the workflow run ID.
326    pub fn run_id(&self) -> &str {
327        &self.run_id
328    }
329
330    /// Get the unique task ID.
331    pub fn task_id(&self) -> &str {
332        &self.task_id
333    }
334
335    /// Get the current attempt number, starting at 1.
336    ///
337    /// Useful for behaving differently on retries.
338    pub fn attempt(&self) -> i32 {
339        self.attempt
340    }
341
342    /// Get the heartbeat timeout, if configured.
343    pub fn heartbeat_timeout(&self) -> Option<Duration> {
344        self.heartbeat_timeout
345    }
346
347    /// Check if this is a retry attempt.
348    pub fn is_retry(&self) -> bool {
349        self.attempt > 1
350    }
351
352    /// Check if the task has been cancelled.
353    ///
354    /// A long-running task should check this periodically and return early
355    /// once it is set.
356    ///
357    /// # Example
358    ///
359    /// ```rust
360    /// # use orcher_sdk::prelude::*;
361    /// use orcher_sdk::error::TaskError;
362    ///
363    /// async fn long_task(ctx: &TaskContext) -> Result<()> {
364    ///     for i in 0..1000 {
365    ///         // Check for cancellation
366    ///         if ctx.is_cancelled() {
367    ///             return Err(Error::Task(TaskError::Canceled));
368    ///         }
369    ///
370    ///         // Do work...
371    ///         process_item(i).await?;
372    ///     }
373    ///     Ok(())
374    /// }
375    /// # async fn process_item(i: i32) -> Result<()> { Ok(()) }
376    /// ```
377    pub fn is_cancelled(&self) -> bool {
378        self.cancellation_token.is_cancelled()
379    }
380
381    /// Get the task's cancellation token.
382    ///
383    /// Use it with `tokio::select!` to stop waiting on work as soon as the
384    /// task is canceled.
385    ///
386    /// # Example
387    ///
388    /// ```rust
389    /// # use orcher_sdk::prelude::*;
390    /// use orcher_sdk::error::TaskError;
391    ///
392    /// async fn cancellable_task(ctx: &TaskContext) -> Result<()> {
393    ///     let token = ctx.cancellation_token();
394    ///     let work = async {
395    ///         // Do long-running work
396    ///         tokio::time::sleep(std::time::Duration::from_secs(3600)).await;
397    ///         Ok(())
398    ///     };
399    ///
400    ///     tokio::select! {
401    ///         result = work => result,
402    ///         _ = token.cancelled() => {
403    ///             Err(Error::Task(TaskError::Canceled))
404    ///         }
405    ///     }
406    /// }
407    /// ```
408    pub fn cancellation_token(&self) -> Arc<tokio_util::sync::CancellationToken> {
409        Arc::clone(&self.cancellation_token)
410    }
411
412    // ============================================================================
413    // Logging
414    // ============================================================================
415
416    /// Get a logger for this task.
417    ///
418    /// The logger carries the task's metadata.
419    ///
420    /// # Example
421    ///
422    /// ```rust
423    /// # use orcher_sdk::prelude::*;
424    /// async fn my_task(ctx: &TaskContext) -> Result<()> {
425    ///     let logger = ctx.logger();
426    ///     tracing::info!(
427    ///         workflow_id = logger.workflow_id(),
428    ///         task_id = logger.task_id(),
429    ///         attempt = logger.attempt(),
430    ///         "task started"
431    ///     );
432    ///     Ok(())
433    /// }
434    /// ```
435    pub fn logger(&self) -> TaskLogger {
436        TaskLogger {
437            workflow_id: self.workflow_id.clone(),
438            run_id: self.run_id.clone(),
439            task_id: self.task_id.clone(),
440            attempt: self.attempt,
441        }
442    }
443}
444
445/// Task metadata for structured logging, from [`TaskContext::logger`].
446pub struct TaskLogger {
447    workflow_id: String,
448    run_id: String,
449    task_id: String,
450    attempt: i32,
451}
452
453impl TaskLogger {
454    /// Get the logging target for this task.
455    pub fn target(&self) -> String {
456        format!("orcher_sdk::task::{}", self.task_id)
457    }
458
459    /// Get the workflow ID.
460    pub fn workflow_id(&self) -> &str {
461        &self.workflow_id
462    }
463
464    /// Get the run ID.
465    pub fn run_id(&self) -> &str {
466        &self.run_id
467    }
468
469    /// Get the task ID.
470    pub fn task_id(&self) -> &str {
471        &self.task_id
472    }
473
474    /// Get the attempt number.
475    pub fn attempt(&self) -> i32 {
476        self.attempt
477    }
478}