Documentation
¶
Overview ¶
Package process provides an explicit, bounded local process adapter.
The package owns portable command/result, cancellation, timeout and output capture semantics. It does not authorize commands, provide a sandbox, choose an approval policy or decide which signals may be sent. Hosts must perform those checks before calling the local adapter.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Command ¶
type Command struct {
Command string
Workdir string
Env map[string]string
Timeout time.Duration
MaxOutputBytes int
}
Command describes one non-interactive shell command. Workdir may be relative to LocalOptions.Root or an absolute path within that root. Env entries extend the current process environment for this command only.
type CommandResult ¶
type CommandResult struct {
Command string
Workdir string
ExitCode int
Stdout string
Stderr string
Duration time.Duration
StdoutTruncated bool
StderrTruncated bool
Status string
TimedOut bool
Cancelled bool
Interrupted bool
Termination *Termination
}
CommandResult is the bounded, structured result of Run. A non-zero process exit code is a result, not an adapter error. An adapter-owned timeout is also returned as a timed_out result so callers can present partial output.
type Error ¶
Error is a typed local adapter error. Cause remains available through errors.Is/errors.As; Message is safe for developer-facing diagnostics but must not be treated as an authorization decision.
type ErrorCode ¶
type ErrorCode string
ErrorCode is a stable, programmatic failure category.
const ( // ErrorCodeInvalidCommand marks an empty command. ErrorCodeInvalidCommand ErrorCode = "invalid_command" // ErrorCodeWorkdirResolution marks a workdir outside the configured root. ErrorCodeWorkdirResolution ErrorCode = "workdir_resolution_failed" // ErrorCodeCommandFailed marks a command that could not be started or waited. ErrorCodeCommandFailed ErrorCode = "command_failed" // ErrorCodeContextCanceled marks caller cancellation. ErrorCodeContextCanceled ErrorCode = "context_canceled" // ErrorCodeContextDeadlineExceeded marks a caller-owned deadline. ErrorCodeContextDeadlineExceeded ErrorCode = "context_deadline_exceeded" // ErrorCodeProcessListFailed marks a local process-list failure. ErrorCodeProcessListFailed ErrorCode = "process_list_failed" // ErrorCodeOutputLimitExceeded marks a process-list capture beyond its bound. ErrorCodeOutputLimitExceeded ErrorCode = "output_limit_exceeded" )
type ListRequest ¶
type ListRequest struct {
Limit int
}
ListRequest configures read-only local process inspection.
type ListResult ¶
ListResult contains normalized non-empty process listing lines.
type LocalAdapter ¶
type LocalAdapter struct {
// contains filtered or unexported fields
}
LocalAdapter performs explicit local side effects. Constructing it does not execute a command and does not read credentials or provider configuration.
func NewLocalAdapter ¶
func NewLocalAdapter(options LocalOptions) *LocalAdapter
NewLocalAdapter constructs an opt-in local adapter. Root defaults to the current directory and is resolved again for every call so symlink escapes are rejected at the side-effect boundary.
func (*LocalAdapter) List ¶
func (a *LocalAdapter) List(ctx context.Context, request ListRequest) (ListResult, error)
List returns a bounded local process listing. It does not start, stop or signal a process.
func (*LocalAdapter) Run ¶
func (a *LocalAdapter) Run(ctx context.Context, request Command) (CommandResult, error)
Run executes one bounded foreground command. It never starts a detached or background process. Callers must authorize the command before invoking Run.
type LocalOptions ¶
type LocalOptions struct {
Root string
DefaultTimeout time.Duration
MaxOutputBytes int
ProcessOutputBytes int
}
LocalOptions configures the opt-in local adapter. Root is a containment boundary, not an OS sandbox. MaxOutputBytes and ProcessOutputBytes are hard adapter ceilings; individual calls may request a lower command-output bound.
Source Files