Documentation
¶
Index ¶
- type DiskChecker
- type JobAcquirer
- type MessageHandler
- type Option
- type ScaleSetClient
- type ScaleSetController
- func (s *ScaleSetController) Drain(ctx context.Context) error
- func (s *ScaleSetController) HandleDesiredRunnerCount(ctx context.Context, count int) (int, error)
- func (s *ScaleSetController) HandleJobCompleted(ctx context.Context, jobInfo *scaleset.JobCompleted) error
- func (s *ScaleSetController) HandleJobStarted(ctx context.Context, jobInfo *scaleset.JobStarted) error
- func (s *ScaleSetController) InstanceCounts() (idle, busy int)
- func (s *ScaleSetController) InstanceLifecycleCounts() (provisioning, idle, busy, removing int)
- func (s *ScaleSetController) RuntimeStatus() metrics.RuntimeStatus
- func (s *ScaleSetController) Shutdown(ctx context.Context)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DiskChecker ¶
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
func (h *MessageHandler) Scale(ctx context.Context, msg *scaleset.RunnerScaleSetMessage) error
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 ¶
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 ¶
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.