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: Apache-2.0 Imports: 16 Imported by: 0

Documentation

Overview

Package jobs runs a plugin's background jobs and answers the job calls of the JOBS capability (ListJobs, GetJob, ListJobRuns, GetJobRun, RunJob, CancelJobRun) with the shared panelarr.jobs.v1 model.

Add jobs to a Runner, call Runner.Start to begin their schedules, and forward the plugin's job calls to the runner's methods of the same names. History is kept in memory: a plugin that restarts starts with none.

Index

Constants

View Source
const (
	TypeBool       = "bool"
	TypeInt        = "int"
	TypeString     = "string"
	TypeStringList = "string_list"
)

Param types of jobsv1.JobParam.

View Source
const (
	LevelInfo  = "info"
	LevelWarn  = "warn"
	LevelError = "error"
)

Note levels.

Variables

View Source
var IDPattern = regexp.MustCompile(`^[a-z0-9][a-z0-9._-]*$`)

IDPattern is what job IDs look like: no ':', which HTTP paths read as a custom verb (as in ":run").

Functions

This section is empty.

Types

type Job

type Job struct {
	// ID matches [IDPattern].
	ID          string
	Name        string
	Description string
	// Group is a label to group jobs by, such as "Stores".
	Group string
	// Every is how often the job runs on its own; zero means only on request.
	// [Runner.SetEvery] changes it.
	Every time.Duration
	// ScheduleSource says where the schedule is configured, e.g. a config key.
	ScheduleSource string
	// AtStart runs the job once when the runner starts.
	AtStart bool
	// Params are what a run accepts. Scheduled runs use their defaults.
	Params []*jobsv1.JobParam
	// Cancellable jobs stop when their run's context is cancelled.
	Cancellable bool
	// DisabledReason, when set, says why the job can't run now; "" means it
	// can. It's asked every time the job is shown or due, so it follows
	// changes. While it gives a reason, starting the job fails with
	// JOB_DISABLED and the schedule doesn't fire. It must not call the
	// runner.
	DisabledReason func() string
	// Run does the work. Returning an error fails the run with its message;
	// see [Run] for counts, notes, progress and skipping.
	Run func(ctx context.Context, run *Run) error
}

Job is a piece of background work.

type Options

type Options struct {
	// Keep is how many runs are kept per job, 100 by default.
	Keep int
	// RunIDPrefix starts every run ID, so a plugin that also passes on another
	// service's runs can tell them apart.
	RunIDPrefix string
	// Now is the clock, time.Now by default.
	Now func() time.Time
}

Options tune a Runner.

type Run

type Run struct {
	// contains filtered or unexported fields
}

Run is one run of a job, handed to Job.Run to report what it does.

func (*Run) Add

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

Add adds delta to a count.

func (*Run) Count

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

Count sets a count of what the run did, such as "updates".

func (*Run) ID

func (r *Run) ID() string

ID is the run's ID.

func (*Run) List

func (r *Run) List(name string) []string

List returns a string_list param's items.

func (*Run) Note

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

Note records a warning, error or notable event (at most 200 a run). ref says what it is about, such as a source ID; it may be empty.

func (*Run) Param

func (r *Run) Param(name string) string

Param returns a param's value, or its default, or "".

func (*Run) Progress

func (r *Run) Progress(phase string, done, total int64, unit string)

Progress reports how far the run is, e.g. ("Checking", 3, 10, "sources").

func (*Run) SetMessage

func (r *Run) SetMessage(message string)

SetMessage sets the run's one-line outcome.

func (*Run) Skip

func (r *Run) Skip(message string)

Skip marks the run as having nothing to do; return nil after it.

func (*Run) Trigger

func (r *Run) Trigger() jobsv1.JobTrigger

Trigger is what started the run.

type Runner

type Runner struct {
	// contains filtered or unexported fields
}

Runner keeps jobs, runs them on request and on schedule, and remembers their runs. It is safe for concurrent use.

func New

func New(opts Options) *Runner

New returns a runner without jobs.

func (*Runner) Add

func (r *Runner) Add(j Job) error

Add adds a job. Add jobs before Start.

func (*Runner) CancelJobRun

CancelJobRun answers the CancelJobRun call. The run stops when its job notices; the answer shows it as it is at that moment.

func (*Runner) GetJob

GetJob answers the GetJob call.

func (*Runner) GetJobRun

GetJobRun answers the GetJobRun call.

func (*Runner) ListJobRuns

ListJobRuns answers the ListJobRuns call: newest first, a page at a time.

func (*Runner) ListJobs

ListJobs answers the ListJobs call.

func (*Runner) RunJob

RunJob answers the RunJob call: it starts a run and returns at once.

func (*Runner) SetEvery

func (r *Runner) SetEvery(id string, every time.Duration) error

SetEvery changes how often a job runs on its own; zero stops its schedule.

func (*Runner) Start

func (r *Runner) Start()

Start begins the schedules and the AtStart runs.

func (*Runner) Stop

func (r *Runner) Stop()

Stop cancels the runs going on and the schedules, and waits for them. A run cut short this way fails with "interrupted".

func (*Runner) Trigger

func (r *Runner) Trigger(id string, params map[string]string) (*jobsv1.JobRunSummary, error)

Trigger starts a run the plugin decided on itself (JOB_TRIGGER_SYSTEM). Missing params get their defaults.

func (*Runner) Wait

func (r *Runner) Wait(ctx context.Context, runID string) (*jobsv1.JobRun, error)

Wait waits for a run to finish and returns it.

Jump to

Keyboard shortcuts

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