Documentation
¶
Overview ¶
Package runner runs the programs that ncly and its extensions start, as the Programs that ncly runs section of contract.md defines. It owns their environment, their session or process group, their cancellation, their captured output, and their exit code.
Start a program without the terminal with Setsid alone, never with Setpgid too, because setpgid refuses a session leader (D047). Give such a program no descriptor of the terminal, because a process outside the terminal's session reads it without a stop. Bound what a caller keeps of noisy output with Capture.
Read a program's stdout and stderr through pipes that the runner owns: a writer that exec.Cmd copies can keep Wait blocked until descendants close the pipe. Send cleanup signals through the runner to the whole process tree, because exec.CommandContext kills only the direct child. Keep the signal handler registered until cleanup ends, because stopping signal.NotifyContext first lets a second Ctrl-C end ncly at once. The test binary shortens the 15 seconds of cleanup, so a scenario proves the SIGKILL path without waiting.
Index ¶
- Constants
- Variables
- func Environ(parent []string, set map[string]string) []string
- func ListenForSignals() (context.Context, func())
- func Lookup(name, path string) string
- func OnSignal() context.Context
- func SignalOf(ctx context.Context) os.Signal
- func Stop(sig os.Signal)
- type Capture
- type Program
- type ProgramCheck
- type Result
- type SignalCause
- type Verdict
Constants ¶
const DrainLimit = 2 * time.Second
DrainLimit bounds how long the runner reads a program's streams after the program exits, because a descendant may hold them open. It runs on its own clock, apart from Cleanup.
Variables ¶
var Cleanup = 15 * time.Second
Cleanup bounds the time that a program and its descendants get to stop after a signal, before SIGKILL ends what still runs. Only the test binary shortens it.
Functions ¶
func Environ ¶
Environ returns the environment of a program: its parent's, without the key of any service, which needs a grant, and with each variable of set given its value, or removed when that value is empty.
func ListenForSignals ¶ added in v0.18.0
ListenForSignals returns a context that the first Ctrl-C or SIGTERM ends, with that signal as its cause, as OnSignal does, and a function that stops listening, after which a signal reaches the process as before, such as once a form has its answer.
func Lookup ¶ added in v0.18.0
Lookup returns the first executable file named name in the folders of path, skipping an empty or relative one, as discovery does, or empty.
func OnSignal ¶
OnSignal returns a context that the first Ctrl-C or SIGTERM ends, with that signal as its cause. The handler stays registered for the life of the process, so a later signal never ends it.
func SignalOf ¶
SignalOf returns the signal that ended ctx, and SIGTERM when ctx ended for another reason, such as a timeout.
func Stop ¶ added in v0.18.0
Stop sends sig to every descendant of ncly, then waits until none runs, and sends SIGKILL to those that still run once cleanup ends, as Cancellation in contract.md defines. It reaches a program that starts outside Run, such as the security program that go-keyring starts on macOS, so a command that a signal ends while it waits for one calls it.
Types ¶
type Capture ¶ added in v0.18.0
type Capture struct {
Limit int
// contains filtered or unexported fields
}
Capture keeps what a program writes, up to Limit bytes, and drops the rest, so a noisy program never fills the memory of ncly. A write never fails, so the program never waits on a full pipe. Read it once Run returns, because Run stops every copy before it returns.
type Program ¶
type Program struct {
Path string
// Name, when set, is the program's argv[0] instead of Path, as ncly
// starts itself under the name of a bundled extension.
Name string
Args []string
Env []string
// Stdin, Stdout, and Stderr reach the program. An *os.File passes as it
// is, so the program sees the terminal when it is one.
Stdin io.Reader
Stdout io.Writer
Stderr io.Writer
// Terminal keeps the program in the process group of ncly, because it
// may read the terminal, as an extension does. Any other program starts
// in a new session, with no controlling terminal, so an open of /dev/tty
// fails at once. Such a program also gets no descriptor of the terminal.
// A terminal on its stdin fails Run. A terminal on its stdout or stderr
// reaches it through a pipe that the runner reads. No program inherits a
// descriptor of the terminal above stderr.
Terminal bool
// Limit, when set, bounds execution. If it expires before the program
// exits, Run sends SIGKILL to every descendant of ncly and closes the
// streams at once. Normal exit and cancellation keep their ordinary
// drain and cleanup, even when the limit expires during them.
Limit time.Duration
// Completion also bounds output reading by Limit and skips cleanup on
// cancellation, as a list command that completion runs requires.
Completion bool
// CleanupReserve leaves this much of Cleanup for the direct program after
// force-stopping its descendants. Zero keeps the ordinary single deadline.
// The reservation is clamped to zero through Cleanup; it never extends it.
CleanupReserve time.Duration
}
Program is one program to run.
type ProgramCheck ¶ added in v0.18.0
type ProgramCheck struct {
Verdict Verdict
// Path is where the lookup found the program, or empty when missing.
Path string
// Version is the version that the probe printed, or empty.
Version string
// Exit is the probe's exit code, for ProgramProbeFailed.
Exit int
// Install is the install command of the first package manager of this
// system that the requirement names and PATH holds, or nil.
Install []string
// Signal is the signal that ended the probe, or nil.
Signal os.Signal
}
ProgramCheck is what a program check found.
func CheckProgram ¶ added in v0.18.0
func CheckProgram(ctx context.Context, name string, r contract.Requirement, env []string, limit time.Duration) (ProgramCheck, error)
CheckProgram checks one program that a manifest requires. It looks name up in the PATH of env. When r declares a version, it runs the probe for at most limit, with stdin closed, in a new session. It then compares the version that the probe prints with r's. A failed check names the install command of this system. Doctor, sdk/wrap, and a Go extension's status command share it, so none copies the rule.
func (ProgramCheck) Failed ¶ added in v0.18.0
func (c ProgramCheck) Failed() bool
Failed reports whether the check fails with PREREQ_MISSING.
type Result ¶
type Result struct {
// Exit is the program's exit code, or 128 plus the number of the signal
// that ended it, as a shell reports it. It is -1 when ctx had ended
// before the program started, so it never ran.
Exit int
// Signal is the signal that ended ctx before the program exited, or
// SIGTERM when another cause, such as a deadline, ended it. A signal that
// ends ctx within signalSettle after the exit counts too, because it may
// have reached the program first. Signal is nil otherwise.
Signal os.Signal
// TimedOut reports that the program still ran at its Limit.
TimedOut bool
}
Result is how a program ended.
func Run ¶
Run starts the program and waits for it to exit. When ctx ends first, Run sends the signal that ended it, or SIGTERM for any other end, to every descendant of ncly that it can reach, the program included, and sends SIGKILL to what still runs once Cleanup has passed. A signal that ends ctx within signalSettle after the exit does the same. Any other later end of ctx, such as a deadline, changes nothing. Run reads a stream that is not a file for at most DrainLimit after the program exits.
type SignalCause ¶
SignalCause is the cause of a context that a signal ended.
func (SignalCause) Error ¶
func (c SignalCause) Error() string
type Verdict ¶ added in v0.18.0
type Verdict string
Verdict is the outcome of a program check, as Required programs in core-spec.md defines it.
const ( // ProgramFound is a program found in PATH, recent enough when it // declares a version. ProgramFound Verdict = "found" // ProgramMissing is a program that no folder of PATH holds. ProgramMissing Verdict = "missing" // ProgramTooOld is a program whose version is older than the one it // declares. ProgramTooOld Verdict = "too_old" // ProgramProbeFailed is a probe that exited with another code than 0. ProgramProbeFailed Verdict = "probe_failed" // ProgramNoVersion is a probe that printed no version. ProgramNoVersion Verdict = "no_version" // ProgramTimedOut is a probe that still ran at its limit, or a signal // that ended it. ProgramTimedOut Verdict = "timed_out" )