status

package
v0.7.2 Latest Latest
Warning

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

Go to latest
Published: Nov 13, 2026 License: MIT Imports: 10 Imported by: 0

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

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

View Source
const QueueCollection = "files_queue"

QueueCollection persists the pending jobs: {id: "<kind>/<spaceId>/<fileId>", kind, sp, fid, att, next, lastErr, lim}.

Variables

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

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

type OnChange func(job Job, done bool)

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

func (q *Queue) Enqueue(ctx context.Context, kind, spaceId, fileId string) error

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

func (q *Queue) Get(ctx context.Context, kind, spaceId, fileId string) (Job, bool, error)

Get reads one pending job.

func (*Queue) Kick

func (q *Queue) Kick()

Kick wakes the worker immediately (app events, manual retry).

func (*Queue) KickJob

func (q *Queue) KickJob(ctx context.Context, kind, spaceId, fileId string) (bool, error)

KickJob makes one job due immediately (manual retry) and wakes the worker. False when no such job is pending.

func (*Queue) ListSpace

func (q *Queue) ListSpace(ctx context.Context, spaceId string) ([]Job, error)

ListSpace returns the pending jobs of one space (aggregate counts).

func (*Queue) Remove

func (q *Queue) Remove(ctx context.Context, kind, spaceId, fileId string) error

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

func (q *Queue) RemoveSpace(ctx context.Context, spaceId string) error

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

type Runner

type Runner func(ctx context.Context, job Job) error

Runner executes one job. Success removes the job; ErrLimited parks it on the slow cadence; ErrNoFileNodes parks it uncounted; any other error backs off exponentially.

Jump to

Keyboard shortcuts

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