controller

package
v0.22.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 14, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type DiskChecker

type DiskChecker interface {
	NeedsReclaim() (bool, error)
	Sweep(ctx context.Context) error
}

DiskChecker is the pre-job-start disk-pressure check startInstanceWithLease consults before generating a JIT config for a new runner. internal/diskguard.Guard satisfies it: NeedsReclaim is a cheap per-filesystem statfs (no volume walking, no Measure), Sweep does the actual reclaim work when needed.

type JobAcquirer added in v0.15.0

type JobAcquirer interface {
	AcquireJobs(ctx context.Context, requestIDs []int64) ([]int64, error)
}

JobAcquirer claims the jobs a message offers. The listener's message session client satisfies it.

type MessageHandler added in v0.15.0

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

MessageHandler passes one listener session's messages to a controller, doing what the SDK listener did itself before v0.5.0. The listener now acks a message only after Scale returns nil, so an error leaves the message to be delivered again instead of losing it.

Jobs are acquired first, so a failed acquire leaves nothing half handled, and acquiring an already acquired job again is a no-op. Job starts and completions follow, then the desired runner count, which clears the completion barrier they set. An idle poll carries no message; the last statistics then refresh the desired count, which the controller needs to resume scaling after a runner exits without a completion message.

Scale is not safe for concurrent use; the listener never calls it concurrently.

func NewMessageHandler added in v0.15.0

func NewMessageHandler(acquirer JobAcquirer, s *ScaleSetController, recorder *metrics.Recorder, logger *slog.Logger) *MessageHandler

NewMessageHandler returns a handler for one listener session.

func (*MessageHandler) Scale added in v0.15.0

Scale handles one poll result: a message, or nil for an idle poll.

type Option

type Option func(*ScaleSetController)

Option configures optional ScaleSetController behavior at construction time.

func WithCapacityAllocator

func WithCapacityAllocator(a *capacity.Allocator) Option

WithCapacityAllocator shares a process-wide runner limit with other scale set controllers. The manager registers every scale set before starting any controller so minimum reservations are effective from the beginning.

func WithDiagnostics added in v0.13.0

func WithDiagnostics(store *diagnostics.Store, scaleSet, kind string, secrets ...string) Option

func WithDiskChecker

func WithDiskChecker(c DiskChecker) Option

WithDiskChecker wires a pre-job-start disk-pressure check into the ScaleSetController: startInstanceWithLease consults it before starting a new runner and reclaims first if free space is low. Omitting this option (the default) leaves diskChecker nil, so the check is skipped entirely.

func WithRetry added in v0.13.0

func WithRetry(settings config.RetryConfig) Option

type ScaleSetClient

type ScaleSetClient interface {
	GenerateJitRunnerConfig(ctx context.Context, setting *scaleset.RunnerScaleSetJitRunnerSetting, scaleSetID int) (*scaleset.RunnerScaleSetJitRunnerConfig, error)
	RemoveRunner(ctx context.Context, runnerID int64) error
}

ScaleSetClient abstracts the GitHub scale-set client methods used by the controller.

type ScaleSetController

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

ScaleSetController makes scaling decisions from the listener messages MessageHandler passes it and manages runner lifecycle via a pluggable InstanceProvider.

func NewScaleSetController

func NewScaleSetController(scaleSetID, minRunners, maxRunners int, p provider.InstanceProvider, client ScaleSetClient, logger *slog.Logger, opts ...Option) *ScaleSetController

NewScaleSetController creates a controller for one GitHub runner scale set. See WithDiskChecker for the optional pre-start capacity check.

func (*ScaleSetController) Drain

func (s *ScaleSetController) Drain(ctx context.Context) error

Drain stops taking new work and waits for in-flight jobs and runner cleanup. Apparently idle runners are deregistered before their instances are removed, so GitHub can retain runners it assigned before JobStarted arrived. Failed cleanup is retried until it succeeds or ctx expires.

The listener must remain running while this method waits: JobCompleted messages delivered through the listener are what move busy runners to zero. The caller should cancel the listener only after Drain returns, then invoke Shutdown to force-remove anything left after a deadline or removal failure.

func (*ScaleSetController) HandleDesiredRunnerCount

func (s *ScaleSetController) HandleDesiredRunnerCount(ctx context.Context, count int) (int, error)

HandleDesiredRunnerCount records the latest demand and wakes the background reconciler. Provider and GitHub API I/O never blocks the listener callback. Completed runners are removed directly; fresh lower demand also converges surplus idle runners without preempting busy jobs.

func (*ScaleSetController) HandleJobCompleted

func (s *ScaleSetController) HandleJobCompleted(ctx context.Context, jobInfo *scaleset.JobCompleted) error

HandleJobCompleted removes the runner after job finishes.

func (*ScaleSetController) HandleJobStarted

func (s *ScaleSetController) HandleJobStarted(ctx context.Context, jobInfo *scaleset.JobStarted) error

HandleJobStarted marks a runner as busy when a job is assigned.

func (*ScaleSetController) InstanceCounts

func (s *ScaleSetController) InstanceCounts() (idle, busy int)

InstanceCounts returns the number of idle and busy runners.

func (*ScaleSetController) InstanceLifecycleCounts

func (s *ScaleSetController) InstanceLifecycleCounts() (provisioning, idle, busy, removing int)

InstanceLifecycleCounts exposes the complete controller state machine for health reporting without changing the older idle/busy counter contract.

func (*ScaleSetController) RuntimeStatus added in v0.11.0

func (s *ScaleSetController) RuntimeStatus() metrics.RuntimeStatus

RuntimeStatus reports provisioning state without provider or GitHub I/O. Historical failures do not degrade a scale set whose demand is satisfied, and a normal wait for global host capacity is not an operational failure.

func (*ScaleSetController) Shutdown

func (s *ScaleSetController) Shutdown(ctx context.Context)

Shutdown force-removes all managed runners in parallel. The provided context should already be detached from cancellation (e.g. via context.WithoutCancel); this method adds a timeout to prevent hanging if a provider operation is unresponsive.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL