runner

package
v0.18.5 Latest Latest
Warning

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

Go to latest
Published: Oct 23, 2026 License: MIT Imports: 20 Imported by: 0

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

View Source
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

View Source
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

func Environ(parent []string, set map[string]string) []string

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

func ListenForSignals() (context.Context, func())

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

func Lookup(name, path string) string

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

func OnSignal() context.Context

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

func SignalOf(ctx context.Context) os.Signal

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

func Stop(sig os.Signal)

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.

func (*Capture) Bytes added in v0.18.0

func (c *Capture) Bytes() []byte

Bytes returns what Capture kept.

func (*Capture) Over added in v0.18.0

func (c *Capture) Over() bool

Over reports whether the program wrote more than Limit bytes, so that Bytes holds only the first ones.

func (*Capture) Write added in v0.18.0

func (c *Capture) Write(p []byte) (int, error)

Write keeps what fits under Limit and drops the rest.

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
}

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

func Run(ctx context.Context, p Program) (Result, error)

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

type SignalCause struct{ Signal os.Signal }

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"
)

Jump to

Keyboard shortcuts

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