docker

package
v0.5.1 Latest Latest
Warning

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

Go to latest
Published: Nov 7, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var ErrNoTTY = errors.New("interactive TTY required on stdin and stdout")

Functions

func WithPreflightTimeout added in v0.0.4

func WithPreflightTimeout(parent context.Context) (context.Context, context.CancelFunc)

WithPreflightTimeout prevents an unreachable daemon from hanging a CLI check.

Types

type Docker added in v0.1.0

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

Docker keeps one client so preflight and Run use the same daemon configuration.

func New added in v0.1.0

func New(opts ...Option) (*Docker, error)

New applies options before creating the client so test injection cannot leave an unused transport behind.

func (*Docker) CheckDaemon added in v0.1.0

func (d *Docker) CheckDaemon(ctx context.Context) error

func (*Docker) Close added in v0.1.0

func (d *Docker) Close() error

func (*Docker) ContainerRunning added in v0.3.3

func (d *Docker) ContainerRunning(ctx context.Context, name string) (exists, running bool, err error)

ContainerRunning rejects paused containers, which would stall shared-network traffic, and restarting containers, whose namespace Docker refuses to join. Only a classified not-found returns no error.

func (*Docker) ImageExists added in v0.1.0

func (d *Docker) ImageExists(ctx context.Context, image string) (bool, error)

ImageExists distinguishes a missing image from a failed daemon request.

func (*Docker) NetworkExists added in v0.3.3

func (d *Docker) NetworkExists(ctx context.Context, name string) (bool, error)

NetworkExists preserves daemon errors instead of misreporting them as absence.

func (*Docker) Run added in v0.1.0

func (d *Docker) Run(ctx context.Context, s Spec) error

Run starts the wait before the container so fast auto-removed exits retain their status. It drains output and joins closeable stdin readers before return to avoid lost output and goroutine leaks. If stdin cannot be made closeable, its blocked copy goroutine may outlive Run.

type ErrDaemonUnreachable

type ErrDaemonUnreachable struct {
	Cause error
}

func (*ErrDaemonUnreachable) Error

func (e *ErrDaemonUnreachable) Error() string

func (*ErrDaemonUnreachable) Unwrap

func (e *ErrDaemonUnreachable) Unwrap() error

type ExitError

type ExitError struct {
	Code int
}

ExitError is returned by Run on non-zero container exit. Code is the daemon's status code (e.g. 137 for SIGKILL).

func (*ExitError) Error

func (e *ExitError) Error() string

type Mount

type Mount struct {
	Type            string
	Host, Container string
	ReadOnly        bool
}

Mount keeps the same representation for CLI and SDK projections.

type Option added in v0.1.0

type Option func(*Docker)

func WithClient added in v0.1.0

func WithClient(c apiClient) Option

WithClient lets same-package tests avoid a real daemon client.

func WithRawMode added in v0.1.0

func WithRawMode(fn func(int) (*term.State, error)) Option

func WithStreams added in v0.1.0

func WithStreams(in io.Reader, out io.Writer) Option

WithStreams overrides the stdin reader and stdout writer used by Run for container I/O. Fd-based terminal operations (raw mode, GetSize, resize) always use the real os.Stdin; only the data copies are redirected.

func WithTTYCheck added in v0.1.0

func WithTTYCheck(fn func() bool) Option

type Options

type Options struct {
	// The caller guarantees a main project at index 0, unique names and disjoint roots.
	Projects []Project
	// CacheMounts contains fully resolved opt-in binds, in configuration order.
	CacheMounts []Mount
	Image       string
	Command     string // shell to exec inside the container

	// TmpDirSize is passed verbatim to --tmpfs /tmp:size=<TmpDirSize>; config.Load
	// owns the default, BuildSpec does not re-default.
	TmpDirSize string

	// Env holds "KEY=VALUE" pairs to inject; copied verbatim (caller sorts).
	Env []string

	// NetworkMode is passed verbatim as --network / HostConfig.NetworkMode
	// (bridge, host, none, container:<x>, or a network name). Empty means the
	// Docker default. Mutually exclusive with Networks (projectconfig enforces).
	NetworkMode string

	// Networks lists networks to attach at create time, in order; the first is
	// the primary (HostConfig.NetworkMode). Copied verbatim.
	Networks []string
}

Options must be resolved before BuildSpec; it performs no I/O.

type Project added in v0.4.0

type Project struct {
	Host     string
	Name     string
	Label    string
	ReadOnly bool // ignored for Projects[0]

	MaskedFiles []string
	MaskedDirs  []string

	// Set only for an existing file; a missing bind source fails container creation.
	ProtectConfig bool

	// Only directory-backed .git can have hooks masked within this mount.
	MaskGitHooks bool
}

Project.Host must be absolute and symlink-resolved before BuildSpec.

type Section added in v0.4.0

type Section struct {
	Label string
	Start int // index into Spec.Mounts
}

type Spec

type Spec struct {
	Image   string
	Command string
	Workdir string
	Env     []string // "KEY=VALUE" pairs; nil/empty → no -e flags
	Mounts  []Mount
	Tmpfs   []string
	CapDrop []string
	SecOpt  []string

	NetworkMode string   // "" → no --network flag, Docker default bridge
	Networks    []string // one --network per entry; first is primary

	// Presentation only; argv and SDK projections ignore these labels.
	Sections []Section
}

Spec is shared by dry-run output and the SDK call to prevent drift.

func BuildSpec

func BuildSpec(o Options) Spec

BuildSpec preserves mount order because later masks must shadow earlier binds.

func (Spec) Args

func (s Spec) Args() []string

Args uses CSV quoting so Docker can parse mount paths containing ',' or '"'.

func (Spec) ContainerConfig

func (s Spec) ContainerConfig() *container.Config

func (Spec) HostConfig

func (s Spec) HostConfig() *container.HostConfig

func (Spec) NetworkingConfig added in v0.3.3

func (s Spec) NetworkingConfig() *network.NetworkingConfig

NetworkingConfig returns the SDK endpoint config attaching every entry of Networks at create time, or nil when Networks is empty (NetworkMode alone is carried by HostConfig). Multiple endpoints need daemon API >= 1.44.

func (Spec) ShellCommand

func (s Spec) ShellCommand() string

ShellCommand labels join sections for inspection. With joins, those labels break shell continuation, so the result cannot be pasted as one command.

Jump to

Keyboard shortcuts

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