Struct JobContext 

#[non_exhaustive]
pub struct JobContext {
    pub job_id: Uuid,
    pub job_type: String,
    pub attempt: u32,
    pub max_attempts: u32,
    pub auth: AuthContext,
    /* private fields */
}

Context available to job handlers.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

job_id: Uuid

Current attempt (1-based).

job_type: String

attempt: u32

max_attempts: u32

auth: AuthContext

Implementations

impl JobContext

pub fn new( job_id: Uuid, job_type: String, attempt: u32, max_attempts: u32, db_pool: PgPool, http_client: CircuitBreakerClient, ) -> Self

Create a new job context.

pub fn with_kv(self, kv: Arc<dyn KvHandle>) -> Self

Attach a KV store handle. Called by the runtime before handing the context to the handler.

pub fn with_job_dispatch(self, dispatcher: Arc<dyn JobDispatch>) -> Self

Attach a job dispatcher so dispatch_job routes through the JobDispatch trait (the only path that resolves registered job metadata).

pub fn with_workflow_dispatch( self, dispatcher: Arc<dyn WorkflowDispatch>, ) -> Self

Attach a workflow dispatcher so start_workflow routes through the WorkflowDispatch trait, which writes the active version + signature. Without this, dispatched workflows would resume as BlockedSignatureMismatch on first attempt.

pub fn kv(&self) -> Result<&dyn KvHandle>

Access the KV store.

pub fn with_saved(self, data: Value) -> Self

Create a new job context with persisted saved data.

pub fn with_auth(self, auth: AuthContext) -> Self

Set authentication context.

pub fn with_tenant_id(self, tenant_id: Uuid) -> Self

Inject a tenant ID into the auth context claims.

Merges the tenant_id claim into the existing auth context so that ctx.auth.tenant_id() returns the value for the duration of this job. Used by the executor when the job record carries a tenant ID.

pub fn with_progress(self, tx: Sender<ProgressUpdate>) -> Self

Set progress channel.

pub fn with_env_provider(self, provider: Arc<dyn EnvProvider>) -> Self

Set environment provider.

pub fn db(&self) -> ForgeDb

Get database pool.

pub fn db_conn(&self) -> DbConn<'_>

Get a DbConn for use in shared helper functions.

pub async fn conn(&self) -> Result<ForgeConn<'static>>

Acquire a connection compatible with sqlx compile-time checked macros.

pub fn http(&self) -> HttpClient

Get the HTTP client for external requests.

pub fn raw_http(&self) -> &Client

Get the raw reqwest client, bypassing circuit breaker execution.

pub fn set_http_timeout(&mut self, timeout: Option<Duration>)

pub fn progress(&self, percentage: u8, message: impl Into<String>) -> Result<()>

Report job progress.

pub async fn saved(&self) -> Value

Get all saved job data.

Returns data that was saved during job execution via save(). This data persists across retries and is accessible in compensation handlers.

pub async fn save(&self, key: &str, value: Value) -> Result<()>

Save a key-value pair to persistent job data.

Merges key into the saved data object and persists the result to the database. Saved data survives retries and is accessible in compensation handlers. Use this to store information needed for rollback (e.g., transaction IDs, resource handles, progress markers).

Read saved data back with saved().

Example

ctx.save("charge_id", json!(charge.id)).await?;
ctx.save("refund_amount", json!(amount)).await?;

pub async fn dispatch_job<T: Serialize>( &self, job_type: &str, args: &T, ) -> Result<Uuid>

Dispatch a sub-job directly.

Routes through the JobDispatch trait so registered job metadata (queue/capability, priority, retry policy) is honoured. The dispatch is non-transactional: once the parent job returns, the child remains enqueued regardless of success. Use the transactional dispatch on MutationContext for commit-dependent fan-out.

pub async fn dispatch<J: ForgeJob>(&self, args: &J::Args) -> Result<Uuid>

Type-safe dispatch: resolves the job name from the type’s ForgeJob impl and serializes the args at the call site.

pub async fn start_workflow<T: Serialize>( &self, workflow_name: &str, args: &T, ) -> Result<Uuid>

Start a workflow directly.

Routes through the WorkflowDispatch trait, which writes the active version + signature onto the run row and enqueues the $workflow_resume job. Calling raw SQL here would leave both columns blank and the executor would immediately mark the run as BlockedSignatureMismatch.

pub async fn is_cancel_requested(&self) -> Result<bool>

Check if cancellation has been requested for this job.

pub async fn check_cancelled(&self) -> Result<()>

Return an error if cancellation has been requested.

pub async fn heartbeat(&self) -> Result<()>

Send heartbeat to keep job alive (async).

pub fn is_retry(&self) -> bool

Check if this is a retry attempt.

pub fn is_last_attempt(&self) -> bool

Check if this is the last attempt.

Trait Implementations

impl EnvAccess for JobContext

fn env_provider(&self) -> &dyn EnvProvider

fn env(&self, key: &str) -> Option<String>

fn env_or(&self, key: &str, default: &str) -> String

fn env_require(&self, key: &str) -> Result<String>

fn env_parse<T: FromStr>(&self, key: &str) -> Result<T>

where T::Err: Display,

fn env_parse_or<T: FromStr>(&self, key: &str, default: T) -> Result<T>

where T::Err: Display,

Returns the default when unset; errors only if the variable is set but unparseable.

fn env_contains(&self, key: &str) -> bool

impl HandlerContext for JobContext

fn db(&self) -> ForgeDb

Database handle with automatic db.query tracing spans.

fn db_conn(&self) -> DbConn<'_>

Unified connection handle for shared helper functions.