Help us shape the future of Go! Take the 2026 Go Developer Survey

container

package
v0.8.0 Latest Latest
Warning

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

Go to latest
Published: Oct 26, 2026 License: BSD-3-Clause Imports: 19 Imported by: 0

Documentation

Overview

Package container is the container lifecycle: created, running, exited; its root filesystem, its logs, its exit code. It runs modules through a runtime.Executor and knows nothing of images beyond the frozen lower filesystem and the run configuration it is handed.

Index

Constants

View Source
const (
	Stdout byte = 1
	Stderr byte = 2
)

Stream numbers, as in the Docker multiplexed stream format.

Variables

View Source
var (
	ErrNotFound       = errors.New("no such container")
	ErrNameConflict   = errors.New("container name already in use")
	ErrRunning        = errors.New("container is running")
	ErrNotRunning     = errors.New("container is not running")
	ErrAlreadyStarted = errors.New("container already started")
	ErrInvalid        = errors.New("invalid container configuration")
	ErrTooMany        = errors.New("too many containers")
	ErrAmbiguous      = errors.New("multiple containers match")
)

Errors the API layer maps to HTTP statuses.

Functions

func DecodeRecord added in v0.4.0

func DecodeRecord(v []byte) (*record, error)

DecodeRecord reads a stored container record; it is exported for the fuzzer and for tools that inspect a data root.

Types

type Config

type Config struct {
	Image      string            `json:"Image"`
	ImageID    string            `json:"-"`
	Entrypoint []string          `json:"Entrypoint"`
	Cmd        []string          `json:"Cmd"`
	Env        []string          `json:"Env"`
	WorkingDir string            `json:"WorkingDir"`
	Labels     map[string]string `json:"Labels"`
	// MemoryLimitBytes bounds linear memory (0 = manager default).
	MemoryLimitBytes int64 `json:"-"`
	// AutoRemove removes the container when it exits (run --rm).
	AutoRemove bool `json:"-"`
	// Mounts are the volumes it mounts (run -v NAME:/path[:ro]).
	Mounts []Mount `json:"-"`
}

Config is how a container runs, resolved from the image config and the run overrides.

type Container

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

Container is one container. Read it through Snapshot.

func (*Container) Attach added in v0.5.0

func (c *Container) Attach(ctx context.Context, logs bool, fn func(Record) error) error

Attach streams to fn what the container writes from now on (with logs, what it wrote before too) until its next exit — of the run in progress, or of the next start when it is not running — or its removal.

func (*Container) FS

func (c *Container) FS() *rootfs.FS

FS returns the container's root filesystem.

func (*Container) ID

func (c *Container) ID() string

ID returns the container's ID.

func (*Container) Logs

func (c *Container) Logs(ctx context.Context, follow bool, fn func(Record) error) error

Logs streams the container's output to fn: everything kept so far and, with follow, everything written until the container stops running.

func (*Container) Snapshot

func (c *Container) Snapshot() Snapshot

Snapshot returns the container's current state.

func (*Container) Stats added in v0.7.0

func (c *Container) Stats() Stats

Stats measures the container now.

func (*Container) Wait

func (c *Container) Wait(ctx context.Context, cond WaitCondition) (int, error)

Wait blocks until the condition holds and returns the exit code.

type CreateOptions

type CreateOptions struct {
	Name   string
	Config Config
	// Lower is the image's frozen root filesystem.
	Lower *rootfs.FS
}

CreateOptions describes a new container.

type Logs

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

Logs is a container's bounded, append-only output. When it exceeds its byte bound the oldest records are dropped, so a chatty container cannot exhaust the daemon's memory.

type Manager

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

Manager owns every container of a daemon.

func NewManager

func NewManager(opt Options) *Manager

NewManager returns a manager running modules on opt.Executor.

func (*Manager) Create

func (m *Manager) Create(o CreateOptions) (*Container, error)

Create makes a container in the created state.

func (*Manager) DefaultMemoryLimit added in v0.7.0

func (m *Manager) DefaultMemoryLimit() int64

DefaultMemoryLimit is the memory limit of containers that set none.

func (*Manager) Flush added in v0.4.0

func (m *Manager) Flush(ctx context.Context) error

Flush waits until every change made so far is stored.

func (*Manager) Get

func (m *Manager) Get(ref string) (*Container, error)

Get finds a container by full ID, name, or unique ID prefix.

func (*Manager) Kill

func (m *Manager) Kill(ref string) error

Kill ends a running container.

func (*Manager) List

func (m *Manager) List(all bool) []Snapshot

List returns containers, newest first; all includes stopped ones.

func (*Manager) Logs

func (m *Manager) Logs(ctx context.Context, ref string, follow bool, fn func(Record) error) error

Logs streams a container's output; see Container.Logs.

func (*Manager) PersistError added in v0.4.0

func (m *Manager) PersistError() error

PersistError is the last checkpoint's failure, nil when the store holds every container's latest state.

func (*Manager) Prune added in v0.4.0

func (m *Manager) Prune() ([]string, int64)

Prune removes every container that is not running and returns their IDs and the bytes their writable layers held.

func (*Manager) Remove

func (m *Manager) Remove(ctx context.Context, ref string, force bool) error

Remove deletes a container; a running one only with force, which kills it.

func (*Manager) Restart added in v0.5.0

func (m *Manager) Restart(ctx context.Context, ref string) error

Restart stops the container if it runs, then starts it.

func (*Manager) Restore added in v0.4.0

func (m *Manager) Restore(lower func(imageID string) (*rootfs.FS, error), lim rootfs.Limits) (RestoreReport, error)

Restore loads every stored container. lower returns the frozen root filesystem of an image by ID; lim bounds reading a stored writable layer. A record that fails its seal or its checks is deleted and reported; a blob that does, is dropped (the container keeps its configuration and loses its logs or its writes), and so is a container whose image is gone.

func (*Manager) Shutdown

func (m *Manager) Shutdown(ctx context.Context)

Shutdown kills every running container and waits for them.

func (*Manager) Start

func (m *Manager) Start(ctx context.Context, ref string) error

Start runs a created or exited container.

func (*Manager) Stop added in v0.5.0

func (m *Manager) Stop(ctx context.Context, ref string) error

Stop ends a running container and waits until it has exited. A wasm guest has no signal to catch, so there is no grace period: stopping is killing (docker stop's SIGKILL after the timeout, at once).

func (*Manager) UsesImage

func (m *Manager) UsesImage(imageID string) []string

UsesImage reports whether any container was created from imageID.

func (*Manager) UsesVolume added in v0.8.0

func (m *Manager) UsesVolume(name string) []string

UsesVolume lists the containers, in any state, that mount a volume.

func (*Manager) Wait

func (m *Manager) Wait(ctx context.Context, ref string, cond WaitCondition) (int, error)

Wait blocks until the condition holds and returns the exit code.

type Mount added in v0.8.0

type Mount struct {
	Volume   string `json:"volume"`
	Target   string `json:"target"`
	ReadOnly bool   `json:"readOnly,omitempty"`
}

Mount is a volume mounted at Target.

type Options

type Options struct {
	Executor runtime.Executor
	// MemoryLimitBytes is the default linear-memory bound per container.
	MemoryLimitBytes int64
	// Timeout is the wall-clock bound of one run (0 = none).
	Timeout time.Duration
	// Quota bounds what one container may write to its filesystem.
	Quota rootfs.Quota
	// MaxLogBytes bounds one container's kept output (default 8 MiB).
	MaxLogBytes int
	// MaxContainers bounds how many containers exist (default 256).
	MaxContainers int
	// Store, when set, keeps containers across restarts: their state,
	// logs and writable layers (see Restore).
	Store state.Store
	// CheckpointEvery is how often a running container's changes are
	// stored (default 2s; negative: only at state changes).
	CheckpointEvery time.Duration
	// Events, when set, receives create, start, die, kill, stop, restart,
	// destroy and prune, with Docker's attributes (image, name, labels,
	// exitCode).
	Events *events.Bus
	// Volume finds a volume's tree by name, for Config.Mounts.
	Volume func(name string) (*rootfs.FS, error)
}

Options configures a Manager.

type Record

type Record struct {
	Stream byte
	Data   []byte
	Time   time.Time
}

Record is one write of a container to stdout or stderr.

type RestoreReport added in v0.4.0

type RestoreReport struct {
	// Restored containers, of which Stopped were running when the engine
	// stopped and are now exited with status 137.
	Restored, Stopped int
	// Removed are --rm containers that had run, removed as they would
	// have been.
	Removed []string
	// Repaired describes what was found corrupted and dropped.
	Repaired []string
}

RestoreReport says what Restore did.

type Snapshot

type Snapshot struct {
	ID         string
	Name       string
	Created    time.Time
	Config     Config
	State      State
	ExitCode   int
	Error      string
	TimedOut   bool
	StartedAt  time.Time
	FinishedAt time.Time
	// Path is the resolved module path (empty until the first start).
	Path string
	// SizeRw is the bytes the container wrote to its filesystem.
	SizeRw int64
}

Snapshot is a consistent copy of a container's state.

func (Snapshot) Command

func (s Snapshot) Command() []string

Command is argv as configured.

type State

type State string

State is a container's lifecycle state.

const (
	Created State = "created"
	Running State = "running"
	Exited  State = "exited"
)

type Stats added in v0.7.0

type Stats struct {
	Read    time.Time
	Running bool
	// MemoryBytes is the guest's linear memory (0 when not running);
	// MemoryLimitBytes the most it may grow to.
	MemoryBytes, MemoryLimitBytes int64
	// WrittenBytes is everything written to its filesystem, ever;
	// SizeRw what its writable layer holds now.
	WrittenBytes, SizeRw int64
	// LogBytes is the output kept.
	LogBytes int64
}

Stats is what a container uses now. CPU time is not in it: a wasm guest gives the engine no CPU accounting (its wall-clock time includes the time it waits on the host), and an estimate would be a guess.

type WaitCondition

type WaitCondition string

WaitCondition is a /containers/{id}/wait condition.

const (
	WaitNotRunning WaitCondition = "not-running"
	WaitNextExit   WaitCondition = "next-exit"
	WaitRemoved    WaitCondition = "removed"
)

Jump to

Keyboard shortcuts

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