From bab07a7547729c693f4e91441f97c56f390c83da Mon Sep 17 00:00:00 2001
From: kalvinparker <106995826+kalvinparker@users.noreply.github.com>
Date: Fri, 14 Nov 2025 15:14:09 +0000
Subject: [PATCH] docs(proposals): add persistent token cache proposal

---
 docs/proposals/persistent-token-cache.md | 30 ++++++++++++++++++++++++
 1 file changed, 30 insertions(+)
 create mode 100644 docs/proposals/persistent-token-cache.md

diff --git a/docs/proposals/persistent-token-cache.md b/docs/proposals/persistent-token-cache.md
new file mode 100644
index 0000000..4f83ce5
--- /dev/null
+++ b/docs/proposals/persistent-token-cache.md
@@ -0,0 +1,30 @@
+# Proposal: Persistent / Distributed Token Cache
+
+Summary
+-------
+Introduce an optional pluggable token cache interface for registry auth tokens so deployments can opt for a shared cache (Redis, Memcached, or file-backed) across multiple Watchtower instances.
+
+Motivation
+----------
+- In multi-instance deployments, the in-memory token cache avoids redundant token requests only per instance. A shared cache reduces token endpoint load and synchronizes token usage across instances.
+
+Proposal
+--------
+- Define a `TokenCache` interface (Get/Set/Delete) in `pkg/registry/auth/cache_interface.go`.
+- Keep the existing in-memory cache as the default implementation.
+- Provide example Redis-backed implementation in `contrib/redis-token-cache/` (optional).
+
+Migration
+---------
+1. Add `TokenCache` interface and adapter in `pkg/registry/auth`.
+2. Wire `TokenCache` into `GetBearerHeader` to check the cache via the interface.
+3. Add configuration options or environment variable to enable persistent cache and connection details.
+
+Risks
+-----
+- Operational complexity for configuration (credentials for Redis, etc.).
+- Need to handle TTL semantics and clock skew.
+
+References
+----------
+- Current in-memory cache: `pkg/registry/auth/auth.go` (`tokenCache`, `getCachedToken`, `storeToken`).