M2: local cache of pack indexes (ngb_index)

Opening a repository lists index/ once and downloads only index files
that are not cached; packs written by this server are cached on write,
stale cache rows are dropped. Each resumable step therefore no longer
downloads every index file from the location.

lib/Repository/BlobIndex.php

@@ -24,22 +24,51 @@ final class BlobIndex {
 	/** @var array<string, true> blobs added in this run but whose pack is not uploaded yet */
 	private array $pending = [];
 
+	private ?IIndexCache $cache = null;
+	private string $repositoryId = '';
+	/** @var int index files downloaded by the last load() (for tests and diagnostics) */
+	public int $downloaded = 0;
+
 	public function __construct(
 		private IBackend $backend,
 		private StreamCipher $cipher,
 	) {
 	}
 
+	public function setCache(IIndexCache $cache, string $repositoryId): void {
+		$this->cache = $cache;
+		$this->repositoryId = $repositoryId;
+	}
+
+	/**
+	 * Load the index: one listing of index/, entries from the local cache where available,
+	 * and only the index files that are not cached yet are downloaded. Cached packs that no
+	 * longer exist on the backend are dropped from the cache.
+	 */
 	public function load(): void {
+		$cached = $this->cache?->all($this->repositoryId) ?? [];
+		$present = [];
+		$this->downloaded = 0;
 		foreach ($this->backend->list('index') as $path) {
 			$packId = basename($path);
-			$fh = $this->backend->get($path);
-			$entries = json_decode($this->cipher->decryptString((string)stream_get_contents($fh), 'index:' . $packId), true, 512, JSON_THROW_ON_ERROR);
-			fclose($fh);
+			$present[$packId] = true;
+			if (isset($cached[$packId])) {
+				$entries = $cached[$packId];
+			} else {
+				$fh = $this->backend->get($path);
+				$entries = json_decode($this->cipher->decryptString((string)stream_get_contents($fh), 'index:' . $packId), true, 512, JSON_THROW_ON_ERROR);
+				fclose($fh);
+				$this->downloaded++;
+				$this->cache?->put($this->repositoryId, $packId, $entries);
+			}
 			foreach ($entries as $e) {
 				$this->blobs[$e['id']] = [$packId, $e['offset'], $e['length'], $e['raw'], $e['flags']];
 			}
 		}
+		$stale = array_keys(array_diff_key($cached, $present));
+		if ($stale !== []) {
+			$this->cache?->remove($this->repositoryId, $stale);
+		}
 	}
 
 	public function has(string $id): bool {
@@ -68,6 +97,7 @@ final class BlobIndex {
 		fwrite($stream, $this->cipher->encryptString(json_encode($entries, JSON_THROW_ON_ERROR), 'index:' . $packId));
 		rewind($stream);
 		$this->backend->put('index/' . $packId, $stream);
+		$this->cache?->put($this->repositoryId, $packId, $entries);
 		foreach ($entries as $e) {
 			$this->blobs[$e['id']] = [$packId, $e['offset'], $e['length'], $e['raw'], $e['flags']];
 			unset($this->pending[$e['id']]);

lib/Repository/IIndexCache.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+// SPDX-FileCopyrightText: 2026 Dillard Blom
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+namespace OCA\NgBackup\Repository;
+
+/** Optional local cache of pack index entries (the repository's index/ files stay authoritative). */
+interface IIndexCache {
+	/** @return array<string, list<array{id:string, offset:int, length:int, raw:int, flags:int}>> packId => entries */
+	public function all(string $repositoryId): array;
+
+	/** @param list<array{id:string, offset:int, length:int, raw:int, flags:int}> $entries */
+	public function put(string $repositoryId, string $packId, array $entries): void;
+
+	/** @param list<string> $packIds */
+	public function remove(string $repositoryId, array $packIds): void;
+}

lib/Repository/Repository.php

@@ -64,7 +64,7 @@ final class Repository {
 	}
 
 	/** Open with the master key the server holds (scheduled backups, no passphrase needed). */
-	public static function openWithKey(IBackend $backend, KeyRing $keys): self {
+	public static function openWithKey(IBackend $backend, KeyRing $keys, ?IIndexCache $cache = null): self {
 		$config = self::readConfig($backend);
 		try {
 			$ok = isset($config['check']) && (new StreamCipher($keys))->decryptString((string)base64_decode($config['check'], true), 'config-check') === $config['id'];
@@ -75,10 +75,18 @@ final class Repository {
 			throw new RepositoryException('This repository was created with a different key');
 		}
 		$repo = new self($backend, $keys, $config['id']);
+		if ($cache !== null) {
+			$repo->index->setCache($cache, $config['id']);
+		}
 		$repo->index->load();
 		return $repo;
 	}
 
+	/** Index files downloaded when this repository was opened (0 when the local cache was complete). */
+	public function indexDownloads(): int {
+		return $this->index->downloaded;
+	}
+
 	private static function readConfig(IBackend $backend): array {
 		try {
 			$fh = $backend->get('config');