backend

Documentation

Index

• func FormatBytes(b uint64) string
• type CommandRunner
• type DockerAPI
• type DockerBackend
  • func NewDockerBackend(ss config.ScaleSetConfig, client DockerAPI, logger *slog.Logger) *DockerBackend
  • func (b *DockerBackend) RemoveRunner(ctx context.Context, resourceID string) error
  • func (b *DockerBackend) Shutdown(ctx context.Context)
  • func (b *DockerBackend) StartRunner(ctx context.Context, name string, jitConfig string) (string, error)
• type RunnerBackend
• type TartBackend
  • func NewTartBackend(ss config.ScaleSetConfig, logger *slog.Logger) *TartBackend
  • func (b *TartBackend) EnsureImage(ctx context.Context) error
  • func (b *TartBackend) RemoveRunner(ctx context.Context, resourceID string) error
  • func (b *TartBackend) Shutdown(ctx context.Context)
  • func (b *TartBackend) StartPool(ctx context.Context)
  • func (b *TartBackend) StartRunner(ctx context.Context, name string, jitConfig string) (string, error)

Functions

func FormatBytes

func FormatBytes(b uint64) string

FormatBytes formats a byte count into a human-readable string.

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.

type DockerAPI

type DockerAPI interface {
	ContainerCreate(ctx context.Context, config *container.Config, hostConfig *container.HostConfig, networkingConfig *network.NetworkingConfig, platform *ocispec.Platform, containerName string) (container.CreateResponse, error)
	ContainerStart(ctx context.Context, containerID string, options container.StartOptions) error
	ContainerRemove(ctx context.Context, containerID string, options container.RemoveOptions) error
	ImagesPrune(ctx context.Context, pruneFilters filters.Args) (image.PruneReport, error)
	BuildCachePrune(ctx context.Context, opts build.CachePruneOptions) (*build.CachePruneReport, error)
	VolumeRemove(ctx context.Context, volumeID string, force bool) error
}

DockerAPI abstracts the Docker client methods used by DockerBackend, enabling dependency injection and testing.

type DockerBackend

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

DockerBackend runs GitHub Actions runners as Docker containers.

func NewDockerBackend

func NewDockerBackend(ss config.ScaleSetConfig, client DockerAPI, logger *slog.Logger) *DockerBackend

NewDockerBackend creates a DockerBackend from scale set config.

func (*DockerBackend) RemoveRunner

func (b *DockerBackend) RemoveRunner(ctx context.Context, resourceID string) error

RemoveRunner force-removes a Docker container by ID.

func (*DockerBackend) Shutdown

func (b *DockerBackend) Shutdown(ctx context.Context)

Shutdown removes the shared Docker volume and prunes dangling resources.

func (*DockerBackend) StartRunner

func (b *DockerBackend) StartRunner(ctx context.Context, name string, jitConfig string) (string, error)

StartRunner creates and starts a new ephemeral Docker container runner.

type RunnerBackend

type RunnerBackend interface {
	// StartRunner creates and starts a new ephemeral runner with the given
	// name and JIT configuration. Returns a resource ID used for cleanup.
	StartRunner(ctx context.Context, name string, jitConfig string) (resourceID string, err error)

	// RemoveRunner stops and removes a runner by its resource ID.
	RemoveRunner(ctx context.Context, resourceID string) error

	// Shutdown performs backend-specific cleanup (prune images, remove volumes, etc.).
	Shutdown(ctx context.Context)
}

RunnerBackend abstracts runner lifecycle operations across different execution backends (Docker containers, Tart VMs, etc.).

type TartBackend

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

TartBackend 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
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. StartRunner picks a warm VM from the pool (near-instant) instead of cold-starting one (~30s). The pool is refilled in the background.

func NewTartBackend

func NewTartBackend(ss config.ScaleSetConfig, logger *slog.Logger) *TartBackend

NewTartBackend creates a TartBackend from scale set config.

func (*TartBackend) EnsureImage

func (b *TartBackend) EnsureImage(ctx context.Context) error

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

func (*TartBackend) RemoveRunner

func (b *TartBackend) RemoveRunner(ctx context.Context, resourceID string) error

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

func (*TartBackend) Shutdown

func (b *TartBackend) Shutdown(ctx context.Context)

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

func (*TartBackend) StartPool

func (b *TartBackend) StartPool(ctx context.Context)

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

func (*TartBackend) StartRunner

func (b *TartBackend) StartRunner(ctx context.Context, name string, jitConfig string) (string, error)

StartRunner 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).