fleet

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

type Clock interface {
	Now() time.Time
}

type DrainReason string

type FleetConfig struct {
	// Instance provisioning
	InstanceConfig instance.InstanceConfig // Template for launching new instances (from shared package)

	// Fleet sizing
	MinInstances   int // Floor -- never scale below this (default: 1)
	MaxInstances   int // Ceiling -- never scale above this (default: 50)
	WarmPoolTarget int // Number of idle instances to keep ready (default: 2)

	// Capacity thresholds
	MaxSessionsPerInstance int     // Max sandboxes per instance (default: 10)
	CapacityHeadroom       float64 // Don't route above this fraction (default: 0.8)

	// Health checking
	HealthCheckInterval time.Duration // How often to poll (default: 15s)
	UnhealthyThreshold  int           // Consecutive failures before marking unhealthy (default: 3)
	HealthyThreshold    int           // Consecutive successes before marking healthy again during drain recovery (default: 3)

	// Scaling
	IdleCooldown            time.Duration // How long an instance must be idle before scale-down (default: 10m)
	DrainTimeout            time.Duration // Max time to wait for active sandboxes during drain (default: 30m)
	ProvisionTimeout        time.Duration // Max time to wait for instance to become healthy (default: 5m)
	MaxConcurrentProvisions int           // Max simultaneous LaunchInstance calls (default: 3)

	// Termination
	MaxTerminateRetries int // Max consecutive TerminateInstance failures before alerting (default: 5)

	// Shutdown behavior
	LeaveInstancesOnClose bool // If true, skip instance termination on Close for re-adoption on restart

	// Sandbox-host port
	SandboxHostPort int // Port sandbox-host listens on (default: 9100)
}

type FleetNodeClient interface {
	control.SandboxControl
	HealthCheck(ctx context.Context) (*HealthCheckResult, error)
}

type FleetOption func(*fleetOptions)

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

type FleetStatus struct {
	TotalInstances    int
	InstancesByState  map[InstanceState]int
	TotalSessions     int64
	WarmPoolSize      int
	PendingProvisions int32
	Healthy           bool
	Closed            bool
}

type HealthCheckResult struct {
	Status       string
	SessionCount int
	ActiveTools  int
	Uptime       time.Duration
	Errors       []string
}

type InstanceState string

type ManagedInstance struct {

	// InstanceID is the cloud provider's unique identifier.
	InstanceID string

	// State is the current lifecycle state.
	State InstanceState

	// Client is the combined SandboxControl + HealthCheck client for this
	// instance. Set after the instance is provisioned and the client factory
	// creates a connection.
	Client FleetNodeClient

	// SessionCount tracks the number of active sandbox sessions on this
	// instance. Updated via the atomic claim-slot protocol (section 4.1.1)
	// and reconciled against HealthCheck-reported counts.
	SessionCount int64

	// MaxSessions is the maximum number of sessions this instance can host,
	// typically set from FleetConfig.MaxSessionsPerInstance.
	MaxSessions int

	// IP is the instance's private IP address used for RPC connections.
	IP string

	// ConsecutiveHealthSuccesses counts consecutive successful health checks.
	// Used for Draining -> Ready recovery when DrainReason is DrainHealth.
	// Reset to 0 on health check failure.
	ConsecutiveHealthSuccesses int

	// ConsecutiveHealthFailures counts consecutive failed health checks.
	// Used to trigger Draining transition when >= UnhealthyThreshold.
	// Reset to 0 on health check success.
	ConsecutiveHealthFailures int

	// DrainReason records why this instance entered the Draining state.
	// Only meaningful when State == InstanceDraining.
	DrainReason DrainReason

	// IdleSince records when the session count last reached 0 (in Ready state).
	// Used by the scale-down logic to determine if the instance has been idle
	// longer than IdleCooldown.
	IdleSince time.Time

	// ProvisionStarted records when provisioning began. Used by the control
	// loop to detect provision timeouts.
	ProvisionStarted time.Time

	// DrainStarted records when draining began. Used by the control loop
	// to detect drain timeouts and force-terminate.
	DrainStarted time.Time

	// TerminateRetries counts consecutive TerminateInstance failures for
	// this instance. Used to trigger an alert after MaxTerminateRetries.
	TerminateRetries int
	// contains filtered or unexported fields
}

type SandboxClientFactory func(addr string) (FleetNodeClient, error)