exec

Documentation

Index

• Constants
• func ArgToCmd(ctx context.Context, args ...[]string) (cmds []*std_exec.Cmd)
• func CmdToString(cmds ...*std_exec.Cmd) string
• type CommonExecutor
  • func (c CommonExecutor) Buffered(ctx context.Context, cmds ...*std_exec.Cmd) (stdout *bytes.Buffer, stderr *bytes.Buffer, res PipelineResult, err error)
  • func (c CommonExecutor) Command(name string, arg ...string) *std_exec.Cmd
  • func (c CommonExecutor) CommandContext(ctx context.Context, name string, arg ...string) *std_exec.Cmd
  • func (c CommonExecutor) Pty(cmd *std_exec.Cmd) error
  • func (c CommonExecutor) Standard(ctx context.Context, stdout io.Writer, stderr io.Writer, stdin io.Reader, ...) (res PipelineResult, err error)
• type Executor
• type PipelineResult
• type Result

Constants

const (
	SigIntDelay  = 2 * time.Second
	SigKillDelay = 5 * time.Second
)

Functions

func ArgToCmd

func ArgToCmd(ctx context.Context, args ...[]string) (cmds []*std_exec.Cmd)

func CmdToString

func CmdToString(cmds ...*std_exec.Cmd) string

CmdToString stringifies an os/exec.Cmd.

Types

type CommonExecutor

type CommonExecutor struct{}

CommonExecutor provides a general case Executor implementation.

func (CommonExecutor) Buffered

func (c CommonExecutor) Buffered(ctx context.Context, cmds ...*std_exec.Cmd) (stdout *bytes.Buffer, stderr *bytes.Buffer, res PipelineResult, err error)

Buffered returns standard output/error in addition to the exit code.

It implements an Executor behavior.

func (CommonExecutor) Command

func (c CommonExecutor) Command(name string, arg ...string) *std_exec.Cmd

Command completely delegates to the os/exec method.

It implements an Executor behavior.

func (CommonExecutor) CommandContext

func (c CommonExecutor) CommandContext(ctx context.Context, name string, arg ...string) *std_exec.Cmd

CommandContext completely delegates to the os/exec method.

It implements an Executor behavior.

func (CommonExecutor) Pty

func (c CommonExecutor) Pty(cmd *std_exec.Cmd) error

Pty runs the command in a pseudo-terminal and returns an error only if the command fails to start.

It implements an Executor behavior.

func (CommonExecutor) Standard

func (c CommonExecutor) Standard(ctx context.Context, stdout io.Writer, stderr io.Writer, stdin io.Reader, cmds ...*std_exec.Cmd) (res PipelineResult, err error)

Standard allows standard in, out, and error to be customized.

It implements an Executor behavior.

type Executor

type Executor interface {
	// Command replaces the standard library os/exec method, allowing mock implementations to
	// control Cmd creation in addition to Cmd execution.
	//
	// Tests may need to use it when asserting mocking a method's (e.g. Buffered) return values
	// and also asserting PipelineResult.Cmd contents. This is because PipelineResult.Cmd is a map
	// indexed by the executed os/exec.Cmd. A mock Command will allow the method (e.g. Buffered)
	// to execute, and also index PipelineResult.Cmd, will the exact same pointer.
	Command(name string, arg ...string) *std_exec.Cmd

	// CommandContext replaces the standard library os/exec method, allowing mock implementations to
	// control Cmd creation in addition to Cmd execution.
	//
	// Tests may need to use it when asserting mocking a method's (e.g. Buffered) return values
	// and also asserting PipelineResult.Cmd contents. This is because PipelineResult.Cmd is a map
	// indexed by the executed os/exec.Cmd. A mock Command will allow the method (e.g. Buffered)
	// to execute, and also index PipelineResult.Cmd, will the exact same pointer.
	CommandContext(ctx context.Context, name string, arg ...string) *std_exec.Cmd

	// Buffered returns standard output/error in addition to the exit code.
	//
	// - Assumes all commands in the pipeline share the passed context.
	// - Return error should be used to determine overall pipeline success.
	//   Per-process results are stored in the return PipelineResult.Cmd map.
	// - If multiple commands are passed, standard out/error between them will be piped.
	// - Returned stdout is only from cmds[len(cmds)-1].
	// - Returned stderr is from all commands. Its ordering is not guaranteed, but per-command stderr
	//   is available in PipelineResult.Cmd Result values.
	Buffered(ctx context.Context, cmds ...*std_exec.Cmd) (stdout *bytes.Buffer, stderr *bytes.Buffer, res PipelineResult, err error)

	// Standard allows standard in, out, and error to be customized.
	//
	// - Assumes all commands in the pipeline share the passed context.
	// - Return error should be used to determine overall pipeline success.
	//   Per-process results are stored in the return PipelineResult.Cmd map.
	// - If multiple commands are passed, standard out/error between them will be piped.
	// - Input stdin will be piped to the first input exec.Cmd.
	// - Input stdout receives only from cmds[len(cmds)-1].
	// - Input stderr receives from all commands. Its ordering is not guaranteed, but per-command stderr
	//   is available in PipelineResult.Cmd Result values.
	Standard(ctx context.Context, stdout io.Writer, stderr io.Writer, stdin io.Reader, cmds ...*std_exec.Cmd) (res PipelineResult, err error)

	// Pty runs the command in a pseudo-terminal and returns an error only if the command fails to start.
	Pty(cmd *std_exec.Cmd) error
}

Executor implementations handle os/exec.Cmd execution in various ways, e.g. buffered output.

The main intent is to allow tests of client code to use mock implementations.

type PipelineResult

type PipelineResult struct {
	// Cmd stores more detail about each process executed in the pipeline.
	Cmd map[*std_exec.Cmd]Result
}

type Result

type Result struct {
	Code int

	// Pid supports concerns like verifying the process exited.
	Pid int

	// Pgid supports concerns like verifying the process group exited.
	//
	// Values are NOT pre-negated, e.g. for syscall.Kill.
	Pgid int

	Stdout *bytes.Buffer
	Stderr *bytes.Buffer

	Err error
}