jobs

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Nov 9, 2026 License: GPL-3.0 Imports: 16 Imported by: 0

Documentation

Overview

Package jobs runs the server's named background jobs (plugin sync, cleanups, update checks): on a schedule, at startup or by hand, one run at a time per job, each run recorded with its outcome, counts and notes. It follows the jobs model every Panelarr admin shares.

Index

Constants

View Source
const (
	StatusRunning   = "running"
	StatusSucceeded = "succeeded"
	StatusFailed    = "failed"
	StatusCancelled = "cancelled"
	StatusSkipped   = "skipped"
)

Run statuses.

View Source
const (
	TriggerSchedule = "schedule"
	TriggerManual   = "manual"
	TriggerStartup  = "startup"
)

Triggers.

View Source
const (
	ParamBool       = "bool"
	ParamInt        = "int"
	ParamString     = "string"
	ParamStringList = "string_list"
)

Param types.

View Source
const DefaultRetention = 100

DefaultRetention is how many runs are kept per job.

View Source
const MaxNotes = 200

MaxNotes caps the notes kept per run.

Variables

View Source
var (
	ErrNotFound       = errors.New("jobs: not found")
	ErrNotCancellable = errors.New("jobs: this job can't be cancelled")
	ErrNotRunning     = errors.New("jobs: the run has finished")
)

Errors callers map to responses.

Functions

This section is empty.

Types

type AlreadyRunningError

type AlreadyRunningError struct{ RunID uuid.UUID }

AlreadyRunningError is a manual run of a job that is running.

func (*AlreadyRunningError) Error

func (e *AlreadyRunningError) Error() string

type BadParamError

type BadParamError struct{ Name, Reason string }

BadParamError is a parameter that doesn't fit its definition.

func (*BadParamError) Error

func (e *BadParamError) Error() string

type Definition

type Definition struct {
	// ID matches ^[a-z0-9][a-z0-9._-]*$ (no ":").
	ID          string
	Name        string
	Description string
	Group       string
	// Interval between scheduled runs; 0 means by hand only.
	Interval time.Duration
	// ScheduleSource says where the schedule is configured.
	ScheduleSource string
	Params         []Param
	Cancellable    bool
	RunOnStart     bool
	Run            func(ctx context.Context, r *Run) error
}

Definition is a named job.

type Manager

type Manager struct {
	Retention int
	// contains filtered or unexported fields
}

Manager runs the jobs.

func NewManager

func NewManager(st *store.Store, hub *events.Hub, m *metrics.Metrics, log *slog.Logger) *Manager

NewManager returns a manager. hub and m may be nil.

func (*Manager) Cancel

func (m *Manager) Cancel(ctx context.Context, runID uuid.UUID) (db.JobRun, error)

Cancel stops a running run.

func (*Manager) Get

func (m *Manager) Get(ctx context.Context, id string) (View, error)

Get returns one job.

func (*Manager) GetRun

func (m *Manager) GetRun(ctx context.Context, id uuid.UUID) (db.JobRun, error)

GetRun returns a run.

func (*Manager) List

func (m *Manager) List(ctx context.Context) ([]View, error)

List returns every job.

func (*Manager) Register

func (m *Manager) Register(d Definition)

Register adds a job. Call before Start.

func (*Manager) RunNow

func (m *Manager) RunNow(ctx context.Context, jobID string, params map[string]string, by string) (db.JobRun, error)

RunNow starts a run by hand.

func (*Manager) Runs

func (m *Manager) Runs(ctx context.Context, jobID, status string, before *db.JobRun, limit int) ([]db.JobRun, error)

Runs lists a job's runs, newest first, before a cursor.

func (*Manager) Start

func (m *Manager) Start(ctx context.Context) error

Start marks runs left running by a previous process as interrupted, runs the startup jobs and schedules the rest. It returns at once; jobs run until ctx ends. Wait waits for them.

func (*Manager) Wait

func (m *Manager) Wait()

Wait blocks until every run and the scheduler have stopped.

type Note

type Note struct {
	At      time.Time `json:"at"`
	Level   string    `json:"level"`
	Message string    `json:"message"`
	Ref     string    `json:"ref,omitempty"`
}

Note is a notable event of a run.

type Param

type Param struct {
	Name        string
	Type        string
	Description string
	Required    bool
	Default     string
	Choices     []string
}

Param is a value a run accepts.

type Progress

type Progress struct {
	Phase string `json:"phase,omitempty"`
	Done  int64  `json:"done"`
	Total int64  `json:"total,omitempty"`
	Unit  string `json:"unit,omitempty"`
}

Progress is how far a run is.

type Run

type Run struct {
	ID     uuid.UUID
	JobID  string
	Params map[string]string
	// contains filtered or unexported fields
}

Run is a running job, handed to its function.

func (*Run) Count

func (r *Run) Count(name string, delta int64)

Count adds delta to a named count (e.g. "synced").

func (*Run) Note

func (r *Run) Note(level, message, ref string)

Note records a notable event; level is info, warn or error.

func (*Run) SetMessage

func (r *Run) SetMessage(msg string)

SetMessage sets the run's one-line outcome.

func (*Run) SetProgress

func (r *Run) SetProgress(p Progress)

SetProgress reports how far the run is (writes are throttled).

type View

type View struct {
	Definition
	Running      bool
	CurrentRunID uuid.UUID
	LastRun      *db.JobRun
	NextRunAt    *time.Time
}

View is a job with its live state.

Jump to

Keyboard shortcuts

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