operator

type Config struct {
	// DefaultServiceAccount names the ServiceAccount the operator
	// impersonates when a JsonnetSnippet does not set
	// spec.serviceAccountName. Empty means snippets without an explicit SA
	// are rejected.
	DefaultServiceAccount string

	// NoCrossNamespaceRefs mirrors Flux's --no-cross-namespace-refs:
	// when true (the default in Phase 1B's main.go wiring), a snippet
	// referencing a SourceRef in a different namespace is rejected.
	NoCrossNamespaceRefs bool

	// LabelSelector narrows the operator's watch to objects matching this
	// selector. Empty selects all objects in the watched scope, matching
	// controller-runtime's default.
	LabelSelector string

	// WatchNamespaces restricts the manager's cache to the listed
	// namespaces (Cache.DefaultNamespaces). Empty (the default) means
	// cluster-wide watch — the historical behaviour. When set, the
	// cache only observes CRs in these namespaces; CRs outside are
	// invisible to the reconciler even when the SA's RBAC would
	// otherwise grant access. Paired with per-namespace RoleBindings
	// in the chart, this is the multi-tenant operator-instances
	// pattern: one operator per tenant-group, disjoint watch sets.
	//
	// Each entry must be a valid Kubernetes namespace (DNS-1123
	// label). main.go validates the list at flag-parse time and
	// rejects an invalid entry with rc=2.
	WatchNamespaces []string

	// KnownLibraryAliases enumerates the OCI-mounted library aliases
	// available cluster-wide (one per subdirectory of every -library-path).
	// The reconciler + admission webhook use these to reject snippets
	// whose spec.libraries[*].importPath shadows an OCI mount — the CR
	// would silently win and the operator would never consult the OCI
	// volume, surprising operators who set up the mount expecting it to
	// be used. Empty disables the check.
	//
	// Derived at startup from OCILibraries (its keys); kept separately
	// so the admission webhook validator can avoid the eval-package
	// dependency.
	KnownLibraryAliases []string

	// OCILibraries holds the byte contents of every OCI-mounted
	// library the operator was booted with, keyed by alias. The
	// reconciler merges these into the per-snippet library map after
	// the CR-based LibraryRef resolution so snippets can `import
	// "<alias>/file"` against operator-shipped shared libraries
	// without declaring a CR LibraryRef. CR aliases CAN'T collide
	// (admission rejects shadow attempts); the merge is purely
	// additive.
	OCILibraries map[string]eval.Library

	// RerenderRate is the steady-state per-snippet re-render budget, in
	// tokens per second. Parsed from --rerender-rate=N/period via
	// ParseRerenderRate.
	RerenderRate float64

	// RerenderBurst is the per-snippet token-bucket depth.
	RerenderBurst int

	// ExtVars is the operator-level std.extVar map. Keys here take
	// precedence over CR-level spec.externalVariables; conflicts are
	// rejected at admission, with a reconciler fallback that fails Ready.
	ExtVars map[string]string

	// EvaluationTimeout bounds a single reconcile's snippet eval; zero
	// disables the bound. Mirrors the HTTP path's --evaluation-timeout.
	EvaluationTimeout time.Duration

	// MaxStack overrides go-jsonnet's default call-stack depth; zero keeps
	// the default. Mirrors the HTTP path's --max-stack.
	MaxStack int

	// Store is the artifact backend the Publisher writes tarballs to.
	// Nil leaves the reconciler in eval-only mode (no ExternalArtifact
	// upserts) — useful for early bring-up and unit tests. In production
	// main.go wires either a *storage.Store (filesystem, single-pod) or
	// a *storage.S3Backend (object store, HA across replicas) depending
	// on -storage-backend.
	Store storage.Backend

	// StorageBaseURL is the public URL prefix the operator's storage HTTP
	// server serves tarballs from. Combined with Store.Path it forms each
	// artifact's status.artifact.url. Required when Store is set.
	StorageBaseURL string

	// MaxArtifactBytes caps the published content size in bytes — the
	// rendered output in Output=rendered mode, the whole source tree in
	// Output=source mode. A snippet over the cap fails with
	// ReasonArtifactTooLarge before any disk/S3 write. Zero disables.
	MaxArtifactBytes int64

	// ArtifactGCGrace is the minimum time a revision evicted from the
	// keep-set remains fetchable before storage GC removes it. Closes
	// the pin→fetch race in which a Flux consumer reads
	// status.artifact a moment before the operator garbage-collects the
	// superseded revision, then 404s on the dereference. Forwarded
	// verbatim to Publisher.GCGrace and on to storage.Backend.Prune;
	// zero restores the immediate-prune behavior. Default in main.go is
	// 5m — wide enough to cover steady-state consumer fetch latencies
	// (kustomize-controller, helm-controller, stageset-controller) while
	// keeping storage growth bounded.
	ArtifactGCGrace time.Duration

	// EnableWebhook opts into running the validating admission webhook for
	// JsonnetSnippet. The webhook checks operator-level ext-var conflicts
	// at admission time; the reconciler enforces the same invariant as a
	// fallback when the webhook is bypassed.
	EnableWebhook bool

	// WebhookCertDir tells controller-runtime where to find the TLS cert
	// and key for the webhook server. Provisioning of these files is the
	// helm chart's responsibility (cert-manager or an init container).
	WebhookCertDir string

	// WebhookPort is the port the webhook server binds to. Defaults to 9443
	// when unset.
	WebhookPort int

	// SkipControllerNameValidation disables controller-runtime's
	// once-per-process check that every controller name is unique. Only
	// the envtest harness sets this — main.go-driven invocations always
	// boot a single controller per process where the validation is a
	// useful safety net.
	SkipControllerNameValidation bool

	// SkipImpersonation makes the reconciler use the manager's own client
	// for tenant-side operations instead of building a per-snippet
	// impersonating client. Only the envtest harness sets this so its
	// reconcile tests can run without provisioning per-snippet SAs and
	// RBAC; production must keep the default (impersonation on) so a
	// compromised or buggy snippet can't reach beyond the tenant's SA
	// permissions.
	SkipImpersonation bool

	// LeaderElection toggles controller-runtime's leader-election lock.
	// When true the manager only runs reconcilers + cache + the webhook
	// while holding the lease at LeaderElectionNamespace/LeaderElectionID —
	// letting operators scale the Deployment without two replicas
	// double-reconciling the same JsonnetSnippet. Defaults on in main.go
	// when --enable-flux-integration is set; tests opt out via the
	// zero-value (false) to avoid the cost of a lease per envtest case.
	LeaderElection bool

	// LeaderElectionID is the Lease object's name. Multiple installations
	// in the same cluster must pick distinct IDs (helm uses the release
	// name) so they don't fight over a shared lease.
	LeaderElectionID string

	// LeaderElectionNamespace holds the Lease. main.go fills this from a
	// flag (typically the release namespace); empty falls back to
	// controller-runtime's downward-API discovery.
	LeaderElectionNamespace string

	// MaxWithdrawWait bounds how long a deleted JsonnetSnippet may
	// stay stuck in the finalizer while its Publisher.Withdraw keeps
	// failing. Past the bound the reconciler force-drops the
	// finalizer, emits a Warning WithdrawForced event, and lets the
	// snippet be garbage-collected — possibly leaving an orphaned
	// tarball in storage. Without this escape a permanently-broken
	// backend (S3 perma-down, revoked RBAC, deleted bucket) makes
	// snippets undeletable, which blocks namespace teardown.
	//
	// Zero falls back to defaultMaxWithdrawWait (1h). Negative is
	// treated as zero; force-drop is unconditional only when an
	// operator explicitly sets a very small value (test fixtures).
	MaxWithdrawWait time.Duration

	// MetricsBindAddress is the host:port the controller-runtime metrics
	// server listens on. The default "" leaves controller-runtime's own
	// default in place (":8080"), which collides with the jsonnet HTTP
	// server, so main.go always sets this explicitly. "0" disables the
	// metrics server entirely.
	MetricsBindAddress string

	// Logger receives operator-level events. nil falls back to slog.Default.
	Logger *slog.Logger

	// OnReady, when non-nil, is invoked exactly once after the manager's
	// cache has synced — on every replica, leader or not (it is wired as a
	// non-leader-election runnable). main.go threads `HealthState.SetReady`
	// here so the pod's readiness probe stays 503 until the operator has
	// booted and its cache is warm. Gating on leader election instead would
	// leave standby replicas permanently NotReady even though they serve the
	// HTTP renderer + storage and are ready to take over reconciliation.
	OnReady func()
}

type PublishResult struct {
	Revision string
	URL      string
}

type Publisher struct {
	Store   storage.Backend
	BaseURL string
	Clock   func() time.Time

	// MaxArtifactBytes caps the published content size in bytes. The cap
	// measures the sum of the tarball members' content — len(rendered) in
	// Output=rendered mode, the whole sourceFiles tree in Output=source
	// mode — so it bounds what actually lands on disk/S3 in either mode. A
	// snippet over the cap fails with ErrArtifactTooLarge before any
	// write, so one runaway snippet can't fill the storage volume. Zero
	// disables.
	MaxArtifactBytes int64

	// GCGrace is the minimum time a revision evicted from the keep-set
	// remains fetchable before Prune removes it. Closes the pin→fetch
	// race in which a Flux consumer reads status.artifact a moment
	// before the operator garbage-collects the superseded revision and
	// then 404s on the dereference. Threaded through to
	// storage.Backend.Prune verbatim; zero restores eager pruning.
	GCGrace time.Duration
}

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

type SnippetReconciler struct {
	Client client.Client
	Scheme *runtime.Scheme

	// APIReader bypasses the manager's cache for the pre-publish
	// staleness gate. The cache can lag behind the apiserver under
	// load, so a fresh Get just before the downstream-visible commit
	// catches a spec edit that landed during this reconcile's fetch +
	// eval phase. nil falls back to Client — fine for tests but
	// production wiring (defaultBuilder) sets it from mgr.GetAPIReader.
	APIReader client.Reader

	// RestConfig is the manager's rest.Config, cloned per-reconcile and
	// stamped with a freshly-minted ServiceAccount token to mint a tenant
	// client. nil disables impersonation — fake-client tests that don't
	// model TokenRequest set this to nil and the reconciler falls back to
	// Client for tenant operations.
	RestConfig *rest.Config

	// TokenCache mints + caches bearer tokens for the tenant SAs the
	// reconciler impersonates. nil pairs with RestConfig nil — both off
	// means "use r.Client". With RestConfig set, TokenCache must be set
	// too; defaultBuilder wires the pair.
	TokenCache *tokenCache

	// ClientCache memoizes the impersonating controller-runtime client per
	// (namespace, SA) so a reconcile against a cached, unchanged tenant
	// token can skip client.New entirely (which builds a fresh RESTMapper
	// + transport — non-trivial on the per-event hot path). nil disables
	// caching; tenantClient still works, just constructs a client on every
	// call. defaultBuilder wires this together with TokenCache.
	ClientCache *tenantClientCache

	// CycleCache memoizes the dependency-cycle verdict per snippet UID,
	// keyed by snip.Generation. The watch handlers (mapJsonnetLibrary,
	// mapFluxSource) Forget the entries they enqueue so a library or
	// upstream-source change re-triggers the walk — generation alone does
	// not catch a transitively-introduced cycle. nil disables caching;
	// detectSourceRefCycle still works, just walks the graph every
	// reconcile.
	CycleCache *cycleCache

	// DefaultServiceAccount fills in for snippets that omit
	// spec.serviceAccountName. Empty leaves such snippets rejected with
	// ReasonServiceAccountMissing.
	DefaultServiceAccount string

	// NoCrossNamespaceRefs mirrors Config.NoCrossNamespaceRefs; when true,
	// a snippet referencing a library outside its own namespace fails with
	// ReasonCrossNamespaceRefRejected.
	NoCrossNamespaceRefs bool

	// ExtVars is the operator-level external-variable map. Conflicting CR
	// keys are rejected with ReasonExternalVariableConflict.
	ExtVars map[string]string

	// EvaluationTimeout bounds a single eval; zero disables the bound.
	EvaluationTimeout time.Duration

	// MaxStack overrides go-jsonnet's default; zero keeps the default.
	MaxStack int

	// Fetcher resolves spec.sourceRef into in-memory files via Flux source
	// CRs. nil makes any sourceRef return ReasonSourceRefNotYetSupported
	// — useful for tests that don't model source-controller. Production
	// defaultBuilder always wires sources.New.
	Fetcher SourceFetcher

	// Publisher writes the artifact tarball and upserts the matching
	// ExternalArtifact CR. nil disables publication — useful for unit tests
	// that only exercise the eval pipeline.
	Publisher *Publisher

	// Limiter applies per-snippet rate limiting before each eval+publish.
	// nil disables the limiter (tests, or operator started with
	// --rerender-rate=0).
	Limiter *RateLimiter

	// Clock is the time source for RevisionEntry timestamps. nil falls
	// back to time.Now — tests inject a fake.
	Clock func() time.Time

	// EventRecorder emits standard Kubernetes Events on Ready-condition
	// transitions so Flux's notification-controller (or any other
	// Event-sourced alerter) can route via Alert CRs targeting
	// JsonnetSnippet. nil disables event emission. The reason and
	// message mirror what's written to the Ready condition; severity
	// is Normal for Synced and Warning for every other reason.
	//
	// Uses the events.v1 API (k8s.io/client-go/tools/events) — the
	// older record.EventRecorder was deprecated in controller-runtime.
	// notification-controller listens on both forms.
	EventRecorder events.EventRecorder

	// OCILibraries mirrors Config.OCILibraries — the byte contents of
	// every operator-shipped (OCI-mounted) library, keyed by alias.
	// resolveLibraries merges these into the per-snippet library map
	// after the CR loop, so snippets can `import "<alias>/file"`
	// against shared libraries without a CR LibraryRef.
	OCILibraries map[string]eval.Library

	// KnownLibraryAliases mirrors Config.KnownLibraryAliases — populated
	// at SetupWithManager time. The reconciler consults it to reject
	// LibraryRef.ImportPath values that collide with OCI-mounted
	// library names.
	KnownLibraryAliases []string

	// MaxWithdrawWait bounds the time a deleted snippet's finalizer
	// can hold while Publisher.Withdraw keeps failing. Past the
	// bound, reconcileDelete force-drops the finalizer, emits a
	// Warning WithdrawForced event, and the snippet is GC'd —
	// possibly leaving an orphan tarball. Zero falls back to
	// defaultMaxWithdrawWait. See Config.MaxWithdrawWait for the
	// rationale.
	MaxWithdrawWait time.Duration

	// Logger receives reconcile-level logs. nil falls back to slog.Default.
	Logger *slog.Logger
	// contains filtered or unexported fields
}

type SnippetValidator struct {
	// OperatorExtVars is the operator-level external-variable set.
	OperatorExtVars map[string]string

	// KnownLibraryAliases enumerates OCI-mounted library aliases the
	// operator was started with. A LibraryRef.ImportPath that shadows
	// one is rejected at admission so the user notices the OCI mount is
	// being silently overridden — empty disables the check.
	KnownLibraryAliases []string

	// Client reads the existing snippet graph for cycle detection. nil
	// disables cycle checks at admission — the reconciler still enforces
	// the invariant. defaultBuilder always wires the manager's client.
	Client client.Client
}

type SourceFetcher interface {
	Fetch(ctx context.Context, c client.Client, ref *jaasv1.SourceRef, ownerNs string) (*sources.Result, error)
}