controllers

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: Oct 28, 2026 License: AGPL-3.0 Imports: 36 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 (
	DefaultCatalogRepo = "https://github.com/ContainerSolutions/factory"
	DefaultCatalogRef  = "main"
	DefaultCatalogPath = "catalog"
)

Catalog-sync source defaults (the LLD's --catalog-* flags).

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 (
	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 (
	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 (
	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 (
	// DefaultResyncInterval is how often a work item's links are re-observed when their
	// Provider sets no resync.every.
	DefaultResyncInterval = 10 * time.Minute
	// DefaultRebuildTimeout bounds the startup rebuild.
	DefaultRebuildTimeout = 5 * time.Minute
)

Work-item controller defaults.

View Source
const DefaultDeliveryRetention = 24 * time.Hour

DefaultDeliveryRetention is how long a handled Delivery record is kept. Duplicates arriving later are still deduped by their Events' ids.

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 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 LabelRule = "factory.ccf.dev/rule"

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

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 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) 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 it was normalised into.
	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 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 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). Default DefaultCatalogRepo.
	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
}

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

func (GitSource) Head

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

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

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

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 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. 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) 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 (each created once), marks it handled, and deletes it after the retention.

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 RebuildResult

type RebuildResult struct {
	// Objects is how many provider objects were listed and observed.
	Objects int
	// Created are the work items recreated, by id; Existing counts those already stored.
	Created  []string
	Existing int
}

RebuildResult reports a Rebuild.

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 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;
  • deletes the item once all its links are closed and its last activity is older than the retention (the store never sweeps WorkItems).

Rebuild recreates the work items from the providers' projections on startup.

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) Rebuild

Rebuild recreates work items from the providers' projections (startup, before the rule controller starts): for every RuleSet scope it lists each bound provider's objects, observes them and reads their projections (the markers). Projections of one work item on several objects are merged: links are united, counters take the maximum, and state comes from the most recently updated object. Work items already in the store are left alone. It is bounded by RebuildTimeout.

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.

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
	// RebuildTimeout bounds Rebuild. Default 5 m.
	RebuildTimeout 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