From dff738453b8bf84c3478abdc925d36e2e3cc83f7 Mon Sep 17 00:00:00 2001
From: Alvaro Aleman <alvaroaleman@users.noreply.github.com>
Date: Sat, 1 Apr 2023 17:17:12 -0400
Subject: [PATCH] :book: Add a design for cache options configuration

---
 designs/cache_options.md | 104 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 104 insertions(+)
 create mode 100644 designs/cache_options.md

diff --git a/designs/cache_options.md b/designs/cache_options.md
new file mode 100644
index 0000000000..ce4d4a2e52
--- /dev/null
+++ b/designs/cache_options.md
@@ -0,0 +1,104 @@
+Cache Options
+===================
+
+This document describes how we imagine the cache options to look like in
+the future.
+
+## Goals
+
+* Align everyone on what settings on the cache we want to support and
+  their configuration surface
+* Ensure that we support both complicated cache setups and provide an
+  intuitive configuration UX
+
+## Non-Goals
+
+* Line out how the actual implementation of the cache itself will look like.
+  The assumption is that the most granular level we will end up with is
+  "per object multiple namespaces with distinct selectors" and that this
+  can be implemented using a "meta cache" that delegates per object and by
+  extending the current multi-namespace cache
+* Outline any kind of timeline for when these settings will be implemented.
+  Implementation will happen gradually over time whenever someone steps up
+  to do the actual work
+
+## Proposal
+
+
+```
+type CacheSetting struct {
+  // LabelSelector specifies a label selector. A nil value allows to
+  // default this.
+  LabelSelector labels.Selector
+
+  // FieldSelector specifics a field selector. A nil value allows to
+  // default this.
+  FieldSelector fields.Selector
+
+  // Transform specifies a transform func. A nil value allows to default
+  // this.
+  Transform     toolscache.TransformFunc
+
+  // UnsafeDisableDeepCopy specifies if List and Get requests against the
+  // cache should not DeepCopy. A nil value allows to default this.
+  UnsafeDisableDeepCopy *bool
+}
+
+
+type ByObject struct {
+  // Namespaces maps a namespace name to cache setting. If set, only the
+  // namespaces in this map will be cached.
+  //
+  // A nil value in this map means "fall through to the ByObject CacheSetting"
+  //
+  // An empty value in this map means "No Selectors".
+  //
+  // It is possible to have specific CacheSettings for just some namespaces
+  // but cache all namespaces by using the empty string as map key for
+  // "all namespaces". This wil then include all namespaces that do not have
+  // a more specific setting.
+  //
+  // A nil map allows to default this to the caches DefaultNamespaces setting.
+  // An empty map prevents this.
+  Namespaces map[string]*CacheSetting
+
+  // CacheSettings will be used if Namespaces is empty or for entries in
+  // Namespaces that have a nil value.
+  //
+  // If nil, this will be defaulted to the caches DefaultLabelSelector,
+  // DefaultFieldSelector and DefaultTransform.
+  CacheSettings *CacheSetting
+}
+
+type Options struct {
+  // ByObject specifies per-object cache settings. If unset for a given
+  // object, this will fall through to Default* settings.
+  ByObject map[client.Object]*ByObject
+
+  // DefaultNamespaces maps namespace names to cache settings. If set, it
+  // will be usd for all objects that have a nil Namespaces setting.
+  //
+  // It is possible to have specific CacheSettings for just some namespaces
+  // but cache all namespaces by using the empty string as map key for
+  // "all namespaces". This wil then include all namespaces that do not have
+  // a more specific setting.
+  //
+  // If CacheSetting is nil, DefaultLabelSelector, DefaultFieldSelector
+  // and DefaultTransform will be used if set.
+  DefaultNamespaces map[string]*CacheSetting
+
+  // DefaultLabelSelector is the label selector that will be used as
+  // the default field label selector for everything that doesn't
+  // have one configured.
+  DefaultLabelSelector labels.Selector
+
+  // DefaultFieldSelector is the field selector that will be used as
+  // the default field selector for everything that doesn't have
+  // one configured.
+  DefaultFieldSelector fields.Selector
+
+  // DefaultUnsafeDisableDeepCopy is the default for UnsafeDisableDeepCopy
+  // for everything that doesn't specify this.
+  DefaultUnsafeDisableDeepCopy *bool
+}
+```