Documentation
¶
Overview ¶
Package model holds values shared by recording and storage, without either lifecycle.
Index ¶
- Variables
- func CloneJSONAttributes(attributes map[string]json.RawMessage) map[string]json.RawMessage
- func SameJSON(a, b any) bool
- func ValidateCompleted(id string, stage Stage) error
- type Actor
- type ActorTable
- type Collection
- type Snapshot
- type Stage
- type StageAttributesJSON
- type StageID
- type StageJSON
- type StageKey
- type Status
Constants ¶
This section is empty.
Variables ¶
var ErrEmptyID = errors.New("timeline: ID must not be empty")
var ErrInvalidAttribute = errors.New("timeline: attribute is not JSON serializable")
var ErrInvalidStage = errors.New("timeline: invalid stage")
Functions ¶
func CloneJSONAttributes ¶
func CloneJSONAttributes(attributes map[string]json.RawMessage) map[string]json.RawMessage
func SameJSON ¶
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 ¶
Types ¶
type Actor ¶
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.
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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) UnmarshalJSON ¶
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.
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.