claim

type ClaimRef struct {
	Ref        string `json:"ref"`
	Sha        string `json:"sha"`
	Cluster    string `json:"cluster"`
	TaskID     string `json:"task_id"`
	LeaseUntil string `json:"lease_until"`
}

type ClaimRefClient interface {
	// List returns every claim ref whose path is prefix or lies under it as a
	// whole path component. prefix is passed as the ?prefix= query value.
	List(ctx context.Context, prefix string) ([]ClaimRef, error)
	// Put creates or replaces the claim at key by compare-and-swap. An empty
	// expectedSha means "must not exist". It returns the new sha from the
	// server response. A 409 is ErrLeaseConflict.
	Put(
		ctx context.Context,
		key string,
		expectedSha string,
		cluster string,
		taskID string,
		leaseUntil libtime.DateTime,
	) (string, error)
	// Delete removes the claim at key by compare-and-swap. A 409 is
	// ErrLeaseConflict.
	Delete(ctx context.Context, key string, expectedSha string) error
}

type HeldClaim struct {
	Key        string
	TaskID     string
	Sha        string
	LeaseUntil libtime.DateTime
}

type JobControl interface {
	// IsJobRunning reports whether a non-terminal Job exists for taskID.
	IsJobRunning(ctx context.Context, taskID string) (bool, error)
	// DeleteJob deletes the Job for taskID. Deleting an absent Job is not an
	// error (idempotent).
	DeleteJob(ctx context.Context, taskID string) error
}

type LeaseManager interface {
	Claim(ctx context.Context, key string, taskID string) (*HeldClaim, error)
	Release(ctx context.Context, key string) error
	Takeover(ctx context.Context, key string, taskID string) (*TakeoverResult, error)
	Tick(ctx context.Context) error
	Run(ctx context.Context) error
	Recover(ctx context.Context) error
	// HeldClaims returns a snapshot sorted by Key. Claims in pending Job
	// deletion or pending release are included: they are still held until the
	// pending action completes or the fence drops them.
	HeldClaims() []HeldClaim
	// AuditMismatch compares the claims this manager holds with the given set of
	// running Job task ids. It adds 1 to executor_claim_mismatch_total for every
	// running Job with no held claim and for every held claim with no running
	// Job, and logs which case each was. A task present in both is not counted.
	AuditMismatch(ctx context.Context, runningTaskIDs map[string]bool)
}

type TakeoverResult struct {
	Key            string
	TaskID         string
	Sha            string
	LeaseUntil     libtime.DateTime
	PreviousTaskID string
}