perf: cache pre-fetched mailboxes on the HTTP level

Signed-off-by: Richard Steinmetz <[email protected]>

[skip ci]

Author: st3iny

lib/Db/Mailbox.php

@@ -159,6 +159,7 @@ public function jsonSerialize() {
 			'unread' => $this->unseen,
 			'myAcls' => $this->myAcls,
 			'shared' => $this->shared === true,
+			'cacheBuster' => $this->getCacheBuster(),
 		];
 	}
 }

src/components/Mailbox.vue

@@ -274,6 +274,7 @@ export default {
 					const envelopes = await this.mainStore.fetchEnvelopes({
 						mailboxId: mailbox.databaseId,
 						limit: this.initialPageSize,
+						includeCacheBuster: true,
 					})
 					this.syncedMailboxes.add(mailbox.databaseId)
 					logger.debug(`Prefetched ${envelopes.length} envelopes for mailbox ${mailbox.displayName} (${mailbox.databaseId})`)

src/store/mainStore/actions.js

@@ -662,6 +662,7 @@ export default function mainStoreActions() {
 			mailboxId,
 			query,
 			addToUnifiedMailboxes = true,
+			includeCacheBuster = false,
 		}) {
 			return handleHttpAuthErrors(async () => {
 				const mailbox = this.getMailbox(mailboxId)

src/tests/unit/service/MessageService.spec.js

@@ -0,0 +1,56 @@
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+import * as MessageService from '../../../service/MessageService.js'
+import axios from '@nextcloud/axios'
+import { generateUrl } from '@nextcloud/router'
+
+jest.mock('@nextcloud/axios')
+jest.mock('@nextcloud/router')
+
+describe('service/MessageService test suite', () => {
+	afterEach(() => {
+		jest.clearAllMocks()
+	})
+
+	it('should include a given cache buster as a URL parameter', async () => {
+		generateUrl.mockReturnValueOnce('/generated-url')
+		axios.get.mockResolvedValueOnce({ data: [] })
+
+		await MessageService.fetchEnvelopes(
+			13, // account id
+			21, // mailbox id
+			undefined, // query
+			undefined, // cursor
+			undefined, // limit
+			undefined, // sort ordre
+			undefined, // layout
+			'abcdef123', // cache buster
+		)
+
+		expect(axios.get).toHaveBeenCalledWith('/generated-url', {
+			params: {
+				mailboxId: 21,
+				v: 'abcdef123',
+			},
+		})
+	})
+
+	it('should not include a cache buster by default', async () => {
+		generateUrl.mockReturnValueOnce('/generated-url')
+		axios.get.mockResolvedValueOnce({ data: [] })
+
+		await MessageService.fetchEnvelopes(
+			13, // account id
+			21, // mailbox id
+		)
+
+		expect(axios.get).toHaveBeenCalledWith('/generated-url', {
+			params: {
+				mailboxId: 21,
+			},
+		})
+	})
+})

src/tests/unit/store/actions.spec.js

@@ -646,4 +646,45 @@ describe('Vuex store actions', () => {
 
 		expect(removeEnvelope).toBeFalsy()
 	})
+
+	it('includes a cache buster if requested', async() => {
+		const account = {
+			id: 13,
+			personalNamespace: 'INBOX.',
+			mailboxes: [],
+		}
+
+		store.addAccountMutation(account)
+		store.addMailboxMutation({
+			account,
+			mailbox: {
+				id: 'INBOX',
+				name: 'INBOX',
+				databaseId: 21,
+				accountId: 13,
+				specialRole: 'inbox',
+				cacheBuster: 'abcdef123',
+			},
+		})
+
+		store.addEnvelopesMutation = jest.fn()
+
+		MessageService.fetchEnvelopes.mockResolvedValueOnce([])
+
+		await store.fetchEnvelopes({
+			mailboxId: 21,
+			includeCacheBuster: true,
+		})
+
+		expect(MessageService.fetchEnvelopes).toHaveBeenCalledWith(
+			13, // account id
+			21, // mailbox id
+			undefined, // query
+			undefined, // cursor
+			20, // limit (PAGE_SIZE)
+			undefined, // sort ordre
+			undefined, // layout
+			'abcdef123', // cache buster
+		)
+	})
 })

tests/Unit/Controller/MessagesControllerTest.php

@@ -24,6 +24,8 @@
 use OCA\Mail\Contracts\IUserPreferences;
 use OCA\Mail\Controller\MessagesController;
 use OCA\Mail\Db\MailAccount;
+use OCA\Mail\Db\Mailbox;
+use OCA\Mail\Db\Message as DbMessage;
 use OCA\Mail\Db\Tag;
 use OCA\Mail\Exception\ClientException;
 use OCA\Mail\Exception\ServiceException;
@@ -1161,4 +1163,60 @@ public function testGetDkim() {
 		$this->assertInstanceOf(JSONResponse::class, $actualResponse);
 		$this->assertEquals(['valid' => true], $actualResponse->getData());
 	}
+
+	public static function provideCacheBusterData(): array {
+		return [
+			[null, false],
+			['', false],
+			['abcdef123', true],
+		];
+	}
+
+	/** @dataProvider provideCacheBusterData */
+	public function testIndexCacheBuster(?string $cacheBuster, bool $expectCaching): void {
+		$mailbox = new Mailbox();
+		$mailbox->setAccountId(100);
+		$this->mailManager->expects(self::once())
+			->method('getMailbox')
+			->with($this->userId, 100)
+			->willReturn($mailbox);
+		$mailAccount = new MailAccount();
+		$account = new Account($mailAccount);
+		$this->accountService->expects(self::once())
+			->method('find')
+			->with($this->userId, 100)
+			->willReturn($account);
+
+		$this->userPreferences->expects(self::once())
+			->method('getPreference')
+			->with($this->userId, 'sort-order', 'newest')
+			->willReturnArgument(2);
+
+		$messages = [
+			new DbMessage(),
+			new DbMessage(),
+		];
+		$this->mailSearch->expects(self::once())
+			->method('findMessages')
+			->with(
+				$account,
+				$mailbox,
+				'DESC',
+				null,
+				null,
+				null,
+				$this->userId,
+				'threaded',
+			)->willReturn($messages);
+
+		$actualResponse = $this->controller->index(100, null, null, null, null, $cacheBuster);
+
+		$cacheForHeader = $actualResponse->getHeaders()['Cache-Control'] ?? null;
+		$this->assertNotNull($cacheForHeader);
+		if ($expectCaching) {
+			$this->assertEquals('private, max-age=604800, immutable', $cacheForHeader);
+		} else {
+			$this->assertEquals('no-cache, no-store, must-revalidate', $cacheForHeader);
+		}
+	}
 }

tests/Unit/Db/MailboxTest.php

@@ -0,0 +1,63 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Mail\Tests\Unit\Db;
+
+use ChristophWurst\Nextcloud\Testing\TestCase;
+use OCA\Mail\Db\Mailbox;
+
+class MailboxTest extends TestCase {
+	private Mailbox $mailbox;
+
+	protected function setUp(): void {
+		parent::setUp();
+
+		$this->mailbox = new Mailbox();
+	}
+
+	public static function provideCacheBusterData(): array {
+		return [
+			['new', 'changed', 'vanished', 'bbddae86e09069fc10c9f2ac401363b4'],
+			[null, null, null, 'dca1f7641c34734a8cd1c7b1c45abf73'],
+		];
+	}
+
+	/** @dataProvider provideCacheBusterData */
+	public function testGetCacheBuster(
+		?string $syncNewToken,
+		?string $syncChangedToken,
+		?string $syncVanishedToken,
+		string $expectedCacheBuster,
+	): void {
+		$this->mailbox->setId(100);
+		$this->mailbox->setSyncNewToken($syncNewToken);
+		$this->mailbox->setSyncChangedToken($syncChangedToken);
+		$this->mailbox->setSyncVanishedToken($syncVanishedToken);
+
+		$this->assertEquals($expectedCacheBuster, $this->mailbox->getCacheBuster());
+	}
+
+	/** @dataProvider provideCacheBusterData */
+	public function testJsonSerializeCacheBuster(
+		?string $syncNewToken,
+		?string $syncChangedToken,
+		?string $syncVanishedToken,
+		string $expectedCacheBuster,
+	): void {
+		$this->mailbox->setId(100);
+		$this->mailbox->setSyncNewToken($syncNewToken);
+		$this->mailbox->setSyncChangedToken($syncChangedToken);
+		$this->mailbox->setSyncVanishedToken($syncVanishedToken);
+		$this->mailbox->setName('INBOX');
+
+		$json = $this->mailbox->jsonSerialize();
+		$this->assertArrayHasKey('cacheBuster', $json);
+		$this->assertEquals($expectedCacheBuster, $json['cacheBuster']);
+	}
+}