statejson

Documentation

Overview

Package statejson provides shared JSON record shapes for SQLite runtime and deployment rows consumed by the CLI (logs, state) and the read-only web inspector (issue #109).

Index

• func MarkSuperseded(records []RunRecord, latestByEnv map[string]string)
• func ParseRunListLimit(raw string) int
• func ParseTraceID(dataJSON string) string
• func TraceIDFromEvents(events []state.TraceEvent) string
• type AppliedProjectRecord
  • func AppliedProject(p *state.AppliedProject) *AppliedProjectRecord
• type AppliedResourceRecord
  • func AppliedResource(r state.AppliedResource) AppliedResourceRecord
  • func AppliedResources(rows []state.AppliedResource) []AppliedResourceRecord
• type RunEventsPayload
• type RunListPayload
• type RunRecord
  • func Run(r state.Run) RunRecord
  • func Runs(runs []state.Run) []RunRecord
• type StateListPayload
• type TraceEventRecord
  • func TraceEvents(events []state.TraceEvent) []TraceEventRecord

Functions

func MarkSuperseded

func MarkSuperseded(records []RunRecord, latestByEnv map[string]string)

MarkSuperseded flags every record whose pinned deployment snapshot is not the latest one deployed for its environment (issue #207). latestByEnv maps an environment label to its latest snapshot digest; a record with an empty digest (pre-#207 run) or a matching digest is left unmarked.

func ParseRunListLimit

func ParseRunListLimit(raw string) int

ParseRunListLimit parses an optional HTTP/query limit string using state.ClampRunListLimit.

func ParseTraceID

func ParseTraceID(dataJSON string) string

ParseTraceID returns an OTel trace id from event data_json when present (issue #108).

func TraceIDFromEvents

func TraceIDFromEvents(events []state.TraceEvent) string

TraceIDFromEvents scans events for the first non-empty trace id in payloads.

Types

type AppliedProjectRecord

type AppliedProjectRecord struct {
	ProjectName string `json:"projectName"`
	Env         string `json:"env"`
	Version     string `json:"version"`
	AppliedAt   string `json:"appliedAt"`
}

AppliedProjectRecord is one applied_projects row when present in state list JSON.

func AppliedProject

func AppliedProject(p *state.AppliedProject) *AppliedProjectRecord

AppliedProject maps one applied_projects row.

type AppliedResourceRecord

type AppliedResourceRecord struct {
	Kind               string `json:"kind"`
	Name               string `json:"name"`
	Env                string `json:"env"`
	SpecHash           string `json:"specHash"`
	AppliedAt          string `json:"appliedAt"`
	NormalizedSpecJSON string `json:"normalizedSpecJson"`
}

AppliedResourceRecord is one applied_resources row (terfyn state list -o json).

func AppliedResource

func AppliedResource(r state.AppliedResource) AppliedResourceRecord

AppliedResource maps one applied_resources row.

func AppliedResources

func AppliedResources(rows []state.AppliedResource) []AppliedResourceRecord

AppliedResources maps applied resource rows.

type RunEventsPayload

type RunEventsPayload struct {
	StatePath string             `json:"statePath"`
	RunID     string             `json:"runId"`
	Workflow  string             `json:"workflow,omitempty"`
	Events    []TraceEventRecord `json:"events"`
}

RunEventsPayload is the JSON envelope for terfyn logs --run.

type RunListPayload

type RunListPayload struct {
	StatePath string      `json:"statePath"`
	Runs      []RunRecord `json:"runs"`
}

RunListPayload is the JSON envelope for terfyn logs (no filters).

type RunRecord

type RunRecord struct {
	RunID          string          `json:"runId"`
	Workflow       string          `json:"workflow"`
	Env            string          `json:"env"`
	Status         string          `json:"status"`
	StartedAt      string          `json:"startedAt"`
	FinishedAt     string          `json:"finishedAt,omitempty"`
	TotalCostUsd   float64         `json:"totalCostUsd"`
	TenantID       string          `json:"tenantId,omitempty"`
	ThreadID       string          `json:"threadId,omitempty"`
	ActorID        string          `json:"actorId,omitempty"`
	ParentRunID    string          `json:"parentRunId,omitempty"`
	RequestID      string          `json:"requestId,omitempty"`
	IdempotencyKey string          `json:"idempotencyKey,omitempty"`
	Source         string          `json:"source,omitempty"`
	Input          json.RawMessage `json:"input"`
	Output         json.RawMessage `json:"output,omitempty"`
	Error          string          `json:"error,omitempty"`
	// DeploymentSnapshotDigest is the immutable snapshot this run pinned (issue #207). Empty for
	// runs created before #207.
	DeploymentSnapshotDigest string `json:"deploymentSnapshotDigest,omitempty"`
	// Superseded is true when the run is executing a snapshot that is no longer the latest deployed
	// one for its environment — i.e. an apply has landed since the run started. Advisory.
	Superseded bool `json:"superseded,omitempty"`
}

RunRecord is one runs row (terfyn logs -o json, inspector /api/runs).

func Run

func Run(r state.Run) RunRecord

Run maps one runs row to a JSON record.

func Runs

func Runs(runs []state.Run) []RunRecord

Runs maps run rows to JSON records.

type StateListPayload

type StateListPayload struct {
	Environment    string                  `json:"environment"`
	StatePath      string                  `json:"statePath"`
	Resources      []AppliedResourceRecord `json:"resources"`
	AppliedProject *AppliedProjectRecord   `json:"appliedProject"`
}

StateListPayload is the JSON envelope for terfyn state list -o json.

type TraceEventRecord

type TraceEventRecord struct {
	Seq           int64           `json:"seq"`
	Timestamp     string          `json:"timestamp"`
	Type          string          `json:"type"`
	ActorType     string          `json:"actorType,omitempty"`
	StepID        string          `json:"stepId,omitempty"`
	TenantID      string          `json:"tenantId,omitempty"`
	ThreadID      string          `json:"threadId,omitempty"`
	ActorID       string          `json:"actorId,omitempty"`
	TimelineGroup string          `json:"timelineGroup,omitempty"`
	TimelineIcon  string          `json:"timelineIcon,omitempty"`
	SpanName      string          `json:"spanName,omitempty"`
	PrevHash      string          `json:"prevHash,omitempty"`
	Hash          string          `json:"hash,omitempty"`
	Data          json.RawMessage `json:"data"`
}

TraceEventRecord is one trace_events row (terfyn logs -o json, inspector /api/runs/{id}).

func TraceEvents

func TraceEvents(events []state.TraceEvent) []TraceEventRecord

TraceEvents maps trace rows to API/CLI JSON records.