types

package
v0.6.13 Latest Latest
Warning

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

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

Documentation

Index

Constants

View Source
const (
	TemplateStatusPending         = models.TemplateStatusPending
	TemplateStatusBuildingRootfs  = models.TemplateStatusBuildingRootfs
	TemplateStatusSnapshotting    = models.TemplateStatusSnapshotting
	TemplateStatusReady           = models.TemplateStatusReady
	TemplateStatusReadyNoSnapshot = models.TemplateStatusReadyNoSnapshot
	TemplateStatusFailed          = models.TemplateStatusFailed
	TemplateStatusUnhealthy       = models.TemplateStatusUnhealthy
)
View Source
const (
	WasmModuleStatusReady  = models.WasmModuleStatusReady
	WasmModuleStatusFailed = models.WasmModuleStatusFailed
)
View Source
const (
	FailoverPolicyNone     = models.FailoverPolicyNone
	FailoverPolicyRecreate = models.FailoverPolicyRecreate
)
View Source
const (
	StatusReasonUserStop      = models.StatusReasonUserStop
	StatusReasonIdle          = models.StatusReasonIdle
	StatusReasonMaxAge        = models.StatusReasonMaxAge
	StatusReasonOutOfMemory   = models.StatusReasonOutOfMemory
	StatusReasonDiskLimit     = models.StatusReasonDiskLimit
	StatusReasonCrashed       = models.StatusReasonCrashed
	StatusReasonReconcile     = models.StatusReasonReconcile
	StatusReasonProgramExited = models.StatusReasonProgramExited
	StatusReasonFailover      = models.StatusReasonFailover
	StatusReasonRestarted     = models.StatusReasonRestarted
)

Status reasons say why a sandbox is in its current status (Sandbox.StatusReason). ExitCode is set for out_of_memory, crashed, program_exited and restarted.

View Source
const (
	SessionStatusRunning = models.SessionStatusRunning
	SessionStatusExited  = models.SessionStatusExited
	SessionStatusKilled  = models.SessionStatusKilled
	SessionStatusFailed  = models.SessionStatusFailed
)
View Source
const (
	MountTypeS3     = models.MountTypeS3
	MountTypeNFS    = models.MountTypeNFS
	MountTypeSSHFS  = models.MountTypeSSHFS
	MountTypeRclone = models.MountTypeRclone
)
View Source
const (
	RuntimeDocker      = models.RuntimeDocker
	RuntimeGvisor      = models.RuntimeGvisor
	RuntimeKata        = models.RuntimeKata
	RuntimeFirecracker = models.RuntimeFirecracker
	RuntimeWasm        = models.RuntimeWasm
	RuntimeIsolate     = models.RuntimeIsolate
)
View Source
const (
	DurabilityEphemeral    = models.DurabilityEphemeral
	DurabilityPassivatable = models.DurabilityPassivatable
	DurabilityDurable      = models.DurabilityDurable
)
View Source
const (
	NetworkEgressModeEnforce = models.NetworkEgressModeEnforce
	NetworkEgressModeLearn   = models.NetworkEgressModeLearn
)

Egress modes for NetworkEgressMode.

View Source
const (
	WarmPoolReplaceNow    = models.WarmPoolReplaceNow
	WarmPoolReplaceAsUsed = models.WarmPoolReplaceAsUsed
)

What a warm pool does when its image changes (WarmPoolOptions.OnImageChange).

View Source
const (
	CustomDomainPendingDNS = models.CustomDomainPendingDNS
	CustomDomainIssuing    = models.CustomDomainIssuing
	CustomDomainReady      = models.CustomDomainReady
	CustomDomainFailed     = models.CustomDomainFailed
)
View Source
const (
	IngressTargetSourceHostname = models.IngressTargetSourceHostname
	IngressTargetSourceIPs      = models.IngressTargetSourceIPs
	IngressTargetSourceMixed    = models.IngressTargetSourceMixed
	IngressTargetSourceUnknown  = models.IngressTargetSourceUnknown
)

IngressTarget Source values.

View Source
const (
	DNSRecordTypeCNAME = models.DNSRecordTypeCNAME
	DNSRecordTypeA     = models.DNSRecordTypeA
	DNSRecordTypeAAAA  = models.DNSRecordTypeAAAA
	DNSRecordTypeANAME = models.DNSRecordTypeANAME
	DNSRecordTypeALIAS = models.DNSRecordTypeALIAS
)

DNS record types emitted in CustomDomainDNSRecords. ANAME and ALIAS are apex-flattening alternatives to CNAME, emitted only for an apex domain on a hostname ingress; add the one your provider supports (see DNSRecord.Notes).

View Source
const (
	GPUVendorNVIDIA = models.GPUVendorNVIDIA
	GPUVendorAMD    = models.GPUVendorAMD
	GPUVendorApple  = models.GPUVendorApple
)
View Source
const (
	FileEventCreate = "create"
	FileEventWrite  = "write"
	FileEventRemove = "remove"
	// FileEventRename names the old path; the new path arrives as a create.
	FileEventRename = "rename"
	FileEventChmod  = "chmod"
	// FileEventOverflow means events were lost. List the folder again to
	// catch up. Reason says why.
	FileEventOverflow = "overflow"
)

File event types a watch reports.

View Source
const (
	// WatchOverflowKernelQueue: the sandbox kernel's event queue overflowed.
	WatchOverflowKernelQueue = "kernel_queue"
	// WatchOverflowEventBuffer: more events than the agent holds between two
	// sends (about 4096 in 250 ms).
	WatchOverflowEventBuffer = "event_buffer"
	// WatchOverflowWatchLimit: a folder could not be watched because the
	// sandbox's watch limit was reached; Path names it.
	WatchOverflowWatchLimit = "watch_limit"
)

Overflow reasons.

View Source
const DefaultListLimit = 10000

DefaultListLimit is the entry cap ListFiles sends when ListFilesOptions gives none. A listing past it comes back with Truncated set.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIToken added in v0.6.8

type APIToken = models.APIToken

APIToken is one scoped API token as Tokens().List returns it. It never carries the secret.

type APITokenList added in v0.6.8

type APITokenList = models.APITokenList

APITokenList is Tokens().List's result.

type AuditCoverage added in v0.6.6

type AuditCoverage struct {
	Answered []string `json:"answered"`
	Missing  []string `json:"missing"`
	Partial  bool     `json:"partial"`
}

AuditCoverage reports which nodes answered an audit read.

type AuditEvent added in v0.6.6

type AuditEvent struct {
	Time          time.Time `json:"time"`
	Kind          string    `json:"kind,omitempty"`
	Result        string    `json:"result"`
	Reason        string    `json:"reason,omitempty"`
	Destination   string    `json:"destination,omitempty"`
	Network       string    `json:"network,omitempty"`
	Actor         string    `json:"actor,omitempty"`
	Ref           string    `json:"ref,omitempty"`
	EventID       string    `json:"event_id,omitempty"`
	IncarnationID string    `json:"incarnation_id,omitempty"`
	// Dropped counts records lost at this point (a gap record).
	Dropped int64 `json:"dropped,omitempty"`
}

AuditEvent is one record from a sandbox's audit log (Sandbox.Audit). Kind "egress" covers outbound connections and denials; a denial has Result "failure" and the policy Reason ("host_not_allowed", "sni_not_allowed", …).

type AuditOptions added in v0.6.6

type AuditOptions struct {
	Kind          string
	Limit         int
	Cursor        string
	IncarnationID string
	// Caller keeps only records by this caller: an id such as
	// "system:lifecycle", or "system:*" for everything the server did on
	// its own (automatic stops, deletes, restarts and recreates).
	Caller string
}

AuditOptions filters and pages Sandbox.Audit. Zero values are omitted.

type AuditPage added in v0.6.6

type AuditPage struct {
	Events   []AuditEvent  `json:"events"`
	Coverage AuditCoverage `json:"coverage"`
	// NextCursor, when set, reads the next page via AuditOptions.Cursor.
	NextCursor string `json:"next_cursor,omitempty"`
}

AuditPage is one page of a sandbox's audit log.

type BuildImageOptions added in v0.1.7

type BuildImageOptions struct {
	Push *BuildImagePushOptions
}

BuildImageOptions are optional knobs for Client.BuildImageWithOptions.

type BuildImagePushOptions added in v0.1.7

type BuildImagePushOptions struct {
	// Registry is the destination repository, e.g. "ghcr.io/my-org/my-image".
	Registry string
	// Tag is the destination tag. The daemon defaults to "latest" when empty.
	Tag string
	// Server is the registry serveraddress, e.g. "ghcr.io". Sent inside
	// X-Registry-Auth.
	Server   string
	Username string
	Password string
}

BuildImagePushOptions describes the per-request push directive for Client.BuildImageWithOptions. Credentials are forwarded to the daemon as a one-shot X-Registry-Auth header on the push call and are never persisted.

type BuildImageResult added in v0.1.7

type BuildImageResult struct {
	// Image is the local content-addressed tag (always returned).
	Image string
	// Pushed is the pushed reference (e.g. "ghcr.io/x/y:v1") when push was
	// requested, otherwise empty.
	Pushed string
}

BuildImageResult is the response from Client.BuildImageWithOptions.

type CloneGeneration added in v0.5.2

type CloneGeneration struct {
	// Generation is an opaque token that changes on every resume-from-snapshot.
	Generation string `json:"generation"`
	// ResumedAt is the host wall-clock of the last resume, in unix nanoseconds.
	// 0 means the sandbox has never been resumed.
	ResumedAt int64 `json:"resumedAt"`
}

CloneGeneration is a sandbox's clone-generation marker. Generation changes every time the sandbox is resumed from a snapshot (i.e. it is a clone). A long-lived process running inside the sandbox can poll this and reseed its own userspace PRNGs when the token changes — two clones otherwise share the snapshot's frozen seed state. Read-only: the SDK cannot reseed an in-guest process from the client side. See the "Randomness in cloned sandboxes" docs.

type CopyFileOptions added in v0.6.12

type CopyFileOptions struct {
	// Overwrite replaces an existing destination file.
	Overwrite bool
	// Recursive copies a folder and everything in it, keeping modes and
	// symlinks. Without it, a folder is refused with a 409 conflict.
	Recursive bool
}

CopyFileOptions controls CopyFile.

type CreateAPITokenOptions added in v0.6.8

type CreateAPITokenOptions = models.CreateAPITokenRequest

CreateAPITokenOptions is the body of Tokens().Create. Role is viewer, runner, auditor or admin; Team is a team name or "*" (auditor and admin require "*"); ExpiresIn is required ("90d", "720h", any Go duration).

type CreateSandboxOptions

type CreateSandboxOptions = models.CreateSandboxRequest

type CreateSandboxTokenOptions added in v0.6.12

type CreateSandboxTokenOptions = models.CreateSandboxTokenRequest

CreateSandboxTokenOptions is the body of Sandbox.CreateToken: a signed token for one sandbox that can be handed to a browser or an end user. ExpiresIn is required ("15m", "2h", "1d") and capped by the server (24h by default). Port makes a public-port token; without it the token is for the sandbox's toolbox. PathPrefix and Methods narrow it further.

type CreateSessionOptions

type CreateSessionOptions = models.CreateSessionRequest

type CreateTemplateOptions added in v0.4.1

type CreateTemplateOptions = models.CreateTemplateRequest

CreateTemplateOptions is the request body for Client.CreateTemplate. Supplying an explicit ID lets retries be idempotent — a duplicate ID returns 409 so a re-run CI step does not register two rows for the same logical template.

type CreateWasmModuleOptions added in v0.5.3

type CreateWasmModuleOptions = models.CreateWasmModuleRequest

CreateWasmModuleOptions is the request body for Client.CreateWasmModule.

type CreatedAPIToken added in v0.6.8

type CreatedAPIToken = models.CreatedAPIToken

CreatedAPIToken is Tokens().Create's result: the stored token plus Token, the secret, which the server returns this once and never stores.

type CustomDomain added in v0.3.1

type CustomDomain = models.CustomDomain

CustomDomain is the per-hostname row attached to a sandbox. Status moves pending_dns → issuing → ready (or failed), driven server-side by Caddy's on-demand TLS asks; clients read but never write Status.

type CustomDomainDNSRecords added in v0.3.1

type CustomDomainDNSRecords = models.CustomDomainDNSRecords

CustomDomainDNSRecords is the response body for the per-sandbox custom-domain DNS helper. Records is the flat list (one row per custom domain × per ingress address); Target is the raw aggregation Records was composed from, useful when callers want to render their own UI.

type CustomDomainStatus added in v0.3.1

type CustomDomainStatus = models.CustomDomainStatus

CustomDomainStatus enumerates the lifecycle states surfaced on CustomDomain.Status.

type DNSRecord added in v0.3.1

type DNSRecord = models.DNSRecord

DNSRecord is one ready-to-paste DNS row for a custom domain. Hostname is the full hostname; Name is the leftmost label (or "@" for apex); Value is the target. Notes carries provider-specific gotchas the daemon pre-renders.

type DeleteFileOptions added in v0.6.12

type DeleteFileOptions struct {
	// Recursive deletes a folder and everything in it. Without it, a folder
	// is refused with a 409 conflict.
	Recursive bool
}

DeleteFileOptions controls DeleteFile.

type DownloadFileOptions added in v0.6.12

type DownloadFileOptions struct {
	// MaxBytes refuses a file larger than this many bytes (0 is no limit):
	// before reading when the server states the size, and otherwise as soon
	// as more arrives. A guard against filling memory with a file larger
	// than expected.
	MaxBytes int64
}

DownloadFileOptions controls a download.

type EgressInject added in v0.6.6

type EgressInject = models.EgressInject

EgressInject is an EgressRule's credential injection, {Header, SecretRef}. SecretRef is "env:<KEY>", a key in the create's Env whose value is the whole header value (e.g. "Bearer ghp_..."). A container sandbox sees "aerolvm-placeholder:<KEY>" in its env instead, and the egress gateway replaces Header with the real value on each request the rule allows. Needs Inspect; rotating the value means recreating the sandbox.

type EgressProfile added in v0.6.6

type EgressProfile = models.EgressProfile

EgressProfile is a named allowlist sandboxes reference through EgressProfiles; Generation goes up on every change.

type EgressProfileList added in v0.6.6

type EgressProfileList = models.EgressProfileList

EgressProfileList is one page of ListEgressProfiles.

type EgressProfileOptions added in v0.6.6

type EgressProfileOptions = models.EgressProfileRequest

EgressProfileOptions is the body of PutEgressProfile: a full replace.

type EgressProfileRef added in v0.6.6

type EgressProfileRef = models.EgressProfileRef

EgressProfileRef is a referenced profile and the generation of it live on a sandbox (Sandbox.EgressProfilesApplied).

type EgressRule added in v0.6.6

type EgressRule = models.EgressRule

EgressRule is one method, path or program rule for NetworkEgressRules. It refines a host the allow list already admits: a request to a ruled host passes when some rule for it admits the program, method and path, and gets 403 otherwise. Ports default to [80], or [443] with Inspect, which makes the egress gateway terminate TLS with the node's CA (set at create). Binaries limits the rule to connections opened by those executables (absolute paths inside the sandbox, at most 16; an interpreter's script counts, so "/usr/local/bin/pip" works). A rule with only Binaries decides whole connections, on any port the allow list opens. Runc sandboxes only (docker and containerd); least privilege, not a security boundary.

type ExecExitInfo

type ExecExitInfo struct {
	Code   int    `json:"code"`
	Signal string `json:"signal,omitempty"`
}

type ExecRequest

type ExecRequest = models.ExecRequest

type ExecResult

type ExecResult = models.ExecResult

type ExecStreamOptions

type ExecStreamOptions struct {
	Command string `json:"command"`
	// Argv runs a program with these arguments instead of Command, with no
	// shell parsing: spaces, quotes, $ and ; reach the program as written.
	// Set Command or Argv, not both. The sandbox's agent must list
	// exec.argv on /version; an older one fails with
	// ErrUnsupportedFeature before anything runs.
	Argv     []string            `json:"argv,omitempty"`
	Workdir  string              `json:"workdir,omitempty"`
	Env      map[string]string   `json:"env,omitempty"`
	TTY      bool                `json:"tty,omitempty"`
	Cols     int                 `json:"cols,omitempty"`
	Rows     int                 `json:"rows,omitempty"`
	OnStdout StreamCallback      `json:"-"`
	OnStderr StreamCallback      `json:"-"`
	OnError  StreamErrorCallback `json:"-"`
}

type ExposeProtocol added in v0.1.6

type ExposeProtocol string

ExposeProtocol selects the wire surface an exposure publishes through.

const (
	// ExposeProtocolHTTP is the default — Caddy HTTP reverse proxy at
	// https://<id>-<port>.<domain> (or the path-mode equivalent on an
	// IP-only deployment).
	ExposeProtocolHTTP ExposeProtocol = "http"
	// ExposeProtocolTCP allocates a parent-host port from the configured
	// pool and forwards raw bytes to the container via caddy-l4.
	ExposeProtocolTCP ExposeProtocol = "tcp"
	// ExposeProtocolTLS adds a TLS-SNI route to the shared layer4 server.
	// Requires the daemon to have a domain configured AND
	// SB_L4_TLS_LISTEN set.
	ExposeProtocolTLS ExposeProtocol = "tls"
)

type ExposeResult added in v0.1.6

type ExposeResult = models.ExposePortResponse

ExposeResult is the structured outcome of a successful expose call. Host and HostPort are populated only when Protocol == ExposeProtocolTCP — for HTTP and TLS exposures the dialable URL is in URL alone.

type ExposeVisibility added in v0.6.12

type ExposeVisibility string

ExposeVisibility says who can open a port's URL (Sandbox.ExposePort's WithVisibility). Token-gated URLs need a server with a domain and work for HTTP ports only.

const (
	// ExposeVisibilityPublic: anyone with the URL.
	ExposeVisibilityPublic ExposeVisibility = "public"
	// ExposeVisibilityToken: only a visitor with a sandbox token for this
	// port (Sandbox.CreateToken with Port set).
	ExposeVisibilityToken ExposeVisibility = "token"
)

type ExposedPort

type ExposedPort = models.ExposedPort

type Failover added in v0.2.2

type Failover = models.Failover

type FileEvent added in v0.6.12

type FileEvent struct {
	// Type is one of the FileEvent* constants. Treat an unknown type as a
	// reason to list the folder again.
	Type string `json:"type"`
	// Path is absolute. It is empty for some overflow events.
	Path  string `json:"path,omitempty"`
	IsDir bool   `json:"is_dir,omitempty"`
	// Reason is set on overflow events: one of the WatchOverflow* constants.
	Reason string `json:"reason,omitempty"`
}

FileEvent is one change a file watch reports.

type FileInfo added in v0.6.12

type FileInfo struct {
	// Name is the last part of Path.
	Name string `json:"name"`
	// Path is the full path in the sandbox.
	Path  string `json:"path"`
	IsDir bool   `json:"is_dir"`
	// Size is in bytes.
	Size int64 `json:"size"`
	// Mode is the type and permission string, such as "-rw-r--r--".
	Mode string `json:"mode"`
	// Permissions is the octal permission bits, such as "0644".
	Permissions string `json:"permissions"`
	Owner       string `json:"owner"`
	Group       string `json:"group"`
	// ModTime is the last change time, RFC 3339 in UTC.
	ModTime string `json:"mod_time"`
	// SymlinkTarget is where a symlink points. Set only on ListFiles
	// entries: GetFileInfo follows a symlink and describes what it names.
	SymlinkTarget string `json:"symlink_target,omitempty"`
}

FileInfo describes one file, folder or symlink in a sandbox.

type FileList added in v0.6.12

type FileList struct {
	Entries   []FileInfo `json:"entries"`
	Truncated bool       `json:"truncated"`
}

FileList is the result of ListFiles. Truncated means the listing reached its Limit and stopped; more entries exist.

type FileMatch added in v0.6.12

type FileMatch struct {
	File    string `json:"file"`
	Line    int    `json:"line"`
	Content string `json:"content"`
}

FileMatch is one line FindInFiles found.

type GPURequest added in v0.1.3

type GPURequest = models.GPURequest

type GPUVendor added in v0.1.3

type GPUVendor = models.GPUVendor

type HealthStatus

type HealthStatus = models.HealthStatus

type IdentityOptions added in v0.6.12

type IdentityOptions = models.IdentityRequest

IdentityOptions is CreateSandboxOptions.Identity: a short-lived cloud identity token for the sandbox. RoleTag must be on the team's allow list (PutIdentityRole); Audience defaults to "sts.amazonaws.com".

type IdentityRole added in v0.6.12

type IdentityRole = models.IdentityRole

IdentityRole is one role tag on a team's identity allow list.

type IdentityRoleList added in v0.6.12

type IdentityRoleList = models.IdentityRoleList

IdentityRoleList is one page of ListIdentityRoles.

type IdentityRoleOptions added in v0.6.12

type IdentityRoleOptions struct {
	MinRole string
	Team    string
}

IdentityRoleOptions is PutIdentityRole's body and the team it changes. MinRole is "runner" or "admin"; an empty Team is the operator namespace (sandboxes the operator token creates).

type IngressTarget added in v0.3.1

type IngressTarget = models.IngressTarget

IngressTarget is the cluster-published address(es) DNS for a custom domain must point at. Source disambiguates the shape: "hostname" — Hostname holds a stable name to CNAME at; "ips" — IPs holds one or more raw IPs to A/AAAA at; "mixed" — both are populated; "unknown" — neither is set, the cluster has not gossiped a public address yet.

type Lifecycle

type Lifecycle = models.Lifecycle

type ListEgressProfilesOptions added in v0.6.6

type ListEgressProfilesOptions struct {
	Cursor string
	Limit  int
}

ListEgressProfilesOptions pages ListEgressProfiles.

type ListFilesOptions added in v0.6.12

type ListFilesOptions struct {
	// Depth is how many levels to go down: 1 (the default) is the folder's
	// own entries. Symlinked folders are listed but never entered.
	Depth int
	// Limit is the most entries to return; 0 means DefaultListLimit.
	Limit int
}

ListFilesOptions controls ListFiles. The zero value lists one level with a cap of DefaultListLimit entries.

type ListIdentityRolesOptions added in v0.6.12

type ListIdentityRolesOptions struct {
	Team   string
	Cursor string
	Limit  int
}

ListIdentityRolesOptions pages ListIdentityRoles.

type ListSnapshotsOptions added in v0.6.7

type ListSnapshotsOptions struct {
	Limit         int
	StartingAfter string
}

ListSnapshotsOptions pages ListSnapshots by name. Both fields are optional: Limit caps the page size and StartingAfter is the exclusive name cursor — pass the last name of the previous page to fetch the next one.

type MakeDirOptions added in v0.6.12

type MakeDirOptions struct {
	// Parents makes missing parent folders, and succeeds when the folder is
	// already there (like mkdir -p). Without it the parent must exist and
	// the folder must not.
	Parents bool
	// Mode is the new folder's permissions, such as 0o750; 0 means 0755.
	// With Parents, an existing folder is changed to Mode only when Mode is
	// set.
	Mode os.FileMode
}

MakeDirOptions controls MakeDir.

type MicroVMConfig

type MicroVMConfig struct {
	// PATToken is the bearer every request carries: the operator PAT, an
	// avm_ API token or an OIDC ID token. Empty falls back to SB_PAT_TOKEN,
	// then to its alias SB_API_TOKEN; when both are set, SB_PAT_TOKEN wins.
	PATToken   string
	APIUrl     string
	HTTPClient *http.Client
	// Team selects which of the credential's teams requests act for. It is
	// sent as the X-AerolVM-Team header on every request, WebSocket
	// handshakes included. Empty falls back to SB_TEAM; when both are empty
	// no header is sent and the server uses the credential's first matching
	// binding. The header only chooses among teams the credential is
	// already bound to: a team it does not hold is refused (403), and the
	// operator PAT ignores it.
	Team string
	// APIVersion pins which wire version of the sandbox daemon API the
	// client speaks. Empty defaults to the SDK's pinned default ("v1"
	// today). The Go SDK's package version and the wire version evolve
	// independently — bumping the SDK doesn't move the wire version.
	APIVersion string
	// Retry configures the policy for transient transport errors and retryable
	// HTTP status codes (421, 429, 502, 503, 504). Exec is narrower: it is
	// re-sent only when the connection never opened or on 429/503, because a
	// re-sent exec runs the command again. A 429 or 503 retry waits as long
	// as the server's Retry-After asks, up to RetryConfig.MaxRetryAfterMs.
	Retry *RetryConfig
}

type MountSpec

type MountSpec = models.MountSpec

type MountSpecRedacted

type MountSpecRedacted = models.MountSpecRedacted

type MountType

type MountType = models.MountType

type MoveFileOptions added in v0.6.12

type MoveFileOptions struct {
	// Overwrite replaces an existing destination file. Without it the move
	// is refused with a 409 conflict when the destination exists.
	Overwrite bool
}

MoveFileOptions controls MoveFile.

type NetworkLearned added in v0.6.6

type NetworkLearned = models.NetworkLearned

NetworkLearned is what a sandbox reached in learn mode and the allow list that would have allowed it (Sandbox.Learned).

type NetworkLearnedEntry added in v0.6.6

type NetworkLearnedEntry = models.NetworkLearnedEntry

NetworkLearnedEntry is one destination a learn-mode sandbox reached.

type NetworkPolicy added in v0.6.6

type NetworkPolicy = models.NetworkPolicy

NetworkPolicy is the policy a sandbox enforces after SetNetworkPolicy, with EgressStatus ("active", "held", "unavailable") for hostname rules on a container, or "unenforced" when the server's firewall is off and nothing filters the sandbox.

type NetworkPolicyCheckOptions added in v0.6.6

type NetworkPolicyCheckOptions = models.NetworkPolicyCheckRequest

NetworkPolicyCheckOptions asks whether a sandbox created with these egress fields would reach Destination ("host", "host:port", "IP" or "IP:port").

type NetworkPolicyCheckResult added in v0.6.6

type NetworkPolicyCheckResult = models.NetworkPolicyCheckResponse

NetworkPolicyCheckResult is the answer: Allowed, the deciding MatchedRule ("" for the default verdict), DefaultVerdict, and OutsideCeiling when an allow entry is outside this deployment's ceiling.

type NetworkPolicyOptions added in v0.6.6

type NetworkPolicyOptions = models.NetworkPolicyRequest

NetworkPolicyOptions is a sandbox's whole egress policy for SetNetworkPolicy. It replaces the current policy: a field left empty is cleared, so the zero value means open egress.

type NetworkUsage added in v0.1.7

type NetworkUsage = models.NetworkUsage

type PlacementRule added in v0.6.12

type PlacementRule = models.PlacementRule

PlacementRule limits which cluster nodes may run a sandbox, by zone and node labels (CreateSandboxOptions.Placement). No matching node makes the create fail with 409 placement_unsatisfiable.

type PlatformVolumeMount added in v0.5.4

type PlatformVolumeMount = models.PlatformVolumeMount

type PushWasmModuleOptions added in v0.5.3

type PushWasmModuleOptions = models.PushWasmModuleOptions

PushWasmModuleOptions is the input for Client.PushWasmModule (BYO upload).

type PushWasmModuleResponse added in v0.5.3

type PushWasmModuleResponse = models.PushWasmModuleResponse

PushWasmModuleResponse is the result of Client.PushWasmModule.

type RegisterSnapshotOptions added in v0.1.7

type RegisterSnapshotOptions struct {
	// Name is the human-readable identifier other callers use to reference
	// this snapshot in CreateSandboxOptions.Snapshot. Required.
	Name string
	// Image is a pre-built registry image reference (e.g. "python:3.12").
	// Mutually exclusive with DockerfileContent.
	Image string
	// DockerfileContent is the literal Dockerfile the daemon will build.
	// Mutually exclusive with Image. Use Image.Dockerfile() to obtain this
	// from an Image-builder graph, or RegisterSnapshotFromImage to skip the
	// indirection entirely.
	DockerfileContent string
	// ContextHashes references blobs uploaded ahead of time so COPY/ADD
	// steps in DockerfileContent can resolve. Requires the daemon to have
	// SB_IMAGE_BUILD_CONTEXT_ENABLED set; the resolver itself is not
	// implemented yet, so non-empty values currently return 501.
	ContextHashes []string
	// Entrypoint overrides the image's entrypoint. Echoed back on the
	// snapshot row so future sandbox-create calls inherit it.
	Entrypoint []string
	// RegionID pins the snapshot to a specific region for multi-region
	// deployments. Persisted on the row but not yet used for routing.
	RegionID string
	// CPU, GPU, MemoryMB, DiskGB are resource hints surfaced to clients.
	CPU      float64
	GPU      float64
	MemoryMB int
	DiskGB   int
}

RegisterSnapshotOptions is the input shape for Client.RegisterSnapshot. Exactly one of Image (a pre-built registry reference) or DockerfileContent (build inputs the daemon will compile) must be set.

The remaining fields capture the resource hints the snapshot will report when listed or used in CreateSandboxOptions.Snapshot.

type RegistryAuth added in v0.6.1

type RegistryAuth = models.RegistryAuth

type ResizeSandboxOptions

type ResizeSandboxOptions = models.ResizeSandboxRequest

type RetryConfig added in v0.4.1

type RetryConfig struct {
	// MaxRetries is the maximum number of retry attempts after the initial
	// request fails. Set to a negative number to disable retry entirely.
	// Defaults to 3.
	MaxRetries *int
	// BaseDelayMs is the initial backoff delay in milliseconds. Defaults to 200.
	BaseDelayMs *int
	// MaxDelayMs is the hard ceiling on the computed delay. Defaults to 5000.
	MaxDelayMs *int
	// MaxRetryAfterMs caps the wait before re-sending a 429 or 503. The
	// client waits as long as the server's Retry-After header asks (seconds
	// or an HTTP date), never less than its own backoff, plus up to a fifth
	// more so clients told the same value spread out; a longer ask is cut to
	// this. A missing or malformed header uses the backoff above. Defaults
	// to 30000; 0 or less ignores Retry-After. A cancelled ctx ends the wait.
	MaxRetryAfterMs *int
}

RetryConfig specifies how the SDK should retry transient errors.

type RevokeSandboxTokensResult added in v0.6.12

type RevokeSandboxTokensResult = models.RevokeSandboxTokensResponse

RevokeSandboxTokensResult is Sandbox.RevokeTokens' result: every token issued for the sandbox before TokensNotBefore no longer works.

type Sandbox

type Sandbox = models.Sandbox

type SandboxIdentity added in v0.6.12

type SandboxIdentity = models.SandboxIdentity

SandboxIdentity is Sandbox.Identity: what the sandbox's tokens say and where the token is. It never carries the token.

type SandboxSnapshot added in v0.1.7

type SandboxSnapshot = models.SandboxSnapshot

type SandboxToken added in v0.6.12

type SandboxToken = models.SandboxToken

SandboxToken is Sandbox.CreateToken's result. Token (avmst_…) is shown only here: the server keeps no copy. TokenID (stk_…) is safe to log.

type Session

type Session = models.Session

type SessionStatus

type SessionStatus = models.SessionStatus

type SetNetworkLimitsOptions added in v0.1.7

type SetNetworkLimitsOptions = models.UpdateNetworkLimitsRequest

type SnapshotList added in v0.6.7

type SnapshotList struct {
	Snapshots []SandboxSnapshot `json:"snapshots"`
	HasMore   bool              `json:"has_more"`
}

SnapshotList is one page of ListSnapshots. HasMore mirrors the wire `has_more` flag — true when more snapshots remain after this page, so a caller can keep paging by passing the last name as StartingAfter.

type StreamCallback

type StreamCallback func([]byte)

type StreamErrorCallback

type StreamErrorCallback func(string)

type TeamQuota added in v0.6.12

type TeamQuota = models.TeamQuota

TeamQuota is a team's quota, with Usage (what the team holds now) when read back.

type TeamQuotaOptions added in v0.6.12

type TeamQuotaOptions = models.TeamQuotaRequest

TeamQuotaOptions is the body of PutTeamQuota: MaxSandboxes, MaxCPU and MaxMemoryMB. A zero limit is no limit; at least one must be set.

type TeamQuotaUsage added in v0.6.12

type TeamQuotaUsage = models.TeamQuotaUsage

TeamQuotaUsage is what a team holds: every sandbox not deleted, at the size it asked for.

type Template added in v0.4.1

type Template = models.Template

Template is the server's Firecracker rootfs template row. Re-exported verbatim from pkg/models so the SDK stays aligned with the wire format.

type TemplateStatus added in v0.4.1

type TemplateStatus = models.TemplateStatus

TemplateStatus is the lifecycle of a Firecracker rootfs template. See plans/snapshot-clone-fast-boot.md for the state machine.

type UpdateLifecycleOptions

type UpdateLifecycleOptions = models.UpdateLifecycleRequest

type UploadFileOptions added in v0.6.12

type UploadFileOptions struct {
	// Append adds to the end of the file instead of replacing it.
	Append bool
	// CreateOnly writes only if the file does not exist yet. Otherwise the
	// upload fails with a 412, and of two uploads racing for one new path
	// exactly one wins.
	CreateOnly bool
	// Atomic writes a temp file and renames it into place, so a reader sees
	// the old file or the new one, never half of it. It cannot be combined
	// with Append.
	Atomic bool
	// Mode is the file's permissions after the write, such as 0o600. 0
	// leaves an existing file's permissions and gives a new file 0644.
	Mode os.FileMode
}

UploadFileOptions controls how an upload writes its file. The zero value is a plain upload: missing folders are made and an existing file is replaced in place.

type WarmPool added in v0.6.12

type WarmPool = models.WarmPool

WarmPool is a warm-pool entry: how many ready sandboxes every server with a warm pool keeps for one image. Status is set by GetWarmPool and ListWarmPools.

type WarmPoolOptions added in v0.6.12

type WarmPoolOptions = models.WarmPoolRequest

WarmPoolOptions is the body of PutWarmPool: a full replace.

type WarmPoolServerStatus added in v0.6.12

type WarmPoolServerStatus = models.WarmPoolServerStatus

WarmPoolServerStatus is one server's pool for an image.

type WarmPoolStatus added in v0.6.12

type WarmPoolStatus = models.WarmPoolStatus

WarmPoolStatus is ready and target slots in total and per server.

type WasmModule added in v0.5.3

type WasmModule = models.WasmModule

WasmModule is one row in the wasm_modules catalogue.

type WasmModuleStatus added in v0.5.3

type WasmModuleStatus = models.WasmModuleStatus

WasmModuleStatus is the catalogue lifecycle for WASM modules.

type WatchOptions added in v0.6.12

type WatchOptions struct {
	// Recursive also watches every folder below the path, including new
	// ones as they appear.
	Recursive bool
	// OnEvent is called once per event, in order, on the watch's reader
	// goroutine. Keep it quick: events wait while it runs.
	OnEvent func(FileEvent)
}

WatchOptions configures a file watch.

type WhoAmI added in v0.6.8

type WhoAmI = models.WhoAmI

WhoAmI is Client.WhoAmI: the caller's own principal, role, team ("*" for every team, absent for a managed account) and credential expiry (nil for one that does not expire, such as the operator token).

type WhoAmIPrincipal added in v0.6.8

type WhoAmIPrincipal = models.WhoAmIPrincipal

WhoAmIPrincipal names the caller: a Kind such as "operator", "token" or "oidc", a stable ID ("operator", "tok_…") and a display Name.

Jump to

Keyboard shortcuts

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