Documentation
¶
Overview ¶
Package bridge is what the scheduler integrations share: the robfigcron, gocron, river and asynq modules beside this one, each a module of its own. It uses the standard library only, so it lives in the core module. An app does not need it; a scheduler integration of your own can.
- Watch declares a scheduler's entries as jobs, one per name, tagged with the integration and the app, and declares a job whose entry is gone again without its schedule, so it is never reported missed.
- CheckFires checks a schedule converted from a scheduler's own against the scheduler's own fire times.
- FieldText, EveryText and Zone write what a scheduler holds as the schedule text CronWatch reads.
Which jobs are this app's is told by two tags, the integration's ("robfig-cron") and the app's under it ("robfig-cron:<app>", see AppTag), so two apps sharing one store never declare each other's jobs without a schedule. That is the PHP port's rule for Laravel and Symfony (Cronwatch\Bridge\Unscheduled).
Index ¶
- Constants
- func AppName() string
- func AppTag(tag, app string) string
- func CheckFires(runs Runs, expr, zone, where, scheduler string, daily bool, now int64) error
- func EveryText(d time.Duration) string
- func FieldText(values []int, lo, hi int) string
- func FuncName(full string) (string, error)
- func NeverFires(why string) error
- func OptionsOf(def cronwatch.Definition) []cronwatch.JobOption
- func Refuse(format string, args ...any) error
- func Unscheduled(def cronwatch.Definition) []cronwatch.JobOption
- func ValidName(name string) bool
- func Zone(loc *time.Location) (string, bool)
- type Entry
- type Runs
- type ScheduleError
- type Watch
- func (w *Watch) AppTag() string
- func (w *Watch) Client() *cronwatch.Client
- func (w *Watch) Declare(entries []Entry)
- func (w *Watch) Fallback(ctx context.Context, name string, options []cronwatch.JobOption) *cronwatch.Job
- func (w *Watch) Job(name string) *cronwatch.Job
- func (w *Watch) ReportOnce(err error, where string)
- func (w *Watch) Settle()
- func (w *Watch) Tag() string
- func (w *Watch) Unschedule(ctx context.Context) ([]string, error)
Constants ¶
const SampleRuns = sampleRuns
SampleRuns is how many runs a Runs function gives after start when it is asked without an end.
Variables ¶
This section is empty.
Functions ¶
func AppName ¶
func AppName() string
AppName is the app's name for its tag: $CRONWATCH_APP_ID when set, else the name of the running executable. Two apps that share a store and run executables of the same name need CRONWATCH_APP_ID (or the integration's App option) to tell them apart; every process of one app needs the same.
func AppTag ¶
AppTag is the tag that names the app under an integration's tag: "<tag>:<app>", the app's name lowercased, with anything but letters, digits, ".", "_" and "-" made "-". A name that is empty once cleaned, or longer than 48 characters, is cut and given 8 hex characters of its MD5, so two names never share a tag. The PHP port's appTag(), character for character.
func CheckFires ¶
CheckFires refuses a cron CronWatch would not expect runs of when the scheduler makes them, with a ScheduleError naming where (the job, for the message) and scheduler (its name). expr and zone are the converted schedule, zone "" for the process's own. daily is a cron that names no day or month, which meets every clock change of one kind alike, so one of each is walked. now is the epoch milliseconds the horizon starts from.
func EveryText ¶
EveryText is an interval as CronWatch's schedule text, exact to the millisecond: "every 1h30m".
func FieldText ¶
FieldText is a cron field for a set of values from lo to hi: "*" for all of them, "*/n" for a step from lo (three values or more), else a list with runs of three or more as ranges. "" for none.
func FuncName ¶
FuncName is a job name from a function's name as the runtime writes it (runtime.FuncForPC): without its package's path ("jobs.NightlyReport"), a method value without its receiver's star and "-fm" ("jobs.Reporter.Run"). A function literal ("main.main.func1") has no stable name, since it changes when the code around it does, and is refused, as is a name CronWatch does not take.
func NeverFires ¶
NeverFires is what a Runs function returns for a schedule that never fires again.
func OptionsOf ¶
func OptionsOf(def cronwatch.Definition) []cronwatch.JobOption
OptionsOf are the job options that declare a stored definition again, in its order: schedule, timezone, grace, timeout, maxDuration, budget, failuresBeforeAlert, description, tags, and expect ("contains" as Expect, a pattern Go wrote as ExpectMatch, a custom function as one that passes every output, since the function is the other process's). Fields no option gives are left out.
func Unscheduled ¶
func Unscheduled(def cronwatch.Definition) []cronwatch.JobOption
Unscheduled is the options that declare a job again without its schedule: its description with " (no longer scheduled)", its tags, grace, timeout, maxDuration, budget and failuresBeforeAlert.
func ValidName ¶
ValidName reports whether name is a CronWatch job name: 1 to 120 letters, digits, ".", "_", ":" or "-", starting with a letter or digit.
func Zone ¶
Zone is the IANA name CronWatch reads a scheduler's zone as. The process's own zone (time.Local) is named by $TZ or where /etc/localtime points, so a check in another process reads the schedule in the same zone; "" when it cannot be named, which CronWatch reads as each process's own zone. False for a zone that is not an IANA zone.
Types ¶
type Entry ¶
type Entry struct {
// Name is the job's name.
Name string
// Where names the entry in messages: `robfig/cron entry 3 (jobs.Nightly)`.
Where string
// Schedule and Timezone are the scheduler's schedule as CronWatch reads
// it, "" for none.
Schedule, Timezone string
// Problem is why an entry with a schedule of its own has none here: it
// is reported once, and the job watched without a schedule.
Problem error
// Defaults are the integration's options for every job, applied before
// the schedule, as the SDK spreads a client's defaults first.
Defaults []cronwatch.JobOption
// Options are the job options the app gave this entry, applied after
// the schedule, so a Schedule among them replaces the scheduler's.
Options []cronwatch.JobOption
}
Entry is one job a scheduler runs, as an integration reads it.
type Runs ¶
Runs is a scheduler's own runs, from its own code: the one at or before start and every one after it up to the first past end, or SampleRuns of them after that first one when end is nil. Epoch milliseconds, ascending. An error from NeverFires says the schedule never fires again.
type ScheduleError ¶
type ScheduleError struct{ Message string }
ScheduleError is a scheduler's schedule that cannot be read, or cannot be converted exactly: the job is watched without a schedule, and the error reported once.
func (*ScheduleError) Error ¶
func (e *ScheduleError) Error() string
type Watch ¶
type Watch struct {
// contains filtered or unexported fields
}
Watch is what an integration keeps for one scheduler: the jobs it declared, by name, and the problems it reported. Safe for use by many goroutines at once.
func NewWatch ¶
NewWatch is a watch for one scheduler: tag is the integration's ("robfig-cron"), app the app's name for its tag ("" for AppName()), and scheduler how messages name the scheduler ("robfig/cron").
func (*Watch) Declare ¶
Declare declares every entry the scheduler has now, one job per name, and declares again without its schedule a job this watch declared whose entries are all gone. Several entries of one name on different schedules are one job without a schedule, reported once. Each job is tagged with the integration's tag and the app's. A declaration that has not changed is left alone; one the client refuses is reported, as is each entry's Problem, once.
func (*Watch) Fallback ¶
func (w *Watch) Fallback(ctx context.Context, name string, options []cronwatch.JobOption) *cronwatch.Job
Fallback is the job a run in this process belongs to when this process has not declared it from a scheduler of its own (a worker whose app schedules the job in another process): declared again from the definition the store holds, when that is this app's (tagged with its app tag), so the schedule another process stored is kept, else with options and this watch's tags. Declared once per name in this process; nil, with the reason reported, when the client refuses it or the store cannot be read (the run then goes unrecorded, and the next one asks again), since a declaration made without the stored one would overwrite its schedule. A job Declare has declared meanwhile is Declare's.
func (*Watch) ReportOnce ¶
ReportOnce hands err to the client's error handler the first time this process sees its message for that where.
func (*Watch) Settle ¶
func (w *Watch) Settle()
Settle waits until what Declare declared has been written to the store, for tests and a clean exit.
func (*Watch) Unschedule ¶
Unschedule declares again without its schedule every job of this app's (tagged with its app tag) that the store holds with a schedule and this process has not declared: a scheduler entry taken out since the job was declared, by this process or an earlier one, so it is never reported missed and a missed alert already open closes. Call it just before a check. A process that never declared an entry of this scheduler leaves every job alone. Returns the names declared again.
Source Files