scheduler

type Config struct {
	Runtime         *runtime.Runtime
	Providers       []providers.Provider
	Artifacts       *artifacts.Extractor // OCI image layer extractor for macOS VM jobs (nil if not available)
	LinuxDispatcher *DispatchClient      // if non-nil, Linux jobs are dispatched to a Linux VM worker via gRPC
	// LinuxJobsDisabled makes canHandleJob refuse Linux-labeled jobs even on
	// a host that could run them ([vm.linux] enabled = false on darwin). Used
	// when a dedicated Linux box serves the same labels: without it, both
	// daemons register a JIT runner per queued job and the loser's runner
	// squats as an orphan until the grace sweep.
	LinuxJobsDisabled bool
	MacOSVMConfig     *vm.MacOSVMConfig // if non-nil, macOS-native jobs are enabled (darwin only)
	// CachePruner reclaims disk held by daemon-managed caches (BuildKit's
	// build cache, the containerd image store) on demand, through the
	// manager that owns each one. Backs the PruneCache RPC that
	// `ephemerd cache clear` uses so an operator no longer has to stop the
	// daemon and delete directories. Nil makes PruneCache return
	// Unimplemented.
	CachePruner       cacheprune.Interface
	DataDir           string // ephemerd data directory (used for artifact extraction paths)
	Version           string // daemon build version (from main.version); surfaced via Status and used by the Upgrade RPC
	MaxConcurrent     int
	MaxMacOSVMs       int // max concurrent macOS VMs (Vz limit; default auto-detected)
	Labels            []string
	PollInterval      time.Duration   // if >0, use polling mode (default)
	ReconcileInterval time.Duration   // webhook mode: periodic catch-up sweep for stranded jobs (0 = disabled)
	WebhookPort       int             // listen port for health/webhook server
	WebhookSecret     string          // webhook signature secret
	TLSCert           string          // TLS certificate path
	TLSKey            string          // TLS private key path
	Tunnel            tunnel.Provider // if non-nil, creates a public tunnel for webhooks
	TunnelMaxRetries  int             // max consecutive reconnect failures before fallback to polling (0 = default 5)

	// ExternalURL is the public base URL of an externally-managed tunnel
	// (tunnel = "external"). When set alongside webhook mode and NO managed
	// Tunnel, the scheduler registers each webhook-capable provider's hook to
	// <ExternalURL>/webhook/<provider> on startup, so the operator doesn't
	// have to hand-add a hook per repo. External hooks are operator-owned and
	// are NOT deregistered on shutdown. Empty means "receiver only, don't
	// touch the platform's webhooks".
	ExternalURL     string
	JobTimeout      time.Duration
	ShutdownTimeout time.Duration
	LogRetention    time.Duration // max age for job log files (default 7d)

	// MacOSProvisionTimeout bounds the pre-registration provisioning phase of
	// a macOS VM job — booting the VM and waiting for its runner to become
	// reachable (handleMacOSJob → MacOSVM.WaitForRunner). If the wait has not
	// returned by this deadline the VM is force-stopped so the reachability
	// wait unblocks, the job is failed, and the single macOS concurrency slot
	// is released. Guards against a hung guest SSH command wedging the wait
	// indefinitely (the VM-internal loop caps itself at ~2 min, but its SSH
	// session calls carry no deadline and ignore ctx). Zero applies
	// defaultMacOSProvisionTimeout.
	MacOSProvisionTimeout time.Duration

	// Retry configures the claim/provision retry queue. When the initial
	// attempt to claim a queued job fails with a retryable error
	// (rate-limit exhausted, transient 5xx, network), the job is
	// enqueued and re-attempted on a backoff ladder rather than lost.
	// GitHub does not re-deliver workflow_job webhooks. Leave zero-valued
	// (Enabled=false) to keep the pre-existing "log and drop" behavior.
	Retry RetryConfig

	// OrphanSweep configures teardown of dispatched runners that were
	// never observed picking up a job. GitHub schedules JIT runners onto
	// ANY queued job with matching labels, so the runner dispatched "for"
	// a job may end up running a different one — leaving the runner that
	// was dispatched for THAT job idle with no job-completion event ever
	// pointing at it. The sweep destroys such runners once they have been
	// idle-unbound for Grace. Only active in webhook mode and only for
	// runners dispatched via providers that report runner assignments
	// (providers.RunnerNameReporter) — otherwise "never observed bound"
	// would just mean "we had no way to observe it".
	OrphanSweep OrphanSweepConfig

	// RunnerImageForRepo resolves the per-repo, per-OS image override
	// configured under [runner.images]. Returns "" when no override is
	// set; the scheduler then falls back to the provider per-OS default
	// and finally the runtime's host-aware default. Nil-safe.
	RunnerImageForRepo func(repo, os string) string

	Log *slog.Logger
}

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

type DispatchServer struct {
	apiv1.UnimplementedDispatchServer
	// contains filtered or unexported fields
}

type DispatchServerConfig struct {
	Port               int
	Runtime            *runtime.Runtime
	Log                *slog.Logger
	StatsInterval      time.Duration // default 10s when zero
	LinuxCPULimit      uint64        // 0 = unlimited
	LinuxMemLimitBytes uint64        // 0 = unlimited

	// Token is the shared bearer token the server requires on every RPC. When
	// non-empty, unary + stream interceptors reject any call that does not
	// present a matching token (constant-time compare). Empty disables auth —
	// which should only happen in tests or misconfigured setups; production
	// callers plumb a token from the shared data dir (see
	// LoadOrCreateDispatchToken). The server logs loudly when it starts
	// unauthenticated so the footgun is visible.
	Token string

	// BindAddr is the interface the listener binds to. Empty defaults to
	// "0.0.0.0" so the Vz/Hyper-V host on the NAT side can reach it (a narrower
	// bind is only safe when the host address is known; see the comment on
	// StartDispatchServer). The token check protects the surface regardless of
	// bind, so 0.0.0.0 is defense-in-depth-behind-auth rather than the sole
	// control.
	BindAddr string
}

type OrphanSweepConfig struct {
	// Enabled toggles the sweep.
	Enabled bool

	// Grace is how long a dispatched runner may remain unbound (never
	// seen in an in_progress event) before it is destroyed. Defaults to
	// 10 minutes when zero.
	Grace time.Duration
}

type RetryConfig struct {
	// Enabled toggles the entire retry queue. When false, failures still
	// log and drop as before (no behavior change).
	Enabled bool

	// Schedule is the ordered backoff ladder. Each entry is the base
	// delay for that attempt; jitter is applied on top. If nil, defaults
	// to {30s, 1m, 2m, 5m, 10m}.
	Schedule []time.Duration

	// MaxAge is the wall-clock budget from first failure to giving up.
	// Once (now - firstFailure) > MaxAge, we log a WARN and drop. Default 90m.
	MaxAge time.Duration

	// Jitter is the fraction (0-1) of a delay that's randomized +/- around
	// the base value. Set to a NEGATIVE value (e.g. -1) to request the
	// default (0.2 = +/-20%). Literal 0 is honored  -  tests use it for
	// deterministic scheduling.
	Jitter float64

	// RateHint returns the last-observed GitHub rate-limit state. When
	// remaining == 0 and now < reset and updated is fresh (<5m old),
	// the next attempt is snapped to reset + a small jitter instead of
	// the Schedule entry. Nil-safe: nil means "no rate awareness".
	RateHint func() (remaining int64, reset time.Time, updated time.Time)

	// Now is the clock function. Defaults to time.Now. Tests inject
	// a fake clock so backoff scheduling is deterministic.
	Now func() time.Time
}

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

type VMSSHInfo struct {
	IP         string `json:"ip"`
	User       string `json:"user"`
	PrivateKey []byte `json:"private_key"` // PEM-encoded ed25519
}