herd

type FirecrackerFactory struct {
	// FirecrackerPath is the absolute host path to the firecracker binary.
	// The jailer exec's it inside the chroot; it never runs as root.
	FirecrackerPath string
	// JailerPath is the absolute host path to the jailer binary.
	JailerPath string
	// KernelImagePath is the shared host path to the guest kernel image.
	// It is hard-linked into each VM's chroot at /run/vmlinux before boot.
	KernelImagePath string
	// GuestAgentPath is the host path to the static herd-guest-agent binary.
	GuestAgentPath string

	Storage     *storage.Manager
	IPAM        *network.IPAM
	PortManager *network.PortManager

	// UIDPool is the per-VM UID/GID allocator. Each Spawn leases a unique UID
	// from the pool; Close returns it. This guarantees every concurrent microVM
	// runs in a distinct DAC security domain, preventing lateral movement
	// between tenants on the same host.
	UIDPool *uid.Pool
	// JailerChrootBaseDir is the root under which the jailer creates per-VM
	// chroot directories: <JailerChrootBaseDir>/firecracker/<vmID>/root/
	JailerChrootBaseDir string
}

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 PortMapping struct {
	HostInterface string `json:"host_interface"` // e.g. "eth0", "192.168.0.1", or "0.0.0.0"
	HostPort      int    `json:"host_port"`      // 0 means assign a random available port
	GuestPort     int    `json:"guest_port"`
	Protocol      string `json:"protocol"` // "tcp" or "udp"
}

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
	PortMappings       []PortMapping
}

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
}