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
- Variables
- func AddLink(wi *v1alpha1.WorkItem, ref v1alpha1.ObjectRef, fallback string) bool
- func CloseWorkItem(ctx context.Context, s store.Store, id string, closed v1alpha1.WorkItemClosed) (*v1alpha1.WorkItem, []string, error)
- func Closed(wi *v1alpha1.WorkItem) bool
- func GitHost(p *v1alpha1.Provider) string
- func IsPermanent(err error) bool
- func KillSwitchName(scope, name string) string
- func LinkObject(ctx context.Context, s store.Store, id string, ref v1alpha1.ObjectRef, ...) (bool, error)
- func NameKey(obj store.Object) []string
- func Permanent(err error) error
- func RepoOnHost(raw, host string) (repo string, ok bool)
- func ResultSpec(cat *catalog.Catalog, t *v1alpha1.Task) *catalog.CompiledTaskSpec
- func ValidKillSwitchScope(scope string) bool
- type Abandonment
- type Backoff
- type CatalogProvider
- type CatalogSnapshotter
- type CatalogSource
- type CatalogStatus
- type CatalogSync
- func (s *CatalogSync) Controller() *Controller
- func (s *CatalogSync) Current() *catalog.Catalog
- func (s *CatalogSync) Ready() <-chan struct{}
- func (s *CatalogSync) Reconcile(ctx context.Context, _ string) (Result, error)
- func (s *CatalogSync) Resync()
- func (s *CatalogSync) Run(ctx context.Context) error
- func (s *CatalogSync) Snapshot() (*catalog.Catalog, <-chan struct{})
- func (s *CatalogSync) Status() CatalogStatus
- func (s *CatalogSync) Sync(ctx context.Context, force bool) error
- type CatalogSyncOptions
- type ConnSource
- type Controller
- type DebounceController
- type DebounceRecord
- type DebounceSpec
- type Deleted
- type Delivery
- type DeliveryStatus
- type DirSource
- type EventStatus
- type FactoryEvent
- type FactoryProvider
- type FakeCatalogSource
- func (f *FakeCatalogSource) Head(ctx context.Context) (string, error)
- func (f *FakeCatalogSource) Load(ctx context.Context, revision string) (*catalog.Catalog, []catalog.Error, error)
- func (f *FakeCatalogSource) Loads() []string
- func (f *FakeCatalogSource) Set(revision string, r FakeRevision)
- func (f *FakeCatalogSource) SetHead(revision string, err error)
- func (f *FakeCatalogSource) String() string
- type FakeRevision
- type GitSkills
- type GitSource
- type Informer
- type InformerOptions
- type InstallationCheck
- type InstallationCheckOptions
- type InstallationGap
- type InstallationTarget
- type KeepSkills
- type KeyFunc
- type KillSwitch
- type KillSwitches
- type NoKillSwitches
- type ObservationCache
- type Options
- type ProviderController
- func (p *ProviderController) Accept(ctx context.Context, ev provider.RawEvent) error
- func (p *ProviderController) Conn(name string) (provider.Conn, bool)
- func (p *ProviderController) Connect(ctx context.Context) error
- func (p *ProviderController) Controller() *Controller
- func (p *ProviderController) Names() []string
- func (p *ProviderController) Reconcile(ctx context.Context, id string) (Result, error)
- func (p *ProviderController) Recover(ctx context.Context, since time.Time) error
- func (p *ProviderController) Run(ctx context.Context) error
- type ProviderOptions
- type Queue
- func (q *Queue) Add(key string)
- func (q *Queue) AddAfter(key string, d time.Duration)
- func (q *Queue) AddRateLimited(key string)
- func (q *Queue) Done(key string)
- func (q *Queue) Forget(key string)
- func (q *Queue) Get() (key string, shutdown bool)
- func (q *Queue) Len() int
- func (q *Queue) NumRequeues(key string) int
- func (q *Queue) ShutDown()
- func (q *Queue) ShuttingDown() bool
- type RebuildResult
- type RecompileOptions
- type Reconciler
- type ReconcilerFunc
- type ReplayResult
- type Result
- type RuleController
- func (r *RuleController) Controller() *Controller
- func (r *RuleController) DryRun(ctx context.Context, ev v1alpha1.Event, wiID string) (rules.Evaluation, error)
- func (r *RuleController) Reconcile(ctx context.Context, id string) (Result, error)
- func (r *RuleController) Replay(ctx context.Context, id string) (ReplayResult, error)
- func (r *RuleController) Run(ctx context.Context) error
- type RuleOptions
- type RunAPI
- type RunController
- func (r *RunController) Abandon(ctx context.Context, taskID string, a Abandonment) error
- func (r *RunController) AckCancel(ctx context.Context, taskID string) error
- func (r *RunController) CancelRequested(ctx context.Context, taskID string) (bool, error)
- func (r *RunController) Complete(ctx context.Context, taskID string, res v1alpha1.Result) (v1alpha1.TaskPhase, error)
- func (r *RunController) Controller() *Controller
- func (r *RunController) LeaseIssued(ctx context.Context, taskID string) error
- func (r *RunController) Reconcile(ctx context.Context, id string) (Result, error)
- func (r *RunController) Run(ctx context.Context) error
- type RunOptions
- type SkillResolver
- type StaticConns
- type StoreKillSwitches
- type TaskPrompt
- type WorkItemController
- type WorkItemOptions
Constants ¶
const ( DefaultCatalogRepo = "https://github.com/ContainerSolutions/factory" DefaultCatalogRef = "main" DefaultCatalogPath = "catalog" )
Catalog-sync source defaults (the LLD's --catalog-* flags).
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.
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.
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.
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.
const ( KindChannel = "channel" KindGroup = "group" KindThread = "thread" )
Destination kinds an EffectRequest.Target can name besides issues and PRs.
const ( DeliveryReceived = "received" DeliveryNormalised = "normalised" // DeliveryFailed is a delivery the adapter rejected as invalid: it is never retried. DeliveryFailed = "failed" )
Delivery phases.
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).
const ( ScopeGlobal = "global" ScopeProvider = "provider" ScopeQueue = "queue" ScopeWorkItem = "workitem" )
Kill-switch scopes (the pause/resume command's target.scope).
const ( AbandonThrottled = "throttled" AbandonAgentError = "agent-error" AbandonShutdown = "shutdown" )
Abandon reasons (the API's AbandonRequest.reason).
const ( ReasonBudget = "budget" ReasonInvalidResult = "invalid-result" ReasonTimeout = "timeout" ReasonThrottled = "agent-throttled" ReasonCancelled = "cancelled" )
Task and run failure reasons (Task.status.reason).
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.
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.
const DefaultInstallationCheckTimeout = time.Minute
DefaultInstallationCheckTimeout bounds one InstallationCheck.Check.
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.
const DefaultObservationTTL = 30 * time.Second
DefaultObservationTTL is how long an observation is reused (the LLD's 30 s view cache).
const DefaultRuleIdentity = "author"
DefaultRuleIdentity is the factory identity that rule-level notifications and effects act as.
const DefaultRunCap = 20
DefaultRunCap is the hard maximum of tasks per work item that no rule can override.
const DefaultWallClockGrace = 2 * time.Minute
DefaultWallClockGrace is added to a TaskSpec's limits.maxWallClock before a run times out.
const DefaultWorkers = 2
DefaultWorkers is the default number of workers per controller.
const FactoryEventPrefix = v1alpha1.FactoryProvider + "/"
FactoryEventPrefix starts the id of every event the built-in factory provider emits.
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).
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.
const LabelRule = "factory.ccf.dev/rule"
LabelRule is the label of an Effect record made by a rule: the rule's name.
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 ¶
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.
var ErrCatalogInvalid = errors.New("catalog is invalid")
ErrCatalogInvalid is wrapped by Sync when the source's catalog fails validation (the live catalog is kept).
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.
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.
var ErrNoCatalog = errors.New("no catalog loaded yet")
ErrNoCatalog is a call that needs the live catalog before the first one has loaded.
var ErrNotInCatalog = errors.New("not in the catalog")
ErrNotInCatalog is an ErrInvalidDispatch whose TaskSpec or queue the catalog doesn't have.
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.
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 ¶
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 GitHost ¶
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 ¶
IsPermanent reports whether err, or an error it wraps, was marked with Permanent.
func KillSwitchName ¶
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 Permanent ¶
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 ¶
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 ¶
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 ¶
ValidKillSwitchScope reports whether scope is one of the pause scopes.
Types ¶
type Abandonment ¶
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.
type CatalogProvider ¶
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 ¶
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 ¶
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) 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.
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 ¶
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 ¶
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) 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 ¶
NewDirSource returns a DirSource over the directory dir.
func (DirSource) Head ¶
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.
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 ¶
func (f *FactoryProvider) Emit(ctx context.Context, e FactoryEvent) (v1alpha1.Event, error)
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 ¶
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.
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 ¶
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.
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 ¶
Resyncs returns how many times the informer re-listed after its watch expired.
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 ¶
func (c *InstallationCheck) Check(ctx context.Context, cat *catalog.Catalog) []InstallationGap
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 ¶
func (c *InstallationCheck) Follow(ctx context.Context, cs CatalogSnapshotter) error
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.
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) 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.
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 ¶
func (c *ObservationCache) Observe(ctx context.Context, l v1alpha1.Link) (provider.Observation, error)
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 ¶
func (c *ObservationCache) Refresh(ctx context.Context, l v1alpha1.Link) (provider.Observation, error)
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 ¶
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.
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 ¶
NewQueue returns a running queue (its delay loop runs until ShutDown). A nil clk is the wall clock.
func (*Queue) AddAfter ¶
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 ¶
AddRateLimited counts a failure for key and queues it after its backoff delay.
func (*Queue) Forget ¶
Forget resets key's failure count (call it when key was processed successfully).
func (*Queue) Get ¶
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) NumRequeues ¶
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 ¶
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 ¶
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 ¶
ReconcilerFunc adapts a function to Reconciler.
type ReplayResult ¶
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) 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.
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 ¶
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.
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 ¶
StaticConns is a fixed ConnSource.
type StoreKillSwitches ¶
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 ¶
Pause sets the flag of scope/name (name is ignored for ScopeGlobal). Pausing a paused scope 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 ¶
func Recompile(ctx context.Context, cat *catalog.Catalog, skills SkillResolver, wi *v1alpha1.WorkItem, orig *v1alpha1.Task, opts RecompileOptions) (*v1alpha1.Task, *TaskPrompt, error)
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 ¶
func (w *WorkItemController) Rebuild(ctx context.Context) (RebuildResult, error)
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.
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.