vsock

Documentation

Overview

Package vsock implements the host-side client for communicating with stereosd inside a StereOS guest VM over the vsock control plane.

The wire format is newline-delimited JSON (ndjson). Each message has a "type" field that determines how the payload is interpreted. This matches the protocol defined in the stereosd project.

Index

• Constants
• type AckPayload
• type AgentStatusPayload
• type Client
  • func Connect(transport Transport, timeout time.Duration) (*Client, error)
  • func Dial(address string, timeout time.Duration) (*Client, error)
  • func (c *Client) Close() error
  • func (c *Client) GetHealth(ctx context.Context) (*HealthPayload, error)
  • func (c *Client) InjectSSHKey(ctx context.Context, user, publicKey string) error
  • func (c *Client) InjectSecret(ctx context.Context, name, value string) error
  • func (c *Client) Mount(ctx context.Context, tag, guestPath, fsType string, readOnly bool) error
  • func (c *Client) Ping(ctx context.Context) error
  • func (c *Client) SetConfig(ctx context.Context, content string) error
  • func (c *Client) Shutdown(ctx context.Context, reason string) error
  • func (c *Client) WaitForReady(ctx context.Context, pollInterval time.Duration) error
• type ConfigPayload
• type Envelope
  • func NewEnvelope(msgType MessageType, payload any) (*Envelope, error)
  • func (e *Envelope) DecodePayload(target any) error
• type FuncTransport
  • func (f *FuncTransport) Dial(timeout time.Duration) (net.Conn, error)
  • func (f *FuncTransport) String() string
• type HealthPayload
• type LifecyclePayload
• type LifecycleState
• type MessageType
• type MountPayload
• type SSHKeyPayload
• type SecretPayload
• type ShutdownPayload
• type TCPTransport
  • func (t *TCPTransport) Dial(timeout time.Duration) (net.Conn, error)
  • func (t *TCPTransport) String() string
• type Transport

Constants

const (
	// VsockPort is the well-known port that stereosd listens on.
	VsockPort = 1024

	// VsockGuestCID is the guest CID for vsock connections.
	VsockGuestCID = 3

	// DefaultTimeout is the default timeout for vsock operations.
	DefaultTimeout = 10 * time.Second
)

Types

type AckPayload

type AckPayload struct {
	ReplyTo MessageType `json:"reply_to"`
	OK      bool        `json:"ok"`
	Error   string      `json:"error,omitempty"`
}

AckPayload is the payload for ack messages.

type AgentStatusPayload

type AgentStatusPayload struct {
	Name     string `json:"name"`
	Running  bool   `json:"running"`
	Session  string `json:"session,omitempty"`
	Restarts int    `json:"restarts"`
	Error    string `json:"error,omitempty"`
}

AgentStatusPayload represents the runtime state of a single agent harness.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client communicates with stereosd running inside a StereOS guest over a network connection. The underlying transport is abstracted via the Transport interface, allowing TCP (macOS/HVF), AF_VSOCK (Linux/KVM), or other transports to be used interchangeably.

func Connect

func Connect(transport Transport, timeout time.Duration) (*Client, error)

Connect establishes a connection to stereosd using the given transport. The transport determines the underlying mechanism (TCP, AF_VSOCK, etc.).

func Dial

func Dial(address string, timeout time.Duration) (*Client, error)

Dial connects to stereosd via TCP at the given address. This is a convenience wrapper around Connect with a TCPTransport. Deprecated: prefer Connect with an explicit Transport.

func (*Client) Close

func (c *Client) Close() error

Close closes the connection to stereosd.

func (*Client) GetHealth

func (c *Client) GetHealth(ctx context.Context) (*HealthPayload, error)

GetHealth requests the current health status from stereosd.

func (*Client) InjectSSHKey

func (c *Client) InjectSSHKey(ctx context.Context, user, publicKey string) error

InjectSSHKey sends a public key to stereosd for installation into the specified user's authorized_keys file. stereosd creates ~/.ssh/ if needed and writes the key with appropriate ownership and permissions.

func (*Client) InjectSecret

func (c *Client) InjectSecret(ctx context.Context, name, value string) error

InjectSecret writes a secret to the guest's tmpfs secret store.

func (*Client) Mount

func (c *Client) Mount(ctx context.Context, tag, guestPath, fsType string, readOnly bool) error

Mount requests stereosd to mount a shared directory.

func (*Client) Ping

func (c *Client) Ping(ctx context.Context) error

Ping sends a ping and waits for a pong response.

func (*Client) SetConfig

func (c *Client) SetConfig(ctx context.Context, content string) error

SetConfig sends the jcard.toml configuration to the guest. stereosd writes it to /etc/stereos/jcard.toml where agentd picks it up via its reconciliation loop.

func (*Client) Shutdown

func (c *Client) Shutdown(ctx context.Context, reason string) error

Shutdown requests a graceful shutdown of the StereOS instance.

func (*Client) WaitForReady

func (c *Client) WaitForReady(ctx context.Context, pollInterval time.Duration) error

WaitForReady polls stereosd until it reports ready or healthy state, or the context is cancelled.

type ConfigPayload

type ConfigPayload struct {
	// Content is the raw jcard.toml content to write inside the guest.
	Content string `json:"content"`
}

ConfigPayload is the payload for set_config messages.

type Envelope

type Envelope struct {
	Type    MessageType     `json:"type"`
	Payload json.RawMessage `json:"payload,omitempty"`
}

Envelope is the top-level wire format for all messages.

func NewEnvelope

func NewEnvelope(msgType MessageType, payload any) (*Envelope, error)

NewEnvelope creates an envelope with the given type and payload.

func (*Envelope) DecodePayload

func (e *Envelope) DecodePayload(target any) error

DecodePayload unmarshals the envelope's payload into the given target.

type FuncTransport

type FuncTransport struct {
	// DialFn is called by Dial to establish the connection.
	DialFn func(timeout time.Duration) (net.Conn, error)
	// Label is returned by String() for logging and error messages.
	Label string
}

FuncTransport is a Transport backed by an arbitrary dial function. It is used by the Apple Virtualization.framework backend to inject a vz.VirtioSocketDevice connection without creating an import dependency between pkg/vsock and the darwin-only vz package.

func (*FuncTransport) Dial

func (f *FuncTransport) Dial(timeout time.Duration) (net.Conn, error)

Dial calls the underlying dial function.

func (*FuncTransport) String

func (f *FuncTransport) String() string

String returns the human-readable label.

type HealthPayload

type HealthPayload struct {
	State  LifecycleState       `json:"state"`
	Agents []AgentStatusPayload `json:"agents,omitempty"`
	Uptime int64                `json:"uptime_seconds"`
}

HealthPayload is the payload for health messages.

type LifecyclePayload

type LifecyclePayload struct {
	State   LifecycleState `json:"state"`
	Message string         `json:"message,omitempty"`
}

LifecyclePayload is the payload for lifecycle messages.

type LifecycleState

type LifecycleState string

LifecycleState represents the current state of the StereOS instance.

const (
	StateBooting  LifecycleState = "booting"
	StateReady    LifecycleState = "ready"
	StateHealthy  LifecycleState = "healthy"
	StateDegraded LifecycleState = "degraded"
	StateShutdown LifecycleState = "shutdown"
)

type MessageType

type MessageType string

MessageType identifies the kind of control plane message.

const (
	// Host -> Guest messages
	MsgPing         MessageType = "ping"
	MsgInjectSecret MessageType = "inject_secret"
	MsgMount        MessageType = "mount"
	MsgShutdown     MessageType = "shutdown"
	MsgGetHealth    MessageType = "get_health"
	MsgSetConfig    MessageType = "set_config"
	MsgInjectSSHKey MessageType = "inject_ssh_key"

	// Guest -> Host messages
	MsgPong      MessageType = "pong"
	MsgLifecycle MessageType = "lifecycle"
	MsgAck       MessageType = "ack"
	MsgHealth    MessageType = "health"
)

type MountPayload

type MountPayload struct {
	Tag       string `json:"tag"`
	GuestPath string `json:"guest_path"`
	FSType    string `json:"fs_type"`
	ReadOnly  bool   `json:"read_only,omitempty"`
}

MountPayload is the payload for mount messages.

type SSHKeyPayload

type SSHKeyPayload struct {
	// User is the guest user whose authorized_keys will be updated.
	User string `json:"user"`

	// PublicKey is the SSH public key in authorized_keys format
	// (e.g. "ssh-ed25519 AAAA... comment").
	PublicKey string `json:"public_key"`
}

SSHKeyPayload is the payload for inject_ssh_key messages.

type SecretPayload

type SecretPayload struct {
	Name  string `json:"name"`
	Value string `json:"value"`
	Mode  uint32 `json:"mode,omitempty"`
}

SecretPayload is the payload for inject_secret messages.

type ShutdownPayload

type ShutdownPayload struct {
	Reason string `json:"reason,omitempty"`
}

ShutdownPayload is the payload for shutdown messages.

type TCPTransport

type TCPTransport struct {
	Host string
	Port int
}

TCPTransport connects to stereosd via TCP. This is used when native vsock is not available (macOS/HVF). QEMU's user-mode networking forwards a host TCP port to the guest port where stereosd listens.

func (*TCPTransport) Dial

func (t *TCPTransport) Dial(timeout time.Duration) (net.Conn, error)

Dial connects to stereosd via TCP.

func (*TCPTransport) String

func (t *TCPTransport) String() string

String returns the TCP address.

type Transport

type Transport interface {
	// Dial establishes a connection to stereosd with the given timeout.
	Dial(timeout time.Duration) (net.Conn, error)

	// String returns a human-readable description for logs and error messages.
	String() string
}

Transport abstracts the host-side connection to stereosd running inside a StereOS guest VM. Different backends use different transports:

• TCPTransport: connects via TCP through QEMU user-mode networking (hostfwd). Used on macOS/HVF where native vsock is unavailable.
• VsockTransport (future): connects via AF_VSOCK on Linux/KVM. Requires golang.org/x/sys/unix for socket creation.
• VirtioSerialTransport (future): connects via a chardev unix socket backed by virtio-serial. Works on macOS/HVF without guest networking.