model

package
v0.5.5 Latest Latest
Warning

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

Go to latest
Published: Nov 2, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Index

Constants

View Source
const (
	ConnectionTestMethod   = "connection.test"
	ConnectionOpenMethod   = "connection.open"
	ConnectionTestProtocol = "connection-test-v1"
	ConnectionTestTimeout  = 2 * time.Minute
)
View Source
const (
	GPUDiscrete   = "discrete"
	GPUIntegrated = "integrated"
	GPUVirtual    = "virtual"
	GPUNPU        = "npu"
)
View Source
const LANPeerTTL = 7 * 24 * time.Hour
View Source
const MaxGPUs = 16
View Source
const MaxLANPeers = 128
View Source
const MaxNodeHealthBytes = 16 << 10
View Source
const NodeHealthInterval = 5 * time.Second
View Source
const NodeHealthTTL = 20 * time.Second
View Source
const Version = "1"

Variables

This section is empty.

Functions

func JSON

func JSON(v any) json.RawMessage

func SameJSON

func SameJSON(a, b json.RawMessage) bool

SameJSON compares decoded JSON, preserving numeric precision.

func WithDelegations

func WithDelegations(ctx context.Context, grants []Delegation) context.Context

Types

type APICall

type APICall struct {
	Target string          `json:"target"`
	Method string          `json:"method"`
	Params json.RawMessage `json:"params"`
}

type Activity

type Activity struct {
	ID            string    `json:"id"`
	Kind          string    `json:"kind"`
	Operation     string    `json:"operation"`
	Owner         string    `json:"owner"`
	Peer          string    `json:"peer,omitempty"`
	TaskID        string    `json:"taskId,omitempty"`
	State         string    `json:"state"`
	Phase         string    `json:"phase,omitempty"`
	Started       time.Time `json:"started"`
	Updated       time.Time `json:"updated"`
	Finished      time.Time `json:"finished,omitempty"`
	BytesDone     int64     `json:"bytesDone,omitempty"`
	TotalBytes    int64     `json:"totalBytes,omitempty"`
	BytesSent     int64     `json:"bytesSent,omitempty"`
	BytesReceived int64     `json:"bytesReceived,omitempty"`
}

Activity contains operational metadata, never command arguments, prompts, environment variables, credentials, results, or log contents.

type ActivityQuery

type ActivityQuery struct {
	Recent int `json:"recent,omitempty"`
}

type Artifact

type Artifact struct {
	Node    string    `json:"node"`
	ID      string    `json:"id"`
	Name    string    `json:"name"`
	Size    int64     `json:"size"`
	SHA256  string    `json:"sha256"`
	Created time.Time `json:"created"`
	Grant   string    `json:"grant,omitempty"`
}

type Capability

type Capability struct {
	Name        string          `json:"name"`
	Description string          `json:"description"`
	InputSchema json.RawMessage `json:"inputSchema"`
}

type ConnectionLatency

type ConnectionLatency struct {
	Samples      int     `json:"samples"`
	MinMillis    float64 `json:"minMillis"`
	MeanMillis   float64 `json:"meanMillis"`
	MaxMillis    float64 `json:"maxMillis"`
	JitterMillis float64 `json:"jitterMillis"`
}

type ConnectionOpenRequest

type ConnectionOpenRequest struct {
	Protocol string `json:"protocol"`
	ConnectionTestOptions
}

type ConnectionRouteCounts added in v0.2.0

type ConnectionRouteCounts struct {
	Direct  int `json:"direct"`
	TURN    int `json:"turn"`
	Relay   int `json:"relay"`
	Unknown int `json:"unknown"`
}

ConnectionRouteCounts counts usable peers once across their traffic lanes. DirectSessions retains its legacy WebRTC meaning, including TURN and unknown ICE paths.

type ConnectionTestOptions

type ConnectionTestOptions struct {
	Bytes   int64 `json:"bytes"`
	Samples int   `json:"samples"`
}

ConnectionTestOptions bounds synthetic traffic independently of network speed.

func (ConnectionTestOptions) Normalize

type ConnectionTestRequest

type ConnectionTestRequest struct {
	Target string `json:"target"`
	ConnectionTestOptions
}

type ConnectionTestResult

type ConnectionTestResult struct {
	Source      string               `json:"source"`
	SourceID    string               `json:"sourceId"`
	Target      string               `json:"target"`
	TargetID    string               `json:"targetId"`
	Transport   string               `json:"transport"`
	Route       *PeerRoute           `json:"route,omitempty"`
	StartedAt   time.Time            `json:"startedAt"`
	SetupMillis float64              `json:"setupMillis"`
	Latency     ConnectionLatency    `json:"latency"`
	Upload      ConnectionThroughput `json:"upload"`
	Download    ConnectionThroughput `json:"download"`
}

type ConnectionThroughput

type ConnectionThroughput struct {
	Bytes   int64   `json:"bytes"`
	Seconds float64 `json:"seconds"`
	Mbps    float64 `json:"mbps"`
}

type DelegatedInput

type DelegatedInput struct {
	Node     string `json:"node"`
	Path     string `json:"path"`
	TaskID   string `json:"taskId"`
	Artifact int    `json:"artifact"`
}

type Delegation

type Delegation struct {
	ID         string           `json:"id"`
	Target     string           `json:"target"`
	Alias      string           `json:"alias,omitempty"`
	Subject    string           `json:"subject"`
	Owner      string           `json:"owner"`
	Method     string           `json:"method"`
	Params     json.RawMessage  `json:"params"`
	InputsFrom []DelegatedInput `json:"inputsFrom,omitempty"`
	DeliverTo  []string         `json:"deliverTo,omitempty"`
	Expires    time.Time        `json:"expires"`
}

Delegation permits one instruction, or the lifecycle of one named task. It is bound to its destination, subject and orchestrator owner. Instruction-only destinations can also bind a direct grant to the requesting account client.

func Delegations

func Delegations(ctx context.Context) []Delegation

func (Delegation) Matches

func (d Delegation) Matches(method string, params json.RawMessage) bool

Matches checks instruction arguments, not just a method or capability name. Artifact ownership and permitted output recipients are also checked by nodes.

func (Delegation) TaskID

func (d Delegation) TaskID() string

type DiskUsage

type DiskUsage struct {
	Path       string `json:"path"`
	TotalBytes uint64 `json:"totalBytes"`
	UsedBytes  uint64 `json:"usedBytes"`
	FreeBytes  uint64 `json:"freeBytes"`
	Error      string `json:"error,omitempty"`
}

type GPUInfo added in v0.5.1

type GPUInfo struct {
	Name             string   `json:"name"`
	Vendor           string   `json:"vendor,omitempty"`
	Kind             string   `json:"kind,omitempty"`
	UsagePercent     *float64 `json:"usagePercent,omitempty"`
	MemoryTotalBytes uint64   `json:"memoryTotalBytes,omitempty"`
	MemoryUsedBytes  *uint64  `json:"memoryUsedBytes,omitempty"`
}

GPUInfo contains GPU/NPU inventory and optional readings. Shared host RAM is not reported as dedicated GPU memory. Nil readings are unknown, not zero.

func (GPUInfo) Displayable added in v0.5.1

func (g GPUInfo) Displayable() bool

Displayable excludes integrated, virtual, and unclassified adapters without discarding their inventory from the system API.

func (GPUInfo) Valid added in v0.5.1

func (g GPUInfo) Valid() bool

type GatewaySnapshot

type GatewaySnapshot struct {
	URL       string         `json:"url"`
	Software  buildinfo.Info `json:"software"`
	StartedAt time.Time      `json:"startedAt"`
	System    *SystemInfo    `json:"system,omitempty"`
}

GatewaySnapshot describes the gateway service, independently of fleet nodes.

type Input

type Input struct {
	Artifact Artifact `json:"artifact"`
	Path     string   `json:"path"`
}

type LANPeer added in v0.5.0

type LANPeer struct {
	ID         string        `json:"id"`
	Local      WakeInterface `json:"local"`
	Remote     WakeInterface `json:"remote"`
	VerifiedAt time.Time     `json:"verifiedAt"`
}

LANPeer is gateway-owned evidence that ID broadcast to this node's Local interface from Remote. It authorizes sender selection, never execution.

type LANProbe added in v0.5.0

type LANProbe struct {
	Receiver    string        `json:"receiver"`
	Sender      string        `json:"sender"`
	ReceiverNIC WakeInterface `json:"receiverInterface"`
	SenderNIC   WakeInterface `json:"senderInterface"`
	Challenge   string        `json:"challenge"`
	Port        int           `json:"port"`
}

type LANProof added in v0.5.0

type LANProof struct {
	LANProbe
	Nonce     string    `json:"nonce"`
	IssuedAt  time.Time `json:"issuedAt"`
	Signature []byte    `json:"signature"`
}

LANProof is delivered only in a UDP broadcast, not in gateway signaling. The receiver must obtain the sender's signature before reporting the edge.

func (LANProof) Message added in v0.5.0

func (p LANProof) Message() []byte

type Lease

type Lease struct {
	ID      string    `json:"id"`
	Owner   string    `json:"owner"`
	Expires time.Time `json:"expires"`
}

type MachineState

type MachineState struct {
	Revision     uint64 `json:"revision"`
	Disabled     bool   `json:"disabled"`
	Unregistered bool   `json:"unregistered"`
	Name         string `json:"name,omitempty"` // Owner-selected routing name, overriding node configuration.
}

MachineState is gateway-owned policy. Revisions are monotonic per identity.

type MachineStateProof

type MachineStateProof struct {
	PublicKey   []byte    `json:"publicKey"`
	SignedAt    time.Time `json:"signedAt"`
	Revision    uint64    `json:"revision"`
	Signature   []byte    `json:"signature"`
	InspectOnly bool      `json:"inspectOnly,omitempty"`
}

MachineStateProof permits a node to learn that it was unregistered even after its enrollment credential has been revoked. It authorizes no mutation.

func (MachineStateProof) Message

func (p MachineStateProof) Message() []byte

type Node

type Node struct {
	UserID         string            `json:"userId,omitempty"`
	ID             string            `json:"id"`
	Name           string            `json:"name"`
	PublicKey      []byte            `json:"publicKey"`
	OS             string            `json:"os"`
	Labels         map[string]string `json:"labels,omitempty"`
	Capabilities   []Capability      `json:"capabilities"`
	Online         bool              `json:"online"`
	LastSeen       time.Time         `json:"lastSeen"`
	System         *SystemInfo       `json:"system,omitempty"`
	Software       buildinfo.Info    `json:"software"`
	Disabled       bool              `json:"disabled,omitempty"`
	ControlPending bool              `json:"controlPending,omitempty"`
	Managed        bool              `json:"managed,omitempty"`
	ClientSessions bool              `json:"clientSessions,omitempty"`
	ClientOwners   bool              `json:"clientOwners,omitempty"`
	ClientOwner    string            `json:"clientOwner,omitempty"`
	PeerChannels   bool              `json:"peerChannels,omitempty"`
	TrickleICE     bool              `json:"trickleICE,omitempty"`
	WakeInterfaces []WakeInterface   `json:"wakeInterfaces,omitempty"`
	LANDiscovery   bool              `json:"lanDiscovery,omitempty"`
	LANPeers       []LANPeer         `json:"lanPeers,omitempty"`
	// RunAs is "system" for a boot-time service account and "user" for a login
	// session. Older nodes omit it.
	RunAs           string `json:"runAs,omitempty"`
	InstructionOnly bool   `json:"instructionOnly,omitempty"`
	// Hybrid pairing is assigned by the gateway from redeemed invitations.
	HybridID   string `json:"hybridId,omitempty"`
	HybridRole string `json:"hybridRole,omitempty"`
	// GatewayWake means the node accepts wake requests relayed by the gateway
	// for its fleet owner, because its allow rules let account clients call
	// network.wake. Older nodes omit it and are never selected.
	GatewayWake bool `json:"gatewayWake,omitempty"`
	// GatewayStartup accepts fixed startup-context management requests.
	GatewayStartup bool `json:"gatewayStartup,omitempty"`
	// LargePackets advertises that this receiver accepts 64 KiB carrier packets.
	LargePackets bool `json:"largePackets,omitempty"`
	// ExecutionAuthority is assigned by the gateway, never by enrollment metadata.
	ExecutionAuthority    bool `json:"executionAuthority,omitempty"`
	InstructionDelegation bool `json:"instructionDelegation,omitempty"`
	// UpdateUntil is gateway-owned display grace, not connection presence.
	UpdateUntil time.Time `json:"updateUntil,omitzero"`
}

type NodeActivitySnapshot

type NodeActivitySnapshot struct {
	ID             string            `json:"id"`
	Name           string            `json:"name"`
	OS             string            `json:"os"`
	Labels         map[string]string `json:"labels,omitempty"`
	Online         bool              `json:"online"`
	LastSeen       time.Time         `json:"lastSeen"`
	Software       buildinfo.Info    `json:"software"`
	Disabled       bool              `json:"disabled,omitempty"`
	ControlPending bool              `json:"controlPending,omitempty"`
	RunAs          string            `json:"runAs,omitempty"`
	HybridID       string            `json:"hybridId,omitempty"`
	HybridRole     string            `json:"hybridRole,omitempty"`
	// WakeVia names the online sender the console would use to wake this
	// offline machine; empty when none has a verified LAN relationship.
	WakeVia string `json:"wakeVia,omitempty"`
	// Status is ready for peer activity, summary for fresh owner health,
	// online for directory-only presence, update during managed updates,
	// offline, or unavailable.
	Status           string                 `json:"status"`
	Error            string                 `json:"error,omitempty"`
	ObservedAt       time.Time              `json:"observedAt,omitempty"`
	Active           []Activity             `json:"active"`
	Recent           []Activity             `json:"recent"`
	ActiveCount      int                    `json:"activeCount"`
	Omitted          int                    `json:"omitted,omitempty"`
	DirectSessions   int                    `json:"directSessions"`
	RelaySessions    int                    `json:"relaySessions"`
	ConnectionRoutes *ConnectionRouteCounts `json:"connectionRoutes,omitempty"`
	Tunnels          *TunnelCounts          `json:"tunnels,omitempty"`
	RetainedTunnels  *TunnelCounts          `json:"retainedTunnels,omitempty"`
	LeaseOwner       string                 `json:"leaseOwner,omitempty"`
	LeaseExpires     time.Time              `json:"leaseExpires,omitempty"`
	Leased           bool                   `json:"leased,omitempty"`
	System           *SystemInfo            `json:"system,omitempty"`
	// Work and LastActive come from owner health reports, not peer activity.
	Work       *WorkCounts `json:"work,omitempty"`
	LastActive time.Time   `json:"lastActive,omitzero"`
}

type NodeHealth

type NodeHealth struct {
	ActiveCount int        `json:"activeCount"`
	Leased      bool       `json:"leased"`
	System      SystemInfo `json:"system"`
	// Aggregate counts and times only. Older nodes omit them.
	Work             *WorkCounts            `json:"work,omitempty"`
	Tunnels          *TunnelCounts          `json:"tunnels,omitempty"`
	ConnectionRoutes *ConnectionRouteCounts `json:"connectionRoutes,omitempty"`
	LeaseExpires     time.Time              `json:"leaseExpires,omitzero"`
	LastActive       time.Time              `json:"lastActive,omitzero"`
}

NodeHealth reports aggregate machine health to the fleet owner. It contains no task records, identities, arguments, credentials, or local filesystem paths.

func (NodeHealth) Valid added in v0.5.0

func (h NodeHealth) Valid() bool

Valid rejects negative counts from a malformed report.

type NodeSelector added in v0.4.0

type NodeSelector struct {
	Labels         map[string]string `json:"labels"`
	Capability     string            `json:"capability"`
	MinMemoryBytes uint64            `json:"minMemoryBytes,omitempty"`
	MinDiskBytes   uint64            `json:"minDiskBytes,omitempty"`
	MaxCPUPercent  *float64          `json:"maxCpuPercent,omitempty"`
	RequireFresh   bool              `json:"requireFresh,omitempty"`
}

type PeerRoute added in v0.2.0

type PeerRoute struct {
	Kind            string `json:"kind"`
	LocalCandidate  string `json:"localCandidate,omitempty"`
	RemoteCandidate string `json:"remoteCandidate,omitempty"`
	Protocol        string `json:"protocol,omitempty"`
}

PeerRoute describes the selected path without exposing addresses or ICE credentials.

type PeerSession

type PeerSession struct {
	ID       string     `json:"id"`
	Peer     string     `json:"peer"`
	Lane     string     `json:"lane"`
	Mode     string     `json:"mode"`
	Outgoing int        `json:"outgoingStreams"`
	Incoming int        `json:"incomingStreams"`
	Route    *PeerRoute `json:"route,omitempty"`
}

type PoolActivityQuery

type PoolActivityQuery struct {
	Nodes  []string `json:"nodes,omitempty"`
	Recent int      `json:"recent,omitempty"`
}

type PoolActivitySnapshot

type PoolActivitySnapshot struct {
	ObservedAt time.Time              `json:"observedAt"`
	Nodes      []NodeActivitySnapshot `json:"nodes"`
	Gateway    *GatewaySnapshot       `json:"gateway,omitempty"`
	Notice     string                 `json:"notice,omitempty"`
}

type RPCError added in v0.4.0

type RPCError struct {
	Code    string `json:"code"`
	Outcome string `json:"outcome"`
	Message string `json:"message"`
	Cause   error  `json:"-"`
}

RPCError describes delivery certainty, never permission to replay a request.

func OperationError added in v0.4.0

func OperationError(err error, outcome string) *RPCError

func (*RPCError) Error added in v0.4.0

func (e *RPCError) Error() string

func (*RPCError) Unwrap added in v0.4.0

func (e *RPCError) Unwrap() error

type Request

type Request struct {
	Version string          `json:"version"`
	Method  string          `json:"method"`
	Params  json.RawMessage `json:"params,omitempty"`
	// Deadline is enforced by the receiving node, including through a relay.
	Deadline    time.Time    `json:"deadline,omitempty"`
	Delegation  string       `json:"delegation,omitempty"`
	Delegations []Delegation `json:"delegations,omitempty"`
}

type Response

type Response struct {
	Result  json.RawMessage `json:"result,omitempty"`
	Error   string          `json:"error,omitempty"`
	Code    string          `json:"code,omitempty"`
	Outcome string          `json:"outcome,omitempty"`
}

func ErrorResponse added in v0.4.0

func ErrorResponse(err error) Response

func (Response) Err added in v0.4.0

func (r Response) Err() error

type StartupReply added in v0.5.0

type StartupReply struct {
	ID     string `json:"id,omitempty"`
	Status string `json:"status"`
	Reason string `json:"reason,omitempty"`
}

StartupReply distinguishes admission from observed completion. Unknown means the instruction may have run and must not be replayed automatically.

type StartupRequest added in v0.5.0

type StartupRequest struct {
	ID   string `json:"id"`
	Mode string `json:"mode"`
}

StartupRequest is a management instruction, never a shell command or a path.

type SystemInfo

type SystemInfo struct {
	OS                   string      `json:"os"`
	Arch                 string      `json:"arch"`
	Platform             string      `json:"platform,omitempty"`
	PlatformVersion      string      `json:"platformVersion,omitempty"`
	KernelVersion        string      `json:"kernelVersion,omitempty"`
	CPUModel             string      `json:"cpuModel,omitempty"`
	LogicalCPUs          int         `json:"logicalCPUs"`
	PhysicalCPUs         int         `json:"physicalCPUs"`
	CPUUsagePercent      *float64    `json:"cpuUsagePercent,omitempty"`
	MemoryTotalBytes     uint64      `json:"memoryTotalBytes"`
	MemoryUsedBytes      uint64      `json:"memoryUsedBytes"`
	MemoryAvailableBytes uint64      `json:"memoryAvailableBytes"`
	Disks                []DiskUsage `json:"disks"`
	GPUs                 []GPUInfo   `json:"gpus,omitempty"`
	UptimeSeconds        uint64      `json:"uptimeSeconds"`
	SampledAt            time.Time   `json:"sampledAt"`
	IntervalSeconds      int         `json:"intervalSeconds"`
	Errors               []string    `json:"errors,omitempty"`
}

type Task

type Task struct {
	ID             string          `json:"id"`
	Owner          string          `json:"owner"`
	Spec           TaskSpec        `json:"spec"`
	State          string          `json:"state"`
	Phase          string          `json:"phase,omitempty"`
	Created        time.Time       `json:"created"`
	Updated        time.Time       `json:"updated"`
	Result         json.RawMessage `json:"result,omitempty"`
	ResultArtifact *Artifact       `json:"resultArtifact,omitempty"`
	Artifacts      []Artifact      `json:"artifacts,omitempty"`
	Error          string          `json:"error,omitempty"`
	// Pruned marks a terminal task whose record, logs, result, and workspace
	// were removed by retention. Its ID still cannot be resubmitted.
	Pruned bool `json:"pruned,omitempty"`
}

func (Task) Terminal

func (t Task) Terminal() bool

type TaskLogChunk

type TaskLogChunk struct {
	Data     []byte `json:"data,omitempty"`
	Offset   int64  `json:"offset"`
	Terminal bool   `json:"terminal"`
	Error    string `json:"error,omitempty"`
}

type TaskPage added in v0.4.0

type TaskPage struct {
	Tasks      []TaskSummary `json:"tasks"`
	NextCursor string        `json:"nextCursor,omitempty"`
}

type TaskSpec

type TaskSpec struct {
	ID             string          `json:"id,omitempty"`
	Capability     string          `json:"capability"`
	Args           json.RawMessage `json:"args"`
	Inputs         []Input         `json:"inputs,omitempty"`
	Outputs        []string        `json:"outputs,omitempty"`
	TimeoutSeconds int             `json:"timeoutSeconds,omitempty"`
	LeaseID        string          `json:"leaseId,omitempty"`
}

type TaskSummary added in v0.4.0

type TaskSummary struct {
	ID             string    `json:"id"`
	Capability     string    `json:"capability"`
	State          string    `json:"state"`
	Phase          string    `json:"phase,omitempty"`
	Created        time.Time `json:"created"`
	Updated        time.Time `json:"updated"`
	Error          string    `json:"error,omitempty"`
	ErrorTruncated bool      `json:"errorTruncated,omitempty"`
}

TaskSummary deliberately excludes arguments, results and artifact manifests.

func SummarizeTask added in v0.4.0

func SummarizeTask(t Task) TaskSummary

type TransportStats

type TransportStats struct {
	GatewayReconnects      int64 `json:"gatewayReconnects"`
	GatewayConnectFailures int64 `json:"gatewayConnectFailures"`
	DirectSessions         int64 `json:"directSessions"`
	RelaySessions          int64 `json:"relaySessions"`
	RelayFallbacks         int64 `json:"relayFallbacks"`
	LinkOverflows          int64 `json:"linkOverflows"`
	LookupHits             int64 `json:"lookupHits"`
	LookupMisses           int64 `json:"lookupMisses"`
}

TransportStats are cumulative peer-transport counters for local diagnostics.

type TunnelCounts

type TunnelCounts struct {
	Forward int `json:"forward"`
	Reverse int `json:"reverse"`
}

TunnelCounts separates forward connections from reverse listeners for live activity, or forward/reverse definitions when used for RetainedTunnels.

func ActiveTunnelCounts

func ActiveTunnelCounts(active []Activity) *TunnelCounts

ActiveTunnelCounts excludes recent completions and non-tunnel operations.

type WakeInterface added in v0.5.0

type WakeInterface struct {
	Address string `json:"address"`
	MAC     string `json:"mac"`
}

WakeInterface records an IPv4 interface address with prefix length and its MAC. Nodes report eligible interfaces automatically, independently of labels.

type WakeResult added in v0.5.0

type WakeResult struct {
	Target  string `json:"target"`
	Source  string `json:"source"`
	Packets int    `json:"packets"`
}

type WorkCounts added in v0.5.0

type WorkCounts struct {
	Tasks     int `json:"tasks"`
	Exec      int `json:"exec"`
	Transfers int `json:"transfers"`
	Other     int `json:"other"`
}

WorkCounts splits a machine's active operations by kind. Tunnels are counted separately by TunnelCounts.

type WorkflowStep

type WorkflowStep struct {
	Name   string   `json:"name"`
	Target string   `json:"target"`
	Needs  []string `json:"needs,omitempty"`
	Task   TaskSpec `json:"task"`
	Inputs []struct {
		Step     string `json:"step"`
		Artifact int    `json:"artifact"`
		Path     string `json:"path"`
	} `json:"inputs,omitempty"`
}

Jump to

Keyboard shortcuts

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