provider

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: 37 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// ManagedByLabel and ManagedByValue tag every container runner creates;
	// the label is the primary ownership signal for containers.
	ManagedByLabel = "managed-by"
	ManagedByValue = "runner"
)

Variables

View Source
var (
	ErrReadinessDisabled    = errors.New("readiness_disabled")
	ErrReadinessTimeout     = errors.New("readiness_timeout")
	ErrReadinessUnavailable = errors.New("readiness_unavailable")
	ErrExitedBeforeReady    = errors.New("runner_exited_before_ready")
)

Functions

func AcquireTartInspectionLock added in v0.22.1

func AcquireTartInspectionLock(ctx context.Context, home string) (func(), error)

AcquireTartInspectionLock serializes temporary guest inspection and orphan cleanup in one Tart home. It is separate from the manager's lifetime lock, so validate can inspect images while a manager runs. The persistent lock file must not be unlinked: all processes must contend on the same inode.

func CleanupWorkspaceRoot added in v0.18.1

func CleanupWorkspaceRoot(root string, remaining []container.Summary) error

CleanupWorkspaceRoot reclaims private directories left when the previous manager exited before it could finish runner cleanup. Call only after the machine-wide lock is held and orphan containers were removed successfully.

func CleanupWorkspaceVolumes added in v0.20.1

func CleanupWorkspaceVolumes(ctx context.Context, client RunnerCleanupAPI) error

CleanupWorkspaceVolumes reclaims local volumes left by a crashed manager after runner reconciliation. A surviving bind or named-volume reference keeps the volume; no unrelated volume is touched.

func EnsureTartImage added in v0.22.0

func EnsureTartImage(ctx context.Context, runner CommandRunner, image string, logger *slog.Logger) error

EnsureTartImage checks if image exists locally through runner, and pulls it if not. It needs no TartProvider, so a preflight can check an image without building one.

func KeepVMName added in v0.14.0

func KeepVMName() string

KeepVMName names the throwaway clone a cache prune makes to mark a runner image as recently used (see cachestore's Tart store).

func NewRunnerName added in v0.14.0

func NewRunnerName() string

NewRunnerName names one ephemeral runner container or VM.

func OwnsContainer added in v0.14.0

func OwnsContainer(labels map[string]string, names []string) bool

OwnsContainer reports whether a listed container is runner's: labelled by the current release, or named by one whose label value differed. Docker lists names with a leading slash.

func OwnsTartVM added in v0.14.0

func OwnsTartVM(vm TartVM) bool

OwnsTartVM reports whether a listed Tart VM is runner's: a local VM named as an ephemeral runner, a warm-pool VM or a cache-prune marker clone. OCI cache entries are never owned, whatever they are called.

func RemoveRunnerContainer added in v0.17.0

func RemoveRunnerContainer(ctx context.Context, client RunnerCleanupAPI, instanceID string, logger *slog.Logger) error

RemoveRunnerContainer stops a runner, removes containers explicitly tied to it, then removes the runner itself. Keep the stopped runner's metadata until child cleanup succeeds so name-based ownership survives a retry. Anonymous volumes and explicitly owned temporary named volumes are reclaimed; shared/cache volumes, images, and daemon build caches are preserved.

func TartHomeDir added in v0.22.0

func TartHomeDir(home string) (string, error)

TartHomeDir resolves the directory tart keeps VMs under: home, then $TART_HOME, then ~/.tart.

func TartImagePresent added in v0.22.0

func TartImagePresent(ctx context.Context, runner CommandRunner, image string) (bool, error)

TartImagePresent reports whether Tart already has image locally.

Types

type CommandRunner

type CommandRunner interface {
	Run(ctx context.Context, name string, args ...string) ([]byte, error)
	// RunStreaming executes a command with stdout/stderr piped to the terminal.
	// Used for long-running commands where progress output is important (e.g. tart pull).
	RunStreaming(ctx context.Context, name string, args ...string) error
}

CommandRunner abstracts shell command execution for testability.

func TartCommandRunner added in v0.14.0

func TartCommandRunner(home string) CommandRunner

TartCommandRunner runs tart against home, or against tart's default ($HOME/.tart) when home is empty.

type DockerAPI

type DockerAPI interface {
	RunnerCleanupAPI
	ImageInspect(ctx context.Context, image string, options ...dockerclient.ImageInspectOption) (dockerclient.ImageInspectResult, error)
	ImagePull(ctx context.Context, ref string, options dockerclient.ImagePullOptions) (dockerclient.ImagePullResponse, error)
	VolumeCreate(ctx context.Context, options dockerclient.VolumeCreateOptions) (dockerclient.VolumeCreateResult, error)
	ContainerCreate(ctx context.Context, options dockerclient.ContainerCreateOptions) (dockerclient.ContainerCreateResult, error)
	ContainerStart(ctx context.Context, containerID string, options dockerclient.ContainerStartOptions) (dockerclient.ContainerStartResult, error)
	ContainerWait(ctx context.Context, containerID string, options dockerclient.ContainerWaitOptions) dockerclient.ContainerWaitResult
	// ContainerLogs feeds readiness detection and failure diagnostics.
	ContainerLogs(ctx context.Context, containerID string, options dockerclient.ContainerLogsOptions) (dockerclient.ContainerLogsResult, error)
	// ContainerInspect reports whether a runner is still running and how it
	// exited.
	ContainerInspect(ctx context.Context, containerID string, options dockerclient.ContainerInspectOptions) (dockerclient.ContainerInspectResult, error)
}

DockerAPI is the slice of the Docker client DockerProvider itself uses to run, watch and diagnose runner containers. internal/cachestore declares its own interface for the daemon-maintenance calls it needs.

type DockerImagePullCoordinator added in v0.21.0

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

DockerImagePullCoordinator shares in-flight pulls for the same Docker daemon, image, and platform.

func NewDockerImagePullCoordinator added in v0.21.0

func NewDockerImagePullCoordinator() *DockerImagePullCoordinator

type DockerProvider

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

DockerProvider runs GitHub Actions runners as Docker containers.

func NewDockerProvider

func NewDockerProvider(ss config.ScaleSetConfig, client DockerAPI, logger *slog.Logger) *DockerProvider

NewDockerProvider creates a DockerProvider from scale set config.

func NewDockerProviderWithCoordinator added in v0.21.0

func NewDockerProviderWithCoordinator(ss config.ScaleSetConfig, client DockerAPI, logger *slog.Logger, coordinator *DockerImagePullCoordinator) *DockerProvider

NewDockerProviderWithCoordinator shares missing-image pulls across Docker scale sets. A nil coordinator gives the provider a private coordinator.

func (*DockerProvider) CollectDiagnostics added in v0.13.0

func (p *DockerProvider) CollectDiagnostics(ctx context.Context, id string) (ExitDiagnostics, error)

func (*DockerProvider) EnableDiagnosticLogs added in v0.13.0

func (p *DockerProvider) EnableDiagnosticLogs(enabled bool)

EnableDiagnosticLogs opts into collecting a bounded raw excerpt. Call before starting workers. Redaction and private persistence remain the caller's job.

func (*DockerProvider) RemoveInstance

func (p *DockerProvider) RemoveInstance(ctx context.Context, instanceID string) error

RemoveInstance removes a runner and its explicitly owned child resources.

func (*DockerProvider) Shutdown

func (p *DockerProvider) Shutdown(_ context.Context)

Shutdown is a no-op for DockerProvider. Nothing shared is reclaimed at exit: the shared volume carries handoff data for runs still in flight across a restart, and images and build cache belong to the daemon, not to this process. Every one of them is reclaimed on its own schedule instead, through internal/cachestore — the periodic sweepers in cmd/runner and the disk guard. A per-provider Shutdown that touched any of it would also race the other scale sets sharing this Docker client.

func (*DockerProvider) StartInstance

func (p *DockerProvider) StartInstance(ctx context.Context, name string, jitConfig string) (string, error)

StartInstance creates and starts a new ephemeral Docker container runner.

func (*DockerProvider) WaitInstance

func (p *DockerProvider) WaitInstance(ctx context.Context, instanceID string) error

WaitInstance returns when a runner container is no longer running. The controller uses this to evict containers that crash before GitHub can send JobCompleted.

func (*DockerProvider) WaitReady added in v0.13.0

func (p *DockerProvider) WaitReady(parent context.Context, id string) error

type ExitDiagnostics added in v0.13.0

type ExitDiagnostics struct {
	ExitCode   *int       `json:"exit_code,omitempty"`
	OOMKilled  *bool      `json:"oom_killed,omitempty"`
	FinishedAt *time.Time `json:"finished_at,omitempty"`
	// RawLog is private collection input. It is never serialized directly.
	RawLog string `json:"-"`
}

type InstanceDiagnostics added in v0.13.0

type InstanceDiagnostics interface {
	CollectDiagnostics(context.Context, string) (ExitDiagnostics, error)
}

type InstanceProvider

type InstanceProvider interface {
	// StartInstance creates and starts a new ephemeral runner with the given
	// name and JIT configuration. Returns an instance ID used for cleanup.
	StartInstance(ctx context.Context, name string, jitConfig string) (instanceID string, err error)

	// RemoveInstance stops and removes a runner by its instance ID. It must be
	// idempotent (an already-absent instance is success) and must honor ctx so
	// controller drain and shutdown deadlines remain bounded.
	RemoveInstance(ctx context.Context, instanceID string) error

	// Shutdown performs provider-specific cleanup.
	Shutdown(ctx context.Context)
}

InstanceProvider provisions and removes the isolated instance that hosts one ephemeral GitHub Actions runner (a Docker container or Tart VM).

type InstanceReadiness added in v0.13.0

type InstanceReadiness interface {
	WaitReady(context.Context, string) error
}

InstanceReadiness is optional. Resource creation and readiness are distinct: a returned ID stays tracked until readiness, work evidence or safe cleanup.

type InstanceWatcher

type InstanceWatcher interface {
	WaitInstance(ctx context.Context, instanceID string) error
}

InstanceWatcher is optionally implemented by providers that can observe an instance exiting independently of GitHub job messages. A nil return means the instance stopped; a non-nil error means observation failed or the context ended.

type RunnerCleanupAPI added in v0.17.0

RunnerCleanupAPI is the lifecycle-only surface needed to remove a runner and its explicitly owned resources. Daemon pruning remains in cachestore.

type TartGuest added in v0.22.0

type TartGuest int

TartGuest is the guest operating system of a Tart image. The zero value is macOS, so an unknown guest is always held to Apple's limit.

const (
	TartGuestMacOS TartGuest = iota
	TartGuestLinux
)

func DetectTartGuest added in v0.22.0

func DetectTartGuest(ctx context.Context, runner CommandRunner, home, image string) (TartGuest, error)

DetectTartGuest reads the guest OS from a temporary clone of image. OCI image references have no local config.json until Tart clones them.

func (TartGuest) String added in v0.22.0

func (g TartGuest) String() string

String returns "macos" or "linux".

type TartHostCoordinator

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

TartHostCoordinator limits macOS guests and gives every Tart VM a unique MAC slot across all scale sets in this process.

func NewTartHostCoordinator

func NewTartHostCoordinator(macOSLimit int) *TartHostCoordinator

type TartProvider

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

TartProvider runs GitHub Actions runners as ephemeral Tart macOS VMs.

Lifecycle per runner:

  1. tart clone <baseImage> <name> — APFS CoW clone (< 1 sec)
  2. tart set <name> --cpu/--memory — configure VM resources (if specified)
  3. Set deterministic MAC address — prevent DHCP lease exhaustion
  4. tart run <name> --no-graphics — boot VM in background goroutine (--net-bridged=<interface> when configured)
  5. tart exec <name> true — poll until Guest Agent is ready
  6. tart exec <name> ... run.sh — start runner with JIT config
  7. tart stop + tart delete on removal

When poolSize > 0, VMs are pre-booted and kept ready in a pool. StartInstance picks a warm VM from the pool (near-instant) instead of cold-starting one (~30s). The pool is refilled in the background.

func NewTartProviderWithCoordinator

func NewTartProviderWithCoordinator(ss config.ScaleSetConfig, logger *slog.Logger, coordinator *TartHostCoordinator, guest TartGuest) *TartProvider

NewTartProviderWithCoordinator creates a TartProvider from scale set config. coordinator is shared by every Tart scale set on the host so MAC slots and the two-VM limit are host-wide; nil gets a private one.

func (*TartProvider) EnsureImage

func (p *TartProvider) EnsureImage(ctx context.Context) error

EnsureImage checks if the base image exists locally, and pulls it if not.

func (*TartProvider) RemoveInstance

func (p *TartProvider) RemoveInstance(ctx context.Context, instanceID string) error

RemoveInstance stops and deletes a Tart VM, releasing its VM slot.

func (*TartProvider) Shutdown

func (p *TartProvider) Shutdown(ctx context.Context)

Shutdown stops the warm pool and cleans up any idle VMs.

func (*TartProvider) StartInstance

func (p *TartProvider) StartInstance(ctx context.Context, name string, jitConfig string) (string, error)

StartInstance starts a GitHub Actions runner in a Tart VM. If a warm pool is available, picks a pre-booted VM (near-instant). Otherwise, cold-starts a new VM (~30s).

func (*TartProvider) StartPool

func (p *TartProvider) StartPool(ctx context.Context)

StartPool begins pre-warming VMs in the background. Call this after EnsureImage and before the listener starts.

func (*TartProvider) WaitInstance

func (p *TartProvider) WaitInstance(ctx context.Context, instanceID string) error

type TartVM added in v0.14.0

type TartVM struct {
	Name   string `json:"Name"`
	Source string `json:"Source"` // "local" for VMs, "OCI" for cached images
	State  string `json:"State"`
}

TartVM is one entry of `tart list --format json`.

func ListTartVMs added in v0.14.0

func ListTartVMs(ctx context.Context, runner CommandRunner, extra ...string) ([]TartVM, error)

ListTartVMs lists every VM and cached image visible through runner. extra narrows the listing with further `tart list` flags, such as "--source", "oci".

Jump to

Keyboard shortcuts

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