process

package
v0.1.0-preview.7 Latest Latest
Warning

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

 Go to latest Published: Aug 11, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package process defines provider-neutral executable resolution and process launch contracts used by compiled tools and daemon applications.

The package describes lookup intent, process intent, verified executable ownership, and child ownership. VerifyExecutable opens and hashes one exact executable object without resolving or launching it. On systems that cannot execute a held descriptor, MaterializeForLaunch creates and reverifies an exact private snapshot while preserving explicit lease ownership. Platform path resolution, launch, process-tree containment, and resource joining remain injected implementations. In particular, this package does not claim that an operating system can universally contain descendants.

@import { NamedInterface } from "github.com/spice-framework/spice/annotation/modulith" @NamedInterface("process")

Index

Constants

View Source 
const (
	OutcomeExited   OutcomeKind = "exited"
	OutcomeSignaled OutcomeKind = "signaled"
	OutcomeUnknown  OutcomeKind = "unknown"

	// MaximumExitCode preserves every unsigned 32-bit Windows exit code while
	// also covering Unix exit statuses.
	MaximumExitCode int64 = 1<<32 - 1
)
View Source 
const (
	// MaximumArguments bounds the number of discrete child arguments.
	MaximumArguments = 4096
	// MaximumEnvironment bounds the number of exact child environment entries.
	MaximumEnvironment = 4096
	// MaximumCapabilities bounds security-relevant capability metadata.
	MaximumCapabilities = 128
	// MaximumValueBytes bounds one path, argument, or environment entry.
	MaximumValueBytes = 1 << 20
	// MaximumSpecBytes bounds all copied string data in one specification.
	MaximumSpecBytes = 4 << 20
)

Variables

This section is empty.

Functions

func NewFailure 

func NewFailure(operation Operation, cause error) error

NewFailure returns nil for a nil cause and otherwise creates a redacted typed failure. Unknown operations are represented safely as an empty Operation rather than copied into human-facing output.

Types

type Config 

type Config struct {
	Executable       string
	Arguments        []string
	WorkingDirectory string
	Environment      []string
	Stdin            io.Reader
	Stdout           io.Writer
	Stderr           io.Writer
	Capabilities     []tool.Capability
}

Config is copied and validated by NewSpec. Arguments exclude argv[0]. Environment entries use the ordinary name=value representation. An empty environment is explicit; all three streams must be non-nil.

type DigestError 

type DigestError struct {
	// contains filtered or unexported fields
}

DigestError reports an invalid executable digest without retaining or formatting the caller-supplied value.

func (*DigestError) Error 

func (failure *DigestError) Error() string

func (*DigestError) Format 

func (failure *DigestError) Format(state fmt.State, _ rune)

func (*DigestError) MarshalJSON 

func (failure *DigestError) MarshalJSON() ([]byte, error)

func (*DigestError) Problem 

func (failure *DigestError) Problem() DigestProblem

type DigestProblem 

type DigestProblem string

DigestProblem classifies a secret-safe SHA-256 validation failure. 

const (
	DigestProblemMalformed DigestProblem = "malformed"
	DigestProblemZero      DigestProblem = "zero"
)

type ExecutableLease 

type ExecutableLease struct {
	// contains filtered or unexported fields
}

ExecutableLease holds one verified executable object open across process launch. The lease binds an immutable canonical path and expected digest to a platform file identity. Close is idempotent and concurrency-safe.

func VerifyExecutable 

func VerifyExecutable(
	ctx context.Context,
	path string,
	expected SHA256,
) (*ExecutableLease, error)

VerifyExecutable opens and hashes one canonical absolute executable before any child is started. It performs no PATH lookup, shell invocation, network access, or dependency resolution.

func (*ExecutableLease) Close 

func (lease *ExecutableLease) Close() error

Close releases the held executable object. A nil or already-closed lease is harmless. Callers must not close a live child's lease before containment is proved.

func (*ExecutableLease) Digest 

func (lease *ExecutableLease) Digest() SHA256

Digest returns the immutable expected executable digest.

func (*ExecutableLease) DuplicateForLaunch 

func (lease *ExecutableLease) DuplicateForLaunch() (*os.File, error)

DuplicateForLaunch returns a caller-owned duplicate of the verified file object. A trusted native launcher uses this handle for exact-image execution on platforms that support descriptor-backed exec. The lease remains owned by its caller and must outlive process containment.

func (*ExecutableLease) Format 

func (lease *ExecutableLease) Format(state fmt.State, _ rune)

func (*ExecutableLease) GoString 

func (*ExecutableLease) GoString() string

func (*ExecutableLease) LogValue 

func (lease *ExecutableLease) LogValue() slog.Value

func (*ExecutableLease) MarshalJSON 

func (lease *ExecutableLease) MarshalJSON() ([]byte, error)

func (*ExecutableLease) MaterializeForLaunch 

func (lease *ExecutableLease) MaterializeForLaunch(ctx context.Context) (*MaterializedExecutable, error)

MaterializeForLaunch copies bytes only from the verified file object into a newly created process-owned directory, synchronizes and closes the writer, and verifies the exact expected digest again before returning. It performs no PATH lookup and never reopens the configured source pathname.

func (*ExecutableLease) Path 

func (lease *ExecutableLease) Path() string

Path returns the immutable canonical path whose file object was verified.

func (*ExecutableLease) Recheck 

func (lease *ExecutableLease) Recheck(ctx context.Context) error

Recheck reopens the configured path and proves it still resolves to the same platform file identity and content digest. Native launchers use it before a suspended child can execute where descriptor-backed exec is unavailable; callers may also retain it as defense-in-depth after launch.

func (*ExecutableLease) String 

func (*ExecutableLease) String() string

func (*ExecutableLease) ValidateSpec 

func (lease *ExecutableLease) ValidateSpec(spec Spec) error

ValidateSpec proves that a child specification selects the leased path. It deliberately does not relax or reconstruct the independently validated Spec.

type ExecutableResolver 

type ExecutableResolver interface {
	Resolve(context.Context, Lookup) (string, error)
}

ExecutableResolver resolves natural executable names and relative paths to the exact lexically canonical absolute executable required by Spec. Resolve's context bounds only the lookup. Implementations must use only Lookup's working directory and environment, perform no hidden network access, and return failures through NewFailure with OperationResolve. The caller must pass the returned path through NewSpec before launch.

type Failure 

type Failure struct {
	// contains filtered or unexported fields
}

Failure wraps an implementation failure while keeping its formatted and serialized form free of command, path, environment, and platform details. Unwrap preserves cancellation and implementation-specific error identity for deliberate programmatic inspection.

func (*Failure) Error 

func (failure *Failure) Error() string

func (*Failure) Format 

func (failure *Failure) Format(state fmt.State, _ rune)

func (*Failure) MarshalJSON 

func (failure *Failure) MarshalJSON() ([]byte, error)

func (*Failure) Operation 

func (failure *Failure) Operation() Operation

func (*Failure) Retryable 

func (failure *Failure) Retryable() bool

Retryable delegates explicit retry classification to the wrapped cause. An unclassified failure remains retryable so a failed containment observation cannot silently surrender process ownership.

func (*Failure) Unwrap 

func (failure *Failure) Unwrap() error

type Launcher 

type Launcher interface {
	Start(context.Context, Spec) (Process, error)
}

Launcher is an injected provider-neutral process constructor. Start's context bounds launch only; a successfully returned Process has an independent lifetime. When Start returns both a Process and an error, ownership of that Process still transfers to the caller and must be joined. Implementations must never return a nil Process with a nil error.

type LauncherFunc 

type LauncherFunc func(context.Context, Spec) (Process, error)

LauncherFunc adapts an ordinary function for constructor injection and ordered policy decoration.

func (LauncherFunc) Start 

func (launcher LauncherFunc) Start(ctx context.Context, spec Spec) (Process, error)

type Lookup 

type Lookup struct {
	// contains filtered or unexported fields
}

Lookup is immutable executable-resolution intent. RequestedExecutable may be a natural platform name, a relative path interpreted from WorkingDirectory, or an absolute path. Environment is the exact explicit child environment; resolvers may use its platform search variables but never ambient process state. Lookup performs no filesystem or network access.

func NewLookup 

func NewLookup(
	requestedExecutable,
	workingDirectory string,
	environment []string,
) (Lookup, error)

NewLookup validates and defensively copies executable-resolution intent.

func (Lookup) Clone 

func (lookup Lookup) Clone() Lookup

Clone returns an independently backed immutable value.

func (Lookup) Environment 

func (lookup Lookup) Environment() []string

func (Lookup) Format 

func (Lookup) Format(state fmt.State, _ rune)

func (Lookup) GoString 

func (Lookup) GoString() string

func (Lookup) MarshalJSON 

func (Lookup) MarshalJSON() ([]byte, error)

func (Lookup) RequestedExecutable 

func (lookup Lookup) RequestedExecutable() string

func (Lookup) String 

func (Lookup) String() string

func (Lookup) Validate 

func (lookup Lookup) Validate() error

Validate rejects a zero or corrupted lookup without performing I/O.

func (Lookup) WorkingDirectory 

func (lookup Lookup) WorkingDirectory() string

type LookupError 

type LookupError struct {
	// contains filtered or unexported fields
}

LookupError identifies a secret-safe executable-lookup input failure.

func (*LookupError) Error 

func (failure *LookupError) Error() string

func (*LookupError) Field 

func (failure *LookupError) Field() string

func (*LookupError) Index 

func (failure *LookupError) Index() int

func (*LookupError) MarshalJSON 

func (failure *LookupError) MarshalJSON() ([]byte, error)

func (*LookupError) Problem 

func (failure *LookupError) Problem() SpecProblem

type MaterializedExecutable 

type MaterializedExecutable struct {
	// contains filtered or unexported fields
}

MaterializedExecutable is a private, digest-reverified executable snapshot. It supports platforms such as Darwin that cannot execute an already-open descriptor. Close keeps its verification lease until the caller has proved child containment, then removes exactly the snapshot and its private directory.

func (*MaterializedExecutable) Close 

func (executable *MaterializedExecutable) Close() error

Close releases the materialized lease, removes exactly its private file, and removes the now-empty private directory. It is idempotent and refuses to recursively delete unexpected contents.

func (*MaterializedExecutable) Format 

func (executable *MaterializedExecutable) Format(state fmt.State, _ rune)

func (*MaterializedExecutable) GoString 

func (*MaterializedExecutable) GoString() string

func (*MaterializedExecutable) LogValue 

func (executable *MaterializedExecutable) LogValue() slog.Value

func (*MaterializedExecutable) MarshalJSON 

func (executable *MaterializedExecutable) MarshalJSON() ([]byte, error)

func (*MaterializedExecutable) Path 

func (executable *MaterializedExecutable) Path() string

Path returns the absolute private path selected for launch. It is intended only as the executable argument of a trusted VerifiedLauncher.

func (*MaterializedExecutable) Recheck 

func (executable *MaterializedExecutable) Recheck(ctx context.Context) error

Recheck proves that the private launch path still identifies the exact materialized object and digest.

func (*MaterializedExecutable) String 

func (*MaterializedExecutable) String() string

type Operation 

type Operation string

Operation classifies a provider-neutral process operation. 

const (
	OperationLaunch      Operation = "launch"
	OperationResolve     Operation = "resolve"
	OperationResult      Operation = "result"
	OperationRequestStop Operation = "request_stop"
	OperationForceKill   Operation = "force_kill"
	OperationWait        Operation = "wait"
)

type Outcome 

type Outcome struct {
	// contains filtered or unexported fields
}

Outcome is an immutable root-process result. It says nothing about whether descendants or platform containment resources have joined; Wait owns that separate fact.

func NewExitedOutcome 

func NewExitedOutcome(exitCode int64) (Outcome, error)

NewExitedOutcome creates an ordinary process-exit outcome.

func NewSignaledOutcome 

func NewSignaledOutcome() Outcome

NewSignaledOutcome reports termination by a platform signal or analogous forced mechanism without exposing a platform-specific signal value.

func NewUnknownOutcome 

func NewUnknownOutcome() Outcome

NewUnknownOutcome reports that the root is known to have terminated but no portable exit classification is available. Unknown is never successful.

func (Outcome) ExitCode 

func (outcome Outcome) ExitCode() (int64, bool)

func (Outcome) Kind 

func (outcome Outcome) Kind() OutcomeKind

func (Outcome) Successful 

func (outcome Outcome) Successful() bool

func (Outcome) Validate 

func (outcome Outcome) Validate() error

Validate rejects a zero or corrupted outcome.

type OutcomeError 

type OutcomeError struct {
	// contains filtered or unexported fields
}

OutcomeError is a typed, secret-safe invalid-outcome failure.

func (*OutcomeError) Error 

func (failure *OutcomeError) Error() string

func (*OutcomeError) Problem 

func (failure *OutcomeError) Problem() string

type OutcomeKind 

type OutcomeKind string

OutcomeKind classifies the provider-neutral root-process outcome.

type Process 

type Process interface {
	Done() <-chan struct{}
	Result() (Outcome, error)
	RequestStop(context.Context) error
	ForceKill(context.Context) error
	Wait(context.Context) error
}

Process owns one launched root and its implementation-defined containment resources. Done closes when the root outcome becomes stable. Result is then deterministic and returns a validated Outcome; its error is only an observation failure, never a containment/join failure.

RequestStop and ForceKill request graceful and forced termination respectively. They are concurrency-safe and idempotent after success. A failure does not poison a later retry. Wait honors its context and returns nil only when all owned descendants and containment resources are safe to release. A canceled, unclassified, or explicitly retryable Wait retains ownership and a later Wait must perform a fresh join attempt. A Wait error implementing Retryable() bool with a false result declares that repeating containment cleanup is unsafe; ownership remains for manual recovery.

type ResolverFunc 

type ResolverFunc func(context.Context, Lookup) (string, error)

ResolverFunc adapts an ordinary function for constructor injection.

func (ResolverFunc) Resolve 

func (resolver ResolverFunc) Resolve(ctx context.Context, lookup Lookup) (string, error)

type SHA256 

type SHA256 struct {
	// contains filtered or unexported fields
}

SHA256 is an immutable exact executable-content identity. Its bytes remain private so callers cannot mutate a validated digest through shared storage.

func ParseSHA256 

func ParseSHA256(value string) (SHA256, error)

ParseSHA256 accepts exactly 64 lowercase hexadecimal characters. Parsing does not accept a zero digest as a usable pin; callers must also use Validate.

func (SHA256) String 

func (digest SHA256) String() string

String returns the canonical lowercase hexadecimal digest.

func (SHA256) Validate 

func (digest SHA256) Validate() error

Validate rejects the zero value, which cannot authorize an executable.

type Spec 

type Spec struct {
	// contains filtered or unexported fields
}

Spec is immutable process intent. It performs no filesystem access and does not establish a permission or containment boundary. Capability metadata is declarative input for injected policy decorators.

func NewSpec 

func NewSpec(config Config) (Spec, error)

NewSpec validates and defensively copies one process specification.

func (Spec) Arguments 

func (spec Spec) Arguments() []string

func (Spec) Capabilities 

func (spec Spec) Capabilities() []tool.Capability

func (Spec) Clone 

func (spec Spec) Clone() Spec

Clone returns an independently backed immutable value.

func (Spec) Environment 

func (spec Spec) Environment() []string

func (Spec) Executable 

func (spec Spec) Executable() string

func (Spec) Format 

func (Spec) Format(state fmt.State, _ rune)

func (Spec) GoString 

func (Spec) GoString() string

func (Spec) MarshalJSON 

func (Spec) MarshalJSON() ([]byte, error)

func (Spec) Stderr 

func (spec Spec) Stderr() io.Writer

func (Spec) Stdin 

func (spec Spec) Stdin() io.Reader

func (Spec) Stdout 

func (spec Spec) Stdout() io.Writer

func (Spec) String 

func (Spec) String() string

String prevents command arguments, environment values, paths, or stream implementations from leaking through incidental formatting.

func (Spec) Validate 

func (spec Spec) Validate() error

Validate rejects a zero or corrupted specification without performing I/O.

func (Spec) WorkingDirectory 

func (spec Spec) WorkingDirectory() string

type SpecError 

type SpecError struct {
	// contains filtered or unexported fields
}

SpecError identifies a field and optional element without including its potentially sensitive value. Index returns -1 for a scalar field.

func (*SpecError) Error 

func (failure *SpecError) Error() string

func (*SpecError) Field 

func (failure *SpecError) Field() string

func (*SpecError) Index 

func (failure *SpecError) Index() int

func (*SpecError) MarshalJSON 

func (failure *SpecError) MarshalJSON() ([]byte, error)

func (*SpecError) Problem 

func (failure *SpecError) Problem() SpecProblem

type SpecProblem 

type SpecProblem string

SpecProblem classifies one secret-safe specification validation failure. 

const (
	ProblemRequired          SpecProblem = "required"
	ProblemNotAbsolute       SpecProblem = "not_absolute"
	ProblemNotCanonical      SpecProblem = "not_canonical"
	ProblemInvalidUTF8       SpecProblem = "invalid_utf8"
	ProblemContainsNUL       SpecProblem = "contains_nul"
	ProblemMalformed         SpecProblem = "malformed"
	ProblemDuplicate         SpecProblem = "duplicate"
	ProblemTooMany           SpecProblem = "too_many"
	ProblemTooLarge          SpecProblem = "too_large"
	ProblemMissingCapability SpecProblem = "missing_capability"
)

type VerificationError 

type VerificationError struct {
	// contains filtered or unexported fields
}

VerificationError preserves cancellation and platform error identity for deliberate inspection. Its formatted and serialized forms never include a path, digest, environment entry, file identity, or platform error text.

func (*VerificationError) Error 

func (failure *VerificationError) Error() string

func (*VerificationError) Format 

func (failure *VerificationError) Format(state fmt.State, _ rune)

func (*VerificationError) LogValue 

func (failure *VerificationError) LogValue() slog.Value

func (*VerificationError) MarshalJSON 

func (failure *VerificationError) MarshalJSON() ([]byte, error)

func (*VerificationError) Operation 

func (failure *VerificationError) Operation() VerificationOperation

func (*VerificationError) Unwrap 

func (failure *VerificationError) Unwrap() error

type VerificationOperation 

type VerificationOperation string

VerificationOperation identifies one secret-safe verified-executable step. 

const (
	VerificationOperationValidate    VerificationOperation = "validate"
	VerificationOperationOpen        VerificationOperation = "open"
	VerificationOperationInspect     VerificationOperation = "inspect"
	VerificationOperationHash        VerificationOperation = "hash"
	VerificationOperationDuplicate   VerificationOperation = "duplicate"
	VerificationOperationMaterialize VerificationOperation = "materialize"
	VerificationOperationRecheck     VerificationOperation = "recheck"
	VerificationOperationClose       VerificationOperation = "close"
)

type VerifiedLauncher 

type VerifiedLauncher interface {
	StartVerified(context.Context, *ExecutableLease, Spec) (Process, error)
}

VerifiedLauncher starts a child from a previously verified executable lease. Implementations must validate the Spec against the lease and must prevent a pathname substitution from selecting a different image. On a partial launch, Process ownership follows the same rules as Launcher.Start.

This interface is intentionally separate from Launcher: a security-sensitive caller must not silently fall back to pathname-only launch.

type VerifiedLauncherFunc 

type VerifiedLauncherFunc func(context.Context, *ExecutableLease, Spec) (Process, error)

VerifiedLauncherFunc adapts a verified launch function for constructor injection and conformance tests.

func (VerifiedLauncherFunc) StartVerified 

func (launcher VerifiedLauncherFunc) StartVerified(
	ctx context.Context,
	lease *ExecutableLease,
	spec Spec,
) (Process, error)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.