From f95ce30994852185026ad6675caf509af7dc333c Mon Sep 17 00:00:00 2001
From: Richard Steinmetz <richard@steinmetz.cloud>
Date: Tue, 12 Aug 2025 11:28:36 +0200
Subject: [PATCH] feat: indicate reason for preloading notifications

Signed-off-by: Richard Steinmetz <richard@steinmetz.cloud>
---
 lib/composer/composer/autoload_classmap.php   |  1 +
 lib/composer/composer/autoload_static.php     |  1 +
 lib/private/Notification/Manager.php          |  9 ++++-
 .../Notification/IPreloadableNotifier.php     |  7 +++-
 .../NotificationPreloadReason.php             | 40 +++++++++++++++++++
 5 files changed, 55 insertions(+), 3 deletions(-)
 create mode 100644 lib/public/Notification/NotificationPreloadReason.php

diff --git a/lib/composer/composer/autoload_classmap.php b/lib/composer/composer/autoload_classmap.php
index 7a0f910db69..986ea2097b4 100644
--- a/lib/composer/composer/autoload_classmap.php
+++ b/lib/composer/composer/autoload_classmap.php
@@ -701,6 +701,7 @@ return array(
     'OCP\\Notification\\IncompleteNotificationException' => $baseDir . '/lib/public/Notification/IncompleteNotificationException.php',
     'OCP\\Notification\\IncompleteParsedNotificationException' => $baseDir . '/lib/public/Notification/IncompleteParsedNotificationException.php',
     'OCP\\Notification\\InvalidValueException' => $baseDir . '/lib/public/Notification/InvalidValueException.php',
+    'OCP\\Notification\\NotificationPreloadReason' => $baseDir . '/lib/public/Notification/NotificationPreloadReason.php',
     'OCP\\Notification\\UnknownNotificationException' => $baseDir . '/lib/public/Notification/UnknownNotificationException.php',
     'OCP\\OCM\\Events\\ResourceTypeRegisterEvent' => $baseDir . '/lib/public/OCM/Events/ResourceTypeRegisterEvent.php',
     'OCP\\OCM\\Exceptions\\OCMArgumentException' => $baseDir . '/lib/public/OCM/Exceptions/OCMArgumentException.php',
diff --git a/lib/composer/composer/autoload_static.php b/lib/composer/composer/autoload_static.php
index b8352d41f65..ecb634a31cf 100644
--- a/lib/composer/composer/autoload_static.php
+++ b/lib/composer/composer/autoload_static.php
@@ -742,6 +742,7 @@ class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2
         'OCP\\Notification\\IncompleteNotificationException' => __DIR__ . '/../../..' . '/lib/public/Notification/IncompleteNotificationException.php',
         'OCP\\Notification\\IncompleteParsedNotificationException' => __DIR__ . '/../../..' . '/lib/public/Notification/IncompleteParsedNotificationException.php',
         'OCP\\Notification\\InvalidValueException' => __DIR__ . '/../../..' . '/lib/public/Notification/InvalidValueException.php',
+        'OCP\\Notification\\NotificationPreloadReason' => __DIR__ . '/../../..' . '/lib/public/Notification/NotificationPreloadReason.php',
         'OCP\\Notification\\UnknownNotificationException' => __DIR__ . '/../../..' . '/lib/public/Notification/UnknownNotificationException.php',
         'OCP\\OCM\\Events\\ResourceTypeRegisterEvent' => __DIR__ . '/../../..' . '/lib/public/OCM/Events/ResourceTypeRegisterEvent.php',
         'OCP\\OCM\\Exceptions\\OCMArgumentException' => __DIR__ . '/../../..' . '/lib/public/OCM/Exceptions/OCMArgumentException.php',
diff --git a/lib/private/Notification/Manager.php b/lib/private/Notification/Manager.php
index 0cbda651a8b..62fa66df85c 100644
--- a/lib/private/Notification/Manager.php
+++ b/lib/private/Notification/Manager.php
@@ -22,6 +22,7 @@ use OCP\Notification\IncompleteParsedNotificationException;
 use OCP\Notification\INotification;
 use OCP\Notification\INotifier;
 use OCP\Notification\IPreloadableNotifier;
+use OCP\Notification\NotificationPreloadReason;
 use OCP\Notification\UnknownNotificationException;
 use OCP\RichObjectStrings\IRichTextFormatter;
 use OCP\RichObjectStrings\IValidator;
@@ -391,14 +392,18 @@ class Manager implements IManager {
 		return $notification;
 	}
 
-	public function preloadDataForParsing(array $notifications, string $languageCode): void {
+	public function preloadDataForParsing(
+		array $notifications,
+		string $languageCode,
+		NotificationPreloadReason $reason,
+	): void {
 		$notifiers = $this->getNotifiers();
 		foreach ($notifiers as $notifier) {
 			if (!($notifier instanceof IPreloadableNotifier)) {
 				continue;
 			}
 
-			$notifier->preloadDataForParsing($notifications, $languageCode);
+			$notifier->preloadDataForParsing($notifications, $languageCode, $reason);
 		}
 	}
 
diff --git a/lib/public/Notification/IPreloadableNotifier.php b/lib/public/Notification/IPreloadableNotifier.php
index 2bdcd84d254..ac2e98d1f93 100644
--- a/lib/public/Notification/IPreloadableNotifier.php
+++ b/lib/public/Notification/IPreloadableNotifier.php
@@ -26,6 +26,11 @@ interface IPreloadableNotifier extends INotifier {
 	 *
 	 * @param INotification[] $notifications The notifications which are about to be prepared in the next step.
 	 * @param string $languageCode The code of the language that should be used to prepare the notification.
+	 * @param NotificationPreloadReason $reason The reason for preloading the given notifications to facilitate smarter decisions about what data to preload.
 	 */
-	public function preloadDataForParsing(array $notifications, string $languageCode): void;
+	public function preloadDataForParsing(
+		array $notifications,
+		string $languageCode,
+		NotificationPreloadReason $reason,
+	): void;
 }
diff --git a/lib/public/Notification/NotificationPreloadReason.php b/lib/public/Notification/NotificationPreloadReason.php
new file mode 100644
index 00000000000..f7b39cc3e87
--- /dev/null
+++ b/lib/public/Notification/NotificationPreloadReason.php
@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\Notification;
+
+use OCP\AppFramework\Attribute\Consumable;
+
+/**
+ * Indicates the reason for preloading notifications to facilitate smarter decisions about what data
+ * to preload.
+ */
+#[Consumable(since: '32.0.0')]
+enum NotificationPreloadReason {
+	/**
+	 * Preparing a single notification for many users.
+	 *
+	 * @since 32.0.0
+	 */
+	case Push;
+
+	/**
+	 * Preparing many notifications for many users.
+	 *
+	 * @since 32.0.0
+	 */
+	case Email;
+
+	/**
+	 * Preparing many notifications for a single user.
+	 *
+	 * @since 32.0.0
+	 */
+	case EndpointController;
+}