Struct JobContext 

pub struct JobContext {
    pub job: JobRow,
    /* private fields */
}

Context passed to worker handlers during job execution.

Provides access to the job metadata, shared state (e.g., service dependencies), callback registration, and structured progress reporting.

Fields

job: JobRow

The raw job row from the database.

Implementations

impl JobContext

pub fn is_cancelled(&self) -> bool

Check if this job’s execution has been cancelled (shutdown or deadline).

pub fn cancellation_flag(&self) -> Arc<AtomicBool>

Clone the shared cancellation flag for language bridges.

pub fn cancel(&self)

Signal cancellation for this job.

pub fn extract<T: Any + Send + Sync + Clone>(&self) -> Option<T>

Extract a shared state value by type.

State values are registered via Client::builder().state(value). Register the concrete type you want to extract:

// Register with the type you'll extract:
let deps = Arc::new(MyDeps::new());
Client::builder(pool)
    .state(deps.clone())  // stores Arc<MyDeps>
    .build()?;

// In handler — extract the same type:
let deps = ctx.extract::<Arc<MyDeps>>().unwrap();

pub fn pool(&self) -> &PgPool

Get a reference to the database pool.

pub fn queue_storage_store(&self) -> Option<Arc<QueueStorage>>

Get the active queue-storage backend for this job, if any.

pub async fn register_callback( &self, timeout: Duration, ) -> Result<CallbackGuard, AwaError>

Register a callback for this job, writing the callback_id to the database immediately.

Call this BEFORE sending the callback_id to the external system to avoid the race condition where the external system fires before the DB knows about the callback.

Returns a CallbackGuard whose id should be included in the URL or payload sent to the external system.

pub async fn register_callback_with_config( &self, timeout: Duration, config: &CallbackConfig, ) -> Result<CallbackGuard, AwaError>

Register a callback with CEL expressions for automatic resolution.

See CallbackConfig for expression semantics.

pub async fn wait_for_callback( &self, guard: CallbackGuard, ) -> Result<Value, AwaError>

Wait for an external callback to resolve, then resume with the payload.

This enables sequential callbacks: the handler can register a callback, wait for it, process the result, register another callback, wait again, and so on — all within a single handler invocation.

The handler’s async task suspends while waiting. The job transitions to waiting_external. When resume_external(callback_id, payload) is called, the job transitions back to running and this method returns the payload.

The handler holds its permit (worker slot) during the wait. For very long waits, consider whether the single-shot WaitForCallback pattern (which releases the permit) is more appropriate.

let token = ctx.register_callback(Duration::from_secs(3600)).await?;
send_to_external_system(token.id());
let payload = ctx.wait_for_callback(token).await?;
// Handler resumes here with the external system's response

pub fn set_progress(&self, percent: u8, message: &str)

Set structured progress (0-100 with message). Sync — writes to in-memory buffer.

percent is clamped to 0-100. For progress without a message, pass "".

pub fn update_metadata(&self, updates: Value) -> Result<(), AwaError>

Shallow-merge keys into progress.metadata for checkpointing. Sync.

updates must be a JSON object. Top-level keys overwrite; nested objects are replaced, not deep-merged.

pub async fn flush_progress(&self) -> Result<(), AwaError>

Force immediate flush of pending progress to DB. For critical checkpoints.

Does not return success until the progress has been durably written or the job is no longer in running state (rescued/cancelled).

pub fn progress_buffer(&self) -> Arc<Mutex<ProgressState>>

Get a clone of the shared progress state Arc (for Python bridge).