engine

Documentation

Overview

Package engine is the merge-queue reconcile loop: rollup batching with bisection. It keeps a work queue of candidate batches (lists of PR numbers). Each cycle it tests one candidate on a fresh staging branch; on success the whole batch lands, on failure a multi-PR batch is split in half (bisection) to isolate the culprit while letting the good PRs through. Staging conflicts split at the conflict point so earlier PRs keep their place in the queue.

Index

• type CheckpointStore
• type Config
• type Engine
  • func New(cfg Config, fc ForgeAPI, st Stager) *Engine
  • func (e *Engine) Reconcile(ctx context.Context) error
• type ForgeAPI
• type QueueLease
• type Stager

Types

type CheckpointStore

type CheckpointStore interface {
	LoadQueue(ctx context.Context, key checkpoint.QueueKey) (checkpoint.QueueSnapshot, bool, error)
	SaveQueue(ctx context.Context, snapshot checkpoint.QueueSnapshot) error
	DeleteQueue(ctx context.Context, key checkpoint.QueueKey) error
}

CheckpointStore persists queue snapshots for one engine-managed queue.

type Config

type Config struct {
	Owner         string
	Repo          string
	Base          string
	StatusCtx     string // required commit-status context, e.g. "merge-queue"
	MergeStyle    string // fallback merge style when restoring a consumed schedule
	StagingBranch string // staging branch prefix, e.g. "mq/main/staging"
	InstanceURL   string // used for API/git (may be an in-cluster URL)
	PublicURL     string // used for user-facing links (defaults to InstanceURL)
	MaxBatch      int    // cap the initial rollup size (0 = unlimited)
	BatchLinger   time.Duration
	BatchTarget   int
	BisectFanout  int // max concurrent bisection staging runs (0 = 1)
	QueueComments bool
	BotUser       string
	// ConfigSource describes whether this queue's settings came from a repo-level
	// .shunt.yml file ("repo") or from process-global defaults ("default").
	// Safe to expose in the /status JSON.
	ConfigSource  string
	Metrics       *metrics.Collector
	Checkpoint    CheckpointStore
	Lease         QueueLease
	LeaseHolderID string
	LeaseTTL      time.Duration
	Logger        *slog.Logger
}

type Engine

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

func New

func New(cfg Config, fc ForgeAPI, st Stager) *Engine

func (*Engine) Reconcile

func (e *Engine) Reconcile(ctx context.Context) error

Reconcile advances the queue by one step. Safe to call on a fixed interval.

type ForgeAPI

type ForgeAPI interface {
	ListOpenPRs(ctx context.Context, owner, repo, base string) ([]forge.PullRequest, error)
	GetPR(ctx context.Context, owner, repo string, index int) (forge.PullRequest, error)
	AutomergeState(ctx context.Context, owner, repo string, index int) (forge.AutomergeState, error)
	LatestCommitStatus(ctx context.Context, owner, repo, sha, statusContext string) (forge.CommitStatus, bool, error)
	RunStatus(ctx context.Context, owner, repo, sha, branch string) (string, error)
	RunTargetURL(ctx context.Context, owner, repo, sha, branch string) (string, error)
	SetCommitStatus(ctx context.Context, owner, repo, sha, context, state, desc, targetURL string) error
	ScheduleAutomerge(ctx context.Context, owner, repo string, index int, style, headSHA string) (forge.ScheduleAutomergeResult, error)
	CancelAutomerge(ctx context.Context, owner, repo string, index int) (bool, error)
	DeleteBranch(ctx context.Context, owner, repo, branch string) error
	UpsertComment(ctx context.Context, owner, repo string, index int, marker, botUser, body string) error
}

ForgeAPI is the subset of the forge client the engine needs (interface so the reconcile/bisection logic is unit-testable with a mock).

type QueueLease

type QueueLease interface {
	AcquireLease(ctx context.Context, key checkpoint.QueueKey, holderID string, ttl time.Duration) (bool, error)
}

QueueLease atomically acquires or renews exclusive ownership of one queue. Implementations that coordinate multiple replicas must use a durable store.

type Stager

type Stager interface {
	BuildStaging(ctx context.Context, base, stagingBranch string, refs []gitops.MergedRef) (sha string, conflictPR int, err error)
}

Stager builds an integration ("staging") branch from a base + PR head refs.