jobsvc

package
v0.0.0-...-82b03cc Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 17, 2026 License: AGPL-3.0 Imports: 13 Imported by: 0

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.

func NewService

func NewService(bunDB *bun.DB, dbSvc db.Service, n notifier.EventNotifier, rt *realtime.Publisher) Service

NewService creates a new job service. rt may be nil (realtime disabled): hint publishing through it is a nil-safe no-op.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址