process

package
v0.1.1 Latest Latest
Warning

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

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

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func ForwardedSignals

func ForwardedSignals() []os.Signal

ForwardedSignals are the signals a sibling's command binary turns into cancellation of its serving context.

func LaunchFailure

func LaunchFailure(p *Process, name string, err error) error

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 Lookup

func Lookup(env []string, key string) (string, bool)

Lookup reads one variable from a KEY=value list.

func ResolveExecutable

func ResolveExecutable(path string, env []string) (string, error)

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

func ScratchDir(parent, vendor, purpose string) (string, error)

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

func ScratchPath(parent, vendor, purpose, name string) (string, error)

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

func ValidateExtraPathDirs(dirs []string) error

ValidateExtraPathDirs refuses an entry that is empty, relative, or contains the platform list separator.

func ValidateNames

func ValidateNames(env map[string]string) error

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

func ValidateOptionalAbsolutePath(path string) error

ValidateOptionalAbsolutePath accepts an unset path and refuses a relative one. It guards the home and scratch path options.

func WriteSeedFiles

func WriteSeedFiles(dir string, files map[string]string) error

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.

func LockFile

func LockFile(path string) (*FileLock, error)

LockFile holds an exclusive nonblocking lock until the returned lock is closed. The lock file stays in place so every contender uses the same inode.

func (*FileLock) Close

func (l *FileLock) Close() error

Close releases the lock explicitly before closing its descriptor. A child between fork and exec may still hold an inherited descriptor to this file.

type NameError

type NameError struct {
	Key string
}

NameError reports an environment entry that cannot be a variable.

func (*NameError) Error

func (e *NameError) Error() string

type PathDirError

type PathDirError struct {
	Index int
	Dir   string
}

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

func Start(ctx context.Context, request Request) (*Process, error)

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

func (p *Process) Close() error

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

func (p *Process) Kill() error

Kill sends SIGKILL to the process group and begins reaping the root, so a killed child never lingers as a zombie.

func (*Process) Shutdown

func (p *Process) Shutdown(ctx context.Context, grace time.Duration) error

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

func (p *Process) StderrTail() string

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.

func (*Process) Wait

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

Wait blocks until the root process exits. Cancelling ctx detaches this caller and does not affect the process.

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 Result

type Result struct {
	ExitCode int
	Signal   int
}

Result describes a terminal process.

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

type SeedFileFlag struct {
	Files map[string]string
}

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

Jump to

Keyboard shortcuts

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