model

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Oct 14, 2026 License: MIT Imports: 6 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 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, requesting worker and orchestrator owner.

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 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 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"`
	// 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"`
	// 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"`
}

type NodeHealth

type NodeHealth struct {
	ActiveCount int        `json:"activeCount"`
	Leased      bool       `json:"leased"`
	System      SystemInfo `json:"system"`
}

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

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 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"`
}

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"`
	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"`
	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 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 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 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