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 AlertKindID(s AlertSource) (kind, id string, ok 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) RetainProviders(live []string)
- 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 Codes = append(slices.Clip(StartCodes), []struct { Err error Code string }{ {ErrUnknownJob, "job_unknown"}, {ErrNotCancellable, "job_not_cancellable"}, }...)
Codes is every sentinel the job calls api makes (Keyed, Begin, Get, Cancel) return, with the code api answers for it, StartCodes first. The element type is unnamed, so status never imports api's wirespec.
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 AlertKindID ¶
func AlertKindID(s AlertSource) (kind, id string, ok bool)
AlertKindID splits a source into the labels its gauge series carries: its kind, a fixed source's own name or its constructor's kind, and its id, the text after the kind's separator (the value, or the digest of a hashed source), empty for a fixed source. 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 ProviderDataAlert ¶
func ProviderDataAlert(id string) AlertSource
ProviderDataAlert is the source for the data a subtitle provider downloads, such as AnimeTosho's anime map, by the provider's 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
// Source is the media source a scan job reads, "" for every other job.
Source media.SourceID
// 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) RetainProviders ¶
RetainProviders drops every provider state whose ID is not in live, and from then on SetProvider ignores one outside live, so a removed provider's late call cannot bring it back. It signals observers once, and only when it drops a state. app calls it after each activation with the active providers' ids.
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. Once RetainProviders has run, a p whose ID it did not name is ignored.
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. |