Struct Job 

pub struct Job {
    pub job_id: Uuid,
    pub tool_name: String,
    pub params: Value,
    pub idempotency_key: Option<String>,
    pub max_retries: u32,
    pub retry_count: u32,
}

A job represents a unit of work to be executed by a ToolWorker.

Jobs encapsulate all the information needed to execute a tool, including the tool name, parameters, retry configuration, and optional idempotency key. They are the primary unit of work in the riglr job processing system.

Job Lifecycle

1. Creation - Job is created with tool name and parameters
2. Queuing - Job is submitted to a job queue for processing
3. Execution - Worker picks up job and executes the corresponding tool
4. Retry - If execution fails with a retriable error, job may be retried
5. Completion - Job succeeds or fails permanently after exhausting retries

Examples

Basic Job Creation

use riglr_core::Job;
use serde_json::json;

let job = Job::new(
    "price_checker",
    &json!({
        "symbol": "BTC",
        "currency": "USD"
    }),
    3 // max retries
)?;

println!("Job ID: {}", job.job_id);
println!("Tool: {}", job.tool_name);
println!("Can retry: {}", job.can_retry());

Idempotent Job Creation

use riglr_core::Job;
use serde_json::json;

let job = Job::new_idempotent(
    "bank_transfer",
    &json!({
        "from_account": "123",
        "to_account": "456",
        "amount": 100.00,
        "currency": "USD"
    }),
    2, // max retries
    "transfer_123_456_100_20241201" // idempotency key
)?;

assert!(job.idempotency_key.is_some());

Fields

job_id: Uuid

Unique identifier for this job instance.

Generated automatically when the job is created. This ID is used for tracking and logging purposes throughout the job’s lifecycle.

tool_name: String

Name of the tool to execute.

This must match the name of a tool registered with the ToolWorker. Tool names also influence resource pool assignment (e.g., “solana_*” tools use the “solana_rpc” resource pool).

params: Value

Parameters to pass to the tool, serialized as JSON.

These parameters will be passed to the tool’s execute method. Tools are responsible for validating and extracting the required parameters from this JSON value.

idempotency_key: Option<String>

Optional idempotency key to prevent duplicate execution.

When an idempotency key is provided and an idempotency store is configured, the worker will cache successful results. Subsequent jobs with the same idempotency key will return the cached result instead of re-executing.

Idempotency keys should be unique per logical operation and include relevant parameters to ensure uniqueness.

max_retries: u32

Maximum number of retry attempts allowed for this job.

If a tool execution fails with a retriable error, the job will be retried up to this many times. The total execution attempts will be max_retries + 1.

Only retriable failures trigger retries - permanent failures will not be retried regardless of this setting.

retry_count: u32

Current retry count for this job.

This tracks how many retry attempts have been made. It starts at 0 for new jobs and is incremented after each failed execution attempt. The job stops retrying when retry_count >= max_retries.

Implementations

impl Job

pub fn new<T: Serialize>( tool_name: impl Into<String>, params: &T, max_retries: u32, ) -> Result<Self, Error>

Create a new job without an idempotency key.

This creates a standard job that will be executed normally without result caching. If the job fails with a retriable error, it may be retried up to max_retries times.

Parameters

• tool_name - Name of the tool to execute (must match a registered tool)
• params - Parameters to pass to the tool (will be JSON-serialized)
• max_retries - Maximum number of retry attempts (0 = no retries)

Returns

• Ok(Job) - Successfully created job
• Err(serde_json::Error) - If parameters cannot be serialized to JSON

Examples

use riglr_core::Job;
use serde_json::json;

// Simple job with basic parameters
let job = Job::new(
    "weather_check",
    &json!({
        "city": "San Francisco",
        "units": "metric"
    }),
    3 // allow up to 3 retries
)?;

assert_eq!(job.tool_name, "weather_check");
assert_eq!(job.max_retries, 3);
assert_eq!(job.retry_count, 0);
assert!(job.idempotency_key.is_none());

pub fn new_idempotent<T: Serialize>( tool_name: impl Into<String>, params: &T, max_retries: u32, idempotency_key: impl Into<String>, ) -> Result<Self, Error>

Create a new job with an idempotency key for safe retry behavior.

When an idempotency store is configured, successful results for jobs with idempotency keys are cached. Subsequent jobs with the same key will return the cached result instead of re-executing the tool.

Parameters

• tool_name - Name of the tool to execute (must match a registered tool)
• params - Parameters to pass to the tool (will be JSON-serialized)
• max_retries - Maximum number of retry attempts (0 = no retries)
• idempotency_key - Unique key for this operation (should include relevant parameters)

Returns

• Ok(Job) - Successfully created job
• Err(serde_json::Error) - If parameters cannot be serialized to JSON

Examples

use riglr_core::Job;
use serde_json::json;

// Idempotent job for a financial transaction
let job = Job::new_idempotent(
    "transfer_funds",
    &json!({
        "from": "account_123",
        "to": "account_456",
        "amount": 100.50,
        "currency": "USD"
    }),
    2, // allow up to 2 retries
    "transfer_123_456_100.50_USD_20241201_001" // unique operation ID
)?;

assert_eq!(job.tool_name, "transfer_funds");
assert_eq!(job.max_retries, 2);
assert!(job.idempotency_key.is_some());

Idempotency Key Best Practices

Idempotency keys should:

• Be unique per logical operation
• Include relevant parameters that affect the result
• Include timestamp or sequence numbers for time-sensitive operations
• Be deterministic for the same logical operation

Example patterns:

• "transfer_{from}_{to}_{amount}_{currency}_{date}_{sequence}"
• "price_check_{symbol}_{currency}_{timestamp}"
• "user_action_{user_id}_{action}_{target}_{date}"

pub fn can_retry(&self) -> bool

Check if this job has retries remaining.

Returns true if the job can be retried after a failure, false if all retry attempts have been exhausted.

Returns

• true - Job can be retried (retry_count < max_retries)
• false - No retries remaining (retry_count >= max_retries)

Examples

use riglr_core::Job;
use serde_json::json;

let mut job = Job::new("test_tool", &json!({}), 2)?;

assert!(job.can_retry());  // 0 < 2, can retry
job.increment_retry();
assert!(job.can_retry());  // 1 < 2, can retry
job.increment_retry();
assert!(!job.can_retry()); // 2 >= 2, cannot retry

pub fn increment_retry(&mut self)

Increment the retry count for this job.

This should be called by the job processing system after each failed execution attempt. The retry count is used to determine whether the job can be retried again.

Examples

use riglr_core::Job;
use serde_json::json;

let mut job = Job::new("test_tool", &json!({}), 3)?;

assert_eq!(job.retry_count, 0);
job.increment_retry();
assert_eq!(job.retry_count, 1);
job.increment_retry();
assert_eq!(job.retry_count, 2);

Trait Implementations

impl Clone for Job

fn clone(&self) -> Job

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Job

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Job

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for Job

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.