cache

package
v0.9.0 Latest Latest
Warning

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

Go to latest
Published: Nov 10, 2026 License: Apache-2.0 Imports: 5 Imported by: 1

Documentation

Overview

Package cache owns the cache layer. There are two distinct caching concerns in the platform:

  1. The informer cache — the controller-runtime shared cache backed by Kubernetes API watches. This is the SOURCE OF TRUTH for all CR reads. Correctness-bearing reads (cross-CR lookups, prerequisite checks) always go here via client.Reader.

  2. The external cache — an optional distributed backend (Redis, Memcached) used as a WRITE-THROUGH PROJECTION LAYER for resolved contracts. This is advisory only. A miss or error always falls through to full computation. Correctness never depends on a hit.

The two layers are composed in Cache and never cross-wired: the informer cache provides correctness, the external cache provides observability and opportunistic reuse within a generation.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ListByField

func ListByField[T client.ObjectList](ctx context.Context, rdr client.Reader, list T, field, value string) error

ListByField lists objects from the informer cache matching a single field=value pair. The field must have been registered via IndexField before the cache started.

Example:

var builds buildv1.BuildList
err := core.ListByField(ctx, cache.Reader, &builds, ".spec.repo", "github.com/foo/bar")

func WaitForSync

func WaitForSync(ctx context.Context, c cache.Cache) bool

WaitForSync blocks until the informer cache has completed its initial sync against the API server. Called during manager startup to ensure reconcilers do not operate against a partially populated cache.

Types

type Cache

type Cache struct {
	// Reader is the informer-backed source of truth for all CR reads.
	// Injected from the controller-runtime manager cache.
	Reader client.Reader

	// Indexer allows domains to register field indexes on the informer cache
	// for efficient filtered list queries.
	Indexer client.FieldIndexer

	// External is the optional distributed cache for resolved contract
	// projections. Never nil — falls back to NoopExternalCache if unconfigured.
	External ExternalCache
}

Cache composes the controller-runtime shared informer cache (source of truth) with an optional external cache (opportunistic projection layer).

The two layers serve different purposes and must not be confused:

  • Reader: informer-backed, always consistent with the API server via watches. Use for all correctness-bearing reads.
  • External: distributed backend, advisory only. Use for resolved contract projections where a stale or missing value is safe to recompute.

func NewCache

func NewCache(mgr ctrl.Manager, external ExternalCache) *Cache

NewCache constructs a Cache from the controller-runtime manager and an optional external backend. A nil external is silently replaced with NoopExternalCache and logged so a misconfigured backend is never an invisible failure.

func (*Cache) IndexField

func (c *Cache) IndexField(ctx context.Context, obj client.Object, field string, extract func(client.Object) []string) error

IndexField registers a field extractor on the informer cache, enabling efficient MatchingFields queries via ListByField. Must be called during manager setup before the cache starts.

type ExternalCache

type ExternalCache interface {
	Set(ctx context.Context, key string, val any, ttl time.Duration) error

	Get(ctx context.Context, key string, into any) (found bool, err error)

	Del(ctx context.Context, key string) error
	// DelPrefix removes all keys sharing the given prefix. Backends without
	// key enumeration (e.g. Memcached) may implement this as a no-op.
	// Callers should prefer generation-scoped keys over relying on prefix
	// invalidation for correctness guarantees.
	DelPrefix(ctx context.Context, prefix string) error
}

ExternalCache defines the distributed cache contract for resolved contract projections. Implementations (Redis, Memcached) live under cache/adapter/ — core never imports backend libraries directly. Serialization is the implementation's responsibility.

Semantics:

  • Get returning (false, nil) is a MISS, not an error. Callers MUST treat the external cache as advisory and fall through to full computation on any miss.
  • Errors from any method are infrastructure failures only. They MUST degrade gracefully — log and continue — never abort reconciliation.
  • Keys should be generation-scoped (kind:namespace/name:genN:field) to guarantee the happy path always misses on spec change. See ObjectCache in cache/ for the canonical key schema.

type NoopExternalCache

type NoopExternalCache struct{}

NoopExternalCache is the zero-value external cache. It satisfies the ExternalCache interface and safely ignores all calls. Every Get is a miss. Used when no external backend is configured so the rest of the platform needs no nil checks.

func (NoopExternalCache) Del

func (NoopExternalCache) DelPrefix

func (NoopExternalCache) Get

func (NoopExternalCache) Set

Jump to

Keyboard shortcuts

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