Documentation
¶
Index ¶
- Constants
- Variables
- func BuildCommandEscapedString(command string, args []string) string
- func BuildShellCommandString(shell string, args []string, command string) string
- func DetachAttr(_ bool) *syscall.SysProcAttr
- func DetectShebang(script string) (string, []string, error)
- func FindExecutable(cmd string) (string, bool)
- func GetScriptExtension(shellCommand string) string
- func GetShellCommand(configuredShell string) string
- func HasShellArgs(shell []string) bool
- func IsCmdShell(shell string) bool
- func IsExecutableFileInEnv(path string, envs []string) bool
- func IsNixShell(shell string) bool
- func IsPowerShell(shell string) bool
- func IsShellValueSet(shellValue any) bool
- func IsUnixLikeShell(shell string) bool
- func JoinCommandArgs(cmd string, args []string) string
- func KillMultipleProcessGroups(cmds map[string]*exec.Cmd, sig os.Signal) errordeprecated
- func KillProcessGroup(cmd *exec.Cmd, sig os.Signal) errordeprecated
- func LookPathInEnv(name string, envs []string) (string, error)
- func LookPathInEnvDir(name string, envs []string, dir string) (string, error)
- func LookupEnv(envs []string, key string) (string, bool)
- func ParsePipedCommand(cmdString string) ([][]string, error)
- func ResolveExecutable(cmd string) string
- func SetupCommand(cmd *exec.Cmd)
- func ShellCommandFlag(shell string) string
- func ShellQuote(s string) string
- func ShellQuoteArgs(args []string) string
- func SplitCommand(cmd string) (string, []string, error)
- func SplitCommandArgs(cmdWithArgs string) (string, []string)
- func StartParentExitWatcher(cmd *exec.Cmd) (func(), error)
- func TerminateMultipleProcessGroups(cmds map[string]*exec.Cmd, intent TerminationIntent) error
- func TerminateProcessGroup(cmd *exec.Cmd, intent TerminationIntent) error
- type ManagedProcess
- type StopMechanism
- type StopOutcome
- type StopReason
- type StopRequest
- type TerminationIntent
- type TerminationMode
Constants ¶
const ArgsDelimiter = "∯ᓰ♨"
ArgsDelimiter is the delimiter used to separate command arguments
Variables ¶
var ErrCommandIsEmpty = fmt.Errorf("command is empty")
Functions ¶
func BuildCommandEscapedString ¶
BuildCommandEscapedString constructs a single shell-ready string from a command and its arguments. It assumes that the command and arguments are already escaped.
func BuildShellCommandString ¶
BuildShellCommandString constructs a complete shell command string suitable for remote execution (e.g., via SSH). The command is properly quoted.
Example outputs:
- Unix: `/bin/bash -c 'echo hello'`
- PowerShell: `powershell -Command 'echo hello'`
- cmd.exe: `cmd.exe /c 'echo hello'`
func DetachAttr ¶
func DetachAttr(_ bool) *syscall.SysProcAttr
DetachAttr returns process attributes that start a command in a session of its own, so the end of the caller's terminal or process group does not end it. breakawayFromJob applies only on Windows.
func DetectShebang ¶
DetectShebang checks if the given script starts with a shebang (#!) line.
func FindExecutable ¶
FindExecutable resolves cmd from PATH first, then falls back to common Windows compatibility locations for Git-provided Unix tooling.
func GetScriptExtension ¶
GetScriptExtension returns the appropriate file extension for the given shell. This is needed because some shells (like PowerShell) require specific file extensions.
func GetShellCommand ¶
GetShellCommand returns the shell to use for command execution
func HasShellArgs ¶
HasShellArgs reports whether a shell slice contains a non-empty argument that is not the "direct" shell placeholder.
func IsCmdShell ¶
IsCmdShell reports whether the shell is Windows cmd.exe.
func IsExecutableFileInEnv ¶ added in v2.18.0
IsExecutableFileInEnv reports whether path resolves to a file the process starter can launch under envs. Off Windows the file must exist and carry an executable bit. On Windows it follows the os/exec lookup rules: a name with an extension is tried as is, then each PATHEXT suffix is appended, and the first existing candidate must carry a PATHEXT extension — a match like tool.txt resolves at lookup but cannot launch. An extensionless name never matches as is, so tool resolves tool.cmd even when a file named tool exists.
func IsNixShell ¶
IsNixShell reports whether the shell is nix-shell.
func IsPowerShell ¶
IsPowerShell reports whether the shell is PowerShell or pwsh.
func IsShellValueSet ¶
IsShellValueSet checks whether a shell value from a generic config is non-empty and not the "direct" shell placeholder.
func IsUnixLikeShell ¶
IsUnixLikeShell reports whether the shell supports -c and -e flags. Returns true for sh, bash, zsh, ksh, ash, dash (including .exe variants).
func JoinCommandArgs ¶
JoinCommandArgs joins a command and its arguments into a single string separated by ArgsDelimiter
func LookPathInEnv ¶ added in v2.18.0
LookPathInEnv resolves name to an executable file using the PATH entry in envs, honoring PATHEXT on Windows. When envs carries no PATH entry it falls back to FindExecutable. Names containing a path separator are checked as file paths.
func LookPathInEnvDir ¶ added in v2.18.0
LookPathInEnvDir is LookPathInEnv with relative names resolved against dir, matching how a process started in dir resolves them: relative PATH entries and relative path-form names anchor to dir instead of the process working directory. An empty dir keeps process working directory semantics.
func LookupEnv ¶ added in v2.18.0
LookupEnv returns the value of the first "key=value" entry in envs whose key matches key. The key comparison is case-insensitive on Windows.
func ParsePipedCommand ¶
ParsePipedCommand splits a shell-style command string into a pipeline ([][]string). Each sub-slice represents a single command. Unquoted "|" tokens define the boundaries.
Example:
parsePipedCommand(`echo foo | grep foo | wc -l`) =>
[][]string{
{"echo", "foo"},
{"grep", "foo"},
{"wc", "-l"},
}
parsePipedCommand(`echo "hello|world"`) =>
[][]string{ {"echo", "hello|world"} } // single command
func ResolveExecutable ¶
ResolveExecutable returns the best-effort resolved executable path for cmd. If no compatibility path is found, the original value is returned unchanged.
func SetupCommand ¶
SetupCommand configures Unix-specific command attributes
func ShellCommandFlag ¶
ShellCommandFlag returns the flag used to pass a command string to the shell. Returns "-c" for Unix shells, "-Command" for PowerShell, "/c" for cmd.exe, "--run" for nix-shell, or "-c" for unknown shells (defaulting to Unix-style).
func ShellQuote ¶
ShellQuote escapes a string for use in a shell command.
func ShellQuoteArgs ¶
ShellQuoteArgs escapes a slice of strings for use in a shell command.
func SplitCommand ¶
SplitCommand splits a command string into a command and its arguments.
func SplitCommandArgs ¶
SplitCommandArgs splits a command and its arguments into a command and a slice of arguments
func StartParentExitWatcher ¶
StartParentExitWatcher starts a small watchdog process that kills cmd's process group if this parent process dies before the returned stop function sends a normal-shutdown token.
func TerminateMultipleProcessGroups ¶
func TerminateMultipleProcessGroups(cmds map[string]*exec.Cmd, intent TerminationIntent) error
TerminateMultipleProcessGroups stops multiple process groups on Unix systems.
func TerminateProcessGroup ¶
func TerminateProcessGroup(cmd *exec.Cmd, intent TerminationIntent) error
TerminateProcessGroup stops the process group on Unix systems according to the requested lifecycle intent.
Types ¶
type ManagedProcess ¶
type ManagedProcess struct {
// contains filtered or unexported fields
}
ManagedProcess owns the lifecycle for one local OS process.
func NewManagedProcess ¶
func NewManagedProcess(cmd *exec.Cmd) *ManagedProcess
NewManagedProcess wraps an already-created command for lifecycle operations.
func StartManagedProcess ¶
func StartManagedProcess(cmd *exec.Cmd) (*ManagedProcess, error)
StartManagedProcess configures, starts, and contains cmd for lifecycle management.
func (*ManagedProcess) Command ¶
func (p *ManagedProcess) Command() *exec.Cmd
Command returns the wrapped command.
func (*ManagedProcess) PID ¶
func (p *ManagedProcess) PID() int
PID returns the root process ID, or zero when no process is attached.
func (*ManagedProcess) Release ¶
func (p *ManagedProcess) Release() error
Release releases lifecycle resources. It is safe to call multiple times.
func (*ManagedProcess) Stop ¶
func (p *ManagedProcess) Stop(req StopRequest) (StopOutcome, error)
Stop requests that the platform adapter stop the process.
func (*ManagedProcess) Wait ¶
func (p *ManagedProcess) Wait() error
Wait waits for the root process to exit.
type StopMechanism ¶
type StopMechanism string
StopMechanism describes how a platform adapter requested process termination.
const ( StopMechanismNone StopMechanism = "none" StopMechanismProcessGroup StopMechanism = "process-group" StopMechanismProcessTree StopMechanism = "process-tree" StopMechanismJobObject StopMechanism = "job-object" )
type StopOutcome ¶
type StopOutcome struct {
RequestedMode TerminationMode
AppliedMode TerminationMode
Mechanism StopMechanism
Contained bool
Partial bool
Reason StopReason
}
StopOutcome reports how a platform adapter applied a stop request.
type StopReason ¶
type StopReason string
StopReason describes why a process stop was requested.
const ( StopReasonUnknown StopReason = "" StopReasonCancel StopReason = "cancel" StopReasonTimeout StopReason = "timeout" StopReasonShutdown StopReason = "shutdown" StopReasonParentExit StopReason = "parent-exit" )
type StopRequest ¶
type StopRequest struct {
Intent TerminationIntent
Reason StopReason
}
StopRequest is the platform-neutral lifecycle request for a local process.
type TerminationIntent ¶
type TerminationIntent struct {
Mode TerminationMode
Signal os.Signal
}
TerminationIntent is the platform-neutral stop request used by process adapters. Signal is retained for POSIX adapters and for user-facing logs, but callers should make decisions from Mode instead of assuming Unix semantics.
func ForceTermination ¶
func ForceTermination() TerminationIntent
ForceTermination creates a forceful process-tree termination request.
func GracefulTermination ¶
func GracefulTermination(sig os.Signal) TerminationIntent
GracefulTermination creates a graceful stop request for the given signal. Force-class signals are normalized to a forceful intent.
func TerminationFromSignal ¶
func TerminationFromSignal(sig os.Signal) TerminationIntent
TerminationFromSignal preserves the legacy signal-based call sites while moving the implementation behind an intent-based seam.
func (TerminationIntent) IsForce ¶
func (i TerminationIntent) IsForce() bool
IsForce reports whether this request is a forceful stop.
func (TerminationIntent) IsTermination ¶
func (i TerminationIntent) IsTermination() bool
IsTermination reports whether this intent should mark a running node aborted.
func (TerminationIntent) SignalName ¶
func (i TerminationIntent) SignalName() string
SignalName returns a stable string for logging.
func (TerminationIntent) WithSignal ¶
func (i TerminationIntent) WithSignal(sig os.Signal) TerminationIntent
WithSignal returns a copy of the intent with a different signal. Force-class signals always force the mode because they cannot be graceful in practice.
type TerminationMode ¶
type TerminationMode string
TerminationMode describes the lifecycle intent behind a process stop request.
const ( // TerminationModeGraceful asks the platform adapter to stop the process tree // using the least forceful supported mechanism for the requested signal. TerminationModeGraceful TerminationMode = "graceful" // TerminationModeForce asks the platform adapter to terminate the process tree. TerminationModeForce TerminationMode = "force" )
Source Files