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 ¶
- func DescendantCleanupSupported() bool
- func OwnershipKey(model ProcessModel, artifactDigest, instanceID string) string
- func RuntimeChannelSupported(p PlatformID) bool
- func StopProcess(p Process, gracefulTimeout time.Duration) error
- func ValidateCatalog(catalog EvidenceCatalog) error
- type ActivateRequest
- type ActivateResult
- type BuildResult
- type CandidateAssessment
- type CandidateID
- type ChannelFactory
- type Config
- type CookiePlaintextChannel
- type DimensionEvidence
- type EvidenceCatalog
- type EvidenceLevel
- type ExactlyOnceWait
- type Host
- func (h *Host) Activate(ctx context.Context, req ActivateRequest) (ActivateResult, error)
- func (h *Host) Close() error
- func (h *Host) CloseInstance(id string) error
- func (h *Host) InvalidateGeneration(key string) error
- func (h *Host) InvalidateProcessGeneration(generation uint64) error
- func (h *Host) SetLaunchProbe(fn func())
- type HostSecureProfile
- type LaunchEnvProvider
- type LaunchSpec
- type Launcher
- type Listener
- type OfficialSourceEvidence
- type PeerIdentity
- type PlatformChannel
- type PlatformID
- type PlatformLauncher
- type PlatformProfile
- type PlatformVerificationStatus
- type Process
- type ProcessModel
- type Reason
- type ReplacementCost
- type RequirementID
- type RequirementSpec
- type SelectionResult
- type SharingOptions
- type SourceRef
- type TestChannel
- type TestLauncher
- type UnsupportedChannel
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 ¶
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 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.
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 (*Host) Activate ¶
func (h *Host) Activate(ctx context.Context, req ActivateRequest) (ActivateResult, error)
func (*Host) CloseInstance ¶
func (*Host) InvalidateGeneration ¶
func (*Host) InvalidateProcessGeneration ¶
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
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" )
func ProcessModelFromSharing ¶
func ProcessModelFromSharing(s backendplugin.ProcessSharing, opt SharingOptions) (ProcessModel, error)
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" )
type ReplacementCost ¶
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 (r SelectionResult) Assessment(id CandidateID) (CandidateAssessment, bool)
func (SelectionResult) SelectedAssessment ¶
func (r SelectionResult) SelectedAssessment() (CandidateAssessment, bool)
type SharingOptions ¶
SharingOptions gates shared-process reuse.
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.
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)