pluginhost

type CommandSpec struct {
	Path string
	Args []string
	Env  []string
}

type Config struct {
	PluginID        string
	Kind            Kind
	Protocol        string
	ProtocolVersion uint32
	Command         CommandSpec

	// HandshakeTimeout is how long the host waits for the unique stdout
	// handshake line and the socket authentication frame before killing the
	// process and counting a crash.
	HandshakeTimeout time.Duration
	// ShutdownTimeout is the graceful shutdown deadline; after it the process
	// is killed.
	ShutdownTimeout time.Duration
	// HealthCheckInterval is how often the established RPC client is probed.
	HealthCheckInterval time.Duration
	// MaxRestarts is the crash-loop budget: at most this many re-launches are
	// attempted before the plugin is disabled. Zero disables restarts.
	MaxRestarts int
	BaseBackoff time.Duration
	MaxBackoff  time.Duration
	// LogBufferSize caps the retained redacted log lines per plugin.
	LogBufferSize int
	// Jitter randomizes backoff; default is full jitter in [0, d]. Override
	// with a deterministic function in tests.
	Jitter func(time.Duration) time.Duration
}

type ExecRunner struct{}

type Handshake struct {
	Marker          string
	PluginID        string
	Protocol        string
	ProtocolVersion uint32
	Transport       string
	Endpoint        string
	RPC             string
	LaunchID        string
	Proof           string
}

type Health uint8

type HealthChecker interface {
	Check(ctx context.Context, target HealthTarget) (Health, error)
}

type HealthFailurePolicy uint8

type HealthTarget struct {
	PluginID   string
	Version    string
	Tenant     string
	InstanceID string
}

type Installation struct {
	PluginID string
	Version  string
	Path     string
	// Kind selects the protocol client the host builds for this installation.
	// A zero value means KindDriver.
	Kind Kind
}

type Instance struct {
	ID        string
	Tenant    string
	PluginID  string
	Version   string
	Config    map[string]string
	Isolation Isolation
}

type InstanceSnapshot struct {
	Tenant              string
	InstanceID          string
	PluginID            string
	Version             string
	Isolation           Isolation
	Enabled             bool
	State               State
	Health              Health
	ConsecutiveFailures int
	Restarts            int
	Crashes             int
	Launches            int
	Config              map[string]string
}

type InstanceSpec struct {
	ID        string
	Tenant    string
	PluginID  string
	Version   string
	Config    map[string]string
	Isolation Isolation
}

type Isolation uint8

type Kind uint8

type LogEntry struct {
	Stream string
	Line   string
}

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

type ManagerOptions struct {
	Runner           Runner
	Logger           *slog.Logger
	Protocol         string
	ProtocolVersion  uint32
	HealthChecker    HealthChecker
	MetricsCollector MetricsCollector

	// HealthCheckInterval is how often running instances are probed.
	HealthCheckInterval time.Duration
	// HealthFailureThreshold is the number of consecutive failed probes before
	// HealthFailurePolicy is applied.
	HealthFailureThreshold int
	// HealthFailurePolicy selects restart or disable after the threshold.
	HealthFailurePolicy HealthFailurePolicy

	// Supervisor tuning, forwarded to every supervised process.
	HandshakeTimeout time.Duration
	ShutdownTimeout  time.Duration
	MaxRestarts      int
	BaseBackoff      time.Duration
	MaxBackoff       time.Duration
	LogBufferSize    int
	Jitter           func(time.Duration) time.Duration

	// CommandArgs/CommandEnv are the default argv/env used for every launched
	// process (Env is supplemented with the launch identity).
	CommandArgs []string
	CommandEnv  []string
}

type Metrics struct {
	// CPUTime is total CPU time consumed by the plugin process.
	CPUTime time.Duration
	// RSSBytes is resident set size in bytes (0 when unavailable).
	RSSBytes int64
	// Handles is the open handle count, or -1 when unavailable.
	Handles int
	// Goroutines is the live goroutine count, or -1 when unavailable.
	Goroutines int
	// MessageRate is messages per second over the observation window.
	MessageRate float64
	// RestartCount is the process restart count maintained by the Manager.
	RestartCount int
	// LastHealthy is the last time the health loop observed HEALTHY (zero when
	// never observed).
	LastHealthy time.Time
}

type MetricsCollector interface {
	Collect(ctx context.Context, target MetricsTarget) (Metrics, error)
}

type MetricsTarget struct {
	PluginID   string
	Version    string
	Tenant     string
	InstanceID string
}

type Process interface {
	Wait() error
	Signal(os.Signal) error
	Kill() error
	Pid() int
	Stdout() io.ReadCloser
	Stderr() io.ReadCloser
}

type RemoveOption func(*removeOptions)

type RemoveResult struct {
	// Purged is true only when an explicit purge option was requested.
	Purged bool
	// DataPreserved is true when plugin data was left in place. It is the
	// default Remove semantics.
	DataPreserved bool
}

type Runner interface {
	Start(spec CommandSpec) (Process, error)
}

type Snapshot struct {
	State              State
	Crashes            int
	Restarts           int
	Launches           int
	HandshakeCompleted bool
	Backoffs           []time.Duration
	// Kind is the protocol kind the supervisor was configured for.
	Kind Kind
	// Endpoint is the most recent launch endpoint (loopback TCP or Unix
	// socket path). It is a local-only address and safe to surface.
	Endpoint string
	// RPCConnections is the number of authenticated RPC connections the host
	// has accepted across the current launch. Rejected proofs never count.
	RPCConnections int
}

type State uint8

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