protocol

package
v0.13.0 Latest Latest
Warning

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

 Go to latest Published: Nov 5, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package protocol is the request format shared by the nsl CLI and the VM agent. See docs/specs/agent.md. Both ends are built from this repository, so the version detects mismatched builds and is never negotiated.

Index

Constants

View Source 
const (
	Version        = 1
	MachineVersion = 1
	Limit          = 64 << 10
	AgentPath      = "/usr/lib/nsl/nsl-agent"
	// ImageShare is where a VM mounts the host's verified machine-image cache.
	ImageShare = "/var/cache/nsl/images"
	// ArchiveLimit bounds an exported root filesystem, compressed or not: the
	// largest data disk.
	ArchiveLimit int64 = 4096 << 30
)

Version is the agent protocol; MachineVersion is the machine-layer protocol that the agent requires of machine images.

View Source 
const (
	CodeBadRequest     = "bad-request"
	CodeProtocol       = "protocol"
	CodeUnknownMachine = "unknown-machine"
	CodeMachineID      = "machine-id"
	CodeNotRunning     = "not-running"
	CodeBusy           = "busy"
	CodeRefused        = "refused"
	CodeFailed         = "failed"
)

Error codes from docs/specs/agent.md.

View Source 
const ErrorExit = 255

ErrorExit is the agent's exit status for its own errors.

Variables

View Source 
var Passive = map[string]bool{"identity": true, "machines": true, "listeners": true, "display": true}

Passive operations observe or serve the VM; they are not activity for the idle monitor.

Functions

func DecodeStrict 

func DecodeStrict(data []byte, dst any) error

DecodeStrict decodes one JSON value, rejecting duplicate keys, unknown fields and trailing data.

func Encode 

func Encode(r Request) (string, error)

Encode validates a request and frames it for SSH_ORIGINAL_COMMAND.

func ExitStatus 

func ExitStatus(code, status int32) int

ExitStatus maps systemd's ExecMainCode and ExecMainStatus to a shell-style status: the exit code, or 128+N for signal N.

func SafeHostPath 

func SafeHostPath(p string) bool

SafeHostPath reports whether p is a clean absolute path other than / that vmspawn and mount options can carry.

func ValidAccount 

func ValidAccount(s string) bool

ValidAccount reports whether s is a POSIX account name nsl accepts.

func ValidBuildID 

func ValidBuildID(s string) bool

ValidBuildID reports whether s is an image build ID.

func ValidDigest 

func ValidDigest(s string) bool

ValidDigest reports whether s is sha256: followed by 64 lowercase hex digits.

func ValidID 

func ValidID(s string) bool

ValidID reports whether s is a 32-hex VM or machine ID.

func ValidName 

func ValidName(s string) bool

ValidName reports whether s is a machine name: a lowercase letter, then lowercase letters, digits or interior hyphens, at most 24 characters.

func ValidUID 

func ValidUID(n int) bool

ValidUID reports whether n is usable as a machine account's UID or GID.

func ValidZone 

func ValidZone(s string) bool

ValidZone reports whether s is an IANA zone name without path tricks.

Types

type Account 

type Account struct {
	User  string `json:"user"`
	Group string `json:"group"`
	UID   int    `json:"uid"`
	GID   int    `json:"gid"`
}

type Alias 

type Alias struct {
	Path   string `json:"path"`
	Target string `json:"target"`
}

Alias is a relative symlink under /mnt/host for a top-level host alias.

type Binding 

type Binding struct {
	Version int         `json:"version"`
	ID      string      `json:"id"`
	Role    string      `json:"role"`
	UID     int         `json:"uid"`
	GID     int         `json:"gid"`
	Machine *MachineRef `json:"machine,omitempty"`
}

Binding is the VM identity recorded on first boot and checked on every boot.

func (*Binding) Validate 

func (b *Binding) Validate() error

Validate checks a binding's fields and the role's machine reference.

type CreateResult 

type CreateResult struct {
	BuildID string `json:"build_id"`
}

CreateResult is the answer to create and import.

type Credential 

type Credential struct {
	Binding
	PublicKey   string  `json:"public_key"`
	Autostart   bool    `json:"autostart"`
	IdleTimeout int     `json:"idle_timeout"`
	Shares      []Share `json:"shares"`
	Aliases     []Alias `json:"aliases"`
}

Credential is the nsl.vm boot credential. The binding fields must match the VM's recorded binding on every boot after the first.

func (*Credential) Validate 

func (c *Credential) Validate() error

Validate checks a credential completely.

type Error 

type Error struct {
	Code    string
	Message string
}

func ParseError 

func ParseError(stderr string) *Error

ParseError recovers an agent error from its stderr line, for operations whose stderr belongs to the agent rather than to a user command.

func (*Error) Error 

func (e *Error) Error() string

type Identity 

type Identity struct {
	Protocol int             `json:"protocol"`
	VM       Binding         `json:"vm"`
	Image    json.RawMessage `json:"image"`
}

Identity is the agent's answer to the identity operation.

type Image 

type Image struct {
	Path    string `json:"path"`
	Digest  string `json:"digest"`
	Size    int64  `json:"size"`
	BuildID string `json:"build_id"`
}

Image names a verified machine image in the VM's read-only image share. BuildID is empty for a local image; the agent reports the descriptor's.

type Listener 

type Listener struct {
	Port    int    `json:"port"`
	Address string `json:"address"`
	Machine string `json:"machine"`
}

Listener is one TCP socket listening for a machine, from the listeners operation.

type MachineRecord 

type MachineRecord struct {
	Schema  int     `json:"schema"`
	Name    string  `json:"name"`
	ID      string  `json:"id"`
	Account Account `json:"account"`
	BuildID string  `json:"build_id"`
	Created string  `json:"created"`
}

MachineRecord is the VM's record of one machine, on the state subvolume.

type MachineRef 

type MachineRef struct {
	Name string `json:"name"`
	ID   string `json:"id"`
}

type MachineStatus 

type MachineStatus struct {
	Machine  string `json:"machine"`
	ID       string `json:"id"`
	State    string `json:"state"`
	Sessions int    `json:"sessions"`
	BuildID  string `json:"build_id"`
}

MachineStatus is one entry of the machines operation.

type Request 

type Request struct {
	Protocol    int               `json:"protocol"`
	Op          string            `json:"op"`
	Machine     string            `json:"machine,omitempty"`
	ID          string            `json:"id,omitempty"`
	Argv        []string          `json:"argv,omitempty"`
	Directory   string            `json:"directory,omitempty"`
	Root        bool              `json:"root,omitempty"`
	TTY         bool              `json:"tty,omitempty"`
	Env         map[string]string `json:"env,omitempty"`
	IdleTimeout *int              `json:"idle_timeout,omitempty"`
	Account     *Account          `json:"account,omitempty"`
	Image       *Image            `json:"image,omitempty"`
	Rootfs      *Rootfs           `json:"rootfs,omitempty"`
	TimeZone    string            `json:"time_zone,omitempty"`
	PublicKey   string            `json:"public_key,omitempty"`
}

func Decode 

func Decode(s string) (*Request, error)

Decode reverses Encode, refusing anything with more than one interpretation.

func (*Request) Validate 

func (r *Request) Validate() error

Validate checks a request completely before anything acts on it.

type Rootfs 

type Rootfs struct {
	Digest  string `json:"digest"`
	Size    int64  `json:"size"`
	BuildID string `json:"build_id"`
}

Rootfs is the compressed root filesystem an import reads from stdin, as the archive's manifest records it.

type Share 

type Share struct {
	Source string `json:"source"`
}

Share is a host tree mounted read-write at /mnt/host plus its canonical path.

type StartResult 

type StartResult struct {
	State   string  `json:"state"`
	Seconds float64 `json:"seconds"`
}

StartResult is the answer to start.

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.