Help us shape the future of Go! Take the 2026 Go Developer Survey

microvmmanager

package
v0.0.51 Latest Latest
Warning

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

Go to latest
Published: Oct 26, 2026 License: Apache-2.0 Imports: 30 Imported by: 0

Documentation

Overview

Package microvmmanager owns idempotent readiness and explicit diagnostics for the user-local microvmd lifecycle. It supplies safe paths and process operations without weakening microvmd's absolute-path or operator-policy validation.

Index

Constants

View Source
const (
	// GuestEgressPermissive allows unrestricted guest IPv4 egress.
	GuestEgressPermissive = "permissive"
	// GuestEgressDenyAll blocks all guest network destinations.
	GuestEgressDenyAll = "deny-all"
	// GuestEgressAllowlist permits only explicitly selected destinations.
	GuestEgressAllowlist = "allowlist"
)
View Source
const (
	// Alias is the built-in local profile selected through ordinary configuration.
	Alias = "microvm-local"
	// DarwinSocketPathLimit is kept below Darwin's sockaddr_un.sun_path bound.
	DarwinSocketPathLimit = 104
)

Variables

View Source
var (
	// ErrUnsupportedPlatform marks a host on which microvm-local cannot run.
	ErrUnsupportedPlatform = errors.New("unsupported microVM platform")
	// ErrKVMUnavailable marks missing or inaccessible Linux KVM support.
	ErrKVMUnavailable = errors.New("KVM unavailable")
)

Functions

func GuestEgressSummary

func GuestEgressSummary(selection GuestEgressSelection) string

GuestEgressSummary returns the safe operator-facing configured policy summary.

func ReportReadinessStage

func ReportReadinessStage(ctx context.Context, stage ReadinessStage)

ReportReadinessStage reports one stage to an observer carried by ctx. It is exported so command-root test doubles can preserve the observer contract.

func ValidateDeleteRequest

func ValidateDeleteRequest(request DeleteRequest) error

ValidateDeleteRequest checks the complete generation selector before any destructive confirmation is shown.

func WithReadinessObserver

func WithReadinessObserver(ctx context.Context, observer ReadinessObserver) context.Context

WithReadinessObserver returns a context that observes EnsureReady stages.

Types

type Artifact

type Artifact struct {
	Kind               string `json:"kind"`
	Reference          string `json:"reference"`
	Digest             string `json:"digest"`
	ManifestDigest     string `json:"manifest_digest,omitempty"`
	DiscoveryReference string `json:"discovery_reference,omitempty"`
	ResolutionEvidence string `json:"resolution_evidence,omitempty"`
	Platform           string `json:"platform,omitempty"`
	Path               string `json:"path"`
	Provenance         string `json:"provenance"`
	SigstoreBundle     string `json:"sigstore_bundle"`
}

Artifact is one installer-projected verified admission artifact.

type DaemonInfo

type DaemonInfo = microvmclient.DaemonInfo

DaemonInfo is the authenticated serving-daemon identity used for exact reuse.

type DefaultOperations

type DefaultOperations struct {
	HTTPClient   *http.Client
	GOOS, GOARCH string
	// contains filtered or unexported fields
}

DefaultOperations implements the real local OS, release, installer, and daemon boundary.

func (*DefaultOperations) DaemonInfo

func (*DefaultOperations) DaemonInfo(ctx context.Context, paths Paths) (DaemonInfo, error)

DaemonInfo queries the process serving the owner-only socket.

func (*DefaultOperations) Doctor

func (o *DefaultOperations) Doctor(ctx context.Context, paths Paths) (string, error)

Doctor verifies the identity of the daemon actually serving the configured socket and returns its structured, line-oriented readiness report.

func (*DefaultOperations) Download

func (o *DefaultOperations) Download(ctx context.Context, release Release, root, destination string) (string, error)

Download obtains, digest-verifies, and safely extracts one release bundle.

func (*DefaultOperations) Install

func (o *DefaultOperations) Install(ctx context.Context, manifest, root, installRoot string) (InstalledArtifacts, error)

Install executes the installer from the verified bundle.

func (*DefaultOperations) Preflight

func (o *DefaultOperations) Preflight(ctx context.Context, _ Paths) error

Preflight checks the current user's platform, required host tools, hypervisor access, and ability to create the unprivileged user namespace used at launch.

func (*DefaultOperations) Running

func (*DefaultOperations) Running(ctx context.Context, paths Paths) (bool, error)

Running reports whether an owner-only socket accepts a local connection.

func (*DefaultOperations) Start

func (*DefaultOperations) Start(_ context.Context, paths Paths) error

Start launches the installed daemon with absolute manager paths.

func (*DefaultOperations) Stop

func (*DefaultOperations) Stop(ctx context.Context, paths Paths) error

Stop gracefully stops only the exact manager-owned daemon.

func (*DefaultOperations) Verify

func (*DefaultOperations) Verify(_ context.Context, release Release, manifest string) error

Verify rechecks that the extracted manifest still belongs to the verified bundle.

func (*DefaultOperations) WaitSocket

func (*DefaultOperations) WaitSocket(ctx context.Context, socket string) error

WaitSocket waits until the daemon publishes an owner-only Unix socket.

type DeleteRequest

type DeleteRequest struct {
	SessionID  string
	Ref        string
	Generation uint32
}

DeleteRequest identifies one exact local-owner generation for permanent deletion.

type DeleteResult

type DeleteResult struct {
	WorktreePath     string
	WorktreeRetained bool
}

DeleteResult reports clean worktree removal or dirty retention.

type EgressRule

type EgressRule struct {
	Hostname string
	Port     uint16
	Protocol uint8
}

EgressRule is one daemon-enforced guest destination allowance.

type Generation

type Generation struct {
	SessionID, EnvironmentID, Ref, WorktreePath, State, Error string
	Generation                                                uint32
	Health                                                    microvmclient.GenerationHealth
}

Generation is one exact owner-scoped daemon generation.

type GuestEgressSelection

type GuestEgressSelection struct {
	Mode  string
	Allow []EgressRule
}

GuestEgressSelection is the host-operator projection of guest egress. It is intentionally not part of any public session API or project configuration surface.

func NewGuestEgressSelection

func NewGuestEgressSelection() GuestEgressSelection

NewGuestEgressSelection returns the byte-compatible default policy selection.

func ParseGuestEgressSelection

func ParseGuestEgressSelection(mode string, allow []string) (GuestEgressSelection, error)

ParseGuestEgressSelection parses settings values with the same destination grammar used by the command-line flags.

func (*GuestEgressSelection) AllowValue

func (s *GuestEgressSelection) AllowValue() flag.Value

AllowValue returns a repeatable flag.Value for --microvm-guest-allow.

func (*GuestEgressSelection) ModeValue

func (s *GuestEgressSelection) ModeValue() flag.Value

ModeValue returns a flag.Value for --microvm-guest-egress.

func (GuestEgressSelection) Validate

func (s GuestEgressSelection) Validate() error

Validate rejects incomplete or contradictory selections.

type HostPaths

type HostPaths struct {
	Home, XDGConfigHome, XDGDataHome, XDGStateHome, XDGRuntimeDir string
	UID                                                           int
	GOOS                                                          string
}

HostPaths supplies environment-independent inputs for DefaultPaths.

type InstalledArtifacts

type InstalledArtifacts struct {
	Schema    string     `json:"schema,omitempty"`
	Artifacts []Artifact `json:"artifacts"`
}

InstalledArtifacts is the existing release installer's strict projection.

type Manager

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

Manager coordinates readiness and daemon lifecycle operations.

func DefaultLocal

func DefaultLocal() (*Manager, string, error)

DefaultLocal builds the user-local manager without changing host state.

func New

func New(paths Paths, ops Operations, lifecycle ...lifecycleClient) *Manager

New constructs a manager over explicit paths and operations.

func (*Manager) Delete

func (m *Manager) Delete(ctx context.Context, request DeleteRequest) (DeleteResult, error)

Delete permanently destroys one exact generation. It never stops the daemon or removes verified installation state shared by other sessions.

func (*Manager) Doctor

func (m *Manager) Doctor(ctx context.Context) (string, error)

Doctor reports host preflight and backend health without downloading, installing, starting, or changing configuration.

func (*Manager) EnsureReady

func (m *Manager) EnsureReady(ctx context.Context, request ReadyRequest) (string, error)

EnsureReady idempotently installs or validates the configured release and starts or reuses the exact compatible daemon. The inter-process manager lock serializes the complete transaction. Readiness is observed state: this method never edits the operator settings file.

func (*Manager) HostFallbackEnabled

func (*Manager) HostFallbackEnabled() bool

HostFallbackEnabled is deliberately false: manager failures never redirect a selected microVM session to host filesystem or shell execution.

func (*Manager) Status

func (m *Manager) Status(ctx context.Context, requests ...StatusRequest) (Status, error)

Status inspects daemon configuration, health, and one owner inventory page without mutation.

type Operations

type Operations interface {
	Preflight(context.Context, Paths) error
	Download(ctx context.Context, release Release, root, destination string) (string, error)
	Verify(context.Context, Release, string) error
	Install(ctx context.Context, manifest, root, installRoot string) (InstalledArtifacts, error)
	Running(context.Context, Paths) (bool, error)
	DaemonInfo(context.Context, Paths) (DaemonInfo, error)
	Start(context.Context, Paths) error
	WaitSocket(context.Context, string) error
	Doctor(context.Context, Paths) (string, error)
	Stop(context.Context, Paths) error
}

Operations is the OS/network/process boundary. DefaultOperations is the real implementation; tests can keep the complete manager journey offline.

type Paths

type Paths struct {
	StateDir, RuntimeDir, Socket, DataDir, ConfigFile, UserSettings string
	DaemonBinary                                                    string
}

Paths are the absolute, user-owned manager paths.

func DefaultPaths

func DefaultPaths(host HostPaths) (Paths, error)

DefaultPaths resolves XDG paths without requiring any XDG variable. The runtime directory uses a short /tmp path when any derived daemon socket would exceed Darwin's Unix-socket bound.

type Policy

type Policy struct {
	PolicyRevision, CertificateIdentity, OIDCIssuer string
	PublicKey, PublicKeyIdentity                    string

	RequiredAttestations map[string]string
	GuestEgressMode      string
	GuestAllow           []EgressRule
	// contains filtered or unexported fields
}

Policy is the daemon-enforced local profile policy. Bootstrap writes it only to microvmd's strict config; the host alias contains only enabled+endpoint.

type ReadinessError

type ReadinessError struct {
	Stage ReadinessStage
	Cause error
}

ReadinessError preserves the failed transaction stage for safe public classification while retaining the detailed cause for diagnostics.

func (*ReadinessError) Error

func (e *ReadinessError) Error() string

func (*ReadinessError) Unwrap

func (e *ReadinessError) Unwrap() error

type ReadinessFailure

type ReadinessFailure struct {
	Stage, Category, Cause string
}

ReadinessFailure is the bounded, path-free projection suitable for clients.

func ClassifyReadinessFailure

func ClassifyReadinessFailure(err error, fallback ReadinessStage) ReadinessFailure

ClassifyReadinessFailure reduces a detailed readiness error to a closed public category and constant actionable cause. The original error remains diagnostics-only.

type ReadinessObserver

type ReadinessObserver func(ReadinessStage, string)

ReadinessObserver receives only closed stage identifiers and constant display text. Release metadata, paths, credentials, and process output are never sent.

type ReadinessStage

type ReadinessStage string

ReadinessStage is one bounded, secret-free phase of EnsureReady.

const (
	StagePrepare   ReadinessStage = "prepare"
	StagePreflight ReadinessStage = "preflight"
	StageDownload  ReadinessStage = "download"
	StageVerify    ReadinessStage = "verify"
	StageInstall   ReadinessStage = "install"
	StageDaemon    ReadinessStage = "daemon"
	StageSocket    ReadinessStage = "socket"
	StageHealth    ReadinessStage = "health"
	StageReady     ReadinessStage = "ready"
)

Readiness stages are emitted in transaction order.

type ReadyRequest

type ReadyRequest struct {
	Release Release
	Policy  Policy
}

ReadyRequest identifies the manager-owned release and daemon policy that ordinary use must converge before provisioning a microVM environment.

func ReadyRequestFromDefaults

func ReadyRequestFromDefaults(encoded, version string, egress ...GuestEgressSelection) (ReadyRequest, error)

ReadyRequestFromDefaults validates one release-generated defaults projection and overlays an optional, already operator-selected guest-egress policy.

type Release

type Release struct {
	URL, SHA256 string
	// contains filtered or unexported fields
}

Release identifies a bundle by an immutable, out-of-band SHA-256 digest.

type ReleaseDefaults

type ReleaseDefaults struct {
	Version             string `json:"version"`
	Platform            string `json:"platform"`
	URL                 string `json:"url"`
	SHA256              string `json:"sha256"`
	PolicyRevision      string `json:"policy_revision"`
	CertificateIdentity string `json:"certificate_identity"`
	OIDCIssuer          string `json:"oidc_issuer"`
}

ReleaseDefaults is the release-generated projection embedded in production composition roots.

type Status

type Status struct {
	Configured, Running bool
	Socket              string
	GuestEgress         string
	Generations         []Generation
	Continuation        string
}

Status reports manager state without starting or recreating anything.

type StatusRequest

type StatusRequest struct {
	PageSize     int
	Continuation string
}

StatusRequest selects one bounded daemon inventory page.

Jump to

Keyboard shortcuts

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