feat: add Team Folder recovery bin

REUSE.toml

@@ -78,7 +78,7 @@ SPDX-FileCopyrightText = "none"
 SPDX-License-Identifier = "MIT"
 
 [[annotations]]
-path = ["openapi.json", "src/types/openapi/openapi.ts"]
+path = ["openapi.json", "openapi-administration.json", "openapi-full.json", "src/types/openapi/openapi.ts"]
 precedence = "aggregate"
 SPDX-FileCopyrightText = "2024 Nextcloud GmbH and Nextcloud contributors"
 SPDX-License-Identifier = "AGPL-3.0-or-later"

appinfo/info.xml

@@ -47,6 +47,7 @@ Folder.
 	<background-jobs>
 		<job>OCA\GroupFolders\BackgroundJob\ExpireGroupVersions</job>
 		<job>OCA\GroupFolders\BackgroundJob\ExpireGroupTrash</job>
+		<job>OCA\GroupFolders\BackgroundJob\ExpireDeletedFolders</job>
 	</background-jobs>
 
 	<repair-steps>

lib/BackgroundJob/ExpireDeletedFolders.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\GroupFolders\BackgroundJob;
+
+use OCA\GroupFolders\Folder\FolderManager;
+use OCP\AppFramework\Utility\ITimeFactory;
+use OCP\BackgroundJob\TimedJob;
+use Psr\Log\LoggerInterface;
+
+/**
+ * Permanently removes Team folders whose recovery period has elapsed.
+ */
+class ExpireDeletedFolders extends TimedJob {
+	public function __construct(
+		private readonly ITimeFactory $timeFactory,
+		private readonly FolderManager $folderManager,
+		private readonly LoggerInterface $logger,
+	) {
+		parent::__construct($timeFactory);
+		$this->setInterval(24 * 60 * 60);
+		$this->setAllowParallelRuns(false);
+	}
+
+	#[\Override]
+	protected function run(mixed $argument): void {
+		$expiredBefore = $this->timeFactory->getTime() - FolderManager::DELETED_FOLDER_RETENTION_SECONDS;
+
+		foreach ($this->folderManager->getDeletedFoldersBefore($expiredBefore) as $deletedFolder) {
+			try {
+				$this->folderManager->purgeDeletedFolder($deletedFolder->folder->id);
+			} catch (\Throwable $exception) {
+				$this->logger->error('Could not permanently remove an expired Team folder from the recovery bin', [
+					'app' => 'groupfolders',
+					'folderId' => $deletedFolder->folder->id,
+					'exception' => $exception,
+				]);
+			}
+		}
+	}
+}

lib/Command/Delete.php

@@ -19,9 +19,10 @@ class Delete extends FolderCommand {
 	protected function configure(): void {
 		$this
 			->setName('groupfolders:delete')
-			->setDescription('Delete Team folder')
-			->addArgument('folder_id', InputArgument::REQUIRED, 'Id of the folder to rename')
-			->addOption('force', 'f', InputOption::VALUE_NONE, 'Skip confirmation');
+			->setDescription('Move Team folder to the recovery bin')
+			->addArgument('folder_id', InputArgument::REQUIRED, 'Id of the folder to delete')
+			->addOption('force', 'f', InputOption::VALUE_NONE, 'Skip confirmation')
+			->addOption('permanent', 'p', InputOption::VALUE_NONE, 'Permanently delete the Team folder and all files');
 		parent::configure();
 	}
 
@@ -38,10 +39,18 @@ protected function execute(InputInterface $input, OutputInterface $output): int
 
 		/** @var QuestionHelper $helper */
 		$helper = $this->getHelper('question');
-		$question = new ConfirmationQuestion('Are you sure you want to delete the Team folder ' . $folder->mountPoint . ' and all files within, this cannot be undone (y/N).', false);
+		$permanent = (bool)$input->getOption('permanent');
+		$question = new ConfirmationQuestion(
+			$permanent
+				? 'Are you sure you want to permanently delete the Team folder ' . $folder->mountPoint . ' and all files within, this cannot be undone (y/N).'
+				: 'Move the Team folder ' . $folder->mountPoint . ' to the recovery bin? It can be restored for 30 days (y/N).',
+			false,
+		);
 		if ($input->getOption('force') || $helper->ask($input, $output, $question)) {
-			$this->folderStorageManager->deleteStoragesForFolder($folder);
-			$this->folderManager->removeFolder($folder->id);
+			$this->folderManager->archiveFolder($folder->id, null);
+			if ($permanent) {
+				$this->folderManager->purgeDeletedFolder($folder->id);
+			}
 		}
 
 		return 0;

lib/Controller/FolderController.php

@@ -10,9 +10,9 @@
 
 use OC\AppFramework\OCS\V1Response;
 use OCA\GroupFolders\Attribute\RequireGroupFolderAdmin;
+use OCA\GroupFolders\Folder\DeletedFolder;
 use OCA\GroupFolders\Folder\FolderManager;
 use OCA\GroupFolders\Folder\FolderWithMappingsAndCache;
-use OCA\GroupFolders\Mount\FolderStorageManager;
 use OCA\GroupFolders\ResponseDefinitions;
 use OCA\GroupFolders\Service\DelegationService;
 use OCA\GroupFolders\Service\FoldersFilter;
@@ -38,6 +38,7 @@
  * @phpstan-import-type GroupFoldersUser from ResponseDefinitions
  * @phpstan-import-type GroupFoldersFolder from ResponseDefinitions
  * @phpstan-import-type GroupFoldersAclManage from ResponseDefinitions
+ * @phpstan-import-type GroupFoldersDeletedFolder from ResponseDefinitions
  * @phpstan-type GroupFoldersFolderXML = array{
  *     id: int,
  *     mount_point: string,
@@ -68,7 +69,6 @@ public function __construct(
 		private readonly FoldersFilter $foldersFilter,
 		private readonly DelegationService $delegationService,
 		private readonly IGroupManager $groupManager,
-		private readonly FolderStorageManager $folderStorageManager,
 	) {
 		parent::__construct($appName, $request);
 		$this->user = $userSession->getUser();
@@ -115,6 +115,20 @@ private function formatFolder(FolderWithMappingsAndCache $folder): array {
 		];
 	}
 
+	/**
+	 * @return GroupFoldersDeletedFolder
+	 */
+	private function formatDeletedFolder(DeletedFolder $deletedFolder): array {
+		return [
+			'id' => $deletedFolder->folder->id,
+			'mount_point' => $deletedFolder->folder->mountPoint,
+			'quota' => $deletedFolder->folder->quota,
+			'size' => $deletedFolder->rootCacheEntry->getSize(),
+			'deleted_at' => $deletedFolder->deletedAt,
+			'deleted_by' => $deletedFolder->deletedBy,
+		];
+	}
+
 	/**
 	 * Gets all Groupfolders
 	 *
@@ -282,13 +296,13 @@ public function addFolder(string $mountpoint, ?string $bucket = null, bool $acl_
 	}
 
 	/**
-	 * Remove a Groupfolder
+	 * Move a Groupfolder to the recovery bin
 	 *
 	 * @param int $id ID of the Groupfolder
 	 * @return DataResponse<Http::STATUS_OK, array{success: true}, array{}>
 	 * @throws OCSNotFoundException Groupfolder not found
 	 *
-	 * 200: Groupfolder removed successfully
+	 * 200: Groupfolder moved to the recovery bin successfully
 	 */
 	#[PasswordConfirmationRequired]
 	#[RequireGroupFolderAdmin]
@@ -301,8 +315,71 @@ public function removeFolder(int $id): DataResponse {
 			throw new OCSForbiddenException('This folder belongs to a team and cannot be deleted directly; unlink it from its team first');
 		}
 
-		$this->folderStorageManager->deleteStoragesForFolder($folder);
-		$this->manager->removeFolder($id);
+		$this->manager->archiveFolder($folder->id, $this->user?->getUID());
+
+		return new DataResponse(['success' => true]);
+	}
+
+	/**
+	 * Get Team folders that are still recoverable
+	 *
+	 * @return DataResponse<Http::STATUS_OK, list<GroupFoldersDeletedFolder>, array{}>
+	 *
+	 * 200: Deleted Team folders returned successfully
+	 */
+	#[FrontpageRoute(verb: 'GET', url: '/folders/deleted')]
+	public function getDeletedFolders(): DataResponse {
+		return new DataResponse(array_map($this->formatDeletedFolder(...), $this->manager->getDeletedFolders()));
+	}
+
+	/**
+	 * Restore a Team folder from the recovery bin
+	 *
+	 * @param int $id ID of the deleted Team folder
+	 * @param ?string $mountpoint Replacement mount point when its original name is in use
+	 * @return DataResponse<Http::STATUS_OK, array{success: true, folder: GroupFoldersFolder}, array{}>
+	 * @throws OCSBadRequestException A replacement mount point is invalid or already in use
+	 * @throws OCSNotFoundException Deleted Team folder not found
+	 *
+	 * 200: Team folder restored successfully
+	 */
+	#[PasswordConfirmationRequired]
+	#[FrontpageRoute(verb: 'POST', url: '/folders/{id}/restore', requirements: ['id' => '\\d+'])]
+	public function restoreDeletedFolder(int $id, ?string $mountpoint = null): DataResponse {
+		if ($mountpoint !== null) {
+			$mountpoint = $this->manager->trimMountpoint($mountpoint);
+		}
+
+		try {
+			$this->manager->restoreDeletedFolder($id, $mountpoint);
+		} catch (\InvalidArgumentException $exception) {
+			if ($exception->getMessage() === 'Deleted Team folder not found') {
+				throw new OCSNotFoundException($exception->getMessage());
+			}
+			throw new OCSBadRequestException($exception->getMessage());
+		}
+
+		return new DataResponse([
+			'success' => true,
+			'folder' => $this->formatFolder($this->checkedGetFolder($id)),
+		]);
+	}
+
+	/**
+	 * Permanently remove a Team folder and all of its stored data
+	 *
+	 * @param int $id ID of the deleted Team folder
+	 * @return DataResponse<Http::STATUS_OK, array{success: true}, array{}>
+	 * @throws OCSNotFoundException Deleted Team folder not found
+	 *
+	 * 200: Team folder permanently removed successfully
+	 */
+	#[PasswordConfirmationRequired]
+	#[FrontpageRoute(verb: 'DELETE', url: '/folders/{id}/permanent', requirements: ['id' => '\\d+'])]
+	public function purgeDeletedFolder(int $id): DataResponse {
+		if (!$this->manager->purgeDeletedFolder($id)) {
+			throw new OCSNotFoundException('Deleted Team folder not found');
+		}
 
 		return new DataResponse(['success' => true]);
 	}

lib/Folder/DeletedFolder.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\GroupFolders\Folder;
+
+use OCP\Files\Cache\ICacheEntry;
+
+/**
+ * A Team folder that has been removed from users' mounts but is still within
+ * its recovery period.
+ */
+class DeletedFolder {
+	public function __construct(
+		public readonly FolderDefinition $folder,
+		public readonly ICacheEntry $rootCacheEntry,
+		public readonly int $deletedAt,
+		public readonly ?string $deletedBy,
+	) {
+	}
+}