Documentation
¶
Index ¶
- Constants
- func JSON(v any) json.RawMessage
- func SameJSON(a, b json.RawMessage) bool
- func WithDelegations(ctx context.Context, grants []Delegation) context.Context
- type APICall
- type Activity
- type ActivityQuery
- type Artifact
- type Capability
- type ConcurrencyPool
- type ConnectionLatency
- type ConnectionOpenRequest
- type ConnectionRouteCounts
- type ConnectionTestOptions
- type ConnectionTestRequest
- type ConnectionTestResult
- type ConnectionThroughput
- type DelegatedInput
- type Delegation
- type DiskUsage
- type GPUInfo
- type GatewaySnapshot
- type Input
- type LANPeer
- type LANProbe
- type LANProof
- type Lease
- type MachineState
- type MachineStateProof
- type Node
- type NodeActivitySnapshot
- type NodeConcurrency
- type NodeHealth
- type NodeSelector
- type PeerRoute
- type PeerSession
- type PoolActivityQuery
- type PoolActivitySnapshot
- type RPCError
- type Request
- type Response
- type StartupReply
- type StartupRequest
- type SystemInfo
- type Task
- type TaskLogChunk
- type TaskPage
- type TaskSpec
- type TaskSubmissionReceipt
- type TaskSummary
- type TransportStats
- type TunnelCounts
- type WakeInterface
- type WakeResult
- type WorkCounts
- type WorkflowStep
Constants ¶
const ( ConnectionTestMethod = "connection.test" ConnectionOpenMethod = "connection.open" ConnectionTestProtocol = "connection-test-v1" ConnectionTestTimeout = 2 * time.Minute )
const ( GPUDiscrete = "discrete" GPUIntegrated = "integrated" GPUVirtual = "virtual" GPUNPU = "npu" )
const LANPeerTTL = 7 * 24 * time.Hour
const MaxGPUs = 16
const MaxLANPeers = 128
const MaxNodeHealthBytes = 16 << 10
const NodeHealthInterval = 5 * time.Second
const NodeHealthTTL = 20 * time.Second
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 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 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 ¶
ConnectionTestOptions bounds synthetic traffic independently of network speed.
func (ConnectionTestOptions) Normalize ¶
func (q ConnectionTestOptions) Normalize() (ConnectionTestOptions, error)
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 DelegatedInput ¶
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 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
Displayable excludes integrated, virtual, and unclassified adapters without discarding their inventory from the system API.
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 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.
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"`
// 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"`
// 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"`
}
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"`
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"`
}
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 PoolActivityQuery ¶
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
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
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
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"`
}
type TaskLogChunk ¶
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 ¶
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
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 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.