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}