docker

package
v1.1.1 Latest Latest
Warning

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

Go to latest
Published: Nov 1, 2026 License: MIT Imports: 24 Imported by: 0

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

Constants

This section is empty.

Variables

View Source
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

func New(ctx context.Context, cfg Config) (*Executor, error)

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

func (e *Executor) Close(ctx context.Context) error

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

func (e *Executor) CreateWorkspace(ctx context.Context, owner string) (script.Workspace, error)

CreateWorkspace generates an unguessable task identifier. The owner is a trusted run identity, not a user-controlled directory or model argument.

func (*Executor) DeleteWorkspace

func (e *Executor) DeleteWorkspace(ctx context.Context, w script.Workspace) error

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

func (e *Executor) EnsureImage(ctx context.Context, image string) error

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

func (e *Executor) Fingerprint() string

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

func (e *Executor) ReleaseWorkspace(ctx context.Context, w script.Workspace) error

ReleaseWorkspace applies the configured terminal-task retention policy.

func (*Executor) ValidateWorkspace

func (e *Executor) ValidateWorkspace(ctx context.Context, w script.Workspace) error

ValidateWorkspace permits checkpoint restoration without granting access to another task. Its protected owner marker survives executor process restarts.

func (*Executor) WorkspaceRoot

func (e *Executor) WorkspaceRoot() string

WorkspaceRoot exposes the managed root only to trusted application code.

Jump to

Keyboard shortcuts

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