Documentation
¶
Overview ¶
Package exec provides command execution utilities.
Index ¶
- Constants
- type CmdResult
- type CommandExecutor
- type Exec
- func (e *Exec) RunCmd(ctx context.Context, name string, args []string) (string, error)
- func (e *Exec) RunCmdFull(ctx context.Context, name string, args []string, cwd string, timeout int) (*CmdResult, error)
- func (e *Exec) RunCmdImpl(ctx context.Context, name string, args []string, cwd string) (string, error)
- func (e *Exec) RunCmdInDir(ctx context.Context, name string, args []string, cwd string) (string, error)
- func (e *Exec) RunPrivilegedCmd(ctx context.Context, name string, args []string) (string, error)
- func (e *Exec) RunPrivilegedCmdWithStdin(ctx context.Context, name string, args []string, stdin string) (string, error)
- type Manager
Constants ¶
const DefaultCommandTimeout = 10 * time.Minute
DefaultCommandTimeout bounds a command whose caller supplied no deadline of its own. It is a backstop rather than a budget: long enough for a package installation over a slow mirror, short enough that a command waiting on a prompt nobody will answer does not outlive the agent.
A caller's own deadline still wins whenever it falls earlier, because the deadline is derived from the context it passed.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CmdResult ¶
type CmdResult struct {
// Stdout contains the standard output of the command.
Stdout string
// Stderr contains the standard error output of the command.
Stderr string
// ExitCode is the exit code of the command.
ExitCode int
// DurationMs is the execution time in milliseconds.
DurationMs int64
}
CmdResult contains the full result of a command execution with separate stdout and stderr streams.
type CommandExecutor ¶
type CommandExecutor interface {
Execute(
ctx context.Context,
name string,
args []string,
cwd string,
) (string, error)
// ExecuteWithStdin runs the command with stdin written to its standard
// input. Implementations must not log stdin.
ExecuteWithStdin(
ctx context.Context,
name string,
args []string,
cwd string,
stdin string,
) (string, error)
}
CommandExecutor executes OS commands. The default implementation runs real commands via os/exec. Tests inject a mock to assert commands without executing them.
Every method takes a context: it is what cancels a command that is still running when the agent shuts down, and what bounds one that would otherwise run forever.
type Exec ¶
type Exec struct {
// contains filtered or unexported fields
}
Exec disk implementation.
func (*Exec) RunCmd ¶
RunCmd executes the provided command with arguments, using the current working directory.
func (*Exec) RunCmdFull ¶
func (e *Exec) RunCmdFull( ctx context.Context, name string, args []string, cwd string, timeout int, ) (*CmdResult, error)
RunCmdFull executes the provided command with separate stdout and stderr capture, an optional working directory, and a timeout in seconds. A timeout of 0 defaults to 30 seconds.
func (*Exec) RunCmdImpl ¶
func (e *Exec) RunCmdImpl( ctx context.Context, name string, args []string, cwd string, ) (string, error)
RunCmdImpl executes the provided command with the specified arguments and an optional working directory. It delegates to the CommandExecutor.
func (*Exec) RunCmdInDir ¶
func (e *Exec) RunCmdInDir( ctx context.Context, name string, args []string, cwd string, ) (string, error)
RunCmdInDir executes the provided command with arguments, using the current provided directory.
func (*Exec) RunPrivilegedCmd ¶
RunPrivilegedCmd executes the provided command with arguments. When sudo is enabled, the original command is passed as an argument to "sudo".
func (*Exec) RunPrivilegedCmdWithStdin ¶
func (e *Exec) RunPrivilegedCmdWithStdin( ctx context.Context, name string, args []string, stdin string, ) (string, error)
RunPrivilegedCmdWithStdin executes the provided command with arguments and writes stdin to the command's standard input. When sudo is enabled, the command is prepended with "sudo".
Pass secrets this way rather than in arguments: stdin is not interpreted by a shell, does not appear in the process list, and is never logged.
type Manager ¶
type Manager interface {
// RunCmd executes the provided command with arguments, using the current
// working directory.
RunCmd(
ctx context.Context,
name string,
args []string,
) (string, error)
// RunPrivilegedCmd executes the provided command with arguments.
// When sudo is enabled, the command is prepended with "sudo".
RunPrivilegedCmd(
ctx context.Context,
name string,
args []string,
) (string, error)
// RunPrivilegedCmdWithStdin executes the provided command with arguments
// and writes stdin to its standard input. When sudo is enabled, the
// command is prepended with "sudo". Use it to pass secrets, which must
// never be placed in arguments.
RunPrivilegedCmdWithStdin(
ctx context.Context,
name string,
args []string,
stdin string,
) (string, error)
// RunCmdFull executes a command with separate stdout/stderr capture,
// an optional working directory, and a timeout in seconds.
RunCmdFull(
ctx context.Context,
name string,
args []string,
cwd string,
timeout int,
) (*CmdResult, error)
}
Manager manager responsible for exec operations.
Every method takes a context. A command with no deadline of its own is bounded by DefaultCommandTimeout, and one still running when the agent shuts down is killed with it rather than outliving it.
Source Files
Directories