Documentation
¶
Overview ¶
Package status holds what subflux is doing and what is wrong with it and its providers: jobs, alerts as levels and provider states. Every mutation bumps one sequence number and wakes every observer.
Index ¶
- Constants
- Variables
- func AlertKind(s AlertSource) (string, bool)
- func OwnerOf(userID int64, bypass bool) int64
- type Alert
- type AlertSource
- type Health
- type Job
- type JobID
- type JobKey
- type JobLimits
- type Kind
- type Outcome
- type Persister
- type ProviderState
- type Snapshot
- type State
- type Store
- func (s *Store) Begin(ctx context.Context, job Job, stop func()) (_ Job, replayed bool, _ error)
- func (s *Store) Cancel(id JobID) error
- func (s *Store) Changed() <-chan struct{}
- func (s *Store) Get(ctx context.Context, id JobID) (Job, bool, error)
- func (s *Store) Keyed(ctx context.Context, owner int64, k JobKey) (Job, bool, error)
- func (s *Store) Reconcile(source AlertSource, active bool, text string)
- func (s *Store) RetainAlerts(kind string, live []AlertSource)
- func (s *Store) Run(ctx context.Context) error
- func (s *Store) SetProvider(p ProviderState)
- func (s *Store) Snapshot() (snap Snapshot, seq uint64)
- func (s *Store) Update(id JobID, fn func(*Job))
Constants ¶
const ( // SystemOwner owns scheduled work; it is never a principal's owner. SystemOwner int64 = 0 // BypassOwner stands for the bypass principal, whose user ID is 0 and so // would read as SystemOwner. BypassOwner int64 = -1 )
The owners Job.Owner holds besides a user's ID.
const MaxAlertSource = 512
MaxAlertSource bounds a source's bytes.
Variables ¶
var ( ErrJobUnrecorded = errors.New("status: job not recorded") ErrKeyReused = errors.New("status: idempotency key reused with another request") ErrJobCapacity = errors.New("status: job record capacity reached") ErrNotCancellable = errors.New("status: job is not cancellable") ErrUnknownJob = errors.New("status: unknown job") )
The sentinels the job calls return.
var DefaultLimits = JobLimits{PerOwner: 1_000, Total: 10_000}
DefaultLimits are the bounds Begin passes.
var StartCodes = []struct { Err error Code string }{ {ErrKeyReused, "idempotency_key_reused"}, {ErrJobCapacity, "job_capacity"}, {ErrJobUnrecorded, "job_unrecorded"}, }
StartCodes pairs each sentinel Keyed and Begin return with the code api answers for it, so a job-start owner lists exactly what it can answer.
Functions ¶
func AlertKind ¶
func AlertKind(s AlertSource) (string, bool)
AlertKind is a source's kind, the bounded label its gauge carries: a fixed source's own name, or its constructor's kind. It is false for a source no constant or constructor yields.
Types ¶
type Alert ¶
type Alert struct {
Since time.Time
Source AlertSource
Text string
}
Alert is a level: present while its owner reports it active.
type AlertSource ¶
type AlertSource string
AlertSource names one alert slot. It comes from a fixed constant below or from a constructor, never from a literal.
const ( AlertConfig AlertSource = "config" AlertStore AlertSource = "store" AlertJobRecords AlertSource = "job_records" AlertBackup AlertSource = "backup" AlertAuthDisabled AlertSource = "auth_disabled" AlertAdminSocket AlertSource = "admin_socket" AlertRestartPending AlertSource = "restart_pending" AlertPendingWrites AlertSource = "pending_writes" )
The fixed sources, each its own kind.
func MediaRootAlert ¶
func MediaRootAlert(path string) AlertSource
MediaRootAlert is the source for a media root, by its path.
func MediaServerAlert ¶
func MediaServerAlert(id string) AlertSource
MediaServerAlert is the source for a media server, by its id.
func ProviderAlert ¶
func ProviderAlert(id string) AlertSource
ProviderAlert is the source for a subtitle provider, by its id.
func SourceAlert ¶
func SourceAlert(id string) AlertSource
SourceAlert is the source for a media source, by its id.
func SourceOverlapAlert ¶
func SourceOverlapAlert(id string) AlertSource
SourceOverlapAlert is the source for a media source whose roots overlap another's, by its id.
type Health ¶
type Health uint8
Health is a provider's state.
The provider states; the zero Health is none of them.
func (Health) MarshalText ¶
MarshalText writes the health's snake_case name; a value no constant names is an error.
func (*Health) UnmarshalText ¶
UnmarshalText reads a health's snake_case name, refusing every other text.
type Job ¶
type Job struct {
Started time.Time
Ended time.Time
Key *JobKey
ID JobID
Scope string
Phase string
Cause string
// Owner is the starting principal's user ID, BypassOwner for the bypass
// principal, SystemOwner only for scheduled work (OwnerOf).
Owner int64
Done, Total int
Rev uint64
Kind Kind
State State
Outcome Outcome
// Cancellable is derived by Update: a stop handle and State != Done.
Cancellable bool
}
Job is one unit of work as observers and the persister see it.
type JobID ¶
type JobID string
JobID is a job's opaque id: the 32 lowercase hex digits Begin assigns.
func (JobID) MarshalText ¶
MarshalText writes the id as is; anything but 32 lowercase hex digits is an error, so no id Begin did not assign reaches the wire.
func (*JobID) UnmarshalText ¶
UnmarshalText reads 32 lowercase hex digits, refusing every other text.
type JobLimits ¶
type JobLimits struct{ PerOwner, Total int }
JobLimits bounds stored job records. PerOwner bounds each owner, system included; Total bounds all user owners together.
type Kind ¶
type Kind uint8
Kind is what a job does.
The job kinds; the zero Kind is none of them.
func (Kind) MarshalText ¶
MarshalText writes the kind's snake_case name; a value no constant names is an error.
func (*Kind) UnmarshalText ¶
UnmarshalText reads a kind's snake_case name, refusing every other text.
type Outcome ¶
type Outcome uint8
Outcome is how a Done job ended; it is None until then.
func (Outcome) MarshalText ¶
MarshalText writes the outcome's snake_case name, None as "none"; a value no constant names is an error.
func (*Outcome) UnmarshalText ¶
UnmarshalText reads an outcome's snake_case name, refusing every other text.
type Persister ¶
type Persister interface {
// InsertJob stores a new record in one transaction. A record with the
// same (Owner, Key.Key) is returned with true when its fingerprint is
// equal and is ErrKeyReused otherwise, either winning over the bounds.
// At a full bound it first deletes the oldest ended record inside that
// bound, keyed or not (the owner's for PerOwner, any user's for Total),
// and answers ErrJobCapacity, writing nothing, only when every record
// there is unfinished. An existing ID is an error.
InsertJob(context.Context, Job, JobLimits) (Job, bool, error)
// PutJob replaces a stored record; an absent ID, or a Rev not above the
// stored one, is an error.
PutJob(context.Context, Job) error
GetJob(context.Context, JobID) (Job, bool, error)
JobByKey(ctx context.Context, owner int64, key string) (Job, bool, error)
UnfinishedJobs(context.Context) ([]Job, error)
DeleteJobsEndedBefore(context.Context, time.Time) (int, error)
}
Persister stores job records; statedb implements it.
type ProviderState ¶
ProviderState is one provider's health, until when it holds, and why.
type Snapshot ¶
type Snapshot struct {
// Jobs are the live jobs, newest started first; Alerts are ordered by
// source, Providers by id.
Jobs []Job
Alerts []Alert
Providers []ProviderState
// Boot names this process, so an observer tells a restart from a
// sequence number that went back.
Boot [16]byte
}
Snapshot is one consistent reading of the store.
type State ¶
type State uint8
State is where a job is in its life.
func (State) MarshalText ¶
MarshalText writes the state's snake_case name; a value no constant names is an error.
func (*State) UnmarshalText ¶
UnmarshalText reads a state's snake_case name, refusing every other text.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store is the process's one status store.
func New ¶
New opens the store over p, first rewriting every unfinished record as Done with Outcome Interrupted, not cancellable, so a job a crash cut short never reads back as running.
func (*Store) Begin ¶
Begin records job and makes it live: it assigns ID, Rev 1 and Queued and inserts the record before returning, so the caller runs the work only after a nil error with replayed false. A keyed resend of the same request returns the existing job, its live state while live, with replayed true. A SystemOwner job with a Key is ErrJobUnrecorded, writing nothing. ErrKeyReused and ErrJobCapacity pass through; any other failure is ErrJobUnrecorded.
func (*Store) Cancel ¶
Cancel calls a live job's stop handle; the job's own work then ends it. A Done job, or one started without a handle, is ErrNotCancellable; a job that is not live is ErrUnknownJob.
func (*Store) Changed ¶
func (s *Store) Changed() <-chan struct{}
Changed returns the current generation's channel, which the next mutation closes after bumping the sequence number. An observer re-reads Changed before each Snapshot, so every observer sees every change.
func (*Store) Keyed ¶
Keyed is the job owner started under k.Key while the persister holds its record, read as the live job when it is live. A job under that key with another fingerprint is ErrKeyReused; a failed read is ErrJobUnrecorded.
func (*Store) Reconcile ¶
func (s *Store) Reconcile(source AlertSource, active bool, text string)
Reconcile sets source's alert when active, keeping Since across a re-assert, and clears it otherwise. text is cut to one line of at most 512 bytes. A source no constructor yields is dropped with ERROR, and a raise of a retained kind outside its live set is dropped.
func (*Store) RetainAlerts ¶
func (s *Store) RetainAlerts(kind string, live []AlertSource)
RetainAlerts clears every alert of kind, a per-entity kind, whose source is not in live, and from then on Reconcile drops a raise of that kind outside live; a kind never retained accepts every source. A fixed or unknown kind, or a live source of another kind, is a programming fault: logged at ERROR, and nothing changes.
func (*Store) Run ¶
Run retries every terminal record not yet stored, with backoff from 1 s to 60 s, and deletes records ended over 24 h ago at start and hourly. It returns nil when ctx ends, after one last attempt at the unstored records.
func (*Store) SetProvider ¶
func (s *Store) SetProvider(p ProviderState)
SetProvider records p, its Reason cut as an alert's text is.
func (*Store) Update ¶
Update applies fn to a copy of the live job and keeps what callers may not change: ID, Kind, Scope, Owner, Key, Started, Rev and Cancellable, which is derived as a stop handle and State != Done. A transition to Done needs an Outcome other than None (else Failed, with ERROR), sets Ended, drops the stop handle and is final; it stores the terminal record before returning, retried by Run on failure. An unknown or Done job is left alone.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package statustest holds the contract every status.Persister meets and an in-memory reference implementation of it.
|
Package statustest holds the contract every status.Persister meets and an in-memory reference implementation of it. |