Module pulls 

The record a pull keeps on disk, so a download outlives the process that started it.

One directory per pull under <data>/pulls/<id>/: the descriptor (job.json, written once), the live record (status.json, rewritten as the transfer moves), an append-only history (events.jsonl), the lock a worker holds for as long as it runs, and the control file a client writes to ask for a pause or a cancel.

Nothing here starts, signals, or waits on a process: this module owns the format and the rules, the runtime owns the worker.

The liveness rule rests on Unix advisory locks (flock), where a lock belongs to an open file description rather than to a process. Readers take a shared lock to test, so they never exclude one another; a worker takes the exclusive one.

Structs

PullEvent

One line of a job’s history.

PullJob

A pull’s descriptor: what was asked for, written once when the job is created.

PullJobDir

One pull’s directory: its descriptor, and the files around it.

PullLock

A worker’s claim on a job, held for as long as the worker runs. Dropping it releases the lock, and so does the process ending for any reason, which is what makes a lost worker detectable.

PullStatus

A pull’s live record, rewritten as the transfer moves.

PullStore

The directory of pull jobs.

Enums

PullControl

What a client asked a running worker to do.

PullError

A failure reading or writing a pull’s record.

PullEventKind

What a history line records. Progress is deliberately absent: it belongs in the rewritten status, not in a file that only grows.

PullState

Where a pull is in its life.

Constants

REGISTERING_LINE

The status line a worker writes while it registers what it fetched. The scan it names is the one stretch of a job that reads no control file, so the line doubles as the mark of a job past stopping.

START_GRACE_MS

How long a job queued with no worker is given before it counts as abandoned. A worker writes its pid as soon as it holds the job, which it does within milliseconds of starting, so this is generous rather than tuned.

Functions

take_lock

Take an exclusive lock on path, creating it if it is not there, or None when someone else holds it. The lock lives with the returned handle.