prochost

package
v0.1.0-alpha.2 Latest Latest
Warning

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

Go to latest
Published: Oct 15, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package prochost hosts a helper process for process-kill proofs (openspec change setup-04a-01-floor, capability process-host). A helper is a function in the test binary: the test binary re-executes itself with an environment marker that selects it, so no runtime binary is built. The child runs in its own process group with stdout and stderr in files under the test's temporary directory, and the test can signal, pause, resume, kill and wait for it. No helper outlives its test: Start registers a cleanup that kills the group, joins the child and, when the test has failed, writes the child's output to the test log. Test-only: contract test T-B1 refuses any production import.

A helper that must stay up parks on a signal (signal.Notify for SIGTERM, then receive), never on a bare select{}. The child runs with only -test.run, so no test-timeout timer keeps the runtime waiting: once every goroutine blocks, Go kills it with "all goroutines are asleep" and exit 2.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Helper

func Helper(name string, fn func())

Helper runs fn and exits the process when the environment marker names this helper, and otherwise returns at once. Call it from the test binary's TestHelperProcess, once per helper; in a normal test run every call is a no-op.

Types

type ExitStatus

type ExitStatus struct {
	Code   int
	Signal syscall.Signal
}

ExitStatus is how a helper ended: Code is its exit code, or -1 when a signal ended it, and Signal is that signal, zero otherwise.

type Process

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

Process is one running helper. Signals go to its whole process group.

func Start

func Start(t testing.TB, name string, env ...string) (*Process, error)

Start re-executes the test binary to run the helper name, with env added to this process's environment, in a new process group. Output goes to files under t.TempDir(). t's cleanup kills the group, waits for the child and, if t has failed by then, writes the child's stdout and stderr to the test log.

func (*Process) Alive

func (p *Process) Alive() bool

Alive reports whether the helper has not yet exited. It reads the host's own record of the child, not the pid, so a reused pid cannot make it true.

func (*Process) Kill

func (p *Process) Kill() error

Kill kills the helper's process group (SIGKILL). Once the helper has been reaped it sends nothing and returns nil; a group already gone is not an error.

func (*Process) Pause

func (p *Process) Pause() error

Pause stops the helper's process group (SIGSTOP).

func (*Process) Resume

func (p *Process) Resume() error

Resume continues the helper's process group (SIGCONT).

func (*Process) Signal

func (p *Process) Signal(sig os.Signal) error

Signal sends sig, which must be a syscall.Signal, to the helper's process group. Once the helper has been reaped it sends nothing and returns an error, as Pause and Resume do.

A reap that lands between the Alive check and the signal is not prevented: the kernel frees the pid inside the reaper's blocking wait, so no lock can sit between them, and closing the window needs a per-platform waitid(WNOWAIT) reaper. Reuse inside that window needs the pid space to wrap within microseconds; for a test harness that residual is accepted.

func (*Process) Wait

func (p *Process) Wait(ctx context.Context) (ExitStatus, error)

Wait returns the helper's exit status once it has exited, or, when ctx ends first, ctx's error together with the process state last observed.

Jump to

Keyboard shortcuts

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