procx

package
v0.1.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 28, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Overview

Package procx holds the cross-platform process helpers every vendor plugin uses: finding a binary, probing its version, building a minimal environment, and starting and killing whole process trees on Linux, macOS and Windows.

It never starts a shell, except cmd.exe for Windows .cmd and .bat shims.

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrNotFound is returned by FindBinary when the binary is not on the search path.
	ErrNotFound = errors.New("procx: binary not found")

	// ErrUnsupported is returned for an operation the platform cannot do, such as
	// Proc.Interrupt on Windows. It wraps errors.ErrUnsupported.
	ErrUnsupported = fmt.Errorf("procx: operation not supported on this platform: %w", errors.ErrUnsupported)

	// ErrNoVersion is returned by Version when the output holds no version number.
	ErrNoVersion = errors.New("procx: no version found in output")

	// ErrRelativePath is returned by Start for a program path that is not absolute.
	ErrRelativePath = errors.New("procx: path must be absolute")

	// ErrUnsafeArg is returned for an argument that cannot be passed safely to a
	// .cmd or .bat file through cmd.exe.
	ErrUnsafeArg = errors.New("procx: argument cannot be passed safely to a .cmd or .bat file")
)

Functions

func AtLeast

func AtLeast(found, min string) bool

AtLeast reports whether the version found is at least min, by semver precedence. A leading "v" is optional on both sides. An empty min means no minimum and gives true; an invalid version on either side gives false. A pre-release is lower than its release, and build metadata is ignored.

func FindBinary

func FindBinary(name string, extra ...string) (string, error)

FindBinary looks for the program name in the PATH directories and then in the extra directories, and returns its absolute, symlink-resolved path.

An extra directory may start with "~" (the home directory) and may contain %NAME% references to environment variables. Relative directories, including relative PATH entries such as ".", are ignored, so the current directory is never searched. On Windows the candidates are name.exe, name.cmd, name.bat and name.com, restricted to the extensions listed in PATHEXT (other PATHEXT entries such as .vbs cannot be started and are ignored).

The error wraps ErrNotFound when nothing matches.

func NeverPass

func NeverPass() []string

NeverPass returns the names of the variables EnvBuilder never passes on.

func Version

func Version(ctx context.Context, path string, args ...string) (ver string, raw string, err error)

Version runs path with args (default: --version) and returns the first version number found in its stdout, then stderr, without a leading "v". The program gets a minimal environment and 10 seconds (less if ctx expires sooner); its output is bounded. raw holds the trimmed output, cut to 4 KiB, and is returned on every path so callers can show it. A non-zero exit code is an error even when the output holds a version; a missing version is an error wrapping ErrNoVersion.

Types

type EnvBuilder

type EnvBuilder struct {
	// contains filtered or unexported fields
}

EnvBuilder builds the environment of a child process. It starts from a small allow-list of the parent environment, so credentials and tokens in the parent are not inherited. The methods return the builder for chaining.

func Env

func Env() *EnvBuilder

Env returns a builder holding the allow-listed part of the current environment (PATH, HOME, USERPROFILE, APPDATA, LOCALAPPDATA, SystemRoot, TEMP, TMP, TMPDIR, LANG, LC_* and XDG_*) and TERM=dumb.

func (*EnvBuilder) Build

func (b *EnvBuilder) Build() []string

Build returns the environment as "NAME=value" strings sorted by name. Each call returns a new slice.

func (*EnvBuilder) Proxy

func (b *EnvBuilder) Proxy(proxy string) *EnvBuilder

Proxy points the child at the sandbox egress proxy (PROTOCOL §5.1, §15.3): HTTPS_PROXY, HTTP_PROXY and ALL_PROXY, with lower-case twins, and NO_PROXY=localhost,127.0.0.1. proxy is the sandbox.proxy value from initialize; an empty proxy is a no-op.

func (*EnvBuilder) Set

func (b *EnvBuilder) Set(name, value string) *EnvBuilder

Set adds or replaces a variable. The call is ignored when the name is empty or contains "=" or NUL, when the value contains NUL, or when the name is on the never-pass list (see NeverPass).

func (*EnvBuilder) Strip

func (b *EnvBuilder) Strip(prefixes ...string) *EnvBuilder

Strip removes every variable currently held whose name starts with one of the prefixes. Empty prefixes are ignored. The order of calls matters: a Set after Strip is kept, so the idiom

procx.Env().Strip("ANTHROPIC_").Set("ANTHROPIC_API_KEY", key)

removes inherited auth variables and then sets the one the connection wants.

type Proc

type Proc struct {
	// contains filtered or unexported fields
}

Proc is a started program and the root of its process tree.

The root owns its tree. When the root exits, every descendant still in the tree is killed, on every OS, unless KillTree is running (it finishes the job itself and honours its grace period). Descendants that leave the tree (a daemon that calls setsid on Unix) are outside it.

func Start

func Start(ctx context.Context, spec Spec) (*Proc, error)

Start runs the program described by spec as the root of a new process tree. It never uses a shell, except cmd.exe for .cmd and .bat files on Windows. Cancelling ctx kills the tree (SIGTERM, then SIGKILL after a short grace on Unix; immediately on Windows).

func (*Proc) Done

func (p *Proc) Done() <-chan struct{}

Done returns a channel that is closed when the root has exited, its tree has been cleaned up and the exit status is available.

func (*Proc) Interrupt

func (p *Proc) Interrupt() error

Interrupt asks the tree to stop gracefully: SIGINT to the process group on Unix. On Windows it returns ErrUnsupported (vendor plugins use their protocol-level interrupt). It returns os.ErrProcessDone after the root has exited.

func (*Proc) KillTree

func (p *Proc) KillTree(grace time.Duration)

KillTree stops the whole tree. On Unix it sends SIGTERM to the process group, waits up to grace for the group to disappear, then sends SIGKILL; grace <= 0 goes straight to SIGKILL. On Windows it terminates the Job Object at once and ignores grace. It returns after the root has been reaped (or after a safety timeout). KillTree is idempotent and safe for concurrent use: the first call decides the grace period, later calls wait for it, and a call after the process has finished does nothing.

func (*Proc) Pid

func (p *Proc) Pid() int

Pid returns the process id of the root.

func (*Proc) Wait

func (p *Proc) Wait() (exitCode int, err error)

Wait blocks until the root has exited and returns its exit code. A program killed by a signal on Unix reports 128+signal; one stopped by KillTree on Windows reports 1. The error is non-nil only when waiting itself failed, for example with exec.ErrWaitDelay. It is safe to call Wait many times and from many goroutines; every call returns the same values.

type Spec

type Spec struct {
	// Path is the absolute path of the program (use FindBinary). It is never
	// resolved through PATH. A .cmd or .bat path runs through cmd.exe on Windows.
	Path string
	// Args are the arguments without argv[0].
	Args []string
	// Dir is the working directory; empty means the current directory.
	Dir string
	// Env is the environment as "NAME=value" strings. A nil Env means
	// Env().Build(), the minimal environment; a non-nil empty slice means an
	// empty environment. The parent environment is never inherited implicitly.
	Env []string
	// Stdin, Stdout and Stderr connect the standard streams; nil means no input
	// and discarded output.
	Stdin          io.Reader
	Stdout, Stderr io.Writer
}

Spec describes a program to start.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL