Documentation
¶
Overview ¶
Package runner manages build/pipeline runner records: their registration, scope (workspace-owned vs platform-shared), labels/concurrency, and reachability. Runners are dedicated build machines — they never host apps — and dial in over an outbound tunnel with a tightly-scoped registration token (mirrors the node agent join token, distinct scope). Job leasing, the scheduler, and the runner binary land in later phases; this service owns the CRUD + token lifecycle they build on.
Index ¶
- Constants
- Variables
- type ConnRegistry
- type Input
- type Job
- type Service
- func (s *Service) Authenticate(token string) (*models.Runner, error)
- func (s *Service) AvailabilityReason(job Job) string
- func (s *Service) CreateShared(createdByID uint, in Input) (*models.Runner, string, error)
- func (s *Service) CreateWorkspace(workspaceID, createdByID uint, in Input) (*models.Runner, string, error)
- func (s *Service) DeleteShared(id uint) error
- func (s *Service) DeleteWorkspace(workspaceID, id uint) error
- func (s *Service) EnsureBuiltin() (*models.Runner, string, error)
- func (s *Service) GetShared(id uint) (*models.Runner, error)
- func (s *Service) GetWorkspace(workspaceID, id uint) (*models.Runner, error)
- func (s *Service) Image() string
- func (s *Service) Lease(runnerID uint, kind models.LeaseKind, runID uint, stepID *uint, ...) (*models.RunnerLease, error)
- func (s *Service) ListShared() ([]models.Runner, error)
- func (s *Service) ListUsable(workspaceID uint) ([]models.Runner, error)
- func (s *Service) ListWorkspace(workspaceID uint) ([]models.Runner, error)
- func (s *Service) MarkConnected(id uint, os, arch, version, remoteIP string)
- func (s *Service) MarkDisconnected(id uint)
- func (s *Service) RegenerateTokenShared(id uint) (string, error)
- func (s *Service) RegenerateTokenWorkspace(workspaceID, id uint) (string, error)
- func (s *Service) ReleaseRun(kind models.LeaseKind, runID uint) error
- func (s *Service) SelectRunner(job Job) (*models.Runner, error)
- func (s *Service) SetCordoned(m *models.Runner, cordoned bool) error
- func (s *Service) SetEnabled(m *models.Runner, enabled bool) error
- func (s *Service) SetImage(image string)
- func (s *Service) SetQuota(q *quota.Service)
- func (s *Service) SetScheduling(conn ConnRegistry, leases *repositories.RunnerLeaseRepository)
- func (s *Service) SweepExpiredLeases(now time.Time) ([]models.RunnerLease, error)
- func (s *Service) UpdateShared(id uint, in Input) (*models.Runner, error)
- func (s *Service) UpdateWorkspace(workspaceID, id uint, in Input) (*models.Runner, error)
Constants ¶
const BuiltinRunnerName = "builtin"
BuiltinRunnerName is the reserved handle of the co-located built-in runner.
Variables ¶
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") )
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 ¶
ConnRegistry reports whether a runner currently has a live tunnel. Satisfied by runners.Manager; injected (via SetScheduling) to avoid an import cycle.
type Input ¶
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 ¶
Job describes what a build/pipeline run needs from a runner: the tenant it belongs to and any required labels (arch/gpu/buildkit/…).
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 ¶
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 ¶
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) CreateShared ¶
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 ¶
DeleteShared removes a platform-shared runner (admin).
func (*Service) DeleteWorkspace ¶
DeleteWorkspace removes a workspace-owned runner.
func (*Service) EnsureBuiltin ¶
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) GetWorkspace ¶
GetWorkspace fetches one of a workspace's own runners.
func (*Service) Image ¶
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 ¶
ListShared returns the platform-shared runner pool (admin view).
func (*Service) ListUsable ¶
ListUsable returns the runners a workspace's jobs may target: its own runners plus, when its plan grants the platform-runners capability, the shared pool.
func (*Service) ListWorkspace ¶
ListWorkspace returns a workspace's own runners.
func (*Service) MarkConnected ¶
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 ¶
MarkDisconnected flips a runner offline when its tunnel drops. Best-effort.
func (*Service) RegenerateTokenShared ¶
RegenerateTokenShared issues a fresh registration token for a shared runner.
func (*Service) RegenerateTokenWorkspace ¶
RegenerateTokenWorkspace issues a fresh registration token for a workspace-owned runner, invalidating the old one.
func (*Service) ReleaseRun ¶
ReleaseRun releases a job's active lease when it reaches a terminal state.
func (*Service) SelectRunner ¶
SelectRunner picks the least-loaded eligible runner for job, or ErrNoRunner when none can take it right now. Eligibility is:
connected AND enabled AND not cordoned AND labels ⊇ required AND in scope (owned by the workspace, or shared + plan allows) AND active leases < declared concurrency
Among eligible runners the one with the fewest active leases wins (ties break toward the lower id for determinism).
func (*Service) SetCordoned ¶
SetCordoned holds a runner out of scheduling (or releases it) without disconnecting it. scope is enforced by the caller's Get*.
func (*Service) SetEnabled ¶
SetEnabled toggles a runner's on/off switch (a disabled runner never receives jobs even while connected).
func (*Service) SetImage ¶
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 ¶
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 ¶
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 ¶
UpdateShared edits a platform-shared runner (admin).
Source Files