container

package
v0.4.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: 17 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:"-"`
}

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) 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) 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) 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) 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) UsesImage

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

UsesImage reports whether any container was created from imageID.

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 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
}

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