Documentation
¶
Overview ¶
Package procutil provides shared process helpers for Compozy runtime components.
Index ¶
- Constants
- Variables
- func AccountLoginShell(ctx context.Context) (string, error)
- func Alive(pid int) bool
- func ConfigureCommandProcessGroup(cmd *exec.Cmd)
- func ConfigureCommandSession(cmd *exec.Cmd)
- func ConfigureCommandTerminalSession(cmd *exec.Cmd)
- func CreationProcessToken(pid int) string
- func CurrentProcessNiceness() (int, error)
- func EnrichProcesses(ctx context.Context, rows []ScannedProcess)
- func FilteredDaemonEnv(base []string) []string
- func InternalHandoffEnvName(name string) bool
- func IsProcessMissingError(err error) bool
- func IsolatedDaemonEnv(base []string) []string
- func KillCommandProcessGroupAndWait(cmd *exec.Cmd, timeout time.Duration) error
- func KillProcessGroupIDAndWait(pgid int, timeout time.Duration) error
- func MatchesObservedStartTime(observed, startedAt time.Time) bool
- func MatchesProcessIdentity(pid int, startedAt time.Time, token string) (bool, error)
- func MatchesStartTime(pid int, startedAt time.Time) bool
- func OwnsFileLock(pid int, path string) (_ bool, returnErr error)
- func ProcessGroupNiceness(pgid int) (int, error)
- func ProcessToken(pid int) (string, error)
- func RegisterCommandProcessGroup(_ *exec.Cmd) error
- func ResolveLoginShellPath(ctx context.Context, environment []string, options LoginShellPathOptions) (string, error)
- func SensitiveEnvName(name string) bool
- func SetProcessGroupNiceness(pgid int, niceness int) error
- func Signal(pid int, sig syscall.Signal) error
- func SignalCommandProcessGroup(cmd *exec.Cmd, sig syscall.Signal) error
- func SignalProcessGroupID(pgid int, sig syscall.Signal) error
- func SignalProcessGroupIDStrict(pgid int, sig syscall.Signal) error
- func StartWithNiceness(niceness int, start func() error) (priorityErr, startErr error)
- func StartedAt(pid int) (time.Time, error)
- func VerifyProcessExit(pid int, startedAt time.Time) (bool, error)
- func WaitForCommandProcessGroupExit(cmd *exec.Cmd, timeout time.Duration) error
- func WaitForProcessGroupIDExit(pgid int, timeout time.Duration) error
- func WatchParentExit(ctx context.Context, poll time.Duration, onExit func())
- func WithoutInternalHandoffEnv(env []string) []string
- type DetachedLaunchRequest
- type DetachedProcess
- type LoginShellPathOptions
- type ProcessSnapshot
- type ProcessTermination
- type ScannedProcess
Constants ¶
const InternalHandoffEnvPrefix = "COMPOZY_INTERNAL_"
InternalHandoffEnvPrefix marks variables that carry one-shot handoff state between a CompozyOS process and the specific process it launches. They must never reach ordinary children.
Variables ¶
ErrAccountShellUnavailable reports that the account database names no usable login shell.
var ErrProcessIdentityGone = errors.New("procutil: process identity is gone")
ErrProcessIdentityGone distinguishes a vanished process from unreadable identity data.
Functions ¶
func AccountLoginShell ¶
AccountLoginShell returns the login shell recorded for the current user's account.
A daemon started by launchd, the desktop app, or a service manager inherits whatever SHELL its launcher had, which is not necessarily the shell the operator chose with chsh. The account database (directory services on macOS, passwd/NSS elsewhere) is the authority for that choice.
func ConfigureCommandProcessGroup ¶
ConfigureCommandProcessGroup starts the command in its own process group so callers can signal and observe the full descendant tree.
func ConfigureCommandSession ¶
ConfigureCommandSession starts the command in a new Unix session.
func ConfigureCommandTerminalSession ¶
ConfigureCommandTerminalSession starts the command in a new session with a controlling terminal.
func CreationProcessToken ¶
CreationProcessToken preserves timestamp identity when kernel identity is unavailable at creation. Existing tokenized records must still propagate lookup errors instead of downgrading identity.
func CurrentProcessNiceness ¶
CurrentProcessNiceness reports the niceness of the calling process.
func EnrichProcesses ¶
func EnrichProcesses(ctx context.Context, rows []ScannedProcess)
EnrichProcesses adds best-effort cwd and listener metadata to already attributed rows.
func FilteredDaemonEnv ¶
FilteredDaemonEnv returns process environment entries safe to pass to child processes. It drops credential-shaped variables and internal handoff variables.
func InternalHandoffEnvName ¶
InternalHandoffEnvName reports whether name is an internal handoff variable.
func IsProcessMissingError ¶
IsProcessMissingError reports whether a signal failed because its target no longer exists.
func IsolatedDaemonEnv ¶
IsolatedDaemonEnv returns only the fixed operational environment allowlist needed to launch local subprocesses. It intentionally drops all non-allowlisted daemon variables, including provider CLI credentials.
func KillCommandProcessGroupAndWait ¶
KillCommandProcessGroupAndWait forcefully terminates any remaining members of the command's process group, then waits for the group to disappear.
func KillProcessGroupIDAndWait ¶
KillProcessGroupIDAndWait forcefully terminates any remaining members of a process group.
func MatchesObservedStartTime ¶
MatchesObservedStartTime compares persisted and kernel timestamps with launcher skew tolerance.
func MatchesProcessIdentity ¶
MatchesProcessIdentity prefers a persisted kernel identity when available.
func MatchesStartTime ¶
MatchesStartTime reports whether pid currently belongs to a process whose observed start time matches the recorded value closely enough to account for launcher-vs-kernel timestamp skew.
func OwnsFileLock ¶
OwnsFileLock verifies Linux kernel lock ownership independently of wall-clock drift.
func ProcessGroupNiceness ¶
ProcessGroupNiceness reports the niceness of the least-niced member of the process group.
func ProcessToken ¶
ProcessToken identifies a process without converting kernel ticks to wall time.
func RegisterCommandProcessGroup ¶
RegisterCommandProcessGroup keeps Unix parity with Windows job registration.
func ResolveLoginShellPath ¶
func ResolveLoginShellPath( ctx context.Context, environment []string, options LoginShellPathOptions, ) (string, error)
ResolveLoginShellPath returns the PATH produced by the operator's login shell.
func SensitiveEnvName ¶
SensitiveEnvName reports whether an environment variable name commonly carries credentials.
func SetProcessGroupNiceness ¶
SetProcessGroupNiceness lowers the CPU scheduling priority of every process in the process group to at least niceness. Descendants forked after the call returns inherit the value. A child whose fork is still in flight during the call can keep its parent's previous niceness: the kernel copies the value before the child joins the group, and setpriority(PRIO_PGRP) only reaches joined members. No userspace re-check can observe that child, so callers that need complete coverage must apply niceness before the group can fork (Linux launch paths use StartWithNiceness). Unprivileged callers can only raise niceness, so a group already at or above niceness (for example under a niced daemon) is left unchanged instead of failing with a permission error.
func SignalCommandProcessGroup ¶
SignalCommandProcessGroup delivers sig to the command's process group.
func SignalProcessGroupID ¶
SignalProcessGroupID delivers sig to the process group identified by pgid.
func SignalProcessGroupIDStrict ¶
SignalProcessGroupIDStrict reports when no member remains to receive the signal.
func StartWithNiceness ¶
StartWithNiceness starts on a disposable Linux thread so the child inherits priority before exec.
func VerifyProcessExit ¶
VerifyProcessExit checks whether the recorded process identity is gone. A reused PID proves the original process exited; a failed lookup does not.
func WaitForCommandProcessGroupExit ¶
WaitForCommandProcessGroupExit blocks until the command's process group no longer exists, which ensures descendants are gone before returning.
func WaitForProcessGroupIDExit ¶
WaitForProcessGroupIDExit blocks until the process group identified by pgid no longer exists.
func WatchParentExit ¶
WatchParentExit calls onExit once if this process is reparented because its original parent exited, then returns; it stops early when ctx is done. It lets a child self-terminate when its launcher dies abruptly (SIGKILL, test timeout, Ctrl-C) — Darwin has no Pdeathsig. On Windows the kill-on-close job object (RegisterCommandProcessGroup) handles this, so that build is a no-op.
func WithoutInternalHandoffEnv ¶
WithoutInternalHandoffEnv returns a copy of env without internal handoff variables.
Types ¶
type DetachedLaunchRequest ¶
DetachedLaunchRequest describes one detached process launch with log capture.
type DetachedProcess ¶
type DetachedProcess struct {
// contains filtered or unexported fields
}
DetachedProcess wraps a detached child process whose stderr/stdout were appended to a log file.
func SpawnDetachedLoggedProcess ¶
func SpawnDetachedLoggedProcess( ctx context.Context, req DetachedLaunchRequest, ) (*DetachedProcess, error)
SpawnDetachedLoggedProcess launches one detached child process whose stdout/stderr are appended to req.LogPath.
func (*DetachedProcess) Done ¶
func (p *DetachedProcess) Done() <-chan struct{}
Done closes after the detached child has been reaped.
func (*DetachedProcess) PID ¶
func (p *DetachedProcess) PID() int
PID reports the launched process id.
func (*DetachedProcess) Terminate ¶
func (p *DetachedProcess) Terminate() error
Terminate stops the detached child when it has not exited yet.
func (*DetachedProcess) Wait ¶
func (p *DetachedProcess) Wait() error
Wait blocks until the detached process exits and attaches recent log output to failures.
type LoginShellPathOptions ¶
type LoginShellPathOptions struct {
Timeout time.Duration
MaxOutputBytes int
// AccountShell resolves the account's recorded login shell. Nil uses AccountLoginShell.
AccountShell func(context.Context) (string, error)
}
LoginShellPathOptions bounds login shell PATH resolution.
type ProcessSnapshot ¶
type ProcessSnapshot struct {
Supported bool
ScannedAt time.Time
Duration time.Duration
Processes []ScannedProcess
}
func ScanProcessTree ¶
func ScanProcessTree(ctx context.Context) (ProcessSnapshot, error)
ScanProcessTree is the inexpensive lineage pass used during active tool calls.
func ScanProcesses ¶
func ScanProcesses(ctx context.Context) (ProcessSnapshot, error)
type ProcessTermination ¶
func TerminateObservedProcess ¶
func TerminateObservedProcess(ctx context.Context, target ScannedProcess, grace time.Duration) ProcessTermination
TerminateObservedProcess accepts a durable lineage identity verified by the session process service. Lineage authority permits only an individual PID signal, never an inferred group signal.
func TerminateScannedProcess ¶
func TerminateScannedProcess(ctx context.Context, target ScannedProcess, grace time.Duration) ProcessTermination
TerminateScannedProcess never uses the launch-time skew tolerance for user-selected process identities.
type ScannedProcess ¶
type ScannedProcess struct {
PID, PPID, PGID int
StartedAt time.Time
KernelToken string
SessionID, Home, Profile, Workspace string
Argv0, Command, CWD string
Ports []int
Zombie bool
}
ScannedProcess retains only attribution markers, never the complete environment.
func InspectProcess ¶
func InspectProcess(pid int) (ScannedProcess, error)
Source Files
¶
- account_shell.go
- account_shell_unix.go
- detached.go
- detached_unix.go
- env.go
- launch_priority_linux.go
- login_shell_path.go
- parent_watch_unix.go
- process_group_unix.go
- process_lock.go
- process_lock_linux.go
- process_priority_unix.go
- process_started_at.go
- process_started_at_unix.go
- process_token_linux.go
- procutil.go
- scan.go
- scan_linux.go
- scan_terminate_unix.go