Documentation
¶
Overview ¶
Package activity provides concurrent-safe activity and alert tracking for the subflux UI status indicator.
Index ¶
- Constants
- type Alert
- type AlertKind
- type AlertLevel
- type AlertLog
- func (al *AlertLog) AddAlert(source, message string, kind AlertKind, level AlertLevel, ttl time.Duration)
- func (al *AlertLog) Dismiss(id int) bool
- func (al *AlertLog) DismissBySource(source string)
- func (al *AlertLog) Record(source, message string)
- func (al *AlertLog) RecordInfo(message string)
- func (al *AlertLog) RecordPersistent(source, message string)
- func (al *AlertLog) RecordWarn(source, message string)
- func (al *AlertLog) SetOnDismiss(fn func(Alert))
- func (al *AlertLog) SetOnRaise(fn func(Alert))
- func (al *AlertLog) VisibleAlerts() []Alert
- type Entry
- type Log
- func (a *Log) ActiveScan(scope ScanScope) (string, bool)
- func (a *Log) Cancel(id string) bool
- func (a *Log) Dismiss(id string)
- func (a *Log) End(id string)
- func (a *Log) Entries() []Entry
- func (a *Log) Fail(id string)
- func (a *Log) FinishCancelled(id string)
- func (a *Log) Get(id string) (Entry, bool)
- func (a *Log) IsCancelled(id string) bool
- func (a *Log) Progress(id string, current, total int, detail string)
- func (a *Log) PruneCompleted(maxAge time.Duration)
- func (a *Log) SetOnRemove(fn func(Entry))
- func (a *Log) SetOnUpsert(fn func(Entry))
- func (a *Log) SetQueued(id string, queued bool)
- func (a *Log) Start(action, detail string, source Source) string
- func (a *Log) StartQueued(action, detail string, source Source) string
- func (a *Log) StartScan(action, detail string, source Source, scope ScanScope, role auth.Role) (id string, existing bool)
- type Outcome
- type ScanKind
- type ScanScope
- type Source
- type StopRegistry
- type StopResult
Constants ¶
const DefaultPruneAge = 15 * time.Minute
DefaultPruneAge is the duration after which completed activities are pruned.
const TransientAlertTTL = 1 * time.Hour
TransientAlertTTL is the default TTL for transient alerts.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Alert ¶
type Alert struct {
Time time.Time `json:"time"`
Level AlertLevel `json:"level"` // "error", "warn", "info"
Message string `json:"message"`
Source string `json:"source"`
Kind AlertKind `json:"kind"`
TTL time.Duration `json:"-"` // per-alert TTL override; 0 = use default
ID int `json:"id"`
Dismissed bool `json:"dismissed"`
}
Alert represents an actionable error or informational message.
type AlertLevel ¶
type AlertLevel string
AlertLevel is a typed string for alert severity levels.
const ( LevelError AlertLevel = "error" LevelWarn AlertLevel = "warn" LevelInfo AlertLevel = "info" )
Alert level constants.
type AlertLog ¶
type AlertLog struct {
// contains filtered or unexported fields
}
AlertLog tracks actionable errors for the UI.
func NewAlertLog ¶
NewAlertLog creates an AlertLog with the given max capacity.
func (*AlertLog) AddAlert ¶
func (al *AlertLog) AddAlert(source, message string, kind AlertKind, level AlertLevel, ttl time.Duration)
AddAlert appends an alert with the given level and optional TTL override.
func (*AlertLog) DismissBySource ¶
DismissBySource dismisses all undismissed persistent alerts from a source.
func (*AlertLog) RecordInfo ¶
RecordInfo adds a short-lived informational alert for scan results.
func (*AlertLog) RecordPersistent ¶
RecordPersistent adds a persistent error that requires manual dismissal.
func (*AlertLog) RecordWarn ¶
RecordWarn adds a transient warning alert.
func (*AlertLog) SetOnDismiss ¶ added in v0.5.0
SetOnDismiss installs the observer called with the dismissed alert snapshot for every dismissal — the by-id endpoint and DismissBySource alike — fired AFTER the lock is released, like SetOnRaise.
func (*AlertLog) SetOnRaise ¶ added in v0.5.0
SetOnRaise installs the observer called with the recorded alert snapshot after every raise — a new alert and a refreshed persistent one alike. The hook is fired AFTER the log's lock is released (the AlertLog cannot import the events bus; the server injects the publisher here). TTL expiry and cap eviction fire nothing: both stay reconcile-only on the client.
func (*AlertLog) VisibleAlerts ¶
VisibleAlerts returns a copy of non-dismissed, non-expired alerts. It is the only read path: the log never hands out its internal slice, and its mutex stays private (tests that need the raw state live in this package).
type Entry ¶
type Entry struct {
StartedAt time.Time `json:"started_at"`
EndedAt *time.Time `json:"ended_at,omitempty"`
ID string `json:"id"`
Action string `json:"action"`
Detail string `json:"detail"`
Source Source `json:"source"` // "scheduled" or "manual"
Kind ScanKind `json:"kind,omitempty"`
MediaType subflux.MediaType `json:"media_type,omitempty"`
RequiredRole auth.Role `json:"required_role,omitempty"`
MediaID int `json:"media_id,omitempty"`
Season int `json:"season,omitempty"`
Episode int `json:"episode,omitempty"`
Current int `json:"current,omitempty"`
Total int `json:"total,omitempty"`
Done bool `json:"done"`
Queued bool `json:"queued,omitempty"`
Cancelled bool `json:"cancelled,omitempty"`
Failed bool `json:"failed,omitempty"`
Cancellable bool `json:"cancellable,omitempty"`
}
Entry represents an ongoing or recent action.
Scan entries additionally carry their structured scope (Kind, MediaType, MediaID, Season, Episode) and the role required to cancel them (RequiredRole: user for per-item scans, admin for full scans). Cancellable is a serialization-time flag merged from the StopRegistry by the activity GET handler; it is never persisted on the stored entry.
type Log ¶
type Log struct {
// contains filtered or unexported fields
}
Log tracks recent actions for the UI status indicator.
func (*Log) ActiveScan ¶ added in v0.1.148
ActiveScan returns the ID of the live (not done, not cancelled) scan entry matching scope, if any. It is the read-only half of StartScan's same-scope idempotency: endpoints guarding a start by other means (the full-scan CompareAndSwap flag) use it to answer a duplicate start with the RUNNING scan's id instead of a conflict.
func (*Log) Cancel ¶
Cancel marks a queued activity as cancelled. Returns true if found and cancelled.
func (*Log) Entries ¶
Entries returns a snapshot of all entries (for serialization). Each entry is deep-copied (see snapshotEntry): callers may mutate the result freely.
func (*Log) FinishCancelled ¶ added in v0.1.148
FinishCancelled marks an activity as TERMINALLY cancelled: Done=true, Cancelled=true, EndedAt set. This is the terminal state a user-stopped scan reaches — unlike the queued-dismiss Cancel flag alone, the entry stops rendering as running and becomes prunable.
func (*Log) Get ¶ added in v0.1.148
Get returns a snapshot copy of the entry with the given ID. The copy is deep where it matters: mutating it — including through its EndedAt pointer — never touches the log's internal state (see snapshotEntry).
func (*Log) IsCancelled ¶
IsCancelled checks if an activity has been cancelled.
func (*Log) PruneCompleted ¶
PruneCompleted removes completed activities older than maxAge. The prune POLICY lives here; the 60s ticker goroutine driving it is the server's (runActivityPrune), and it is the ONE owner of pruning — the activity GET no longer prunes on read.
func (*Log) SetOnRemove ¶ added in v0.5.0
SetOnRemove installs the observer called once per entry removed from the log — dismiss, prune, and cap eviction alike — with the under-lock entry snapshot, fired AFTER the lock is released (removals are collected under the lock). Like SetOnUpsert, the hook may re-enter the log.
func (*Log) SetOnUpsert ¶ added in v0.5.0
SetOnUpsert installs the observer called with the post-mutation entry snapshot after every entry mutation (start, queue flip, progress, terminal transition, queued-cancel). The hook is fired AFTER the log's lock is released, so it may safely re-enter the log; the Log cannot import the events bus, which is why the server injects the publisher here.
func (*Log) StartQueued ¶ added in v0.5.0
StartQueued records a new activity BORN in the queued state and returns its ID: one upsert carrying Queued=true, where a Start followed by SetQueued would publish a running-looking snapshot first. Sync jobs enter here; the admission hook flips them running via SetQueued(id, false).
func (*Log) StartScan ¶ added in v0.1.148
func (a *Log) StartScan(action, detail string, source Source, scope ScanScope, role auth.Role, ) (id string, existing bool)
StartScan records a new scan activity carrying its structured scope and the role required to cancel it. Idempotent same-scope start: when an active (not done, not cancelled) entry with the same scope already exists, its ID is returned with existing=true and no new entry is created — the find-and-create pair runs under one lock so two concurrent same-scope starts cannot both create an entry.
type Outcome ¶ added in v0.1.148
type Outcome string
Outcome is the four-valued terminal outcome of a background scan runner. It replaces the former activityOK bool: a user-requested stop (cancelled) and process shutdown must never collapse into one state, and a cancelled scan must not end as success.
type ScanKind ¶ added in v0.1.148
type ScanKind string
ScanKind identifies which scan endpoint family a scan activity belongs to. Together with the media fields it forms the structured scan scope carried on activity entries (background-scans S12): the UI reconstructs running scans per scope from these fields instead of parsing human Action/Detail strings.
type ScanScope ¶ added in v0.1.148
type ScanScope struct {
Kind ScanKind
MediaType subflux.MediaType
MediaID int
Season int
Episode int
}
ScanScope is the structured identity of a scan: which endpoint family started it and which media it covers. Zero fields mean "not applicable" (e.g. a full scan has only Kind). It is a parameter/matching struct; the fields are stored flat on the Entry for serialization.
type Source ¶ added in v0.4.0
type Source string
Source is a typed string for activity entry source values.
type StopRegistry ¶ added in v0.1.148
type StopRegistry struct {
// contains filtered or unexported fields
}
StopRegistry tracks the live stop callbacks of running background scans, keyed by activity ID. The zero value is ready to use.
func (*StopRegistry) Cancellable ¶ added in v0.1.148
func (r *StopRegistry) Cancellable(id string) bool
Cancellable reports whether a live stop registration exists for id — the serialization-time source of the activity DTO's cancellable flag.
func (*StopRegistry) RegisterStop ¶ added in v0.1.148
func (r *StopRegistry) RegisterStop(id string, stop func()) (unregister func())
RegisterStop stores the stop callback for a running scan and returns the matching unregister func. The registration MUST be released on every terminal transition (end, fail, cancelled) or failed scans leak registrations and keep reporting cancellable; callers release via defer so every outcome path (including panics) unregisters. Unregister is idempotent.
func (*StopRegistry) RequestStop ¶ added in v0.1.148
func (r *StopRegistry) RequestStop(id string) StopResult
RequestStop asks the scan registered under id to stop gracefully. The first request invokes the stop callback AFTER releasing the registry lock (a callback must never run under any mutex) and returns StopRequested; repeated requests are idempotent (StopAlreadyStopping, callback not re-invoked). An id without a live registration — never registered, or already released by a terminal transition (the cancel-vs-end race resolves here as a no-op) — returns StopNotFound.
type StopResult ¶ added in v0.1.148
type StopResult int
StopResult is the outcome of a stop request against the registry.
const ( StopRequested StopResult = iota StopAlreadyStopping StopNotFound )
Stop request outcomes. The registry reports only these three: every registration is stoppable, so "not cancellable" is not a registry state — the composing endpoint derives it by mapping StopNotFound plus an existing entry onto 409 (see the default branch of handleCancelActivity).