sandbox

type Command struct {
	// Arguments passed to the program.
	Args []string `json:"args,omitempty"`
	// The program that was executed.
	Cmd string `json:"cmd,omitempty"`
	// Stable identifier for this command.
	CommandId string `json:"command_id,omitempty"`
	// Process exit code. Only present when finished is true and the process
	// exited normally (not killed by signal or failed to start).
	ExitCode int `json:"exit_code,omitempty"`
	// Whether the command has finished executing.
	Finished bool `json:"finished,omitempty"`
	// PID of the spawned process. Absent if the process failed to start.
	Pid int64 `json:"pid,omitempty"`

	ForceSendFields []string `json:"-" url:"-"`
}

type ComputeSpec struct {
	// Idle duration after which the sandbox is automatically terminated.
	InactivityTimeout *duration.Duration `json:"inactivity_timeout,omitempty"`

	ForceSendFields []string `json:"-" url:"-"`
}

type CreateDirectoryRequest struct {
	Parent string `json:"-" url:"-"`
	// Defaults to true, which also succeeds when the directory already exists.
	Parents bool `json:"parents,omitempty"`
	// Absolute UTF-8 path of the directory.
	Path string `json:"path"`

	ForceSendFields []string `json:"-" url:"-"`
}

type CreateDirectoryResponse struct {
}

type CreateSandboxRequest struct {
	// The sandbox to create.
	Sandbox Sandbox `json:"sandbox"`
	// Client-supplied ID that becomes the final path segment of the resource
	// name.
	SandboxId string `json:"-" url:"sandbox_id"`
}

type DeletePathRequest struct {
	Parent string `json:"-" url:"-"`
	// Absolute UTF-8 path of the entry to delete.
	Path string `json:"path"`
	// Required for a non-empty directory.
	Recursive bool `json:"recursive,omitempty"`

	ForceSendFields []string `json:"-" url:"-"`
}

type DeletePathResponse struct {
}

type DeleteSandboxRequest struct {
	Name string `json:"-" url:"-"`
}

type DownloadFileRequest struct {
	// A single byte range, such as bytes=0-1023 or bytes=-1024. Equivalent to
	// the Range header.
	ByteRange string `json:"-" url:"byte_range,omitempty"`
	// Entity tags or *. A mismatch returns 412 Precondition Failed. Equivalent
	// to the If-Match header.
	IfMatch string `json:"-" url:"if_match,omitempty"`
	// An HTTP-date. Returns 304 if the file has not changed since this time.
	// Ignored when If-None-Match is present. Equivalent to the
	// If-Modified-Since header.
	IfModifiedSince string `json:"-" url:"if_modified_since,omitempty"`
	// Entity tags or *. A match returns 304 Not Modified. Equivalent to the
	// If-None-Match header.
	IfNoneMatch string `json:"-" url:"if_none_match,omitempty"`
	// A strong entity tag. A mismatch, weak entity tag, or HTTP-date causes a
	// full download. Equivalent to the If-Range header.
	IfRange string `json:"-" url:"if_range,omitempty"`
	// An HTTP-date. Returns 412 if the file has changed since this time.
	// Ignored when If-Match is present. Equivalent to the If-Unmodified-Since
	// header.
	IfUnmodifiedSince string `json:"-" url:"if_unmodified_since,omitempty"`
	// The sandbox resource name, in the form sandboxes/{sandbox_id}.
	Parent string `json:"-" url:"-"`
	// The absolute UTF-8 path of the file inside the sandbox.
	Path string `json:"-" url:"path"`

	ForceSendFields []string `json:"-" url:"-"`
}

type DownloadFileResponse struct {
	// The supported range unit: bytes.
	AcceptRanges string `json:"-" url:"-" header:"Accept-Ranges,omitempty"`
	// The length of the response body in bytes.
	ContentLength int64 `json:"-" url:"-" header:"Content-Length,omitempty"`
	// The returned byte range and full file length, for a partial response.
	ContentRange string `json:"-" url:"-" header:"Content-Range,omitempty"`
	// The media type of the response body: application/octet-stream.
	ContentType string `json:"-" url:"-" header:"Content-Type,omitempty"`

	Contents io.ReadCloser `json:"-"`
	// The entity tag used for conditional requests.
	Etag string `json:"-" url:"-" header:"etag,omitempty"`
	// The modification time as an HTTP-date, when representable.
	LastModified string `json:"-" url:"-" header:"Last-Modified,omitempty"`

	ForceSendFields []string `json:"-" url:"-"`
}

type EnvironmentSpec struct {
	// The Unity Catalog container image to use for the sandbox environment (for
	// example, `catalog.schema.folder.image:tag`). See [Artifact Registry].
	//
	// [Artifact Registry]: https://docs.databricks.com/en/artifact-registry/
	ImageUri string `json:"image_uri,omitempty"`

	ForceSendFields []string `json:"-" url:"-"`
}

type ExecuteCommandStatus string

type ExecuteCommandSyncRequest struct {
	// Arguments passed to `cmd`.
	Args []string `json:"args,omitempty"`
	// Executable or command to run (e.g. `/bin/echo`, `python3`).
	Cmd string `json:"cmd"`
	// Extra environment variables for the command's process, merged over the
	// sandbox's default environment.
	Envs map[string]string `json:"envs,omitempty"`
	// Maximum time to wait for the command to finish. When it elapses the
	// command is terminated and the response carries status `TIMED_OUT`. The
	// server applies a default when unset and clamps to an upper bound;
	// negative or otherwise invalid durations are rejected with
	// `INVALID_ARGUMENT`.
	ExecutionTimeout *duration.Duration `json:"execution_timeout,omitempty"`
	// Resource name of the sandbox to run the command in, in the form
	// `sandboxes/{sandbox_id}`. Bound from the URL path.
	Name string `json:"-" url:"-"`

	ForceSendFields []string `json:"-" url:"-"`
}

type ExecuteCommandSyncResponse struct {
	// Daemon-generated identifier for this command execution, for correlation
	// (for example in `ListCommands`).
	CommandId string `json:"command_id,omitempty"`
	// Process exit code. Unset when the process was terminated by a signal
	// (e.g. on `TIMED_OUT`) or never started (`FAILED`) rather than exiting
	// normally.
	ExitCode int `json:"exit_code,omitempty"`
	// Terminal status of the command execution. Always set on a successful
	// response; never `EXECUTE_COMMAND_STATUS_UNSPECIFIED`.
	Status ExecuteCommandStatus `json:"status,omitempty"`
	// Captured standard error, with the same UTF-8 semantics as `stdout`.
	Stderr string `json:"stderr,omitempty"`
	// Captured standard output as UTF-8 text. Invalid UTF-8 bytes are replaced
	// with the Unicode replacement character (U+FFFD).
	Stdout string `json:"stdout,omitempty"`
	// True when `stdout` / `stderr` were truncated because the captured output
	// exceeded the server's per-response size cap. The dropped output is not
	// included in this response and is not recoverable through this unary API.
	Truncated bool `json:"truncated,omitempty"`

	ForceSendFields []string `json:"-" url:"-"`
}

type GetMetadataRequest struct {
	Parent string `json:"-" url:"-"`
	// Absolute UTF-8 path of the entry to inspect.
	Path string `json:"-" url:"path"`
}

type GetMetadataResponse struct {
	File *SandboxFileInfo `json:"file,omitempty"`
}

type GetSandboxRequest struct {
	Name string `json:"-" url:"-"`
}

type ListCommandsRequest struct {
	// Maximum number of commands to return. The server may return fewer. If
	// unspecified, the server returns all commands.
	PageSize int `json:"-" url:"page_size,omitempty"`
	// Page token returned by a previous ListCommands call. Use this to retrieve
	// the next page of results.
	PageToken string `json:"-" url:"page_token,omitempty"`
	// The sandbox whose commands to list, in the form `sandboxes/{sandbox_id}`.
	Parent string `json:"-" url:"-"`

	ForceSendFields []string `json:"-" url:"-"`
}

type ListCommandsResponse struct {
	// Commands in this page of results.
	Commands []Command `json:"commands,omitempty"`
	// Token to retrieve the next page. Empty when there are no more results.
	NextPageToken string `json:"next_page_token,omitempty"`

	ForceSendFields []string `json:"-" url:"-"`
}

type ListDirectoryContentsRequest struct {
	// Zero uses the default of 1000; values above 1000 are clamped to 1000.
	PageSize int `json:"-" url:"page_size,omitempty"`
	// The token from a prior response. Keep parent and path unchanged between
	// pages.
	PageToken string `json:"-" url:"page_token,omitempty"`

	Parent string `json:"-" url:"-"`
	// Absolute UTF-8 path of the directory.
	Path string `json:"-" url:"path"`

	ForceSendFields []string `json:"-" url:"-"`
}

type ListDirectoryContentsResponse struct {
	Contents []SandboxFileInfo `json:"contents,omitempty"`

	NextPageToken string `json:"next_page_token,omitempty"`

	ForceSendFields []string `json:"-" url:"-"`
}

type ListSandboxesRequest struct {
	PageSize int `json:"-" url:"page_size,omitempty"`

	PageToken string `json:"-" url:"page_token,omitempty"`

	ForceSendFields []string `json:"-" url:"-"`
}

type ListSandboxesResponse struct {
	NextPageToken string `json:"next_page_token,omitempty"`

	Sandboxes []Sandbox `json:"sandboxes,omitempty"`

	ForceSendFields []string `json:"-" url:"-"`
}

type RenamePathRequest struct {
	// Exact absolute UTF-8 destination; it must not already exist.
	Destination string `json:"destination"`
	// Sandbox resource name, for example `sandboxes/my-sandbox`.
	Parent string `json:"-" url:"-"`
	// Absolute UTF-8 path to move.
	Source string `json:"source"`
}

type RenamePathResponse struct {
}

type Sandbox struct {
	// Output only. The creation time of the sandbox.
	CreateTime *time.Time `json:"create_time,omitempty"`
	// Human-readable display label for the sandbox. At most 256 characters.
	DisplayName string `json:"display_name,omitempty"`
	// Metadata associated with the sandbox.
	Metadata *SandboxMetadata `json:"metadata,omitempty"`
	// The sandbox resource name, in the form `sandboxes/{sandbox_id}`. Derived
	// from `sandbox_id`; any value supplied in a create or update request body
	// is ignored.
	Name string `json:"name,omitempty"`
	// The desired configuration of the sandbox, supplied by the caller at
	// creation time.
	Spec *SandboxSpec `json:"spec,omitempty"`
	// The observed runtime state of the sandbox, populated by the server.
	Status *SandboxStatus `json:"status,omitempty"`
	// Output only. The last update time of the sandbox metadata and spec.
	UpdateTime *time.Time `json:"update_time,omitempty"`

	ForceSendFields []string `json:"-" url:"-"`
}

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

type SandboxFileInfo struct {
	FileType SandboxFileType `json:"file_type,omitempty"`

	Group string `json:"group,omitempty"`

	Mode int `json:"mode,omitempty"`
	// Nanosecond precision is preserved on the wire.
	ModifyTime *time.Time `json:"modify_time,omitempty"`

	Name string `json:"name,omitempty"`

	Owner string `json:"owner,omitempty"`

	Path string `json:"path,omitempty"`

	Permissions string `json:"permissions,omitempty"`

	Size int64 `json:"size,omitempty"`

	SymlinkTarget string `json:"symlink_target,omitempty"`

	ForceSendFields []string `json:"-" url:"-"`
}

type SandboxFileType string

type SandboxInterface interface {

	// Creates a directory in a sandbox, including missing parents by default.
	CreateDirectory(ctx context.Context, request CreateDirectoryRequest) (*CreateDirectoryResponse, error)

	// Creates a new Sandbox.
	CreateSandbox(ctx context.Context, request CreateSandboxRequest) (*Sandbox, error)

	// Deletes a file, symlink, or empty directory, with an option for recursive
	// deletion. Succeeds if the path is already absent.
	DeletePath(ctx context.Context, request DeletePathRequest) (*DeletePathResponse, error)

	// Deletes a Sandbox.
	DeleteSandbox(ctx context.Context, request DeleteSandboxRequest) error

	// Downloads a regular file from a sandbox as an application/octet-stream body.
	// The sandbox starts automatically if it is stopped. Filesystem access uses the
	// sandbox user's permissions and follows symbolic links.
	//
	// A full download returns 200 OK. A satisfiable single byte range returns 206
	// Partial Content. Multiple byte ranges are unsupported and return 400. Invalid
	// ranges are ignored; an unsatisfiable range returns 416 with Content-Range
	// describing the file length. Range is ignored for empty files.
	//
	// Conditional requests can return 304 Not Modified or 412 Precondition Failed.
	// If-Range selects a partial response only when its strong entity tag matches;
	// otherwise, the entire file is returned. HTTP-date validators in If-Range
	// cause a full download. Reads are not snapshots: concurrent in-place writes
	// can affect the returned bytes. HEAD is unsupported.
	//
	// Range and conditional options may be supplied as query parameters or HTTP
	// headers. A parameter and one header may both be supplied when their values
	// match exactly. Conflicting values or repeated parameters return 400.
	DownloadFile(ctx context.Context, request DownloadFileRequest) (*DownloadFileResponse, error)

	// Runs a command in the sandbox and blocks until it exits, returning the
	// captured stdout, stderr and exit code in a single response.
	ExecuteCommandSync(ctx context.Context, request ExecuteCommandSyncRequest) (*ExecuteCommandSyncResponse, error)

	// Returns metadata for a path without following its final symlink.
	GetMetadata(ctx context.Context, request GetMetadataRequest) (*GetMetadataResponse, error)

	// Retrieves a Sandbox by name.
	GetSandbox(ctx context.Context, request GetSandboxRequest) (*Sandbox, error)

	// Lists the tracked command executions (running and completed) in a sandbox.
	ListCommands(ctx context.Context, request ListCommandsRequest) (*ListCommandsResponse, error)

	// Lists a directory's immediate children in UTF-8 name order. Later pages may
	// reflect concurrent changes.
	//
	// This method is generated by Databricks SDK Code Generator.
	ListDirectoryContents(ctx context.Context, request ListDirectoryContentsRequest) listing.Iterator[SandboxFileInfo]

	// Lists a directory's immediate children in UTF-8 name order. Later pages may
	// reflect concurrent changes.
	//
	// This method is generated by Databricks SDK Code Generator.
	ListDirectoryContentsAll(ctx context.Context, request ListDirectoryContentsRequest) ([]SandboxFileInfo, error)

	// Lists all Sandboxes.
	//
	// This method is generated by Databricks SDK Code Generator.
	ListSandboxes(ctx context.Context, request ListSandboxesRequest) listing.Iterator[Sandbox]

	// Lists all Sandboxes.
	//
	// This method is generated by Databricks SDK Code Generator.
	ListSandboxesAll(ctx context.Context, request ListSandboxesRequest) ([]Sandbox, error)

	// Renames a path within a sandbox. The destination must be absent and on the
	// same filesystem.
	RenamePath(ctx context.Context, request RenamePathRequest) (*RenamePathResponse, error)

	// Starts a previously stopped Sandbox under the same sandbox name. Returns
	// NOT_FOUND if there is no stopped sandbox to start for the given name.
	StartSandbox(ctx context.Context, request StartSandboxRequest) (*Sandbox, error)

	// Stops a running Sandbox, preserving it so it can later be restarted with a
	// Start request.
	StopSandbox(ctx context.Context, request StopSandboxRequest) (*Sandbox, error)

	// Updates mutable fields on an existing Sandbox. Allowlisted update_mask paths
	// today: display_name, spec.compute.inactivity_timeout. Returns
	// INVALID_PARAMETER_VALUE for empty masks or unknown paths; NOT_FOUND if the
	// sandbox does not exist.
	UpdateSandbox(ctx context.Context, request UpdateSandboxRequest) (*Sandbox, error)

	// Uploads an application/octet-stream body to a sandbox. The sandbox starts
	// automatically if it is stopped. Filesystem access uses the sandbox user's
	// permissions and follows symbolic links.
	//
	// Creates the file or replaces its entire contents, creating parent directories
	// if missing. The completed upload becomes visible atomically. A failure before
	// commit leaves an existing destination unchanged; a lost response after commit
	// does not undo the upload. Completion does not guarantee crash durability.
	//
	// Returns 201 Created for a new file or 204 No Content for a replacement.
	// Partial and conditional uploads are unsupported: Content-Range, If-Match,
	// If-None-Match, and If-Unmodified-Since return 400.
	UploadFile(ctx context.Context, request UploadFileRequest) error
}

type SandboxMetadata struct {
	// Key-value tags associated with the sandbox. Supports up to 54 tags. Keys
	// must be between 1 and 512 characters, and values must not exceed 256
	// characters.
	CustomTags map[string]string `json:"custom_tags,omitempty"`
}

type SandboxSpec struct {
	// Compute configuration (size, inactivity timeout) requested for the
	// sandbox.
	Compute *ComputeSpec `json:"compute,omitempty"`
	// The execution environment to use for the sandbox.
	Environment *EnvironmentSpec `json:"environment,omitempty"`
}

type SandboxState string

type SandboxStatus struct {
	// Lifecycle state of the sandbox.
	State SandboxState `json:"state,omitempty"`
}

type StartSandboxRequest struct {
	// Resource name of the sandbox to start, in the form
	// `sandboxes/{sandbox_id}`.
	Name string `json:"-" url:"-"`
}

type StopSandboxRequest struct {
	// Resource name of the sandbox to stop, in the form
	// `sandboxes/{sandbox_id}`.
	Name string `json:"-" url:"-"`
}

type UpdateSandboxRequest struct {
	// Resource name of the sandbox to update, in the form
	// `sandboxes/{sandbox_id}`.
	Name string `json:"-" url:"-"`
	// The Sandbox resource carrying new field values. Only fields named in
	// `update_mask` are read; unmasked fields are ignored.
	Sandbox Sandbox `json:"sandbox"`
	// Field paths to update. Must be a non-empty subset of: - display_name -
	// spec.compute.inactivity_timeout Any other path returns
	// INVALID_PARAMETER_VALUE.
	UpdateMask fieldmask.FieldMask `json:"-" url:"update_mask"`
}

type UploadFileRequest struct {
	// The complete file contents. An empty body creates an empty file.
	Contents io.ReadCloser `json:"-"`
	// The sandbox resource name, in the form sandboxes/{sandbox_id}.
	Parent string `json:"-" url:"-"`
	// The absolute UTF-8 destination path inside the sandbox.
	Path string `json:"-" url:"path"`
}