Documentation
¶
Overview ¶
Package exec runs external commands. It wraps exec.Cmd package with support for allocating a pseudo-terminal.
Index ¶
- Constants
- Variables
- func PrepareConsole(_ log.Logger) bool
- func PrepareStdinForPrompt(_ log.Logger)
- type Cmd
- func (cmd *Cmd) Configure(opts ...Option)
- func (cmd *Cmd) Dir() string
- func (cmd *Cmd) ForwardSignal(ctx context.Context, l log.Logger, sig os.Signal)
- func (cmd *Cmd) RegisterGracefullyShutdown(ctx context.Context, l log.Logger) func()
- func (cmd *Cmd) Run(l log.Logger) error
- func (cmd *Cmd) SendSignal(l log.Logger, sig os.Signal)
- func (cmd *Cmd) SetDir(dir string)
- func (cmd *Cmd) SetEnv(env []string)
- func (cmd *Cmd) SetStderr(w io.Writer)
- func (cmd *Cmd) SetStdin(r io.Reader)
- func (cmd *Cmd) SetStdout(w io.Writer)
- func (cmd *Cmd) Start(l log.Logger) error
- func (cmd *Cmd) Wait() error
- type ConsoleState
- type Option
Constants ¶
const DefaultGracefulShutdownDelay = 30 * time.Second
DefaultGracefulShutdownDelay is the default time to wait for a process to exit gracefully after sending an interrupt signal before escalating to SIGKILL.
Variables ¶
var ErrPTYRequiresOSBackend = errors.New("PTY allocation requires an OS-backed vexec.Exec")
ErrPTYRequiresOSBackend is returned when a Cmd is started with PTY allocation requested but the underlying vexec.Exec is not OS-backed.
Functions ¶
func PrepareConsole ¶
PrepareConsole is run at the start of the application to set up the console. On Unix, terminals handle ANSI escape sequences natively, so this is a no-op. Returns true to indicate ANSI support is available.
func PrepareStdinForPrompt ¶ added in v1.0.0
PrepareStdinForPrompt is a no-op on Unix.
Types ¶
type Cmd ¶
type Cmd struct {
// contains filtered or unexported fields
}
Cmd wraps a vexec.Cmd with signal forwarding and optional PTY support. The Cmd may be backed by a real OS process or by an in-memory vexec backend (used in tests and fuzzers to prevent fork of external binaries).
func Command ¶
Command returns a `Cmd` configured to execute the named program with the given arguments via the provided vexec.Exec. PTY allocation requires an OS-backed Exec; non-OS backends are accepted but `WithUsePTY(true)` will fail at Start with ErrPTYRequiresOSBackend.
func (*Cmd) ForwardSignal ¶
ForwardSignal forwards a given `sig` with a delay if cmd.forwardSignalDelay is greater than 0, and if the same signal is received again, it is forwarded immediately.
func (*Cmd) RegisterGracefullyShutdown ¶
RegisterGracefullyShutdown registers a graceful shutdown for the command in two ways:
- If the context cancel contains a cause with a signal, this means that Terragrunt received the signal from the OS, since our executed command may also receive the same signal, we need to give the command time to gracefully shutting down, to avoid the command receiving this signal twice. Thus we will send the signal to the executed command with a delay or immediately if Terragrunt receives this same signal again.
- If the context does not contain any causes, this means that there was some failure and we need to terminate all executed commands, in this situation we are sure that commands did not receive any signal, so we send them an interrupt signal immediately.
func (*Cmd) SendSignal ¶
SendSignal sends the given `sig` to the executed command. Errors are logged rather than returned; ErrProcessNotStarted is silently ignored because callers may race against process startup.
type ConsoleState ¶ added in v1.0.0
type ConsoleState struct{}
ConsoleState is a no-op on Unix. On Windows it saves/restores console modes that subprocesses may modify.
func SaveConsoleState ¶ added in v1.0.0
func SaveConsoleState() ConsoleState
SaveConsoleState is a no-op on Unix.
func (ConsoleState) Restore ¶ added in v1.0.0
func (ConsoleState) Restore()
Restore is a no-op on Unix.
type Option ¶
type Option func(*Cmd)
Option is type for passing options to the Cmd.
func WithForwardSignalDelay ¶
WithForwardSignalDelay sets forwarding signal delay to the Cmd.
func WithGracefulShutdownDelay ¶ added in v0.99.2
WithGracefulShutdownDelay sets the time to wait for a process to exit gracefully after sending an interrupt signal before escalating to SIGKILL. This allows processes like Terraform to clean up child processes (e.g., provider plugins).
Source Files