proc

type ExitValue struct {
	// Code is the exit status (0–255) when the process exited normally; it is -1
	// when the process was terminated by a signal.
	Code int
	// Signal is the signal that terminated the process, or the zero Signal when
	// it exited normally.
	Signal Signal
	// Signaled reports whether the process was terminated by a signal rather
	// than exiting on its own.
	Signaled bool
	// UserTime is the CPU time spent in user mode.
	UserTime time.Duration
	// SystemTime is the CPU time spent in kernel mode on the process's behalf.
	SystemTime time.Duration
	// MaxRSS is the peak resident set size in kilobytes, as reported by wait4's
	// rusage; it is 0 when the platform does not supply it.
	MaxRSS int64
}

type Group interface {
	// SetMemoryMax writes memory.max (systemd MemoryMax=); a negative value
	// means "max" (no limit).
	SetMemoryMax(bytes int64) error
	// SetCPUMax writes cpu.max as "quota period" (systemd CPUQuota=); a negative
	// quota means "max".
	SetCPUMax(quota, period int64) error
	// SetPidsMax writes pids.max (systemd TasksMax=); a negative value means
	// "max".
	SetPidsMax(n int64) error
	// SetIOMax writes one io.max line verbatim (systemd IO*Max=), e.g.
	// "8:0 rbps=1048576".
	SetIOMax(spec string) error
	// Add moves the process pid into this group by writing cgroup.procs.
	Add(pid int) error
	// Kill atomically SIGKILLs every process in the group by writing "1" to
	// cgroup.kill (systemd KillMode=control-group; kernel >= 5.14). Unlike a
	// process-group kill, nothing escapes — a member that called setsid is still
	// in the control group. Returns UnsupportedPlatform when cgroup.kill is absent
	// (older kernels), so callers can fall back to SignalGroup.
	Kill() error
	// Freeze quiesces the whole group by writing "1" to cgroup.freeze (kernel
	// >= 5.2), stopping every member so a consistent signal sweep or snapshot can
	// run. Returns UnsupportedPlatform when cgroup.freeze is absent. Idempotent.
	Freeze() error
	// Thaw resumes a frozen group by writing "0" to cgroup.freeze. Returns
	// UnsupportedPlatform when cgroup.freeze is absent. Idempotent.
	Thaw() error
	// Delete removes the (empty) control group; callers move processes out first.
	Delete() error
}

type LimitValue struct {
	// Soft is the enforced limit; it must not exceed Hard.
	Soft uint64
	// Hard is the ceiling for Soft; raising it typically requires privilege.
	Hard uint64
}

type Listener interface {
	// Recv blocks until the next datagram arrives and returns it parsed, with the
	// sender PID verified by the kernel. It returns a typed error on a malformed
	// datagram or once the listener is closed.
	Recv() (NotificationValue, error)
	// Close releases the socket and unblocks any in-flight Recv.
	Close() error
}

type MemoryLimitValue struct {
	// Allowance is the tightest cgroup memory cap governing this process, in
	// bytes, or zero when none was read.
	Allowance int64
	// Limit is the Go soft memory limit derived from Allowance, in bytes, or
	// zero when no limit was applied.
	Limit int64
	// Source names what decided the outcome.
	Source MemorySource
}

type MemorySource uint8

type NotificationValue struct {
	// State is the raw NAME=value field set from the datagram (READY, STATUS,
	// MAINPID, WATCHDOG, RELOADING, STOPPING, …), preserved verbatim.
	State map[string]string
	// Status is the free-text STATUS= line, empty when absent.
	Status string
	// MainPID is the PID advertised by MAINPID=, or 0 when absent.
	MainPID int
	// SenderPID is the sending process's PID as verified by the kernel via
	// SO_PASSCRED, not a value the sender can forge; 0 when credentials were
	// unavailable.
	SenderPID int
}

type Process interface {
	// PID reports the process identifier of the leader.
	PID() int
	// Wait blocks until the process exits and returns its ExitValue — the real
	// one even when a running Reaper collected the child first. It is safe
	// to call once; concurrent or repeated calls observe the same outcome. Under
	// StdioCapture it returns only after every captured byte has reached the
	// caller's writers; if a writer itself failed, the ExitValue still reports the
	// real exit status and the error is StdioCaptureFailed.
	Wait() (ExitValue, error)
	// Signal delivers sig to the leader process only.
	Signal(sig Signal) error
	// SignalGroup delivers sig to the leader's entire process group (kill(-pgid,
	// sig)), reaching forked grandchildren — the KillMode=control-group analogue.
	SignalGroup(sig Signal) error
	// Stop terminates the process group gracefully: it sends sig, waits up to
	// grace for exit, then escalates to SIGKILL. It returns when the process has
	// exited or ctx is cancelled.
	Stop(ctx context.Context, grace time.Duration, sig Signal) error
}

type Reaper interface {
	// Start begins a background SIGCHLD-driven loop that reaps children as they
	// exit. It is idempotent: a second Start while running is a no-op.
	Start()
	// Stop ends the background loop after a final draining sweep, so shutdown
	// leaves no un-reaped zombies. It is safe to call without a prior Start.
	Stop()
	// ReapOnce performs a single non-blocking sweep and reports how many
	// children were reaped. It is safe to call concurrently with the loop.
	ReapOnce() (int, error)
}

type Resource int

type Signal int

type Spec struct {
	// Path is the executable to run. Required. A value containing a path
	// separator is a file path, taken as written (a relative one is resolved
	// against Dir). A bare name — "go", "sh" — is searched in the PATH the
	// CHILD will see: the PATH entry of Env whenever Env names one (an
	// explicitly empty PATH= searches nothing), the parent's only when Env
	// names none (including when Env is nil). os/exec's rules apply: the first
	// executable in PATH order wins, and a match found only through a relative
	// entry ("." or an empty one) is refused with exec.ErrDot.
	Path string
	// Args is the full argv including argv[0]; when empty the service uses
	// [Spec.Path] — the name as written, not the resolved file — as the sole
	// argument.
	Args []string
	// Dir is the working directory; empty means inherit the parent's.
	Dir string
	// Env is the explicit environment; nil yields an empty environment, never
	// implicit inheritance, so a spawned service starts from a known state.
	Env []string

	// User is the name or numeric uid to setuid to; empty leaves the parent's.
	User string
	// Group is the name or numeric gid to setgid to; empty leaves the parent's.
	Group string
	// Groups are supplementary group names or gids (systemd SupplementaryGroups=).
	Groups []string

	// Setpgid places the child in its own process group, enabling group-kill of
	// the whole tree (systemd KillMode=control-group without cgroups).
	Setpgid bool
	// Setsid starts the child in a new session detached from the controlling tty.
	Setsid bool

	// Umask, when non-nil, is the file-creation mask applied to the child
	// (systemd UMask=).
	Umask *int
	// Nice, when non-nil, is the scheduling-priority adjustment applied to the
	// child (systemd Nice=).
	Nice *int
	// OOMScoreAdj, when non-nil, is the /proc/<pid>/oom_score_adj value applied
	// to the child (systemd OOMScoreAdjust=).
	OOMScoreAdj *int
	// Rlimits are per-resource soft/hard limits applied post-fork, pre-exec
	// (systemd Limit*=); resources unsupported on the platform surface a typed
	// error rather than silently no-op.
	Rlimits map[Resource]LimitValue

	// CgroupPath, when non-empty, is an already-created cgroup v2 directory the
	// child is placed into BEFORE exec, so controller limits (MemoryMax/TasksMax/
	// …) apply from its first instruction — closing the unconfined window that a
	// post-spawn Group.Add(pid) leaves open (systemd places the unit's payload in
	// its cgroup the same way). The service writes the child's pid to
	// <CgroupPath>/cgroup.procs in the pre-exec trampoline. Linux-only: a non-empty
	// value on any other GOOS surfaces UnsupportedPlatform; a path that is missing,
	// not a cgroup v2 directory, or not delegated surfaces a typed cgroup error
	// rather than spawning unconfined.
	CgroupPath string

	// Stdio selects how the child's standard streams are wired: StdioInherit
	// (default — share the parent's), StdioNull (discard to the null device), or
	// StdioCapture (use the Stdout/Stderr/Stdin members below). systemd
	// StandardOutput=/StandardError=/StandardInput= is the analogue.
	Stdio StdioMode
	// Stdout, when Stdio is StdioCapture, receives the child's standard output;
	// a nil writer discards that stream to the null device.
	Stdout io.Writer
	// Stderr, when Stdio is StdioCapture, receives the child's standard error;
	// a nil writer discards that stream to the null device.
	Stderr io.Writer
	// Stdin, when Stdio is StdioCapture, is copied to the child's standard input;
	// a nil reader gives the child an immediate-EOF stdin. The reader should be
	// EOF-terminating (a buffer, file, or strings.Reader); the copier closes the
	// child's stdin at EOF and never blocks Wait.
	Stdin io.Reader

	// ExtraFiles are additional open files inherited by the child, in order,
	// starting at file descriptor 3 (after stdin/stdout/stderr). This is the
	// mechanism behind socket activation (sd_listen_fds): an activator binds
	// listening sockets and passes them here, then sets LISTEN_FDS/LISTEN_PID in
	// Env so the child finds them at fd 3..3+len-1. nil means no extra fds.
	ExtraFiles []*os.File
}

type StdioMode uint8