feat(fulltextsearch): new API

lib/composer/composer/autoload_classmap.php

@@ -17,6 +17,17 @@
     'NCU\\Config\\Lexicon\\Preset' => $baseDir . '/lib/unstable/Config/Lexicon/Preset.php',
     'NCU\\Config\\ValueType' => $baseDir . '/lib/unstable/Config/ValueType.php',
     'NCU\\Federation\\ISignedCloudFederationProvider' => $baseDir . '/lib/unstable/Federation/ISignedCloudFederationProvider.php',
+    'NCU\\FullTextSearch\\Exceptions\\ServiceNotFoundException' => $baseDir . '/lib/unstable/FullTextSearch/Exceptions/ServiceNotFoundException.php',
+    'NCU\\FullTextSearch\\IContentProvider' => $baseDir . '/lib/unstable/FullTextSearch/IContentProvider.php',
+    'NCU\\FullTextSearch\\IContentProviderImprovedSearch' => $baseDir . '/lib/unstable/FullTextSearch/IContentProviderImprovedSearch.php',
+    'NCU\\FullTextSearch\\IContentProviderSyncIndex' => $baseDir . '/lib/unstable/FullTextSearch/IContentProviderSyncIndex.php',
+    'NCU\\FullTextSearch\\IIndexQueryHelper' => $baseDir . '/lib/unstable/FullTextSearch/IIndexQueryHelper.php',
+    'NCU\\FullTextSearch\\ILoggerService' => $baseDir . '/lib/unstable/FullTextSearch/ILoggerService.php',
+    'NCU\\FullTextSearch\\IManager' => $baseDir . '/lib/unstable/FullTextSearch/IManager.php',
+    'NCU\\FullTextSearch\\IService' => $baseDir . '/lib/unstable/FullTextSearch/IService.php',
+    'NCU\\FullTextSearch\\Model\\Document' => $baseDir . '/lib/unstable/FullTextSearch/Model/Document.php',
+    'NCU\\FullTextSearch\\Model\\DocumentAccess' => $baseDir . '/lib/unstable/FullTextSearch/Model/DocumentAccess.php',
+    'NCU\\FullTextSearch\\Model\\UnindexedDocument' => $baseDir . '/lib/unstable/FullTextSearch/Model/UnindexedDocument.php',
     'NCU\\Security\\Signature\\Enum\\DigestAlgorithm' => $baseDir . '/lib/unstable/Security/Signature/Enum/DigestAlgorithm.php',
     'NCU\\Security\\Signature\\Enum\\SignatoryStatus' => $baseDir . '/lib/unstable/Security/Signature/Enum/SignatoryStatus.php',
     'NCU\\Security\\Signature\\Enum\\SignatoryType' => $baseDir . '/lib/unstable/Security/Signature/Enum/SignatoryType.php',
@@ -1775,6 +1786,7 @@
     'OC\\Files\\View' => $baseDir . '/lib/private/Files/View.php',
     'OC\\ForbiddenException' => $baseDir . '/lib/private/ForbiddenException.php',
     'OC\\FullTextSearch\\FullTextSearchManager' => $baseDir . '/lib/private/FullTextSearch/FullTextSearchManager.php',
+    'OC\\FullTextSearch\\Manager' => $baseDir . '/lib/private/FullTextSearch/Manager.php',
     'OC\\FullTextSearch\\Model\\DocumentAccess' => $baseDir . '/lib/private/FullTextSearch/Model/DocumentAccess.php',
     'OC\\FullTextSearch\\Model\\IndexDocument' => $baseDir . '/lib/private/FullTextSearch/Model/IndexDocument.php',
     'OC\\FullTextSearch\\Model\\SearchOption' => $baseDir . '/lib/private/FullTextSearch/Model/SearchOption.php',

lib/composer/composer/autoload_static.php

@@ -58,6 +58,17 @@ class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2
         'NCU\\Config\\Lexicon\\Preset' => __DIR__ . '/../../..' . '/lib/unstable/Config/Lexicon/Preset.php',
         'NCU\\Config\\ValueType' => __DIR__ . '/../../..' . '/lib/unstable/Config/ValueType.php',
         'NCU\\Federation\\ISignedCloudFederationProvider' => __DIR__ . '/../../..' . '/lib/unstable/Federation/ISignedCloudFederationProvider.php',
+        'NCU\\FullTextSearch\\Exceptions\\ServiceNotFoundException' => __DIR__ . '/../../..' . '/lib/unstable/FullTextSearch/Exceptions/ServiceNotFoundException.php',
+        'NCU\\FullTextSearch\\IContentProvider' => __DIR__ . '/../../..' . '/lib/unstable/FullTextSearch/IContentProvider.php',
+        'NCU\\FullTextSearch\\IContentProviderImprovedSearch' => __DIR__ . '/../../..' . '/lib/unstable/FullTextSearch/IContentProviderImprovedSearch.php',
+        'NCU\\FullTextSearch\\IContentProviderSyncIndex' => __DIR__ . '/../../..' . '/lib/unstable/FullTextSearch/IContentProviderSyncIndex.php',
+        'NCU\\FullTextSearch\\IIndexQueryHelper' => __DIR__ . '/../../..' . '/lib/unstable/FullTextSearch/IIndexQueryHelper.php',
+        'NCU\\FullTextSearch\\ILoggerService' => __DIR__ . '/../../..' . '/lib/unstable/FullTextSearch/ILoggerService.php',
+        'NCU\\FullTextSearch\\IManager' => __DIR__ . '/../../..' . '/lib/unstable/FullTextSearch/IManager.php',
+        'NCU\\FullTextSearch\\IService' => __DIR__ . '/../../..' . '/lib/unstable/FullTextSearch/IService.php',
+        'NCU\\FullTextSearch\\Model\\Document' => __DIR__ . '/../../..' . '/lib/unstable/FullTextSearch/Model/Document.php',
+        'NCU\\FullTextSearch\\Model\\DocumentAccess' => __DIR__ . '/../../..' . '/lib/unstable/FullTextSearch/Model/DocumentAccess.php',
+        'NCU\\FullTextSearch\\Model\\UnindexedDocument' => __DIR__ . '/../../..' . '/lib/unstable/FullTextSearch/Model/UnindexedDocument.php',
         'NCU\\Security\\Signature\\Enum\\DigestAlgorithm' => __DIR__ . '/../../..' . '/lib/unstable/Security/Signature/Enum/DigestAlgorithm.php',
         'NCU\\Security\\Signature\\Enum\\SignatoryStatus' => __DIR__ . '/../../..' . '/lib/unstable/Security/Signature/Enum/SignatoryStatus.php',
         'NCU\\Security\\Signature\\Enum\\SignatoryType' => __DIR__ . '/../../..' . '/lib/unstable/Security/Signature/Enum/SignatoryType.php',
@@ -1816,6 +1827,7 @@ class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2
         'OC\\Files\\View' => __DIR__ . '/../../..' . '/lib/private/Files/View.php',
         'OC\\ForbiddenException' => __DIR__ . '/../../..' . '/lib/private/ForbiddenException.php',
         'OC\\FullTextSearch\\FullTextSearchManager' => __DIR__ . '/../../..' . '/lib/private/FullTextSearch/FullTextSearchManager.php',
+        'OC\\FullTextSearch\\Manager' => __DIR__ . '/../../..' . '/lib/private/FullTextSearch/Manager.php',
         'OC\\FullTextSearch\\Model\\DocumentAccess' => __DIR__ . '/../../..' . '/lib/private/FullTextSearch/Model/DocumentAccess.php',
         'OC\\FullTextSearch\\Model\\IndexDocument' => __DIR__ . '/../../..' . '/lib/private/FullTextSearch/Model/IndexDocument.php',
         'OC\\FullTextSearch\\Model\\SearchOption' => __DIR__ . '/../../..' . '/lib/private/FullTextSearch/Model/SearchOption.php',

lib/private/AppFramework/Bootstrap/RegistrationContext.php

@@ -10,6 +10,7 @@
 namespace OC\AppFramework\Bootstrap;
 
 use Closure;
+use NCU\FullTextSearch\IService as IFullTextSearchService;
 use OC\Support\CrashReport\Registry;
 use OCP\AppFramework\App;
 use OCP\AppFramework\Bootstrap\IRegistrationContext;
@@ -145,6 +146,11 @@
 	/** @var array<array-key, string> */
 	private array $configLexiconClasses = [];
 
+	/** @var null|ServiceRegistration<IFullTextSearchService> */
+	private ?ServiceRegistration $fullTextSearchService = null;
+	/** @var array<array-key, string> */
+	private array $fullTextSearchContentProviders = [];
+
 	/** @var ServiceRegistration<ITeamResourceProvider>[] */
 	private array $teamResourceProviders = [];
 
@@ -443,6 +449,20 @@
 					$configLexiconClass
 				);
 			}
+
+			public function registerFullTextSearchService(string $service): void {
+				$this->context->registerFullTextSearchService(
+					$this->appId,
+					$service
+				);
+			}
+
+			public function registerFullTextSearchContentProvider(string $contentProviderClass): void {
+				$this->context->registerFullTextSearchContentProvider(
+					$this->appId,
+					$contentProviderClass
+				);
+			}
 		};
 	}
 
@@ -657,6 +677,24 @@
 		$this->configLexiconClasses[$appId] = $configLexiconClass;
 	}
 
+	public function registerFullTextSearchService(string $appId, string $service) {
+		if ($appId !== 'fulltextsearch') {
+			throw new RuntimeException('Only the FullTextSearch app is allowed to register a fts service');
+		}
+		if ($this->fullTextSearchService !== null) {
+			throw new RuntimeException('There can only be one FullTextSearch service');
+		}
+
+		$this->fullTextSearchService = new ServiceRegistration($appId, $service);
+	}
+
+	/**
+	 * @psalm-param class-string<ILexicon> $contentProviderClass
+	 */
+	public function registerFullTextSearchContentProvider(string $appId, string $contentProviderClass): void {
+		$this->fullTextSearchContentProviders[$appId] = $contentProviderClass;
+	}
+
 	/**
 	 * @param App[] $apps
 	 */
@@ -1031,4 +1069,18 @@
 
 		return \OCP\Server::get($this->configLexiconClasses[$appId]);
 	}
+
+	/**
+	 * @return ServiceRegistration<IFullTextSearchService>|null
+	 */
+	public function getFullTextSearchService(): ?ServiceRegistration {
+		return $this->fullTextSearchService;
+	}
+
+	/**
+	 * @return ServiceRegistration<\NCU\FullTextSearch\IContentProvider>[]
+	 */
+	public function getFullTextSearchContentProviders(): array {
+		return $this->fullTextSearchContentProviders;
+	}
 }

lib/private/FullTextSearch/Manager.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+namespace OC\FullTextSearch;
+
+use NCU\FullTextSearch\Exceptions\ServiceNotFoundException;
+use NCU\FullTextSearch\IContentProvider;
+use NCU\FullTextSearch\IManager;
+use NCU\FullTextSearch\IService;
+use OC\AppFramework\Bootstrap\Coordinator;
+use OC\AppFramework\Bootstrap\ServiceRegistration;
+use Psr\Container\ContainerInterface;
+
+class Manager implements IManager {
+	private ?IService $service = null;
+
+	public function __construct(
+		private readonly Coordinator $coordinator,
+		private readonly ContainerInterface $container,
+	) {
+	}
+
+	/**
+	 * @throws ServiceNotFoundException if no full text search service found
+	 */
+	public function getService(): IService {
+		if ($this->service === null) {
+			$registration = $this->coordinator->getRegistrationContext()?->getFullTextSearchService();
+			if ($registration === null) {
+				throw new ServiceNotFoundException('fts service not found');
+			}
+			$this->service = $this->container->get($registration->getService());
+		}
+
+		return $this->service;
+	}
+
+	/**
+	 * @return ServiceRegistration<IContentProvider>[]
+	 */
+	public function getContentProviders(): array {
+		return $this->coordinator->getRegistrationContext()?->getFullTextSearchContentProviders() ?? [];
+	}
+}

lib/private/Server.php

@@ -1208,6 +1208,7 @@ public function __construct($webRoot, \OC\Config $config) {
 		$this->registerAlias(\OCP\Dashboard\IManager::class, \OC\Dashboard\Manager::class);
 
 		$this->registerAlias(IFullTextSearchManager::class, FullTextSearchManager::class);
+		$this->registerAlias(\NCU\FullTextSearch\IManager::class, \OC\FullTextSearch\Manager::class);
 		$this->registerAlias(IFilesMetadataManager::class, FilesMetadataManager::class);
 
 		$this->registerAlias(ISubAdmin::class, SubAdmin::class);

lib/public/AppFramework/Bootstrap/IRegistrationContext.php

@@ -447,4 +447,21 @@ public function registerMailProvider(string $class): void;
 	 * @since 31.0.0
 	 */
 	public function registerConfigLexicon(string $configLexiconClass): void;
+
+	/**
+	 * allow FullTextSearch to register its service
+	 * @since 33.0.0
+	 */
+	public function registerFullTextSearchService(string $service): void;
+
+	/**
+	 * Register an implementation of \NCU\FullTextSearch\IContentProvider that
+	 * will handle the getaway with full text search to extract app's content
+	 *
+	 * @param string $contentProviderClass
+	 *
+	 * @psalm-param class-string<\NCU\FullTextSearch\IContentProvider> $contentProviderClass
+	 * @since 33.0.0
+	 */
+	public function registerFullTextSearchContentProvider(string $contentProviderClass): void;
 }

lib/unstable/FullTextSearch/Exceptions/ServiceNotFoundException.php

@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace NCU\FullTextSearch\Exceptions;
+
+use Exception;
+
+class ServiceNotFoundException extends Exception {
+}

lib/unstable/FullTextSearch/IContentProvider.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace NCU\FullTextSearch;
+
+use NCU\FullTextSearch\Model\Document;
+
+interface IContentProvider {
+	public function getId(): string;
+	public function getConfiguration(): array;
+
+//	public function setIndexOptions(IIndexOptions $options);
+	public function getDocument(string $documentId): ?Document;
+}

lib/unstable/FullTextSearch/IContentProviderImprovedSearch.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace NCU\FullTextSearch;
+
+use OCP\FullTextSearch\Model\ISearchRequest;
+use OCP\FullTextSearch\Model\ISearchResult;
+use OCP\FullTextSearch\Model\ISearchTemplate;
+
+/**
+ * implementing this interface to your content provider
+ * will complete it with search related features
+ */
+interface IContentProviderImprovedSearch {
+	public function getSearchTemplate(): ?ISearchTemplate;
+	public function improveSearchRequest(ISearchRequest $searchRequest): void;
+	public function improveSearchResult(ISearchResult $searchResult): void;
+}

lib/unstable/FullTextSearch/IContentProviderSyncIndex.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace NCU\FullTextSearch;
+
+use Generator;
+use OCP\FullTextSearch\IFullTextSearchManager;
+
+/**
+ * this interface needs to be implemented to re-generate a full sync
+ * if not implemented, the only source of documents to be indexed are via the API
+ *
+ * @see IFullTextSearchManager::requestIndex()
+ */
+interface IContentProviderSyncIndex {
+	/*
+	 * if $qh is ignored, indexes are compared lately in the process
+	 * if the IIndexQueryHelper is useless but returned documents are to be indexed, you must
+	 * initiated the method with a call to $qh->notNeeded()
+	 *
+	 * @return Generator<UnindexedDocument|[UnindexedDocument]>
+	 */
+	public function getUnindexedDocuments(IIndexQueryHelper $qh): Generator;
+}

lib/unstable/FullTextSearch/IIndexQueryHelper.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace NCU\FullTextSearch;
+
+interface IIndexQueryHelper {
+}

lib/unstable/FullTextSearch/ILoggerService.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types = 1);
+
+/**
+ * SPDX-FileCopyrightText: 2017 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace NCU\FullTextSearch;
+
+interface ILoggerService {
+	public function info(string $entry): void;
+	public function action(string $entry): void;
+	public function warning(string $entry, array $data = []): void;
+	public function error(string $entry, array $data = []): void;
+}

lib/unstable/FullTextSearch/IManager.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 NCU\FullTextSearch;
+
+use NCU\FullTextSearch\Exceptions\ServiceNotFoundException;
+use OC\AppFramework\Bootstrap\ServiceRegistration;
+
+interface IManager {
+	/**
+	 * returns FullTextSearch API
+	 *
+	 * @throws ServiceNotFoundException if no full text search service found
+	 * @since 33.0.0
+	 */
+	public function getService(): IService;
+
+	/**
+	 * returns list of registered FullTextSearch config provider
+	 *
+	 * @return ServiceRegistration<IContentProvider>[]
+	 * @since 33.0.0
+	 */
+	public function getContentProviders(): array;
+}

lib/unstable/FullTextSearch/IService.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace NCU\FullTextSearch;
+
+interface IService {
+	public function getLogger(): ILoggerService;
+	public function requestIndex(string $providerId, string $documentId): void;
+	public function deleteIndex(string $providerId, string $documentId): void;
+}