Documentation
¶
Overview ¶
Package status is the files background-work engine (SYN-29): one persistent queue with two job kinds — drive-toward-durable (every registered row whose backup hasn't succeeded yet) and pin (full background fetches). Jobs survive restarts, retry with backoff, and report every transition so the status surface can push events.
Index ¶
- Constants
- Variables
- type Job
- type OnChange
- type Queue
- func (q *Queue) Close()
- func (q *Queue) Enqueue(ctx context.Context, kind, spaceId, fileId string) error
- func (q *Queue) EnqueueDelayed(ctx context.Context, kind, spaceId, fileId string, delay time.Duration) error
- func (q *Queue) Get(ctx context.Context, kind, spaceId, fileId string) (Job, bool, error)
- func (q *Queue) Kick()
- func (q *Queue) KickJob(ctx context.Context, kind, spaceId, fileId string) (bool, error)
- func (q *Queue) ListSpace(ctx context.Context, spaceId string) ([]Job, error)
- func (q *Queue) Remove(ctx context.Context, kind, spaceId, fileId string) error
- func (q *Queue) RemoveSpace(ctx context.Context, spaceId string) error
- func (q *Queue) Run()
- type Runner
Constants ¶
const ( KindDurable = "durable" // drive an unsigned row to a verified receipt KindPin = "pin" // fetch every block of a file into the local store )
Job kinds.
const QueueCollection = "files_queue"
QueueCollection persists the pending jobs: {id: "<kind>/<spaceId>/<fileId>", kind, sp, fid, att, next, lastErr, lim}.
Variables ¶
var ErrLimited = errors.New("filestatus: storage limit exceeded")
ErrLimited is returned by a Runner to mark a limit refusal (mapped from the broker's per-item outcome).
var ErrNoFileNodes = errors.New("filestatus: no file nodes in the network")
ErrNoFileNodes is returned by a Runner when the network lists no file nodes (a local-only network): nothing was attempted, so the job waits for nodes to appear without counting a failure.
Functions ¶
This section is empty.
Types ¶
type Job ¶
type Job struct {
Kind string
SpaceId string
FileId string
Attempts int
NextAt time.Time
LastErr string
// Limited: the last attempt was refused for storage limit. Retried
// on the slow cadence (headroom appears by quota raise / deletes),
// or immediately via Kick.
Limited bool
}
Job is one unit of pending background work.
type OnChange ¶
OnChange observes job transitions (enqueue, attempt failure, done). done=true means the job left the queue (succeeded or was removed).
type Queue ¶
type Queue struct {
// contains filtered or unexported fields
}
Queue is the persistent work queue. One per SDK.
func NewQueue ¶
func NewQueue(ctx context.Context, db anystore.DB, runner Runner, onChange OnChange) (*Queue, error)
NewQueue opens the queue over the shared files DB. Call Run to start the worker; runner and onChange must be set before Run.
func (*Queue) Close ¶
func (q *Queue) Close()
Close stops the workers and waits for the in-flight jobs.
func (*Queue) Enqueue ¶
Enqueue adds (or refreshes) a job due immediately. Re-enqueueing an existing job resets its schedule but keeps its attempt count.
func (*Queue) EnqueueDelayed ¶
func (q *Queue) EnqueueDelayed(ctx context.Context, kind, spaceId, fileId string, delay time.Duration) error
EnqueueDelayed schedules a job to first run no sooner than `delay` from now (via the same NextAt the backoff uses). Used to stagger durability takeover: a device that DOWNLOADED a non-durable file waits before uploading it, so the creator (which enqueues durability immediately) usually wins and the delayed job then no-ops on its NetworkSign re-check — avoiding two devices uploading the same file at once. The worker's periodic scan picks it up when due, so no Kick.
func (*Queue) Kick ¶
func (q *Queue) Kick()
Kick wakes the worker immediately (app events, manual retry).
func (*Queue) KickJob ¶
KickJob makes one job due immediately (manual retry) and wakes the worker. False when no such job is pending.
func (*Queue) Remove ¶
Remove drops a job (its work became unnecessary — e.g. the file was deleted) and cancels its attempt when one is running.
func (*Queue) RemoveSpace ¶
RemoveSpace drops every pending job of a space (space deletion — nothing left to drive).
func (*Queue) Run ¶
func (q *Queue) Run()
Run starts the worker loop. Persisted jobs from a previous session pick up on the first scan, and a backoff earned in that session does not carry over: the network may be back, so every job that ran before is due now and its backoff starts over from the base step. A job that never ran keeps its schedule (takeover stagger).