Interface: JobQueue
Defined in: packages/workflow-engine/src/persistence/interface.ts:1031
Properties
fairnessGroupBy?
readonlyoptionalfairnessGroupBy?:string|null
Defined in: packages/workflow-engine/src/persistence/interface.ts:1038
The dotted groupBy path this queue's fairness cap reads, or null when
fairness is off (or undefined when unsupported). Read by
createSpillingJobTransport so a spilled payload still carries its group
key.
Methods
adoptWorkerId()?
optionaladoptWorkerId(workerId):string
Defined in: packages/workflow-engine/src/persistence/interface.ts:1181
Optional. Offer a host's workerId to the queue so it is the id
written to job_queue.workerId. A queue explicitly configured with
its own worker id keeps it. Returns the id the queue will stamp,
whichever way it went, so the caller can warn on a mismatch.
Parameters
workerId
string
Returns
string
cancelByRun()
cancelByRun(
workflowRunId):Promise<number>
Defined in: packages/workflow-engine/src/persistence/interface.ts:1158
Cancel all pending/suspended jobs for a workflow run. Returns count of cancelled jobs.
Parameters
workflowRunId
string
Returns
Promise<number>
complete()
complete(
jobId,fence?):Promise<JobAckOutcome>
Defined in: packages/workflow-engine/src/persistence/interface.ts:1081
Mark job as completed.
Passing a fence conditions the write on the job still being the RUNNING
attempt with that startedAt; omitting it keeps the previous unconditional
behaviour and always returns "acknowledged". Note that the fenced form is
the recommended one and that the unfenced form exists for transports that
cannot carry the stamp.
Parameters
jobId
string
fence?
Returns
Promise<JobAckOutcome>
defer()?
optionaldefer(jobId,nextPollAt,reason,fence?):Promise<JobAckOutcome>
Defined in: packages/workflow-engine/src/persistence/interface.ts:1110
Return a claimed job to PENDING with a later nextPollAt WITHOUT counting
the claim as an attempt (the dequeue incremented attempt; this undoes it).
fail(id, err, true) is the wrong shape for work a host declines rather
than fails: declining is not a failed attempt, and a condition that lasts
for a whole deploy — a run pinned to a version this build does not
present — exhausts the three-attempt budget in about fifteen seconds and
takes the job row terminal.
Optional: a transport that does not implement it falls back to fail with retry, which is correct but bounded by the budget.
Parameters
jobId
string
nextPollAt
Date
reason
string
fence?
Returns
Promise<JobAckOutcome>
deleteByRunAndStages()
deleteByRunAndStages(
workflowRunId,stageIds):Promise<number>
Defined in: packages/workflow-engine/src/persistence/interface.ts:1062
Remove every job row for the given stages of a run, whatever their status. Returns the number of rows removed.
Called by run.rerunFrom for the stage records it deletes, so a
rerun does not leave the retired stages' job rows behind (including
the downstream stages it deletes without recreating, which nothing
would ever re-enqueue). An empty stageIds is a no-op.
Parameters
workflowRunId
string
stageIds
string[]
Returns
Promise<number>
dequeue()
dequeue(
options?):Promise<DequeueResult|null>
Defined in: packages/workflow-engine/src/persistence/interface.ts:1070
Atomically dequeue the next available job
Parameters
options?
Returns
Promise<DequeueResult | null>
enqueueParallel()
enqueueParallel(
jobs):Promise<string[]>
Defined in: packages/workflow-engine/src/persistence/interface.ts:1051
Enqueue multiple stages in parallel (same execution group).
Idempotent on (workflowRunId, stageId): at most one job row may
exist per stage per run, so an implementation MUST replace any row(s)
already queued for a pair it is asked to enqueue, resetting attempt,
status, workerId, lockedAt, lastError and nextPollAt. That
makes run.rerunFrom's re-enqueue and run.reapStuck's
PENDING-without-job recovery sweep safe to run over a stage that
still carries a terminal job row from a previous execution.
Parameters
jobs
Returns
Promise<string[]>
expireRunawayJobs()?
optionalexpireRunawayJobs(absoluteTimeoutMs):Promise<number>
Defined in: packages/workflow-engine/src/persistence/interface.ts:1152
Fail every RUNNING job whose claim (startedAt, stamped once and never
refreshed) is older than absoluteTimeoutMs, stamping lastError with
the LEASE_ABSOLUTE_CAP prefix; returns how many. The coarse tier of a
two-tier expiry: releaseStaleJobs is the fine-grained heartbeat
signal and is defeated by a worker that is alive but wedged, because
such a worker keeps calling touchJob. Optional — a transport that
does not implement it simply has no absolute cap.
Parameters
absoluteTimeoutMs
number
Returns
Promise<number>
fail()
fail(
jobId,error,shouldRetry?,fence?):Promise<JobAckOutcome>
Defined in: packages/workflow-engine/src/persistence/interface.ts:1128
Mark job as failed. shouldRetry defaults to false -- callers must
opt in to a retry rather than risk an unbounded retry loop for
adapters/hosts that omit the argument.
Passing a fence conditions the write on the job still being the RUNNING
attempt with that startedAt; omitting it keeps the previous unconditional
behaviour and always returns "acknowledged". Note that the fenced form is
the recommended one and that the unfenced form exists for transports that
cannot carry the stamp.
Parameters
jobId
string
error
string
shouldRetry?
boolean
fence?
Returns
Promise<JobAckOutcome>
getJobsByWorkflowRun()
getJobsByWorkflowRun(
workflowRunId):Promise<JobRecord[]>
Defined in: packages/workflow-engine/src/persistence/interface.ts:1166
Get all job rows for a workflow run (any status). Used to detect
pending/in-flight retries for a stage (so run.transition doesn't
treat a FAILED stage with a queued retry as terminal) and to find
orphaned SUSPENDED job rows or PENDING stages missing a queued job.
Parameters
workflowRunId
string
Returns
Promise<JobRecord[]>
releaseStaleJobs()
releaseStaleJobs(
staleThresholdMs?):Promise<number>
Defined in: packages/workflow-engine/src/persistence/interface.ts:1141
Release stale locks (for crashed workers). Stamps lastError with
the LEASE_HEARTBEAT_LOST prefix so an operator can tell a reclaimed
lease from a stage-level failure. The fine-grained tier of a two-tier
expiry whose coarse tier is expireRunawayJobs.
Parameters
staleThresholdMs?
number
Returns
Promise<number>
suspend()
suspend(
jobId,nextPollAt,fence?):Promise<JobAckOutcome>
Defined in: packages/workflow-engine/src/persistence/interface.ts:1092
Mark job as suspended (for async-batch).
Passing a fence conditions the write on the job still being the RUNNING
attempt with that startedAt; omitting it keeps the previous unconditional
behaviour and always returns "acknowledged". Note that the fenced form is
the recommended one and that the unfenced form exists for transports that
cannot carry the stamp.
Parameters
jobId
string
nextPollAt
Date
fence?
Returns
Promise<JobAckOutcome>
touchJob()
touchJob(
jobId):Promise<void>
Defined in: packages/workflow-engine/src/persistence/interface.ts:1173
Refresh a running job's lease (lockedAt) without changing status.
Called periodically by hosts while a long-running stage executes so
releaseStaleJobs doesn't duplicate work still in-flight.
Parameters
jobId
string
Returns
Promise<void>