microvm

package
v0.7.23 Latest Latest
Warning

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

 Go to latest Published: Jul 23, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Client 

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

func NewClient 

func NewClient() (*Client, error)

func NewClientWithConfig 

func NewClientWithConfig(config *sdktypes.MicroVMConfig) (*Client, error)

func (*Client) AttachSession 

func (c *Client) AttachSession(ctx context.Context, sandboxID, sessionID string, options SessionAttachOptions) (*SessionAttachHandle, error)

func (*Client) BuildImage added in v0.1.7 

func (c *Client) BuildImage(ctx context.Context, image *Image) (string, error)

BuildImage compiles an Image builder into a content-addressed image tag via POST /v1/images/build. Older daemons that do not register the route return a tailored error telling the caller to fall back to a plain string image.

func (*Client) BuildImageWithOptions added in v0.1.7 

func (c *Client) BuildImageWithOptions(ctx context.Context, image *Image, opts sdktypes.BuildImageOptions) (sdktypes.BuildImageResult, error)

BuildImageWithOptions builds an Image and optionally pushes the result to a remote registry. Push credentials are forwarded to the daemon as a one-shot X-Registry-Auth header and never persisted server-side. Returns the local content-addressed tag and (when push was requested) the pushed reference.

func (*Client) CloneGeneration added in v0.5.2 

func (c *Client) CloneGeneration(ctx context.Context, id string) (sdktypes.CloneGeneration, error)

CloneGeneration reads a sandbox's clone-generation token. The token changes whenever the sandbox is resumed from a snapshot, so a change signals "this is a clone." Read-only — the SDK cannot reseed a process inside the guest; see the "Randomness in cloned sandboxes" docs for the in-guest pattern.

func (*Client) Create 

func (c *Client) Create(ctx context.Context, opts sdktypes.CreateSandboxOptions) (*Sandbox, error)

func (*Client) CreateSession 

func (c *Client) CreateSession(ctx context.Context, sandboxID string, opts sdktypes.CreateSessionOptions) (sdktypes.Session, error)

func (*Client) CreateSnapshot added in v0.1.7 

func (c *Client) CreateSnapshot(ctx context.Context, id, name string) (sdktypes.SandboxSnapshot, error)

func (*Client) CreateTemplate added in v0.4.1 

func (c *Client) CreateTemplate(ctx context.Context, opts sdktypes.CreateTemplateOptions) (sdktypes.Template, error)

CreateTemplate registers a Firecracker rootfs template. Returns immediately with a status="pending" row; poll Client.GetTemplate until the row reaches "ready" (fast-boot available) or "ready_no_snapshot" (cold boot only).

Idempotent when opts.ID is set: a duplicate ID returns 409 so a retried CI step does not register two rows for the same logical template.

func (*Client) CreateWasmModule added in v0.5.3 

func (c *Client) CreateWasmModule(ctx context.Context, opts sdktypes.CreateWasmModuleOptions) (sdktypes.WasmModule, error)

CreateWasmModule registers a WASM module in the host catalogue. Resolution is synchronous — the returned row is typically already ready.

func (*Client) CreateWithImage added in v0.1.7 

func (c *Client) CreateWithImage(ctx context.Context, image *Image, opts sdktypes.CreateSandboxOptions) (*Sandbox, error)

CreateWithImage builds an Image to a content-addressed tag, then creates the sandbox using the resolved string image. This keeps CreateSandboxOptions source-compatible with the server's request model.

func (*Client) DNSTarget added in v0.3.1 

func (c *Client) DNSTarget(ctx context.Context) (sdktypes.IngressTarget, error)

DNSTarget returns the cluster-published ingress target — the hostname and/or IP set that custom-domain DNS records must point at. Source disambiguates the shape ("hostname" / "ips" / "mixed" / "unknown"), so callers don't have to inspect which fields are populated to know whether to render a CNAME or A/AAAA setup hint.

func (*Client) DeleteSession 

func (c *Client) DeleteSession(ctx context.Context, sandboxID, sessionID string) error

func (*Client) DeleteTemplate added in v0.4.1 

func (c *Client) DeleteTemplate(ctx context.Context, id string) error

func (*Client) DeleteWasmModule added in v0.5.3 

func (c *Client) DeleteWasmModule(ctx context.Context, id string) error

func (*Client) Destroy 

func (c *Client) Destroy(ctx context.Context, id string) error

func (*Client) ExecStream 

func (c *Client) ExecStream(ctx context.Context, id string, options sdktypes.ExecStreamOptions) (*ExecStreamHandle, error)

func (*Client) Get 

func (c *Client) Get(ctx context.Context, id string) (*Sandbox, error)

func (*Client) GetNetworkUsage added in v0.1.7 

func (c *Client) GetNetworkUsage(ctx context.Context, id string) (sdktypes.NetworkUsage, error)

GetNetworkUsage returns current cumulative ingress/egress byte counters and the configured per-direction caps for a sandbox. A `*Limit` of zero means unlimited.

func (*Client) GetSession 

func (c *Client) GetSession(ctx context.Context, sandboxID, sessionID string) (sdktypes.Session, error)

func (*Client) GetTemplate added in v0.4.1 

func (c *Client) GetTemplate(ctx context.Context, id string) (sdktypes.Template, error)

func (*Client) GetWasmModule added in v0.5.3 

func (c *Client) GetWasmModule(ctx context.Context, id string) (sdktypes.WasmModule, error)

func (*Client) Health 

func (c *Client) Health(ctx context.Context) (sdktypes.HealthStatus, error)

func (*Client) List 

func (c *Client) List(ctx context.Context, opts ...ListOption) ([]*Sandbox, error)

func (*Client) ListSessions 

func (c *Client) ListSessions(ctx context.Context, sandboxID string) ([]sdktypes.Session, error)

func (*Client) ListTemplates added in v0.4.1 

func (c *Client) ListTemplates(ctx context.Context) ([]sdktypes.Template, error)

func (*Client) ListWasmModules added in v0.5.3 

func (c *Client) ListWasmModules(ctx context.Context) ([]sdktypes.WasmModule, error)

func (*Client) Mounts 

func (c *Client) Mounts(ctx context.Context, id string) ([]sdktypes.MountSpecRedacted, error)

Mounts returns the redacted mount config for a sandbox. Credentials are never included; this endpoint is for showing the user what their sandbox has configured, not for retrieving secrets.

func (*Client) PushWasmModule added in v0.5.3 

func (c *Client) PushWasmModule(ctx context.Context, opts sdktypes.PushWasmModuleOptions) (sdktypes.PushWasmModuleResponse, error)

PushWasmModule uploads a compiled core-wasip1 module to the registry under your own credentials and returns the oci:// ref to use as ModuleRef on a later Create. The daemon validates and forwards the bytes; it never stores them.

func (*Client) RebuildTemplate added in v0.4.1 

func (c *Client) RebuildTemplate(ctx context.Context, id string) (sdktypes.Template, error)

RebuildTemplate re-runs the snapshot phase against an existing template. Idempotent under concurrent retry: the daemon's CAS collapses N parallel calls for the same ready template into one rebuild kick. Returns the row in its post-transition state (typically "unhealthy"); poll GetTemplate to observe the transition back to "ready".

Returns an HTTP error (status 412) when the template is in a state where rebuild is not safe (build in flight) or not supported (ready_no_snapshot, failed — those need delete+recreate today).

func (*Client) Reconcile added in v0.1.1 

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

func (*Client) RegisterSnapshot added in v0.1.7 

func (c *Client) RegisterSnapshot(ctx context.Context, opts sdktypes.RegisterSnapshotOptions) (sdktypes.SandboxSnapshot, error)

RegisterSnapshot persists a named snapshot pointing at either a pre-built image (opts.Image) or a Dockerfile the daemon will build (opts.Dockerfile — typically obtained from Image.Dockerfile()). The returned snapshot's Image field reflects the resolved registry reference (for the build path this is the daemon's content-addressed tag).

Once registered, callers can reference the snapshot by name in CreateSandboxOptions.Snapshot — the server resolves it to the image at create time.

func (*Client) RegisterSnapshotFromImage added in v0.1.7 

func (c *Client) RegisterSnapshotFromImage(ctx context.Context, name string, image *Image, opts sdktypes.RegisterSnapshotOptions) (sdktypes.SandboxSnapshot, error)

RegisterSnapshotFromImage compiles an Image-builder graph and registers the resulting Dockerfile as a named snapshot. Convenience wrapper around RegisterSnapshot that mirrors CreateWithImage's ergonomics — pass an *Image instead of remembering to call Image.Dockerfile() yourself.

func (*Client) Resize 

func (c *Client) Resize(ctx context.Context, id string, opts sdktypes.ResizeSandboxOptions) (*Sandbox, error)

func (*Client) ResizeSession 

func (c *Client) ResizeSession(ctx context.Context, sandboxID, sessionID string, cols, rows int) error

func (*Client) SessionLog 

func (c *Client) SessionLog(ctx context.Context, sandboxID, sessionID string) ([]byte, error)

func (*Client) SessionRecording 

func (c *Client) SessionRecording(ctx context.Context, sandboxID, sessionID string) ([]byte, error)

func (*Client) SetNetworkLimits added in v0.1.7 

func (c *Client) SetNetworkLimits(ctx context.Context, id string, opts sdktypes.SetNetworkLimitsOptions) (sdktypes.NetworkUsage, error)

SetNetworkLimits raises or lifts the per-direction byte caps. Leave a field nil to keep the current value; pass a pointer to zero to set "unlimited". Raising a cap above current usage clears the per-IP iptables block on the next reconcile pass (or immediately if it's already over the new cap).

func (*Client) SignalSession 

func (c *Client) SignalSession(ctx context.Context, sandboxID, sessionID, signal string) error

func (*Client) Start 

func (c *Client) Start(ctx context.Context, id string) (*Sandbox, error)

func (*Client) Stop 

func (c *Client) Stop(ctx context.Context, id string) (*Sandbox, error)

func (*Client) UpdateLifecycle 

func (c *Client) UpdateLifecycle(ctx context.Context, id string, lifecycle sdktypes.Lifecycle) (*Sandbox, error)

UpdateLifecycle replaces the per-sandbox lifecycle timers. Pass zero in any field to clear that timer; pass non-zero to set or extend it. The server validates and rejects negative durations, durations over the configured cap, or stop/destroy pairs where destroy fires before stop.

type CustomDomainOption added in v0.4.1 

type CustomDomainOption func(*customDomainOptions)

CustomDomainOption customizes an AddCustomDomain call. Build values with WithTargetPort; the variadic shape leaves room for future expansion.

func WithTargetPort added in v0.4.1 

func WithTargetPort(port int) CustomDomainOption

WithTargetPort routes the custom hostname to the given in-container TCP port instead of the default toolbox agent. Set once at attach time; changing the port for an already-attached hostname requires RemoveCustomDomain + AddCustomDomain so in-flight traffic can't silently redirect. Re-adding the same hostname with a different port returns 409.

type ExecStreamHandle 

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

func (*ExecStreamHandle) Close 

func (h *ExecStreamHandle) Close() error

func (*ExecStreamHandle) Resize 

func (h *ExecStreamHandle) Resize(cols, rows int) error

func (*ExecStreamHandle) Signal 

func (h *ExecStreamHandle) Signal(name string) error

func (*ExecStreamHandle) Wait 

func (h *ExecStreamHandle) Wait() (sdktypes.ExecExitInfo, error)

func (*ExecStreamHandle) Write 

func (h *ExecStreamHandle) Write(data []byte) error

func (*ExecStreamHandle) WriteString 

func (h *ExecStreamHandle) WriteString(data string) error

type ExposeOption added in v0.1.6 

type ExposeOption func(*exposeOptions)

ExposeOption customizes an ExposePort call. Build values with WithProtocol; the variadic shape leaves room for future expansion (e.g. tags, idle TTL) without breaking call sites.

func WithProtocol added in v0.1.6 

func WithProtocol(p sdktypes.ExposeProtocol) ExposeOption

WithProtocol selects the wire surface the exposure publishes through. Defaults to ExposeProtocolHTTP when omitted.

type Image added in v0.1.7 

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

Image is a fluent Dockerfile builder for the Go SDK. Build it locally, then pass it to Client.BuildImage or Client.CreateWithImage.

func BaseImage added in v0.1.7 

func BaseImage(image string) *Image

BaseImage starts a Dockerfile with FROM <image>.

func FromDockerfile added in v0.1.7 

func FromDockerfile(dockerfile string) *Image

FromDockerfile wraps an existing Dockerfile string and normalizes the final trailing newline so builds stay content-stable across callers.

func (*Image) Cmd added in v0.1.7 

func (i *Image) Cmd(commands ...string) *Image

func (*Image) Dockerfile added in v0.1.7 

func (i *Image) Dockerfile() string

func (*Image) Entrypoint added in v0.1.7 

func (i *Image) Entrypoint(commands ...string) *Image

func (*Image) Env added in v0.1.7 

func (i *Image) Env(envVars map[string]string) *Image

Env appends one ENV line containing all provided key/value pairs.

func (*Image) Err added in v0.1.7 

func (i *Image) Err() error

func (*Image) Expose added in v0.1.7 

func (i *Image) Expose(port int) *Image

func (*Image) RunCommands added in v0.1.7 

func (i *Image) RunCommands(commands ...any) *Image

RunCommands appends one RUN per string argument. A []string argument is joined with && so the commands share one layer.

func (*Image) User added in v0.1.7 

func (i *Image) User(username string) *Image

func (*Image) Workdir added in v0.1.7 

func (i *Image) Workdir(dirPath string) *Image

type ListOption added in v0.2.1 

type ListOption func(*listOptions)

ListOption customizes a List call. Build values with WithTags; the variadic shape leaves room for future filters (e.g. status, lifecycle) without breaking call sites.

func WithTags added in v0.2.1 

func WithTags(tags map[string]string) ListOption

WithTags filters the result to sandboxes whose Tags map contains every supplied key/value pair (AND semantics on the server). Wire format is `?tag.<key>=<value>`; the SDK percent-encodes keys and values for you. An empty or nil map is a no-op — the call is identical to List(ctx).

type Sandbox 

type Sandbox struct {
	sdktypes.Sandbox
	// SSHPrivateKey is populated only on the response from Client.Create. It
	// is the per-sandbox ed25519 private key the gateway authorizes; persist
	// it locally before discarding the create response, the server cannot
	// regenerate it.
	SSHPrivateKey string
	// contains filtered or unexported fields
}

func (*Sandbox) AddCustomDomain added in v0.3.1 

func (s *Sandbox) AddCustomDomain(ctx context.Context, hostname string, opts ...CustomDomainOption) ([]sdktypes.CustomDomain, error)

AddCustomDomain attaches a public hostname (e.g. "api.acme.com") to this sandbox. The server lowercases / trims and validates the hostname; the returned slice is the full per-hostname row list, so callers can read the canonical form and initial status without a follow-up GET.

412 Precondition Failed surfaces when the deployment is in IP mode or the custom-domain feature is disabled. 409 Conflict surfaces when the hostname is already attached to a different sandbox, the sandbox has any tcp/tls-protocol exposed port (the IRON RULE: SNI cannot route per host on a shared L4 listener), or the re-add target_port differs from the stored value. 400 Bad Request surfaces when target_port is outside [0, 65535].

func (*Sandbox) AttachSession 

func (s *Sandbox) AttachSession(ctx context.Context, sessionID string, options SessionAttachOptions) (*SessionAttachHandle, error)

func (*Sandbox) CloneGeneration added in v0.5.2 

func (s *Sandbox) CloneGeneration(ctx context.Context) (sdktypes.CloneGeneration, error)

CloneGeneration reads this sandbox's clone-generation token (changes on resume-from-snapshot). Read-only; does not reseed in-guest PRNGs.

func (*Sandbox) CreateSession 

func (s *Sandbox) CreateSession(ctx context.Context, opts sdktypes.CreateSessionOptions) (sdktypes.Session, error)

func (*Sandbox) CreateSnapshot added in v0.1.7 

func (s *Sandbox) CreateSnapshot(ctx context.Context, name string) (sdktypes.SandboxSnapshot, error)

func (*Sandbox) CustomDomainDNS added in v0.3.1 

func (s *Sandbox) CustomDomainDNS(ctx context.Context) (sdktypes.CustomDomainDNSRecords, error)

CustomDomainDNS returns the ready-to-paste DNS records the user must add at their provider for every custom domain on this sandbox to reach the cluster, plus the raw ingress target the records were derived from. One row per (hostname × ingress address); branch on Target.Source to render a "CNAME vs A/AAAA" hint.

func (*Sandbox) DeleteSession 

func (s *Sandbox) DeleteSession(ctx context.Context, sessionID string) error

func (*Sandbox) Destroy 

func (s *Sandbox) Destroy(ctx context.Context) error

func (*Sandbox) DownloadFile 

func (s *Sandbox) DownloadFile(ctx context.Context, targetPath string) ([]byte, error)

func (*Sandbox) Exec 

func (s *Sandbox) Exec(ctx context.Context, request sdktypes.ExecRequest) (sdktypes.ExecResult, error)

func (*Sandbox) ExecCommand 

func (s *Sandbox) ExecCommand(ctx context.Context, command string) (sdktypes.ExecResult, error)

func (*Sandbox) ExecStream 

func (s *Sandbox) ExecStream(ctx context.Context, options sdktypes.ExecStreamOptions) (*ExecStreamHandle, error)

func (*Sandbox) ExposePort 

func (s *Sandbox) ExposePort(ctx context.Context, port int, opts ...ExposeOption) (sdktypes.ExposeResult, error)

ExposePort publishes a sandbox container port. Use WithProtocol to choose a non-HTTP surface:

  • WithProtocol(ExposeProtocolTCP): raw caddy-l4 listener on a parent-host port. Pair with native protocol clients (psql, redis-cli, mysql, mongosh). Result.Host and Result.HostPort are populated on this path.
  • WithProtocol(ExposeProtocolTLS): caddy-l4 TLS-SNI route on the shared listener. Requires --domain and SB_L4_TLS_LISTEN.

With no option (or WithProtocol(ExposeProtocolHTTP)) the result is the default Caddy HTTP reverse-proxy URL.

func (*Sandbox) GetNetworkUsage added in v0.1.7 

func (s *Sandbox) GetNetworkUsage(ctx context.Context) (sdktypes.NetworkUsage, error)

func (*Sandbox) GetSession 

func (s *Sandbox) GetSession(ctx context.Context, sessionID string) (sdktypes.Session, error)

func (*Sandbox) ListCustomDomains added in v0.3.1 

func (s *Sandbox) ListCustomDomains(ctx context.Context) ([]sdktypes.CustomDomain, error)

ListCustomDomains returns the per-hostname rows currently attached to the sandbox. Use this to poll Status (pending_dns → issuing → ready/failed) after AddCustomDomain.

func (*Sandbox) ListSessions 

func (s *Sandbox) ListSessions(ctx context.Context) ([]sdktypes.Session, error)

func (*Sandbox) Refresh 

func (s *Sandbox) Refresh(ctx context.Context) error

func (*Sandbox) RemoveCustomDomain added in v0.3.1 

func (s *Sandbox) RemoveCustomDomain(ctx context.Context, hostname string) error

RemoveCustomDomain detaches a hostname previously attached via AddCustomDomain or CreateSandboxOptions.CustomDomains. Case-insensitive; the server normalizes before comparing.

func (*Sandbox) Resize 

func (s *Sandbox) Resize(ctx context.Context, opts sdktypes.ResizeSandboxOptions) error

func (*Sandbox) ResizeSession 

func (s *Sandbox) ResizeSession(ctx context.Context, sessionID string, cols, rows int) error

func (*Sandbox) SessionLog 

func (s *Sandbox) SessionLog(ctx context.Context, sessionID string) ([]byte, error)

func (*Sandbox) SessionRecording 

func (s *Sandbox) SessionRecording(ctx context.Context, sessionID string) ([]byte, error)

func (*Sandbox) SetNetworkLimits added in v0.1.7 

func (s *Sandbox) SetNetworkLimits(ctx context.Context, opts sdktypes.SetNetworkLimitsOptions) (sdktypes.NetworkUsage, error)

func (*Sandbox) SignalSession 

func (s *Sandbox) SignalSession(ctx context.Context, sessionID, signal string) error

func (*Sandbox) Start 

func (s *Sandbox) Start(ctx context.Context) error

func (*Sandbox) Stop 

func (s *Sandbox) Stop(ctx context.Context) error

func (*Sandbox) UnexposePort 

func (s *Sandbox) UnexposePort(ctx context.Context, port int) error

func (*Sandbox) UpdateLifecycle 

func (s *Sandbox) UpdateLifecycle(ctx context.Context, lifecycle sdktypes.Lifecycle) error

func (*Sandbox) UploadFile 

func (s *Sandbox) UploadFile(ctx context.Context, targetPath string, data []byte) error

type SessionAttachHandle 

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

SessionAttachHandle is the live-session counterpart of ExecStreamHandle. It outlives the underlying process — Close() detaches without killing.

func (*SessionAttachHandle) Close 

func (h *SessionAttachHandle) Close() error

func (*SessionAttachHandle) Resize 

func (h *SessionAttachHandle) Resize(cols, rows int) error

func (*SessionAttachHandle) Signal 

func (h *SessionAttachHandle) Signal(name string) error

func (*SessionAttachHandle) Wait 

func (h *SessionAttachHandle) Wait() (int, string, error)

func (*SessionAttachHandle) Write 

func (h *SessionAttachHandle) Write(data []byte) error

func (*SessionAttachHandle) WriteString 

func (h *SessionAttachHandle) WriteString(data string) error

type SessionAttachOptions 

type SessionAttachOptions = apiclient.SessionAttachOptions

SessionAttachOptions mirrors apiclient.SessionAttachOptions; re-exported here so callers don't need to import the internal package.

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.