cmdexec

package
v0.11.0 Latest Latest
Warning

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

Go to latest
Published: Oct 7, 2026 License: GPL-3.0, LGPL-3.0 Imports: 7 Imported by: 0

Documentation

Overview

Package cmdexec provides a testable abstraction for running external commands.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func WrapExitError added in v0.10.0

func WrapExitError(err error, stderr string) error

WrapExitError returns a bare *exec.ExitError as an *ExitError carrying stderr, and any other error unchanged. Executors call it on the result of a finished command; test doubles call it so that their errors have the same shape as the real ones.

Types

type Executor

type Executor interface {
	// Run executes the named command with the given arguments and returns
	// the captured stdout and stderr. If the command exits with a non-zero
	// status, the returned error is an *ExitError that carries stderr and
	// wraps the *exec.ExitError.
	Run(ctx context.Context, name string, args ...string) (stdout string, stderr string, err error)

	// RunWithStdin is like Run but pipes the given reader to the command's stdin.
	RunWithStdin(ctx context.Context, stdin io.Reader, name string, args ...string) (stdout string, stderr string, err error)

	// Start starts a long-lived command and returns a Process for reading
	// its stdout incrementally. The command is killed when ctx is cancelled.
	// The caller must call Process.Close to release resources.
	Start(ctx context.Context, name string, args ...string) (*Process, error)
}

Executor runs external commands and captures their output.

type ExitError added in v0.10.0

type ExitError struct {
	Err    *exec.ExitError
	Stderr string
}

ExitError is the error of a command that ran and exited with a non-zero status. It keeps what the command wrote to stderr, which for docker is the only place that says what went wrong: "exit status 1" alone cannot tell a missing volume from one that is still in use.

func (*ExitError) Error added in v0.10.0

func (e *ExitError) Error() string

Error returns the exit status followed by the command's stderr, if any.

func (*ExitError) ExitCode added in v0.10.0

func (e *ExitError) ExitCode() int

ExitCode returns the command's exit code.

func (*ExitError) Unwrap added in v0.10.0

func (e *ExitError) Unwrap() error

Unwrap returns the underlying *exec.ExitError.

type LogFunc

type LogFunc func(ctx context.Context, cmd string)

LogFunc is called before each command execution with the context and the full command string (name + args joined by spaces).

type LoggingExecutor

type LoggingExecutor struct {
	Inner Executor
	Log   LogFunc
}

LoggingExecutor wraps another Executor and calls a LogFunc before each command invocation.

func (*LoggingExecutor) Run

func (l *LoggingExecutor) Run(ctx context.Context, name string, args ...string) (string, string, error)

Run implements Executor.

func (*LoggingExecutor) RunWithStdin

func (l *LoggingExecutor) RunWithStdin(ctx context.Context, stdin io.Reader, name string, args ...string) (string, string, error)

RunWithStdin implements Executor.

func (*LoggingExecutor) Start added in v0.9.0

func (l *LoggingExecutor) Start(ctx context.Context, name string, args ...string) (*Process, error)

Start implements Executor.

type OSExecutor

type OSExecutor struct{}

OSExecutor runs commands using os/exec.

func (*OSExecutor) Run

func (e *OSExecutor) Run(ctx context.Context, name string, args ...string) (string, string, error)

Run implements Executor.

func (*OSExecutor) RunWithStdin

func (e *OSExecutor) RunWithStdin(ctx context.Context, stdin io.Reader, name string, args ...string) (string, string, error)

RunWithStdin implements Executor.

func (*OSExecutor) Start added in v0.9.0

func (e *OSExecutor) Start(ctx context.Context, name string, args ...string) (*Process, error)

Start implements Executor.

type Process added in v0.9.0

type Process struct {
	Stdout io.ReadCloser
	// contains filtered or unexported fields
}

Process represents a running long-lived command whose stdout can be read incrementally. The caller must call Close to release resources.

func Start added in v0.9.0

func Start(ctx context.Context, name string, args ...string) (*Process, error)

Start starts a command and returns a Process for reading its stdout. The command is killed when ctx is cancelled.

func (*Process) Close added in v0.9.0

func (p *Process) Close() error

Close kills the process (if still running) and waits for it to exit. If the Process was created without a command (e.g. in tests), Close just closes Stdout. The "signal: killed" error from the intentional Kill is suppressed so normal shutdown returns nil.

Jump to

Keyboard shortcuts

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