status

package
v0.10.0-dev.43 Latest Latest
Warning

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

Go to latest
Published: Nov 9, 2026 License: AGPL-3.0 Imports: 18 Imported by: 0

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

View Source
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.

View Source
const MaxAlertSource = 512

MaxAlertSource bounds a source's bytes.

Variables

View Source
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.

View Source
var DefaultLimits = JobLimits{PerOwner: 1_000, Total: 10_000}

DefaultLimits are the bounds Begin passes.

View Source
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.

func OwnerOf

func OwnerOf(userID int64, bypass bool) int64

OwnerOf is the one mapping from a principal to Job.Owner: BypassOwner for the bypass principal, else its user ID.

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.

const (
	OK Health = iota + 1
	Degraded
	Disabled
)

The provider states; the zero Health is none of them.

func (Health) MarshalText

func (h Health) MarshalText() ([]byte, error)

MarshalText writes the health's snake_case name; a value no constant names is an error.

func (*Health) UnmarshalText

func (h *Health) UnmarshalText(b []byte) error

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

func (id JobID) MarshalText() ([]byte, error)

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

func (id *JobID) UnmarshalText(b []byte) error

UnmarshalText reads 32 lowercase hex digits, refusing every other text.

type JobKey

type JobKey struct {
	Key         string
	Fingerprint [32]byte
}

JobKey is an Idempotency-Key as its owner sent it; the owner is Job.Owner.

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.

const (
	Scan Kind = iota + 1
	Import
	ItemScan
	Download
	Sync
	Backup
)

The job kinds; the zero Kind is none of them.

func (Kind) MarshalText

func (k Kind) MarshalText() ([]byte, error)

MarshalText writes the kind's snake_case name; a value no constant names is an error.

func (Kind) String

func (k Kind) String() string

String is k's text form, or "kind(<n>)" for a value no constant names.

func (*Kind) UnmarshalText

func (k *Kind) UnmarshalText(b []byte) error

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.

const (
	None Outcome = iota
	Succeeded
	Failed
	Cancelled
	Partial
	Interrupted
)

The outcomes.

func (Outcome) MarshalText

func (o Outcome) MarshalText() ([]byte, error)

MarshalText writes the outcome's snake_case name, None as "none"; a value no constant names is an error.

func (Outcome) String

func (o Outcome) String() string

String is o's text form, or "outcome(<n>)" for a value no constant names.

func (*Outcome) UnmarshalText

func (o *Outcome) UnmarshalText(b []byte) error

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

type ProviderState struct {
	Until  time.Time
	ID     string
	Reason string
	Health Health
}

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.

const (
	Queued State = iota + 1
	Running
	Done
)

The job states; the zero State is none of them.

func (State) MarshalText

func (st State) MarshalText() ([]byte, error)

MarshalText writes the state's snake_case name; a value no constant names is an error.

func (State) String

func (st State) String() string

String is st's text form, or "state(<n>)" for a value no constant names.

func (*State) UnmarshalText

func (st *State) UnmarshalText(b []byte) error

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

func New(ctx context.Context, p Persister) (*Store, error)

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

func (s *Store) Begin(ctx context.Context, job Job, stop func()) (_ Job, replayed bool, _ error)

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

func (s *Store) Cancel(id JobID) error

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) Get

func (s *Store) Get(ctx context.Context, id JobID) (Job, bool, error)

Get answers the live job, then the stored record.

func (*Store) Keyed

func (s *Store) Keyed(ctx context.Context, owner int64, k JobKey) (Job, bool, error)

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

func (s *Store) Run(ctx context.Context) error

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) Snapshot

func (s *Store) Snapshot() (snap Snapshot, seq uint64)

Snapshot answers the store's state and the sequence number it was read at.

func (*Store) Update

func (s *Store) Update(id JobID, fn func(*Job))

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.

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.

Jump to

Keyboard shortcuts

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