Documentation
¶
Index ¶
- Constants
- Variables
- type APIError
- type Client
- func (c *Client) AttachSession(ctx context.Context, sandboxID, sessionID string, options SessionAttachOptions) (*SessionAttachHandle, error)
- func (c *Client) BuildImage(ctx context.Context, image *Image) (string, error)
- func (c *Client) BuildImageWithOptions(ctx context.Context, image *Image, opts sdktypes.BuildImageOptions) (sdktypes.BuildImageResult, error)
- func (c *Client) CheckNetworkPolicy(ctx context.Context, opts sdktypes.NetworkPolicyCheckOptions) (sdktypes.NetworkPolicyCheckResult, error)
- func (c *Client) CloneGeneration(ctx context.Context, id string) (sdktypes.CloneGeneration, error)
- func (c *Client) Create(ctx context.Context, opts sdktypes.CreateSandboxOptions) (*Sandbox, error)
- func (c *Client) CreateSession(ctx context.Context, sandboxID string, opts sdktypes.CreateSessionOptions) (sdktypes.Session, error)
- func (c *Client) CreateSnapshot(ctx context.Context, id, name string, opts ...SnapshotOption) (sdktypes.SandboxSnapshot, error)
- func (c *Client) CreateTemplate(ctx context.Context, opts sdktypes.CreateTemplateOptions) (sdktypes.Template, error)
- func (c *Client) CreateWasmModule(ctx context.Context, opts sdktypes.CreateWasmModuleOptions) (sdktypes.WasmModule, error)
- func (c *Client) CreateWithIdempotencyKey(ctx context.Context, opts sdktypes.CreateSandboxOptions, key string) (*Sandbox, error)
- func (c *Client) CreateWithImage(ctx context.Context, image *Image, opts sdktypes.CreateSandboxOptions) (*Sandbox, error)
- func (c *Client) DNSTarget(ctx context.Context) (sdktypes.IngressTarget, error)
- func (c *Client) DeleteEgressProfile(ctx context.Context, name string) error
- func (c *Client) DeleteIdentityRole(ctx context.Context, tag, team string) error
- func (c *Client) DeleteSession(ctx context.Context, sandboxID, sessionID string) error
- func (c *Client) DeleteSnapshot(ctx context.Context, name string) error
- func (c *Client) DeleteTeamQuota(ctx context.Context, team string) error
- func (c *Client) DeleteTemplate(ctx context.Context, id string) error
- func (c *Client) DeleteWarmPool(ctx context.Context, image string) error
- func (c *Client) DeleteWasmModule(ctx context.Context, id string) error
- func (c *Client) Destroy(ctx context.Context, id string) error
- func (c *Client) DestroyAll(ctx context.Context, tags map[string]string) ([]string, error)
- func (c *Client) ExecStream(ctx context.Context, id string, options sdktypes.ExecStreamOptions) (*ExecStreamHandle, error)
- func (c *Client) Get(ctx context.Context, id string, opts ...GetOption) (*Sandbox, error)
- func (c *Client) GetAudit(ctx context.Context, id string, opts sdktypes.AuditOptions) (sdktypes.AuditPage, error)
- func (c *Client) GetByName(ctx context.Context, name string, opts ...GetOption) (*Sandbox, error)
- func (c *Client) GetEgressProfile(ctx context.Context, name string) (sdktypes.EgressProfile, error)
- func (c *Client) GetNetworkLearned(ctx context.Context, id string) (sdktypes.NetworkLearned, error)
- func (c *Client) GetNetworkUsage(ctx context.Context, id string) (sdktypes.NetworkUsage, error)
- func (c *Client) GetOrCreate(ctx context.Context, name string, opts sdktypes.CreateSandboxOptions) (*Sandbox, bool, error)
- func (c *Client) GetSession(ctx context.Context, sandboxID, sessionID string) (sdktypes.Session, error)
- func (c *Client) GetSnapshot(ctx context.Context, name string) (sdktypes.SandboxSnapshot, error)
- func (c *Client) GetTeamQuota(ctx context.Context, team string) (sdktypes.TeamQuota, error)
- func (c *Client) GetTemplate(ctx context.Context, id string) (sdktypes.Template, error)
- func (c *Client) GetWarmPool(ctx context.Context, image string) (sdktypes.WarmPool, error)
- func (c *Client) GetWasmModule(ctx context.Context, id string) (sdktypes.WasmModule, error)
- func (c *Client) Health(ctx context.Context) (sdktypes.HealthStatus, error)
- func (c *Client) List(ctx context.Context, opts ...ListOption) ([]*Sandbox, error)
- func (c *Client) ListEgressProfiles(ctx context.Context, opts sdktypes.ListEgressProfilesOptions) (sdktypes.EgressProfileList, error)
- func (c *Client) ListIdentityRoles(ctx context.Context, opts sdktypes.ListIdentityRolesOptions) (sdktypes.IdentityRoleList, error)
- func (c *Client) ListPage(ctx context.Context, pageToken string, opts ...ListOption) ([]*Sandbox, string, error)
- func (c *Client) ListSessions(ctx context.Context, sandboxID string) ([]sdktypes.Session, error)
- func (c *Client) ListSnapshots(ctx context.Context, opts sdktypes.ListSnapshotsOptions) (sdktypes.SnapshotList, error)
- func (c *Client) ListTemplates(ctx context.Context) ([]sdktypes.Template, error)
- func (c *Client) ListWarmPools(ctx context.Context) ([]sdktypes.WarmPool, error)
- func (c *Client) ListWasmModules(ctx context.Context) ([]sdktypes.WasmModule, error)
- func (c *Client) Mounts(ctx context.Context, id string) ([]sdktypes.MountSpecRedacted, error)
- func (c *Client) PushWasmModule(ctx context.Context, opts sdktypes.PushWasmModuleOptions) (sdktypes.PushWasmModuleResponse, error)
- func (c *Client) PutEgressProfile(ctx context.Context, name string, opts sdktypes.EgressProfileOptions) (sdktypes.EgressProfile, error)
- func (c *Client) PutIdentityRole(ctx context.Context, tag string, opts sdktypes.IdentityRoleOptions) (sdktypes.IdentityRole, error)
- func (c *Client) PutTeamQuota(ctx context.Context, team string, opts sdktypes.TeamQuotaOptions) (sdktypes.TeamQuota, error)
- func (c *Client) PutWarmPool(ctx context.Context, image string, opts sdktypes.WarmPoolOptions) (sdktypes.WarmPool, error)
- func (c *Client) RebuildTemplate(ctx context.Context, id string) (sdktypes.Template, error)
- func (c *Client) Reconcile(ctx context.Context) error
- func (c *Client) RegisterSnapshot(ctx context.Context, opts sdktypes.RegisterSnapshotOptions) (sdktypes.SandboxSnapshot, error)
- func (c *Client) RegisterSnapshotFromImage(ctx context.Context, name string, image *Image, ...) (sdktypes.SandboxSnapshot, error)
- func (c *Client) Resize(ctx context.Context, id string, opts sdktypes.ResizeSandboxOptions) (*Sandbox, error)
- func (c *Client) ResizeSession(ctx context.Context, sandboxID, sessionID string, cols, rows int) error
- func (c *Client) RevokeSandboxTokens(ctx context.Context, id string) (sdktypes.RevokeSandboxTokensResult, error)
- func (c *Client) SessionLog(ctx context.Context, sandboxID, sessionID string) ([]byte, error)
- func (c *Client) SessionRecording(ctx context.Context, sandboxID, sessionID string) ([]byte, error)
- func (c *Client) SetNetworkLimits(ctx context.Context, id string, opts sdktypes.SetNetworkLimitsOptions) (sdktypes.NetworkUsage, error)
- func (c *Client) SetNetworkPolicy(ctx context.Context, id string, opts sdktypes.NetworkPolicyOptions) (sdktypes.NetworkPolicy, error)
- func (c *Client) SignalSession(ctx context.Context, sandboxID, sessionID, signal string) error
- func (c *Client) Start(ctx context.Context, id string) (*Sandbox, error)
- func (c *Client) Stop(ctx context.Context, id string) (*Sandbox, error)
- func (c *Client) Tokens() *Tokens
- func (c *Client) UpdateLifecycle(ctx context.Context, id string, lifecycle sdktypes.Lifecycle) (*Sandbox, error)
- func (c *Client) WatchFiles(ctx context.Context, id, path string, options sdktypes.WatchOptions) (*WatchHandle, error)
- func (c *Client) WhoAmI(ctx context.Context) (sdktypes.WhoAmI, error)
- type CustomDomainOption
- type ExecStreamHandle
- func (h *ExecStreamHandle) Close() error
- func (h *ExecStreamHandle) Resize(cols, rows int) error
- func (h *ExecStreamHandle) Signal(name string) error
- func (h *ExecStreamHandle) Wait() (sdktypes.ExecExitInfo, error)
- func (h *ExecStreamHandle) Write(data []byte) error
- func (h *ExecStreamHandle) WriteString(data string) error
- type ExposeOption
- type GetOption
- type Image
- func (i *Image) Cmd(commands ...string) *Image
- func (i *Image) Dockerfile() string
- func (i *Image) Entrypoint(commands ...string) *Image
- func (i *Image) Env(envVars map[string]string) *Image
- func (i *Image) Err() error
- func (i *Image) Expose(port int) *Image
- func (i *Image) RunCommands(commands ...any) *Image
- func (i *Image) User(username string) *Image
- func (i *Image) Workdir(dirPath string) *Image
- type ListOption
- type Sandbox
- func (s *Sandbox) AddCustomDomain(ctx context.Context, hostname string, opts ...CustomDomainOption) ([]sdktypes.CustomDomain, error)
- func (s *Sandbox) AttachSession(ctx context.Context, sessionID string, options SessionAttachOptions) (*SessionAttachHandle, error)
- func (s *Sandbox) Audit(ctx context.Context, opts sdktypes.AuditOptions) (sdktypes.AuditPage, error)
- func (s *Sandbox) CloneGeneration(ctx context.Context) (sdktypes.CloneGeneration, error)
- func (s *Sandbox) Close(ctx context.Context) error
- func (s *Sandbox) CopyFile(ctx context.Context, source, destination string, opts sdktypes.CopyFileOptions) error
- func (s *Sandbox) CreateSession(ctx context.Context, opts sdktypes.CreateSessionOptions) (sdktypes.Session, error)
- func (s *Sandbox) CreateSnapshot(ctx context.Context, name string, opts ...SnapshotOption) (sdktypes.SandboxSnapshot, error)
- func (s *Sandbox) CreateToken(ctx context.Context, opts sdktypes.CreateSandboxTokenOptions) (sdktypes.SandboxToken, error)
- func (s *Sandbox) CustomDomainDNS(ctx context.Context) (sdktypes.CustomDomainDNSRecords, error)
- func (s *Sandbox) DeleteFile(ctx context.Context, path string, opts sdktypes.DeleteFileOptions) error
- func (s *Sandbox) DeleteSession(ctx context.Context, sessionID string) error
- func (s *Sandbox) Destroy(ctx context.Context) error
- func (s *Sandbox) DownloadFile(ctx context.Context, targetPath string) ([]byte, error)
- func (s *Sandbox) DownloadFileStream(ctx context.Context, targetPath string) (io.ReadCloser, error)
- func (s *Sandbox) DownloadFileStreamWithOptions(ctx context.Context, targetPath string, opts sdktypes.DownloadFileOptions) (io.ReadCloser, error)
- func (s *Sandbox) DownloadFileWithOptions(ctx context.Context, targetPath string, opts sdktypes.DownloadFileOptions) ([]byte, error)
- func (s *Sandbox) Exec(ctx context.Context, request sdktypes.ExecRequest) (sdktypes.ExecResult, error)
- func (s *Sandbox) ExecCommand(ctx context.Context, command string) (sdktypes.ExecResult, error)
- func (s *Sandbox) ExecStream(ctx context.Context, options sdktypes.ExecStreamOptions) (*ExecStreamHandle, error)
- func (s *Sandbox) ExposePort(ctx context.Context, port int, opts ...ExposeOption) (sdktypes.ExposeResult, error)
- func (s *Sandbox) FileExists(ctx context.Context, path string) (bool, error)
- func (s *Sandbox) FindInFiles(ctx context.Context, path, text string) ([]sdktypes.FileMatch, error)
- func (s *Sandbox) GetFileInfo(ctx context.Context, path string) (sdktypes.FileInfo, error)
- func (s *Sandbox) GetNetworkUsage(ctx context.Context) (sdktypes.NetworkUsage, error)
- func (s *Sandbox) GetSession(ctx context.Context, sessionID string) (sdktypes.Session, error)
- func (s *Sandbox) Learned(ctx context.Context) (sdktypes.NetworkLearned, error)
- func (s *Sandbox) ListCustomDomains(ctx context.Context) ([]sdktypes.CustomDomain, error)
- func (s *Sandbox) ListFiles(ctx context.Context, path string, opts sdktypes.ListFilesOptions) (sdktypes.FileList, error)
- func (s *Sandbox) ListSessions(ctx context.Context) ([]sdktypes.Session, error)
- func (s *Sandbox) MakeDir(ctx context.Context, path string, opts sdktypes.MakeDirOptions) error
- func (s *Sandbox) MoveFile(ctx context.Context, source, destination string, opts sdktypes.MoveFileOptions) error
- func (s *Sandbox) Refresh(ctx context.Context) error
- func (s *Sandbox) RemoveCustomDomain(ctx context.Context, hostname string) error
- func (s *Sandbox) Resize(ctx context.Context, opts sdktypes.ResizeSandboxOptions) error
- func (s *Sandbox) ResizeSession(ctx context.Context, sessionID string, cols, rows int) error
- func (s *Sandbox) RevokeTokens(ctx context.Context) (sdktypes.RevokeSandboxTokensResult, error)
- func (s *Sandbox) SearchFiles(ctx context.Context, path, pattern string) ([]string, error)
- func (s *Sandbox) SessionLog(ctx context.Context, sessionID string) ([]byte, error)
- func (s *Sandbox) SessionRecording(ctx context.Context, sessionID string) ([]byte, error)
- func (s *Sandbox) SetNetworkLimits(ctx context.Context, opts sdktypes.SetNetworkLimitsOptions) (sdktypes.NetworkUsage, error)
- func (s *Sandbox) SetNetworkPolicy(ctx context.Context, opts sdktypes.NetworkPolicyOptions) (sdktypes.NetworkPolicy, error)
- func (s *Sandbox) SignalSession(ctx context.Context, sessionID, signal string) error
- func (s *Sandbox) Start(ctx context.Context) error
- func (s *Sandbox) Stop(ctx context.Context) error
- func (s *Sandbox) ToolboxRequest(ctx context.Context, method, path string, query url.Values, body []byte, ...) (*http.Response, error)
- func (s *Sandbox) UnexposePort(ctx context.Context, port int) error
- func (s *Sandbox) UpdateLifecycle(ctx context.Context, lifecycle sdktypes.Lifecycle) error
- func (s *Sandbox) UploadDir(ctx context.Context, localDir, remoteDir string) error
- func (s *Sandbox) UploadFile(ctx context.Context, targetPath string, data []byte) error
- func (s *Sandbox) UploadFileStream(ctx context.Context, targetPath string, r io.Reader) error
- func (s *Sandbox) UploadFileStreamWithOptions(ctx context.Context, targetPath string, r io.Reader, ...) error
- func (s *Sandbox) UploadFileWithOptions(ctx context.Context, targetPath string, data []byte, ...) error
- func (s *Sandbox) WatchFiles(ctx context.Context, path string, options sdktypes.WatchOptions) (*WatchHandle, error)
- type SessionAttachHandle
- func (h *SessionAttachHandle) Close() error
- func (h *SessionAttachHandle) Resize(cols, rows int) error
- func (h *SessionAttachHandle) Signal(name string) error
- func (h *SessionAttachHandle) Wait() (int, string, error)
- func (h *SessionAttachHandle) Write(data []byte) error
- func (h *SessionAttachHandle) WriteString(data string) error
- type SessionAttachOptions
- type SnapshotOption
- type StreamError
- type Tokens
- type UnsupportedFeatureError
- type WatchHandle
Constants ¶
const FeatureFilesWatch = apiclient.FeatureFilesWatch
FeatureFilesWatch is the feature an *UnsupportedFeatureError names when a sandbox's agent predates file watching.
const HeaderTeam = apiclient.HeaderTeam
HeaderTeam is the header the client sends its team in (MicroVMConfig.Team or SB_TEAM) on every request.
Variables ¶
var ( ErrNotFound = apiclient.ErrNotFound ErrConflict = apiclient.ErrConflict ErrCapacity = apiclient.ErrCapacity ErrTimeout = apiclient.ErrTimeout ErrAuth = apiclient.ErrAuth ErrNameLookupUnsupported = apiclient.ErrNameLookupUnsupported ErrUnsupportedFeature = apiclient.ErrUnsupportedFeature // ErrFileTooLarge means a download was larger than its MaxBytes. ErrFileTooLarge = apiclient.ErrFileTooLarge )
Sentinels for errors.Is. ErrNotFound matches a 404 (and a GetByName miss), ErrConflict a 409, ErrCapacity a 503, ErrTimeout a 408 or 504, ErrAuth a 401 or 403, ErrNameLookupUnsupported a server that ignored `?name=`, and ErrUnsupportedFeature an *UnsupportedFeatureError. The status sentinels match an *APIError, which errors.As still reads for the details.
Functions ¶
This section is empty.
Types ¶
type APIError ¶ added in v0.6.5
APIError is an HTTP error response from sandboxd: status, the server's optional stable error code, and its message (Error() returns the message unchanged). Use errors.As to read it.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
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
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) CheckNetworkPolicy ¶ added in v0.6.6
func (c *Client) CheckNetworkPolicy(ctx context.Context, opts sdktypes.NetworkPolicyCheckOptions) (sdktypes.NetworkPolicyCheckResult, error)
CheckNetworkPolicy asks whether a sandbox created with these egress fields would reach a destination, with the same matcher the filter enforces. No sandbox is needed.
func (*Client) CloneGeneration ¶ added in v0.5.2
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 ¶
Create creates a sandbox. It sends a random Idempotency-Key, made once for this call and sent unchanged on each of its automatic retries, so a create retried after a timeout gets back the sandbox the first attempt made instead of making a second one. Use CreateWithIdempotencyKey to choose the key.
func (*Client) CreateSession ¶
func (*Client) CreateSnapshot ¶ added in v0.1.7
func (c *Client) CreateSnapshot(ctx context.Context, id, name string, opts ...SnapshotOption) (sdktypes.SandboxSnapshot, error)
CreateSnapshot saves the sandbox id's files as a snapshot named name.
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) CreateWithIdempotencyKey ¶ added in v0.6.10
func (c *Client) CreateWithIdempotencyKey(ctx context.Context, opts sdktypes.CreateSandboxOptions, key string) (*Sandbox, error)
CreateWithIdempotencyKey is Create with key as the Idempotency-Key. A create sent again with the same key and the same options returns the sandbox the first one made instead of making a second, so your own retries of the whole call are safe too, such as after your process restarts. The same key with different options fails with an *APIError whose Code is "idempotency_key_reused" (HTTP 422). Keys are scoped to the caller's account. A blank key gets a random one, as Create does.
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
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) DeleteEgressProfile ¶ added in v0.6.6
DeleteEgressProfile deletes a profile; one that sandboxes still reference is refused (409).
func (*Client) DeleteIdentityRole ¶ added in v0.6.12
DeleteIdentityRole takes a role tag off a team's allow list (team "" is the operator namespace). Admin only. Sandboxes that use it keep their current token (at most one hour) and get no new one. Deleting a tag that is already gone succeeds.
func (*Client) DeleteSession ¶
func (*Client) DeleteSnapshot ¶ added in v0.6.7
DeleteSnapshot removes a named snapshot. Returns ErrNotFound (404) when no snapshot by that name exists.
func (*Client) DeleteTeamQuota ¶ added in v0.6.12
DeleteTeamQuota removes a team's quota. Removing one that is already gone succeeds.
func (*Client) DeleteTemplate ¶ added in v0.4.1
func (*Client) DeleteWarmPool ¶ added in v0.6.12
DeleteWarmPool deletes an image's warm-pool entry; its warm sandboxes are removed. Deleting a missing entry succeeds.
func (*Client) DeleteWasmModule ¶ added in v0.5.3
func (*Client) DestroyAll ¶ added in v0.6.12
DestroyAll deletes every sandbox of the caller's that carries all of tags and returns the IDs of the ones now gone. It lists every page first, then deletes them one at a time. A sandbox that is already gone (404) counts as deleted, so a second call, or two calls at once, is safe. Any other failed delete stops it: the error is returned with the IDs deleted so far, and calling it again finishes the job. tags must not be empty, since with no filter it would delete every sandbox the caller owns.
func (*Client) ExecStream ¶
func (c *Client) ExecStream(ctx context.Context, id string, options sdktypes.ExecStreamOptions) (*ExecStreamHandle, error)
func (*Client) GetAudit ¶ added in v0.6.6
func (c *Client) GetAudit(ctx context.Context, id string, opts sdktypes.AuditOptions) (sdktypes.AuditPage, error)
GetAudit reads one page of a sandbox's audit log: outbound connections and egress denials (Kind "egress") and secret reads.
func (*Client) GetByName ¶ added in v0.6.5
GetByName returns the caller's sandbox called name, with one request. Names are unique per owner. A missing name returns an error matching ErrNotFound. A server that predates name lookup ignores `?name=` and returns an unfiltered list; GetByName detects that and returns an error matching ErrNameLookupUnsupported instead of picking a row.
func (*Client) GetEgressProfile ¶ added in v0.6.6
GetEgressProfile reads one named egress profile.
func (*Client) GetNetworkLearned ¶ added in v0.6.6
GetNetworkLearned reads what a sandbox reached in learn mode and the allow list that would have allowed it.
func (*Client) GetNetworkUsage ¶ added in v0.1.7
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) GetOrCreate ¶ added in v0.6.12
func (c *Client) GetOrCreate(ctx context.Context, name string, opts sdktypes.CreateSandboxOptions) (*Sandbox, bool, error)
GetOrCreate returns the caller's sandbox called name, creating it from opts when there is none; created is true only when this call made it. It is safe to retry and to run concurrently:
GET ?name=name ── hit ──► (existing, false)
│ miss
POST {opts, name}
├─ 201 ──────────────► (new, true)
├─ 409 ─► GET ?name= ─► (the winner, false)
└─ lost reply ─► the client retries the same POST (same
Idempotency-Key) ─► 201, or 409 as above
Names are unique per owner, so of two callers racing to create a name one gets a 409 and reads the other's sandbox. A 409 whose name still cannot be found is a conflict on something else and is returned as is. An existing sandbox is returned unchanged: its image and settings are not compared with opts. opts.Name may be empty or repeat name.
func (*Client) GetSession ¶
func (*Client) GetSnapshot ¶ added in v0.6.7
GetSnapshot reads one named snapshot's metadata. Returns ErrNotFound (404) when no snapshot by that name exists.
func (*Client) GetTeamQuota ¶ added in v0.6.12
GetTeamQuota reads a team's quota and what the team holds now (Usage). A team with no quota is a 404 *APIError.
func (*Client) GetTemplate ¶ added in v0.4.1
func (*Client) GetWarmPool ¶ added in v0.6.12
GetWarmPool reads an image's warm-pool entry with its status (ready and target, in total and per server).
func (*Client) GetWasmModule ¶ added in v0.5.3
func (*Client) ListEgressProfiles ¶ added in v0.6.6
func (c *Client) ListEgressProfiles(ctx context.Context, opts sdktypes.ListEgressProfilesOptions) (sdktypes.EgressProfileList, error)
ListEgressProfiles reads one page of your egress profiles by name.
func (*Client) ListIdentityRoles ¶ added in v0.6.12
func (c *Client) ListIdentityRoles(ctx context.Context, opts sdktypes.ListIdentityRolesOptions) (sdktypes.IdentityRoleList, error)
ListIdentityRoles reads one page of a team's cloud identity allow list. Admin only.
func (*Client) ListPage ¶ added in v0.6.1
func (c *Client) ListPage(ctx context.Context, pageToken string, opts ...ListOption) ([]*Sandbox, string, error)
ListPage fetches one bounded page and returns the server's opaque token for the next page. Callers inventorying large fleets should loop until the token is empty instead of materializing every sandbox in one slice.
func (*Client) ListSessions ¶
func (*Client) ListSnapshots ¶ added in v0.6.7
func (c *Client) ListSnapshots(ctx context.Context, opts sdktypes.ListSnapshotsOptions) (sdktypes.SnapshotList, error)
ListSnapshots reads one page of your snapshots ordered by name. Pass opts.Limit to cap the page and opts.StartingAfter (the last name of the previous page) to keep paging while the returned SnapshotList.HasMore is true.
func (*Client) ListTemplates ¶ added in v0.4.1
func (*Client) ListWarmPools ¶ added in v0.6.12
ListWarmPools reads every warm-pool entry, by image, with its status.
func (*Client) ListWasmModules ¶ added in v0.5.3
func (*Client) Mounts ¶
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) PutEgressProfile ¶ added in v0.6.6
func (c *Client) PutEgressProfile(ctx context.Context, name string, opts sdktypes.EgressProfileOptions) (sdktypes.EgressProfile, error)
PutEgressProfile creates or replaces a named egress profile (a full replace: the same body twice is a no-op). Sandboxes reference it through EgressProfiles, and a change reaches every one of them.
func (*Client) PutIdentityRole ¶ added in v0.6.12
func (c *Client) PutIdentityRole(ctx context.Context, tag string, opts sdktypes.IdentityRoleOptions) (sdktypes.IdentityRole, error)
PutIdentityRole puts a role tag on a team's cloud identity allow list, or changes its minimum caller role ("runner" or "admin"). Admin only. The same call twice changes nothing, so it is safe to retry. Sandboxes are created with a tag through CreateSandboxOptions.Identity.
func (*Client) PutTeamQuota ¶ added in v0.6.12
func (c *Client) PutTeamQuota(ctx context.Context, team string, opts sdktypes.TeamQuotaOptions) (sdktypes.TeamQuota, error)
PutTeamQuota sets a team's quota: the most sandboxes, CPU and memory its sandboxes may hold. Admin only. The same limits twice change nothing. A create, resize or start past the quota fails with an *APIError whose StatusCode is 429 and Code is "team_quota_exceeded".
func (*Client) PutWarmPool ¶ added in v0.6.12
func (c *Client) PutWarmPool(ctx context.Context, image string, opts sdktypes.WarmPoolOptions) (sdktypes.WarmPool, error)
PutWarmPool sets how many ready sandboxes every server with a warm pool keeps for an image (a full replace: the same call twice is a no-op). A create that names the image then starts from a warm sandbox. Admin only.
func (*Client) RebuildTemplate ¶ added in v0.4.1
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) 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) ResizeSession ¶
func (*Client) RevokeSandboxTokens ¶ added in v0.6.12
func (c *Client) RevokeSandboxTokens(ctx context.Context, id string) (sdktypes.RevokeSandboxTokensResult, error)
RevokeSandboxTokens makes every token issued for the sandbox id so far stop working (see Sandbox.RevokeTokens).
func (*Client) SessionLog ¶
func (*Client) SessionRecording ¶
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) SetNetworkPolicy ¶ added in v0.6.6
func (c *Client) SetNetworkPolicy(ctx context.Context, id string, opts sdktypes.NetworkPolicyOptions) (sdktypes.NetworkPolicy, error)
SetNetworkPolicy replaces a sandbox's egress policy while it runs and returns once the new policy is enforced. Sending the same policy again is a no-op, so it is safe to retry.
func (*Client) SignalSession ¶
func (*Client) Tokens ¶ added in v0.6.8
Tokens manages scoped API tokens (avm_…) for services and CI. Creating and revoking needs an admin credential; listing needs an auditor or an admin.
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.
func (*Client) WatchFiles ¶ added in v0.6.12
func (c *Client) WatchFiles(ctx context.Context, id, path string, options sdktypes.WatchOptions) (*WatchHandle, error)
WatchFiles streams changes under path in sandbox id: create, write, remove, rename and chmod events, plus overflow when events were lost. It returns once the watch is armed.
Only gVisor and Firecracker sandboxes can watch; any other runtime answers an *APIError with status 501. A sandbox whose agent predates file watching answers an *UnsupportedFeatureError (errors.Is(err, ErrUnsupportedFeature)). The request is not retried: a watch is a stream.
ctx bounds the whole watch, not only the call that arms it: cancelling it (or its deadline passing) ends the stream, as Stop on the handle does. To arm with a time limit and then watch for longer, pass a ctx without a deadline and stop the watch through the handle.
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.
func WithVisibility ¶ added in v0.6.12
func WithVisibility(v sdktypes.ExposeVisibility) ExposeOption
WithVisibility sets who can open the port's URL. ExposeVisibilityToken makes it need a sandbox token for this port (Sandbox.CreateToken with Port). Without it a new port is public and an exposed port keeps what it has; pass it to change it.
type GetOption ¶ added in v0.6.1
type GetOption func(*getOptions)
GetOption customizes a Get call.
func WithGetIncludeEnv ¶ added in v0.6.1
func WithGetIncludeEnv() GetOption
WithGetIncludeEnv requests env on Get (`?include_env=true`).
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 FromDockerfile ¶ added in v0.1.7
FromDockerfile wraps an existing Dockerfile string and normalizes the final trailing newline so builds stay content-stable across callers.
func (*Image) Dockerfile ¶ added in v0.1.7
func (*Image) Entrypoint ¶ added in v0.1.7
func (*Image) Env ¶ added in v0.1.7
Env appends one ENV line containing all provided key/value pairs.
func (*Image) RunCommands ¶ added in v0.1.7
RunCommands appends one RUN per string argument. A []string argument is joined with && so the commands share one layer.
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 WithIncludeEnv ¶ added in v0.6.1
func WithIncludeEnv() ListOption
WithIncludeEnv requests sandbox env vars on List/Get (`?include_env=true`). Env is omitted by default; opt-in reads are audited server-side.
func WithLimit ¶ added in v0.6.5
func WithLimit(n int) ListOption
WithLimit asks for at most n sandboxes per page (`?limit=<n>`); with ListPage that bounds one call, and List still drains every page. The server clamps n to its maximum (500). Servers that predate single-node paging ignore it there and return every row, so a caller that needs a hard bound must also cap the slice it gets back.
func WithName ¶ added in v0.6.5
func WithName(name string) ListOption
WithName filters to the caller's sandbox with exactly this name (`?name=<name>`); the result has zero or one entries. Names are unique per owner. Servers that predate name lookup ignore the filter and return a normal list, so prefer GetByName, which checks the reply.
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
// DestroyOnClose makes Close delete the sandbox. It is off by default,
// so `defer sb.Close(ctx)` alone leaves the sandbox running; set it to
// opt in to delete-on-exit (plan S2).
DestroyOnClose bool
// 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) Audit ¶ added in v0.6.6
func (s *Sandbox) Audit(ctx context.Context, opts sdktypes.AuditOptions) (sdktypes.AuditPage, error)
Audit reads one page of this sandbox's audit log (see Client.GetAudit).
func (*Sandbox) CloneGeneration ¶ added in v0.5.2
CloneGeneration reads this sandbox's clone-generation token (changes on resume-from-snapshot). Read-only; does not reseed in-guest PRNGs.
func (*Sandbox) Close ¶ added in v0.6.12
Close deletes the sandbox when DestroyOnClose is true and does nothing otherwise, so `defer sb.Close(ctx)` is the Go form of a block that cleans up after itself. The delete ignores ctx's cancellation and deadline (it keeps ctx's values) and has its own two-minute bound. A sandbox that is already gone counts as deleted, and a second Close does nothing.
func (*Sandbox) CopyFile ¶ added in v0.6.12
func (s *Sandbox) CopyFile(ctx context.Context, source, destination string, opts sdktypes.CopyFileOptions) error
CopyFile copies a file, or a folder with Recursive.
func (*Sandbox) CreateSession ¶
func (*Sandbox) CreateSnapshot ¶ added in v0.1.7
func (s *Sandbox) CreateSnapshot(ctx context.Context, name string, opts ...SnapshotOption) (sdktypes.SandboxSnapshot, error)
CreateSnapshot saves this sandbox's files as a snapshot named name.
func (*Sandbox) CreateToken ¶ added in v0.6.12
func (s *Sandbox) CreateToken(ctx context.Context, opts sdktypes.CreateSandboxTokenOptions) (sdktypes.SandboxToken, error)
CreateToken issues a signed token for this sandbox only, to hand to a browser or an end user. With opts.Port the token opens that port's public URL (a port exposed with token visibility); without it the token is for the toolbox: commands, files and sessions. Each call makes a new token, and the server keeps no copy, so Token is shown only in the result. A token stops working when it expires, when the sandbox is deleted, or when RevokeTokens is called.
func (*Sandbox) CustomDomainDNS ¶ added in v0.3.1
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) DeleteFile ¶ added in v0.6.12
func (s *Sandbox) DeleteFile(ctx context.Context, path string, opts sdktypes.DeleteFileOptions) error
DeleteFile deletes a file, or a folder and its contents with Recursive.
func (*Sandbox) DeleteSession ¶
func (*Sandbox) DownloadFile ¶
func (*Sandbox) DownloadFileStream ¶ added in v0.6.5
DownloadFileStream opens targetPath for reading without buffering it. The caller must Close the returned body; closing early ends the transfer, so reading only the head of a large file costs only the head.
func (*Sandbox) DownloadFileStreamWithOptions ¶ added in v0.6.12
func (s *Sandbox) DownloadFileStreamWithOptions(ctx context.Context, targetPath string, opts sdktypes.DownloadFileOptions) (io.ReadCloser, error)
DownloadFileStreamWithOptions is DownloadFileStream with a size limit: the read that passes opts.MaxBytes fails with ErrFileTooLarge.
func (*Sandbox) DownloadFileWithOptions ¶ added in v0.6.12
func (s *Sandbox) DownloadFileWithOptions(ctx context.Context, targetPath string, opts sdktypes.DownloadFileOptions) ([]byte, error)
DownloadFileWithOptions reads a whole file, refusing one larger than opts.MaxBytes with ErrFileTooLarge. It retries like DownloadFile.
func (*Sandbox) Exec ¶
func (s *Sandbox) Exec(ctx context.Context, request sdktypes.ExecRequest) (sdktypes.ExecResult, error)
func (*Sandbox) ExecCommand ¶
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.
A sandbox created with AllowPublicTraffic omitted or false starts private, with no public URL; the first ExposePort makes it public, whichever of the two it was. Set AllowPublicTraffic to true to make it public from boot.
func (*Sandbox) FileExists ¶ added in v0.6.12
FileExists reports whether path exists in the sandbox.
func (*Sandbox) FindInFiles ¶ added in v0.6.12
FindInFiles returns each line under path that contains text.
func (*Sandbox) GetFileInfo ¶ added in v0.6.12
GetFileInfo describes one path. A symlink is followed.
func (*Sandbox) GetNetworkUsage ¶ added in v0.1.7
func (*Sandbox) GetSession ¶
func (*Sandbox) Learned ¶ added in v0.6.6
Learned reads what this sandbox reached in learn mode (see Client.GetNetworkLearned). A recording stays readable after a switch to enforce, until the sandbox is destroyed.
func (*Sandbox) ListCustomDomains ¶ added in v0.3.1
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) ListFiles ¶ added in v0.6.12
func (s *Sandbox) ListFiles(ctx context.Context, path string, opts sdktypes.ListFilesOptions) (sdktypes.FileList, error)
ListFiles lists a folder. The zero options list one level, up to sdktypes.DefaultListLimit entries; FileList.Truncated says more exist.
func (*Sandbox) ListSessions ¶
func (*Sandbox) MoveFile ¶ added in v0.6.12
func (s *Sandbox) MoveFile(ctx context.Context, source, destination string, opts sdktypes.MoveFileOptions) error
MoveFile moves or renames a file or folder. Without Overwrite, an existing destination is a 409 conflict (errors.Is(err, ErrConflict)).
func (*Sandbox) RemoveCustomDomain ¶ added in v0.3.1
RemoveCustomDomain detaches a hostname previously attached via AddCustomDomain or CreateSandboxOptions.CustomDomains. Case-insensitive; the server normalizes before comparing.
func (*Sandbox) ResizeSession ¶
func (*Sandbox) RevokeTokens ¶ added in v0.6.12
RevokeTokens makes every token issued for this sandbox so far stop working, toolbox and port tokens alike. A token made after the call works. Safe to call again.
func (*Sandbox) SearchFiles ¶ added in v0.6.12
SearchFiles returns the paths under path whose name matches a glob such as "*.py".
func (*Sandbox) SessionLog ¶
func (*Sandbox) SessionRecording ¶
func (*Sandbox) SetNetworkLimits ¶ added in v0.1.7
func (s *Sandbox) SetNetworkLimits(ctx context.Context, opts sdktypes.SetNetworkLimitsOptions) (sdktypes.NetworkUsage, error)
func (*Sandbox) SetNetworkPolicy ¶ added in v0.6.6
func (s *Sandbox) SetNetworkPolicy(ctx context.Context, opts sdktypes.NetworkPolicyOptions) (sdktypes.NetworkPolicy, error)
SetNetworkPolicy replaces this sandbox's egress policy (see Client.SetNetworkPolicy) and updates its policy fields.
func (*Sandbox) SignalSession ¶
func (*Sandbox) ToolboxRequest ¶ added in v0.6.5
func (s *Sandbox) ToolboxRequest(ctx context.Context, method, path string, query url.Values, body []byte, contentType string) (*http.Response, error)
ToolboxRequest sends one raw request to this sandbox's toolbox (path such as "/files" or "/process/execute") and returns the response for the caller to read and close. Use it for toolbox endpoints without a typed method, or to bound how much of a response you read. A 4xx/5xx returns an *APIError. Reads (GET/HEAD) retry on transient statuses; requests with a body are sent once.
func (*Sandbox) UpdateLifecycle ¶
func (*Sandbox) UploadDir ¶ added in v0.6.12
UploadDir copies the local folder localDir into remoteDir in the sandbox, made if missing (a gzipped tar the sandbox unpacks safely: no entry can land outside remoteDir). Symlinks are sent as links and hard-linked files as separate files; devices, pipes and sockets are skipped. It is sent once and never retried. It needs an agent that lists files.extract.
func (*Sandbox) UploadFile ¶
func (*Sandbox) UploadFileStream ¶ added in v0.6.5
UploadFileStream uploads r to targetPath without holding the file in memory; use it instead of UploadFile for large or unbounded inputs. The request is not retried (the reader is consumed as it is sent).
func (*Sandbox) UploadFileStreamWithOptions ¶ added in v0.6.12
func (s *Sandbox) UploadFileStreamWithOptions(ctx context.Context, targetPath string, r io.Reader, opts sdktypes.UploadFileOptions) error
UploadFileStreamWithOptions is UploadFileStream with write options. It is sent once and never retried.
func (*Sandbox) UploadFileWithOptions ¶ added in v0.6.12
func (s *Sandbox) UploadFileWithOptions(ctx context.Context, targetPath string, data []byte, opts sdktypes.UploadFileOptions) error
UploadFileWithOptions is UploadFile with write options: append, create-only, atomic replace and a file mode (see UploadFileOptions). A sandbox whose agent predates them fails with ErrUnsupportedFeature rather than ignoring them. Plain and atomic uploads retry like UploadFile; append and create-only retry only on 429 and 503.
func (*Sandbox) WatchFiles ¶ added in v0.6.12
func (s *Sandbox) WatchFiles(ctx context.Context, path string, options sdktypes.WatchOptions) (*WatchHandle, error)
WatchFiles streams changes under path in this sandbox. See Client.WatchFiles.
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) 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.
type SnapshotOption ¶ added in v0.6.12
type SnapshotOption func(*snapshotOptions)
SnapshotOption configures CreateSnapshot.
func WithAllowPause ¶ added in v0.6.12
func WithAllowPause(allow bool) SnapshotOption
WithAllowPause says whether the snapshot may pause a running sandbox. Without it the answer is yes: a running sandbox is paused while it is copied (its disk writes wait; Docker pauses the container) and keeps running afterwards. WithAllowPause(false) has a sandbox that is not stopped refused with HTTP 409 instead, for a workload that must never stall. A stopped sandbox needs no pause.
type StreamError ¶ added in v0.6.6
type StreamError = apiclient.StreamError
StreamError is a failure the toolbox reported on an exec or session stream, such as a command that could not start, as opposed to the stream dropping. Use errors.As to tell the two apart.
type Tokens ¶ added in v0.6.8
type Tokens struct {
// contains filtered or unexported fields
}
Tokens is the API token surface of a Client; get one from Client.Tokens.
func (*Tokens) Create ¶ added in v0.6.8
func (t *Tokens) Create(ctx context.Context, opts sdktypes.CreateAPITokenOptions) (sdktypes.CreatedAPIToken, error)
Create mints a token. The result's Token field is the secret, returned this once and never again, so store it before discarding the result. A 409 (errors.Is(err, ErrConflict)) means the name is taken, possibly by an earlier attempt whose reply was lost; that secret cannot be recovered, so revoke the token and create it again.
type UnsupportedFeatureError ¶ added in v0.6.12
type UnsupportedFeatureError = apiclient.UnsupportedFeatureError
UnsupportedFeatureError is returned when the sandbox's agent (toolboxd) is older than an option the call needs; the SDK refuses rather than send an option the agent would silently ignore. Restart the sandbox, or re-create its Firecracker template, to get the current agent.
type WatchHandle ¶ added in v0.6.12
type WatchHandle struct {
// contains filtered or unexported fields
}
WatchHandle is a running file watch.
func (*WatchHandle) Done ¶ added in v0.6.12
func (h *WatchHandle) Done() <-chan struct{}
Done is closed when the watch has ended.
func (*WatchHandle) Stop ¶ added in v0.6.12
func (h *WatchHandle) Stop() error
Stop ends the watch; Wait then returns nil.
func (*WatchHandle) Wait ¶ added in v0.6.12
func (h *WatchHandle) Wait() error
Wait blocks until the watch ends: nil after Stop, an error naming the reason when the agent ended it (the folder was removed or moved), or the error that dropped the connection.