Documentation
¶
Overview ¶
Package jobsvc provides job queue operations for the job system.
Index ¶
Constants ¶
View Source
const ( // MaxRetryCount is the maximum number of retries allowed for a job (so 3 // attempts total: original + 2 retries). Exported so the stuck-job reaper // and the worker share a single source of truth for the cap instead of // duplicating the literal. MaxRetryCount = 2 )
Variables ¶
View Source
var ( // ErrJobNotFound is returned when a job cannot be found. ErrJobNotFound = errors.New("job not found") // ErrInvalidJobConfig is returned when a job's config payload is not a // JSON object. It is a client error, not an infrastructure failure — HTTP // callers must map it to 400, which is why it is a sentinel rather than an // anonymous fmt.Errorf that could only be matched on its message. ErrInvalidJobConfig = errors.New("invalid job config") // ErrJobAlreadyCompleted is returned when trying to cancel a completed job. ErrJobAlreadyCompleted = errors.New("job not found or already completed") // ErrExecutionNotFound is returned when an execution cannot be found. ErrExecutionNotFound = errors.New("execution not found") // ErrJobNotPending is returned when trying to cancel a non-pending job. ErrJobNotPending = errors.New("job not found or not pending") // ErrMaxRetriesReached is returned when a job has reached its retry limit. ErrMaxRetriesReached = errors.New("max retries reached (3 attempts total)") // ErrJobLeaseLost is returned by CompleteRunningJob when the job is no // longer in 'running' — the stuck-job reaper (or another actor) already // transitioned it, so the worker's terminal write must be discarded rather // than clobbering the reaper's decision. ErrJobLeaseLost = errors.New("job no longer running, terminal write discarded") )
Functions ¶
This section is empty.
Types ¶
type JobOptions ¶
type JobOptions struct {
ScheduledAt *time.Time // If nil, the job will be scheduled at the current time.
BounceDelay *time.Duration // If provided, the job will be bounced after the delay if already exists.
}
JobOptions contains options for creating a job.
type ListJobsOptions ¶
type ListJobsOptions struct {
// Type filters to a single job type. Ignored when Types is set.
Type string
// Types filters to any of the given job types (WHERE type IN). Takes
// precedence over Type when non-empty.
Types []string
Status string
Limit int
Offset int
}
ListJobsOptions contains filtering options for listing jobs.
type ReapResult ¶
type ReapResult struct {
// Retried is the number of stuck jobs flipped to 'retried' with a backoff
// clone scheduled (retries remained).
Retried int
// Failed is the number of stuck jobs flipped to 'failed' with reason
// "stuck_timeout" (retry cap reached).
Failed int
}
ReapResult reports how many stuck jobs were recovered in one sweep, split by terminal outcome.
type Service ¶
type Service interface {
// CreateJob creates a new job and notifies waiting runners.
// If bounceDelay is provided:
// - If a duplicate exists, updates its scheduled_at to now + bounceDelay
// - If no duplicate, schedules the new job at now + bounceDelay
CreateJob(
ctx context.Context,
orgUID, jobType string,
config json.RawMessage,
jobOptions *JobOptions,
) (*models.Job, error)
// CreateJobAdmitted inserts a new job, due now, in the same transaction as
// admit, which runs first on that transaction and refuses the job by
// returning an error (returned as is). It never dedups against a pending
// job: admit is where the caller guards. This makes a check-then-create
// atomic when admit serializes its callers (spec 2026-10-22-04).
CreateJobAdmitted(
ctx context.Context,
orgUID, jobType string,
config json.RawMessage,
admit func(ctx context.Context, tx bun.Tx) error,
) (*models.Job, error)
// GetJob retrieves a job by UID
GetJob(ctx context.Context, uid string) (*models.Job, error)
// ListJobs lists jobs with optional filtering
ListJobs(ctx context.Context, orgUID string, opts ListJobsOptions) ([]*models.Job, error)
// CancelJob cancels a pending job (soft delete)
CancelJob(ctx context.Context, uid string) error
// IsJobDeleted reports whether the job row has been soft-deleted
// (canceled). The worker's cancellation watcher polls this while a job
// runs so a mid-run cancellation (e.g. a stopped discovery scan) aborts
// the runner instead of letting it hold its slot to completion.
IsJobDeleted(ctx context.Context, uid string) (bool, error)
// CancelPendingForIncident soft-deletes all pending jobs whose config
// references the given incident UID under the "incidentUid" key. Returns
// the number of jobs canceled. Used by ack / snooze / resolve to stop
// pending notification jobs from firing on an incident the operator has
// taken responsibility for.
//
// The incident_resolution_notice job type is deliberately exempt: it is not
// a page, it is the all-clear owed to people who already got one. Sweeping
// it would mean an ack landing between a resolution and the job's pickup
// silently cancels the "it is over" message — the exact bug the job exists
// to fix.
//
// If notBefore is non-nil, only jobs scheduled strictly before that
// timestamp are canceled — used by snooze, where notifications scheduled
// for after the snooze window are kept (they fire only if the incident
// is still open then).
CancelPendingForIncident(ctx context.Context, incidentUID string, notBefore *time.Time) (int64, error)
// ListForIncident returns EVERY job of one type that references the
// incident under the "incidentUid" config key — every status, and
// soft-deleted rows included — oldest scheduled_at first.
//
// This is what makes an interrupted escalation cycle recoverable without a
// new column: the rows ARE the record of where the cycle was when the
// acknowledgment stopped it. Their config still carries stepUid,
// repeatIndex and isLastStep, and their scheduled_at still carries when
// each rung was due.
//
// It returns the WHOLE history rather than just the canceled rows on
// purpose. One incident can accumulate several generations of the same rung
// across repeated ack → unack cycles, and deciding whether a rung may be
// resumed requires correlating them: a rung whose LATER generation already
// fired must never be resurrected from its earlier canceled one. A
// canceled-rows-only view cannot express that, so the correlation lives in
// the caller with the full history in hand.
ListForIncident(ctx context.Context, incidentUID, jobType string) ([]*models.Job, error)
// GetJobWait waits for and claims the next available job
// Uses PostgreSQL LISTEN/NOTIFY for efficient waiting
GetJobWait(ctx context.Context) (*models.Job, error)
// UpdateJobStatus updates job status to running/success/failed
UpdateJobStatus(ctx context.Context, job *models.Job, status models.JobStatus, output json.RawMessage) error
// CompleteRunningJob writes a terminal status from the worker, guarded so it
// only applies while the job is still 'running'. If the stuck-job reaper (or
// any other actor) already moved the row out of 'running', the write affects
// zero rows and ErrJobLeaseLost is returned — the worker lost its job to the
// reaper and must discard its result rather than clobber the reaper's
// decision. This is the anti-clobber guard for the lease-collision race.
CompleteRunningJob(
ctx context.Context, job *models.Job, status models.JobStatus, output json.RawMessage,
) error
// RetryJob creates a new job from a failed job
// Copies config, increments nb_tries, sets previous_job_uid
RetryJob(ctx context.Context, job *models.Job) (*models.Job, error)
// ReapStuckJobs recovers jobs stuck in 'running' whose updated_at is older
// than now-timeout (orphaned by a dead/redeployed worker, since nothing
// bumps updated_at mid-run). Each stuck job rides the existing retry chain:
// if retries remain it is marked 'retried' and a backoff clone is scheduled,
// otherwise it is marked 'failed' with reason "stuck_timeout". The
// transition re-asserts the stuck condition atomically so a concurrent
// reaper run or the original worker finishing is a no-op. Returns per-outcome
// counts.
ReapStuckJobs(ctx context.Context, timeout time.Duration) (ReapResult, error)
// CountQueueDepth returns the number of live (deleted_at IS NULL) jobs in the
// queue per status, across all organizations. Only "pending" and "running"
// statuses are returned; both keys are always present (zero-filled) so a
// drained status reports 0 rather than going stale. Used by the queue-depth
// metrics sampler.
CountQueueDepth(ctx context.Context) (map[models.JobStatus]int, error)
}
Service provides job queue operations.
Click to show internal directories.
Click to hide internal directories.