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
	MacOSVMConfig    *vm.MacOSVMConfig    // if non-nil, macOS-native jobs are enabled (darwin only)
	DataDir          string               // ephemerd data directory (used for artifact extraction paths)
	MaxConcurrent    int
	MaxMacOSVMs      int // max concurrent macOS VMs (Vz limit; default auto-detected)
	Labels           []string
	PollInterval     time.Duration   // if >0, use polling mode (default)
	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)

	// 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

	MaxNativeMac      int                      // max concurrent native macOS jobs (default 4)
	MacOSModeForRepo  func(repo string) string // returns "native" or "vm" per repo (nil = always VM)
	NativeMacUser     string                   // non-root user for native macOS runner processes
	NativeMacStrict   bool                     // opt-in deny-by-default sandbox for native macOS jobs
	NativeMacMaxProcs int                      // ulimit -u for native macOS jobs (0 = unlimited; default 2048)
	RunnerDir         string                   // path to extracted GHA runner binary dir (runner.Manager.Dir())
	PrivateKeyPath    string                   // GitHub App private_key_path, denied read access in the native sandbox (empty for PAT auth)

	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
}

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
}