From ad39dab6ca4eae14db24169863726d9f02642bef Mon Sep 17 00:00:00 2001
From: Richard Steinmetz <richard@steinmetz.cloud>
Date: Mon, 4 Aug 2025 09:12:57 +0200
Subject: [PATCH] feat(notifications): provide method to preload many
 notifications at once

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          | 12 +++++++
 lib/public/Notification/IManager.php          |  2 +-
 lib/public/Notification/INotifier.php         |  5 +++
 .../Notification/IPreloadableNotifier.php     | 31 +++++++++++++++++++
 6 files changed, 51 insertions(+), 1 deletion(-)
 create mode 100644 lib/public/Notification/IPreloadableNotifier.php

diff --git a/lib/composer/composer/autoload_classmap.php b/lib/composer/composer/autoload_classmap.php
index 3f2dbe5edf9..bc633fb7e31 100644
--- a/lib/composer/composer/autoload_classmap.php
+++ b/lib/composer/composer/autoload_classmap.php
@@ -696,6 +696,7 @@ return array(
     'OCP\\Notification\\IManager' => $baseDir . '/lib/public/Notification/IManager.php',
     'OCP\\Notification\\INotification' => $baseDir . '/lib/public/Notification/INotification.php',
     'OCP\\Notification\\INotifier' => $baseDir . '/lib/public/Notification/INotifier.php',
+    'OCP\\Notification\\IPreloadableNotifier' => $baseDir . '/lib/public/Notification/IPreloadableNotifier.php',
     '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',
diff --git a/lib/composer/composer/autoload_static.php b/lib/composer/composer/autoload_static.php
index 233b667add9..1f129604270 100644
--- a/lib/composer/composer/autoload_static.php
+++ b/lib/composer/composer/autoload_static.php
@@ -737,6 +737,7 @@ class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2
         'OCP\\Notification\\IManager' => __DIR__ . '/../../..' . '/lib/public/Notification/IManager.php',
         'OCP\\Notification\\INotification' => __DIR__ . '/../../..' . '/lib/public/Notification/INotification.php',
         'OCP\\Notification\\INotifier' => __DIR__ . '/../../..' . '/lib/public/Notification/INotifier.php',
+        'OCP\\Notification\\IPreloadableNotifier' => __DIR__ . '/../../..' . '/lib/public/Notification/IPreloadableNotifier.php',
         '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',
diff --git a/lib/private/Notification/Manager.php b/lib/private/Notification/Manager.php
index 8c457db8beb..0cbda651a8b 100644
--- a/lib/private/Notification/Manager.php
+++ b/lib/private/Notification/Manager.php
@@ -21,6 +21,7 @@ use OCP\Notification\IncompleteNotificationException;
 use OCP\Notification\IncompleteParsedNotificationException;
 use OCP\Notification\INotification;
 use OCP\Notification\INotifier;
+use OCP\Notification\IPreloadableNotifier;
 use OCP\Notification\UnknownNotificationException;
 use OCP\RichObjectStrings\IRichTextFormatter;
 use OCP\RichObjectStrings\IValidator;
@@ -390,6 +391,17 @@ class Manager implements IManager {
 		return $notification;
 	}
 
+	public function preloadDataForParsing(array $notifications, string $languageCode): void {
+		$notifiers = $this->getNotifiers();
+		foreach ($notifiers as $notifier) {
+			if (!($notifier instanceof IPreloadableNotifier)) {
+				continue;
+			}
+
+			$notifier->preloadDataForParsing($notifications, $languageCode);
+		}
+	}
+
 	/**
 	 * @param INotification $notification
 	 */
diff --git a/lib/public/Notification/IManager.php b/lib/public/Notification/IManager.php
index 23664af17cd..207a89344b0 100644
--- a/lib/public/Notification/IManager.php
+++ b/lib/public/Notification/IManager.php
@@ -11,7 +11,7 @@ namespace OCP\Notification;
 use OCP\AppFramework\Attribute\Consumable;
 
 #[Consumable(since: '9.0.0')]
-interface IManager extends IApp, INotifier {
+interface IManager extends IApp, IPreloadableNotifier {
 	/**
 	 * @param string $appClass The service must implement IApp, otherwise a
 	 *                         \InvalidArgumentException is thrown later
diff --git a/lib/public/Notification/INotifier.php b/lib/public/Notification/INotifier.php
index bdc7207216f..b6851e3dfb3 100644
--- a/lib/public/Notification/INotifier.php
+++ b/lib/public/Notification/INotifier.php
@@ -10,6 +10,11 @@ namespace OCP\Notification;
 
 use OCP\AppFramework\Attribute\Implementable;
 
+/**
+ * Please consider implementing {@see IPreloadableNotifier} to improve performance. It allows to
+ * preload and cache data for many notifications at once instead of loading the data for each
+ * prepared notification separately.
+ */
 #[Implementable(since: '9.0.0')]
 interface INotifier {
 	/**
diff --git a/lib/public/Notification/IPreloadableNotifier.php b/lib/public/Notification/IPreloadableNotifier.php
new file mode 100644
index 00000000000..2bdcd84d254
--- /dev/null
+++ b/lib/public/Notification/IPreloadableNotifier.php
@@ -0,0 +1,31 @@
+<?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\Implementable;
+
+/**
+ * Allow notifier implementations to preload and cache data for many notifications at once to
+ * improve performance by, for example, bundling SQL queries.
+ */
+#[Implementable(since: '32.0.0')]
+interface IPreloadableNotifier extends INotifier {
+	/**
+	 * This method provides a way for notifier implementations to preload and cache data for many
+	 * notifications. The data is meant to be consumed later in the {@see INotifier::prepare()}
+	 * method to improve performance.
+	 *
+	 * @since 32.0.0
+	 *
+	 * @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.
+	 */
+	public function preloadDataForParsing(array $notifications, string $languageCode): void;
+}