engine

package
v3.3.1 Latest Latest
Warning

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

Go to latest
Published: Nov 14, 2026 License: Apache-2.0 Imports: 21 Imported by: 0

Documentation

Overview

Package engine finds and operates the container engine (Docker Desktop, Docker Engine, or Podman) through the Engine API. It does not use the docker or podman command for the lifecycle of the container.

Index

Constants

View Source
const (
	LabelManagedBy = "dev.mai.managed-by"
	ManagedByValue = "mai-cli"
	LabelInstance  = "dev.mai.instance"
)

Labels of each object that the CLI makes.

View Source
const ContainerPort = 8080

ContainerPort is the HTTP port of the server in the container.

View Source
const StartWait = 120 * time.Second

StartWait is the maximum time to wait for the engine or for the health of the container.

View Source
const StopTimeout = 60

StopTimeout is the time in seconds that a stop waits before a kill.

Variables

View Source
var Capabilities = []string{"CHOWN", "DAC_OVERRIDE", "FOWNER", "SETGID", "SETUID", "KILL"}

Capabilities that the container adds after it drops all.

View Source
var ErrForeign = errors.New("engine: a container that the CLI did not make holds the name")

ErrForeign means that a container with the instance name exists without the label of the CLI.

View Source
var ErrNoResponse = errors.New("engine: the container engine gives no response")

ErrNoResponse means that the engine did not answer in the wait time.

View Source
var ErrNotInstalled = errors.New("engine: no container engine is installed")

ErrNotInstalled means that no engine is installed on this computer.

View Source
var ErrPullRefused = errors.New("engine: the image is not local and the pull is off")

ErrPullRefused means that the image is not local and the caller refused a pull.

View Source
var TmpfsPaths = []string{"/run", "/tmp", "/etc/postfix", "/etc/dovecot", "/var/lib/postgresql"}

TmpfsPaths are the tmpfs folders of the container. /var/lib/postgresql stops the anonymous volume that the base image declares.

Functions

func DataDir added in v3.2.0

func DataDir(c container.InspectResponse) string

DataDir gives the host folder of the bind mount at /data of the container. It gives "" when /data is a volume, or when the container has no mount at /data.

func DataVolume

func DataVolume(instance string) string

DataVolume is the name of the data volume of an instance.

func FreeBytes

func FreeBytes(path string) (uint64, error)

FreeBytes returns the free disk space for the user at path.

func HostPort added in v3.2.0

func HostPort(c container.InspectResponse) int

HostPort gives the host port of the HTTP port of the container, or 0 when the container has no binding of that port.

func InstallHint

func InstallHint(goos string) string

InstallHint is the one install step for the OS when no engine is installed.

func Labels

func Labels(instance string) map[string]string

Labels returns the labels of each object of the instance.

func Overlap added in v3.2.0

func Overlap(a, b string) bool

Overlap tells if the folders a and b are the same folder, or if one of them holds the other.

func Owned

Owned returns ErrForeign when the container has no label of the CLI.

func SpoolVolume

func SpoolVolume(instance string) string

SpoolVolume is the name of the spool volume of an instance.

func Within added in v3.2.0

func Within(root, path string) bool

Within tells if the folder path is the folder root, or is in it.

Types

type Candidate

type Candidate struct {
	Host   string // address for the Engine API, for example unix:///var/run/docker.sock
	Source string // where the address came from
	Kind   Kind
}

Candidate is one engine address to try.

func Discover

func Discover(e Env) []Candidate

Discover returns the engine addresses to try, in sequence: DOCKER_HOST, the current Docker context, the default sockets of Docker Desktop and Docker Engine, then the default sockets of Podman. A socket file that does not exist is not in the list, but the default address of the OS is always in the list, so that the caller can start the engine.

type Engine

type Engine struct {
	API       *client.Client
	Candidate Candidate
}

Engine is a connection to one container engine.

func Connect

func Connect(ctx context.Context, env Env, log io.Writer) (*Engine, error)

Connect finds the engine. If no engine answers, it starts the first installed engine and waits up to StartWait. If no engine is installed, it returns ErrNotInstalled.

func ConnectSystem

func ConnectSystem(ctx context.Context, log io.Writer) (*Engine, error)

ConnectSystem is Connect with the environment of this process.

func Find

func Find(ctx context.Context, cands []Candidate) (*Engine, error)

Find returns the first candidate that answers, or ErrNoResponse.

func (*Engine) BindMounts added in v3.2.0

func (e *Engine) BindMounts(ctx context.Context) ([]Mount, error)

BindMounts gives each bind mount of each container that has the label of an instance. The list of the containers can give a different path for the host folder, for example /host_mnt/private/tmp/x on Docker Desktop. Thus the inspect of each container gives the path.

func (*Engine) Close

func (e *Engine) Close() error

Close ends the connection.

func (*Engine) Container

func (e *Engine) Container(ctx context.Context, name string) (container.InspectResponse, bool, error)

Find the container with the exact name. ok is false when no such container exists.

func (*Engine) Create

func (e *Engine) Create(ctx context.Context, s Spec) (string, error)

Create makes the container of the spec and returns its ID.

func (*Engine) Describe

func (e *Engine) Describe(ctx context.Context) string

Describe returns one line about the engine: its platform and version.

func (*Engine) EnsureImage

func (e *Engine) EnsureImage(ctx context.Context, ref string, noPull bool, log io.Writer) (id string, pulled bool, err error)

EnsureImage makes sure that the image is local. It pulls the image with no registry credential when it is not local. pulled is true when this call pulled the image.

func (*Engine) EnsureVolumes

func (e *Engine) EnsureVolumes(ctx context.Context, s Spec) (made []string, err error)

EnsureVolumes makes each volume of the spec with the labels of the CLI. made is the list of volumes that this call made.

func (*Engine) Exec

func (e *Engine) Exec(ctx context.Context, id string, cmd []string, stdin io.Reader, stdout, stderr io.Writer) (int, error)

Exec runs cmd in the container and returns its exit code. stdin can be nil.

func (*Engine) Healthy

func (e *Engine) Healthy(ctx context.Context, id string, out io.Writer) error

Healthy runs "mai health" in the container once and returns nil on exit 0.

func (*Engine) LocalImage

func (e *Engine) LocalImage(ctx context.Context, ref string) (string, error)

LocalImage returns the ID of a local image with the reference, or "" when it is not local.

func (*Engine) Logs

func (e *Engine) Logs(ctx context.Context, id string, follow bool, stdout, stderr io.Writer) error

Logs writes the log of the container to stdout and stderr.

func (*Engine) Pause

func (e *Engine) Pause(ctx context.Context, id string) error

Pause freezes the container.

func (*Engine) Pull

func (e *Engine) Pull(ctx context.Context, ref string, log io.Writer) error

Pull gets the image through the Engine API with no registry credential, and writes the progress to log.

func (*Engine) Remove

func (e *Engine) Remove(ctx context.Context, id string) error

Remove removes the container with its anonymous volumes.

func (*Engine) RemoveVolume

func (e *Engine) RemoveVolume(ctx context.Context, name string) error

RemoveVolume removes one volume.

func (*Engine) Resume

func (e *Engine) Resume(ctx context.Context, id string) error

Resume unfreezes the container.

func (*Engine) Start

func (e *Engine) Start(ctx context.Context, id string) error

Start starts the container.

func (*Engine) Stop

func (e *Engine) Stop(ctx context.Context, id string) error

Stop stops the container with the stop timeout of the contract.

func (*Engine) WaitHealthy

func (e *Engine) WaitHealthy(ctx context.Context, id string, wait time.Duration) error

WaitHealthy runs "mai health" in the container until it gives exit 0, up to wait.

type Env

type Env struct {
	GOOS     string
	Home     string
	Getenv   func(string) string
	ReadFile func(string) ([]byte, error)
	Exists   func(string) bool
}

Env is the environment that discovery reads. Tests give a fake one.

func SystemEnv

func SystemEnv(goos string) Env

SystemEnv returns the Env of this process.

type Kind

type Kind string

Kind tells which engine a candidate socket belongs to.

const (
	KindDocker Kind = "docker"
	KindPodman Kind = "podman"
)

Kinds of engines.

type Launcher

type Launcher struct {
	Name string
	Cmd  []string
}

Launcher starts an engine that is installed but stopped.

func Launchers

func Launchers(goos string) []Launcher

Launchers returns the start commands of the installed engines, in sequence of preference. An empty list means that no engine is installed.

type Mount added in v3.2.0

type Mount struct {
	Instance  string // The instance of the container.
	Container string // The name of the container.
	Source    string // The host folder.
	Target    string // The folder in the container.
}

Mount is a bind mount of a container that has the label of an instance.

func HostMounts added in v3.2.0

func HostMounts(c container.InspectResponse) []Mount

HostMounts gives each bind mount of the container, when the container has the label of an instance.

type Spec

type Spec struct {
	Instance string
	Port     int
	Image    string
	DataDir  string // a host folder for /data; empty means the volume <instance>3-data
}

Spec is the input of the container definition.

func (Spec) CreateOptions

func (s Spec) CreateOptions() client.ContainerCreateOptions

CreateOptions returns the container definition of the contract.

func (Spec) Volumes

func (s Spec) Volumes() []string

Volumes returns the names of the volumes that the instance uses. With a host data folder, only the spool is a volume.

Jump to

Keyboard shortcuts

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