readyproto

package
v0.6.13 Latest Latest
Warning

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

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

Documentation

Overview

Package readyproto defines the newline-delimited JSON handshake toolboxd sends to sandboxd when a Docker sandbox's agent is ready to serve.

Index

Constants

View Source
const (
	// EventReady is the guest→host readiness announcement after adopt or cold boot.
	EventReady = "ready"
	// EventParked is the guest→host hello from a warm-pool slot awaiting adopt.
	EventParked = "parked"
	// EventAdopt is the host→guest frame that binds real sandbox identity.
	EventAdopt = "adopt"
	// MaxLineBytes caps attacker-controlled read size on the host listener.
	MaxLineBytes = 4 << 10
	// MaxAdoptLineBytes caps an adopt frame. It is far above MaxLineBytes
	// because the frame carries the sandbox's env (plans/cluster-phase-2.md
	// §2), and it is the only line the larger cap applies to: the adopt
	// frame is host→guest, written by sandboxd and read by toolboxd, so the
	// host listener, which reads the lines a guest controls (parked hello,
	// ready ack), keeps the 4 KiB cap on attacker-sized reads.
	MaxAdoptLineBytes = 256 << 10
	// MaxAdoptEnvBytes is the largest JSON-encoded env an adopt frame may
	// carry. The rest of the frame (event, sandbox id, token, nonce) is what
	// every other line already fits in MaxLineBytes, so an env within this
	// bound always leaves a frame within MaxAdoptLineBytes, and a create
	// whose env is bigger is refused from the warm pool up front rather
	// than failing an adopt and burning a parked slot.
	MaxAdoptEnvBytes = MaxAdoptLineBytes - MaxLineBytes
)

Variables

View Source
var ErrEnvInvalid = errors.New("readyproto: env has an empty key, a key containing '=', a NUL byte, or bytes that are not UTF-8")

ErrEnvInvalid is returned for an env an adopt frame cannot carry: an empty key, a key containing '=', a NUL byte anywhere, or bytes that are not UTF-8 (encoding/json would replace them, so the guest would get a different value). The message names neither the key nor the value, since either could be a secret pasted into the wrong field.

View Source
var ErrEnvTooLarge = fmt.Errorf("readyproto: env exceeds %d encoded bytes", MaxAdoptEnvBytes)

ErrEnvTooLarge is returned for an env whose encoding exceeds MaxAdoptEnvBytes.

Functions

func Encode

func Encode(w io.Writer, sig ReadySignal) error

Encode writes one newline-terminated JSON line.

func EncodeAdopt

func EncodeAdopt(w io.Writer, frame AdoptFrame) error

EncodeAdopt writes a host→guest adopt frame.

func EncodeParked

func EncodeParked(w io.Writer, sig ParkedSignal) error

EncodeParked writes a parked hello line.

func EnvDigest added in v0.6.12

func EnvDigest(nonce string, env map[string]string) string

EnvDigest is the proof a guest's ready ack carries that it applied exactly the env an adopt frame held: hex HMAC-SHA256 keyed with the adopt nonce over the env in canonical form (entries sorted by key, each "key=value" then a NUL; keys hold neither '=' nor NUL and values hold no NUL, so the form is unambiguous). Keyed with the per-adopt nonce rather than a bare hash so the ack never holds a stable fingerprint of the env: a bare hash of a low-entropy secret could be matched by hashing guesses.

func EnvDigestMatches added in v0.6.12

func EnvDigestMatches(nonce string, env map[string]string, digest string) bool

EnvDigestMatches reports, in constant time, whether digest is EnvDigest(nonce, env). An empty digest never matches.

func ValidateAdoptEnv added in v0.6.12

func ValidateAdoptEnv(env map[string]string) error

ValidateAdoptEnv reports whether env can ride an adopt frame: every entry is one a process environment can carry, and the encoding fits within MaxAdoptEnvBytes. The host checks it before it takes a parked slot for a create, so an env the frame cannot carry sends the create cold instead of failing the adopt after the slot is spent. Errors are ErrEnvInvalid or ErrEnvTooLarge, which quote nothing from env.

Types

type AdoptFrame

type AdoptFrame struct {
	Event     string `json:"event"`
	SandboxID string `json:"sandbox_id"`
	Token     string `json:"token"`
	Nonce     string `json:"nonce"`
	// Env is the sandbox's env. The guest loads it before it takes the
	// identity and starts the held-back image command, so that command,
	// exec and sessions all see it. Omitted when empty, so an env-less
	// adopt is the same bytes an older agent has always read.
	Env map[string]string `json:"env,omitempty"`
}

AdoptFrame is the host→guest identity bind during warm-pool adoption.

func DecodeAdopt

func DecodeAdopt(r io.Reader) (AdoptFrame, error)

DecodeAdopt reads a host→guest adopt frame.

type ParkedSignal

type ParkedSignal struct {
	Event        string `json:"event"`
	Token        string `json:"token"`
	Nonce        string `json:"nonce"`
	AgentVersion string `json:"agent_version,omitempty"`
}

ParkedSignal is the guest→host parked-slot hello.

func DecodeParked

func DecodeParked(r io.Reader) (ParkedSignal, error)

DecodeParked reads a guest→host parked hello.

type ReadySignal

type ReadySignal struct {
	Event        string `json:"event"`
	SandboxID    string `json:"sandbox_id"`
	Token        string `json:"token"`
	Nonce        string `json:"nonce"`
	AgentVersion string `json:"agent_version,omitempty"`
	// EnvDigest is set only in the ack of an adopt: EnvDigest(Nonce, env)
	// over the env the guest applied. An agent built before adopt frames
	// carried env leaves it out (encoding/json drops the unknown "env"
	// field without a word), which is how the host tells an agent that
	// ignored the env from one that applied it.
	EnvDigest string `json:"env_digest,omitempty"`
}

ReadySignal is the guest→host readiness announcement.

func Decode

func Decode(r io.Reader) (ReadySignal, error)

Decode reads one bounded newline-delimited ready line from r.

Jump to

Keyboard shortcuts

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