herd

type FirecrackerFactory struct {
	FirecrackerPath string
	KernelImagePath string
	// GuestAgentPath is the host path to the static herd-guest-agent binary; it is
	// copied into each VM rootfs before boot (no initrd).
	GuestAgentPath string
	Storage        *storage.Manager

	SocketPathDir string
	IPAM          *network.IPAM
}

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

type Option func(*config)

type Pool[C any] struct {
	// contains filtered or unexported fields
}

type PoolStats struct {
	TotalWorkers     int
	ActiveSessions   int
	InflightAcquires int
	Node             observer.NodeStats
}

type Session[C any] struct {
	ID     string
	Worker Worker[C]
	// contains filtered or unexported fields
}

type SessionRegistry[C any] interface {
	// Get returns the worker pinned to sessionID.
	// Returns (nil, nil) if no session exists for this ID.
	Get(ctx context.Context, sessionID string) (Worker[C], error)

	// Put pins a worker to a sessionID.
	Put(ctx context.Context, sessionID string, w Worker[C]) error

	// Delete removes the pinning for sessionID.
	Delete(ctx context.Context, sessionID string) error

	// List returns a snapshot of all currently active sessions.
	// Primarily used for background health checks and cleanup.
	List(ctx context.Context) (map[string]Worker[C], error)

	// Len returns the number of active sessions.
	Len() int
}

type TenantConfig struct {
	Image              string
	Command            []string
	Env                map[string]string
	IdleTimeoutSeconds int
	TTLSeconds         int
	HealthInterval     string
}

type Worker[C any] interface {
	// ID returns a stable, unique identifier for this worker (e.g. "worker-3").
	// Never reused — not even after a crash and restart.
	ID() string

	// Address returns the internal network URI the worker
	// is listening on (e.g., '127.0.0.1:54321').
	Address() string

	// Client returns the typed connection to the worker process.
	// For most users this is *http.Client; gRPC users return their stub here.
	Client() C

	// Healthy performs a liveness check against the subprocess.
	// Returns nil if the worker is accepting requests; non-nil otherwise.
	// Pool.Acquire calls this before handing a worker to a new session,
	// so a stale or crashed worker is never returned to a caller.
	Healthy(ctx context.Context) error

	// OnCrash sets a callback triggered when the worker process exits unexpectedly.
	OnCrash(func(sessionID string))

	// Close performs graceful shutdown of the worker process.
	// Called by the pool during scale-down or Pool.Shutdown.
	io.Closer
}

type WorkerFactory[C any] interface {
	// Spawn starts one new worker and blocks until it is healthy.
	// If ctx is cancelled before the worker becomes healthy, Spawn must
	// kill the process and return a non-nil error.
	Spawn(ctx context.Context, sessionID string, config TenantConfig) (Worker[C], error)

	// WarmImage ensures the requested image is present in the local cache.
	WarmImage(ctx context.Context, imageRef string) error
}