controllers

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 29, 2026 License: AGPL-3.0 Imports: 37 Imported by: 0

Documentation

Overview

Package controllers is the dispatcher's controller runtime (keyed work queues, rate-limited retries, store informers) and its controllers, starting with catalog-sync.

Design: design/workstreams/dispatcher-runtime/LLD/controllers.md.

Index

Constants

View Source
const (
	DefaultCatalogRef  = "main"
	DefaultCatalogPath = "catalog"
)

Catalog-sync source defaults (the LLD's --catalog-* flags). There is no default repository: serve requires --catalog-repo or --catalog-dir.

View Source
const (
	// CatalogSyncKey is catalog-sync's only work-queue key.
	CatalogSyncKey = "catalog"
	// DefaultCatalogPollInterval is how often catalog-sync polls its source.
	DefaultCatalogPollInterval = 60 * time.Second
	// DefaultCatalogMaxErrors bounds the diagnostics kept in CatalogStatus.
	DefaultCatalogMaxErrors = 50
	// DefaultCatalogRetryBase is the first retry delay after the source couldn't be read;
	// retries back off exponentially up to the poll interval.
	DefaultCatalogRetryBase = time.Second
)

Catalog-sync defaults.

View Source
const (
	// MaxCredentialTTL caps a task's git credential (design/02 §Safety rails: ≤ 1h).
	MaxCredentialTTL = time.Hour

	// LabelTaskSpec is the Task label holding its TaskSpec name.
	LabelTaskSpec = "factory.ccf.dev/taskspec"
	// LLMAgentLocal is the only LLM credential mode: the agent's own harness login.
	LLMAgentLocal = "agent-local"
	// TrustUntrusted labels context the agent must treat as untrusted input.
	TrustUntrusted = "untrusted"
)

Task compilation defaults.

View Source
const (
	// DefaultListPageSize is the page size of an informer's (re)list.
	DefaultListPageSize = 500
	// DefaultInformerRetryBase and DefaultInformerRetryMax bound the backoff after a failed
	// list or watch.
	DefaultInformerRetryBase = 100 * time.Millisecond
	DefaultInformerRetryMax  = 30 * time.Second
)

Informer defaults.

View Source
const (
	// KindEventStatus marks an Event as processed by the rule controller. v1alpha1.Event has
	// no status, so the mark is a record named by the event id; it is deleted when its Event is.
	KindEventStatus = "EventStatus"
	// KindDebounce is a debounced rule's held actions (the LLD's internal Debounce object).
	KindDebounce = "Debounce"
	// KindTaskPrompt is a Task's rendered prompt (the LLD's blob prompt/<taskID>), named by the
	// task id. The agent fetches it through the API server.
	KindTaskPrompt = "TaskPrompt"
)

Internal kinds the controllers keep in the store. They are not part of v1alpha1 (no API, no schema): the store reaches their metadata through store.MetaObject.

View Source
const (
	// LeaderLock is the store lock whose holder runs the loops that write from a watch or a
	// timer: the controllers, the scheduler's lease controller and Refresh, the sweeper and the
	// installation check.
	LeaderLock = "leader"
	// DefaultLeaderTTL is the leader lock's lease.
	DefaultLeaderTTL = 3 * time.Minute
	// DefaultLeaderRenew is how often the holder renews the lock and every other instance tries
	// to take it.
	DefaultLeaderRenew = time.Minute
	// DefaultLeaderTry bounds each Lock and Renew call: Lock waits while another holder has
	// the lock.
	DefaultLeaderTry = 5 * time.Second
)

The leader lock (P3 §Several dispatchers: who runs what).

View Source
const (
	KindChannel = "channel"
	KindGroup   = "group"
	KindThread  = "thread"
)

Destination kinds an EffectRequest.Target can name besides issues and PRs.

View Source
const (
	DeliveryReceived   = "received"
	DeliveryNormalised = "normalised"
	// DeliveryFailed is a delivery the adapter rejected as invalid: it is never retried.
	DeliveryFailed = "failed"
)

Delivery phases.

View Source
const (
	// DropNoRule: no rule's on has the event's type for its provider (the rule's providers
	// included).
	DropNoRule = "no-rule"
	// DropOutOfScope: some rule's on and providers take the event, but none of their
	// RuleSets' scope (repos, exclude, branches, channels) holds its object.
	DropOutOfScope = "out-of-scope"
)

Why the intake filter dropped an event (the reason label of factory_events_dropped_total). It drops an event only when no work item links its object, no rule could fire for it and the factory didn't cause it.

View Source
const (
	DefaultBaseDelay = 5 * time.Millisecond
	DefaultMaxDelay  = 5 * time.Minute
	DefaultJitter    = 0.1
)

Backoff defaults (the LLD's 5 ms → 5 min exponential backoff with jitter).

View Source
const (
	ScopeGlobal   = "global"
	ScopeProvider = "provider"
	ScopeQueue    = "queue"
	ScopeWorkItem = "workitem"
)

Kill-switch scopes (the pause/resume command's target.scope).

View Source
const (
	RenderPrompt   = "prompt"   // a dispatch's prompt; Name is the TaskSpec
	RenderTemplate = "template" // a notify's GitHub body; Name is the Template
)

What a Rendered text is.

View Source
const (
	AbandonThrottled  = "throttled"
	AbandonAgentError = "agent-error"
	AbandonShutdown   = "shutdown"
)

Abandon reasons (the API's AbandonRequest.reason).

View Source
const (
	ReasonBudget        = "budget"
	ReasonInvalidResult = "invalid-result"
	ReasonTimeout       = "timeout"
	ReasonThrottled     = "agent-throttled"
	ReasonCancelled     = "cancelled"
)

Task and run failure reasons (Task.status.reason).

View Source
const DefaultDeliveryRetention = 24 * time.Hour

DefaultDeliveryRetention is how long a handled Delivery record that keeps an Event, or that failed, is kept. Duplicates arriving later are still deduped by their Events' ids. A delivery none of whose events was stored is deleted at once.

View Source
const DefaultInstallationCheckTimeout = time.Minute

DefaultInstallationCheckTimeout bounds one InstallationCheck.Check.

View Source
const DefaultLockTTL = 2 * time.Minute

DefaultLockTTL is the lease of a work item lock ("wi/<id>"). A reconcile holds it for one event; an expired lock is reclaimable, so a stuck holder can't block the item for long.

View Source
const DefaultObservationTTL = 30 * time.Second

DefaultObservationTTL is how long an observation is reused (the LLD's 30 s view cache).

View Source
const (
	// DefaultResyncInterval is how often a work item's links are re-observed when their
	// Provider sets no resync.every.
	DefaultResyncInterval = 10 * time.Minute
)

Work-item controller defaults.

View Source
const DefaultRuleIdentity = "author"

DefaultRuleIdentity is the factory identity that rule-level notifications and effects act as.

View Source
const DefaultRunCap = 20

DefaultRunCap is the hard maximum of tasks per work item that no rule can override.

View Source
const DefaultWallClockGrace = 2 * time.Minute

DefaultWallClockGrace is added to a TaskSpec's limits.maxWallClock before a run times out.

View Source
const DefaultWorkers = 2

DefaultWorkers is the default number of workers per controller.

View Source
const FactoryEventPrefix = v1alpha1.FactoryProvider + "/"

FactoryEventPrefix starts the id of every event the built-in factory provider emits.

View Source
const KindDelivery = "Delivery"

KindDelivery is a raw provider delivery, stored before the webhook is acknowledged and normalised into Events from the store (controllers.md §provider).

View Source
const KindKillSwitch = "KillSwitch"

KindKillSwitch is a pause flag set by the pause command (internal kind, no API, no schema). A record exists while its scope is paused; resume deletes it.

View Source
const KindLinkObservations = "LinkObservations"

KindLinkObservations holds a work item's resync baselines (internal store kind, no API, no schema): per link, the digest of its last observation, so a new leader, or one after a restart, compares with the last one any leader saw (P3 §Several dispatchers). It is named by the work item id, written only when a digest changes, and deleted with the item; the leader's sweep deletes one whose work item is gone. It holds digests and link refs only.

View Source
const LabelRule = "factory.ccf.dev/rule"

LabelRule is the label of an Effect record made by a rule: the rule's name.

View Source
const RenderUIBase = "https://factory.example"

RenderUIBase is the Factory UI base URL of links.ui in RenderEvaluation's Templates.

View Source
const StopLabel = "factory:stop"

StopLabel on any object linked to a work item stops the factory for that item (the per-item kill switch; design/02-architecture.md §Safety rails).

Variables

View Source
var (
	// ErrUnknownTask is a task id the store doesn't have (404).
	ErrUnknownTask = errors.New("unknown task")
	// ErrNotLeased is a task that has no lease to complete or abandon (409).
	ErrNotLeased = errors.New("task is not leased")
)

Errors of the run API, for the API server to map to HTTP statuses.

View Source
var ErrCatalogInvalid = errors.New("catalog is invalid")

ErrCatalogInvalid is wrapped by Sync when the source's catalog fails validation (the live catalog is kept).

View Source
var ErrInvalidDispatch = errors.New("invalid dispatch")

ErrInvalidDispatch is a dispatch that can't become a Task: the rule controller records it on the decision (not retried); Recompile returns it for a task the current catalog can't compile again.

View Source
var ErrLockDeadline = errors.New("work item lock section ran out of time")

ErrLockDeadline is returned when a section under a work item lock ran out of its time: it is retried, by which time the lease is free or reclaimable.

View Source
var ErrNoCatalog = errors.New("no catalog loaded yet")

ErrNoCatalog is a call that needs the live catalog before the first one has loaded.

View Source
var ErrNotInCatalog = errors.New("not in the catalog")

ErrNotInCatalog is an ErrInvalidDispatch whose TaskSpec or queue the catalog doesn't have.

View Source
var ErrReplayHistoryGone = errors.New("the event's earlier decisions are gone from its work item")

ErrReplayHistoryGone is a replay of an event whose earlier decision records aged out of its work item: which rules already fired is unknown, so nothing is replayed.

View Source
var ErrTaskLeased = errors.New("a task of the work item is leased")

ErrTaskLeased is DeleteWorkItem's refusal, without force, while one of the item's tasks is leased (Leased, Running or Cancelling).

Functions

func AddLink(wi *v1alpha1.WorkItem, ref v1alpha1.ObjectRef, fallback string) bool

AddLink adds ref to the work item unless it is linked already (same provider and ref), and reports whether it did. A ref without a provider is on the primary link's provider (else on fallback); one without a kind gets guessKind's. The new link is primary only when it is the item's first.

func CheckRunResult added in v0.3.0

func CheckRunResult(cat *catalog.Catalog, ev v1alpha1.Event) (string, error)

CheckRunResult validates the Result a factory.run.completed event's run fact carries against its TaskSpec's output schema in cat, as complete does. The Result is run.result read back (resultMap's inverse): its Result fields as they are, the others under data unless it has data, and the run's id, status and outcome where it lacks task, status and outcome. It returns the TaskSpec it checked against ("" when ev is another event or has no run.result) and the schema's error; a TaskSpec cat doesn't have is an error.

func CloseWorkItem

func CloseWorkItem(ctx context.Context, s store.Store, id string, closed v1alpha1.WorkItemClosed) (*v1alpha1.WorkItem, []string, error)

CloseWorkItem closes the work item id under its lock: it sets status.closed, appends a decision saying who closed it and why, and moves the item's active tasks (Pending, Leased, Running) to Cancelling, as the cancel command does (the run controller cancels a task no agent holds at once; an agent learns it from its next heartbeat). Closing a closed item updates its reason and note. It returns the item and the tasks it cancelled; a missing item is store.ErrNotFound.

func Closed

func Closed(wi *v1alpha1.WorkItem) bool

Closed reports whether an admin closed the work item (status.closed).

func GitHost

func GitHost(p *v1alpha1.Provider) string

GitHost is the git host of a Provider's repositories, which its tokens are for: for a github Provider, the host of spec.github.apiURL (github.com for api.github.com, the GHE host otherwise, as the token minter sets it). Other types, and nil, have none ("").

func IsPermanent

func IsPermanent(err error) bool

IsPermanent reports whether err, or an error it wraps, was marked with Permanent.

func KillSwitchName

func KillSwitchName(scope, name string) string

KillSwitchName is the record name of scope/name: "global", or "<scope>:<name>".

func LinkObject

func LinkObject(ctx context.Context, s store.Store, id string, ref v1alpha1.ObjectRef, fallback string) (bool, error)

LinkObject adds ref to the stored work item id (AddLink's rules) outside a rule evaluation: the Effector links the object an effect created. It re-reads and retries an update that lost to a concurrent writer (the store's optimistic concurrency), writes nothing when the ref is linked already, and is a no-op for a work item that's gone. It reports whether it added the link.

func NameKey

func NameKey(obj store.Object) []string

NameKey is the KeyFunc that reconciles the object itself, by name.

func Permanent

func Permanent(err error) error

Permanent marks err as permanent: retrying the key won't help (the provider refuses access, say), so the controller logs it once at WARN and drops the key instead of requeueing it. The key is reconciled again only when it is added again. Permanent(nil) is nil.

func RepoOnHost

func RepoOnHost(raw, host string) (repo string, ok bool)

RepoOnHost is the "owner/name" of an http(s) repository URL on host ("https://github.com/o/r" or ".../o/r.git" → "o/r"), with ok false for a URL on another host, with user info, a query or a fragment, or with a path that isn't exactly a repo.

func ResultSpec

func ResultSpec(cat *catalog.Catalog, t *v1alpha1.Task) *catalog.CompiledTaskSpec

ResultSpec is the TaskSpec a task's Result is validated against on complete: the task's TaskSpec, by name, in cat, the live catalog snapshot (the only one the dispatcher keeps; the task's own, provenance.catalogSHA, is gone after a reload). Nil when cat is nil or no longer has it: the Result is then checked against the outcomes only. getTaskOutputSchema serves this TaskSpec's OutputSchemaDocument, so an agent checks with what complete checks.

func ValidKillSwitchScope

func ValidKillSwitchScope(scope string) bool

ValidKillSwitchScope reports whether scope is one of the pause scopes.

Types

type Abandonment

type Abandonment struct {
	Reason  string
	Until   time.Time
	Message string
}

Abandonment is an agent giving a task back.

type Backoff

type Backoff struct {
	Base, Max time.Duration
	// Jitter is the fraction of the delay added at random (0.1 adds up to 10%); 0 disables it.
	Jitter float64
	// Rand returns a float in [0, 1); nil is math/rand/v2.Float64.
	Rand func() float64
}

Backoff is an exponential per-key retry delay: Base·2^(failures-1), plus up to Jitter of it at random, capped at Max.

func (Backoff) Delay

func (b Backoff) Delay(failures int) time.Duration

Delay returns the delay before retry number failures (1 for the first retry).

type CatalogProvider

type CatalogProvider interface {
	Current() *catalog.Catalog
}

CatalogProvider gives readers the live catalog snapshot. Snapshots are immutable and swapped whole, so a reader that calls Current once per unit of work sees one consistent catalog throughout. Current returns nil until the first good catalog has loaded: the dispatcher's startup waits for CatalogSync.Ready before starting the controllers that read it, so after startup it is never nil.

type CatalogSnapshotter

type CatalogSnapshotter interface {
	CatalogProvider
	Snapshot() (*catalog.Catalog, <-chan struct{})
}

CatalogSnapshotter is the live catalog and a channel closed at its next swap (*CatalogSync).

type CatalogSource

type CatalogSource interface {
	// Head returns the revision the source is at now: for git, the commit the configured
	// ref points to (git ls-remote); for a directory, a hash of its files. It must be cheap
	// enough to call on every poll.
	Head(ctx context.Context) (string, error)
	// Load loads and validates the catalog at revision (as returned by Head). The snapshot's
	// SHA is revision. The diagnostics are catalog.LoadDir's; err is set only when the
	// revision couldn't be read at all.
	Load(ctx context.Context, revision string) (*catalog.Catalog, []catalog.Error, error)
	// String describes the source for logs and status, without credentials.
	String() string
}

CatalogSource is where catalog-sync reads the catalog from.

type CatalogStatus

type CatalogStatus struct {
	// Source describes where the catalog comes from (no credentials).
	Source string `json:"source"`
	// Ready is true once a good catalog is live (and stays true: a later failure keeps it).
	Ready bool `json:"ready"`
	// LastGoodSHA is the live catalog's SHA; LoadedAt is when it was swapped in.
	LastGoodSHA string    `json:"lastGoodSHA,omitempty"`
	LoadedAt    time.Time `json:"loadedAt,omitzero"`
	// LastAttemptSHA is the last revision catalog-sync tried to load (equal to LastGoodSHA
	// when it is live).
	LastAttemptSHA string `json:"lastAttemptSHA,omitempty"`
	// LastSuccess is the last sync that ended with the source's revision live; LastFailure
	// the last that didn't (invalid catalog or unreadable source).
	LastSuccess time.Time `json:"lastSuccess,omitzero"`
	LastFailure time.Time `json:"lastFailure,omitzero"`
	// Errors are the error diagnostics of the last load that failed validation (the revision
	// in LastAttemptSHA, unless a source failure came after), at most MaxErrors of them;
	// ErrorsOmitted counts the rest. Cleared when a catalog is swapped in.
	Errors        []catalog.Error `json:"errors,omitempty"`
	ErrorsOmitted int             `json:"errorsOmitted,omitempty"`
	// Warnings are the live catalog's warnings, bounded like Errors.
	Warnings        []catalog.Error `json:"warnings,omitempty"`
	WarningsOmitted int             `json:"warningsOmitted,omitempty"`
	// SourceError is the last failure to read the source (git or the directory), credentials
	// redacted; empty once the source reads again.
	SourceError string `json:"sourceError,omitempty"`
}

CatalogStatus is catalog-sync's report (the LLD's {lastGood, lastAttempt, errors}), for the API server and the UI. Times come from the injected clock.

type CatalogSync

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

CatalogSync is the catalog-sync controller. It polls its CatalogSource; when the head revision changes it loads and validates the catalog there and, when it has no errors, swaps it in atomically. A catalog with errors is rejected whole: the live catalog stays, and Status reports the attempt and its diagnostics. A rejected revision is not loaded again until the head moves or Resync forces it.

Before the first good catalog Current returns nil and Ready is open.

func NewCatalogSync

func NewCatalogSync(src CatalogSource, opts CatalogSyncOptions) *CatalogSync

NewCatalogSync returns a catalog-sync controller over src.

func (*CatalogSync) Controller

func (s *CatalogSync) Controller() *Controller

Controller returns the underlying controller (its panics, for metrics).

func (*CatalogSync) Current

func (s *CatalogSync) Current() *catalog.Catalog

Current returns the live catalog, nil before the first good one.

func (*CatalogSync) Ready

func (s *CatalogSync) Ready() <-chan struct{}

Ready is closed once the first good catalog is live (startup waits for it).

func (*CatalogSync) Reconcile

func (s *CatalogSync) Reconcile(ctx context.Context, _ string) (Result, error)

Reconcile implements Reconciler: one Sync, then the next poll. An unreadable source is returned as an error, so it is retried with backoff (capped at the interval); an invalid catalog waits for the next poll.

func (*CatalogSync) Resync

func (s *CatalogSync) Resync()

Resync makes the controller sync now, reloading the head even if it was already tried (the `resync-catalog` command).

func (*CatalogSync) Run

func (s *CatalogSync) Run(ctx context.Context) error

Run syncs at once, then every Interval (and on Resync), until ctx is done.

func (*CatalogSync) Snapshot

func (s *CatalogSync) Snapshot() (*catalog.Catalog, <-chan struct{})

Snapshot returns the live catalog (nil before the first good one) and a channel closed at the next swap. Controllers that derive state from the catalog (provider connections, budgets) wait on it, then call Snapshot again.

func (*CatalogSync) Status

func (s *CatalogSync) Status() CatalogStatus

Status returns a copy of the current status.

func (*CatalogSync) Sync

func (s *CatalogSync) Sync(ctx context.Context, force bool) error

Sync polls the source once: when its head differs from the live catalog (or force is set), it loads the head and swaps it in if it validates. It returns nil when the head is live afterwards, an error wrapping ErrCatalogInvalid when the head failed validation (now or on an earlier attempt), or the source's error.

type CatalogSyncOptions

type CatalogSyncOptions struct {
	// Interval is the poll interval. Default 60 s.
	Interval time.Duration
	// MaxErrors bounds CatalogStatus.Errors and Warnings. Default 50.
	MaxErrors int
	// Clock times polls and retries and stamps the status. Default the wall clock.
	Clock clock.Clock
	// Logger. Default slog.Default().
	Logger *slog.Logger
}

CatalogSyncOptions configure CatalogSync. Zero fields take the defaults.

type ConnSource

type ConnSource interface {
	Conn(name string) (provider.Conn, bool)
}

ConnSource gives the controllers the live connection of a Provider instance by name. The provider controller, which connects one Conn per catalog Provider, implements it; tests use StaticConns.

type Controller

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

Controller runs a Reconciler over a keyed work queue fed by store watches (Watch) and direct adds (Enqueue). A key is reconciled by at most one worker at a time; a failed Reconcile (an error or a panic) is retried with exponential backoff, unless its error is Permanent.

func NewController

func NewController(name string, rec Reconciler, opts Options) *Controller

NewController returns a controller named name (used in logs) that reconciles with rec. Its queue exists from the start, so keys can be enqueued before Run.

func (*Controller) Enqueue

func (c *Controller) Enqueue(key string)

Enqueue adds key to the work queue.

func (*Controller) Name

func (c *Controller) Name() string

Name returns the controller's name.

func (*Controller) Panics

func (c *Controller) Panics() uint64

Panics returns how many Reconcile calls panicked (controller_panics_total).

func (*Controller) Queue

func (c *Controller) Queue() *Queue

Queue returns the controller's work queue.

func (*Controller) Run

func (c *Controller) Run(ctx context.Context) error

Run starts the informers and the workers and blocks until ctx is done; then it shuts the queue down, waits for in-flight reconciles and informers to return, and returns nil. Run may be called once.

func (*Controller) SetGate added in v0.2.0

func (c *Controller) SetGate(g Gate) error

SetGate makes every reconcile wait for g first (the leader lock: P3 §Several dispatchers). The informers run regardless, so the queue holds every key once g opens. SetGate must be called before Run.

func (*Controller) Watch

func (c *Controller) Watch(s store.Store, kind string, keyFn KeyFunc, opts InformerOptions) error

Watch feeds the queue from kind's objects in s: every object on start and after each resync, then every change, mapped to keys by keyFn (NameKey when nil). The informer starts with Run and stops with it. Watch must be called before Run.

type DebounceController

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

DebounceController fires debounced rules (controllers.md §debounce, part of the rule controller): at a DebounceRecord's Until it re-checks the rails of each held action, applies the allowed ones under the work item's lock, records the decision and deletes the record. Its key is the record's name; the queue's delayed requeue is the timer wheel.

func NewDebounceController

func NewDebounceController(rule *RuleController) (*DebounceController, error)

NewDebounceController returns the debounce controller of a rule controller (same store, catalog, providers and options).

func (*DebounceController) Controller

func (d *DebounceController) Controller() *Controller

Controller returns the underlying controller.

func (*DebounceController) Reconcile

func (d *DebounceController) Reconcile(ctx context.Context, name string) (Result, error)

Reconcile implements Reconciler for one DebounceRecord.

func (*DebounceController) Run

Run runs the controller until ctx is done.

type DebounceRecord

type DebounceRecord struct {
	v1alpha1.TypeMeta
	Metadata v1alpha1.ObjectMeta `json:"metadata"`
	Spec     DebounceSpec        `json:"spec"`
}

DebounceRecord is a pending debounced rule: the first match of Key holds the rule's actions until Until; later matches of the same Key change nothing (first wins).

func (*DebounceRecord) GetName

func (d *DebounceRecord) GetName() string

GetName returns metadata.name.

func (*DebounceRecord) GetObjectMeta

func (d *DebounceRecord) GetObjectMeta() *v1alpha1.ObjectMeta

GetObjectMeta implements store.MetaObject.

type DebounceSpec

type DebounceSpec struct {
	// Key is the engine's debounce key ("<rule>/<value>").
	Key      string `json:"key"`
	WorkItem string `json:"workItem"`
	// Event, RuleSet and Rule are where the held actions come from (task provenance, records).
	Event   string    `json:"event"`
	RuleSet string    `json:"ruleSet"`
	Rule    string    `json:"rule"`
	Until   time.Time `json:"until"`
	// Then are the rule's materialised actions, in order.
	Then []rules.ActionIntent `json:"then"`
}

DebounceSpec is what a DebounceRecord holds.

type Deleted

type Deleted struct {
	Kinds map[string]int
	Tasks []string
}

Deleted is what DeleteWorkItem removed: how many objects of each kind, and the ids of the item's tasks (so the caller can drop what it keys to them, the scheduler's leases).

func DeleteWorkItem

func DeleteWorkItem(ctx context.Context, s store.Store, id string, force bool) (Deleted, error)

DeleteWorkItem deletes the work item id, under its lock, with everything keyed to it: its tasks and their prompts, runs (the store drops their transcripts) and effects; its events (the ones processed for it, the ones its decisions name and the factory events about it), their processed marks and the rule effects they made; its debounces. Without force it refuses with ErrTaskLeased while a task is Leased, Running or Cancelling; with force it cancels the active tasks first. A missing item is store.ErrNotFound.

type Delivery

type Delivery struct {
	v1alpha1.TypeMeta
	Metadata v1alpha1.ObjectMeta `json:"metadata"`
	Spec     provider.RawEvent   `json:"spec"`
	Status   DeliveryStatus      `json:"status"`
}

Delivery is the internal Delivery record: the RawEvent as received, then its outcome. Once handled, the body and headers are dropped (they are untrusted and may be large).

func (*Delivery) GetName

func (d *Delivery) GetName() string

GetName returns metadata.name (the delivery id).

func (*Delivery) GetObjectMeta

func (d *Delivery) GetObjectMeta() *v1alpha1.ObjectMeta

GetObjectMeta implements store.MetaObject.

type DeliveryStatus

type DeliveryStatus struct {
	Phase string `json:"phase"`
	// Events are the ids of the Events stored from it: the intake filter drops the others.
	Events []string `json:"events,omitzero"`
	// Reason is why it failed.
	Reason    string    `json:"reason,omitzero"`
	HandledAt time.Time `json:"handledAt,omitzero"`
}

DeliveryStatus is what became of a delivery.

type DirSource

type DirSource struct {
	// FS is the catalog root, e.g. os.DirFS(dir).
	FS fs.FS
	// Name describes the directory in logs and status.
	Name string
	// Options are passed to catalog.LoadDir (SHA is set to the revision).
	Options catalog.Options
}

DirSource reads the catalog from a local directory (`--catalog-dir`, local development). Head hashes the files LoadDir reads (the same "dir:<sha256>" LoadDir computes), so an edit is picked up on the next poll.

func NewDirSource

func NewDirSource(dir string, opts catalog.Options) DirSource

NewDirSource returns a DirSource over the directory dir.

func (DirSource) Head

func (d DirSource) Head(ctx context.Context) (string, error)

Head hashes the directory: every regular file outside dot-directories that isn't a dot file, in lexical order (path, length and content), as LoadDir does.

func (DirSource) Load

func (d DirSource) Load(ctx context.Context, revision string) (*catalog.Catalog, []catalog.Error, error)

Load runs catalog.LoadDir on the directory, labelling the snapshot with revision.

func (DirSource) String

func (d DirSource) String() string

type DropCount added in v0.2.0

type DropCount struct {
	Provider, Type, Reason string
	Count                  uint64
}

DropCount is how many events of one provider and type the intake filter dropped, and why.

type EventStatus

type EventStatus struct {
	v1alpha1.TypeMeta
	Metadata v1alpha1.ObjectMeta `json:"metadata"`
	// WorkItem is the work item the event was applied to; empty when no rule matched.
	WorkItem    string    `json:"workItem,omitzero"`
	ProcessedAt time.Time `json:"processedAt"`
	// Recorded is how many decision records processing (and replays) appended on WorkItem;
	// nil on a mark older than the count. A replay refuses an event that recorded some when
	// none remain on the item.
	Recorded *int `json:"recorded,omitempty"`
}

EventStatus records that the rule controller processed an Event.

func (*EventStatus) GetName

func (e *EventStatus) GetName() string

GetName returns metadata.name (the event id).

func (*EventStatus) GetObjectMeta

func (e *EventStatus) GetObjectMeta() *v1alpha1.ObjectMeta

GetObjectMeta implements store.MetaObject.

type FactoryEvent

type FactoryEvent struct {
	Type v1alpha1.EventType
	// WorkItem is the work item the event is about; factory events always carry one.
	WorkItem string
	// Key makes the event id ("factory/<Key>"): emitting the same Key twice stores one event,
	// so a retried emitter never duplicates it.
	Key string
	// Facts are the event's facts (run, approval, command args, …).
	Facts map[string]any
	// Actor is who caused it (a command's user); nil for the factory itself.
	Actor *v1alpha1.Actor
}

FactoryEvent is one factory.* event to emit.

type FactoryProvider

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

FactoryProvider is the built-in `factory` provider: the only writer of factory.* Events. The run controller emits factory.run.*, the work-item controller factory.workitem.resynced, and the API server's commands factory.command.* (RT-S2-T03). It is safe for concurrent use.

func NewFactoryProvider

func NewFactoryProvider(s store.Store, clk clock.Clock) *FactoryProvider

NewFactoryProvider returns the factory provider writing to s.

func (*FactoryProvider) Emit

Emit stores the event and returns it. Only factory.* types of the vocabulary are accepted. An event whose id already exists is not stored again (the existing one is returned).

func (*FactoryProvider) EmitCommand

func (f *FactoryProvider) EmitCommand(ctx context.Context, typ v1alpha1.EventType, workItem, key string, args map[string]any, actor *v1alpha1.Actor) (v1alpha1.Event, error)

EmitCommand emits a factory.command.* event (pause, resume, redispatch, cancel) for the API server's commands. key identifies the command (its request id).

type FakeCatalogSource

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

FakeCatalogSource is an in-memory CatalogSource for tests. It is safe for concurrent use.

func NewFakeCatalogSource

func NewFakeCatalogSource() *FakeCatalogSource

NewFakeCatalogSource returns a fake with no revisions and an empty head.

func (*FakeCatalogSource) Head

func (f *FakeCatalogSource) Head(ctx context.Context) (string, error)

Head implements CatalogSource.

func (*FakeCatalogSource) Load

func (f *FakeCatalogSource) Load(ctx context.Context, revision string) (*catalog.Catalog, []catalog.Error, error)

Load implements CatalogSource; an unknown revision is an error.

func (*FakeCatalogSource) Loads

func (f *FakeCatalogSource) Loads() []string

Loads returns the revisions Load was called with, in order.

func (*FakeCatalogSource) Set

func (f *FakeCatalogSource) Set(revision string, r FakeRevision)

Set sets what Load returns for revision.

func (*FakeCatalogSource) SetHead

func (f *FakeCatalogSource) SetHead(revision string, err error)

SetHead sets what Head returns.

func (*FakeCatalogSource) String

func (f *FakeCatalogSource) String() string

type FakeRevision

type FakeRevision struct {
	Catalog     *catalog.Catalog
	Diagnostics []catalog.Error
	Err         error
}

FakeRevision is what a FakeCatalogSource's Load returns for one revision.

type Gate added in v0.2.0

type Gate interface {
	// Held reports whether this process may do the work now.
	Held() bool
	// Wait blocks until Held, or until ctx ends (its error).
	Wait(ctx context.Context) error
}

Gate holds work until this process may do it. The Leader is the one in use: a controller with a gate checks it before each reconcile (Controller.SetGate).

type GitSkills

type GitSkills struct {
	Base string
	// Token, when set, mints a read-only token for a skills repo ("owner/name") on Base's git
	// host, so that a private skills repo resolves: the ls-remote sends it as a header in git's
	// environment (gitsource.HeadAuth), never in the URL or argv. When the mint fails the
	// ls-remote runs anonymously (a public repo still resolves), and a failure then reports
	// both errors. Sources on another host always resolve anonymously. Nil: all anonymous.
	Token func(ctx context.Context, repo string) (string, error)
	// contains filtered or unexported fields
}

GitSkills resolves a skill ref with `git ls-remote` (gitsource.Head), caching each (url, ref). A source that isn't a URL is a repo under Base ("ccf-skills" → "https://github.com/compliance-framework/ccf-skills"). It is safe for concurrent use.

func (*GitSkills) Resolve

func (g *GitSkills) Resolve(ctx context.Context, source, ref string) (string, string, error)

Resolve implements SkillResolver.

type GitSource

type GitSource struct {
	// Repo is the repository URL (https, ssh, git or file). Required: there is no default.
	Repo string
	// Ref is the branch or tag to follow, or a full commit SHA to pin. Default "main".
	Ref string
	// Path is the catalog's directory in the repository. Default "catalog".
	Path string
	// Options are passed to catalog.LoadDir (SHA is set by gitsource).
	Options catalog.Options
	// Token, when set, mints a read-only token for the repository ("owner/name") before each
	// Head and Load, which send it as a header in git's environment, never in the URL or argv.
	// Repo must then be https://<host>/<owner>/<name>[.git]. A mint error fails the call:
	// there is no anonymous fallback. Nil: anonymous.
	Token func(ctx context.Context, repo string) (string, error)
	// contains filtered or unexported fields
}

GitSource reads the catalog from a git repository through gitsource: Head is gitsource.HeadAuth (git ls-remote), Load is gitsource.LoadAuth at that commit (a shallow fetch into a temporary directory). gitsource redacts credentials in the URL, and the token, from its errors.

func (GitSource) Head

func (g GitSource) Head(ctx context.Context) (string, error)

Head resolves Ref with gitsource.HeadAuth (git ls-remote): a branch wins over a tag, an annotated tag resolves to its commit, and a full commit SHA is pinned (no token minted).

func (GitSource) Load

func (g GitSource) Load(ctx context.Context, revision string) (*catalog.Catalog, []catalog.Error, error)

Load fetches revision and loads the catalog under Path (gitsource.LoadAuth).

func (GitSource) String

func (g GitSource) String() string

type Informer

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

Informer feeds a handler from one kind of the store with list-then-watch: it lists every object (handing each to the handler), then watches from the list's ResourceVersion, so no change falls between the two. When the watch expires (store.ErrWatchExpired: the consumer fell behind, or the version left the history) it resyncs: lists again and watches from the new version. Handlers see each object at least once per change, possibly more (after a resync), so reconcilers must be idempotent.

func NewInformer

func NewInformer(s store.Store, kind string, handler func(store.Object), opts InformerOptions) *Informer

NewInformer returns an informer over kind in s that calls handler for every listed object and every changed one (the last state of a deleted one). handler runs on the informer's goroutine; it must not block for long, or the watch expires.

func (*Informer) Resyncs

func (i *Informer) Resyncs() uint64

Resyncs returns how many times the informer re-listed after its watch expired.

func (*Informer) Run

func (i *Informer) Run(ctx context.Context)

Run lists and watches until ctx is done.

func (*Informer) Synced

func (i *Informer) Synced() <-chan struct{}

Synced is closed once the first list has been handed to the handler.

type InformerOptions

type InformerOptions struct {
	// LabelSelector narrows the list and the watch.
	LabelSelector *v1alpha1.LabelSelector
	// Buffer is the watch buffer (0: the store's default). A watcher that falls further
	// behind expires, and the informer resyncs.
	Buffer int
	// PageSize is the list page size. Default 500.
	PageSize int
	// Retry is the backoff after a failed list or watch (not after an expiry, which resyncs
	// at once). Default 100 ms → 30 s.
	Retry Backoff
	// Clock times the retries. Default the wall clock.
	Clock clock.Clock
	// Logger. Default slog.Default().
	Logger *slog.Logger
}

InformerOptions configure an Informer. Zero fields take the defaults.

type InstallationCheck

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

InstallationCheck checks that each identity's App is installed on every repo the catalog can touch (InstallationTargets), through the Conns that are provider.InstallationCheckers. Each gap is logged at WARN; Gaps reports the last check's. It is safe for concurrent use.

func NewInstallationCheck

func NewInstallationCheck(conns ConnSource, opts InstallationCheckOptions) *InstallationCheck

NewInstallationCheck returns a check over conns.

func (*InstallationCheck) Check

Check checks cat's targets and keeps the gaps it finds. A target whose check fails (GitHub unreachable, the App's key refused) is logged and keeps no gaps: the check reports what it knows, and the next one tries again.

func (*InstallationCheck) Follow

Follow checks the live catalog at once and again after every swap, until ctx is done.

func (*InstallationCheck) Gaps

func (c *InstallationCheck) Gaps() []InstallationGap

Gaps returns the last check's gaps.

type InstallationCheckOptions

type InstallationCheckOptions struct {
	// RuleIdentity is the identity of rule-level notifications and effects. Default
	// DefaultRuleIdentity.
	RuleIdentity string
	// SkillsBase is where a skill source that isn't a URL lives (`--skills-base`).
	SkillsBase string
	// Timeout bounds one Check. Default DefaultInstallationCheckTimeout.
	Timeout time.Duration
	// Logger. Default slog.Default().
	Logger *slog.Logger
}

InstallationCheckOptions configure an InstallationCheck. Zero fields take the defaults.

type InstallationGap

type InstallationGap struct {
	Provider, Identity string
	// App is the App's slug, "" when it couldn't be learnt.
	App  string
	Repo string
}

InstallationGap is an identity's App that isn't installed on a repo the catalog can touch.

func (InstallationGap) Message

func (g InstallationGap) Message() string

Message is the gap as a sentence for the catalog status.

type InstallationTarget

type InstallationTarget struct {
	Provider, Identity string
	// Repos are "owner/name", sorted, without duplicates.
	Repos []string
}

InstallationTarget is the repos one identity of one github Provider can touch.

func InstallationTargets

func InstallationTargets(cat *catalog.Catalog, ruleIdentity, skillsBase string) []InstallationTarget

InstallationTargets lists the repos each identity of each github Provider can touch, from the catalog. For each RuleSet bound to a github Provider: its literal scope repos (the targets its work items link; a glob names no repo), as the identity of every TaskSpec its rules dispatch and, when they notify or apply effects, as ruleIdentity; and, for each such TaskSpec, its literal workspace repos, a literal dispatch target and its skill sources on the Provider's git host (a source that isn't a URL is a repo under skillsBase). Sorted by provider, then identity.

type KeepSkills

type KeepSkills struct{}

KeepSkills is the SkillResolver that resolves nothing: the source stays as written and the commit empty. It is the default; `factory serve` (RT-S2-T04) wires GitSkills.

func (KeepSkills) Resolve

func (KeepSkills) Resolve(_ context.Context, source, _ string) (string, string, error)

Resolve implements SkillResolver.

type KeyFunc

type KeyFunc func(store.Object) []string

KeyFunc maps a changed object to the keys to reconcile (none to ignore it).

type KillSwitch

type KillSwitch struct {
	v1alpha1.TypeMeta
	Metadata v1alpha1.ObjectMeta `json:"metadata"`
	Scope    string              `json:"scope"`
	Target   string              `json:"target,omitzero"`
	// By is who paused it (an Actor id); At is when.
	By string    `json:"by,omitzero"`
	At time.Time `json:"at"`
}

KillSwitch is one pause flag: a scope (and, except for ScopeGlobal, a name) that is paused.

func (*KillSwitch) GetName

func (k *KillSwitch) GetName() string

GetName returns metadata.name.

func (*KillSwitch) GetObjectMeta

func (k *KillSwitch) GetObjectMeta() *v1alpha1.ObjectMeta

GetObjectMeta implements store.MetaObject.

type KillSwitches

type KillSwitches interface {
	// Paused reports whether scope/name (name is empty for ScopeGlobal) is paused.
	Paused(ctx context.Context, scope, name string) (bool, error)
}

KillSwitches reports the pause flags. The pause/resume commands set them in the store (StoreKillSwitches, the rule controller's default); NoKillSwitches pauses nothing.

type Leader added in v0.2.0

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

Leader takes and keeps the store's leader lock. Every instance runs one: it tries to take the lock at start and every Renew, and the holder renews it every Renew. Held is true from a successful Lock or Renew until the lease that call set ends on this process's clock, or until a Renew fails; so a holder paused past its lease stops its loops before another instance can take over. With one dispatcher it is always the leader.

func NewLeader added in v0.2.0

func NewLeader(s store.Store, opts LeaderOptions) *Leader

NewLeader returns a Leader on s's lock LeaderLock. Call Run.

func (*Leader) Held added in v0.2.0

func (l *Leader) Held() bool

Held implements Gate: this process holds the lock and its lease hasn't ended on this process's clock.

func (*Leader) Release added in v0.2.0

func (l *Leader) Release()

Release gives the lock up, when this process holds it, and ends the term. Call it once the leader's loops have stopped, so another instance takes over at its next try.

func (*Leader) Run added in v0.2.0

func (l *Leader) Run(ctx context.Context) error

Run tries to take the lock at once and then every Renew, and renews it while it holds it, until ctx ends. It doesn't give the lock up: call Release once the leader's loops have stopped.

func (*Leader) Wait added in v0.2.0

func (l *Leader) Wait(ctx context.Context) error

Wait implements Gate. It checks again on every Lock or Renew, and at least every Renew.

func (*Leader) While added in v0.2.0

func (l *Leader) While(ctx context.Context, name string, fn func(ctx context.Context) error)

While runs fn for each term this process leads, under a context that ends with the term (a failed Renew, or Release) or as soon as the lease lapses on this process's clock (a holder paused past it), whichever comes first, until ctx ends. fn runs again once this process holds the lock again. fn's error is logged; the next term runs it again.

type LeaderOptions added in v0.2.0

type LeaderOptions struct {
	// TTL is the lock's lease (DefaultLeaderTTL); Renew how often it is renewed or tried
	// (DefaultLeaderRenew); Try bounds each attempt (DefaultLeaderTry).
	TTL, Renew, Try time.Duration
	// Clock times the attempts and the lease as this process sees it. Default the wall clock.
	Clock clock.Clock
	// Logger. Default slog.Default().
	Logger *slog.Logger
}

LeaderOptions configure a Leader. Zero fields take the defaults.

type LinkObservations added in v0.2.0

type LinkObservations struct {
	v1alpha1.TypeMeta
	Metadata v1alpha1.ObjectMeta `json:"metadata"`
	// Digests maps each link ("<provider>/<ref>") to the digest of its last observation
	// ("gone" when the object no longer existed).
	Digests map[string]string `json:"digests"`
}

LinkObservations is a stored KindLinkObservations.

func (*LinkObservations) GetName added in v0.2.0

func (o *LinkObservations) GetName() string

GetName returns metadata.name (the work item id).

func (*LinkObservations) GetObjectMeta added in v0.2.0

func (o *LinkObservations) GetObjectMeta() *v1alpha1.ObjectMeta

GetObjectMeta implements store.MetaObject.

type NoKillSwitches

type NoKillSwitches struct{}

NoKillSwitches is KillSwitches with nothing paused.

func (NoKillSwitches) Paused

Paused implements KillSwitches.

type ObservationCache

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

ObservationCache caches Conn.Observe per object for a TTL. The rule controller reads through it when it builds a WorkItemView; the work-item controller's resync refreshes it. It is safe for concurrent use.

func NewObservationCache

func NewObservationCache(conns ConnSource, clk clock.Clock, ttl time.Duration) *ObservationCache

NewObservationCache returns a cache over conns (ttl ≤ 0: DefaultObservationTTL).

func (*ObservationCache) Forget

func (c *ObservationCache) Forget(l v1alpha1.Link)

Forget drops the link's cached observation.

func (*ObservationCache) Observe

Observe returns the link's observation, from the cache when it is fresher than the TTL. A missing object is provider.ErrNotFound; one the provider won't show, provider.ErrForbidden.

func (*ObservationCache) Refresh

Refresh observes the link now and caches the result.

type Options

type Options struct {
	// Workers is the number of keys reconciled concurrently. Default 2.
	Workers int
	// Clock times retries, delayed requeues and informer retries. Default the wall clock.
	Clock clock.Clock
	// Backoff is the per-key retry backoff after an error. Default 5 ms → 5 min with 10%
	// jitter (a zero Backoff); set any field to configure it (Jitter 0 is then no jitter).
	Backoff Backoff
	// Logger is the controller's logger (it adds controller=<name>). Default slog.Default().
	Logger *slog.Logger
}

Options configure a Controller. Zero fields take the defaults.

type ProviderController

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

ProviderController connects one Conn per catalog Provider through a provider.Registry (reconnecting a Provider whose definition changed, dropping a removed one), is the ConnSource of the other controllers and the API server, and is the webhooks' IngressSink: Accept stores a Delivery record, and its reconcile normalises the Delivery into Events with the Provider's Conn, storing only the Events that can matter (the intake filter). Its key is the delivery id.

func NewProviderController

func NewProviderController(s store.Store, cat CatalogSnapshotter, reg *provider.Registry, opts ProviderOptions) (*ProviderController, error)

NewProviderController returns the provider controller, watching Deliveries.

func (*ProviderController) Accept

Accept implements provider.IngressSink: it stores the delivery as a Delivery record named by its id. A delivery already stored is provider.ErrDuplicateDelivery.

func (*ProviderController) Conn

func (p *ProviderController) Conn(name string) (provider.Conn, bool)

Conn implements ConnSource.

func (*ProviderController) Connect

func (p *ProviderController) Connect(ctx context.Context) error

Connect connects every Provider of the live catalog. It is the startup step: the first Provider that can't be connected (no adapter for its type, a missing secret) fails it, and nothing is connected then. Run keeps the connections in line with later catalogs.

func (*ProviderController) Controller

func (p *ProviderController) Controller() *Controller

Controller returns the underlying controller.

func (*ProviderController) Drops added in v0.2.0

func (p *ProviderController) Drops() []DropCount

Drops returns how many events the intake filter dropped since the process started, by provider, type and reason, sorted (factory_events_dropped_total).

func (*ProviderController) Names

func (p *ProviderController) Names() []string

Names returns the connected Providers, sorted.

func (*ProviderController) Reconcile

func (p *ProviderController) Reconcile(ctx context.Context, id string) (Result, error)

Reconcile implements Reconciler for one delivery id: it normalises a received delivery into Events, stores the ones that can matter (each created once), marks it handled, and deletes it after the retention. A delivery none of whose events was stored (all dropped, or a type the adapter doesn't map) is deleted at once.

func (*ProviderController) Recover

func (p *ProviderController) Recover(ctx context.Context, since time.Time) error

Recover asks every connection to re-ingest the deliveries it made since since (the restart gap). Failures are logged and joined; the deliveries the store already has are skipped.

func (*ProviderController) Run

Run normalises deliveries and follows the catalog (reconnecting changed Providers) until ctx is done.

type ProviderOptions

type ProviderOptions struct {
	Workers int
	Clock   clock.Clock
	Logger  *slog.Logger
	// Secrets resolve the Providers' secretRefs (FACTORY_SECRET_<NAME>_<KEY>).
	Secrets provider.SecretResolver
	// DeliveryRetention is how long a handled Delivery is kept. Default
	// DefaultDeliveryRetention.
	DeliveryRetention time.Duration
}

ProviderOptions configure the provider controller. Zero fields take the defaults.

type Queue

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

Queue is a keyed work queue:

  • a key is queued at most once however often it is added (dedupe);
  • a key is handed to at most one worker at a time: a key added while it is being processed is queued again only when the worker calls Done;
  • keys can be added after a delay (AddAfter) or after a per-key exponential backoff (AddRateLimited, reset by Forget), timed on the injected Clock.

The zero Queue is not usable; use NewQueue. ShutDown stops it.

func NewQueue

func NewQueue(clk clock.Clock, backoff Backoff) *Queue

NewQueue returns a running queue (its delay loop runs until ShutDown). A nil clk is the wall clock.

func (*Queue) Add

func (q *Queue) Add(key string)

Add queues key unless it is already queued. Adds after ShutDown are ignored.

func (*Queue) AddAfter

func (q *Queue) AddAfter(key string, d time.Duration)

AddAfter queues key once d has passed on the queue's clock (at once when d <= 0). A key already waiting keeps the earlier of its two deadlines.

func (*Queue) AddRateLimited

func (q *Queue) AddRateLimited(key string)

AddRateLimited counts a failure for key and queues it after its backoff delay.

func (*Queue) Done

func (q *Queue) Done(key string)

Done marks key as processed; if it was added again meanwhile it is queued now.

func (*Queue) Forget

func (q *Queue) Forget(key string)

Forget resets key's failure count (call it when key was processed successfully).

func (*Queue) Get

func (q *Queue) Get() (key string, shutdown bool)

Get blocks until a key is ready and hands it to the caller, who must call Done(key) when finished. shutdown is true (and key empty) once the queue is shut down.

func (*Queue) Len

func (q *Queue) Len() int

Len returns the number of keys ready for a worker (not the delayed ones).

func (*Queue) NumRequeues

func (q *Queue) NumRequeues(key string) int

NumRequeues returns key's failure count since the last Forget.

func (*Queue) ShutDown

func (q *Queue) ShutDown()

ShutDown stops the queue: Get returns shutdown to every waiting and future caller, adds are ignored and the delay loop exits. Keys still queued are dropped. It is idempotent.

func (*Queue) ShuttingDown

func (q *Queue) ShuttingDown() bool

ShuttingDown reports whether ShutDown was called.

type RecompileOptions

type RecompileOptions struct {
	// TaskID is the new task's id.
	TaskID string
	// Harness, when set, replaces the harness request.
	Harness *v1alpha1.HarnessRequest
	Now     time.Time
}

RecompileOptions are what Recompile takes besides the original task.

type Reconciler

type Reconciler interface {
	Reconcile(ctx context.Context, key string) (Result, error)
}

Reconciler brings the world in line with the desired state of one key. Reconcile must be idempotent: it re-reads state and never trusts the event that queued the key (P4).

type ReconcilerFunc

type ReconcilerFunc func(ctx context.Context, key string) (Result, error)

ReconcilerFunc adapts a function to Reconciler.

func (ReconcilerFunc) Reconcile

func (f ReconcilerFunc) Reconcile(ctx context.Context, key string) (Result, error)

Reconcile calls f.

type Rendered added in v0.3.0

type Rendered struct {
	// Decision is the decision's index in the evaluation.
	Decision int
	// Kind is RenderPrompt or RenderTemplate.
	Kind string
	// Name is the TaskSpec (RenderPrompt) or the Template (RenderTemplate).
	Name string
	Text string
	// Err is why it doesn't render; Text is empty then.
	Err error
}

Rendered is the text one decision of an evaluation renders.

func RenderEvaluation added in v0.3.0

func RenderEvaluation(ctx context.Context, cat *catalog.Catalog, ev v1alpha1.Event, view rules.WorkItemView, eval rules.Evaluation) []Rendered

RenderEvaluation renders what the rule controller renders when it applies eval's decisions for ev to the work item view, with no store, provider or network (`factory rules test`): the prompt of each dispatch whose TaskSpec has one (compileTask with KeepSkills, the task id the decision's key gives, ev's time as now) and the GitHub body of each notify's Template (templateData with RenderUIBase, renderBody). The decisions apply in order as apply does: an allowed or deferred set or link changes the work item the later decisions see. A dispatch or a notify renders whatever its rail verdict, so a suppressed one is checked too.

type ReplayResult

type ReplayResult struct {
	WorkItem  string
	Decisions []v1alpha1.Decision
}

ReplayResult is what a replay recorded: the event's work item ("" when no rule fires for it) and the decision records it appended there.

type Result

type Result struct {
	// RequeueAfter, when positive, reconciles the key again after this delay (and resets its
	// backoff); zero forgets it until it is added again.
	RequeueAfter time.Duration
}

Result says what to do with a key after a successful Reconcile.

type RuleController

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

RuleController turns Events into decisions (controllers.md §rule): for each unprocessed Event it finds or creates the work item, builds its WorkItemView, runs the engine, applies the decisions in order under the work item's lock, appends the decision records and marks the Event processed. Its key is the event id.

func NewRuleController

func NewRuleController(s store.Store, cat CatalogProvider, conns ConnSource, opts RuleOptions) (*RuleController, error)

NewRuleController returns the rule controller, watching the store's Events.

func (*RuleController) Controller

func (r *RuleController) Controller() *Controller

Controller returns the underlying controller (its queue, for tests and the manager).

func (*RuleController) DryRun

func (r *RuleController) DryRun(ctx context.Context, ev v1alpha1.Event, wiID string) (rules.Evaluation, error)

DryRun evaluates ev as the rule controller would, but applies nothing and writes nothing to the store (the API's dry-run): against the work item wiID as it is now (state, runs, observations and the real rails, kill switches included), or, when wiID is empty, against the work item the event would create (its object observed, no state). A missing work item is store.ErrNotFound.

func (*RuleController) Reconcile

func (r *RuleController) Reconcile(ctx context.Context, id string) (Result, error)

Reconcile implements Reconciler for one event id.

func (*RuleController) Replay

func (r *RuleController) Replay(ctx context.Context, id string) (ReplayResult, error)

Replay evaluates the stored event id again, with its own id, against the live catalog and its work item as it is now (creating the item when a rule now fires for an event that had none), and applies it under the item's lock, as processLocked does on a replay: only the rules with no earlier fired record for the event act, and their new records are appended marked Replay. A missing event is store.ErrNotFound; with no catalog loaded yet it is ErrNoCatalog; an event whose earlier records aged out is ErrReplayHistoryGone.

func (*RuleController) Run

func (r *RuleController) Run(ctx context.Context) error

Run runs the controller until ctx is done.

type RuleOptions

type RuleOptions struct {
	// Workers reconciles that many events at once (different work items run in parallel;
	// one work item's events are serialised by its lock). Default 2.
	Workers int
	// Clock stamps decisions and is the engine's `now`. Default the wall clock.
	Clock clock.Clock
	// Logger. Default slog.Default().
	Logger *slog.Logger
	// Cache is the observation cache, shared with the work-item controller. Default a new
	// one with DefaultObservationTTL.
	Cache *ObservationCache
	// KillSwitches are the pause flags. Default StoreKillSwitches over the controller's store
	// (the flags the pause/resume commands write).
	KillSwitches KillSwitches
	// Skills resolves TaskSpec skill refs. Default KeepSkills.
	Skills SkillResolver
	// RunCap is the per-item task cap. Default DefaultRunCap.
	RunCap int
	// LockTTL is the work item lock's lease. Default DefaultLockTTL.
	LockTTL time.Duration
	// UIBaseURL is the Factory UI's public URL, for templates' links.ui.
	UIBaseURL string
	// Identity is the factory identity of rule-level notifications and effects. Default
	// DefaultRuleIdentity.
	Identity string
}

RuleOptions configure the rule controller. Zero fields take the defaults.

type RunAPI

type RunAPI interface {
	// LeaseIssued creates the Run of a task the scheduler just leased (the run controller
	// also creates it from the Task watch, so calling this is an optimisation).
	LeaseIssued(ctx context.Context, taskID string) error
	// Complete ingests a Result. It returns the task's phase after it (Succeeded, or Failed
	// for an invalid result or a failed status); completing a finished task again returns its
	// phase and changes nothing.
	Complete(ctx context.Context, taskID string, res v1alpha1.Result) (v1alpha1.TaskPhase, error)
	// Abandon gives a leased task back: throttled returns it to Pending without using an
	// attempt; other reasons retry it per the queue's retry policy, or fail it.
	Abandon(ctx context.Context, taskID string, a Abandonment) error
	// CancelRequested is the heartbeat's cancel flag: true while the task is Cancelling.
	CancelRequested(ctx context.Context, taskID string) (bool, error)
	// AckCancel is the agent's acknowledgement: a Cancelling task becomes Cancelled.
	AckCancel(ctx context.Context, taskID string) error
}

RunAPI is how the scheduler (RT-S2-T02) and the API server (RT-S2-T03) drive runs. The run controller implements it.

type RunController

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

RunController tracks runs (controllers.md §run): it creates the Run when a task is leased, ingests Results (validated against the TaskSpec's output), times runs out, handles cancel and abandon, updates the work item's counters and emits factory.run.completed / .failed. Its key is the task id.

func NewRunController

func NewRunController(s store.Store, cat CatalogProvider, factory *FactoryProvider, opts RunOptions) (*RunController, error)

NewRunController returns the run controller, watching Tasks and Runs.

func (*RunController) Abandon

func (r *RunController) Abandon(ctx context.Context, taskID string, a Abandonment) error

Abandon implements RunAPI.

func (*RunController) AckCancel

func (r *RunController) AckCancel(ctx context.Context, taskID string) error

AckCancel implements RunAPI.

func (*RunController) CancelRequested

func (r *RunController) CancelRequested(ctx context.Context, taskID string) (bool, error)

CancelRequested implements RunAPI.

func (*RunController) Complete

func (r *RunController) Complete(ctx context.Context, taskID string, res v1alpha1.Result) (v1alpha1.TaskPhase, error)

Complete implements RunAPI.

func (*RunController) Controller

func (r *RunController) Controller() *Controller

Controller returns the underlying controller.

func (*RunController) LeaseIssued

func (r *RunController) LeaseIssued(ctx context.Context, taskID string) error

LeaseIssued implements RunAPI.

func (*RunController) Reconcile

func (r *RunController) Reconcile(ctx context.Context, id string) (Result, error)

Reconcile implements Reconciler for one task: it keeps the task's open Run in line with the task's phase and times the run out.

func (*RunController) Run

func (r *RunController) Run(ctx context.Context) error

Run runs the controller until ctx is done.

type RunOptions

type RunOptions struct {
	Workers int
	// Clock times runs and timeouts. Default the wall clock.
	Clock clock.Clock
	// Logger. Default slog.Default().
	Logger *slog.Logger
	// Grace is added to maxWallClock. Default DefaultWallClockGrace.
	Grace time.Duration
	// LockTTL is the work item lock's lease. Default DefaultLockTTL.
	LockTTL time.Duration
}

RunOptions configure the run controller. Zero fields take the defaults.

type SkillResolver

type SkillResolver interface {
	Resolve(ctx context.Context, source, ref string) (url, commit string, err error)
}

SkillResolver resolves a TaskSpec skill (source, ref tag) to a repo URL and a commit.

type StaticConns

type StaticConns map[string]provider.Conn

StaticConns is a fixed ConnSource.

func (StaticConns) Conn

func (s StaticConns) Conn(name string) (provider.Conn, bool)

Conn implements ConnSource.

type StoreKillSwitches

type StoreKillSwitches struct {
	Store store.Store
}

StoreKillSwitches is KillSwitches kept in the store: the pause/resume commands write the flags with Pause and Resume, and the rule controller's rails read them with Paused. It is the rule controller's default.

func (StoreKillSwitches) Pause

func (k StoreKillSwitches) Pause(ctx context.Context, scope, name, by string, at time.Time) error

Pause sets the flag of scope/name (name is ignored for ScopeGlobal). Pausing a paused scope changes nothing.

func (StoreKillSwitches) Paused

func (k StoreKillSwitches) Paused(ctx context.Context, scope, name string) (bool, error)

Paused implements KillSwitches.

func (StoreKillSwitches) Resume

func (k StoreKillSwitches) Resume(ctx context.Context, scope, name string) error

Resume clears the flag of scope/name. Resuming a scope that isn't paused changes nothing.

type TaskPrompt

type TaskPrompt struct {
	v1alpha1.TypeMeta
	Metadata v1alpha1.ObjectMeta `json:"metadata"`
	Text     string              `json:"text"`
	Digest   string              `json:"digest"`
}

TaskPrompt is a Task's rendered prompt.

func Recompile

Recompile compiles orig again against cat, as a new Pending task opts.TaskID, with the code path compileTask uses (the redispatch command). It keeps what the original dispatch decided: the TaskSpec and queue names, the target, the inputs (as merged then, over the current defaults), the dispatch's context refs, the requires labels, the labels and the rule provenance. It recomputes everything the current TaskSpec gives: the prompt (with wi's current summary), skills (resolved again), workspace, context mounts, credentials request, effects, limits, output, environment and versions (from the kept inputs); the provenance's CatalogSHA is cat's and its Event is left for the caller. The harness request is opts.Harness, else the original's while the TaskSpec is unchanged (same digest), else the current TaskSpec's default: a stored task can't tell a dispatch's request from the default it was given.

A TaskSpec or queue cat no longer has is ErrNotInCatalog; a task the current TaskSpec can't express (an input it no longer declares, a prompt that doesn't render) is ErrInvalidDispatch; any other error (skills resolution) is transient.

func (*TaskPrompt) GetName

func (p *TaskPrompt) GetName() string

GetName returns metadata.name (the task id).

func (*TaskPrompt) GetObjectMeta

func (p *TaskPrompt) GetObjectMeta() *v1alpha1.ObjectMeta

GetObjectMeta implements store.MetaObject.

type WorkItemController

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

WorkItemController keeps work items and their provider objects in line (controllers.md §work-item). Per work item (its key is the id) it:

  • projects state, counters and links onto every linked object (Conn.Project) when the projection changed;
  • re-observes the links every resync interval (refreshing the observation cache) and emits factory.workitem.resynced when an observation changed out of band, against the baselines stored in its LinkObservations;
  • deletes the item once all its links are closed and its last activity is older than the retention (the store never sweeps WorkItems).

func NewWorkItemController

func NewWorkItemController(s store.Store, cat CatalogProvider, conns ConnSource, factory *FactoryProvider, opts WorkItemOptions) (*WorkItemController, error)

NewWorkItemController returns the work-item controller, watching WorkItems.

func (*WorkItemController) Controller

func (w *WorkItemController) Controller() *Controller

Controller returns the underlying controller.

func (*WorkItemController) Reconcile

func (w *WorkItemController) Reconcile(ctx context.Context, id string) (Result, error)

Reconcile implements Reconciler for one work item.

func (*WorkItemController) Run

Run runs the controller until ctx is done.

func (*WorkItemController) SweepObservations added in v0.2.0

func (w *WorkItemController) SweepObservations(ctx context.Context) (int, error)

SweepObservations deletes the LinkObservations whose work item no longer exists (a delete whose baselines' delete failed), and returns how many it deleted. The leader's sweep runs it.

type WorkItemOptions

type WorkItemOptions struct {
	Workers int
	// Clock times resyncs and retention. Default the wall clock.
	Clock clock.Clock
	// Logger. Default slog.Default().
	Logger *slog.Logger
	// Cache is the observation cache, shared with the rule controller (resync refreshes it).
	// Default a new one.
	Cache *ObservationCache
	// Retention: a work item whose links are all closed is deleted this long after its last
	// activity (`--retention`). Default store.DefaultRetention (90 days).
	Retention time.Duration
	// ResyncInterval applies when a Provider has no resync.every. Default 10 m.
	ResyncInterval time.Duration
	// Jitter picks the delay of an item's first resync in this process, when a leader before
	// it stored the item's baselines: from 0 up to the interval, so a new leader spreads its
	// checks over the interval. Default uniform (math/rand/v2).
	Jitter func(interval time.Duration) time.Duration
	// LockTTL is the work item lock's lease. Default DefaultLockTTL.
	LockTTL time.Duration
}

WorkItemOptions configure the work-item controller. Zero fields take the defaults.

Jump to

Keyboard shortcuts

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