prober

Documentation

Overview

Package prober exports Probe, which implements logic to identify a wrapper's wrapped target. In addition to basic PATH/filename lookup, Prober contains logic to ensure that the wrapper is not the same software as the current running instance, and enables optional hard-coded wrap target paths and runtime checks.

Index

• type CheckWrapperFunc
• type Probe
  • func (p *Probe) Locate(c context.Context, cached string, env environ.Env) (string, error)
  • func (p *Probe) ResolveSelf(argv0 string) error

Types

type CheckWrapperFunc

type CheckWrapperFunc func(c context.Context, path string, env environ.Env) (isWrapper bool, err error)

CheckWrapperFunc is an optional function that can be implemented for a Prober to check if a candidate path is a wrapper.

type Probe

type Probe struct {
	// Target is the name of the target (as seen by exec.LookPath) that we are
	// searching for.
	Target string

	// RelativePathOverride is a series of forward-slash-delimited paths to
	// directories relative to the wrapper executable that will be checked
	// prior to checking PATH. This allows bundles (e.g., CIPD) that include both
	// the wrapper and a real implementation, to force the wrapper to use
	// the bundled implementation.
	RelativePathOverride []string

	// CheckWrapper, if not nil, is a function called on a candidate wrapper to
	// determine whether or not that candidate is valid.
	//
	// On success, it will return isWrapper, which will be true if path is a
	// wrapper instance and false if it is not. If an error occurred during
	// checking, the error should be returned and isWrapper will be ignored. If
	// a candidate is a wrapper, or if an error occurred during check, the
	// candidate will be discarded and the probe will continue.
	//
	// CheckWrapper should be lightweight and fast, as it may be called multiple
	// times.
	CheckWrapper CheckWrapperFunc

	// Self and Selfstat are resolved contain the path and FileInfo of the
	// currently running executable, respectively. They can both be resolved via
	// ResolveSelf, and may be empty if resolution has not been performed, or if
	// the current executable could not be resolved. They may also be set
	// explicitly, bypassing the need to perform resolution.
	Self     string
	SelfStat os.FileInfo

	// PathDirs, if not zero, contains the list of directories to search. If
	// zero, the os.PathListSeparator-delimited PATH environment variable will
	// be used.
	PathDirs []string
}

Probe can Locate a Target executable by probing the local system PATH.

Target should be an executable name resolvable by exec.LookPath. On Windows systems, this may omit the executable extension (e.g., "bat", "exe") since that is augmented via the PATHEXT environment variable (see "probe_windows.go").

func (*Probe) Locate

func (p *Probe) Locate(c context.Context, cached string, env environ.Env) (string, error)

Locate attempts to locate the system's Target by traversing the available PATH.

cached is the cached path, passed from wrapper to wrapper through the a State struct in the environment. This may be empty, if there was no cached path or if the cached path was invalid.

env is the environment to operate with, and will not be modified during execution.

func (*Probe) ResolveSelf

func (p *Probe) ResolveSelf(argv0 string) error

ResolveSelf attempts to identify the current process. If successful, p's Self will be set to an absolute path reference to Self, and its SelfStat field will be set to the os.FileInfo for that path.

If this process was invoked via symlink, the path to the symlink will be returned if possible.