Documentation
¶
Overview ¶
Package process launches a harness as a plain child: the merged environment, the session cwd, its own process group, and three dedicated pipes.
Index ¶
- func ForwardedSignals() []os.Signal
- func LaunchFailure(p *Process, name string, err error) error
- func Lookup(env []string, key string) (string, bool)
- func ResolveExecutable(path string, env []string) (string, error)
- func ScratchDir(parent, vendor, purpose string) (string, error)
- func ScratchPath(parent, vendor, purpose, name string) (string, error)
- func ValidateExtraPathDirs(dirs []string) error
- func ValidateNames(env map[string]string) error
- func ValidateOptionalAbsolutePath(path string) error
- func WriteSeedFiles(dir string, files map[string]string) error
- type Environment
- type FileLock
- type NameError
- type PathDirError
- type Process
- func (p *Process) Close() error
- func (p *Process) Done() <-chan struct{}
- func (p *Process) Kill() error
- func (p *Process) Shutdown(ctx context.Context, grace time.Duration) error
- func (p *Process) StderrTail() string
- func (p *Process) Stdin() io.WriteCloser
- func (p *Process) Stdout() io.ReadCloser
- func (p *Process) Wait(ctx context.Context) (Result, error)
- type Request
- type Result
- type SeedFileError
- type SeedFileFlag
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ForwardedSignals ¶
ForwardedSignals are the signals a sibling's command binary turns into cancellation of its serving context.
func LaunchFailure ¶
LaunchFailure explains a launch that failed before the harness named name was ready. A failed handshake often means the harness is exiting, so it waits up to stderrFlushWait for the process to be reaped; one that exited is reported as such. Either way the stderr tail, where a dying or stalled harness states its reason, follows err.
func ResolveExecutable ¶
ResolveExecutable resolves the configured executable selector against env. A name containing a path separator is used as given; a bare name is searched on env's PATH. The result is an existing regular file with an execute bit.
func ScratchDir ¶
ScratchDir creates one ephemeral directory for one purpose under the scratch parent, which is the system temp directory when empty. The parent is created 0700 when missing, and the name carries the acp-go-<vendor>-<purpose>- prefix so a host can sweep orphans.
func ScratchPath ¶
ScratchPath names the directory for one purpose and one name under the scratch parent without creating it, so a sibling can address content the same way across launches.
func ValidateExtraPathDirs ¶
ValidateExtraPathDirs refuses an entry that is empty, relative, or contains the platform list separator.
func ValidateNames ¶
ValidateNames refuses a map whose entries could not be environment entries: an empty name, a name containing = or NUL, or a value containing NUL. Keys are checked in sorted order so the first refusal is deterministic.
func ValidateOptionalAbsolutePath ¶
ValidateOptionalAbsolutePath accepts an unset path and refuses a relative one. It guards the home and scratch path options.
func WriteSeedFiles ¶
WriteSeedFiles writes each file into dir under an ownership manifest so the adapter never overwrites a file it did not create: a pre-existing unmanaged target fails closed before anything is written, and every new path is recorded in the manifest before its file exists, so an interrupted write leaves only managed files behind. Every path is opened relative to dir with os.Root, and a symlink at a seed name is refused, so no write can leave the seed root.
Types ¶
type Environment ¶
type Environment struct {
// Process is the sibling's own environment, in KEY=value form, read once at
// construction.
Process []string
// Agent is the static host overlay from WithEnv.
Agent map[string]string
// Session is the per-session overlay from the session's env option.
Session map[string]string
// Owned are the keys the sibling sets because of how it launches the harness,
// such as the home variable.
Owned map[string]string
// InternalPrefix names the sibling's private process markers, dropped from
// every layer before the merge.
InternalPrefix string
// ExtraPathDirs are prepended, in order, to the PATH the merge produced.
ExtraPathDirs []string
}
Environment is the merge that produces a harness environment. Later layers win. Nothing is scrubbed except names under InternalPrefix, dropped from the inherited, agent, and session layers; the Owned layer is applied after that drop, so the sibling's own markers reach the child.
func (Environment) Base ¶
func (e Environment) Base() ([]string, error)
Base is the environment executable resolution uses: the process environment and the agent overlay, with internal markers dropped and no session or owned keys applied.
func (Environment) Build ¶
func (e Environment) Build() ([]string, error)
Build merges the layers into the KEY=value list the child receives, sorted by key. PATH is composed last from ExtraPathDirs and the merged PATH.
type FileLock ¶
type FileLock struct {
// contains filtered or unexported fields
}
FileLock owns an exclusive advisory file lock.
type NameError ¶
type NameError struct {
Key string
}
NameError reports an environment entry that cannot be a variable.
type PathDirError ¶
PathDirError reports an extra path directory that is not an absolute separator-free path.
func (*PathDirError) Error ¶
func (e *PathDirError) Error() string
type Process ¶
type Process struct {
// contains filtered or unexported fields
}
Process is a running harness with its stdin and stdout pipes and a bounded stderr tail it drains itself. Wait may be called from many goroutines; the first call begins reaping and every caller sees the same result.
func Start ¶
Start launches the request as a child in its own process group with dedicated pipes for stdin, stderr, and, unless the request names a stdout file, stdout. exec.Cmd's own pipe helpers hand their parent ends to Wait, which closes them the moment the child exits and races whoever is still draining; owning both ends here keeps each parent end open until its reader sees EOF.
func (*Process) Close ¶
Close closes stdin and stdout, allows the stderr copier a bounded drain, then closes stderr and joins the copier. Closing the parent end ends a read held open by a live child or descendant. An already closed pipe is not an error; concurrent Close calls are safe.
func (*Process) Done ¶
func (p *Process) Done() <-chan struct{}
Done is closed once the root process has been reaped.
func (*Process) Kill ¶
Kill sends SIGKILL to the process group and begins reaping the root, so a killed child never lingers as a zombie.
func (*Process) Shutdown ¶
Shutdown signals the process group with SIGTERM, waits up to grace, then sends SIGKILL and waits for the root to exit or ctx to end.
func (*Process) StderrTail ¶
StderrTail is the retained end of the child's stderr, trimmed, where a dying harness states its reason as an error line, a hint, or a stack trace. After the child has exited it waits briefly for the copier to deliver the last bytes.
func (*Process) Stdin ¶
func (p *Process) Stdin() io.WriteCloser
Stdin is the child's standard input.
func (*Process) Stdout ¶
func (p *Process) Stdout() io.ReadCloser
Stdout is the child's standard output pipe, or nil when the request sent stdout to a file.
type Request ¶
type Request struct {
Executable string
Args []string
Env []string
Dir string
// Stdout, when set, is the file the child writes its standard output to
// instead of a pipe; Process.Stdout is then nil. The caller owns the file.
Stdout *os.File
}
Request describes one harness launch.
type SeedFileError ¶
type SeedFileError struct {
Name string
}
SeedFileError reports an invalid or unwritable seed file; the root package maps it to the uniform unsupported error naming seedFiles.
func (*SeedFileError) Error ¶
func (e *SeedFileError) Error() string
type SeedFileFlag ¶
SeedFileFlag collects repeatable -seed-file <relpath>=<hostpath> values, reading each host file's contents into Files keyed by the relative path.
func (*SeedFileFlag) Set ¶
func (s *SeedFileFlag) Set(value string) error
Set parses one flag value and reads the named host file.
func (*SeedFileFlag) String ¶
func (s *SeedFileFlag) String() string