model

package
v0.10.3 Latest Latest
Warning

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

Go to latest
Published: Nov 19, 2026 License: MIT Imports: 16 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 (
	MaxProxyEndpoints      = 8
	MaxProxyInterfaceBytes = 64
	MaxProxyErrorBytes     = 160
	// ProxyCheckInterval is the healthy worker's proxy-to-gateway check cadence,
	// independent of dashboard polling.
	ProxyCheckInterval = time.Minute
	// ProxyReadinessTTL turns an older observation into "stale", which is
	// never eligible for new invitations.
	ProxyReadinessTTL = 3 * ProxyCheckInterval
	// MaxProxySources bounds a managed listener's source CIDR allowlist.
	MaxProxySources = 16
)

Gateway proxy limits. A worker advertises a few explicitly configured endpoints, never every interface, and reports bounded readiness for each.

View Source
const (
	ProxyReady = "ready"
	// ProxyStandby reports a managed listener that is intentionally off because
	// nothing depends on it, after the worker freshly verified the direct
	// gateway path the listener would use. Invitation creation activates it.
	ProxyStandby     = "standby"
	ProxyUnavailable = "unavailable"
	ProxyStale       = "stale"
	ProxyOffline     = "offline"
	ProxyUnchecked   = "unchecked"
)

Proxy readiness states. ProxyReady is eligible for invitation selection; ProxyStandby is eligible only for a Control-managed endpoint.

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 MaxWorkflowParallel = 16
View Source
const NodeHealthInterval = 5 * time.Second
View Source
const NodeHealthTTL = 20 * time.Second
View Source
const Version = "1"

Variables

View Source
var TaskIDPattern = regexp.MustCompile(`^[a-zA-Z0-9_-]{1,128}$`)

TaskIDPattern is the task ID syntax nodes accept: 1-128 ASCII letters, digits, underscores and hyphens. Machine names may contain dots; IDs may not.

Functions

func JSON

func JSON(v any) json.RawMessage

func ManagedListenAddress added in v0.9.1

func ManagedListenAddress(proxyURL string) (netip.AddrPort, error)

ManagedListenAddress returns the explicit private or VPN socket address a managed listener binds. Hostnames, wildcard, loopback, link-local, and public addresses are refused so the listener never opens on every interface.

func ManagedSources added in v0.9.1

func ManagedSources(sources []string) ([]netip.Prefix, error)

ManagedSources validates a managed listener's source allowlist. Every prefix must lie inside a private or VPN range.

func NormalizeProxyURL added in v0.9.1

func NormalizeProxyURL(value string) (string, error)

NormalizeProxyURL accepts only an explicit http://host:port CONNECT proxy without credentials, path, query, or fragment. IPv6 hosts are bracketed.

func SameJSON

func SameJSON(a, b json.RawMessage) bool

SameJSON compares decoded JSON, preserving numeric precision.

func ValidProxyReadiness added in v0.9.1

func ValidProxyReadiness(readiness []ProxyReadiness) bool

ValidProxyReadiness bounds a node-reported observation.

func ValidateGatewayProxy added in v0.9.1

func ValidateGatewayProxy(proxy *GatewayProxy) error

ValidateGatewayProxy checks display metadata as well as the configured URL.

func ValidateProxyEndpoints added in v0.9.1

func ValidateProxyEndpoints(endpoints []ProxyEndpoint) error

ValidateProxyEndpoints checks a worker's advertisement for registration.

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 ConcurrencyPool added in v0.8.0

type ConcurrencyPool struct {
	Limit int `json:"limit"`
	InUse int `json:"inUse"`
	// Older workers report limit/inUse without queue counts. Nil means unknown.
	Queued *int `json:"queued,omitempty"`
}

ConcurrencyPool reports admission, not CPU usage or a capacity reservation.

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 GatewayProxy added in v0.9.1

type GatewayProxy struct {
	URL    string `json:"url"`
	Worker string `json:"worker,omitempty"`
	// Managed records that the invitation selected a Control-managed listener,
	// so the gateway keeps that listener active for this dependency.
	Managed bool `json:"managed,omitempty"`
}

GatewayProxy selects the single CONNECT proxy a child uses for every gateway request. Worker is the proxy worker's stable identity, recorded for display and auditing; the URL alone determines routing.

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. Its only effects are acknowledgements of the signer's own policy revision: a connected node's lifecycle acknowledgement, and an unregistered node's retirement acknowledgement that releases its own managed proxy dependency.

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"`
	// MachineStatePush asks the gateway to hint at policy changes on this connection.
	MachineStatePush bool `json:"machineStatePush,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"`
	// GatewayProxyManagement supports worker-local explicit proxy settings.
	GatewayProxyManagement bool `json:"gatewayProxyManagement,omitempty"`
	// ProxyManagementPending is a gateway-owned durable uncertainty fence.
	ProxyManagementPending bool `json:"proxyManagementPending,omitempty"`
	// SecretManagementKey is a process-local P-256 public key for encrypted writes.
	SecretManagementKey []byte `json:"secretManagementKey,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"`
	// ProxyEndpoints are explicitly configured CONNECT proxies on this worker.
	// Readiness is reported separately in health; advertisement is not proof.
	ProxyEndpoints []ProxyEndpoint `json:"proxyEndpoints,omitempty"`
	// GatewayProxy reports this node's configured route, not connection health.
	// It is retained by the gateway for owner status, not peer discovery.
	GatewayProxy *GatewayProxy `json:"gatewayProxy,omitempty"`
}

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"`
	UpdateState      string                 `json:"updateState,omitempty"`
	Error            string                 `json:"error,omitempty"`
	ObservedAt       time.Time              `json:"observedAt,omitempty"`
	Active           []Activity             `json:"active"`
	Recent           []Activity             `json:"recent"`
	ActiveCount      int                    `json:"activeCount"`
	Concurrency      *NodeConcurrency       `json:"concurrency,omitempty"`
	Omitted          int                    `json:"omitted,omitempty"`
	DirectSessions   int                    `json:"directSessions"`
	RelaySessions    int                    `json:"relaySessions"`
	ConnectionRoutes *ConnectionRouteCounts `json:"connectionRoutes,omitempty"`
	// ProxyEndpoints are owner-visible advertised gateway proxies and readiness.
	ProxyEndpoints  []ProxyEndpointStatus `json:"proxyEndpoints,omitempty"`
	GatewayProxy    *GatewayProxy         `json:"gatewayProxy,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 NodeConcurrency added in v0.8.0

type NodeConcurrency struct {
	Execution  ConcurrencyPool `json:"execution"`
	Operations ConcurrencyPool `json:"operations"`
	// Older workers have no separate desktop admission or desktop report.
	Desktop *ConcurrencyPool `json:"desktop,omitempty"`
	// Task transfer stages are absent on workers predating pipelined admission.
	InputStaging      *ConcurrencyPool `json:"inputStaging,omitempty"`
	OutputPublication *ConcurrencyPool `json:"outputPublication,omitempty"`
}

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"`
	// Proxies reports this worker's own proxy-to-gateway checks.
	Proxies []ProxyReadiness `json:"proxies,omitempty"`
}

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 ProxyConfiguration added in v0.9.1

type ProxyConfiguration struct {
	Supported  bool             `json:"supported"`
	Enabled    bool             `json:"enabled"`
	Interfaces []ProxyInterface `json:"interfaces"`
	Settings   *ProxySettings   `json:"settings,omitempty"`
	Dependents ProxyDependents  `json:"dependents"`
}

type ProxyConfigure added in v0.9.1

type ProxyConfigure struct {
	Enabled   bool     `json:"enabled"`
	Interface string   `json:"interface,omitempty"`
	Address   string   `json:"address,omitempty"`
	Port      int      `json:"port,omitempty"`
	Sources   []string `json:"sources,omitempty"`
}

func (ProxyConfigure) Endpoint added in v0.9.1

func (q ProxyConfigure) Endpoint() (ProxyEndpoint, error)

type ProxyDependents added in v0.9.1

type ProxyDependents struct {
	Invitations int `json:"invitations"`
	Children    int `json:"children"`
	Retiring    int `json:"retiring"`
	// Machines groups enrolled children by their gateway-issued Hybrid pair.
	// It is display-only and does not add to Total.
	Machines int `json:"machines"`
}

ProxyDependents counts a managed endpoint's durable gateway dependencies: pending usable invitations (including Hybrid companions), enrolled children whether online or not, and unregistered children that have not yet acknowledged their signed retirement policy.

func (ProxyDependents) Total added in v0.9.1

func (d ProxyDependents) Total() int

Total is the number of dependencies preventing explicit disable.

type ProxyEndpoint added in v0.9.1

type ProxyEndpoint struct {
	URL string `json:"url"`
	// Interface optionally labels the LAN or VPN the address belongs to.
	Interface string `json:"interface,omitempty"`
	// Managed selects Control's own fixed-gateway CONNECT listener on URL's
	// private address instead of separately managed proxy software. The
	// owner explicitly enables or disables it; dependencies prevent unsafe
	// disable/reconfiguration. It never controls an external proxy.
	Managed bool `json:"managed,omitempty"`
	// Sources lists the private/VPN CIDRs a managed listener accepts. It is
	// local profile configuration and is not advertised in registration.
	Sources []string `json:"sources,omitempty"`
}

ProxyEndpoint is a CONNECT proxy address a worker explicitly advertises for machines that cannot reach the gateway directly. Configuration, not readiness.

type ProxyEndpointStatus added in v0.9.1

type ProxyEndpointStatus struct {
	URL       string    `json:"url"`
	Interface string    `json:"interface,omitempty"`
	Managed   bool      `json:"managed,omitempty"`
	State     string    `json:"state"`
	CheckedAt time.Time `json:"checkedAt,omitzero"`
	Error     string    `json:"error,omitempty"`
	// Dependents counts what prevents disabling a managed listener.
	Dependents *ProxyDependents `json:"dependents,omitempty"`
}

ProxyEndpointStatus is the gateway's fleet-scoped projection of an advertised endpoint and its latest readiness observation.

func ProxyStatuses added in v0.9.1

func ProxyStatuses(endpoints []ProxyEndpoint, online bool, readiness []ProxyReadiness, observedAt, now time.Time) []ProxyEndpointStatus

ProxyStatuses projects advertised endpoints with readiness observed at observedAt. Configuration without a fresh matching observation is never ready.

func (ProxyEndpointStatus) Selectable added in v0.9.1

func (s ProxyEndpointStatus) Selectable() bool

Selectable reports whether a new invitation can select this endpoint now.

type ProxyInterface added in v0.9.1

type ProxyInterface struct {
	Name    string `json:"name"`
	Address string `json:"address"`
	Prefix  string `json:"prefix"`
}

ProxyInterface is an eligible address observed on a live worker interface.

type ProxyManagementReply added in v0.9.1

type ProxyManagementReply struct {
	ID            string             `json:"id"`
	Error         string             `json:"error,omitempty"`
	Configuration ProxyConfiguration `json:"configuration"`
	Endpoints     []ProxyEndpoint    `json:"endpoints"`
}

type ProxyManagementRequest added in v0.9.1

type ProxyManagementRequest struct {
	ID        string          `json:"id"`
	ExpiresAt int64           `json:"expiresAt"`
	Configure *ProxyConfigure `json:"configure,omitempty"`
}

ProxyManagementRequest is a fixed owner-management operation with no RPC, executable, credential, or arbitrary filesystem access.

type ProxyReadiness added in v0.9.1

type ProxyReadiness struct {
	URL       string    `json:"url"`
	State     string    `json:"state"`
	CheckedAt time.Time `json:"checkedAt"`
	// AgeSeconds lets the gateway date the check on its own clock.
	AgeSeconds int    `json:"ageSeconds"`
	Error      string `json:"error,omitempty"`
}

ProxyReadiness is a worker's bounded proxy-to-gateway check of one endpoint. Ready proves CONNECT, gateway TLS verification, and a gateway health response through that proxy. It does not prove a future child can reach it.

type ProxySettings added in v0.9.1

type ProxySettings struct {
	Interface string   `json:"interface"`
	Address   string   `json:"address"`
	Port      int      `json:"port"`
	Sources   []string `json:"sources"`
}

type ProxyState added in v0.9.1

type ProxyState struct {
	Listeners []string `json:"listeners"`
}

ProxyState lists the managed endpoint URLs whose listeners must run.

type ProxyStateProof added in v0.9.1

type ProxyStateProof struct {
	PublicKey []byte    `json:"publicKey"`
	SignedAt  time.Time `json:"signedAt"`
	Signature []byte    `json:"signature"`
}

ProxyStateProof lets a worker read its own desired managed listeners. It is signed by the worker identity and authorizes no mutation.

func (ProxyStateProof) Message added in v0.9.1

func (p ProxyStateProof) Message() []byte

type ProxyWorker added in v0.9.1

type ProxyWorker struct {
	ID        string                `json:"id"`
	Name      string                `json:"name"`
	Online    bool                  `json:"online"`
	Disabled  bool                  `json:"disabled,omitempty"`
	Endpoints []ProxyEndpointStatus `json:"endpoints"`
}

ProxyWorker is a fleet machine advertising gateway proxy endpoints, as projected for invitation selection.

func (ProxyWorker) ReadyEndpoints added in v0.9.1

func (w ProxyWorker) ReadyEndpoints() []ProxyEndpointStatus

ReadyEndpoints returns endpoints currently eligible for a new invitation: ready endpoints, and managed endpoints on standby that invitation creation activates.

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"`
	// SubmissionID is a fresh RPC nonce, never a durable task ID.
	SubmissionID string `json:"submissionId,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"`
	Submission *TaskSubmissionReceipt `json:"submission,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 TaskSubmissionReceipt added in v0.8.5

type TaskSubmissionReceipt struct {
	ID     string `json:"id"`
	TaskID string `json:"taskId"`
	Status string `json:"status"` // accepted, existing, or rejected before adoption
}

TaskSubmissionReceipt describes only this RPC's acceptance decision. It is never persisted in a Task or restored by tasks.get.

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 WorkflowPlan added in v0.10.1

type WorkflowPlan struct {
	Steps       []WorkflowStep `json:"steps"`
	MaxParallel int            `json:"maxParallel,omitempty"`
}

func (WorkflowPlan) Ordered added in v0.10.1

func (p WorkflowPlan) Ordered() ([]WorkflowStep, error)

Ordered validates the whole graph before issuing grants or starting children.

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

func (WorkflowStep) Ready added in v0.10.1

func (s WorkflowStep) Ready(completed map[string]bool) bool

Jump to

Keyboard shortcuts

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