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
- Variables
- func Folder(state string) string
- func NewID(now time.Time) string
- func ValidID(id string) bool
- type Artifact
- type Effect
- type Item
- type Problem
- type Record
- type Run
- func (r *Run) Again(nclyVersion string, tools map[string]string) error
- func (r *Run) ArtifactDir() string
- func (r *Run) Begin(item, step int) error
- func (r *Run) Close()
- func (r *Run) Complete(item, step int, artifacts []Artifact, evidence any) error
- func (r *Run) Create(rec Record) error
- func (r *Run) Effect() contract.Effect
- func (r *Run) End(item, step int, status StepStatus, p contract.Problem, run Status) error
- func (r *Run) File() string
- func (r *Run) Publish(name string, data []byte) (Artifact, error)
- type Status
- type Step
- type StepStatus
- type Store
- func (s Store) Active(id string) (bool, error)
- func (s Store) ArtifactDir(id string) string
- func (s Store) File(id string) string
- func (s Store) IDs() ([]string, error)
- func (s Store) Lock(id string) string
- func (s Store) Open(ctx context.Context, id string) (*Run, error)
- func (s Store) Read(id string) (*Record, error)
- func (s Store) View(id string) (*Record, map[string]any, error)
- type UnreadableError
Constants ¶
const FormatVersion = 1
FormatVersion is the record format that this package reads and writes.
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 ¶
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.
var ErrBusy = errors.New("another process holds the run")
ErrBusy means that another process held the run for longer than LockWait.
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 ¶
Folder returns the runs folder of a state folder, which holds one record per run and the folder of each run's artifacts.
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.
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.
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 ¶
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 ¶
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 ¶
ArtifactDir returns the folder of the run's artifacts.
func (*Run) Begin ¶
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) Complete ¶
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 ¶
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 ¶
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.
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 ¶
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 ¶
ArtifactDir returns the folder of a run's artifacts, beside its record.
func (Store) IDs ¶
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) Open ¶
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.
type UnreadableError ¶
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