runner

package
v1.10.21 Latest Latest
Warning

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

Go to latest
Published: Oct 25, 2026 License: AGPL-3.0 Imports: 15 Imported by: 0

Documentation

Overview

Package runner manages build/pipeline runner records: registration, scope (workspace-owned vs platform-shared), labels, concurrency and reachability. Runners are dedicated build machines that never host apps, dialing in over an outbound tunnel with a tightly-scoped registration token.

Index

Constants

View Source
const BuiltinRunnerName = "builtin"

BuiltinRunnerName is the reserved handle of the co-located built-in runner.

Variables

View Source
var (
	ErrNotFound     = errors.New("runner not found")
	ErrNameRequired = errors.New("runner name is required")
	ErrNameTaken    = errors.New("a runner with that name already exists")
	ErrBadToken     = errors.New("invalid runner token")
)
View Source
var ErrNoRunner = errors.New("no eligible runner available")

ErrNoRunner is returned when no connected, eligible runner can take a job right now. The caller queues the run in a "waiting for a runner" state rather than falling back to building on a hosting node.

Functions

This section is empty.

Types

type ConnRegistry

type ConnRegistry interface {
	Connected(id uint) bool
}

ConnRegistry reports whether a runner currently has a live tunnel. Satisfied by runners.Manager; injected (via SetScheduling) to avoid an import cycle.

type Input

type Input struct {
	Name        string
	DisplayName string
	Labels      []string
	Concurrency int
}

Input is the mutable set of fields a create/update accepts. Scope-specific fields (WorkspaceID, Scope) are set by the caller, not bound from the request.

type Job

type Job struct {
	WorkspaceID      uint
	RequiredLabels   []string
	RequiredFeatures []string
	// MinVersion is the oldest runner release that can run the job, for capabilities that shipped before
	// runners advertised features. Empty means any version.
	MinVersion string
}

Job describes what a build/pipeline run needs from a runner: the tenant it belongs to, any required labels (arch/gpu/buildkit/…), and any features the runner must report supporting (multi-platform).

type Service

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

Service owns runner records and their registration tokens.

func NewService

func NewService(repo *repositories.RunnerRepository) *Service

func (*Service) Authenticate

func (s *Service) Authenticate(token string) (*models.Runner, error)

Authenticate resolves a runner from a presented registration token, constant-time comparing the hash. Used by the runner-gateway endpoint when a runner dials in. A disabled runner is rejected.

func (*Service) AvailabilityReason

func (s *Service) AvailabilityReason(job Job) string

AvailabilityReason explains why SelectRunner couldn't place job, so a waiting deploy/pipeline can tell the user what to fix instead of an opaque "waiting…". Returns "" when a runner is in fact schedulable (the caller shouldn't be here).

func (*Service) BoundBy added in v1.10.5

func (s *Service) BoundBy(id uint) ([]models.Plan, error)

BoundBy returns the plans that offer a shared runner, so deleting one a plan still names can be refused rather than silently narrowing that plan's pool.

func (*Service) CreateShared

func (s *Service) CreateShared(createdByID uint, in Input) (*models.Runner, string, error)

CreateShared registers a platform-shared runner (admin; nil workspace).

func (*Service) CreateWorkspace

func (s *Service) CreateWorkspace(workspaceID, createdByID uint, in Input) (*models.Runner, string, error)

CreateWorkspace registers a workspace-owned runner and returns the one-time registration token (shown once; only its hash is stored). Quota-checked against the workspace's MaxRunners.

func (*Service) DeleteShared

func (s *Service) DeleteShared(id uint) error

DeleteShared removes a platform-shared runner (admin).

func (*Service) DeleteWorkspace

func (s *Service) DeleteWorkspace(workspaceID, id uint) error

DeleteWorkspace removes a workspace-owned runner.

func (*Service) EnsureBuiltin

func (s *Service) EnsureBuiltin() (*models.Runner, string, error)

EnsureBuiltin finds or creates the platform-shared built-in runner and issues it a fresh registration token. The co-located container gets a new token each start, so a stale container's token is invalidated. Returns the runner and its one-time token.

func (*Service) Get added in v1.10.18

func (s *Service) Get(id uint) (*models.Runner, error)

Get fetches a runner of any scope, for callers that filter by owner themselves.

func (*Service) GetShared

func (s *Service) GetShared(id uint) (*models.Runner, error)

GetShared fetches one platform-shared runner (admin).

func (*Service) GetWorkspace

func (s *Service) GetWorkspace(workspaceID, id uint) (*models.Runner, error)

GetWorkspace fetches one of a workspace's own runners.

func (*Service) Image

func (s *Service) Image() string

Image returns the configured runner image, falling back to the current default when unset, so the enrollment command is always complete.

func (*Service) Lease

func (s *Service) Lease(runnerID uint, kind models.LeaseKind, runID uint, stepID *uint, deadline time.Time) (*models.RunnerLease, error)

Lease records a runner's at-most-once claim on a job (pipeline run or build, per kind) with the given deadline, so it counts against the runner's concurrency and a dead lease can be requeued. Returns the created lease.

func (*Service) ListShared

func (s *Service) ListShared() ([]models.Runner, error)

ListShared returns the platform-shared runner pool (admin view).

func (*Service) ListUsable

func (s *Service) ListUsable(workspaceID uint) ([]models.Runner, error)

ListUsable returns the runners a workspace's jobs may target: its own runners plus, when its plan grants the platform-runners capability, the shared runners that plan offers.

func (*Service) ListWorkspace

func (s *Service) ListWorkspace(workspaceID uint) ([]models.Runner, error)

ListWorkspace returns a workspace's own runners.

func (*Service) MarkConnected

func (s *Service) MarkConnected(id uint, f models.RunnerFacts)

MarkConnected records that a runner's tunnel is live: online status, a fresh last-seen, and its self-reported platform facts. Best-effort — a missing runner is ignored — so the connection manager can call it on connect and on each heartbeat without handling errors.

func (*Service) MarkDisconnected

func (s *Service) MarkDisconnected(id uint)

MarkDisconnected flips a runner offline when its tunnel drops. Best-effort.

func (*Service) RegenerateTokenShared

func (s *Service) RegenerateTokenShared(id uint) (string, error)

RegenerateTokenShared issues a fresh registration token for a shared runner.

func (*Service) RegenerateTokenWorkspace

func (s *Service) RegenerateTokenWorkspace(workspaceID, id uint) (string, error)

RegenerateTokenWorkspace issues a fresh registration token for a workspace-owned runner, invalidating the old one.

func (*Service) ReleaseRun

func (s *Service) ReleaseRun(kind models.LeaseKind, runID uint) error

ReleaseRun releases a job's active lease when it reaches a terminal state.

func (*Service) SelectRunner

func (s *Service) SelectRunner(job Job) (*models.Runner, error)

SelectRunner picks the best eligible runner for job, or ErrNoRunner when none can take it right now. Eligible means connected, enabled, not cordoned, labels superset of required, in scope (owned by the workspace or shared with plan permission), and active leases below declared concurrency.

func (*Service) SetCordoned

func (s *Service) SetCordoned(m *models.Runner, cordoned bool) error

SetCordoned holds a runner out of scheduling (or releases it) without disconnecting it. scope is enforced by the caller's Get*.

func (*Service) SetEnabled

func (s *Service) SetEnabled(m *models.Runner, enabled bool) error

SetEnabled toggles a runner's on/off switch (a disabled runner never receives jobs even while connected).

func (*Service) SetImage

func (s *Service) SetImage(image string)

SetImage records the configured miabi-runner image (MIABI_RUNNER_IMAGE) so the panel's generated `docker run` enrollment command uses the operator's image.

func (*Service) SetQuota

func (s *Service) SetQuota(q *quota.Service)

SetQuota wires the plan/quota enforcer (nil-safe; gates MaxRunners on create and the platform-runners capability on shared-pool use).

func (*Service) SetScheduling

func (s *Service) SetScheduling(conn ConnRegistry, leases *repositories.RunnerLeaseRepository)

SetScheduling wires the runtime the scheduler needs: the live-tunnel registry and the lease store (for concurrency accounting). Nil-safe.

func (*Service) SweepExpiredLeases

func (s *Service) SweepExpiredLeases(now time.Time) ([]models.RunnerLease, error)

SweepExpiredLeases marks every active lease past now as expired and returns them, so the caller can requeue their runs. Belt-and-suspenders for a runner that died without releasing its lease.

func (*Service) UpdateShared

func (s *Service) UpdateShared(id uint, in Input) (*models.Runner, error)

UpdateShared edits a platform-shared runner (admin).

func (*Service) UpdateWorkspace

func (s *Service) UpdateWorkspace(workspaceID, id uint, in Input) (*models.Runner, error)

UpdateWorkspace edits a workspace-owned runner's mutable fields.

func (*Service) UsableShared added in v1.10.5

func (s *Service) UsableShared(workspaceID uint) ([]models.Runner, error)

UsableShared returns just the shared runners a workspace may build on — its plan's slice of the pool. The tenant-facing list, so a workspace is never shown a runner its plan refuses.

Jump to

Keyboard shortcuts

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