Documentation
¶
Overview ¶
Package docker runs approved Python Skill scripts in disposable containers. It uses the official Docker Go SDK, never the Docker CLI or a host shell.
Index ¶
- Variables
- type Config
- type ContainerSpec
- type Engine
- type Executor
- func (e *Executor) Close(ctx context.Context) error
- func (e *Executor) CreateWorkspace(ctx context.Context, owner string) (script.Workspace, error)
- func (e *Executor) DeleteWorkspace(ctx context.Context, w script.Workspace) error
- func (e *Executor) EnsureImage(ctx context.Context, image string) error
- func (e *Executor) Execute(ctx context.Context, req script.Request) (result script.Result, returnErr error)
- func (e *Executor) Fingerprint() string
- func (e *Executor) OpenFile(ctx context.Context, w script.Workspace, path string) (io.ReadCloser, error)
- func (e *Executor) ReleaseWorkspace(ctx context.Context, w script.Workspace) error
- func (e *Executor) ValidateWorkspace(ctx context.Context, w script.Workspace) error
- func (e *Executor) WorkspaceRoot() string
Constants ¶
This section is empty.
Variables ¶
var ErrImageNotFound = errors.New("docker: image not found")
ErrImageNotFound is returned only for a missing local image, not connection or permission failures. Engine test doubles must preserve this distinction.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
Enabled bool
Catalog *skill.Catalog
Registrations []script.Registration
Image string
AutoPull bool
MemoryMB int64
CPUs float64
PIDsLimit int64
MaxParallel int
Timeout time.Duration
ConnectTimeout time.Duration
CleanupTimeout time.Duration
NetworkEnabled bool
WorkspaceRoot string
LogMaxBytes int64
WorkspaceMaxBytes int64
OutputMaxBytes int64
MaxFiles int
// CleanupOnRelease deletes task data when the Agent completes. Default false
// retains outputs for trusted application retrieval and explicit deletion.
CleanupOnRelease bool
// Engine is optional dependency injection; nil selects the official SDK.
Engine Engine
}
Config is trusted application configuration, never model input. Enabling it checks Docker connectivity but does not pull images until first use.
type ContainerSpec ¶
type ContainerSpec struct {
Name string
Config *container.Config
Host *container.HostConfig
}
ContainerSpec is the complete application-owned sandbox configuration.
type Engine ¶
type Engine interface {
Ping(context.Context) error
ImageInspect(context.Context, string) (string, error)
ImagePull(context.Context, string) error
Create(context.Context, ContainerSpec) (string, error)
Start(context.Context, string) error
Wait(context.Context, string) (int, bool, error)
Logs(context.Context, string) (io.ReadCloser, error)
Remove(context.Context, string) error
Close() error
}
Engine is the narrow Docker lifecycle boundary. Logs must be multiplexed stdout/stderr and closing their reader must unblock reads. Wait honors context.
type Executor ¶
type Executor struct {
// contains filtered or unexported fields
}
Executor owns a client and disposable containers, not the Docker daemon or shared images. Close cancels active executions and waits for cleanup.
func New ¶
New validates trust manifests and checks Docker only when explicitly enabled. WorkspaceRoot must be private to the service; no host environment enters tasks.
func (*Executor) Close ¶
Close is idempotent and cancellation-aware. Only containers created by this executor are removed. Images and retained task outputs are never deleted.
func (*Executor) CreateWorkspace ¶
CreateWorkspace generates an unguessable task identifier. The owner is a trusted run identity, not a user-controlled directory or model argument.
func (*Executor) DeleteWorkspace ¶
DeleteWorkspace explicitly removes this task's data. Call only after consumers have retrieved output files; no public base directory or image is deleted.
func (*Executor) EnsureImage ¶
EnsureImage inspects first. Only a specific not-found result permits pulling; concurrent callers share one inspect/pull operation for the same image.
func (*Executor) Execute ¶
func (e *Executor) Execute(ctx context.Context, req script.Request) (result script.Result, returnErr error)
Execute runs a registered entrypoint in a fresh temporary container. It returns bounded partial results on errors and never falls back to host execution.
func (*Executor) Fingerprint ¶
Fingerprint binds suspended calls to exact script approvals and runtime limits.
func (*Executor) OpenFile ¶
func (e *Executor) OpenFile(ctx context.Context, w script.Workspace, path string) (io.ReadCloser, error)
OpenFile is for trusted application retrieval using an owner-bound reference. Only regular, single-link output files can be opened; callers close the reader.
func (*Executor) ReleaseWorkspace ¶
ReleaseWorkspace applies the configured terminal-task retention policy.
func (*Executor) ValidateWorkspace ¶
ValidateWorkspace permits checkpoint restoration without granting access to another task. Its protected owner marker survives executor process restarts.
func (*Executor) WorkspaceRoot ¶
WorkspaceRoot exposes the managed root only to trusted application code.