processhost

package
v0.1.0 Latest Latest
Warning

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

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

Documentation

Overview

Package processhost owns the project-selected supervised backend-plugin process host: lazy activation, process-model ownership, peer-gated local channels, generation invalidation, and composition BuildResult cleanup.

Platform honesty: production Windows/Darwin launch and channel factories fail closed until an approved exact-identity profile is runtime-proven. Linux provides source/compile descriptor-launch and private UDS peercred paths.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DescendantCleanupSupported

func DescendantCleanupSupported() bool

DescendantCleanupSupported reports whether the current platform profile claims native process-tree cleanup (Windows job / Linux process group). Darwin remains fail-closed.

func OwnershipKey

func OwnershipKey(model ProcessModel, artifactDigest, instanceID string) string

OwnershipKey uniquely identifies the supervised process slot.

func RuntimeChannelSupported

func RuntimeChannelSupported(p PlatformID) bool

func StopProcess

func StopProcess(p Process, gracefulTimeout time.Duration) error

StopProcess runs graceful stop, then hard kill on timeout, then exactly-once wait. Descendant/process-tree ownership is platform-specific; callers must not assume tree cleanup where the platform profile is fail-closed.

func ValidateCatalog

func ValidateCatalog(catalog EvidenceCatalog) error

Types

type ActivateRequest

type ActivateRequest struct {
	InstanceID  string
	Artifact    *trust.VerifiedArtifact
	Model       ProcessModel
	Sharing     SharingOptions
	FactoryKind string
	ConfigYAML  []byte
	Secrets     backendplugin.SecretBundle
	Policy      backendplugin.RuntimePolicy
	ExpectedUID *int
	ExpectedSID string
	// DialAndConfigure runs only after peer authentication. Secrets are supplied
	// here by the host only after peer success (never via LaunchSpec).
	DialAndConfigure func(ctx context.Context, conn net.Conn, peer PeerIdentity, generation uint64, secrets backendplugin.SecretBundle, configYAML []byte) error
}

ActivateRequest configures one instance against a verified artifact.

type ActivateResult

type ActivateResult struct {
	Generation uint64
	PID        int
	Peer       PeerIdentity
	Conn       net.Conn
	Cleanup    func() error
}

type BuildResult

type BuildResult struct {
	Backend execbackend.Backend
	// contains filtered or unexported fields
}

BuildResult is a composition-owned backend construction outcome. Lifecycle cleanup is not part of the core-consumed Backend value.

func NewBuildResult

func NewBuildResult(be execbackend.Backend, cleanup func() error) *BuildResult

NewBuildResult pairs a core Backend with an idempotent cleanup.

func (*BuildResult) Cleanup

func (b *BuildResult) Cleanup() error

Cleanup closes process/instance resources exactly once.

type CandidateAssessment

type CandidateAssessment struct {
	Candidate       CandidateID
	Dimensions      []DimensionEvidence
	Feasible        bool
	Selectable      bool
	RejectReasons   []string
	ReplacementCost ReplacementCost
}

type CandidateID

type CandidateID string
const (
	CandidateStockGoPluginV180  CandidateID = "stock_go_plugin_v1_8_0"
	CandidateCustomGoPluginV18x CandidateID = "customized_go_plugin_v1_8_x"
	CandidateProjectOwnedHost   CandidateID = "project_owned_host"
)

type ChannelFactory

type ChannelFactory interface {
	Listen(ctx context.Context, generation uint64) (lis Listener, inherited []*os.File, err error)
}

ChannelFactory creates an approved local channel for one generation. Inherited may contain confidential one-shot handles for the child (never env).

type Config

type Config struct {
	Launcher Launcher
	Channel  ChannelFactory
	WorkDir  string
	AllowEnv []string
}

Config configures a process supervisor.

type CookiePlaintextChannel

type CookiePlaintextChannel struct{}

CookiePlaintextChannel refuses cookie/plaintext loopback bootstrap.

func (CookiePlaintextChannel) Listen

type DimensionEvidence

type DimensionEvidence struct {
	Requirement   RequirementID
	Level         EvidenceLevel
	Notes         string
	Source        *SourceRef
	ReplacesStock bool
}

type EvidenceCatalog

type EvidenceCatalog map[CandidateID][]DimensionEvidence

func DefaultEvidenceCatalog

func DefaultEvidenceCatalog() EvidenceCatalog

type EvidenceLevel

type EvidenceLevel string
const (
	EvidenceFailed          EvidenceLevel = "failed"
	EvidenceMissing         EvidenceLevel = "missing"
	EvidenceSourceVerified  EvidenceLevel = "source_verified"
	EvidenceRuntimeVerified EvidenceLevel = "runtime_verified"
)

type ExactlyOnceWait

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

ExactlyOnceWait wraps Process.Wait so concurrent/repeated waiters share one result.

func (*ExactlyOnceWait) Wait

func (w *ExactlyOnceWait) Wait(p Process) error

type Host

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

Host supervises lazy plugin process activation and peer-gated configuration.

func NewHost

func NewHost(cfg Config) *Host

func (*Host) Activate

func (h *Host) Activate(ctx context.Context, req ActivateRequest) (ActivateResult, error)

func (*Host) Close

func (h *Host) Close() error

func (*Host) CloseInstance

func (h *Host) CloseInstance(id string) error

func (*Host) InvalidateGeneration

func (h *Host) InvalidateGeneration(key string) error

func (*Host) InvalidateProcessGeneration

func (h *Host) InvalidateProcessGeneration(generation uint64) error

InvalidateProcessGeneration invalidates by process generation ID.

func (*Host) SetLaunchProbe

func (h *Host) SetLaunchProbe(fn func())

type HostSecureProfile

type HostSecureProfile struct {
	Platform             PlatformID
	Verification         PlatformVerificationStatus
	LaunchBinding        string
	LocalChannel         string
	RuntimeChannelOK     bool
	RuntimeChannelReason string
}

HostSecureProfile is the release/QA inventory of launch + local-channel readiness. Darwin remains compile-only until an approved peer-cred channel replaces fail-closed.

func HostSecureProfiles

func HostSecureProfiles() []HostSecureProfile

type LaunchEnvProvider

type LaunchEnvProvider interface {
	LaunchEnv() []string
}

LaunchEnvProvider supplies non-secret channel bootstrap env entries.

type LaunchSpec

type LaunchSpec struct {
	Artifact   *trust.VerifiedArtifact
	WorkDir    string
	Env        []string // minimal non-secret allowlist only; non-nil
	Generation uint64
	// ExtraFiles are confidential one-shot inherited handles (never env bootstrap).
	ExtraFiles []*os.File
}

LaunchSpec describes a direct, no-shell activation request. It never carries connector secrets or bootstrap key material.

type Launcher

type Launcher interface {
	Launch(ctx context.Context, spec LaunchSpec) (Process, error)
}

Launcher starts an exact verified artifact identity.

type Listener

type Listener interface {
	Accept(ctx context.Context) (net.Conn, PeerIdentity, error)
	Close() error
}

Listener is an approved confidential local channel endpoint.

type OfficialSourceEvidence

type OfficialSourceEvidence struct {
	ModulePath string
	Version    string
	License    string
	SourceURL  string
	LicenseURL string
}

func DefaultOfficialSource

func DefaultOfficialSource() OfficialSourceEvidence

type PeerIdentity

type PeerIdentity struct {
	PID        int
	UID        int
	SID        string // Windows token user SID when available
	Generation uint64
}

PeerIdentity is the authenticated local peer for an accepted connection.

type PlatformChannel

type PlatformChannel struct{}

PlatformChannel is the OS-approved production channel factory.

func NewPlatformChannel

func NewPlatformChannel() *PlatformChannel

func (PlatformChannel) Listen

func (PlatformChannel) Listen(ctx context.Context, generation uint64) (Listener, []*os.File, error)

Listen creates a connected AF_UNIX socketpair. The child end is returned in inherited for LaunchSpec.ExtraFiles; the host end is authenticated via SO_PEERCRED after the child process exists. No filesystem UDS path is used.

type PlatformID

type PlatformID string
const (
	PlatformLinux   PlatformID = "linux"
	PlatformDarwin  PlatformID = "darwin"
	PlatformWindows PlatformID = "windows"
)

type PlatformLauncher

type PlatformLauncher struct{}

PlatformLauncher is the OS-approved production launcher.

func NewPlatformLauncher

func NewPlatformLauncher() *PlatformLauncher

func (PlatformLauncher) Launch

func (PlatformLauncher) Launch(ctx context.Context, spec LaunchSpec) (Process, error)

Launch duplicates the held verified descriptor and executes it through a child ExtraFiles slot via /proc/self/fd/%d. The executable FD is appended after channel ExtraFiles so os/exec's FD-3+ remapping keeps channelChildFD stable and the exec path resolves to the verified bytes (not the channel). Shell is never used. Env must already be allowlisted by the supervisor.

type PlatformProfile

type PlatformProfile struct {
	Platform      PlatformID
	Verification  PlatformVerificationStatus
	LaunchBinding string
	LocalChannel  string
}

func ApprovedPlatformProfiles

func ApprovedPlatformProfiles() []PlatformProfile

type PlatformVerificationStatus

type PlatformVerificationStatus string
const (
	PlatformRuntimeVerified       PlatformVerificationStatus = "runtime_verified"
	PlatformDesignSourceEvidenced PlatformVerificationStatus = "design_source_evidenced"
	PlatformCompileUnverified     PlatformVerificationStatus = "compile_unverified"
)

type Process

type Process interface {
	PID() int
	Generation() uint64
	Wait() (err error)
	SignalKill() error
	GracefulStop(timeout time.Duration) error
	Close() error
	ContainsPID(pid int) bool
	Stdout() io.ReadCloser
	Stderr() io.ReadCloser
}

Process is a supervised child identity for peer checks and cleanup.

type ProcessModel

type ProcessModel string

ProcessModel is the declared ownership model for supervised plugin processes.

const (
	ProcessModelPerInstance    ProcessModel = "per_instance"
	ProcessModelSharedArtifact ProcessModel = "shared_artifact"
)

type Reason

type Reason string

Reason is a bounded stable process-host outcome code (no paths/secrets).

These constants are outcome codes, not sentinel errors: ReasonOK is a success code, so the Err prefix convention for error sentinels does not apply. The names follow the enum convention (type name prefix + value). Error() is implemented so reasons can be wrapped and matched with errors.Is.

const (
	ReasonOK                    Reason = "ok"
	ReasonUnsupportedBinding    Reason = "unsupported_binding"
	ReasonUnsupportedChannel    Reason = "unsupported_channel"
	ReasonPeerRejected          Reason = "peer_rejected"
	ReasonStaleGeneration       Reason = "stale_generation"
	ReasonPIDReuse              Reason = "pid_reuse"
	ReasonLaunchFailed          Reason = "launch_failed"
	ReasonHandshakeFailed       Reason = "handshake_failed"
	ReasonConfigureBeforePeer   Reason = "configure_before_peer"
	ReasonEnvBootstrapRejected  Reason = "env_bootstrap_rejected"
	ReasonLoopbackRejected      Reason = "loopback_rejected"
	ReasonCookieAuthRejected    Reason = "cookie_auth_rejected"
	ReasonShuttingDown          Reason = "shutting_down"
	ReasonGenerationInvalidated Reason = "generation_invalidated"
	ReasonProcessModelViolation Reason = "process_model_violation"
	ReasonMissingRuntime        Reason = "missing_runtime"
	ReasonArtifactRequired      Reason = "artifact_required"
	ReasonSubstitution          Reason = "substitution"
)

func (Reason) Error

func (r Reason) Error() string

type ReplacementCost

type ReplacementCost struct {
	Launch               bool
	AuthTransport        bool
	Bootstrap            bool
	Lifecycle            bool
	Limits               bool
	ExceedsRetainedValue bool
	Rationale            string
}

type RequirementID

type RequirementID string
const (
	ReqPublicABIOwnership          RequirementID = "public_abi_ownership"
	ReqProtocolNegotiation         RequirementID = "protocol_negotiation"
	ReqBidirectionalStreaming      RequirementID = "bidirectional_streaming"
	ReqTransportRetriesDisabled    RequirementID = "transport_retries_disabled"
	ReqExactByteLaunch             RequirementID = "exact_byte_launch"
	ReqExpectedProcessPeerIdentity RequirementID = "expected_process_peer_identity"
	ReqProtectedBootstrap          RequirementID = "protected_bootstrap"
	ReqMinimalEnvHandleControl     RequirementID = "minimal_env_handle_control"
	ReqProcessTreeCleanup          RequirementID = "process_tree_cleanup"
	ReqBoundedMessagesLogs         RequirementID = "bounded_messages_logs"
	ReqDeclaredProcessModels       RequirementID = "declared_process_models"
	ReqReattachProhibition         RequirementID = "reattach_prohibition"
	ReqLicenseEvidence             RequirementID = "license_evidence"
)

type RequirementSpec

type RequirementSpec struct {
	ID        RequirementID
	Mandatory bool
	Summary   string
}

func MandatoryRequirements

func MandatoryRequirements() []RequirementSpec

type SelectionResult

type SelectionResult struct {
	Selected       CandidateID
	Platforms      []PlatformProfile
	Assessments    []CandidateAssessment
	OfficialSource OfficialSourceEvidence
	Task12Blockers []string
}

func SelectSubstrate

func SelectSubstrate(catalog EvidenceCatalog) (SelectionResult, error)

func (SelectionResult) Assessment

func (SelectionResult) SelectedAssessment

func (r SelectionResult) SelectedAssessment() (CandidateAssessment, bool)

type SharingOptions

type SharingOptions struct {
	IsolationDeclared   bool
	ConcurrencyDeclared bool
}

SharingOptions gates shared-process reuse.

type SourceRef

type SourceRef struct {
	Module     string
	Version    string
	Path       string
	Symbol     string
	Lines      string
	URL        string
	License    string
	LicenseURL string
}

type TestChannel

type TestChannel struct {
	PeerPID    int
	PeerUID    int
	RejectPeer bool
	StaleGen   bool
	Accepts    atomic.Int64
	// contains filtered or unexported fields
}

TestChannel is a peer-gated in-memory channel for unit tests.

func (*TestChannel) Listen

func (t *TestChannel) Listen(_ context.Context, generation uint64) (Listener, []*os.File, error)

type TestLauncher

type TestLauncher struct {
	Launches      atomic.Int64
	PID           int
	Fail          error
	ContainFail   bool // ContainsPID always false (simulates PID reuse / dead child)
	LastSpec      LaunchSpec
	LastProcess   Process
	OnLaunch      func(LaunchSpec)
	StderrPayload string
}

TestLauncher is an in-process launcher for host unit tests (not production).

func (*TestLauncher) Launch

func (t *TestLauncher) Launch(_ context.Context, spec LaunchSpec) (Process, error)

type UnsupportedChannel

type UnsupportedChannel struct{}

UnsupportedChannel refuses with the stable unsupported_channel reason.

func (UnsupportedChannel) Listen

Jump to

Keyboard shortcuts

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