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
- Variables
- type Job
- type Options
- type Run
- func (r *Run) Add(name string, delta int64)
- func (r *Run) Count(name string, n int64)
- func (r *Run) ID() string
- func (r *Run) List(name string) []string
- func (r *Run) Note(level, message, ref string)
- func (r *Run) Param(name string) string
- func (r *Run) Progress(phase string, done, total int64, unit string)
- func (r *Run) SetMessage(message string)
- func (r *Run) Skip(message string)
- func (r *Run) Trigger() jobsv1.JobTrigger
- type Runner
- func (r *Runner) Add(j Job) error
- func (r *Runner) CancelJobRun(_ context.Context, req *sourcev1.CancelJobRunRequest) (*sourcev1.CancelJobRunResponse, error)
- func (r *Runner) GetJob(_ context.Context, req *sourcev1.GetJobRequest) (*sourcev1.GetJobResponse, error)
- func (r *Runner) GetJobRun(_ context.Context, req *sourcev1.GetJobRunRequest) (*sourcev1.GetJobRunResponse, error)
- func (r *Runner) ListJobRuns(_ context.Context, req *sourcev1.ListJobRunsRequest) (*sourcev1.ListJobRunsResponse, error)
- func (r *Runner) ListJobs(context.Context, *sourcev1.ListJobsRequest) (*sourcev1.ListJobsResponse, error)
- func (r *Runner) RunJob(_ context.Context, req *sourcev1.RunJobRequest) (*sourcev1.RunJobResponse, error)
- func (r *Runner) SetEvery(id string, every time.Duration) error
- func (r *Runner) Start()
- func (r *Runner) Stop()
- func (r *Runner) Trigger(id string, params map[string]string) (*jobsv1.JobRunSummary, error)
- func (r *Runner) Wait(ctx context.Context, runID string) (*jobsv1.JobRun, error)
Constants ¶
const ( TypeBool = "bool" TypeInt = "int" TypeString = "string" TypeStringList = "string_list" )
Param types of jobsv1.JobParam.
const ( LevelInfo = "info" LevelWarn = "warn" LevelError = "error" )
Note levels.
Variables ¶
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) Note ¶
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) SetMessage ¶
SetMessage sets the run's one-line outcome.
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 (*Runner) CancelJobRun ¶
func (r *Runner) CancelJobRun(_ context.Context, req *sourcev1.CancelJobRunRequest) (*sourcev1.CancelJobRunResponse, error)
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 ¶
func (r *Runner) GetJob(_ context.Context, req *sourcev1.GetJobRequest) (*sourcev1.GetJobResponse, error)
GetJob answers the GetJob call.
func (*Runner) GetJobRun ¶
func (r *Runner) GetJobRun(_ context.Context, req *sourcev1.GetJobRunRequest) (*sourcev1.GetJobRunResponse, error)
GetJobRun answers the GetJobRun call.
func (*Runner) ListJobRuns ¶
func (r *Runner) ListJobRuns(_ context.Context, req *sourcev1.ListJobRunsRequest) (*sourcev1.ListJobRunsResponse, error)
ListJobRuns answers the ListJobRuns call: newest first, a page at a time.
func (*Runner) ListJobs ¶
func (r *Runner) ListJobs(context.Context, *sourcev1.ListJobsRequest) (*sourcev1.ListJobsResponse, error)
ListJobs answers the ListJobs call.
func (*Runner) RunJob ¶
func (r *Runner) RunJob(_ context.Context, req *sourcev1.RunJobRequest) (*sourcev1.RunJobResponse, error)
RunJob answers the RunJob call: it starts a run and returns at once.
func (*Runner) SetEvery ¶
SetEvery changes how often a job runs on its own; zero stops its schedule.
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".