feat(Reference): Add public API endpoints to get references

Calling the public API endpoints will check for matching registered reference providers that implement `IPublicReferenceProvider` and call their respective functions. If no matching provider is found, the default `LinkReferenceProvider` will be used to provide open graph data. The frontend reference widget components will call these endpoints from unauthorized sessions, e.g. in public shares. If present, the sharing token of the origin URL is passed to `resolveReferencePublic()` as additional information for the reference provider to determine the access scope. This allows the respective reference providers to determine whether the origin share has access to the linked resource. `getCacheKeyPublic` also gets the sharing token so it can scope the cached entry to it. Contributes to #45978 Signed-off-by: Jonas <[email protected]>
nextcloud · Jul 17, 2024 · 1671bf3 · 1671bf3
1 parent b06ce83
commit 1671bf3
Show file tree

Hide file tree

Showing 9 changed files with 794 additions and 14 deletions.
diff --git a/core/Controller/ReferenceApiController.php b/core/Controller/ReferenceApiController.php
@@ -10,6 +10,7 @@
 
 use OC\Core\ResponseDefinitions;
 use OCP\AppFramework\Http;
+use OCP\AppFramework\Http\Attribute\AnonRateLimit;
 use OCP\AppFramework\Http\Attribute\ApiRoute;
 use OCP\AppFramework\Http\DataResponse;
 use OCP\Collaboration\Reference\IDiscoverableReferenceProvider;
@@ -22,6 +23,8 @@
  * @psalm-import-type CoreReferenceProvider from ResponseDefinitions
  */
 class ReferenceApiController extends \OCP\AppFramework\OCSController {
+	private const LIMIT_MAX = 15;
+
 	public function __construct(
 		string $appName,
 		IRequest $request,
@@ -62,6 +65,39 @@ public function extract(string $text, bool $resolve = false, int $limit = 1): Da
 		]);
 	}
 
+	/**
+	 * @PublicPage
+	 *
+	 * Extract references from a text
+	 *
+	 * @param string $text Text to extract from
+	 * @param string $sharingToken Token of the public share
+	 * @param bool $resolve Resolve the references
+	 * @param int $limit Maximum amount of references to extract, limited to 15
+	 * @return DataResponse<Http::STATUS_OK, array{references: array<string, CoreReference|null>}, array{}>
+	 *
+	 * 200: References returned
+	 */
+	#[ApiRoute(verb: 'POST', url: '/extractPublic', root: '/references')]
+	#[AnonRateLimit(limit: 10, period: 120)]
+	public function extractPublic(string $text, string $sharingToken, bool $resolve = false, int $limit = 1): DataResponse {
+		$references = $this->referenceManager->extractReferences($text);
+
+		$result = [];
+		$index = 0;
+		foreach ($references as $reference) {
+			if ($index++ >= min($limit, self::LIMIT_MAX)) {
+				break;
+			}
+
+			$result[$reference] = $resolve ? $this->referenceManager->resolveReference($reference, true, $sharingToken)?->jsonSerialize() : null;
+		}
+
+		return new DataResponse([
+			'references' => $result
+		]);
+	}
+
 	/**
 	 * @NoAdminRequired
 	 *
@@ -73,6 +109,7 @@ public function extract(string $text, bool $resolve = false, int $limit = 1): Da
 	 * 200: Reference returned
 	 */
 	#[ApiRoute(verb: 'GET', url: '/resolve', root: '/references')]
+	#[AnonRateLimit(limit: 10, period: 120)]
 	public function resolveOne(string $reference): DataResponse {
 		/** @var ?CoreReference $resolvedReference */
 		$resolvedReference = $this->referenceManager->resolveReference(trim($reference))?->jsonSerialize();
@@ -82,6 +119,28 @@ public function resolveOne(string $reference): DataResponse {
 		return $response;
 	}
 
+	/**
+	 * @PublicPage
+	 *
+	 * Resolve from a public page
+	 *
+	 * @param string $reference Reference to resolve
+	 * @param string $sharingToken Token of the public share
+	 * @return DataResponse<Http::STATUS_OK, array{references: array<string, ?CoreReference>}, array{}>
+	 *
+	 * 200: Reference returned
+	 */
+	#[ApiRoute(verb: 'GET', url: '/resolvePublic', root: '/references')]
+	#[AnonRateLimit(limit: 10, period: 120)]
+	public function resolveOnePublic(string $reference, string $sharingToken): DataResponse {
+		/** @var ?CoreReference $resolvedReference */
+		$resolvedReference = $this->referenceManager->resolveReference(trim($reference), true, trim($sharingToken))?->jsonSerialize();
+
+		$response = new DataResponse(['references' => [$reference => $resolvedReference]]);
+		$response->cacheFor(3600, false, true);
+		return $response;
+	}
+
 	/**
 	 * @NoAdminRequired
 	 *
@@ -110,6 +169,36 @@ public function resolve(array $references, int $limit = 1): DataResponse {
 		]);
 	}
 
+	/**
+	 * @PublicPage
+	 *
+	 * Resolve multiple references from a public page
+	 *
+	 * @param string[] $references References to resolve
+	 * @param string $sharingToken Token of the public share
+	 * @param int $limit Maximum amount of references to resolve, limited to 15
+	 * @return DataResponse<Http::STATUS_OK, array{references: array<string, CoreReference|null>}, array{}>
+	 *
+	 * 200: References returned
+	 */
+	#[ApiRoute(verb: 'POST', url: '/resolvePublic', root: '/references')]
+	#[AnonRateLimit(limit: 10, period: 120)]
+	public function resolvePublic(array $references, string $sharingToken, int $limit = 1): DataResponse {
+		$result = [];
+		$index = 0;
+		foreach ($references as $reference) {
+			if ($index++ >= min($limit, self::LIMIT_MAX)) {
+				break;
+			}
+
+			$result[$reference] = $this->referenceManager->resolveReference($reference, true, $sharingToken)?->jsonSerialize();
+		}
+
+		return new DataResponse([
+			'references' => $result
+		]);
+	}
+
 	/**
 	 * @NoAdminRequired
 	 *