record

package
v0.23.2 Latest Latest
Warning

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

Go to latest
Published: Oct 29, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package record keeps the records of recorded operations, as Operations in contract.md defines them: run IDs, one durable record per run, the lock that one execution holds, the transitions of its steps, and the verified artifacts that a success answers from. The domain names its steps, declares their effects, and verifies their results; this package never decides what a step does.

Write a record during cleanup with a context that cancellation does not end, such as context.WithoutCancel, within the 15 seconds of cleanup.

Index

Constants

View Source
const FormatVersion = 1

FormatVersion is the record format that this package reads and writes.

View Source
const LockWait = 250 * time.Millisecond

LockWait bounds how long an execution waits for a run that another process holds, as Record format in contract.md defines.

Variables

View Source
var Boundary func(name string)

Boundary, when set, runs at each step boundary of record support, just before and just after it persists the intent, the artifact, or the completion of a step, with the name of that boundary: before-intent, after-intent, before-artifact, after-artifact, before-completion, or after-completion. Only the test binary sets it, to kill the process there, as the boundary scenario of a recorded operation asks, or to pause it there, so a scenario sends a signal at that boundary.

View Source
var ErrBusy = errors.New("another process holds the run")

ErrBusy means that another process held the run for longer than LockWait.

View Source
var ErrChanged = errors.New("the artifact changed since its run recorded it")

ErrChanged means that an artifact no longer holds what its record says.

Functions

func Folder

func Folder(state string) string

Folder returns the runs folder of a state folder, which holds one record per run and the folder of each run's artifacts.

func NewID

func NewID(now time.Time) string

NewID generates a run ID from the UTC time and six random hexadecimal digits, such as 20261007-214501-3f9a2c. Readers never parse it.

func ValidID

func ValidID(id string) bool

ValidID reports whether id is a run ID, as Run IDs in contract.md defines it.

Types

type Artifact

type Artifact struct {
	Path      string `json:"path"`
	SizeBytes int64  `json:"size_bytes"`
	SHA256    string `json:"sha256"`
}

Artifact is a verified output of a step.

func (Artifact) Read

func (a Artifact) Read() ([]byte, error)

Read returns the content of an artifact once it matches its recorded size and SHA-256, and ErrChanged otherwise.

type Effect

type Effect string

Effect is the strongest effect that a step can make, as its domain declares it, each value more cautious than the one before it.

const (
	EffectNone          Effect = "none"
	EffectRepeatable    Effect = "repeatable"
	EffectNonRepeatable Effect = "non_repeatable"
	EffectPaid          Effect = "paid"
)

type Item

type Item struct {
	Key string `json:"key"`
	// OutputDir is the folder selected for the item's results, or nil until
	// the domain selects one.
	OutputDir *string `json:"output_dir"`
	Steps     []Step  `json:"steps"`
}

Item is one input item of a run, with its steps in execution order.

type Problem

type Problem struct {
	Code    contract.Code `json:"code"`
	Message string        `json:"message"`
	Hint    string        `json:"hint"`
}

Problem is the error of a step, as the public problem object holds it.

type Record

type Record struct {
	FormatVersion int               `json:"format_version"`
	RunID         string            `json:"run_id"`
	Path          string            `json:"path"`
	Status        Status            `json:"status"`
	StartedAt     string            `json:"started_at"`
	UpdatedAt     string            `json:"updated_at"`
	NclyVersion   string            `json:"ncly_version"`
	Attempts      int               `json:"attempts"`
	Inputs        map[string]any    `json:"inputs"`
	Resolved      map[string]any    `json:"resolved"`
	Tools         map[string]string `json:"tools"`
	Items         []Item            `json:"items"`
}

Record is the record of one run, as Record format in contract.md defines its keys.

type Run

type Run struct {
	ID     string
	Record *Record
	// contains filtered or unexported fields
}

Run is a run whose lock this process holds, with its record as read under that lock: nil when no record holds its ID.

func (*Run) Again

func (r *Run) Again(nclyVersion string, tools map[string]string) error

Again starts a new attempt of a run whose saved intents allow it, as Run IDs in contract.md defines: attempts plus one and the status running, with the release of ncly and the versions of the tools that this attempt uses, saved before any intent.

func (*Run) ArtifactDir

func (r *Run) ArtifactDir() string

ArtifactDir returns the folder of the run's artifacts.

func (*Run) Begin

func (r *Run) Begin(item, step int) error

Begin persists the intent of a step before its effect: the step turns unknown, with its start time. The effect may start only once Begin returns nil. A step that may bill stays unknown until its domain records a verified result.

func (*Run) Close

func (r *Run) Close()

Close releases the lock of the run.

func (*Run) Complete

func (r *Run) Complete(item, step int, artifacts []Artifact, evidence any) error

Complete records the verified result of a step: its artifacts, which the domain verified, and its evidence. The run completes with its last step.

func (*Run) Create

func (r *Run) Create(rec Record) error

Create writes the first record of a new run, with the status running and every step pending, before any effect. The domain fills the path, the version of ncly, the inputs, the resolved values, the tools, and the items with their steps and effects.

func (*Run) Effect

func (r *Run) Effect() contract.Effect

Effect returns the strongest effect of the steps whose intent this process persisted, which the outcome carries, so that exit 75 holds only when Retry safety in contract.md allows it.

func (*Run) End

func (r *Run) End(item, step int, status StepStatus, p contract.Problem, run Status) error

End records how an execution ended without completion: the problem of a step, the step's status, and the run's status, which the domain derives from its evidence, so a missing answer never reads as no effect.

func (*Run) File

func (r *Run) File() string

File returns the path of the run's record.

func (*Run) Publish

func (r *Run) Publish(name string, data []byte) (Artifact, error)

Publish writes data as the artifact name in the folder of the run, durably, then reads it back, and returns it with its size and SHA-256. The domain records completion only after Publish returns.

type Status

type Status string

Status is the saved status of a run.

const (
	Running     Status = "running"
	Completed   Status = "completed"
	Failed      Status = "failed"
	Interrupted Status = "interrupted"
	Unknown     Status = "unknown"
)

type Step

type Step struct {
	ID         string     `json:"id"`
	Effect     Effect     `json:"effect"`
	Status     StepStatus `json:"status"`
	StartedAt  *string    `json:"started_at"`
	FinishedAt *string    `json:"finished_at"`
	Artifacts  []Artifact `json:"artifacts"`
	// Error is the latest unsuccessful attempt's problem, or nil.
	Error *Problem `json:"error"`
	// Evidence holds what the domain needs to answer again, with its own
	// format_version, or nothing.
	Evidence json.RawMessage `json:"evidence,omitempty"`
}

Step is one step of an item.

type StepStatus

type StepStatus string

StepStatus is the saved status of a step. Pending means that its effect has not started.

const (
	StepPending   StepStatus = "pending"
	StepCompleted StepStatus = "completed"
	StepFailed    StepStatus = "failed"
	StepUnknown   StepStatus = "unknown"
)

type Store

type Store struct {
	Dir string
}

Store is a runs folder.

func (Store) Active

func (s Store) Active(id string) (bool, error)

Active reports whether a process holds the run now. It never creates the lock file and never holds the lock past its answer.

func (Store) ArtifactDir

func (s Store) ArtifactDir(id string) string

ArtifactDir returns the folder of a run's artifacts, beside its record.

func (Store) File

func (s Store) File(id string) string

File returns the path of the record of a run.

func (Store) IDs

func (s Store) IDs() ([]string, error)

IDs returns, in name order, the run ID of each record of the folder: each file <id>.json whose name holds a valid run ID. It skips any other file, such as the temporary file of a write, and a missing folder holds none.

func (Store) Lock

func (s Store) Lock(id string) string

Lock returns the path of the lock file of a run.

func (Store) Open

func (s Store) Open(ctx context.Context, id string) (*Run, error)

Open takes the lock of a run, waiting at most LockWait, then reads its record while it holds the lock, as Record format in contract.md asks. It returns ErrBusy when another process holds the run, and an UnreadableError for a record that it cannot use. The caller closes the run, which releases the lock, once it has answered.

func (Store) Read

func (s Store) Read(id string) (*Record, error)

Read reads the record of a run without its lock, for a dry run or an inspection: nil when no record holds the ID, and an UnreadableError for a record that it cannot use.

func (Store) View

func (s Store) View(id string) (*Record, map[string]any, error)

View reads a record as Read does, for an inspection, and also returns every key that its file holds, numbers as json.Number, so a key that this release does not know still shows.

type UnreadableError

type UnreadableError struct {
	File string
	Err  error
}

UnreadableError is a record that cannot be read or parsed, or that holds a format_version that this package does not support. It never counts as an absent record, so it never permits a new paid operation.

func (*UnreadableError) Error

func (e *UnreadableError) Error() string

func (*UnreadableError) Unwrap

func (e *UnreadableError) Unwrap() error

Jump to

Keyboard shortcuts

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