cron

package
v0.2.8 Latest Latest
Warning

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

Go to latest
Published: Oct 14, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package cron schedules the recurring jobs.

It replaces the TypeScript CronRunner, which was a process holding a setInterval per job. That arrangement had two properties worth losing: only one process could ever run it, because a second one would double-run every job, and a run that failed was simply gone — there was no record and no retry. Scheduling through River instead gives leader election, so any number of pods can be started and exactly one of them schedules, and it puts every run in a table with its arguments, its attempts and its errors.

What is deliberately preserved is the schedule semantics: fixed intervals aligned to wall-clock boundaries, not cron expressions.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type BoundarySchedule

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

BoundarySchedule fires on wall-clock boundaries measured from the Unix epoch.

This reproduces msUntilNextBoundary() from backend/src/cron/CronRunner.ts, and it is the reason the schedules are intervals rather than cron expressions. A `1h` job fires at the top of every UTC hour and a `1d` job at UTC midnight, without any persisted state and without drifting: the next fire time is a function of the clock alone, so restarting a pod does not shift a daily job to whenever the pod happened to come up.

The alternative — River's own PeriodicInterval — measures from when the scheduler started, which would make every deploy silently move every job.

func Every

func Every(interval time.Duration) BoundarySchedule

Every returns a schedule firing on boundaries of the given interval.

func ScheduleFor

func ScheduleFor(c jobs.Cron) (BoundarySchedule, error)

ScheduleFor resolves a cron's declared schedule string.

func (BoundarySchedule) Interval

func (s BoundarySchedule) Interval() time.Duration

Interval reports the configured interval.

func (BoundarySchedule) Next

func (s BoundarySchedule) Next(current time.Time) time.Time

Next returns the first boundary strictly after current.

Strictly after matters: called at exactly a boundary — which is precisely when it is called, having just fired — returning that same instant would schedule a job to run immediately and forever.

type Registry

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

Registry maps cron names to their implementations.

Separate from internal/jobs.Crons, which declares what exists and how often. This says what actually runs. The two are checked against each other at startup, which is how a cron that was declared but never implemented — or implemented under a misspelled name — becomes a startup error rather than a job that silently never runs.

func NewRegistry

func NewRegistry() *Registry

NewRegistry returns an empty registry.

func (*Registry) Implemented

func (r *Registry) Implemented() []string

Implemented returns the registered names, sorted.

func (*Registry) Lookup

func (r *Registry) Lookup(name string) (RunFunc, bool)

Lookup returns an implementation.

func (*Registry) MustRegister

func (r *Registry) MustRegister(name string, fn RunFunc)

MustRegister is Register for wiring that cannot meaningfully continue.

func (*Registry) PeriodicJobs

func (r *Registry) PeriodicJobs() ([]*river.PeriodicJob, error)

PeriodicJobs builds the River periodic jobs for everything registered.

func (*Registry) Register

func (r *Registry) Register(name string, fn RunFunc) error

Register adds an implementation.

Registering a name that is not declared in internal/jobs.Crons is an error: it would run on no schedule at all, which is never what was meant.

func (*Registry) Specs

func (r *Registry) Specs() ([]Spec, error)

Specs resolves every implemented cron to its schedule, in registry order.

Only implemented crons are included. Scheduling a declared-but-unimplemented one would insert a job every interval that fails every time, which fills the error log with a fact already known and retries it forever.

func (*Registry) Unimplemented

func (r *Registry) Unimplemented() []string

Unimplemented returns declared crons with no implementation, sorted.

During the port this is most of them, and surfacing it is the point: a port that quietly runs eight of thirty-two jobs looks identical from the outside to one that runs all thirty-two, right up until something is noticed missing weeks later.

type Run

type Run struct {
	Context context.Context
	Name    string
	Report  string
	Elapsed time.Duration

	// Skipped is set when the job did not run because Tranquility is offline.
	Skipped bool
	Err     error
}

Run is one completed cron run, reported for display.

func RunOnce

func RunOnce(ctx context.Context, r *Registry, name string) (run Run, runErr error)

RunOnce executes a cron immediately, outside the scheduler.

This is `cron:run`, and it deliberately bypasses River: an operator running a job by hand wants it to run now, in the foreground, with its output on their terminal — not to insert a row and hope a worker somewhere picks it up. The caller owns error and panic reporting, as it does for other commands.

type RunFunc

type RunFunc func(ctx context.Context) (string, error)

RunFunc executes one scheduled job.

The report string is a one-line summary for the operator — "3,412 rows, 2 systems changed hands" — not a log line. It ends up on the job row, so a run that did nothing and a run that did a great deal are distinguishable after the fact rather than only while someone is watching.

type Spec

type Spec struct {
	Name        string
	Description string
	Schedule    BoundarySchedule
	RunOnStart  bool
	RequiresTQ  bool
}

Spec is one scheduled job, resolved.

This exists as a separate step from building River's PeriodicJob because River's is opaque: its schedule and constructor are unexported, so once built there is no way to ask what it will run. Resolving to a Spec first makes the schedule inspectable — which is what `cron:list` prints and what the tests assert against — and leaves PeriodicJobs as mechanical translation.

type Worker

type Worker struct {
	river.WorkerDefaults[queue.CronArgs]

	Registry *Registry
	Redis    *redis.Client

	// OnStart is called immediately before a valid scheduled run. Optional.
	OnStart func(name string)

	// OnRun is called after each run, for logging. Optional.
	OnRun func(Run)
}

Worker runs scheduled jobs.

One worker handles every cron, dispatching on the name in the job args. See the note on queue.CronArgs for why they share a job kind.

func (*Worker) Timeout

func (w *Worker) Timeout(*river.Job[queue.CronArgs]) time.Duration

Timeout gives scheduled jobs longer than the client default.

Several crons are importers that legitimately run for many minutes — a day of killmails, a full sovereignty snapshot — and the default would kill them partway through, repeatedly, without ever completing one.

func (*Worker) Work

func (w *Worker) Work(ctx context.Context, job *river.Job[queue.CronArgs]) error

Work executes one scheduled job.

Jump to

Keyboard shortcuts

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