Task Configuration
Task macros and decorators accept configuration attributes that control naming, routing, retries, timeouts, and resource requirements. These are set at definition time and apply to every invocation of the task.
Standalone vs Grouped Tasks
Orcher supports two patterns for defining tasks:
- Standalone tasks — individual functions decorated with
#[task](Rust),@Task()(TypeScript), or@task(Python) - Task groups (Rust) — multiple
#[task]methods on an impl block via#[tasks], with group-level defaults
Both patterns produce the same runtime behavior. Task groups are purely an organizational and DX feature — they register tasks identically to standalone functions.
Basic Attributes
Every task has a name and a task queue. The name identifies the task type for routing and observability. The task queue determines which workers receive the task.
1#[task(2name = "process_payment", // Task identifier (required)3description = "Charge credit card", // Human-readable description4version = "1.0.0", // Task version (default: "1.0.0")5namespace = "payments" // Namespace for multi-tenancy6)]7pub async fn process_payment(8ctx: TaskContext,9input: PaymentInput,10) -> Result<PaymentResult> {11// Implementation12}Retry Configuration
Configure how many times a task is retried on failure and the delay strategy between attempts. You can set a maximum number of attempts, initial and maximum backoff intervals, and a backoff coefficient for exponential delay growth.
1// Simple retry (exponential backoff)2#[task(3name = "fetch_data",4retry = 5 // Retry up to 5 times with exponential backoff5)]6pub async fn fetch_data(7_ctx: TaskContext,8url: String,9) -> Result<String> {10let response = reqwest::get(&url).await?.text().await?;11Ok(response)12}1314// Advanced retry policy15#[task(16name = "flaky_operation",17retry_policy(18 max_attempts = 5,19 initial_interval = 1, // Start with 1 second delay20 max_interval = 60, // Cap at 60 seconds21 backoff_coefficient = 2.0 // Double delay each retry22)23)]24pub async fn flaky_operation(25ctx: TaskContext,26input: OperationInput,27) -> Result<OperationResult> {28// Will retry with delays: 1s, 2s, 4s, 8s, 16s29if ctx.is_retry() {30 tracing::warn!("Retrying operation (attempt {})", ctx.attempt());31}3233// Implementation34Ok(result)35}Timeout Configuration
Two independent limits bound a task. The queue limit (schedule_to_start) caps how long it may wait to be picked up; the run limit (start_to_close) caps how long it may run once started. Exceeding either marks the task timed out, and it is retried according to its retry policy.
They are set separately because they answer different questions. A nightly reconciliation job may legitimately queue for an hour and must not run for more than ten minutes; a payment capture must start within seconds and may take a minute. Setting only a run limit leaves the wait unbounded, which is the right default — a task that has not started yet has not misbehaved.
1// Timeout in seconds2#[task(3name = "slow_operation",4timeout = 300 // 5 minutes timeout5)]6pub async fn slow_operation(7_ctx: TaskContext,8input: SlowInput,9) -> Result<SlowOutput> {10// Task will fail if it exceeds 5 minutes11}1213// Timeout shortcut (in minutes)14#[task(15name = "quick_task",16timeout_mins = 2 // Automatically converted to 120 seconds17)]18pub async fn quick_task(19_ctx: TaskContext,20input: QuickInput,21) -> Result<QuickOutput> {22// Task will fail if it exceeds 2 minutes23}Per-Call Timeouts
Limits declared on the task apply to every invocation. When one call needs different bounds — the same task used for an interactive request and for a nightly backfill — set them where the task is scheduled. Call-site values take precedence.
1use std::time::Duration;2use orcher::workflow::TaskOptions;34ctx.execute_task_with_options(5 "charge_card",6 input,7 TaskOptions {8 // How long it may run once a worker starts it.9 timeout: Some(Duration::from_secs(90)),10 // How long it may wait to be started. Omit for no queue limit.11 queue_timeout: Some(Duration::from_secs(10)),12 // Kill the task if it stops heartbeating for this long.13 heartbeat_timeout: Some(Duration::from_secs(30)),14 ..Default::default()15 },16).await?timeout bounds only the run. Omitting queue_timeout leaves the wait unbounded rather than reusing the run limit, so a task given a 90s run limit is not also given 90s to start — the two never sum into a total you did not ask for.
Reading the Limits From a Task
A handler that heartbeats needs to know the interval it is judged by: heartbeat less often than that and a healthy task is killed as stalled.
1if let Some(interval) = ctx.heartbeat_timeout() {2 // Heartbeat comfortably inside the interval, not at its edge.3 let every = interval / 3;4}Resource Requirements (Rust)
In the Rust SDK, you can declare resource requirements (memory, CPU) directly in the task macro. Workers use this information for capacity-aware scheduling — tasks are only dispatched to workers that have sufficient resources available.
1#[task(2 name = "memory_intensive",3 memory = "2Gi", // Shortcut for memory requirement4 resources(5 cpu = 2.0, // 2 CPU cores6 memory = "4Gi", // 4GB RAM7 disk = "10Gi" // 10GB disk space8 )9)]10pub async fn memory_intensive(11 _ctx: TaskContext,12 data: LargeDataset,13) -> Result<ProcessedData> {14 // Task will only run on workers with sufficient resources15}Task Groups (Rust)
In the Rust SDK, you can group related tasks under a struct using the #[tasks] macro. This provides:
- Shared defaults — set retry, timeout, task queue, etc. once for all tasks in the group
- Per-task overrides — any method-level
#[task(...)]attribute overrides the group default - Type-safe references —
StructName::methodworks as aTaskReferenceforctx.execute_task() - Code organization — logically group related tasks, add helper methods
1use orcher::prelude::*;23pub struct NotificationTasks;45#[tasks(retry = 3, timeout = 30, namespace = "notifications")]6impl NotificationTasks {7 #[task]8 async fn send_email(ctx: TaskContext, input: EmailInput) -> Result<EmailResult> {9 // inherits retry=3, timeout=30, namespace="notifications"10 let result = email_service::send(&input.to, &input.subject, &input.body).await?;11 Ok(EmailResult { message_id: result.id })12 }1314 #[task(timeout = 10)]15 async fn send_sms(ctx: TaskContext, input: SmsInput) -> Result<SmsResult> {16 // overrides timeout=10, inherits retry=3, namespace="notifications"17 let result = twilio::send_sms(&input.phone, &input.message).await?;18 Ok(SmsResult { sid: result.sid })19 }2021 #[task(retry = 5, timeout = 120, preset = "long-running")]22 async fn send_push(ctx: TaskContext, input: PushInput) -> Result<PushResult> {23 // fully custom: retry=5, timeout=120, preset="long-running"24 let result = fcm::send(&input.device_token, &input.payload).await?;25 Ok(PushResult { success: result.success })26 }2728 // Not a task — plain helper preserved as-is29 fn build_template(template_name: &str, vars: &HashMap<String, String>) -> String {30 // Template rendering logic31 format!("rendered: {}", template_name)32 }33}Using in workflows:
1#[workflow]2async fn order_confirmation(ctx: WorkflowContext, order: Order) -> Result<()> {3 // Type-safe associated constants — compile error if task doesn't exist4 ctx.execute_task(NotificationTasks::send_email, EmailInput {5 to: order.email.clone(),6 subject: "Order Confirmed".to_string(),7 body: format!("Order #{} confirmed", order.id),8 }).await?;910 if let Some(phone) = &order.phone {11 ctx.execute_task(NotificationTasks::send_sms, SmsInput {12 phone: phone.clone(),13 message: format!("Order #{} confirmed!", order.id),14 }).await?;15 }1617 Ok(())18}Group-level attributes reference:
| Attribute | Type | Description |
|---|---|---|
retry | u32 | Max retry attempts (exponential backoff) |
timeout | u64 | Timeout in seconds |
timeout_mins | u64 | Timeout in minutes |
task_queue | String | Task queue for routing |
namespace | String | Namespace for multi-tenancy |
memory | String | Memory requirement (e.g., "512Mi") |
preset | String | "long-running", "quick", or "critical" |
heartbeat_timeout | u64 | Heartbeat timeout in seconds |
priority | u8 | Priority 0-100 |
max_concurrent | u32 | Max concurrent executions |
rate_limit | u32 | Max executions per second |
Task Context
The TaskContext is a crucial object passed to every task that provides access to workflow metadata, execution state, and utilities for long-running operations.
What TaskContext Provides:
- Workflow Identification - Access to workflow ID, run ID, and task ID
- Execution Metadata - Current attempt number, retry information
- Heartbeat Mechanism - Signal progress for long-running tasks
- Cancellation Signals - Detect when workflow/task is being cancelled
- Logging Context - Structured logging with workflow context
When to Use TaskContext:
- Always available in task functions, even if you don't use it
- Required for heartbeats in long-running tasks
- Useful for debugging (include workflow_id in logs)
- Essential for cancellation-aware operations
Understanding TaskContext Properties
Every task receives a TaskContext parameter. Let's explore what information is available:
Core Properties:
1interface TaskContext {2 // Unique ID of the workflow instance3 workflowId(): string; // e.g., "wf_abc123xyz"45 // Unique ID for this specific workflow run6 runId(): string; // e.g., "run_def456uvw"78 // Unique ID for this task execution9 taskId(): string; // e.g., "task_ghi789rst"1011 // Current attempt number (starts at 1)12 attempt(): number; // 1, 2, 3, etc.1314 // Functions15 isRetry(): boolean;16 heartbeat(): Promise<void>;17 heartbeatWithDetails(details?: any): Promise<void>;18 isCancelled(): boolean;19}Metadata Access
Use Case: Access workflow and task metadata for logging, debugging, and tracking.
1#[task(name = "metadata_example")]2pub async fn metadata_example(3ctx: TaskContext,4input: String,5) -> Result<String> {6// Access workflow metadata7let workflow_id = ctx.workflow_id();8let run_id = ctx.run_id();9let task_id = ctx.task_id();10let attempt = ctx.attempt();1112tracing::info!(13 "Task {} (attempt {}) executing in workflow {} (run {})",14 task_id,15 attempt,16 workflow_id,17 run_id18);1920// Check if this is a retry21if ctx.is_retry() {22 tracing::warn!("This is a retry attempt");23}2425Ok(format!("Processed in workflow {}", workflow_id))26}Why Metadata Matters:
- Debugging: When a task fails, logs with
workflow_idlet you trace the entire workflow execution - Monitoring: Track retry patterns by logging
attemptnumbers - Alerting: Send alerts when tasks repeatedly fail (check
attemptvsmaxAttempts) - Audit Trail: Include
workflow_idin external API calls for end-to-end tracing - Dynamic Logic: Adjust behavior based on attempt number (e.g., use fallback on final attempt)
Real-World Example:
1// Inside a @Tasks() class:2@Task({ name: 'processPayment' })3async processPayment(4 ctx: TaskContext,5 payment: Payment6): Promise<PaymentResult> {7 const workflowId = ctx.workflowId();8 const attempt = ctx.attempt();9 // Mirror the task's configured retryPolicy.maxAttempts10 const maxAttempts = 3;1112 try {13 // Primary payment processor14 const result = await stripeClient.charge({15 amount: payment.amount,16 // Include workflow_id for traceability17 metadata: { workflowId },18 });1920 return result;21 } catch (error) {22 // On final attempt, try backup processor23 if (attempt >= maxAttempts) {24 logger.warn('Stripe failed, trying PayPal as fallback', {25 workflowId,26 error: error.message,27 });2829 return await paypalClient.charge({30 amount: payment.amount,31 metadata: { workflowId },32 });33 }3435 throw error; // Let Orcher retry with Stripe36 }37}Heartbeats
What are Heartbeats?
Heartbeats are periodic signals sent from long-running tasks to indicate they're still making progress. Without heartbeats, Orcher might think a task is stuck and cancel it.
When to Use Heartbeats:
- Tasks that take >30 seconds to complete
- Tasks processing large batches (thousands of items)
- Tasks with unpredictable execution time
- Tasks that might appear "stuck" but are actually working
How Heartbeats Work:
For long-running tasks, send periodic heartbeats to prevent timeout:
1#[task(2name = "process_large_batch",3timeout_mins = 60,4heartbeat_timeout = 30 // Consider stalled if no heartbeat for 30s5)]6pub async fn process_large_batch(7ctx: TaskContext,8items: Vec<Item>,9) -> Result<Vec<ProcessedItem>> {10let mut results = Vec::new();1112for (i, item) in items.iter().enumerate() {13 // Process item14 let processed = process_item(item).await?;15 results.push(processed);1617 // Send heartbeat every 10 items18 if i % 10 == 0 {19 ctx.heartbeat().await?;20 }21}2223Ok(results)24}Heartbeats with Progress
You can include progress data with each heartbeat to track how far a task has progressed. This is useful for long-running tasks like file processing or batch jobs where you want to report completion percentage or the current item being processed.
1use serde::Serialize;23#[derive(Serialize)]4struct Progress {5current: usize,6total: usize,7percent: f64,8}910#[task(name = "process_with_progress")]11pub async fn process_with_progress(12ctx: TaskContext,13items: Vec<Item>,14) -> Result<ProcessedResult> {15let total = items.len();1617for (current, item) in items.iter().enumerate() {18 process_item(item).await?;1920 // Send heartbeat with progress details21 let progress = Progress {22 current: current + 1,23 total,24 percent: ((current + 1) as f64 / total as f64) * 100.0,25 };2627 ctx.heartbeat_with_details(Some(progress)).await?;28}2930Ok(ProcessedResult { count: total })31}Cancellation Handling
Tasks can detect cancellation requests and perform cleanup before exiting. Check for cancellation periodically in long-running tasks to release resources, close connections, or roll back partial work.
1#[task(name = "cancellable_task")]2pub async fn cancellable_task(3ctx: TaskContext,4items: Vec<Item>,5) -> Result<ProcessedResult> {6for item in items {7 // Check for cancellation before processing8 if ctx.is_cancelled() {9 tracing::info!("Task cancelled, cleaning up...");10 cleanup().await?;11 return Err(anyhow::anyhow!("Task cancelled"));12 }1314 process_item(item).await?;15}1617Ok(ProcessedResult::success())18}1920// Using cancellation token with tokio::select21#[task(name = "long_wait_task")]22pub async fn long_wait_task(23ctx: TaskContext,24duration_secs: u64,25) -> Result<String> {26let work = async {27 tokio::time::sleep(Duration::from_secs(duration_secs)).await;28 Ok("Work completed".to_string())29};3031tokio::select! {32 result = work => result,33 _ = ctx.cancellation_token().cancelled() => {34 Err(anyhow::anyhow!("Task was cancelled"))35 }36}37}