wire

package
v1.10.0 Latest Latest
Warning

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

 Go to latest Published: May 12, 2026 License: AGPL-3.0 Imports: 9 Imported by: 0

Documentation

Overview

Package wire defines the binary wire format shared between the registry client and server. It contains protocol constants, framing, and the encode/decode helpers that both sides use to talk over the same TCP connection. Pure types and functions — no networking, no logging, no I/O beyond the io.Reader/io.Writer abstractions used by the framing layer.

Index

Constants

View Source 
const (
	MsgJSON        byte = 0x00
	MsgHeartbeat   byte = 0x01
	MsgHeartbeatOK byte = 0x81
	MsgLookup      byte = 0x02
	MsgLookupOK    byte = 0x82
	MsgResolve     byte = 0x03
	MsgResolveOK   byte = 0x83
	MsgError       byte = 0xFF
)

Binary message type constants.

View Source 
const MaxMessageSize = 64 * 1024 * 1024

MaxMessageSize is the maximum allowed wire message size (64 MiB). Messages exceeding this limit cause the connection to be closed. Note: must stay well below the binary wire magic (0x50494C54 ≈ 1.3B) for protocol auto-detection to work. Sized for full registry snapshot in subscribe_replication: ~26 MiB at 100k+ nodes, with headroom.

View Source 
const Version byte = 1

Version is the current binary protocol version.

View Source 
const WriteMessageDeadline = 5 * time.Second

WriteMessageDeadline bounds how long a single JSON response write can take. If a client is slow to drain (overloaded host, kernel buffer pressure) we'd otherwise hold the request goroutine + response payload in memory indefinitely. After this deadline expires, w.Write returns an error and the caller can drop the connection cleanly.

Variables

View Source 
var Magic = [4]byte{0x50, 0x49, 0x4C, 0x54} // "PILT"

Magic is the 4-byte magic sent by binary clients at connection start.

Functions

func AllowedPortsToPolicy 

func AllowedPortsToPolicy(ports []uint16) (json.RawMessage, error)

AllowedPortsToPolicy converts a port allowlist into a PolicyDocument JSON (json.RawMessage). This replaces the old AllowedPorts mechanism with equivalent policy rules.

func DecodeError 

func DecodeError(payload []byte) string

DecodeError decodes an error message frame payload.

func DecodeHeartbeatResp 

func DecodeHeartbeatResp(payload []byte) (unixTime int64, keyExpiryWarning bool, err error)

DecodeHeartbeatResp decodes a heartbeat response.

func DecodeLookupReq 

func DecodeLookupReq(payload []byte) (uint32, error)

DecodeLookupReq decodes a lookup request.

func DecodeResolveReq 

func DecodeResolveReq(payload []byte) (nodeID, requesterID uint32, sig []byte, err error)

DecodeResolveReq decodes a resolve request.

func EncodeError 

func EncodeError(msg string) []byte

EncodeError encodes an error message frame payload.

func EncodeHeartbeatReq 

func EncodeHeartbeatReq(nodeID uint32, sig []byte) []byte

EncodeHeartbeatReq encodes a heartbeat request payload.

func EncodeHeartbeatResp 

func EncodeHeartbeatResp(unixTime int64, keyExpiryWarning bool) []byte

EncodeHeartbeatResp encodes the heartbeat response: [8B unix_time][1B flags]. flags bit0 = key_expiry_warning.

func EncodeLookupReq 

func EncodeLookupReq(nodeID uint32) []byte

EncodeLookupReq encodes a lookup request: [4B node_id].

func EncodeLookupResp 

func EncodeLookupResp(nodeID uint32, public, taskExec bool,
	networks []uint16, pubKey []byte, hostname string, tags []string,
	realAddr string, externalID string) []byte

EncodeLookupResp encodes a lookup response. Format: [4B node_id][1B flags][4B reserved][2B net_count][net_ids...] 

[1B pubkey_len][pubkey...][1B hostname_len][hostname...]
[1B tags_count][for each: 1B len, bytes...][2B addr_len][addr...]
[1B extid_len][extid...]

The 4-byte reserved field was formerly polo_score; it is written as zero and ignored on decode to preserve wire-format compatibility.

func EncodeResolveReq 

func EncodeResolveReq(nodeID, requesterID uint32, sig []byte) []byte

EncodeResolveReq encodes a resolve request: [4B node_id][4B requester_id][64B signature].

func EncodeResolveResp 

func EncodeResolveResp(nodeID uint32, realAddr string, lanAddrs []string, keyAgeDays int) []byte

EncodeResolveResp encodes a resolve response. Format: [4B node_id][2B addr_len][addr...][2B lan_count][for each: 2B len, addr...] 

[4B key_age_days]  (math.MaxUint32 if unknown)

func ReadFrame 

func ReadFrame(r io.Reader) (msgType byte, payload []byte, err error)

ReadFrame reads a single binary frame: [4B length][1B type][payload].

func ReadMessage 

func ReadMessage(r io.Reader) (map[string]interface{}, error)

ReadMessage reads a length-prefixed JSON message from r and decodes it into a map.

func RulesToPolicy 

func RulesToPolicy(r *NetworkRules) (json.RawMessage, error)

RulesToPolicy converts a NetworkRules struct into a PolicyDocument JSON (json.RawMessage). This provides backward compatibility: existing managed networks continue to work through the policy engine.

func ValidateBlueprint 

func ValidateBlueprint(bp *NetworkBlueprint) error

ValidateBlueprint checks a blueprint for configuration errors.

func ValidateRules 

func ValidateRules(r *NetworkRules) error

ValidateRules checks that a NetworkRules is well-formed. Returns nil if valid.

func WriteFrame 

func WriteFrame(w io.Writer, msgType byte, payload []byte) error

WriteFrame writes a single binary frame.

func WriteMessage 

func WriteMessage(w io.Writer, msg map[string]interface{}) error

WriteMessage writes a length-prefixed JSON-encoded message to w. If w is a net.Conn, a write deadline is applied.

func WriteRawMessage 

func WriteRawMessage(w io.Writer, body []byte) error

WriteRawMessage writes a length-prefixed raw JSON body to w. Callers that have already produced the JSON bytes (e.g., a list-nodes cache hit) can skip the json.Marshal step.

Types

type BlueprintAuditExport 

type BlueprintAuditExport struct {
	Format   string `json:"format"`           // "json", "splunk_hec", "syslog_cef"
	Endpoint string `json:"endpoint"`         // destination URL or address
	Token    string `json:"token,omitempty"`  // auth token (e.g., Splunk HEC token)
	Index    string `json:"index,omitempty"`  // Splunk index
	Source   string `json:"source,omitempty"` // source identifier
}

BlueprintAuditExport configures external audit log export.

type BlueprintIdentityProvider 

type BlueprintIdentityProvider struct {
	Type     string `json:"type"`                // "oidc", "saml", "webhook", "entra_id", "ldap"
	URL      string `json:"url"`                 // verification endpoint
	Issuer   string `json:"issuer,omitempty"`    // OIDC issuer URL
	ClientID string `json:"client_id,omitempty"` // OIDC client ID
	TenantID string `json:"tenant_id,omitempty"` // Azure AD / Entra ID tenant
	Domain   string `json:"domain,omitempty"`    // LDAP domain
}

BlueprintIdentityProvider configures external identity verification.

type BlueprintPolicy 

type BlueprintPolicy struct {
	MaxMembers   int      `json:"max_members,omitempty"`
	AllowedPorts []uint16 `json:"allowed_ports,omitempty"`
	Description  string   `json:"description,omitempty"`
}

BlueprintPolicy defines the network policy section of a blueprint.

type BlueprintRole 

type BlueprintRole struct {
	ExternalID string `json:"external_id"`
	Role       string `json:"role"` // "owner", "admin", "member"
}

BlueprintRole pre-assigns RBAC roles by external identity.

type BlueprintWebhooks 

type BlueprintWebhooks struct {
	AuditURL    string `json:"audit_url,omitempty"`    // audit event webhook
	IdentityURL string `json:"identity_url,omitempty"` // identity verification webhook
}

BlueprintWebhooks configures webhook endpoints for the network.

type HeartbeatReq 

type HeartbeatReq struct {
	NodeID    uint32
	Signature [64]byte
}

HeartbeatReq holds a decoded binary heartbeat request: [4B node_id][64B signature].

func DecodeHeartbeatReq 

func DecodeHeartbeatReq(payload []byte) (HeartbeatReq, error)

DecodeHeartbeatReq decodes a heartbeat request payload.

type LookupResult 

type LookupResult struct {
	NodeID     uint32
	Public     bool
	TaskExec   bool
	Networks   []uint16
	PubKey     []byte
	Hostname   string
	Tags       []string
	RealAddr   string
	ExternalID string
}

LookupResult holds the decoded fields from a binary lookup response.

func DecodeLookupResp 

func DecodeLookupResp(payload []byte) (LookupResult, error)

DecodeLookupResp decodes a binary lookup response.

type NetworkBlueprint 

type NetworkBlueprint struct {
	// Network settings
	Name       string `json:"name"`
	JoinRule   string `json:"join_rule,omitempty"`  // "open", "token", "invite" (default: "open")
	JoinToken  string `json:"join_token,omitempty"` // required if join_rule = "token"
	Enterprise bool   `json:"enterprise,omitempty"` // enable enterprise features

	// Policy
	Policy     *BlueprintPolicy `json:"policy,omitempty"`
	ExprPolicy json.RawMessage  `json:"expr_policy,omitempty"`

	// RBAC pre-assignments (by external_id)
	Roles []BlueprintRole `json:"roles,omitempty"`

	// Identity provider configuration
	IdentityProvider *BlueprintIdentityProvider `json:"identity_provider,omitempty"`

	// Observability
	Webhooks *BlueprintWebhooks `json:"webhooks,omitempty"`

	// Audit export
	AuditExport *BlueprintAuditExport `json:"audit_export,omitempty"`

	// Per-network admin token (optional override)
	NetworkAdminToken string `json:"network_admin_token,omitempty"`
}

NetworkBlueprint defines a declarative configuration for provisioning an enterprise network. Enterprises apply blueprints via the registry protocol or the pilotctl CLI to create and configure networks in one shot.

func LoadBlueprint 

func LoadBlueprint(path string) (*NetworkBlueprint, error)

LoadBlueprint reads a network blueprint from a JSON file.

type NetworkRules 

type NetworkRules struct {
	Links   int    `json:"links"`           // max managed peers per node
	Cycle   string `json:"cycle"`           // Go duration: "24h", "1h"
	Prune   int    `json:"prune"`           // how many to drop per cycle
	PruneBy string `json:"prune_by"`        // "score", "age", "activity"
	Fill    int    `json:"fill"`            // how many to add per cycle
	FillHow string `json:"fill_how"`        // "random"
	Grace   string `json:"grace,omitempty"` // grace period for new members
}

NetworkRules defines the managed network ruleset. When set on a NetworkInfo, the network becomes "managed" — daemon-local link lifecycle is governed by these rules. The registry only stores and distributes the rules; all cycle logic runs inside each daemon.

func ParseRules 

func ParseRules(raw string) (*NetworkRules, error)

ParseRules unmarshals a JSON string into NetworkRules and validates it.

type ResolveResult 

type ResolveResult struct {
	NodeID     uint32
	RealAddr   string
	LANAddrs   []string
	KeyAgeDays int // -1 if unknown
}

ResolveResult holds the decoded fields from a binary resolve response.

func DecodeResolveResp 

func DecodeResolveResp(payload []byte) (ResolveResult, error)

DecodeResolveResp decodes a binary resolve response.

Source Files

View all Source files

Jump to

Keyboard shortcuts

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