backend

type Backend interface {
	// Spawn starts a long-lived worker. The caller provides the worker ID
	// in spec.WorkerID; the backend uses it as its internal key.
	Spawn(ctx context.Context, spec WorkerSpec) error

	// Stop stops and removes a worker by ID.
	Stop(ctx context.Context, id string) error

	// HealthCheck probes whether a worker is responsive.
	HealthCheck(ctx context.Context, id string) bool

	// Logs streams stdout/stderr from a worker.
	Logs(ctx context.Context, id string) (LogStream, error)

	// Addr resolves the worker's network address (host:port).
	Addr(ctx context.Context, id string) (string, error)

	// Build runs a build task to completion (dependency restore).
	Build(ctx context.Context, spec BuildSpec) (BuildResult, error)

	// ListManaged lists all resources carrying blockyard labels.
	ListManaged(ctx context.Context) ([]ManagedResource, error)

	// RemoveResource removes an orphaned resource.
	RemoveResource(ctx context.Context, r ManagedResource) error

	// WorkerResourceUsage returns a point-in-time resource usage
	// snapshot for a worker. Returns nil stats if the worker is not
	// found. Backends may implement this differently — Docker reads
	// container cgroup counters, the process backend walks /proc.
	WorkerResourceUsage(ctx context.Context, workerID string) (*WorkerResourceUsageResult, error)

	// UpdateResources live-updates memory and CPU limits for a running
	// worker. Returns ErrNotSupported if the backend does not support
	// live resource updates.
	UpdateResources(ctx context.Context, id string, mem int64, nanoCPUs int64) error

	// CleanupOrphanResources removes backend-specific stale state left
	// over from previous runs (Docker: orphaned iptables rules).
	// Process backend is a no-op. Called once at startup.
	CleanupOrphanResources(ctx context.Context) error

	// Preflight runs backend-specific startup checks and returns the
	// resulting report. Each backend checks its own prerequisites.
	// main.go calls this through the interface so it does not have to
	// branch on the backend type.
	Preflight(ctx context.Context) (*preflight.Report, error)

	// CheckRVersion validates that the given R version can be served
	// by this backend. The process backend checks rig-managed
	// installations; the Docker backend returns nil (the image tag
	// determines the R version). Returns a user-facing error message
	// listing available versions when the requested version is not
	// installed.
	CheckRVersion(version string) error
}

type BuildResult struct {
	Success  bool
	ExitCode int
	Logs     string // combined stdout+stderr from the build container
}

type BuildSpec struct {
	AppID     string
	BundleID  string
	Image     string
	Labels    map[string]string
	LogWriter func(string) // called with each log line during the build; may be nil
	Cmd       []string     // container command (e.g. R script invocation)
	Mounts    []MountEntry // bind/volume mounts for the build container
	Env       []string     // environment variables (KEY=VALUE)
	RVersion  string       // pinned R version from bundle manifest; empty = default
}

type LogStream struct {
	Lines <-chan string
	// Close cancels the underlying log follow.
	Close func()
}

type ManagedResource struct {
	ID     string
	Kind   ResourceKind
	Labels map[string]string
}

type MountEntry struct {
	Source   string
	Target   string
	ReadOnly bool
}

type ResourceKind int

type WorkerResourceUsageResult struct {
	CPUPercent       float64
	MemoryUsageBytes uint64
	MemoryLimitBytes uint64
}

type WorkerSpec struct {
	AppID        string
	WorkerID     string
	Image        string
	Cmd          []string // container command; nil = use image entrypoint
	BundlePath   string   // server-side path to unpacked bundle
	LibraryPath  string   // server-side path to restored R library (legacy, phase 2-5)
	LibDir       string   // server-side path to per-worker lib dir from store; empty if no store
	TransferDir  string   // server-side path to per-worker transfer dir (phase 2-7)
	TokenDir     string   // server-side path to worker token dir; mounted ro at /var/run/blockyard
	WorkerMount  string   // in-container mount point (BundleWorkerPath)
	ShinyPort    int
	RVersion     string  // pinned R version from bundle manifest (e.g. "4.5.0"); empty = default
	MemoryLimit  string  // e.g. "512m", "" if unset
	CPULimit     float64 // fractional vCPUs, 0 if unset
	Labels       map[string]string
	Env          map[string]string // additional env vars (e.g. VAULT_ADDR)
	RProfilePath string            // server-side path to blockyard R profile; mounted ro by backends
	DataMounts   []MountEntry      // data mounts from app config; resolved host paths
	Runtime      string            // OCI runtime override; empty = default
}