model

package
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Oct 26, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package model holds values shared by recording and storage, without either lifecycle.

Index

Constants

This section is empty.

Variables

View Source
var ErrEmptyID = errors.New("timeline: ID must not be empty")
View Source
var ErrInvalidAttribute = errors.New("timeline: attribute is not JSON serializable")
View Source
var ErrInvalidStage = errors.New("timeline: invalid stage")

Functions

func CloneJSONAttributes

func CloneJSONAttributes(attributes map[string]json.RawMessage) map[string]json.RawMessage

func SameJSON

func SameJSON(a, b any) bool

SQL JSON types may normalize whitespace and object key order. Compare decoded JSON with Number so retries neither conflict on formatting nor round large ints.

func ValidateCompleted

func ValidateCompleted(id string, stage Stage) error

Types

type Actor

type Actor struct {
	ID   string `json:"id,omitempty"`
	Name string `json:"name,omitempty"`
}

Actor identifies the executor, not the requesting user. The zero value is the default executor for single-process recording. When provided, ID takes precedence over Name.

func (Actor) Key added in v0.3.0

func (a Actor) Key() string

Key separates ID and name namespaces. Name is descriptive when ID exists. The empty key identifies the default executor; it is distinct from named actors.

type ActorTable

type ActorTable struct {
	Actors []Actor
	// contains filtered or unexported fields
}

func (*ActorTable) Encode

func (t *ActorTable) Encode(stage Stage) StageJSON

type Collection

type Collection struct {
	// LocalFlushed means no known pending local facts or save loss. A cached
	// read reports the current state without forcing a flush.
	LocalFlushed bool `json:"local_flushed"`
	// StoreRead means this read fetched persistent state; a cache hit is false.
	StoreRead bool `json:"store_read"`
}

Collection is deliberately scoped: neither field asserts that all distributed participants have reported. Remote crashed/unflushed producers are unknown.

type Snapshot

type Snapshot struct {
	ID          string                     `json:"id"`
	RootStageID StageID                    `json:"root_stage_id"`
	Operation   string                     `json:"operation"`
	StartedAt   time.Time                  `json:"started_at"`
	FinishedAt  time.Time                  `json:"finished_at,omitempty"`
	CapturedAt  time.Time                  `json:"captured_at"`
	Status      Status                     `json:"status"`
	Error       string                     `json:"error,omitempty"`
	Attributes  map[string]json.RawMessage `json:"attributes,omitempty"`
	Stages      []Stage                    `json:"stages,omitempty"`
	Collection  Collection                 `json:"collection"`
}

Snapshot is a detached view. Stages are ordered by start time, ID, then actor; overlapping intervals stay overlapping rather than being added together. Collection describes the observations this reader can confirm. A successful read does not prove all processes have flushed or that no late stage remains. All slices and JSON attribute values belong to this snapshot. Standard json.Marshal and json.Unmarshal persist it without a backend or a caller-defined DTO. JSON stores actors once in a payload-local table; stage actor_ref values are resolved back to full Actors when decoding. Times use time.Time JSON encoding (RFC 3339); zero FinishedAt means running.

func (Snapshot) Duration

func (s Snapshot) Duration() time.Duration

Duration returns the signed difference between the recorded boundaries, or between StartedAt and CapturedAt while unfinished. A Start observed after Finish intentionally produces a negative duration; timestamps are not clamped or reordered to infer an execution interval. An absent Start returns zero.

func (Snapshot) LatestFailedStage

func (s Snapshot) LatestFailedStage() (Stage, bool)

LatestFailedStage returns the most recently finished failed or canceled stage. Equal finish times are broken by ID, independently of snapshot slice order. It reports temporal order, not a root-cause or critical-path judgment.

func (Snapshot) MarshalJSON

func (s Snapshot) MarshalJSON() ([]byte, error)

MarshalJSON uses the same actor dictionary format as Document. Public stages remain self-contained in memory and standalone Stage JSON retains its Actor.

func (Snapshot) RunningStages

func (s Snapshot) RunningStages() []Stage

RunningStages returns all running stages in snapshot order. Concurrent stages are separate facts: the last-started stage is not necessarily the blocker.

func (Snapshot) Summary

func (s Snapshot) Summary() string

Summary returns a human-readable plain-text view of the operation and its stages in snapshot order. Repeated logical IDs include actor labels; arbitrary attributes and stage IDs are omitted. It is a display format, not a round-trip serialization or a machine-readable contract. Durations use the snapshot capture time, so repeated calls are deterministic. Operation status and collection outcomes remain independent of stage results.

func (*Snapshot) UnmarshalJSON

func (s *Snapshot) UnmarshalJSON(raw []byte) error

UnmarshalJSON resolves actor references, preserving the collection metadata. Invalid references return an error without replacing the receiver.

type Stage

type Stage struct {
	ID         StageID                    `json:"id"`
	ParentID   StageID                    `json:"parent_id"`
	Actor      Actor                      `json:"actor,omitzero"`
	Elapsed    time.Duration              `json:"elapsed_ns,omitempty"`
	Name       string                     `json:"name"`
	StartedAt  time.Time                  `json:"started_at"`
	FinishedAt time.Time                  `json:"finished_at,omitempty"`
	Status     Status                     `json:"status"`
	Error      string                     `json:"error,omitempty"`
	Attributes map[string]json.RawMessage `json:"attributes,omitempty"`
	// Code is an optional caller-defined value, independent of Status and Error.
	// Timeline records it without inferring or interpreting its meaning.
	Code string `json:"code,omitempty"`
}

Stage retains the interval and result of work or a wait. Leaf stages represent one component's execution flow; parent stages may group parallel child stages. ParentID refers to a logical stage group or Snapshot.RootStageID. FinishedAt is zero while work is running.

func (Stage) Duration

func (s Stage) Duration(capturedAt time.Time) time.Duration

Duration measures a finished interval, or a running interval at capturedAt.

func (Stage) Key added in v0.3.0

func (s Stage) Key() StageKey

func (*Stage) UnmarshalJSON

func (s *Stage) UnmarshalJSON(raw []byte) error

type StageAttributesJSON

type StageAttributesJSON struct {
	LegacyAttributes map[string]json.RawMessage `json:"fields"`
	// contains filtered or unexported fields
}

func (StageAttributesJSON) Stage

func (s StageAttributesJSON) Stage() Stage

type StageID

type StageID string

StageID identifies a logical stage. Begin generates a UUID by default; multiple actors may contribute separate states under a caller-supplied shared ID.

func RootID

func RootID(id string) StageID

type StageJSON

type StageJSON struct {
	LegacyAttributes map[string]json.RawMessage `json:"fields,omitempty"`
	ID               StageID                    `json:"id"`
	ParentID         StageID                    `json:"parent_id"`
	ActorRef         uint64                     `json:"actor_ref,omitempty"`
	Elapsed          time.Duration              `json:"elapsed_ns,omitempty"`
	Name             string                     `json:"name"`
	StartedAt        time.Time                  `json:"started_at"`
	FinishedAt       time.Time                  `json:"finished_at,omitempty"`
	Status           Status                     `json:"status"`
	Error            string                     `json:"error,omitempty"`
	Code             string                     `json:"code,omitempty"`
	Attributes       map[string]json.RawMessage `json:"attributes,omitempty"`
}

References exist only in a complete encoded document. Updates and public stages retain full Actor values so independent writers never merge local refs. Keep the wire stage explicit: embedding Stage here would also emit its actor.

func (StageJSON) Decode

func (s StageJSON) Decode(actors []Actor) (Stage, error)

type StageKey added in v0.3.0

type StageKey struct {
	ID    StageID
	Actor string
}

StageKey identifies one actor's contribution to a logical stage.

type Status

type Status string
const (
	Unknown   Status = "unknown"
	Running   Status = "running"
	Succeeded Status = "succeeded"
	Failed    Status = "failed"
	Canceled  Status = "canceled"
)

Jump to

Keyboard shortcuts

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