Documentation
¶
Index ¶
- Constants
- type APIToken
- type APITokenList
- type AuditCoverage
- type AuditEvent
- type AuditOptions
- type AuditPage
- type BuildImageOptions
- type BuildImagePushOptions
- type BuildImageResult
- type CloneGeneration
- type CopyFileOptions
- type CreateAPITokenOptions
- type CreateSandboxOptions
- type CreateSandboxTokenOptions
- type CreateSessionOptions
- type CreateTemplateOptions
- type CreateWasmModuleOptions
- type CreatedAPIToken
- type CustomDomain
- type CustomDomainDNSRecords
- type CustomDomainStatus
- type DNSRecord
- type DeleteFileOptions
- type DownloadFileOptions
- type EgressInject
- type EgressProfile
- type EgressProfileList
- type EgressProfileOptions
- type EgressProfileRef
- type EgressRule
- type ExecExitInfo
- type ExecRequest
- type ExecResult
- type ExecStreamOptions
- type ExposeProtocol
- type ExposeResult
- type ExposeVisibility
- type ExposedPort
- type Failover
- type FileEvent
- type FileInfo
- type FileList
- type FileMatch
- type GPURequest
- type GPUVendor
- type HealthStatus
- type IdentityOptions
- type IdentityRole
- type IdentityRoleList
- type IdentityRoleOptions
- type IngressTarget
- type Lifecycle
- type ListEgressProfilesOptions
- type ListFilesOptions
- type ListIdentityRolesOptions
- type ListSnapshotsOptions
- type MakeDirOptions
- type MicroVMConfig
- type MountSpec
- type MountSpecRedacted
- type MountType
- type MoveFileOptions
- type NetworkLearned
- type NetworkLearnedEntry
- type NetworkPolicy
- type NetworkPolicyCheckOptions
- type NetworkPolicyCheckResult
- type NetworkPolicyOptions
- type NetworkUsage
- type PlacementRule
- type PlatformVolumeMount
- type PushWasmModuleOptions
- type PushWasmModuleResponse
- type RegisterSnapshotOptions
- type RegistryAuth
- type ResizeSandboxOptions
- type RetryConfig
- type RevokeSandboxTokensResult
- type Sandbox
- type SandboxIdentity
- type SandboxSnapshot
- type SandboxToken
- type Session
- type SessionStatus
- type SetNetworkLimitsOptions
- type SnapshotList
- type StreamCallback
- type StreamErrorCallback
- type TeamQuota
- type TeamQuotaOptions
- type TeamQuotaUsage
- type Template
- type TemplateStatus
- type UpdateLifecycleOptions
- type UploadFileOptions
- type WarmPool
- type WarmPoolOptions
- type WarmPoolServerStatus
- type WarmPoolStatus
- type WasmModule
- type WasmModuleStatus
- type WatchOptions
- type WhoAmI
- type WhoAmIPrincipal
Constants ¶
const ( TemplateStatusPending = models.TemplateStatusPending TemplateStatusBuildingRootfs = models.TemplateStatusBuildingRootfs TemplateStatusSnapshotting = models.TemplateStatusSnapshotting TemplateStatusReady = models.TemplateStatusReady TemplateStatusReadyNoSnapshot = models.TemplateStatusReadyNoSnapshot TemplateStatusFailed = models.TemplateStatusFailed TemplateStatusUnhealthy = models.TemplateStatusUnhealthy )
const ( WasmModuleStatusReady = models.WasmModuleStatusReady WasmModuleStatusFailed = models.WasmModuleStatusFailed )
const ( FailoverPolicyNone = models.FailoverPolicyNone FailoverPolicyRecreate = models.FailoverPolicyRecreate )
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.
const ( SessionStatusRunning = models.SessionStatusRunning SessionStatusExited = models.SessionStatusExited SessionStatusKilled = models.SessionStatusKilled SessionStatusFailed = models.SessionStatusFailed )
const ( MountTypeS3 = models.MountTypeS3 MountTypeNFS = models.MountTypeNFS MountTypeSSHFS = models.MountTypeSSHFS MountTypeRclone = models.MountTypeRclone )
const ( RuntimeDocker = models.RuntimeDocker RuntimeGvisor = models.RuntimeGvisor RuntimeKata = models.RuntimeKata RuntimeFirecracker = models.RuntimeFirecracker RuntimeWasm = models.RuntimeWasm RuntimeIsolate = models.RuntimeIsolate )
const ( DurabilityEphemeral = models.DurabilityEphemeral DurabilityPassivatable = models.DurabilityPassivatable DurabilityDurable = models.DurabilityDurable )
const ( NetworkEgressModeEnforce = models.NetworkEgressModeEnforce NetworkEgressModeLearn = models.NetworkEgressModeLearn )
Egress modes for NetworkEgressMode.
const ( WarmPoolReplaceNow = models.WarmPoolReplaceNow WarmPoolReplaceAsUsed = models.WarmPoolReplaceAsUsed )
What a warm pool does when its image changes (WarmPoolOptions.OnImageChange).
const ( CustomDomainPendingDNS = models.CustomDomainPendingDNS CustomDomainIssuing = models.CustomDomainIssuing CustomDomainReady = models.CustomDomainReady CustomDomainFailed = models.CustomDomainFailed )
const ( IngressTargetSourceHostname = models.IngressTargetSourceHostname IngressTargetSourceIPs = models.IngressTargetSourceIPs IngressTargetSourceMixed = models.IngressTargetSourceMixed IngressTargetSourceUnknown = models.IngressTargetSourceUnknown )
IngressTarget Source values.
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).
const ( GPUVendorNVIDIA = models.GPUVendorNVIDIA GPUVendorAMD = models.GPUVendorAMD GPUVendorApple = models.GPUVendorApple )
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.
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.
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
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
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 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 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
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 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
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 ListEgressProfilesOptions ¶ added in v0.6.6
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
ListIdentityRolesOptions pages ListIdentityRoles.
type ListSnapshotsOptions ¶ added in v0.6.7
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 MountSpecRedacted ¶
type MountSpecRedacted = models.MountSpecRedacted
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 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 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
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
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
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
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.