Documentation
¶
Overview ¶
Package jobs implements a durable, append-only JSONL ledger for tracking `--wait` invocations across vers-cli runs (F14 Phase 1: journaling only).
Phase 1 ships journaling: every `--wait` command appends a "submitted" entry when it dispatches the API call, and a "complete" or "failed" entry when the handler returns. Resumption of in-flight jobs is intentionally out of scope (Phase 2).
Writes are best-effort: a write or directory failure must NOT cause the invoking command to fail. Callers should ignore the error returned from Submit/Complete/Fail in normal flow (or log it to stderr at most).
Index ¶
- Constants
- func Append(e Entry) error
- func Complete(id, resultID string) error
- func Dir() (string, error)
- func Fail(id string, err error) error
- func ParseDuration(s string) (time.Duration, error)
- func Path() (string, error)
- func SetDir(dir string)
- func Submit(s Submission) (string, error)
- type Entry
- type PruneOptions
- type PruneResult
- type Submission
Constants ¶
const ( StatusSubmitted = "submitted" StatusComplete = "complete" StatusFailed = "failed" )
Status values for ledger entries.
Variables ¶
This section is empty.
Functions ¶
func Append ¶
Append writes a single entry as one JSON line to the ledger file. The directory is created if missing.
func Complete ¶
Complete appends a terminal "complete" entry referencing an existing id. If id is empty (e.g. Submit failed), Complete is a no-op.
func Dir ¶
Dir returns the resolved ledger directory.
Precedence: explicit override (SetDir) > VERS_JOBS_DIR env > $HOME/.vers.
func Fail ¶
Fail appends a terminal "failed" entry. If id is empty, Fail is a no-op. A nil err is recorded as an empty error string but still marked failed.
func ParseDuration ¶
ParseDuration accepts the small set we surface to users: "7d", "24h", "30m", etc. Anything time.ParseDuration accepts is also accepted; the special "Nd" suffix converts to N*24h.
func SetDir ¶
func SetDir(dir string)
SetDir overrides the directory the ledger is stored in for the current process. Pass "" to clear the override (env var / default re-applies). Intended for tests.
func Submit ¶
func Submit(s Submission) (string, error)
Submit appends a new "submitted" entry and returns the assigned job id. On any I/O failure it returns an empty string and a non-nil error; the caller should treat that as best-effort and continue regardless.
Types ¶
type Entry ¶
type Entry struct {
ID string `json:"id"`
Kind string `json:"kind"`
Command string `json:"command"`
Args []string `json:"args"`
StartedAt time.Time `json:"started_at"`
CompletedAt *time.Time `json:"completed_at,omitempty"`
DurationMs *int64 `json:"duration_ms,omitempty"`
Status string `json:"status"`
ResultID string `json:"result_id,omitempty"`
Error string `json:"error,omitempty"`
}
Entry is a single ledger record. Each line in the JSONL file is one Entry. Entries with the same ID represent state transitions of the same job; the latest line wins when collapsing for reads.
type PruneOptions ¶
type PruneOptions struct {
OlderThan time.Duration // entries with StartedAt older than now-OlderThan are removed
All bool // when true, removes everything regardless of OlderThan
DryRun bool // when true, no file is written
Now time.Time // optional clock override; zero value uses time.Now().UTC()
}
PruneOptions configures Prune.
type PruneResult ¶
PruneResult summarises a prune call.
func Prune ¶
func Prune(opts PruneOptions) (PruneResult, error)
Prune removes ledger entries by age (or all of them) and returns counts. In DryRun mode the ledger file is untouched.
Pruning operates on the latest-state-per-id collapse: a job is kept iff its latest entry is younger than the cutoff. When kept, all of its entries are preserved to maintain the audit trail.
type Submission ¶
Submission is the input for Submit. Args should not include the program name; Command is a short, human-readable invocation summary like "vers run --wait".
Source Files