feat: add predis based Key-Value cache (redis / valkey etc)

Assisted-by: ClaudeCode:claude-opus-4-8
Co-authored-by: Kate <26026535+provokateurin@users.noreply.github.com>
Co-authored-by: Côme Chilliet <91878298+come-nc@users.noreply.github.com>
Signed-off-by: Ferdinand Thiessen <opensource@fthiessen.de>

Author: 3 people

.github/workflows/phpunit-kvstore.yml

@@ -0,0 +1,141 @@
+# SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+# SPDX-License-Identifier: MIT
+
+name: PHPUnit key-value store
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: phpunit-kvstore-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+env:
+  VALKEY_IMAGE: valkey/valkey:8
+
+jobs:
+  changes:
+    runs-on: ubuntu-latest-low
+
+    outputs:
+      src: ${{ steps.changes.outputs.src}}
+
+    steps:
+      - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
+        id: changes
+        continue-on-error: true
+        with:
+          filters: |
+            src:
+              - '.github/workflows/phpunit-kvstore.yml'
+              - '3rdparty/**'
+              - '**/appinfo/**'
+              - '**.php'
+
+  phpunit-kvstore:
+    runs-on: ubuntu-latest
+
+    needs: changes
+    if: needs.changes.outputs.src != 'false'
+
+    strategy:
+      fail-fast: false
+      matrix:
+        php-versions: ["8.3", "8.5"]
+        # The three supported topologies for the key-value store cache
+        topology: ["single", "cluster", "sentinel"]
+
+    name: KV store ${{ matrix.topology }} (PHP ${{ matrix.php-versions }})
+
+    steps:
+      - name: Checkout server
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+          submodules: true
+
+      - name: Set up php ${{ matrix.php-versions }}
+        uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 #v2.37.2
+        timeout-minutes: 5
+        with:
+          php-version: ${{ matrix.php-versions }}
+          # https://docs.nextcloud.com/server/stable/admin_manual/installation/source_installation.html#prerequisites-for-manual-installation
+          extensions: bz2, ctype, curl, dom, fileinfo, gd, iconv, intl, json, libxml, mbstring, openssl, pcntl, pdo_sqlite, posix, session, simplexml, sqlite, xmlreader, xmlwriter, zip, zlib
+          coverage: none
+          ini-file: development
+          ini-values: disable_functions=""
+        env:
+          fail-fast: true
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Start Valkey (single server)
+        if: matrix.topology == 'single'
+        run: |
+          docker run -d --name kv-single -p 6379:6379 "${VALKEY_IMAGE}"
+          timeout 60 sh -c 'until docker exec kv-single valkey-cli ping | grep -q PONG; do sleep 1; done'
+
+      - name: Start Valkey (cluster)
+        if: matrix.topology == 'cluster'
+        run: |
+          for port in 7000 7001 7002 7003 7004 7005; do
+            docker run -d --name "kv-cluster-$port" --network host "${VALKEY_IMAGE}" \
+              valkey-server --port "$port" --cluster-enabled yes \
+              --cluster-config-file "nodes-$port.conf" --cluster-node-timeout 5000 \
+              --appendonly no --save ""
+          done
+          # Wait for every node to answer before forming the cluster
+          for port in 7000 7001 7002 7003 7004 7005; do
+            timeout 60 sh -c "until docker exec kv-cluster-$port valkey-cli -p $port ping | grep -q PONG; do sleep 1; done"
+          done
+          docker exec kv-cluster-7000 valkey-cli --cluster create \
+            127.0.0.1:7000 127.0.0.1:7001 127.0.0.1:7002 \
+            127.0.0.1:7003 127.0.0.1:7004 127.0.0.1:7005 \
+            --cluster-replicas 1 --cluster-yes
+
+      - name: Start Valkey (sentinel)
+        if: matrix.topology == 'sentinel'
+        run: |
+          docker run -d --name kv-master --network host "${VALKEY_IMAGE}" \
+            valkey-server --port 6379
+          docker run -d --name kv-replica --network host "${VALKEY_IMAGE}" \
+            valkey-server --port 6380 --replicaof 127.0.0.1 6379
+          printf 'port 26379\nsentinel monitor mymaster 127.0.0.1 6379 1\nsentinel down-after-milliseconds mymaster 5000\nsentinel failover-timeout mymaster 10000\n' > sentinel.conf
+          docker run -d --name kv-sentinel --network host -v "$PWD/sentinel.conf:/etc/valkey/sentinel.conf" \
+            "${VALKEY_IMAGE}" valkey-sentinel /etc/valkey/sentinel.conf
+          timeout 60 sh -c 'until docker exec kv-sentinel valkey-cli -p 26379 ping | grep -q PONG; do sleep 1; done'
+
+      - name: Set up dependencies
+        run: composer i
+
+      - name: Set up Nextcloud
+        run: |
+          mkdir data
+          cp tests/kvstore-${{ matrix.topology }}.config.php config/
+          cp tests/preseed-config.php config/config.php
+          ./occ maintenance:install --verbose --database=sqlite --database-name=nextcloud --database-user=root --database-pass=rootpassword --admin-user admin --admin-pass admin
+          php -f tests/enable_all.php
+
+      - name: PHPUnit key-value store tests
+        run: composer run test -- --group KeyValueCache --log-junit junit.xml
+
+      - name: Print logs
+        if: always()
+        run: |
+          cat data/nextcloud.log
+
+  summary:
+    permissions:
+      contents: none
+    runs-on: ubuntu-latest-low
+    needs: [changes, phpunit-kvstore]
+
+    if: always()
+
+    name: phpunit-kvstore-summary
+
+    steps:
+      - name: Summary status
+        run: if ${{ needs.changes.outputs.src != 'false' && needs.phpunit-kvstore.result != 'success' }}; then exit 1; fi

3rdparty

@@ -3026,6 +3026,11 @@
       <code><![CDATA[$this->timeFactory->getTime()]]></code>
     </InvalidScalarArgument>
   </file>
+  <file src="core/Command/Memcache/RedisCommand.php">
+    <DeprecatedClass>
+      <code><![CDATA[protected]]></code>
+    </DeprecatedClass>
+  </file>
   <file src="core/Command/Security/BruteforceAttempts.php">
     <DeprecatedMethod>
       <code><![CDATA[getAttempts]]></code>
@@ -4246,6 +4251,11 @@
       <code><![CDATA[array{X-Request-Id: string, Cache-Control: string, Content-Security-Policy: string, Feature-Policy: string, X-Robots-Tag: string, Last-Modified?: string, ETag?: string, ...H}]]></code>
     </MoreSpecificReturnType>
   </file>
+  <file src="lib/public/ICache.php">
+    <AmbiguousConstantInheritance>
+      <code><![CDATA[DEFAULT_TTL]]></code>
+    </AmbiguousConstantInheritance>
+  </file>
   <file src="public.php">
     <DeprecatedMethod>
       <code><![CDATA[getAppValue]]></code>

build/psalm-baseline.xml

@@ -1783,6 +1783,87 @@
 	 */
 	'memcache_customprefix' => 'mycustomprefix',
 
+	/**
+	 * Connection details for the Key-Value store used for in-memory caching,
+	 * for example when using Valkey or Redis.
+	 *
+	 * This is the brand-independent successor of the ``redis`` and
+	 * ``redis.cluster`` options below and supports the latest Valkey and Redis
+	 * releases. Three topologies are supported:
+	 * a single server, a Sentinel managed replication set, and a
+	 * server cluster. Configure exactly one of ``server``, ``sentinel`` or
+	 * ``seeds``.
+	 *
+	 * For enhanced security, it is recommended to configure ACLs in
+	 * the cache server and configure the ``user`` and ``password`` (or a TLS
+	 * client certificate). Alternatively, you can also configure the cache
+	 * server to just use a ``password``.
+	 * See https://valkey.io/topics/security/ for more information when using Valkey.
+	 */
+	'memcache.kvstore' => [
+		/**
+		 * Single server setup.
+		 *
+		 * Also used as the connection template for the ``sentinel`` managed
+		 * primary / replica connections.
+		 */
+		'server' => [
+			'host' => 'localhost', // can also be a Unix domain socket: '/tmp/cache.sock'
+			'port' => 6379, // ignored for Unix domain sockets
+			// Protocol used to connect. One of 'tcp', 'tls' or 'unix'.
+			// When omitted it is derived from the host (a leading '/' means 'unix').
+			'protocol' => 'tcp',
+		],
+
+		/**
+		 * Sentinel managed replication setup.
+		 *
+		 * Provide the name of the monitored service and one entry per Sentinel
+		 * node. Each seed uses the same format as the ``server`` entry above.
+		 * Uncomment to enable and remove the ``server`` / ``seeds`` entries.
+		 */
+		//'sentinel' => [
+		//	'service' => 'mymaster',
+		//	'seeds' => [
+		//		['host' => 'localhost', 'port' => 26379],
+		//		['host' => 'localhost', 'port' => 26380],
+		//	],
+		//],
+
+		/**
+		 * Cluster setup.
+		 *
+		 * Provide some or all of the cluster nodes to bootstrap discovery.
+		 * Each seed uses the same format as the ``server`` entry above.
+		 * Uncomment to enable and remove the ``server`` / ``sentinel`` entries.
+		 */
+		//'seeds' => [
+		//	['host' => 'localhost', 'port' => 7000],
+		//	['host' => 'localhost', 'port' => 7001],
+		//],
+
+		// Optional: username, only sent when the cache server uses ACLs.
+		'user' => '',
+		// Optional: if not defined, no password will be used.
+		'password' => '',
+		// Optional: select a numbered database. Only supported for single
+		// servers and Sentinel setups, clusters always use database 0.
+		'dbindex' => 0,
+		// Optional: connection timeout in seconds (float). 0 means no timeout.
+		'timeout' => 0.0,
+		// Optional: read/write timeout in seconds (float). 0 means no timeout.
+		'read_timeout' => 0.0,
+		// Optional: keep the connection open across requests. Defaults to false.
+		'persistent' => false,
+		// Optional: when the 'tls' protocol is used, provide the SSL context.
+		// SSL context options, see https://www.php.net/manual/en/context.ssl.php
+		//'ssl_context' => [
+		//	'local_cert' => '/certs/cache.crt',
+		//	'local_pk' => '/certs/cache.key',
+		//	'cafile' => '/certs/ca.crt',
+		//],
+	],
+
 	/**
 	 * Connection details for Redis to use for memory caching in a single server configuration.
 	 *
@@ -1792,6 +1873,8 @@
 	 *
 	 * We also support Redis SSL/TLS encryption as of version 6.
 	 * See https://redis.io/topics/encryption for more information.
+	 *
+	 * @deprecated 34.0.0 use `memcache.kvstore` instead which supports also Valkey.
 	 */
 	'redis' => [
 		'host' => 'localhost', // can also be a Unix domain socket: '/tmp/redis.sock'
@@ -1831,6 +1914,8 @@
 	 *
 	 * Authentication works with phpredis version 4.2.1+. See
 	 * https://github.com/phpredis/phpredis/commit/c5994f2a42b8a348af92d3acb4edff1328ad8ce1
+	 *
+	 * @deprecated 34.0.0 use `memcache.kvstore` instead which supports also Valkey.
 	 */
 	'redis.cluster' => [
 		'seeds' => [ // provide some or all of the cluster servers to bootstrap discovery, port required

config/config.sample.php

@@ -1953,6 +1953,8 @@
     'OC\\Memcache\\CASTrait' => $baseDir . '/lib/private/Memcache/CASTrait.php',
     'OC\\Memcache\\Cache' => $baseDir . '/lib/private/Memcache/Cache.php',
     'OC\\Memcache\\Factory' => $baseDir . '/lib/private/Memcache/Factory.php',
+    'OC\\Memcache\\KeyValueCache' => $baseDir . '/lib/private/Memcache/KeyValueCache.php',
+    'OC\\Memcache\\KeyValueCacheFactory' => $baseDir . '/lib/private/Memcache/KeyValueCacheFactory.php',
     'OC\\Memcache\\LoggerWrapperCache' => $baseDir . '/lib/private/Memcache/LoggerWrapperCache.php',
     'OC\\Memcache\\Memcached' => $baseDir . '/lib/private/Memcache/Memcached.php',
     'OC\\Memcache\\NullCache' => $baseDir . '/lib/private/Memcache/NullCache.php',

lib/composer/composer/autoload_classmap.php

@@ -1994,6 +1994,8 @@ class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2
         'OC\\Memcache\\CASTrait' => __DIR__ . '/../../..' . '/lib/private/Memcache/CASTrait.php',
         'OC\\Memcache\\Cache' => __DIR__ . '/../../..' . '/lib/private/Memcache/Cache.php',
         'OC\\Memcache\\Factory' => __DIR__ . '/../../..' . '/lib/private/Memcache/Factory.php',
+        'OC\\Memcache\\KeyValueCache' => __DIR__ . '/../../..' . '/lib/private/Memcache/KeyValueCache.php',
+        'OC\\Memcache\\KeyValueCacheFactory' => __DIR__ . '/../../..' . '/lib/private/Memcache/KeyValueCacheFactory.php',
         'OC\\Memcache\\LoggerWrapperCache' => __DIR__ . '/../../..' . '/lib/private/Memcache/LoggerWrapperCache.php',
         'OC\\Memcache\\Memcached' => __DIR__ . '/../../..' . '/lib/private/Memcache/Memcached.php',
         'OC\\Memcache\\NullCache' => __DIR__ . '/../../..' . '/lib/private/Memcache/NullCache.php',

lib/composer/composer/autoload_static.php

@@ -164,7 +164,7 @@ public function withServerVersionPrefix(\Closure $closure): void {
 	#[\Override]
 	public function createLocking(string $prefix = ''): IMemcache {
 		$cache = new $this->lockingCacheClass($this->getGlobalPrefix() . '/' . $prefix);
-		if ($this->lockingCacheClass === Redis::class) {
+		if ($this->supportsInstrumentation($this->lockingCacheClass)) {
 			if ($this->profiler->isEnabled()) {
 				// We only support the profiler with Redis
 				$cache = new ProfilerWrapperCache($cache, 'Locking');
@@ -187,7 +187,7 @@ public function createLocking(string $prefix = ''): IMemcache {
 	#[\Override]
 	public function createDistributed(string $prefix = ''): ICache {
 		$cache = new $this->distributedCacheClass($this->getGlobalPrefix() . '/' . $prefix);
-		if ($this->distributedCacheClass === Redis::class) {
+		if ($this->supportsInstrumentation($this->distributedCacheClass)) {
 			if ($this->profiler->isEnabled()) {
 				// We only support the profiler with Redis
 				$cache = new ProfilerWrapperCache($cache, 'Distributed');
@@ -210,7 +210,7 @@ public function createDistributed(string $prefix = ''): ICache {
 	#[\Override]
 	public function createLocal(string $prefix = ''): ICache {
 		$cache = new $this->localCacheClass($this->getGlobalPrefix() . '/' . $prefix);
-		if ($this->localCacheClass === Redis::class) {
+		if ($this->supportsInstrumentation($this->localCacheClass)) {
 			if ($this->profiler->isEnabled()) {
 				// We only support the profiler with Redis
 				$cache = new ProfilerWrapperCache($cache, 'Local');
@@ -249,6 +249,15 @@ public function isLocalCacheAvailable(): bool {
 		return $this->localCacheClass !== self::NULL_CACHE;
 	}
 
+	/**
+	 * Whether the given cache backend supports the profiler and logger wrappers.
+	 *
+	 * @param class-string<ICache> $cacheClass
+	 */
+	private function supportsInstrumentation(string $cacheClass): bool {
+		return $cacheClass === Redis::class || $cacheClass === KeyValueCache::class;
+	}
+
 	public function clearAll(): void {
 		$this->createLocal()->clear();
 		$this->createDistributed()->clear();