runtime

Documentation

Overview

Package runtime abstracts the container CLI (podman or docker) behind a small Runner interface. Every higher-level operation - build, run, exec, cp, compose - is argv construction on top of Runner, which makes the whole tool testable with a FakeRunner that records argv and replays canned inspect JSON, with no container runtime present.

Index

• Variables
• func IsRootlessPodman(ctx context.Context, r Runner) bool
• func Version(ctx context.Context, r Runner) (string, error)
• type CLIRunner
  • func Detect(prefer string) (*CLIRunner, error)
  • func NewCLIRunner(bin string) *CLIRunner
  • func (r *CLIRunner) BinPath() string
  • func (r *CLIRunner) Inspect(ctx context.Context, ref string, v any) error
  • func (r *CLIRunner) Name() string
  • func (r *CLIRunner) Output(ctx context.Context, args ...string) ([]byte, error)
  • func (r *CLIRunner) Run(ctx context.Context, args []string, io IO) error
• type Compose
  • func DetectCompose(ctx context.Context, runtimeName, override string) (*Compose, error)
• type FakeRunner
  • func NewFake() *FakeRunner
  • func (f *FakeRunner) CallStrings() []string
  • func (f *FakeRunner) FindCall(verb string) []string
  • func (f *FakeRunner) Inspect(_ context.Context, ref string, v any) error
  • func (f *FakeRunner) LastCall() []string
  • func (f *FakeRunner) Name() string
  • func (f *FakeRunner) Output(_ context.Context, args ...string) ([]byte, error)
  • func (f *FakeRunner) Run(_ context.Context, args []string, _ IO) error
• type IO
• type Kind
• type Runner

Variables

var ErrNoSuchObject = fmt.Errorf("no such object")

ErrNoSuchObject is returned by Inspect when the reference does not exist.

Functions

func IsRootlessPodman

func IsRootlessPodman(ctx context.Context, r Runner) bool

IsRootlessPodman reports whether r is podman running rootless, which decides defaults for --userns=keep-id and SELinux handling. It shells out to `podman info` and tolerates any failure by returning false.

func Version

func Version(ctx context.Context, r Runner) (string, error)

Version returns the runtime's version string (`<bin> --version`), trimmed.

Types

type CLIRunner

type CLIRunner struct {
	// Bin is the executable name or path ("podman", "docker", or absolute).
	Bin string
	// Base is prepended to every argument list (unused today; reserved for
	// global flags such as --connection). Kept so callers need not special-case.
	Base []string
}

CLIRunner is the real Runner, shelling out to a container CLI on PATH.

func Detect

func Detect(prefer string) (*CLIRunner, error)

Detect picks a container runtime. Selection order:

prefer (from --runtime flag) -> DEVC_RUNTIME env -> autodetect

Autodetection prefers podman over docker. It returns the binary found on PATH; an explicit preference that is not installed is an error.

func NewCLIRunner

func NewCLIRunner(bin string) *CLIRunner

NewCLIRunner returns a CLIRunner for the given binary.

func (*CLIRunner) BinPath

func (r *CLIRunner) BinPath() string

BinPath returns the runner's executable path, absolutized when possible. It is baked into the generated ssh ProxyCommand so the transport does not re-resolve the runtime through a possibly-stripped PATH.

func (*CLIRunner) Inspect

func (r *CLIRunner) Inspect(ctx context.Context, ref string, v any) error

func (*CLIRunner) Name

func (r *CLIRunner) Name() string

func (*CLIRunner) Output

func (r *CLIRunner) Output(ctx context.Context, args ...string) ([]byte, error)

func (*CLIRunner) Run

func (r *CLIRunner) Run(ctx context.Context, args []string, io IO) error

type Compose

type Compose struct {
	*CLIRunner
	Label string
}

Compose is a resolved compose implementation: a CLIRunner that invokes it (e.g. Bin="podman", Base=["compose"], or Bin="docker-compose") plus a human-readable label for diagnostics.

func DetectCompose

func DetectCompose(ctx context.Context, runtimeName, override string) (*Compose, error)

DetectCompose resolves a compose implementation. Selection order:

override (--compose-cmd flag) -> DEVC_COMPOSE env -> probe candidates

An override is a full command string ("podman compose", "docker-compose") and is used as-is without probing. Otherwise each candidate is probed with `<cmd> version` and the first that succeeds wins.

type FakeRunner

type FakeRunner struct {
	Bin string

	// Calls records the argv of every Run/Output/Inspect invocation, in order.
	Calls [][]string

	// OutputFunc, if set, produces the stdout (and optional error) for an
	// Output/Inspect call given its argv. Defaults to empty output, no error.
	OutputFunc func(args []string) ([]byte, error)

	// RunErr, if set, is returned by Run.
	RunErr error
}

FakeRunner is a Runner that records every invocation and replays scripted responses. It lets the whole tool be tested without a container runtime: argv is asserted against goldens, and Inspect / Output results are canned.

func NewFake

func NewFake() *FakeRunner

NewFake returns a FakeRunner named "podman" by default.

func (*FakeRunner) CallStrings

func (f *FakeRunner) CallStrings() []string

CallStrings renders every recorded call as a space-joined line, for golden comparison and debugging.

func (*FakeRunner) FindCall

func (f *FakeRunner) FindCall(verb string) []string

FindCall returns the first recorded call whose first argument equals verb, or nil. Handy for asserting a specific subcommand's flags.

func (*FakeRunner) Inspect

func (f *FakeRunner) Inspect(_ context.Context, ref string, v any) error

func (*FakeRunner) LastCall

func (f *FakeRunner) LastCall() []string

LastCall returns the argv of the most recent invocation, or nil.

func (*FakeRunner) Name

func (f *FakeRunner) Name() string

func (*FakeRunner) Output

func (f *FakeRunner) Output(_ context.Context, args ...string) ([]byte, error)

func (*FakeRunner) Run

func (f *FakeRunner) Run(_ context.Context, args []string, _ IO) error

type IO

type IO struct {
	Stdin  io.Reader
	Stdout io.Writer
	Stderr io.Writer
}

IO carries the standard streams for a single invocation. Any nil stream is left disconnected (the child gets no stdin / its output is discarded).

type Kind

type Kind string

Kind names a container runtime.

const (
	Podman Kind = "podman"
	Docker Kind = "docker"
)

type Runner

type Runner interface {
	// Name is the runtime binary, "podman" or "docker".
	Name() string
	// Run executes `<name> <args...>` wired to io and returns the process
	// error (an *exec.ExitError on non-zero exit).
	Run(ctx context.Context, args []string, io IO) error
	// Output runs `<name> <args...>` and returns stdout. Stderr is captured and
	// folded into the error on failure.
	Output(ctx context.Context, args ...string) ([]byte, error)
	// Inspect runs `<name> inspect --format {{json .}} <ref>` and decodes the
	// single-object result into v. It returns ErrNoSuchObject if ref is unknown.
	Inspect(ctx context.Context, ref string, v any) error
}

Runner runs one container-CLI invocation at a time. Implementations must be safe for sequential use; devc never shares a Runner across goroutines.