machinesnapshot

package
v0.182.1 Latest Latest
Warning

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

 Go to latest Published: Oct 5, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package machinesnapshot defines the public, privacy-safe HTTP and durable storage contract for hosted WB machine state.

Index

Constants

View Source 
const (
	// SchemaVersion is the only hosted snapshot schema this build accepts.
	SchemaVersion = 1
	// SnapshotPath is the authenticated endpoint used by the CLI and hub host.
	SnapshotPath = "/v0/workbench/machines/snapshot"
	// Collection is the authoritative durable collection for hosted records.
	Collection = "workbench_machine_snapshots"

	MaxWorktrees      = 5000
	MaxRepositories   = 5000
	MaxIdentityLength = 128
	MaxRepositoryLen  = 256
	MaxTaskLength     = 256
	MaxTaskSummaryLen = 240
	MaxBranchLength   = 512
	MaxStatusLength   = 64
	MaxOwnerLength    = 256
	MaxAttentionLen   = 1024
	MaxPRURLLength    = 2048
	MaxRemoteStoreLen = 2048
	MaxAgents         = 200
	MaxAgentTextLen   = 200
	MaxCPUCount       = 65536

	AttentionOwnerInactive      = "owner session is no longer active"
	AttentionSupersessionReview = "supersession evidence requires review"
	AttentionAbsorptionReview   = "absorption evidence requires review"
	AttentionReviewRequired     = "worktree requires attention"
)

Variables

View Source 
var (
	ErrInvalidSnapshot  = errors.New("invalid hosted machine snapshot")
	ErrStaleSnapshot    = errors.New("hosted machine snapshot is older than the current snapshot")
	ErrSnapshotConflict = errors.New("hosted machine snapshot conflicts at the same published time")
)

Functions

func NormalizeAttentionReason 

func NormalizeAttentionReason(needsAttention bool, value string) string

NormalizeAttentionReason maps local free-form diagnostics onto the hosted allowlist so paths and command output never cross the wire.

func SortPublished 

func SortPublished(snapshots []PublishedSnapshot)

SortStored gives stable responses without exposing a persistence ordering.

func ValidateIdentity 

func ValidateIdentity(value string) error

ValidateIdentity applies the hosted login and machine identifier contract.

Types

type Agent added in v0.175.0 

type Agent struct {
	Kind       string    `json:"kind" firestore:"kind"`
	SessionID  string    `json:"session_id,omitempty" firestore:"session_id,omitempty"`
	RunID      string    `json:"run_id,omitempty" firestore:"run_id,omitempty"`
	Runtime    string    `json:"runtime,omitempty" firestore:"runtime,omitempty"`
	Model      string    `json:"model,omitempty" firestore:"model,omitempty"`
	State      string    `json:"state" firestore:"state"`
	Activity   string    `json:"activity,omitempty" firestore:"activity,omitempty"`
	Task       string    `json:"task,omitempty" firestore:"task,omitempty"`
	Repository string    `json:"repository,omitempty" firestore:"repository,omitempty"`
	StartedAt  time.Time `json:"started_at,omitzero" firestore:"started_at,omitempty"`
}

Agent is one agent of the machine: the closed set of fields of the optional agents list, with no path, command line or free text.

type ListResponse 

type ListResponse struct {
	Snapshots []PublishedSnapshot `json:"snapshots"`
}

ListResponse is the authenticated, privacy-safe response consumed by WB.

type Metrics added in v0.175.0 

type Metrics struct {
	CPUPercent       *float64  `json:"cpu_percent,omitempty" firestore:"cpu_percent,omitempty"`
	Load1            *float64  `json:"load1,omitempty" firestore:"load1,omitempty"`
	MemoryUsedBytes  *uint64   `json:"memory_used_bytes,omitempty" firestore:"memory_used_bytes,omitempty"`
	MemoryTotalBytes *uint64   `json:"memory_total_bytes,omitempty" firestore:"memory_total_bytes,omitempty"`
	DiskFreeBytes    *uint64   `json:"disk_free_bytes,omitempty" firestore:"disk_free_bytes,omitempty"`
	DiskTotalBytes   *uint64   `json:"disk_total_bytes,omitempty" firestore:"disk_total_bytes,omitempty"`
	SampledAt        time.Time `json:"sampled_at" firestore:"sampled_at"`
}

Metrics is the latest machine sample.

type PublishedSnapshot 

type PublishedSnapshot struct {
	Snapshot   Snapshot  `json:"snapshot"`
	ReceivedAt time.Time `json:"received_at"`
}

PublishedSnapshot is the privacy-safe stored view returned to a publisher. The internal digest is deliberately omitted from the wire response.

type PullRequest 

type PullRequest struct {
	Number int    `json:"number" firestore:"number"`
	URL    string `json:"url" firestore:"url"`
	State  string `json:"state,omitempty" firestore:"state,omitempty"`
}

PullRequest is the hosted link for one worktree review.

type Receipt 

type Receipt struct {
	IdentityID  string    `json:"identity_id,omitempty"`
	MachineID   string    `json:"machine_id,omitempty"`
	Login       string    `json:"login"`
	Machine     string    `json:"machine"`
	PublishedAt time.Time `json:"published_at"`
	ReceivedAt  time.Time `json:"received_at"`
	Updated     bool      `json:"updated"`
}

Receipt is the server response to one publish attempt.

type Snapshot 

type Snapshot struct {
	SchemaVersion int        `json:"schema_version" firestore:"schema_version"`
	Login         string     `json:"login" firestore:"login"`
	Machine       string     `json:"machine" firestore:"machine"`
	PublishedAt   time.Time  `json:"published_at" firestore:"published_at"`
	LastSeenAt    time.Time  `json:"last_seen_at,omitempty" firestore:"last_seen_at,omitempty"`
	RemoteStore   string     `json:"remote_store,omitempty" firestore:"remote_store,omitempty"`
	Repositories  []string   `json:"repositories" firestore:"repositories"`
	Worktrees     []Worktree `json:"worktrees" firestore:"worktrees"`
	// The optional fields below are additive (cockpit-views#req:remote-snapshot-
	// agents-and-metrics): the hardware facts of the machine, its agents and
	// its latest metrics sample. A publisher sends them only when it opted in
	// (hardware always, agents and metrics by their own flags); an older hub
	// that refuses them answers 400 and the publisher retries without them.
	OS       string    `json:"os,omitempty" firestore:"os,omitempty"`
	Arch     string    `json:"arch,omitempty" firestore:"arch,omitempty"`
	CPUCount int       `json:"cpu_count,omitempty" firestore:"cpu_count,omitempty"`
	BootTime time.Time `json:"boot_time,omitzero" firestore:"boot_time,omitempty"`
	Agents   []Agent   `json:"agents,omitempty" firestore:"agents,omitempty"`
	// AgentsTruncated is set when the publisher had more than MaxAgents valid
	// agents and sent the first MaxAgents.
	AgentsTruncated bool     `json:"agents_truncated,omitempty" firestore:"agents_truncated,omitempty"`
	Metrics         *Metrics `json:"metrics,omitempty" firestore:"metrics,omitempty"`
}

Snapshot is the complete allowlist of machine state that may cross the hosted boundary. Repositories are canonical identities used as routing candidates, never authorization. The snapshot intentionally has no path, projects root, commit SHA, repository diagnostics, prompts, credentials, or command output.

func (Snapshot) Key 

func (snapshot Snapshot) Key() string

Key identifies a hosted machine record.

func (Snapshot) Validate 

func (snapshot Snapshot) Validate() error

Validate rejects malformed and overlarge records before they reach storage.

type SnapshotStore 

type SnapshotStore interface {
	StoreLatest(ctx context.Context, snapshot StoredSnapshot) (StoreResult, error)
	ListLatest(ctx context.Context) ([]StoredSnapshot, error)
}

SnapshotStore is the durable persistence port used by the host adapter. StoreLatest MUST atomically key records by login/machine, keep the candidate with the newest PublishedAt, reject a different payload at the same PublishedAt, and return the existing record without a write when Digest is already current. ListLatest returns at most one record for every key.

type StoreResult 

type StoreResult struct {
	Current StoredSnapshot
	Updated bool
}

StoreResult is returned by an atomic latest-snapshot replacement.

func ResolveLatest 

func ResolveLatest(current *StoredSnapshot, candidate StoredSnapshot) (StoreResult, error)

ResolveLatest is the deterministic comparison durable adapters apply inside their transaction. It makes retries idempotent and prevents delayed deliveries from replacing newer machine state.

type StoredSnapshot 

type StoredSnapshot struct {
	Snapshot   Snapshot  `json:"snapshot" firestore:"snapshot"`
	ReceivedAt time.Time `json:"received_at" firestore:"received_at"`
	Digest     string    `json:"digest" firestore:"digest"`
}

StoredSnapshot is the durable, server-stamped record. Digest identifies the exact validated payload without retaining the request bytes.

type Worktree 

type Worktree struct {
	Task            string       `json:"task" firestore:"task"`
	TaskSummary     string       `json:"task_summary,omitempty" firestore:"task_summary,omitempty"`
	Stream          string       `json:"stream,omitempty" firestore:"stream,omitempty"`
	Repository      string       `json:"repository" firestore:"repository"`
	Branch          string       `json:"branch" firestore:"branch"`
	Lifecycle       string       `json:"lifecycle,omitempty" firestore:"lifecycle,omitempty"`
	OwnerState      string       `json:"owner_status,omitempty" firestore:"owner_status,omitempty"`
	Owner           string       `json:"owner,omitempty" firestore:"owner,omitempty"`
	LastActivityAt  time.Time    `json:"last_activity_at,omitempty" firestore:"last_activity_at,omitempty"`
	NeedsAttention  bool         `json:"needs_attention,omitempty" firestore:"needs_attention,omitempty"`
	AttentionReason string       `json:"attention_reason,omitempty" firestore:"attention_reason,omitempty"`
	PullRequest     *PullRequest `json:"pull_request,omitempty" firestore:"pull_request,omitempty"`
}

Worktree is the hosted dashboard projection of one WB worktree.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.