runtime

Documentation

Overview

Package runtime assembles the agent's goal control plane into one startable unit: the resource store, the durable job queue, the message bus, the reconcile manager, and the goal reconciler and step worker, wired together.

It owns composition, not behaviour. What a goal step does and how convergence is judged are injected (a goal.StepExecutor and a goal.StopEvaluator), so the same plumbing runs with a stub in tests and with a model-backed executor in production. The result is something you can start, submit a goal to, and watch drive itself to convergence: the reconciler dispatches a step, the worker runs it and signals completion, the signal re-triggers the reconciler, and resync guarantees progress even if a signal is lost. Because each step of progress is recorded on the durable store and queue, a restart resumes mid-goal rather than starting over.

Index

• Constants
• type Config
• type Runtime
  • func New(cfg Config) (*Runtime, error)
  • func (rt *Runtime) Resume(ctx context.Context, name string) (resource.Resource, error)
  • func (rt *Runtime) Start(ctx context.Context) error
  • func (rt *Runtime) Store() resource.Store
  • func (rt *Runtime) SubmitGoal(ctx context.Context, name string, spec goal.Spec) (resource.Resource, error)

Constants

const DefaultWorkerPoll = 50 * time.Millisecond

DefaultWorkerPoll is how often the step worker polls for work when idle. Both bundled queues implement jobs.Waker, so a fresh dispatch wakes the worker at once and this interval is only the fallback sweep for scheduled retries, expired leases, and enqueues from other processes.

Types

type Config

type Config struct {
	// Executor performs one goal step. Required.
	Executor goal.StepExecutor
	// Stop decides whether a goal has converged. Required.
	Stop goal.StopEvaluator

	// Store, Jobs, and Bus are the foundation ports. When Store is nil, an in-memory
	// store, queue, and bus are built over Clock with a registry holding the core
	// and Goal kinds. When Store is set, Jobs must be set too, and the registry the
	// store admits against must already include the Goal kind (goal.RegisterKind).
	Store resource.Store
	Jobs  jobs.Queue
	Bus   bus.Bus

	// Clock is the shared time source (default clock.System). A clock.Manual makes
	// resync and retry backoff deterministic in tests.
	Clock clock.Timing

	// Resync overrides the manager's safety-net interval (0 uses its default).
	Resync time.Duration
	// DriveSubmittedOnly makes the runtime drive only the goals it is explicitly
	// given (via SubmitGoal or a completion signal) and never adopt goals it finds
	// already in the store. A one-shot command sets this so starting a run does not
	// silently resume a goal an earlier run left non-terminal: each run keeps its
	// own event stream, and resuming a parked run is an explicit act. A long-lived
	// server leaves it false so the resync safety net drives every goal to
	// convergence after a crash.
	DriveSubmittedOnly bool
	// WorkerPoll overrides how often the step worker polls when idle.
	WorkerPoll time.Duration
	// PollInterval overrides how often the reconciler re-checks an in-flight step
	// absent a completion signal.
	PollInterval time.Duration
	// WorkerLease overrides how long a claimed step is leased. It bounds how long a
	// crashed worker's in-flight step waits before another worker re-leases it (0
	// uses the worker default).
	WorkerLease time.Duration
	// WorkerRetryBase and WorkerRetryCeiling bound the worker's exponential backoff
	// between failed step attempts (0 uses the worker defaults).
	WorkerRetryBase    time.Duration
	WorkerRetryCeiling time.Duration
	// StepMaxAttempts caps how many times a dispatched step is retried before it
	// goes dead and stalls the goal (0 uses the queue default).
	StepMaxAttempts int
}

Config assembles a Runtime. Executor and Stop are required: they are the agent's behaviour, which the foundation does not supply. Everything else has a standalone, in-process default.

type Runtime

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

Runtime is the assembled goal control plane.

func New

func New(cfg Config) (*Runtime, error)

New assembles a Runtime from cfg, building in-process foundation defaults for any port left nil. It registers the Goal reconciler with the manager.

func (*Runtime) Resume

func (rt *Runtime) Resume(ctx context.Context, name string) (resource.Resource, error)

Resume re-drives an existing goal by name: it loads the goal and enqueues it for reconciliation, so a run left non-terminal (parked or interrupted) is driven on toward completion. Unlike SubmitGoal it neither creates nor overwrites the goal, so the goal's recorded progress is preserved and the continuation lands on the same run. It returns the goal, or a store error (resource.ErrNotFound) if no goal of that name exists.

func (*Runtime) Start

func (rt *Runtime) Start(ctx context.Context) error

Start runs the control plane until ctx is cancelled: it subscribes to step completion signals (waking the reconciler promptly), then runs the manager and the step worker concurrently, blocking until both have stopped. It returns ctx.Err() on shutdown.

func (*Runtime) Store

func (rt *Runtime) Store() resource.Store

Store returns the resource store the runtime drives, so callers can read goal status and submit related resources through the same foundation.

func (*Runtime) SubmitGoal

func (rt *Runtime) SubmitGoal(ctx context.Context, name string, spec goal.Spec) (resource.Resource, error)

SubmitGoal records a new Goal and enqueues it for reconciliation. An empty name gets a server-assigned one. The returned resource carries the assigned name and identity; reconciliation proceeds asynchronously once Start is running.