Help us shape the future of Go! Take the 2026 Go Developer Survey

controller

package
v0.7.0 Latest Latest
Warning

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

Go to latest
Published: Oct 19, 2026 License: Apache-2.0 Imports: 45 Imported by: 0

Documentation

Overview

Package controller contains the AgentOrganization and AgentSeat reconcilers (design §6, contracts.md "Readiness flow" and "Lifecycle decisions").

Index

Constants

View Source
const (
	ReasonInstructionDigestMismatch = "InstructionDigestMismatch"
	ReasonInstructionUnavailable    = "InstructionUnavailable"
	ReasonInstructionInvalid        = "InstructionRefInvalid"
)

Instruction error reasons (Configured=False reasons).

View Source
const AnnotationSeatVerifyRequest = v1alpha1.AnnotationVerifyRequest

AnnotationVerifyRequest on AgentSeats propagates the organisation's verify nonce.

View Source
const FieldOwner = "steadmesh-controller"

FieldOwner is the controller's field manager. It writes only status (and controller metadata: finalizers, verify-observed) on AgentOrganization.

View Source
const MaxInstructionBytes = 1 << 20

MaxInstructionBytes bounds a single referenced instruction document.

Variables

This section is empty.

Functions

func CacheOptions

func CacheOptions() cache.Options

CacheOptions restricts the manager cache for seat-owned kinds to objects labelled steadmesh.io/component=seat, so the controller does not cache every Pod or ConfigMap in the cluster. Instruction ConfigMaps are read live.

func RenderInstructions

func RenderInstructions(sources []compile.InstructionSource, texts map[string]string) string

RenderInstructions concatenates instruction texts in manifest order, each under a header naming its scope and source (§4.3).

func Setup

func Setup(mgr ctrl.Manager, cfg Config) error

Setup registers the reconcilers, the runtime pollers and the backend with mgr.

Types

type Config

type Config struct {
	// Platform is the internal API client.
	Platform platform.API
	// Backend options (platform URL, control-plane namespace, images).
	Backend kube.Options
	// PollInterval of the per-organisation runtime poller (default 2s).
	PollInterval time.Duration
	// InstructionHTTP fetches https instruction bundles (default 15s timeout).
	InstructionHTTP *http.Client
	// Now overrides the clock (tests).
	Now func() time.Time
}

Config configures the controllers.

type InstructionError

type InstructionError struct {
	Ref    string
	Reason string
	Detail string
}

InstructionError is a failure to resolve or verify an instruction reference.

func (*InstructionError) Error

func (e *InstructionError) Error() string

type InstructionResolver

type InstructionResolver struct {
	Reader client.Reader
	HTTP   *http.Client
	// contains filtered or unexported fields
}

InstructionResolver fetches instruction bundles and verifies their digests. configmap:<name>/<key> refs are read live from the organisation namespace; https refs are fetched once and cached by ref (the digest makes them immutable).

func NewInstructionResolver

func NewInstructionResolver(r client.Reader, hc *http.Client) *InstructionResolver

func (*InstructionResolver) Resolve

func (r *InstructionResolver) Resolve(ctx context.Context, namespace, ref string) (string, error)

Resolve returns the verified text of ref.

func (*InstructionResolver) ResolveAll

func (r *InstructionResolver) ResolveAll(ctx context.Context, namespace string, m *compile.Manifest) (map[string]string, []error)

ResolveAll resolves every instruction of the manifest's seats. It returns all failures; the first error's reason is the Configured reason.

type OrganizationReconciler

type OrganizationReconciler struct {
	Client       client.Client
	Platform     platform.API
	Backend      seatruntime.Backend
	Pollers      *Pollers
	Instructions *InstructionResolver
	Recorder     recorder.EventRecorder
	Catalog      compile.Catalog
	PlatformURL  string
	Now          func() time.Time

	// VerifyInterval is how long a passing platform verification is reused.
	VerifyInterval time.Duration
	// VerifyRetry is how long a failing verification is reused.
	VerifyRetry time.Duration
	// SyncInterval is how long a successful identity sync of an unchanged
	// manifest is reused.
	SyncInterval time.Duration
	// contains filtered or unexported fields
}

OrganizationReconciler compiles an AgentOrganization, establishes durable identities through the platform, materialises AgentSeats and reports readiness (contracts.md "Readiness flow").

func (*OrganizationReconciler) Reconcile

func (r *OrganizationReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error)

type Pollers

type Pollers struct {
	API      platform.API
	Interval time.Duration
	// Stale is the age after which a runtime view is no longer used.
	Stale  time.Duration
	Events chan event.GenericEvent
	// contains filtered or unexported fields
}

Pollers runs one platform runtime poller per organisation (not per seat). Each poll fetches GET /internal/v1/organizations/{id}/runtime and enqueues the AgentSeats whose runtime view changed through Events, a channel source.

func NewPollers

func NewPollers(api platform.API, interval time.Duration) *Pollers

func (*Pollers) Ensure

func (p *Pollers) Ensure(orgID, orgKey, namespace string)

Ensure starts (once) the poller of an organisation.

func (*Pollers) Get

func (p *Pollers) Get(orgID, seatKey string) (*runtimeapi.SeatRuntime, bool)

Get returns the latest fresh runtime view of a seat.

func (*Pollers) Lookup added in v0.3.0

func (p *Pollers) Lookup(orgID, seatKey string) (*runtimeapi.SeatRuntime, bool)

Lookup returns the latest runtime view of a seat and whether the organisation's view is fresh; a fresh view without the seat means the platform has no active seat under that key.

func (*Pollers) NeedLeaderElection

func (p *Pollers) NeedLeaderElection() bool

NeedLeaderElection: only the leader polls.

func (*Pollers) Start

func (p *Pollers) Start(ctx context.Context) error

Start implements manager.Runnable.

func (*Pollers) Stop

func (p *Pollers) Stop(orgID string)

Stop stops an organisation's poller and forgets its data.

type Reconcilers

type Reconcilers struct {
	Organization *OrganizationReconciler
	Seat         *SeatReconciler
	Pollers      *Pollers
	Backend      *kube.Backend
}

Reconcilers are the components registered by SetupReconcilers.

func SetupReconcilers

func SetupReconcilers(mgr ctrl.Manager, cfg Config) (*Reconcilers, error)

SetupReconcilers is Setup, returning the registered components.

type SeatReconciler

type SeatReconciler struct {
	Client   client.Client
	Live     client.Reader
	Backend  seatruntime.Backend
	Platform platform.API
	Pollers  *Pollers
	Recorder recorder.EventRecorder
	Now      func() time.Time
	// ProbeTimeout fails a synthetic probe that has not completed.
	ProbeTimeout time.Duration
	// ProbeRetry is the delay before a failed probe is retried.
	ProbeRetry time.Duration
}

SeatReconciler operates one seat's backend and lifecycle.

func (*SeatReconciler) Reconcile

func (r *SeatReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error)

Directories

Path Synopsis
Package lifecycle holds the controller's seat lifecycle decision (contracts.md "Lifecycle decisions").
Package lifecycle holds the controller's seat lifecycle decision (contracts.md "Lifecycle decisions").
Package platform is the controller's client for the platform internal API (/internal/v1/*).
Package platform is the controller's client for the platform internal API (/internal/v1/*).
Package readiness computes organisation readiness conditions (design §5.4, contracts.md "Readiness flow").
Package readiness computes organisation readiness conditions (design §5.4, contracts.md "Readiness flow").

Jump to

Keyboard shortcuts

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