Documentation
¶
Index ¶
- Constants
- Variables
- func BuildCommandEscapedString(command string, args []string) string
- func BuildShellCommandString(shell string, args []string, command string) string
- 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 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 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 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 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 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