feat: Add the possibility to create invitation links to circles

appinfo/info.xml

@@ -12,7 +12,7 @@
 Those groups of people can then be used by any other app for sharing purpose.
 		]]>
 	</description>
-	<version>35.0.0-dev.0</version>
+	<version>35.0.0-dev.1</version>
 	<licence>agpl</licence>
 	<author>Maxence Lange</author>
 	<types>

appinfo/routes.php

@@ -38,6 +38,10 @@
 		['name' => 'Local#editName', 'url' => '/circles/{circleId}/name', 'verb' => 'PUT'],
 		['name' => 'Local#editDescription', 'url' => '/circles/{circleId}/description', 'verb' => 'PUT'],
 		['name' => 'Local#editSetting', 'url' => '/circles/{circleId}/setting', 'verb' => 'PUT'],
+		['name' => 'Local#createInvitation', 'url' => '/circles/{circleId}/invitation', 'verb' => 'PUT'],
+		['name' => 'Local#revokeInvitation', 'url' => '/circles/{circleId}/invitation', 'verb' => 'DELETE'],
+		['name' => 'Local#getInvitation', 'url' => '/invitations/{invitationCode}', 'verb' => 'GET'],
+		['name' => 'Local#joinInvitation', 'url' => '/invitations/{invitationCode}', 'verb' => 'POST'],
 		['name' => 'Local#editConfig', 'url' => '/circles/{circleId}/config', 'verb' => 'PUT'],
 		['name' => 'Local#circleAvatar', 'url' => '/circles/{circleId}/avatar', 'verb' => 'GET'],
 		['name' => 'Local#uploadAvatar', 'url' => '/circles/{circleId}/avatar', 'verb' => 'POST'],

lib/Controller/LocalController.php

@@ -593,6 +593,97 @@ public function link(string $circleId, string $singleId): DataResponse {
 		}
 	}
 
+	#[NoAdminRequired]
+	public function createInvitation(string $circleId): DataResponse {
+		try {
+			$this->setCurrentFederatedUser();
+
+			$outcome = $this->circleService->createInvitation($circleId);
+
+			return new DataResponse($this->serializeArray($outcome));
+		} catch (\Exception $e) {
+			$this->e($e, ['circleId' => $circleId]);
+			throw new OCSException($e->getMessage(), (int)$e->getCode(), $e);
+		}
+	}
+
+	#[NoAdminRequired]
+	public function revokeInvitation(string $circleId): DataResponse {
+		try {
+			$this->setCurrentFederatedUser();
+
+			$outcome = $this->circleService->revokeInvitation($circleId);
+
+			return new DataResponse($this->serializeArray($outcome));
+		} catch (\Exception $e) {
+			$this->e($e, ['circleId' => $circleId]);
+			throw new OCSException($e->getMessage(), (int)$e->getCode(), $e);
+		}
+	}
+
+	#[NoAdminRequired]
+	#[BruteForceProtection(action: 'getInvitation')]
+	public function getInvitation(string $invitationCode): DataResponse {
+		try {
+			$this->setCurrentFederatedUser();
+
+			$circleProbe = (new CircleProbe())
+				->includeSystemCircles()
+				->includeHiddenCircles()
+				->filterByInvitationCode($invitationCode);
+
+			$circles = $this->circleService->getCircles($circleProbe);
+			if (empty($circles)) {
+				return new DataResponse([], Http::STATUS_NOT_FOUND);
+			}
+			$circle = reset($circles);
+
+			$membershipStatus = 'NOT_A_MEMBER';
+			if ($circle->hasInitiator()) {
+				if ($circle->getInitiator()->getLevel() > Member::LEVEL_NONE) {
+					$membershipStatus = 'MEMBER';
+				} elseif ($circle->getInitiator()->getStatus() === Member::STATUS_REQUEST) {
+					$membershipStatus = 'REQUESTED_MEMBERSHIP';
+				}
+			}
+
+			return new DataResponse([
+				'circleId' => $circle->getSingleId(),
+				'circleName' => $circle->getName(),
+				'membershipStatus' => $membershipStatus,
+			]);
+		} catch (\Exception $e) {
+			$this->e($e, ['circleId' => $invitationCode]);
+			throw new OCSException($e->getMessage(), (int)$e->getCode(), $e);
+		}
+	}
+
+	#[NoAdminRequired]
+	#[BruteForceProtection(action: 'joinInvitation')]
+	public function joinInvitation(string $invitationCode): DataResponse {
+		try {
+			$this->setCurrentFederatedUser();
+
+			$circleProbe = (new CircleProbe())
+				->includeSystemCircles()
+				->includeHiddenCircles()
+				->filterByInvitationCode($invitationCode);
+
+			$circles = $this->circleService->getCircles($circleProbe);
+			if (empty($circles)) {
+				return new DataResponse([], Http::STATUS_NOT_FOUND);
+			}
+			$circle = reset($circles);
+
+			$result = $this->circleService->circleJoin($circle->getSingleId(), $invitationCode);
+
+			return new DataResponse($this->serializeArray($result));
+		} catch (\Exception $e) {
+			$this->e($e, ['circleId' => $invitationCode]);
+			throw new OCSException($e->getMessage(), (int)$e->getCode(), $e);
+		}
+	}
+
 	/**
 	 * @throws FederatedUserException
 	 * @throws FederatedUserNotFoundException

lib/Db/CircleInvitationRequest.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2021 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Circles\Db;
+
+use OCA\Circles\Exceptions\InvalidIdException;
+use OCA\Circles\Model\CircleInvitation;
+
+/**
+ * Class CircleInvitationRequest
+ *
+ * @package OCA\Circles\Db
+ */
+class CircleInvitationRequest extends CircleRequestBuilder {
+	/**
+	 * @throws InvalidIdException
+	 */
+	public function save(CircleInvitation $circleInvitation): void {
+		$this->confirmValidId($circleInvitation->getCircleId());
+
+		$qb = $this->getQueryBuilder();
+		$qb->insert(self::TABLE_INVITATIONS)
+			->setValue('created', $qb->createNamedParameter($this->timezoneService->getUTCDate()));
+		$qb->setValue('circle_id', $qb->createNamedParameter($circleInvitation->getCircleId()))
+			->setValue('invitation_code', $qb->createNamedParameter($circleInvitation->getInvitationCode()))
+			->setValue('created_by', $qb->createNamedParameter($circleInvitation->getCreatedBy()));
+		$qb->executeStatement();
+	}
+
+	/**
+	 * @throws InvalidIdException
+	 */
+	public function replace(CircleInvitation $circleInvitation): void {
+		$qb = $this->getQueryBuilder();
+		$qb->delete(self::TABLE_INVITATIONS);
+		$qb->limitToCircleId($circleInvitation->getCircleId());
+		$qb->executeStatement();
+
+		$this->save($circleInvitation);
+	}
+
+	public function delete(string $circleId): void {
+		$qb = $this->getQueryBuilder();
+		$qb->delete(self::TABLE_INVITATIONS);
+		$qb->limitToCircleId($circleId);
+		$qb->executeStatement();
+	}
+}

lib/Db/CircleRequest.php

@@ -167,13 +167,17 @@ public function getCircles(?IFederatedUser $initiator, CircleProbe $probe): arra
 			$qb->limitToInitiator(CoreQueryBuilder::CIRCLE, $initiator);
 			$qb->orderBy($qb->generateAlias(CoreQueryBuilder::CIRCLE, CoreQueryBuilder::INITIATOR) . '.level', 'desc');
 			$qb->addOrderBy(CoreQueryBuilder::CIRCLE . '.display_name', 'asc');
+			$qb->leftJoinCircleInvitation(CoreQueryBuilder::CIRCLE);
 		}
 		if ($probe->hasFilterMember()) {
 			$qb->limitToDirectMembership(CoreQueryBuilder::CIRCLE, $probe->getFilterMember());
 		}
 		if ($probe->hasFilterCircle()) {
 			$qb->filterCircleDetails($probe->getFilterCircle());
 		}
+		if ($probe->hasInvitationCode()) {
+			$qb->filterInvitationCode(CoreQueryBuilder::CIRCLE, $probe->getInvitationCode());
+		}
 		if ($probe->hasFilterRemoteInstance()) {
 			$qb->limitToRemoteInstance(CoreQueryBuilder::CIRCLE, $probe->getFilterRemoteInstance(), false);
 		}
@@ -375,6 +379,7 @@ public function getCircle(
 		$qb->limitToUniqueId($id);
 		$qb->filterCircles(CoreQueryBuilder::CIRCLE, $probe);
 		$qb->leftJoinOwner(CoreQueryBuilder::CIRCLE);
+		$qb->leftJoinCircleInvitation(CoreQueryBuilder::CIRCLE);
 		//		$qb->setOptions(
 		//			[CoreRequestBuilder::CIRCLE, CoreRequestBuilder::INITIATOR], [
 		//																		   'mustBeMember' => false,

lib/Db/CircleRequestBuilder.php

@@ -33,7 +33,6 @@ protected function getCircleInsertSql(): CoreQueryBuilder {
 		return $qb;
 	}
 
-
 	/**
 	 * @return CoreQueryBuilder&IQueryBuilder
 	 */
@@ -44,7 +43,6 @@ protected function getCircleUpdateSql(): CoreQueryBuilder {
 		return $qb;
 	}
 
-
 	/**
 	 * @param string $alias
 	 * @param bool $single
@@ -65,7 +63,6 @@ protected function getCircleSelectSql(
 		return $qb;
 	}
 
-
 	/**
 	 * Base of the Sql Delete request
 	 *
@@ -78,6 +75,17 @@ protected function getCircleDeleteSql(): CoreQueryBuilder {
 		return $qb;
 	}
 
+	/**
+	 * Base of the Sql Delete request
+	 *
+	 * @return CoreQueryBuilder&IQueryBuilder
+	 */
+	protected function getCircleInvitationDeleteSql(): CoreQueryBuilder {
+		$qb = $this->getQueryBuilder();
+		$qb->delete(self::TABLE_INVITATIONS);
+
+		return $qb;
+	}
 
 	/**
 	 * @param CoreQueryBuilder&IQueryBuilder $qb

lib/Db/CoreQueryBuilder.php

@@ -59,7 +59,7 @@ class CoreQueryBuilder extends ExtendedQueryBuilder {
 	public const TOKEN = 'u';
 	public const OPTIONS = 'v';
 	public const HELPER = 'w';
-
+	public const INVITATION = 'x';
 
 	public static $SQL_PATH = [
 		self::SINGLE => [
@@ -69,6 +69,7 @@ class CoreQueryBuilder extends ExtendedQueryBuilder {
 			self::OPTIONS => [
 			],
 			self::MEMBER,
+			self::INVITATION,
 			self::OWNER => [
 				self::BASED_ON
 			],
@@ -865,6 +866,27 @@ public function leftJoinOwner(string $alias, string $field = 'unique_id'): void
 		$this->leftJoinBasedOn($aliasMember);
 	}
 
+	/**
+	 * @throws RequestBuilderException
+	 */
+	public function leftJoinCircleInvitation(string $alias, string $field = 'unique_id'): void {
+		if ($this->getType() !== QueryBuilder::SELECT) {
+			return;
+		}
+
+		try {
+			$aliasInvitation = $this->generateAlias($alias, self::INVITATION, $options);
+		} catch (RequestBuilderException $e) {
+			return;
+		}
+
+		$expr = $this->expr();
+		$this->generateCircleInvitationSelectAlias($aliasInvitation)
+			->leftJoin(
+				$alias, CoreRequestBuilder::TABLE_INVITATIONS, $aliasInvitation,
+				$expr->eq($aliasInvitation . '.circle_id', $alias . '.' . $field),
+			);
+	}
 
 	/**
 	 * @param CircleProbe $probe
@@ -1332,6 +1354,12 @@ protected function limitInitiatorVisibility(string $alias): ICompositeExpression
 		$aliasMembershipCircle = $this->generateAlias($aliasMembership, self::CONFIG, $options);
 		$levelCheck = [$aliasMembership];
 
+		// no need to check anything, we are filtering by invitation code
+		$invitationCode = $this->get('filterInvitationCode', $options, '');
+		if ($invitationCode) {
+			return $this->expr()->andX($this->expr()->eq('1', '1'));
+		}
+
 		$directMember = '';
 		if ($this->getBool('initiatorDirectMember', $options, false)) {
 			$directMember = $this->generateAlias($alias, self::DIRECT_INITIATOR, $options);
@@ -1547,6 +1575,22 @@ public function limitToShareOwner(
 		}
 	}
 
+	public function filterInvitationCode(string $alias, string $invitationCode): void {
+		if ($this->getType() !== QueryBuilder::SELECT) {
+			return;
+		}
+
+		try {
+			$aliasInvitation = $this->generateAlias($alias, self::INVITATION, $options);
+		} catch (RequestBuilderException $e) {
+			return;
+		}
+
+		$expr = $this->expr();
+		$this->andWhere(
+			$expr->eq($aliasInvitation . '.invitation_code', $this->createNamedParameter($invitationCode))
+		);
+	}
 
 	/**
 	 * @param string $aliasMount
@@ -1635,6 +1679,17 @@ private function generateMemberSelectAlias(string $alias, array $default = []):
 		return $this;
 	}
 
+	private function generateCircleInvitationSelectAlias(string $alias, array $default = []): self {
+		$this->generateSelectAlias(
+			CoreRequestBuilder::$tables[CoreRequestBuilder::TABLE_INVITATIONS],
+			$alias,
+			$alias,
+			$default
+		);
+
+		return $this;
+	}
+
 
 	/**
 	 * @param string $alias

lib/Db/CoreRequestBuilder.php

@@ -32,6 +32,7 @@ class CoreRequestBuilder {
 	public const TABLE_STORAGES = 'storages';
 
 	public const TABLE_CIRCLE = 'circles_circle';
+	public const TABLE_INVITATIONS = 'circles_invitations';
 	public const TABLE_MEMBER = 'circles_member';
 	public const TABLE_MEMBERSHIP = 'circles_membership';
 	public const TABLE_REMOTE = 'circles_remote';
@@ -64,6 +65,12 @@ class CoreRequestBuilder {
 			'contact_groupname',
 			'creation'
 		],
+		self::TABLE_INVITATIONS => [
+			'circle_id',
+			'invitation_code',
+			'created_by',
+			'created',
+		],
 		self::TABLE_MEMBER => [
 			'circle_id',
 			'member_id',

lib/Exceptions/CircleInvitationNotFoundException.php

@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+
+/**
+ * SPDX-FileCopyrightText: 2021 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Circles\Exceptions;
+
+class CircleInvitationNotFoundException extends FederatedItemNotFoundException {
+}