Documentation
¶
Index ¶
- Variables
- func ApplyLaunchNiceness(logger *slog.Logger, pid int, niceness int)
- func HealthFailureDetected(state HealthState) bool
- func HealthFailureReason(state HealthState) string
- func LookupEnv(env []string, key string) (string, bool)
- func LookupEnvFunc(env []string) func(string) (string, bool)
- func ResolveExecutable(command string, env []string, dir string) (string, error)
- func SetEnvValue(env []string, key string, value string) []string
- func StartWithLaunchNiceness(logger *slog.Logger, niceness int, cmd *exec.Cmd, start func() error) error
- type AcceptedCapabilities
- type ExecutableResolution
- func (r ExecutableResolution) Clone() ExecutableResolution
- func (r ExecutableResolution) Consume(command string, env []string, dir string) (string, error)
- func (r ExecutableResolution) ResolvedExecutable() string
- func (r ExecutableResolution) State() ExecutableResolutionState
- func (r ExecutableResolution) Valid() bool
- type ExecutableResolutionState
- type ExitStatus
- type HandlerFunc
- type HealthCheckResponse
- type HealthState
- type InitializeCapabilities
- type InitializeExtension
- type InitializeExtensionInfo
- type InitializeMethods
- type InitializeRequest
- type InitializeResponse
- type InitializeRuntime
- type InitializeSupports
- type LaunchConfig
- type Process
- func (p *Process) Call(ctx context.Context, method string, params, result any) error
- func (p *Process) Done() <-chan struct{}
- func (p *Process) ExitStatus() (ExitStatus, bool)
- func (p *Process) HandleMethod(method string, handler HandlerFunc) error
- func (p *Process) HealthState() HealthState
- func (p *Process) Initialize(ctx context.Context, request InitializeRequest) (InitializeResponse, error)
- func (p *Process) PID() int
- func (p *Process) Shutdown(ctx context.Context) error
- func (p *Process) Stderr() string
- func (p *Process) Stdin() io.WriteCloser
- func (p *Process) Stdout() io.ReadCloser
- func (p *Process) Wait() error
- type RPCError
- type ResponseDecodeError
- type ShutdownRequest
- type ShutdownResponse
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNotInitialized reports that an operational request was attempted before initialize completed. ErrNotInitialized = errors.New("subprocess: not initialized") // ErrShutdownInProgress reports that the process is draining and will not accept new requests. ErrShutdownInProgress = errors.New("subprocess: shutdown in progress") // ErrTransportDisabled reports that JSON-RPC transport methods were called on a raw-process launch. ErrTransportDisabled = errors.New("subprocess: transport disabled") )
var ErrTransportClosedBeforeResponse = errors.New("subprocess: transport closed before response")
ErrTransportClosedBeforeResponse reports a subprocess transport that closed while an RPC call was still waiting for its response.
Functions ¶
func ApplyLaunchNiceness ¶
ApplyLaunchNiceness lowers the scheduling priority of the launched process group after start. Linux launches already inherit priority before exec; other Unix platforms retain the in-flight fork limitation of SetProcessGroupNiceness. Failure never aborts the launch. A failed call can still have lowered some group members, and those changes are not restored; the remaining members keep the daemon's priority.
func HealthFailureDetected ¶
func HealthFailureDetected(state HealthState) bool
HealthFailureDetected reports whether a snapshot contains an observed failed verdict. A zero-value snapshot is unsupported or not yet checked and does not degrade consumers.
func HealthFailureReason ¶
func HealthFailureReason(state HealthState) string
HealthFailureReason returns the human-readable reason carried by a failed snapshot.
func LookupEnv ¶
LookupEnv returns the last matching environment assignment using the target platform's key semantics. Windows environment keys are case-insensitive; Unix environment keys are case-sensitive.
func LookupEnvFunc ¶
LookupEnvFunc snapshots env and returns a platform-aware lookup closure.
func ResolveExecutable ¶
ResolveExecutable resolves command against the exact launch environment and working directory that will be used by the child process.
func SetEnvValue ¶
SetEnvValue returns a copy of env with exactly one assignment for key.
Types ¶
type AcceptedCapabilities ¶
type AcceptedCapabilities struct {
Provides []string `json:"provides"`
Permissions []extensionprotocol.HostAPIMethod `json:"permissions"`
}
AcceptedCapabilities is the subset the extension accepted for this session.
type ExecutableResolution ¶
type ExecutableResolution struct {
// contains filtered or unexported fields
}
ExecutableResolution retains one terminal executable lookup result without exposing its operational cause as diagnostic data.
func NewExecutableResolution ¶
func NewExecutableResolution( command string, env []string, dir string, executable string, cause error, ) ExecutableResolution
NewExecutableResolution snapshots one terminal result for an exact command runtime.
func (ExecutableResolution) Clone ¶
func (r ExecutableResolution) Clone() ExecutableResolution
Clone returns an independent immutable snapshot.
func (ExecutableResolution) Consume ¶
Consume returns the pinned result only for its exact command runtime.
func (ExecutableResolution) ResolvedExecutable ¶
func (r ExecutableResolution) ResolvedExecutable() string
ResolvedExecutable returns the absolute executable only for a resolved result.
func (ExecutableResolution) State ¶
func (r ExecutableResolution) State() ExecutableResolutionState
State returns the safe terminal state without exposing the private cause.
func (ExecutableResolution) Valid ¶
func (r ExecutableResolution) Valid() bool
Valid reports whether the value contains a terminal result.
type ExecutableResolutionState ¶
type ExecutableResolutionState string
ExecutableResolutionState identifies one immutable terminal executable lookup result.
const ( ExecutableResolutionResolved ExecutableResolutionState = "resolved" ExecutableResolutionNotFound ExecutableResolutionState = "not_found" ExecutableResolutionFailed ExecutableResolutionState = "failed" )
type ExitStatus ¶
ExitStatus captures the stable OS facts available after a process exits.
func ExitStatusFromProcessState ¶
func ExitStatusFromProcessState(state *os.ProcessState) (ExitStatus, bool)
ExitStatusFromProcessState extracts portable process-exit diagnostics.
func (ExitStatus) ExitCodeValue ¶
func (s ExitStatus) ExitCodeValue() (int, bool)
ExitCodeValue returns a real numeric exit code. Unix uses -1 when a signal terminated the process, which is not an exit code and must not be serialized.
type HandlerFunc ¶
HandlerFunc handles one inbound JSON-RPC request.
type HealthCheckResponse ¶
type HealthCheckResponse struct {
Healthy bool `json:"healthy"`
Message string `json:"message,omitempty"`
Details json.RawMessage `json:"details,omitempty"`
}
HealthCheckResponse is the structured result of the health_check RPC.
type HealthState ¶
type HealthState struct {
Healthy bool
Message string
Details json.RawMessage
LastCheckedAt time.Time
ConsecutiveFailures int
LastError string
}
HealthState captures the current health-monitor snapshot for the subprocess.
func CloneHealthState ¶
func CloneHealthState(state HealthState) HealthState
CloneHealthState returns an immutable copy of a subprocess health snapshot.
type InitializeCapabilities ¶
type InitializeCapabilities struct {
Provides []string `json:"provides"`
GrantedPermissions []extensionprotocol.HostAPIMethod `json:"granted_permissions"`
GrantedResourceKinds []string `json:"granted_resource_kinds"`
GrantedResourceScopes []string `json:"granted_resource_scopes"`
}
InitializeCapabilities carries runtime-granted capabilities.
type InitializeExtension ¶
type InitializeExtension struct {
Name string `json:"name"`
Version string `json:"version"`
SourceTier string `json:"source_tier"`
}
InitializeExtension identifies the launched extension.
type InitializeExtensionInfo ¶
type InitializeExtensionInfo struct {
Name string `json:"name"`
Version string `json:"version"`
SDKName string `json:"sdk_name,omitempty"`
SDKVersion string `json:"sdk_version,omitempty"`
}
InitializeExtensionInfo identifies the running extension implementation.
type InitializeMethods ¶
type InitializeMethods struct {
DaemonRequests []string `json:"daemon_requests"`
ExtensionServices []string `json:"extension_services"`
}
InitializeMethods lists callable method families for the session.
type InitializeRequest ¶
type InitializeRequest struct {
ProtocolVersion string `json:"protocol_version"`
SupportedProtocolVersion []string `json:"supported_protocol_versions"`
CompozyVersion string `json:"compozy_version"`
SessionNonce string `json:"session_nonce"`
Extension InitializeExtension `json:"extension"`
Capabilities InitializeCapabilities `json:"capabilities"`
Methods InitializeMethods `json:"methods"`
Runtime InitializeRuntime `json:"runtime"`
}
InitializeRequest is the Compozy -> extension session contract request.
func CloneInitializeRequest ¶
func CloneInitializeRequest(src InitializeRequest) InitializeRequest
CloneInitializeRequest returns a deep copy safe to expose to callers.
func (InitializeRequest) Validate ¶
func (r InitializeRequest) Validate() error
Validate checks that the initialize request carries the mandatory contract fields.
type InitializeResponse ¶
type InitializeResponse struct {
ProtocolVersion string `json:"protocol_version"`
ExtensionInfo InitializeExtensionInfo `json:"extension_info"`
AcceptedCapabilities AcceptedCapabilities `json:"accepted_capabilities"`
ImplementedMethods []string `json:"implemented_methods"`
SupportedHookEvents []string `json:"supported_hook_events"`
HeartbeatSourceKinds []extensionprotocol.HeartbeatSourceKind `json:"heartbeat_source_kinds,omitempty"`
WatchSourceKinds []string `json:"watch_source_kinds,omitempty"`
CmdPaletteViews []string `json:"cmd_palette_views,omitempty"`
Supports InitializeSupports `json:"supports"`
}
InitializeResponse is the extension -> Compozy initialize acknowledgment.
type InitializeRuntime ¶
type InitializeRuntime struct {
HealthCheckIntervalMS int64 `json:"health_check_interval_ms"`
HealthCheckTimeoutMS int64 `json:"health_check_timeout_ms"`
ShutdownTimeoutMS int64 `json:"shutdown_timeout_ms"`
DefaultHookTimeoutMS int64 `json:"default_hook_timeout_ms"`
DefaultViewTimeoutMS int64 `json:"default_view_timeout_ms,omitempty"`
}
InitializeRuntime carries runtime intervals and deadlines negotiated during initialize.
type InitializeSupports ¶
type InitializeSupports struct {
HealthCheck bool `json:"health_check"`
}
InitializeSupports advertises optional protocol features.
type LaunchConfig ¶
type LaunchConfig struct {
Command string
// Executable carries a previously resolved absolute path so callers can bind
// validation and launch to one executable identity without a second PATH lookup.
Executable string
Args []string
Dir string
// Env inherits when nil; explicit empty excludes parent entries except OS-required variables.
Env []string
Logger *slog.Logger
// StderrSink receives stderr only after StderrTransform has scrubbed it.
StderrSink io.Writer
// StderrTransform scrubs complete stderr records before diagnostic capture or forwarding.
StderrTransform func(string) string
// DisableTransport leaves stdout unread so callers like ACP can attach their own protocol layer.
DisableTransport bool
// MaxMessageBytes bounds a single encoded JSON-RPC frame when transport is enabled.
MaxMessageBytes int
// ShutdownTimeout bounds the cooperative shutdown wait before signal escalation.
ShutdownTimeout time.Duration
// PostSignalGrace bounds the wait between SIGTERM and SIGKILL escalation.
PostSignalGrace time.Duration
// ShutdownReason is sent as the shutdown RPC reason when transport is enabled.
ShutdownReason string
// HealthFailureThreshold overrides the consecutive probe failures needed to mark the process unhealthy.
HealthFailureThreshold int
// Niceness lowers the CPU scheduling priority of the launched process group
// on Unix so descendants inherit it; zero leaves the priority unchanged.
// Failure to apply it is logged and never fails the launch.
Niceness int
// ProcessRegistry checkpoints ownership for long-running subprocesses.
ProcessRegistry *toolruntime.Registry
ProcessRecord toolruntime.RegisterConfig
}
LaunchConfig configures a managed subprocess.
type Process ¶
type Process struct {
// contains filtered or unexported fields
}
Process manages one subprocess and its optional JSON-RPC transport.
func Launch ¶
func Launch(ctx context.Context, cfg LaunchConfig) (*Process, error)
Launch starts a managed subprocess and optionally attaches the shared JSON-RPC transport.
func (*Process) Done ¶
func (p *Process) Done() <-chan struct{}
Done closes when the subprocess exits.
func (*Process) ExitStatus ¶
func (p *Process) ExitStatus() (ExitStatus, bool)
ExitStatus returns the captured OS exit diagnostics after process completion.
func (*Process) HandleMethod ¶
func (p *Process) HandleMethod(method string, handler HandlerFunc) error
HandleMethod registers an inbound JSON-RPC request handler.
func (*Process) HealthState ¶
func (p *Process) HealthState() HealthState
HealthState returns the latest health-monitor snapshot.
func (*Process) Initialize ¶
func (p *Process) Initialize(ctx context.Context, request InitializeRequest) (InitializeResponse, error)
Initialize performs the session initialize handshake and transitions the process to ready on success.
func (*Process) Shutdown ¶
Shutdown performs cooperative shutdown when transport is enabled, then escalates signals if needed.
func (*Process) Stdin ¶
func (p *Process) Stdin() io.WriteCloser
Stdin exposes the subprocess stdin writer for callers that disable the shared transport.
func (*Process) Stdout ¶
func (p *Process) Stdout() io.ReadCloser
Stdout exposes the subprocess stdout reader for callers that disable the shared transport. Drain it to EOF or close it explicitly to release the reader, including after Wait.
type RPCError ¶
type RPCError struct {
Code int `json:"code"`
Message string `json:"message"`
Data json.RawMessage `json:"data,omitempty"`
}
RPCError models a JSON-RPC 2.0 error object.
func NewRPCError ¶
NewRPCError constructs a JSON-RPC error with optional structured data.
type ResponseDecodeError ¶
ResponseDecodeError reports that a JSON-RPC response arrived but its result could not be materialized into the caller's negotiated response type.
func (*ResponseDecodeError) Error ¶
func (e *ResponseDecodeError) Error() string
Error implements error.
func (*ResponseDecodeError) Unwrap ¶
func (e *ResponseDecodeError) Unwrap() error
Unwrap exposes the underlying JSON decode failure.
type ShutdownRequest ¶
ShutdownRequest is the cooperative drain request sent before signal escalation.
type ShutdownResponse ¶
type ShutdownResponse struct {
Acknowledged bool `json:"acknowledged"`
}
ShutdownResponse acknowledges a cooperative drain request.