Guides

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(
2
name = "process_payment", // Task identifier (required)
3
description = "Charge credit card", // Human-readable description
4
version = "1.0.0", // Task version (default: "1.0.0")
5
namespace = "payments" // Namespace for multi-tenancy
6
)]
7
pub async fn process_payment(
8
ctx: TaskContext,
9
input: PaymentInput,
10
) -> Result<PaymentResult> {
11
// Implementation
12
}

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(
3
name = "fetch_data",
4
retry = 5 // Retry up to 5 times with exponential backoff
5
)]
6
pub async fn fetch_data(
7
_ctx: TaskContext,
8
url: String,
9
) -> Result<String> {
10
let response = reqwest::get(&url).await?.text().await?;
11
Ok(response)
12
}
13
14
// Advanced retry policy
15
#[task(
16
name = "flaky_operation",
17
retry_policy(
18
max_attempts = 5,
19
initial_interval = 1, // Start with 1 second delay
20
max_interval = 60, // Cap at 60 seconds
21
backoff_coefficient = 2.0 // Double delay each retry
22
)
23
)]
24
pub async fn flaky_operation(
25
ctx: TaskContext,
26
input: OperationInput,
27
) -> Result<OperationResult> {
28
// Will retry with delays: 1s, 2s, 4s, 8s, 16s
29
if ctx.is_retry() {
30
tracing::warn!("Retrying operation (attempt {})", ctx.attempt());
31
}
32
33
// Implementation
34
Ok(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 seconds
2
#[task(
3
name = "slow_operation",
4
timeout = 300 // 5 minutes timeout
5
)]
6
pub async fn slow_operation(
7
_ctx: TaskContext,
8
input: SlowInput,
9
) -> Result<SlowOutput> {
10
// Task will fail if it exceeds 5 minutes
11
}
12
13
// Timeout shortcut (in minutes)
14
#[task(
15
name = "quick_task",
16
timeout_mins = 2 // Automatically converted to 120 seconds
17
)]
18
pub async fn quick_task(
19
_ctx: TaskContext,
20
input: QuickInput,
21
) -> Result<QuickOutput> {
22
// Task will fail if it exceeds 2 minutes
23
}

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.

1
use std::time::Duration;
2
use orcher::workflow::TaskOptions;
3
4
ctx.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?

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.

1
if 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 requirement
4
resources(
5
cpu = 2.0, // 2 CPU cores
6
memory = "4Gi", // 4GB RAM
7
disk = "10Gi" // 10GB disk space
8
)
9
)]
10
pub async fn memory_intensive(
11
_ctx: TaskContext,
12
data: LargeDataset,
13
) -> Result<ProcessedData> {
14
// Task will only run on workers with sufficient resources
15
}

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::method works as a TaskReference for ctx.execute_task()
  • Code organization — logically group related tasks, add helper methods
1
use orcher::prelude::*;
2
3
pub struct NotificationTasks;
4
5
#[tasks(retry = 3, timeout = 30, namespace = "notifications")]
6
impl 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
}
13
14
#[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
}
20
21
#[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
}
27
28
// Not a task — plain helper preserved as-is
29
fn build_template(template_name: &str, vars: &HashMap<String, String>) -> String {
30
// Template rendering logic
31
format!("rendered: {}", template_name)
32
}
33
}

Using in workflows:

1
#[workflow]
2
async fn order_confirmation(ctx: WorkflowContext, order: Order) -> Result<()> {
3
// Type-safe associated constants — compile error if task doesn't exist
4
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?;
9
10
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
}
16
17
Ok(())
18
}

Group-level attributes reference:

AttributeTypeDescription
retryu32Max retry attempts (exponential backoff)
timeoutu64Timeout in seconds
timeout_minsu64Timeout in minutes
task_queueStringTask queue for routing
namespaceStringNamespace for multi-tenancy
memoryStringMemory requirement (e.g., "512Mi")
presetString"long-running", "quick", or "critical"
heartbeat_timeoutu64Heartbeat timeout in seconds
priorityu8Priority 0-100
max_concurrentu32Max concurrent executions
rate_limitu32Max 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:

  1. Workflow Identification - Access to workflow ID, run ID, and task ID
  2. Execution Metadata - Current attempt number, retry information
  3. Heartbeat Mechanism - Signal progress for long-running tasks
  4. Cancellation Signals - Detect when workflow/task is being cancelled
  5. 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:

1
interface TaskContext {
2
// Unique ID of the workflow instance
3
workflowId(): string; // e.g., "wf_abc123xyz"
4
5
// Unique ID for this specific workflow run
6
runId(): string; // e.g., "run_def456uvw"
7
8
// Unique ID for this task execution
9
taskId(): string; // e.g., "task_ghi789rst"
10
11
// Current attempt number (starts at 1)
12
attempt(): number; // 1, 2, 3, etc.
13
14
// Functions
15
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")]
2
pub async fn metadata_example(
3
ctx: TaskContext,
4
input: String,
5
) -> Result<String> {
6
// Access workflow metadata
7
let workflow_id = ctx.workflow_id();
8
let run_id = ctx.run_id();
9
let task_id = ctx.task_id();
10
let attempt = ctx.attempt();
11
12
tracing::info!(
13
"Task {} (attempt {}) executing in workflow {} (run {})",
14
task_id,
15
attempt,
16
workflow_id,
17
run_id
18
);
19
20
// Check if this is a retry
21
if ctx.is_retry() {
22
tracing::warn!("This is a retry attempt");
23
}
24
25
Ok(format!("Processed in workflow {}", workflow_id))
26
}

Why Metadata Matters:

  • Debugging: When a task fails, logs with workflow_id let you trace the entire workflow execution
  • Monitoring: Track retry patterns by logging attempt numbers
  • Alerting: Send alerts when tasks repeatedly fail (check attempt vs maxAttempts)
  • Audit Trail: Include workflow_id in 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' })
3
async processPayment(
4
ctx: TaskContext,
5
payment: Payment
6
): Promise<PaymentResult> {
7
const workflowId = ctx.workflowId();
8
const attempt = ctx.attempt();
9
// Mirror the task's configured retryPolicy.maxAttempts
10
const maxAttempts = 3;
11
12
try {
13
// Primary payment processor
14
const result = await stripeClient.charge({
15
amount: payment.amount,
16
// Include workflow_id for traceability
17
metadata: { workflowId },
18
});
19
20
return result;
21
} catch (error) {
22
// On final attempt, try backup processor
23
if (attempt >= maxAttempts) {
24
logger.warn('Stripe failed, trying PayPal as fallback', {
25
workflowId,
26
error: error.message,
27
});
28
29
return await paypalClient.charge({
30
amount: payment.amount,
31
metadata: { workflowId },
32
});
33
}
34
35
throw error; // Let Orcher retry with Stripe
36
}
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:

Without heartbeats
Task starts
Process item 1 · 60s+
Process item 2 …
Orcher: “task looks stuck” → cancelled
With heartbeats
Task starts
Process item 1 → heartbeat()
Process item 2 → heartbeat()
Orcher: “still working” → kept alive

For long-running tasks, send periodic heartbeats to prevent timeout:

1
#[task(
2
name = "process_large_batch",
3
timeout_mins = 60,
4
heartbeat_timeout = 30 // Consider stalled if no heartbeat for 30s
5
)]
6
pub async fn process_large_batch(
7
ctx: TaskContext,
8
items: Vec<Item>,
9
) -> Result<Vec<ProcessedItem>> {
10
let mut results = Vec::new();
11
12
for (i, item) in items.iter().enumerate() {
13
// Process item
14
let processed = process_item(item).await?;
15
results.push(processed);
16
17
// Send heartbeat every 10 items
18
if i % 10 == 0 {
19
ctx.heartbeat().await?;
20
}
21
}
22
23
Ok(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.

1
use serde::Serialize;
2
3
#[derive(Serialize)]
4
struct Progress {
5
current: usize,
6
total: usize,
7
percent: f64,
8
}
9
10
#[task(name = "process_with_progress")]
11
pub async fn process_with_progress(
12
ctx: TaskContext,
13
items: Vec<Item>,
14
) -> Result<ProcessedResult> {
15
let total = items.len();
16
17
for (current, item) in items.iter().enumerate() {
18
process_item(item).await?;
19
20
// Send heartbeat with progress details
21
let progress = Progress {
22
current: current + 1,
23
total,
24
percent: ((current + 1) as f64 / total as f64) * 100.0,
25
};
26
27
ctx.heartbeat_with_details(Some(progress)).await?;
28
}
29
30
Ok(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")]
2
pub async fn cancellable_task(
3
ctx: TaskContext,
4
items: Vec<Item>,
5
) -> Result<ProcessedResult> {
6
for item in items {
7
// Check for cancellation before processing
8
if ctx.is_cancelled() {
9
tracing::info!("Task cancelled, cleaning up...");
10
cleanup().await?;
11
return Err(anyhow::anyhow!("Task cancelled"));
12
}
13
14
process_item(item).await?;
15
}
16
17
Ok(ProcessedResult::success())
18
}
19
20
// Using cancellation token with tokio::select
21
#[task(name = "long_wait_task")]
22
pub async fn long_wait_task(
23
ctx: TaskContext,
24
duration_secs: u64,
25
) -> Result<String> {
26
let work = async {
27
tokio::time::sleep(Duration::from_secs(duration_secs)).await;
28
Ok("Work completed".to_string())
29
};
30
31
tokio::select! {
32
result = work => result,
33
_ = ctx.cancellation_token().cancelled() => {
34
Err(anyhow::anyhow!("Task was cancelled"))
35
}
36
}
37
}

Next Steps