Documentation
¶
Overview ¶
Package cache owns the cache layer. There are two distinct caching concerns in the platform:
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.
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")
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) DelPrefix ¶
func (NoopExternalCache) DelPrefix(context.Context, string) error