microvm

package module
v0.0.0-...-bd78618 Latest Latest
Warning

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

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

Documentation

Overview

Package microvm is the opt-in microVM environment runtime: the libkrun-backed repository VM backend and the local lifecycle daemon (mecatl-microvmd) that creates, attaches, and executes in repository-scoped guest VMs.

Index

Constants

View Source 
const (
	// Kind is the durable microVM environment kind.
	Kind = "microvm"
	// GuestPrebootConfigPath is the guest's immutable repository boot config path.
	GuestPrebootConfigPath = "/etc/mecatl/guest-agent.json"
)
View Source 
const LifecycleProtocolVersion uint16 = 4

LifecycleProtocolVersion is the local microvmd management protocol version.

View Source 
const (

	// RepositoryGuestMountRoot is the only guest namespace containing logical worktrees.
	RepositoryGuestMountRoot = "/run/mecatl/repositories"
)

Variables

View Source 
var (
	// ErrMutableArtifact rejects references that are not digest-pinned.
	ErrMutableArtifact = errors.New("microvm artifact is not pinned to an immutable digest")
	// ErrDigestMismatch rejects resolver output that differs from the requested digest.
	ErrDigestMismatch = errors.New("microvm artifact digest mismatch")
	// ErrUnverifiedArtifact rejects evidence that does not satisfy operator policy.
	ErrUnverifiedArtifact = errors.New("microvm artifact verification failed")
	// ErrCorruptCacheEntry rejects cache payload or metadata corruption.
	ErrCorruptCacheEntry = errors.New("verified artifact cache entry is corrupt")
	// ErrStalePolicy rejects an entry admitted under another policy revision.
	ErrStalePolicy = errors.New("verified artifact cache entry uses a stale policy")
)
View Source 
var (
	// ErrLaunchOwnershipUnsupported reports that durable runner ownership is not available on this platform.
	ErrLaunchOwnershipUnsupported = errors.New("durable microvm launch ownership is unsupported on this platform")
	// ErrLaunchOwnershipUncertain means a process may still own the retained VM state and was not signalled.
	ErrLaunchOwnershipUncertain = errors.New("microvm launch ownership is uncertain")
	// ErrLaunchReceiptPending means the launcher owns the attempt lock but has not durably published its receipt yet.
	ErrLaunchReceiptPending = errors.New("microvm launch receipt is pending")
)
View Source 
var (
	// ErrRepositoryVMUnknown means no generation has been admitted for the repository key.
	ErrRepositoryVMUnknown = errors.New("microvm repository generation is unknown")
	// ErrRepositoryVMInconsistent means the durable singleton cannot be reattached exactly.
	ErrRepositoryVMInconsistent = errors.New("microvm repository generation is inconsistent")
	// ErrRepositoryLogicalRootUnavailable means the authenticated guest could not
	// attach the assigned repository worktree. It intentionally carries no backend detail.
	ErrRepositoryLogicalRootUnavailable = errors.New("microvm repository logical root is unavailable")
)
View Source 
var (
	// ErrInvalidEnvironmentRef reports a malformed logical generation ref.
	ErrInvalidEnvironmentRef = errors.New("invalid microvm environment ref")
	// ErrEnvironmentUnavailable reports a repository generation that is not live.
	ErrEnvironmentUnavailable = errors.New("microvm environment generation is not live")
	// ErrInvalidFork reports a mismatched repository child.
	ErrInvalidFork = errors.New("invalid microvm child environment")
	// ErrMergeConflict reports parent/child overlap.
	ErrMergeConflict = errors.New("microvm child environment merge conflict")
)

Functions

func ArtifactTreeDigest 

func ArtifactTreeDigest(root string) (string, error)

ArtifactTreeDigest returns the canonical materialized-tree identity used by strict artifact admission and release provenance subjects.

func ProcessStartIdentity 

func ProcessStartIdentity(ctx context.Context, pid int) (string, error)

ProcessStartIdentity returns the platform process-start token used to distinguish PID reuse.

func PublicKeyIdentity 

func PublicKeyIdentity(publicKey []byte) string

PublicKeyIdentity returns the stable identity operator policy binds to exact public-key bytes.

func RunLaunchOwnerChild 

func RunLaunchOwnerChild(args []string) (bool, error)

RunLaunchOwnerChild handles the hidden launcher mode before normal daemon flag parsing.

func UnixGuestDialer 

func UnixGuestDialer(ctx context.Context, endpoint string) (io.ReadWriteCloser, error)

UnixGuestDialer opens a pre-existing host endpoint.

Types

type ArtifactKind 

type ArtifactKind string

ArtifactKind identifies one executable input to a microVM. 

const (
	// ArtifactRuntime is the go-microvm runner and libkrun bundle.
	ArtifactRuntime ArtifactKind = "runtime"
	// ArtifactFirmware is the libkrunfw bundle.
	ArtifactFirmware ArtifactKind = "firmware"
	// ArtifactExecutionImage is the admitted Brood guest root filesystem.
	ArtifactExecutionImage ArtifactKind = "execution-image"
	// ArtifactGuestAgent is the independently built guest protocol binary.
	ArtifactGuestAgent ArtifactKind = "guest-agent"
)

type ArtifactRequest 

type ArtifactRequest struct {
	Kind               ArtifactKind
	Reference          string
	Digest             string
	ManifestDigest     string
	DiscoveryReference string
	ResolutionEvidence string
	Platform           string
}

ArtifactRequest is an operator-resolved artifact reference. Digest must be a canonical sha256 digest; Reference is retained only for resolver lookup.

type ArtifactResolver 

type ArtifactResolver interface {
	Resolve(context.Context, ArtifactRequest) (ResolvedArtifact, error)
}

ArtifactResolver resolves a digest-pinned reference without granting it cache or execution authority.

type ArtifactVerifier 

type ArtifactVerifier interface {
	Verify(context.Context, map[ArtifactKind]ArtifactRequest) (VerifiedArtifacts, string, error)
}

ArtifactVerifier verifies a complete daemon-owned artifact request set.

type Attestation 

type Attestation struct {
	PredicateType string `json:"predicate_type"`
	SubjectDigest string `json:"subject_digest"`
	Statement     []byte `json:"statement"`
}

Attestation is a signed in-toto statement binding an artifact digest to a predicate.

type ChildForkPayload 

type ChildForkPayload struct {
	Label string `json:"label"`
}

ChildForkPayload is the bounded descriptive input for a child fork.

type ChildMergePayload 

type ChildMergePayload struct {
	Child              control.Binding `json:"child"`
	ChildAcquisitionID string          `json:"child_acquisition_id"`
}

ChildMergePayload identifies the exact child generation merged into Binding.

type Daemon 

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

Daemon owns the local management protocol. Hypervisor creation remains exclusively behind Lifecycle -> VMRuntime.

func NewDaemon 

func NewDaemon(cfg DaemonConfig) (*Daemon, error)

NewDaemon constructs the fail-closed local lifecycle service.

func (*Daemon) Handle 

func (d *Daemon) Handle(ctx context.Context, conn net.Conn, request LifecycleRequest) LifecycleResponse

Handle authenticates the peer before examining any caller-controlled identity, then binds the operation to the authoritative durable registry record.

func (*Daemon) ServeConn 

func (d *Daemon) ServeConn(ctx context.Context, conn net.Conn) error

ServeConn authenticates the peer and serves either one bounded operation or one retained acquisition followed by its terminal release frame.

type DaemonConfig 

type DaemonConfig struct {
	Control                *control.Service
	Observer               *OperationsObserver
	Info                   DaemonInfo
	RepositoryAttachments  *RepositoryAttachmentManager
	RepositoryProvisioner  RepositoryPlacementBuilder
	RepositoryStartupError error
}

DaemonConfig wires the authenticated protocol to durable lifecycle seams.

type DaemonInfo 

type DaemonInfo struct {
	ProtocolVersion uint16   `json:"protocol_version"`
	ReleaseIdentity string   `json:"release_identity"`
	BinaryIdentity  string   `json:"binary_identity"`
	ConfigDigest    string   `json:"config_digest"`
	PolicyRevision  string   `json:"policy_revision"`
	Profiles        []string `json:"profiles"`
	Socket          string   `json:"socket"`
}

DaemonInfo is the authenticated identity of the process serving this socket.

func (DaemonInfo) Equal 

func (d DaemonInfo) Equal(other DaemonInfo) bool

Equal reports an exact compatibility match, including profile order.

type Doctor 

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

Doctor checks whether the repository runtime can accept work.

func NewDoctor 

func NewDoctor(checker ReadinessChecker) *Doctor

NewDoctor constructs an operator readiness path.

func (*Doctor) Run 

func (d *Doctor) Run(ctx context.Context) ReadinessReport

Run executes every readiness probe without hiding later failures.

type EgressDestination 

type EgressDestination struct {
	Hostname string
	Port     uint16
	Protocol EgressProtocol
}

EgressDestination identifies one guest-visible hostname, port and protocol.

type EgressMode 

type EgressMode string

EgressMode is the closed guest-network policy mode. 

const (
	// EgressPermissive permits unrestricted IPv4 guest egress. The guest IPv6
	// stack remains enabled, but go-microvm's hosted topology does not route
	// external IPv6. It is also the zero-value and built-in profile default.
	EgressPermissive EgressMode = "permissive"
	// EgressDenyAll permits no guest destination.
	EgressDenyAll EgressMode = "deny-all"
	// EgressAllowlist permits only explicitly listed destinations.
	EgressAllowlist EgressMode = "allowlist"
)

type EgressProtocol 

type EgressProtocol uint8

EgressProtocol is an IP transport protocol accepted by go-microvm's filter. 

const (
	// ProtocolTCP permits only TCP for a destination.
	ProtocolTCP EgressProtocol = 6
	// ProtocolUDP permits only UDP for a destination.
	ProtocolUDP EgressProtocol = 17
)

type EnforcedProfileStatus 

type EnforcedProfileStatus struct{ Profile, GuestEgress, HostEgress string }

EnforcedProfileStatus is the daemon-authoritative placement policy projection.

type EnvironmentMetadata 

type EnvironmentMetadata struct {
	SessionID       string
	VMID            string
	Artifacts       map[ArtifactKind]string
	ManifestDigests map[ArtifactKind]string
	PolicyRevision  string
}

EnvironmentMetadata is the durable artifact-verification portion of an environment record.

type EnvironmentRef 

type EnvironmentRef struct{ Kind, ID string }

EnvironmentRef is the daemon-internal logical generation identity.

type EnvironmentState 

type EnvironmentState string

EnvironmentState is the durable repository generation state. 

const (
	// EnvironmentProvisioning means first-generation admission has begun.
	EnvironmentProvisioning EnvironmentState = "provisioning"
	// EnvironmentReady means the exact repository generation is healthy.
	EnvironmentReady EnvironmentState = "ready"
	// EnvironmentDestroyed is the inventory projection for a removed attachment.
	EnvironmentDestroyed EnvironmentState = "destroyed"
)

type EvidenceVerifier 

type EvidenceVerifier interface {
	Verify(context.Context, []byte, []byte, string, string) error
}

EvidenceVerifier verifies a Sigstore bundle against exact operator-owned identity policy.

type GoMicroVMBackend 

type GoMicroVMBackend interface {
	Start(context.Context, GoMicroVMLaunch) (GoMicroVMInstance, error)
}

GoMicroVMBackend is the repository hypervisor seam.

type GoMicroVMInstance 

type GoMicroVMInstance interface {
	WaitReady(context.Context) error
	Status(context.Context) (RuntimeStatus, error)
	Stop(context.Context) error
	CleanupBoot(context.Context) error
}

GoMicroVMInstance is the concrete repository runtime handle retained by microvmd.

type GoMicroVMLaunch 

type GoMicroVMLaunch struct {
	EnvironmentID       string
	VMID                string
	Endpoint            string
	Generation          uint32
	PlacementGeneration uint32
	RepositoryOwner     string
	RepositoryKey       string
	RuntimePath         string
	FirmwarePath        string
	ImagePath           string
	NetworkSocket       string
	Network             gomicrovmnet.Provider
	VsockPort           uint32
	Mounts              []gomicrovm.VirtioFSMount
	CapabilityKey       []byte
	Verified            bool
	HostReadOnly        bool
	DisableIPv6         bool
}

GoMicroVMLaunch is the fully resolved, verified repository launch description handed to the hypervisor backend.

type GuestDialer 

type GuestDialer func(context.Context, string) (io.ReadWriteCloser, error)

GuestDialer opens the one vsock-backed host endpoint for a guest generation.

type GuestEgressPolicy 

type GuestEgressPolicy struct {
	Mode  EgressMode
	Allow []EgressDestination
}

GuestEgressPolicy is operator-resolved policy for guest processes only.

func (GuestEgressPolicy) Status 

func (p GuestEgressPolicy) Status() string

Status returns the daemon-authored response-safe summary of enforced guest egress.

type GuestNetworkConfigurator 

type GuestNetworkConfigurator interface {
	DisableIPv6(context.Context) error
}

GuestNetworkConfigurator applies guest-side settings required by tightening modes because go-microvm v0.0.41's frame filter is IPv4-only.

type GuestPrebootConfig 

type GuestPrebootConfig struct {
	DisableIPv6     bool                 `json:"disable_ipv6"`
	AgentEndpoint   string               `json:"agent_endpoint"`
	Binding         control.Binding      `json:"binding"`
	Capabilities    control.Capabilities `json:"capabilities"`
	MaxMessageBytes uint32               `json:"max_message_bytes"`
}

GuestPrebootConfig is the immutable config consumed by the guest agent.

type LaunchOwnership 

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

LaunchOwnership is the concrete host-only launch owner used by microvmd.

func NewLaunchOwnership 

func NewLaunchOwnership(cfg LaunchOwnershipConfig) (*LaunchOwnership, error)

NewLaunchOwnership opens a private host-only launch root and pins the exact launcher identity.

func (*LaunchOwnership) Reconcile 

func (o *LaunchOwnership) Reconcile(ctx context.Context, environmentID string) (LaunchReconcileResult, error)

Reconcile proves every prior attempt dead or terminates its exact pidfd-owned runner.

func (*LaunchOwnership) Spawner 

func (o *LaunchOwnership) Spawner(environmentID string) runner.Spawner

Spawner returns the go-microvm spawner bound to one repository environment.

type LaunchOwnershipConfig 

type LaunchOwnershipConfig struct {
	Root         string
	LauncherPath string
	ReceiptWait  time.Duration
	TermTimeout  time.Duration
	KillTimeout  time.Duration
}

LaunchOwnershipConfig configures the concrete host runner launch owner.

type LaunchReceipt 

type LaunchReceipt struct {
	Version        int    `json:"version"`
	EnvironmentID  string `json:"environment_id"`
	LaunchID       string `json:"launch_id"`
	HostBootID     string `json:"host_boot_id"`
	PID            int    `json:"pid"`
	StartTime      string `json:"start_time"`
	RunnerDigest   string `json:"runner_digest"`
	RunnerDevice   uint64 `json:"runner_device"`
	RunnerInode    uint64 `json:"runner_inode"`
	LauncherDigest string `json:"launcher_digest"`
	LauncherDevice uint64 `json:"launcher_device"`
	LauncherInode  uint64 `json:"launcher_inode"`
	LockDevice     uint64 `json:"lock_device"`
	LockInode      uint64 `json:"lock_inode"`
}

LaunchReceipt is the durable identity written by the launcher before it execs the VM runner.

type LaunchReconcileResult 

type LaunchReconcileResult struct {
	Dead       int
	Terminated int
}

LaunchReconcileResult describes attempts proven dead or terminated through exact pidfds.

type Launcher 

type Launcher interface {
	Launch(context.Context, VerifiedArtifacts) (vmID string, err error)
}

Launcher is the narrow handoff to the later VM lifecycle implementation.

type LibkrunBackend 

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

LibkrunBackend is the production repository go-microvm backend.

func NewLibkrunBackend 

func NewLibkrunBackend(ownedArtifactDir string, ownership *LaunchOwnership) (*LibkrunBackend, error)

NewLibkrunBackend constructs the production backend. ownedArtifactDir is an executable daemon-owned filesystem used to retain runtime libraries for the VM lifetime. Repository backends require durable launch ownership so every provisioned VM can be reconciled after the daemon restarts.

func (*LibkrunBackend) Reconcile 

func (b *LibkrunBackend) Reconcile(ctx context.Context, environmentID string) (LaunchReconcileResult, error)

Reconcile delegates stable repository launch reconciliation to the Linux owner.

func (*LibkrunBackend) Start 

func (b *LibkrunBackend) Start(ctx context.Context, launch GoMicroVMLaunch) (GoMicroVMInstance, error)

Start launches the repository VM with explicit rootfs, network, vsock, and host-enforced read-only Git object mounts.

type LifecycleCreated 

type LifecycleCreated struct {
	Ref          EnvironmentRef `json:"ref"`
	Generation   uint32         `json:"generation"`
	HostWorktree string         `json:"host_worktree"`
	GuestRoot    string         `json:"guest_root"`
	Profile      string         `json:"profile"`
	GuestEgress  string         `json:"guest_egress"`
	HostEgress   string         `json:"host_egress"`
}

LifecycleCreated is the non-resource-handle create result carried on the wire.

type LifecycleDeleteResult 

type LifecycleDeleteResult struct {
	WorktreePath     string `json:"worktree_path"`
	WorktreeRetained bool   `json:"worktree_retained"`
}

LifecycleDeleteResult reports whether the exact generation's worktree was removed.

type LifecycleExecStream 

type LifecycleExecStream struct {
	Channel string `json:"channel"`
	Data    []byte `json:"data"`
}

LifecycleExecStream is one ordered stdout or stderr chunk preceding the final response.

type LifecycleGenerationHealth 

type LifecycleGenerationHealth string

LifecycleGenerationHealth is the operator-facing health of one exact generation. 

const (
	// GenerationHealthy means the exact runtime identity is live.
	GenerationHealthy LifecycleGenerationHealth = "healthy"
	// GenerationStale means the durable generation is not currently reattachable.
	GenerationStale LifecycleGenerationHealth = "stale"
	// GenerationError means the runtime health probe itself failed.
	GenerationError LifecycleGenerationHealth = "error"
)

type LifecycleInventoryEntry 

type LifecycleInventoryEntry struct {
	Owner         string                    `json:"owner"`
	SessionID     string                    `json:"session_id"`
	EnvironmentID string                    `json:"environment_id"`
	Ref           string                    `json:"ref"`
	WorktreePath  string                    `json:"worktree_path"`
	Generation    uint32                    `json:"generation"`
	State         EnvironmentState          `json:"state"`
	Health        LifecycleGenerationHealth `json:"health"`
	Error         string                    `json:"error,omitempty"`
}

LifecycleInventoryEntry is the bounded, non-secret lifecycle projection.

type LifecycleInventoryPage 

type LifecycleInventoryPage struct {
	Entries      []LifecycleInventoryEntry `json:"entries"`
	Continuation string                    `json:"continuation,omitempty"`
}

LifecycleInventoryPage is one bounded page and its opaque continuation.

type LifecycleInventoryRequest 

type LifecycleInventoryRequest struct {
	PageSize     int    `json:"page_size,omitempty"`
	Continuation string `json:"continuation,omitempty"`
}

LifecycleInventoryRequest asks for one deterministic owner-scoped page.

type LifecycleOperation 

type LifecycleOperation string

LifecycleOperation is one closed management operation. 

const (
	// LifecycleInfo returns the authenticated serving daemon identity and loaded policy.
	LifecycleInfo LifecycleOperation = "info"
	// LifecycleCreate provisions and durably registers one new generation.
	LifecycleCreate LifecycleOperation = "create"
	// LifecycleResolve reattaches one exact ready generation.
	LifecycleResolve LifecycleOperation = "resolve"
	// LifecycleInspect verifies one exact ready runtime identity.
	LifecycleInspect LifecycleOperation = "inspect"
	// LifecycleDetach drops process-local handles without changing durable state.
	LifecycleDetach LifecycleOperation = "detach"
	// LifecycleDelete tombstones and destroys one exact generation.
	LifecycleDelete LifecycleOperation = "delete"
	// LifecycleWorkspace proxies bounded guest filesystem calls.
	LifecycleWorkspace LifecycleOperation = "workspace"
	// LifecycleExec proxies bounded guest command execution.
	LifecycleExec LifecycleOperation = "exec"
	// LifecycleFork creates one isolated child generation from the bound parent.
	LifecycleFork LifecycleOperation = "fork"
	// LifecycleMerge conflict-checks and applies one bound child to its parent.
	LifecycleMerge LifecycleOperation = "merge"
	// LifecycleMetrics exports the fixed-dimension operations snapshot.
	LifecycleMetrics LifecycleOperation = "metrics"
	// LifecycleInventory returns one bounded owner-filtered generation inventory.
	LifecycleInventory LifecycleOperation = "inventory"
	// LifecycleChildDelete force-cleans an exact delegated child generation.
	LifecycleChildDelete LifecycleOperation = "child-delete"
)

type LifecycleRequest 

type LifecycleRequest struct {
	Version       uint16             `json:"version"`
	Operation     LifecycleOperation `json:"operation"`
	Binding       control.Binding    `json:"binding"`
	AcquisitionID string             `json:"acquisition_id,omitempty"`
	Provision     *ProvisionRequest  `json:"provision,omitempty"`
	Payload       json.RawMessage    `json:"payload,omitempty"`
}

LifecycleRequest is one bounded request on the authenticated daemon socket. Create, resolve, and fork retain their connection until terminal release and return an AcquisitionID. Workspace, exec, fork, and merge requests require a live acquisition and its complete Binding. Detach and owned deletion must use the acquisition's retained connection. Those are the lifecycle v4 exchange rules.

type LifecycleResponse 

type LifecycleResponse struct {
	Binding       control.Binding      `json:"binding,omitempty"`
	AcquisitionID string               `json:"acquisition_id,omitempty"`
	Created       *LifecycleCreated    `json:"created,omitempty"`
	Stream        *LifecycleExecStream `json:"stream,omitempty"`
	Payload       json.RawMessage      `json:"payload,omitempty"`
	ErrorCode     string               `json:"error_code,omitempty"`
	ErrorText     string               `json:"error,omitempty"`
	Err           error                `json:"-"`
}

LifecycleResponse reports the exact durable generation observed after an operation.

type LogicalEnvironment 

type LogicalEnvironment struct {
	Repository   RepositoryVMRecord
	Binding      control.Binding
	Ref          EnvironmentRef
	WorktreePath string
	SourceRoot   string
	GuestRoot    string
	MetadataPath string
	IndexPath    string
	Branch       string
	Workspace    *workspace.Workspace
	Runner       *guestexec.Runner
	// contains filtered or unexported fields
}

LogicalEnvironment is one authenticated Workspace/runner pair in a shared repository VM.

func (*LogicalEnvironment) Close 

func (e *LogicalEnvironment) Close() error

Close detaches process-local protocol handles and removes only this logical worktree. It never stops the repository VM or removes its rootfs.

func (*LogicalEnvironment) DeletePreservingDirty 

func (e *LogicalEnvironment) DeletePreservingDirty(ctx context.Context) (bool, error)

DeletePreservingDirty detaches the logical environment and removes only a clean worktree. Dirty state remains at the reported worktree path for operator recovery.

func (*LogicalEnvironment) Detach 

func (e *LogicalEnvironment) Detach() error

Detach closes process-local streams independently and retries remote teardown until the guest confirms it.

func (*LogicalEnvironment) DetachContext 

func (e *LogicalEnvironment) DetachContext(ctx context.Context) error

DetachContext performs retryable, serialized remote teardown.

type LogicalEnvironmentRequest 

type LogicalEnvironmentRequest struct {
	Owner        string
	Checkout     string
	Artifacts    RepositoryArtifactSnapshot
	BaseRevision string
}

LogicalEnvironmentRequest selects a repository singleton and asks for one distinct logical Git worktree in it.

type MetadataStore 

type MetadataStore interface {
	Save(context.Context, EnvironmentMetadata) error
}

MetadataStore durably records the artifact identities used by a launched VM.

type NetworkController 

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

NetworkController configures the selected provider. Permissive mode leaves the guest IPv6 stack enabled, although hosted external IPv6 is unrouted and unsupported. Selected tightening additionally closes the provider's IPv6 filtering gap before readiness succeeds.

func NewHostedBootNetworkController 

func NewHostedBootNetworkController() *NetworkController

NewHostedBootNetworkController selects hosted IPv4 filtering when the guest image applies IPv6 policy before starting its authenticated control service. The owning runtime must verify that service before reporting readiness.

func NewHostedNetworkController 

func NewHostedNetworkController(guest GuestNetworkConfigurator) *NetworkController

NewHostedNetworkController selects go-microvm's in-process hosted provider.

func NewNetworkController 

func NewNetworkController(provider NetworkProviderFactory, guest GuestNetworkConfigurator) *NetworkController

NewNetworkController builds a controller around an explicit provider selection. A nil or failed provider is an error; there is no implicit path.

func (*NetworkController) Start 

func (c *NetworkController) Start(ctx context.Context, policy GuestEgressPolicy) (NetworkHandle, error)

Start validates and starts the selected provider with deny-default filtering, then requires either immediate guest IPv6 disablement or an explicit boot-time enforcement contract. Any immediate enforcement failure stops the provider.

func (*NetworkController) StartForDoctor 

func (c *NetworkController) StartForDoctor(ctx context.Context, policy GuestEgressPolicy, runtimeDir string) (NetworkHandle, error)

StartForDoctor exercises the production provider in a caller-owned private runtime directory, then returns the live handle for immediate teardown.

type NetworkHandle 

type NetworkHandle struct {
	SocketPath  string
	Provider    gomicrovmnet.Provider
	GuestEgress string
}

NetworkHandle is the configured provider endpoint handed to VM creation.

type NetworkProviderFactory 

type NetworkProviderFactory func() gomicrovmnet.Provider

NetworkProviderFactory selects the hosted provider used by an environment.

type OCIExecutionImageResolver 

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

OCIExecutionImageResolver pulls a platform-specific digest-pinned OCI image through go-microvm and exposes only its extracted tree to artifact admission.

func NewOCIExecutionImageResolver 

func NewOCIExecutionImageResolver(cacheRoot string, fetcher gomicrovmimage.ImageFetcher, evidence map[string]VerificationEvidence) *OCIExecutionImageResolver

NewOCIExecutionImageResolver constructs an OCI execution-image resolver. cacheRoot is go-microvm's pull/extract cache; mecatl's verified cache remains a separate admission boundary. The versioned child leaves mode-dependent entries produced by older daemons unreachable rather than trusting them.

func (*OCIExecutionImageResolver) Resolve 

func (r *OCIExecutionImageResolver) Resolve(ctx context.Context, request ArtifactRequest) (ResolvedArtifact, error)

Resolve implements ArtifactResolver. Digest is the expected extracted-tree identity; ManifestDigest is the independent OCI manifest identity.

type OperationsObserver 

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

OperationsObserver records repository microVM operator facts without retaining commands, destinations, paths, bindings, or credentials.

func NewOperationsObserver 

func NewOperationsObserver(diag port.Diagnostics) *OperationsObserver

NewOperationsObserver constructs repository runtime metrics and diagnostics.

func (*OperationsObserver) ArtifactVerification 

func (o *OperationsObserver) ArtifactVerification(kind ArtifactKind, outcome Outcome)

ArtifactVerification records a closed-dimension verification outcome.

func (*OperationsObserver) CleanupFinished 

func (o *OperationsObserver) CleanupFinished(outcome Outcome)

CleanupFinished records logical attachment cleanup.

func (*OperationsObserver) ExecFinished 

func (o *OperationsObserver) ExecFinished(outcome Outcome, _ string)

ExecFinished records one repository guest execution.

func (*OperationsObserver) LifecycleRequestFailed 

func (o *OperationsObserver) LifecycleRequestFailed(err error)

LifecycleRequestFailed retains only closed request metadata and a classified cause.

func (*OperationsObserver) Snapshot 

func (o *OperationsObserver) Snapshot() OperationsSnapshot

Snapshot returns a deep-copy operator metric view.

type OperationsSnapshot 

type OperationsSnapshot struct {
	Execs                 uint64
	EgressDenials         uint64
	ArtifactVerifications map[ArtifactKind]map[Outcome]uint64
	Cleanups              map[Outcome]uint64
}

OperationsSnapshot is the bounded-cardinality repository runtime metric set.

type Outcome 

type Outcome uint8

Outcome is the closed metric outcome dimension. 

const (
	// OutcomeSuccess records completed operational work.
	OutcomeSuccess Outcome = iota + 1
	// OutcomeFailure records failed operational work.
	OutcomeFailure
)

func (Outcome) String 

func (o Outcome) String() string

type ProvisionRequest 

type ProvisionRequest struct {
	Owner          string `json:"owner"`
	SessionID      string `json:"session_id"`
	Profile        string `json:"profile"`
	SourceCheckout string `json:"source_checkout"`
}

ProvisionRequest is the thin root-module create shape. The daemon expands operator-owned artifact and resource policy before entering Lifecycle.Create.

type Provisioner 

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

Provisioner verifies a complete artifact set before crossing the launch seam.

func NewProvisioner 

func NewProvisioner(cache *VerifiedCache, resolver ArtifactResolver, policy TrustPolicy, launcher Launcher, metadata MetadataStore, observers ...*OperationsObserver) *Provisioner

NewProvisioner constructs the artifact-gated launch coordinator.

func (*Provisioner) LockAndValidate 

func (p *Provisioner) LockAndValidate(ctx context.Context, artifacts VerifiedArtifacts) (VerifiedArtifacts, func(), error)

LockAndValidate revalidates admitted bytes while holding every corresponding cache lock, then copies them into one private launch snapshot. The caller must pass the returned identities to runtime and release them only after runtime has consumed their paths. Cache-path mutation cannot alter the snapshot bytes.

func (*Provisioner) Provision 

func (p *Provisioner) Provision(ctx context.Context, sessionID string, requests map[ArtifactKind]ArtifactRequest) (EnvironmentMetadata, error)

Provision admits the complete artifact set, launches it, and records the immutable identities and policy revision used by that VM.

func (*Provisioner) Verify 

func (p *Provisioner) Verify(ctx context.Context, requests map[ArtifactKind]ArtifactRequest) (VerifiedArtifacts, string, error)

Verify admits the complete artifact set without crossing the VM launch seam. It returns the policy revision that admitted the immutable identities.

type ReadinessCheck 

type ReadinessCheck string

ReadinessCheck names one repository runtime prerequisite. 

const (
	// CheckHypervisor verifies the host virtualization facility.
	CheckHypervisor ReadinessCheck = "hypervisor"
	// CheckRuntime verifies the runtime artifact.
	CheckRuntime ReadinessCheck = "runtime-artifact"
	// CheckFirmware verifies the firmware artifact.
	CheckFirmware ReadinessCheck = "firmware-artifact"
	// CheckControlSocket verifies the authenticated daemon socket.
	CheckControlSocket ReadinessCheck = "control-socket"
	// CheckNetwork verifies hosted guest networking.
	CheckNetwork ReadinessCheck = "network-provider"
	// CheckProfiles verifies daemon-owned placement aliases.
	CheckProfiles ReadinessCheck = "profiles"
)

type ReadinessChecker 

type ReadinessChecker interface {
	Check(context.Context, ReadinessCheck) error
	Profiles(context.Context) ([]string, error)
}

ReadinessChecker supplies platform and configured-runtime probes.

type ReadinessReport 

type ReadinessReport struct{ Results []ReadinessResult }

ReadinessReport is the stable ordered doctor output.

func (ReadinessReport) Ready 

func (r ReadinessReport) Ready() bool

Ready reports whether every prerequisite passed.

func (ReadinessReport) Result 

func (r ReadinessReport) Result(check ReadinessCheck) (ReadinessResult, bool)

Result returns the named doctor result.

func (ReadinessReport) String 

func (r ReadinessReport) String() string

String renders stable line-oriented operator output.

type ReadinessResult 

type ReadinessResult struct {
	Check       ReadinessCheck
	Status      ReadinessStatus
	Detail      string
	Remediation string
}

ReadinessResult is one actionable doctor finding.

type ReadinessStatus 

type ReadinessStatus string

ReadinessStatus is the closed doctor result status. 

const (
	// ReadinessPass means the prerequisite is ready.
	ReadinessPass ReadinessStatus = "PASS"
	// ReadinessFail means the prerequisite blocks startup.
	ReadinessFail ReadinessStatus = "FAIL"
)

type RepositoryArtifactIdentity 

type RepositoryArtifactIdentity struct {
	Kind               ArtifactKind `json:"kind"`
	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"`
}

RepositoryArtifactIdentity is the durable immutable identity of one admitted launch artifact. Path points at the repository-private retained copy.

type RepositoryArtifactSet 

type RepositoryArtifactSet struct {
	Runtime        RepositoryArtifactIdentity `json:"runtime"`
	Firmware       RepositoryArtifactIdentity `json:"firmware"`
	ExecutionImage RepositoryArtifactIdentity `json:"execution_image"`
	GuestAgent     RepositoryArtifactIdentity `json:"guest_agent"`
}

RepositoryArtifactSet is the complete durable admitted launch set.

func (RepositoryArtifactSet) ByKind 

func (s RepositoryArtifactSet) ByKind(kind ArtifactKind) RepositoryArtifactIdentity

ByKind returns the retained identity for kind, or its zero value.

type RepositoryArtifactSnapshot 

type RepositoryArtifactSnapshot func(context.Context) (VerifiedArtifacts, func(), error)

RepositoryArtifactSnapshot returns a privately locked artifact view and its release. On error, the callback owns cleanup for anything it acquired and returns no cleanup responsibility to Ensure. On success, it returns a non-nil release function; Ensure invokes that function exactly once after every later success or failure, after rootfs materialization and runtime startup have finished consuming the snapshot.

type RepositoryAttachment 

type RepositoryAttachment struct {
	Logical     *LogicalEnvironment
	Environment tool.Environment
	// contains filtered or unexported fields
}

RepositoryAttachment is one session or isolated-child handle on a logical worktree in a repository-scoped VM.

func (*RepositoryAttachment) Close 

func (a *RepositoryAttachment) Close() error

Close detaches only this logical environment and its process-local handles.

type RepositoryAttachmentManager 

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

RepositoryAttachmentManager adapts repository logical worktrees to session attachment and the engine's existing isolated-child fork/merge seams.

func (*RepositoryAttachmentManager) Attach 

func (m *RepositoryAttachmentManager) Attach(ctx context.Context, request LogicalEnvironmentRequest) (*RepositoryAttachment, error)

Attach allocates a distinct logical worktree in the canonical repository VM.

func (*RepositoryAttachmentManager) Detach 

func (m *RepositoryAttachmentManager) Detach(ref session.EnvironmentRef) error

Detach releases only process-local handles and retains the logical worktree.

func (*RepositoryAttachmentManager) Fork 

func (m *RepositoryAttachmentManager) Fork(ctx context.Context, parent tool.Environment, label string) (tool.Environment, func() error, string, error)

Fork captures the parent's exact Git tree, then attaches a distinct logical worktree to the same repository VM. The returned cleanup detaches only the child.

func (*RepositoryAttachmentManager) Merge 

func (m *RepositoryAttachmentManager) Merge(ctx context.Context, child, parent tool.Environment) error

Merge reuses the established conflict-aware isolated-child patch path. A conflict never closes or removes the child attachment. mergeMu serializes cooperating host merges only; patch application and ownership refresh are not transactional with concurrent guest commands, and refresh does not invalidate virtio-fs caches.

func (*RepositoryAttachmentManager) Reattach 

func (m *RepositoryAttachmentManager) Reattach(ctx context.Context, request LogicalEnvironmentRequest, ref session.EnvironmentRef) (*RepositoryAttachment, error)

Reattach restores the exact persisted logical ref after authenticating the repository generation and retained worktree.

type RepositoryBootAuthority 

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

RepositoryBootAuthority is fresh secret material injected once into one repository VM generation. It is never written into a session preboot file.

func (RepositoryBootAuthority) HealthResponse 

func (a RepositoryBootAuthority) HealthResponse(record RepositoryVMRecord, challenge RepositoryHealthChallenge, status RuntimeStatus) (RepositoryHealthResponse, error)

HealthResponse signs a challenge and the guest's actual status.

func (RepositoryBootAuthority) VerifyHealth 

func (a RepositoryBootAuthority) VerifyHealth(record RepositoryVMRecord, challenge RepositoryHealthChallenge, response RepositoryHealthResponse) error

VerifyHealth accepts only a response signed by the boot authority over the exact challenge, tuple, and returned health fields.

type RepositoryBootRecord 

type RepositoryBootRecord struct {
	Generation      uint32 `json:"generation"`
	VMID            string `json:"vm_id"`
	Endpoint        string `json:"endpoint"`
	AuthorityDigest string `json:"authority_digest"`
	RunnerPID       int    `json:"runner_pid,omitempty"`
	ProcessIdentity string `json:"process_identity,omitempty"`
}

RepositoryBootRecord is replaceable runtime state for one boot of a stable repository placement.

type RepositoryComposition 

type RepositoryComposition struct {
	Runtime     *RepositoryRuntime
	Registry    *RepositoryVMRegistry
	Logical     *RepositoryLogicalManager
	Attachments *RepositoryAttachmentManager
	// RestartHealthError is set when durable repository state predates this
	// composition and its in-process network backend therefore cannot be reattached.
	RestartHealthError error
}

RepositoryComposition is the production repository-scoped microvmd slice. Attachments connects session and isolated-delegation callers to the shared authenticated runtime and logical worktree manager.

func NewRepositoryComposition 

func NewRepositoryComposition(stateRoot string, cfg RepositoryRuntimeConfig) (*RepositoryComposition, error)

NewRepositoryComposition wires the singleton lifecycle and logical routing to the concrete hypervisor/guest adapters.

type RepositoryGuestMount 

type RepositoryGuestMount struct {
	HostPath  string
	GuestPath string
}

RepositoryGuestMount describes the host export and the distinct path visible to the guest. Only GuestPath may enter an authenticated Binding.

type RepositoryGuestRegistrar 

type RepositoryGuestRegistrar interface {
	Register(context.Context, RepositoryVMRecord, control.Binding, RepositoryGuestMount) (*guestagent.Services, error)
	Unregister(context.Context, RepositoryVMRecord, control.Binding) error
}

RepositoryGuestRegistrar authenticates and attaches one logical root to an already-running repository guest. It must not provide a host fallback.

type RepositoryHealthChallenge 

type RepositoryHealthChallenge struct {
	Owner         string
	RepositoryKey string
	VMID          string
	Generation    uint32
	Nonce         [repositoryAuthorityBytes]byte
}

RepositoryHealthChallenge is one unpredictable host challenge bound to an exact repository generation. It carries no bearer proof: only the booted guest can produce the corresponding response MAC.

type RepositoryHealthResponse 

type RepositoryHealthResponse struct {
	Status RuntimeStatus
	MAC    [sha256.Size]byte
}

RepositoryHealthResponse authenticates both the challenge and the runtime status actually returned by the guest.

type RepositoryIdentity 

type RepositoryIdentity struct {
	Owner              string
	GitCommonDirectory string
	Key                string
	StateDirectory     string
}

RepositoryIdentity is the canonical owner/repository key and its opaque, owner-confined state location.

func ResolveRepositoryIdentity 

func ResolveRepositoryIdentity(ctx context.Context, owner, checkout, stateRoot string) (RepositoryIdentity, error)

ResolveRepositoryIdentity canonicalizes a checkout through Git and derives an opaque state identity. Repository-controlled path components never enter the state-directory suffix.

type RepositoryLaunchReconciler 

type RepositoryLaunchReconciler interface {
	Reconcile(context.Context, string) (LaunchReconcileResult, error)
}

RepositoryLaunchReconciler proves historical launch attempts dead before replacement.

type RepositoryLogicalManager 

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

RepositoryLogicalManager creates logical worktrees over the task-62 singleton registry.

func NewRepositoryLogicalManager 

func NewRepositoryLogicalManager(registry *RepositoryVMRegistry, preparer *worktree.Preparer, guest RepositoryGuestRegistrar) (*RepositoryLogicalManager, error)

NewRepositoryLogicalManager constructs the daemon-side logical routing use case.

func (*RepositoryLogicalManager) Create 

func (m *RepositoryLogicalManager) Create(ctx context.Context, request LogicalEnvironmentRequest) (_ *LogicalEnvironment, retErr error)

Create reuses one healthy repository VM while allocating a fresh ref, branch, index, worktree, and assigned guest root.

func (*RepositoryLogicalManager) Reattach 

func (m *RepositoryLogicalManager) Reattach(ctx context.Context, request LogicalEnvironmentRequest, ref EnvironmentRef) (*LogicalEnvironment, error)

Reattach restores process-local handles for one exact retained logical ref. It first authenticates the recorded repository generation through Ensure and never creates a replacement when that health check fails.

type RepositoryPlacement 

type RepositoryPlacement struct {
	Request LogicalEnvironmentRequest
	Status  EnforcedProfileStatus
}

RepositoryPlacement contains one repository-scoped logical attachment request. Its artifact snapshot callback is consumed only by the registry's first-launch path.

type RepositoryPlacementBuilder 

type RepositoryPlacementBuilder func(context.Context, ProvisionRequest) (RepositoryPlacement, error)

RepositoryPlacementBuilder resolves daemon-owned profile and immutable artifact policy into one repository-scoped logical attachment request.

type RepositoryRuntime 

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

RepositoryRuntime is both the concrete singleton VM runtime and logical guest registrar used by production microvmd composition.

func NewRepositoryRuntime 

func NewRepositoryRuntime(cfg RepositoryRuntimeConfig) (*RepositoryRuntime, error)

NewRepositoryRuntime constructs the production repository adapters. There is deliberately no host filesystem or command-runner fallback.

func (*RepositoryRuntime) Abort 

func (r *RepositoryRuntime) Abort(ctx context.Context, record RepositoryVMRecord) error

Abort discards a started generation only after VM teardown is confirmed.

func (*RepositoryRuntime) AttachRepository 

func (r *RepositoryRuntime) AttachRepository(record RepositoryVMRecord, authority RepositoryBootAuthority) error

AttachRepository restores capability issuance only for a generation whose VM and network backend are still owned by this daemon process. A daemon restart cannot safely reconstruct go-microvm's in-process hosted network provider.

func (*RepositoryRuntime) Health 

func (r *RepositoryRuntime) Health(ctx context.Context, record RepositoryVMRecord, challenge RepositoryHealthChallenge) (RepositoryHealthResponse, error)

Health performs guest-origin proof of the host's unpredictable challenge.

func (*RepositoryRuntime) Reconcile 

func (r *RepositoryRuntime) Reconcile(ctx context.Context, record RepositoryVMRecord) error

Reconcile proves that every historical runner for this stable repository is dead before the registry rotates boot authority and starts a replacement.

func (*RepositoryRuntime) Register 

func (r *RepositoryRuntime) Register(ctx context.Context, record RepositoryVMRecord, binding control.Binding, mount RepositoryGuestMount) (*guestagent.Services, error)

Register installs one boot-scoped registration transactionally through the separately authenticated data-plane connection.

func (*RepositoryRuntime) Shutdown 

func (r *RepositoryRuntime) Shutdown(ctx context.Context) error

Shutdown stops process-local VM and network resources while retaining every repository rootfs, logical worktree, attachment, and launch record.

func (*RepositoryRuntime) Start 

func (r *RepositoryRuntime) Start(ctx context.Context, record RepositoryVMRecord, verified VerifiedArtifacts, authority RepositoryBootAuthority) (_ RuntimeStatus, retErr error)

Start boots exactly the already-materialized repository rootfs and exports the repository logical namespace once. Individual worktrees are addressed only by guest-visible paths below RepositoryGuestMountRoot.

func (*RepositoryRuntime) Unregister 

func (r *RepositoryRuntime) Unregister(ctx context.Context, record RepositoryVMRecord, binding control.Binding) error

Unregister retries the exact pending teardown and is idempotent after a confirmed removal.

type RepositoryRuntimeConfig 

type RepositoryRuntimeConfig struct {
	Backend          GoMicroVMBackend
	DialGuest        GuestDialer
	DialControl      GuestDialer
	UnixEndpoint     bool
	EndpointRoot     string
	Network          *NetworkController
	GuestEgress      GuestEgressPolicy
	ArtifactPolicy   string
	Artifacts        map[ArtifactKind]ArtifactRequest
	LaunchReconciler RepositoryLaunchReconciler
	Observer         *OperationsObserver
}

RepositoryRuntimeConfig wires the repository-scoped production adapters to the lowest hypervisor and guest-transport seams.

type RepositoryVMRecord 

type RepositoryVMRecord struct {
	State                    EnvironmentState      `json:"state"`
	Owner                    string                `json:"owner"`
	RepositoryKey            string                `json:"repository_key"`
	GitCommonDirectory       string                `json:"git_common_directory"`
	Generation               uint32                `json:"generation"`
	RootFSPath               string                `json:"rootfs_path"`
	RootFSPhase              string                `json:"rootfs_phase"`
	RootFSStagingName        string                `json:"rootfs_staging_name,omitempty"`
	Artifacts                RepositoryArtifactSet `json:"artifacts"`
	PolicyRevision           string                `json:"policy_revision"`
	GuestEgressDigest        string                `json:"guest_egress_digest"`
	GuestAgentExecutableHash string                `json:"guest_agent_executable_hash"`
	Boot                     RepositoryBootRecord  `json:"boot"`

	// Boot mirrors retained for callers while this unmerged API transitions.
	VMID            string `json:"-"`
	Endpoint        string `json:"-"`
	AuthorityDigest string `json:"-"`
	RunnerPID       int    `json:"-"`
	ProcessIdentity string `json:"-"`
}

RepositoryVMRecord is the durable singleton VM/rootfs identity for one key.

type RepositoryVMRegistry 

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

RepositoryVMRegistry owns durable singleton admission under one state root.

func OpenRepositoryVMRegistry 

func OpenRepositoryVMRegistry(stateRoot string, runtime RepositoryVMRuntime, endpointRoots ...string) (*RepositoryVMRegistry, error)

OpenRepositoryVMRegistry opens the repository lifecycle registry without admitting or reconciling any generation. endpointRoots optionally supplies a short owner-private runtime directory for Unix guest endpoints.

func (*RepositoryVMRegistry) Ensure 

func (r *RepositoryVMRegistry) Ensure(ctx context.Context, request RepositoryVMRequest) (RepositoryVMResult, error)

Ensure admits one generation on first use or reattaches only the exact healthy ready generation. Any partial, missing, or mismatched state fails without replacement or destructive reconciliation.

func (*RepositoryVMRegistry) HasRecords 

func (r *RepositoryVMRegistry) HasRecords() (bool, error)

HasRecords reports whether any durable repository generation predates this registry instance. It reads only the fixed owner/repository hierarchy and fails closed on malformed entries.

func (*RepositoryVMRegistry) Lookup 

func (r *RepositoryVMRegistry) Lookup(ctx context.Context, identity RepositoryIdentity) (RepositoryVMRecord, error)

Lookup returns the exact durable record without inspecting or changing runtime state.

type RepositoryVMRequest 

type RepositoryVMRequest struct {
	Owner     string
	Checkout  string
	Artifacts RepositoryArtifactSnapshot
}

RepositoryVMRequest supplies first-use inputs. Artifacts is invoked only when no durable record exists; exact reattachment never validates or copies replacement bytes.

type RepositoryVMResult 

type RepositoryVMResult struct {
	Record     RepositoryVMRecord
	Reattached bool
}

RepositoryVMResult reports the exact durable singleton selected by Ensure.

type RepositoryVMRuntime 

type RepositoryVMRuntime interface {
	Start(context.Context, RepositoryVMRecord, VerifiedArtifacts, RepositoryBootAuthority) (RuntimeStatus, error)
	Health(context.Context, RepositoryVMRecord, RepositoryHealthChallenge) (RepositoryHealthResponse, error)
}

RepositoryVMRuntime owns the repository generation's VM process. Start is called only after the provisioning record and private rootfs are durable.

type ResolvedArtifact 

type ResolvedArtifact struct {
	Kind           ArtifactKind
	Digest         string
	ManifestDigest string
	Source         extract.Source
	Evidence       VerificationEvidence
}

ResolvedArtifact is immutable resolver output. Runtime and firmware Sources are passed through go-microvm's extract.Source model; the execution image is represented by the same materialization seam until VM assembly consumes it.

type RuntimeDaemon 

type RuntimeDaemon struct {
	Daemon     *Daemon
	Repository *RepositoryComposition
	// contains filtered or unexported fields
}

RuntimeDaemon owns the repository-scoped daemon protocol.

func NewRuntimeDaemon 

func NewRuntimeDaemon(cfg RuntimeDaemonConfig) (*RuntimeDaemon, error)

NewRuntimeDaemon composes the single repository-VM lifecycle.

func (*RuntimeDaemon) Serve 

func (d *RuntimeDaemon) Serve(ctx context.Context, listener net.Listener) (retErr error)

Serve accepts authenticated local management connections until cancellation.

type RuntimeDaemonConfig 

type RuntimeDaemonConfig struct {
	Control               *control.Service
	Observer              *OperationsObserver
	Info                  DaemonInfo
	Repository            *RepositoryComposition
	RepositoryProvisioner RepositoryPlacementBuilder
}

RuntimeDaemonConfig is the concrete repository-scoped microvmd composition root.

type RuntimeStatus 

type RuntimeStatus struct {
	Live            bool
	Generation      uint32
	VMID            string
	PID             int
	ProcessIdentity string
	Endpoint        string
}

RuntimeStatus identifies the exact live repository VM process.

type SigstoreVerifier 

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

SigstoreVerifier verifies stored Sigstore bundles in process.

func NewSigstoreKeyVerifier 

func NewSigstoreKeyVerifier(publicKey []byte) (*SigstoreVerifier, error)

NewSigstoreKeyVerifier creates an offline verifier pinned to one public key. The key bytes are copied so later caller mutation cannot change the trust root.

func NewSigstoreVerifier 

func NewSigstoreVerifier() *SigstoreVerifier

NewSigstoreVerifier creates an offline keyless verifier using ToolHive Core's embedded Sigstore trusted material.

func (*SigstoreVerifier) Verify 

func (v *SigstoreVerifier) Verify(ctx context.Context, statement, bundle []byte, identity, issuer string) error

Verify checks that bundle signs statement under the configured exact keyless certificate identity or public-key identity.

type SysctlGuestNetwork 

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

SysctlGuestNetwork disables IPv6 on every current and future guest interface.

func NewSysctlGuestNetwork 

func NewSysctlGuestNetwork(write SysctlWriter) *SysctlGuestNetwork

NewSysctlGuestNetwork builds the guest-side IPv6 enforcer. The guest agent supplies its privileged sysctl implementation (for example harden.Set).

func (*SysctlGuestNetwork) DisableIPv6 

func (g *SysctlGuestNetwork) DisableIPv6(_ context.Context) error

DisableIPv6 applies all/default/interface-wide settings and fails if any setting is unavailable; partial disablement is not accepted.

type SysctlWriter 

type SysctlWriter func(key, value string) error

SysctlWriter is the guest-side sysctl write seam.

type TrustPolicy 

type TrustPolicy struct {
	Revision             string
	CertificateIdentity  string
	OIDCIssuer           string
	PublicKeyIdentity    string
	Verifier             EvidenceVerifier
	RequiredAttestations map[ArtifactKind]string
	RevokedIdentities    map[string]struct{}
}

TrustPolicy is operator-owned verification configuration.

type VerificationEvidence 

type VerificationEvidence struct {
	Bundle      []byte      `json:"bundle"`
	Attestation Attestation `json:"attestation"`
}

VerificationEvidence carries one Sigstore bundle for the attestation statement.

type VerifiedArtifact 

type VerifiedArtifact struct {
	Kind               ArtifactKind
	Digest             string
	ManifestDigest     string
	DiscoveryReference string
	ResolutionEvidence string
	Platform           string
	Path               string
	Source             extract.Source
}

VerifiedArtifact is a cache-admitted artifact. Source always points at the immutable admitted payload, never resolver staging content.

type VerifiedArtifacts 

type VerifiedArtifacts struct {
	Runtime        VerifiedArtifact
	Firmware       VerifiedArtifact
	ExecutionImage VerifiedArtifact
	GuestAgent     VerifiedArtifact
}

VerifiedArtifacts is the complete set required to launch a microVM.

func (VerifiedArtifacts) All 

func (a VerifiedArtifacts) All() []VerifiedArtifact

All returns every independently admitted launch artifact in launch order.

func (VerifiedArtifacts) ByKind 

func (a VerifiedArtifacts) ByKind(kind ArtifactKind) VerifiedArtifact

ByKind returns the verified artifact of kind, or its zero value.

type VerifiedCache 

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

VerifiedCache admits artifacts by atomic rename after materialization and verification. A file lock serializes cold admission across processes.

func NewVerifiedCache 

func NewVerifiedCache(root string) *VerifiedCache

NewVerifiedCache creates an atomic verified cache rooted at root.

Source Files

View all Source files

Directories

Path Synopsis
cmd
mecatl-artifact-digest command
Command mecatl-artifact-digest prints the canonical strict-admission tree digest.
 Command mecatl-artifact-digest prints the canonical strict-admission tree digest.
mecatl-guest-agent command
Command mecatl-guest-agent serves the unified Workspace and exec protocol inside the guest.
 Command mecatl-guest-agent serves the unified Workspace and exec protocol inside the guest.
mecatl-microvmd command
Command mecatl-microvmd runs the local authenticated microVM lifecycle daemon.
 Command mecatl-microvmd runs the local authenticated microVM lifecycle daemon.
mecatl-oci-tree-digest command
Command mecatl-oci-tree-digest pulls one digest-pinned platform image through go-microvm's extractor and prints its materialized tree identity.
 Command mecatl-oci-tree-digest pulls one digest-pinned platform image through go-microvm's extractor and prints its materialized tree identity.
Package control defines the authenticated local microvmd control plane and its bounded, versioned guest handshake.
 Package control defines the authenticated local microvmd control plane and its bounded, versioned guest handshake.
controltest
Package controltest provides deterministic offline control-protocol fakes.
 Package controltest provides deterministic offline control-protocol fakes.
Package gitexec runs the narrow set of host Git operations used by the microVM worktree lifecycle without ambient executable extensions.
 Package gitexec runs the narrow set of host Git operations used by the microVM worktree lifecycle without ambient executable extensions.
Package guestagent composes the workspace and exec services on one authenticated guest stream.
 Package guestagent composes the workspace and exec services on one authenticated guest stream.
Package guestexec implements the bounded microVM guest exec data plane.
 Package guestexec implements the bounded microVM guest exec data plane.
Package virtiofs builds the explicit host/guest mount plan for a microVM.
 Package virtiofs builds the explicit host/guest mount plan for a microVM.
Package workspace implements the authenticated host/guest Workspace RPC adapter.
 Package workspace implements the authenticated host/guest Workspace RPC adapter.
Package worktree prepares session-owned Git worktrees and guest-local metadata.
 Package worktree prepares session-owned Git worktrees and guest-local metadata.

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.