backend

type Backend interface {
	// Name is a human-readable identifier, e.g. "docker-linux".
	Name() string
	// Ping verifies the backend is reachable.
	Ping(ctx context.Context) error
	// OSType returns the daemon's container OS ("linux" or "windows").
	OSType(ctx context.Context) (string, error)
	// EnsureImage makes sure the runner image is present (pull if missing).
	EnsureImage(ctx context.Context, imageRef string) error
	// Launch starts one ephemeral runner and returns immediately with a handle.
	// If it cannot prove that a failed launch left no live instance, it returns
	// both a cleanup-capable handle and an error. Callers must terminate that
	// handle before releasing the runner registration.
	Launch(ctx context.Context, req LaunchRequest) (RunnerHandle, error)
	// Close releases backend resources (daemon client connections).
	Close() error
}

type ContainerSettings struct {
	// CPUCount limits the runner to this many CPUs.
	CPUCount int64
	// MemoryBytes is the hard memory limit.
	MemoryBytes int64
	// MemorySwapBytes is the total memory plus swap limit. It is supported only
	// by Linux Docker.
	MemorySwapBytes int64
	// DNS contains validated IP addresses used as the container's resolvers.
	DNS []string
}

type DockerEndpoint struct {
	Host         string
	OSType       string
	Architecture string
}

type DockerTLSConfig struct {
	CAFile   string
	CertFile string
	KeyFile  string
}

type LaunchRequest struct {
	// Name uniquely identifies this runner instance for this provisioning cycle.
	Name string
	// Image is the runner container image to launch.
	Image string
	// EncodedJITConfig is the base64 blob from GitHub's generate-jitconfig.
	EncodedJITConfig string
	// WorkFolder is the runner work directory inside the container.
	WorkFolder string
	// Labels are the runner labels (informational; already baked into the JIT config).
	Labels []string
	// Env is injected into the container (JIT_CONFIG, cache redirect, tool cache, ...).
	Env map[string]string
	// Mounts are tool-cache volumes, docker socket (DinD), git mirror, etc.
	Mounts []Mount
	// Container contains normalized resource and network controls. Zero values
	// preserve the backend's defaults.
	Container ContainerSettings
	// Index is the slot number within the pool (0-based), for naming/logging.
	Index int
	// Ownership identifies a scale-set runner strongly enough for a restarted
	// multirunner instance to reclaim only its own backend resources.
	Ownership RunnerOwnership
}

type Mount struct {
	Source   string // host path (bind) or volume name (volume)
	Target   string // path inside the container
	ReadOnly bool
	Volume   bool // true => named volume, false => host bind mount
}

type OwnedRunner struct {
	ResourceID string
	Name       string
	RunnerID   int64
}

type OwnedRunnerStore interface {
	ListOwnedRunners(ctx context.Context, ownership RunnerOwnership) ([]OwnedRunner, error)
	RemoveOwnedRunner(ctx context.Context, resourceID string) error
}

type RunnerHandle interface {
	// Wait blocks until the runner exits and returns its exit code.
	Wait(ctx context.Context) (exitCode int, err error)
	// Logs returns a reader for the runner's combined stdout/stderr.
	Logs(ctx context.Context) (io.ReadCloser, error)
	// Kill forcibly terminates the runner (used during shutdown).
	Kill(ctx context.Context) error
	// ID returns the backend-specific identifier (container ID) for logging.
	ID() string
}

type RunnerOwnership struct {
	Instance   string
	Target     string
	Pool       string
	ScaleSetID int
	RunnerID   int64
}