Merge pull request #30901 from nextcloud/feat/30398/migration-registration

Migration registraton

lib/composer/composer/autoload_classmap.php

@@ -543,6 +543,9 @@ return array(
     'OCP\\Talk\\ITalkBackend' => $baseDir . '/lib/public/Talk/ITalkBackend.php',
     'OCP\\Template' => $baseDir . '/lib/public/Template.php',
     'OCP\\UserInterface' => $baseDir . '/lib/public/UserInterface.php',
+    'OCP\\UserMigration\\IExportDestination' => $baseDir . '/lib/public/UserMigration/IExportDestination.php',
+    'OCP\\UserMigration\\IImportSource' => $baseDir . '/lib/public/UserMigration/IImportSource.php',
+    'OCP\\UserMigration\\IMigrator' => $baseDir . '/lib/public/UserMigration/IMigrator.php',
     'OCP\\UserStatus\\IManager' => $baseDir . '/lib/public/UserStatus/IManager.php',
     'OCP\\UserStatus\\IProvider' => $baseDir . '/lib/public/UserStatus/IProvider.php',
     'OCP\\UserStatus\\IUserStatus' => $baseDir . '/lib/public/UserStatus/IUserStatus.php',

lib/composer/composer/autoload_static.php

@@ -572,6 +572,9 @@ class ComposerStaticInit53792487c5a8370acc0b06b1a864ff4c
         'OCP\\Talk\\ITalkBackend' => __DIR__ . '/../../..' . '/lib/public/Talk/ITalkBackend.php',
         'OCP\\Template' => __DIR__ . '/../../..' . '/lib/public/Template.php',
         'OCP\\UserInterface' => __DIR__ . '/../../..' . '/lib/public/UserInterface.php',
+        'OCP\\UserMigration\\IExportDestination' => __DIR__ . '/../../..' . '/lib/public/UserMigration/IExportDestination.php',
+        'OCP\\UserMigration\\IImportSource' => __DIR__ . '/../../..' . '/lib/public/UserMigration/IImportSource.php',
+        'OCP\\UserMigration\\IMigrator' => __DIR__ . '/../../..' . '/lib/public/UserMigration/IMigrator.php',
         'OCP\\UserStatus\\IManager' => __DIR__ . '/../../..' . '/lib/public/UserStatus/IManager.php',
         'OCP\\UserStatus\\IProvider' => __DIR__ . '/../../..' . '/lib/public/UserStatus/IProvider.php',
         'OCP\\UserStatus\\IUserStatus' => __DIR__ . '/../../..' . '/lib/public/UserStatus/IUserStatus.php',

lib/private/AppFramework/Bootstrap/RegistrationContext.php

@@ -52,6 +52,7 @@ use OCP\Notification\INotifier;
 use OCP\Profile\ILinkAction;
 use OCP\Search\IProvider;
 use OCP\Support\CrashReport\IReporter;
+use OCP\UserMigration\IMigrator as IUserMigrator;
 use Psr\Log\LoggerInterface;
 use Throwable;
 
@@ -78,6 +79,9 @@ class RegistrationContext {
 	/** @var ServiceRegistration<IRoomBackend>[] */
 	private $calendarRoomBackendRegistrations = [];
 
+	/** @var ServiceRegistration<IUserMigrator>[] */
+	private $userMigrators = [];
+
 	/** @var ServiceFactoryRegistration[] */
 	private $services = [];
 
@@ -293,6 +297,13 @@ class RegistrationContext {
 					$class
 				);
 			}
+
+			public function registerUserMigrator(string $migratorClass): void {
+				$this->context->registerUserMigrator(
+					$this->appId,
+					$migratorClass
+				);
+			}
 		};
 	}
 
@@ -412,6 +423,13 @@ class RegistrationContext {
 		);
 	}
 
+	/**
+	 * @psalm-param class-string<IUserMigrator> $migratorClass
+	 */
+	public function registerUserMigrator(string $appId, string $migratorClass): void {
+		$this->userMigrators[] = new ServiceRegistration($appId, $migratorClass);
+	}
+
 	/**
 	 * @param App[] $apps
 	 */
@@ -687,4 +705,11 @@ class RegistrationContext {
 	public function getCalendarRoomBackendRegistrations(): array {
 		return $this->calendarRoomBackendRegistrations;
 	}
+
+	/**
+	 * @return ServiceRegistration<IUserMigrator>[]
+	 */
+	public function getUserMigrators(): array {
+		return $this->userMigrators;
+	}
 }

lib/public/AppFramework/Bootstrap/IRegistrationContext.php

@@ -295,4 +295,15 @@ interface IRegistrationContext {
 	 * @since 24.0.0
 	 */
 	public function registerCalendarRoomBackend(string $class): void;
+
+	/**
+	 * Register an implementation of \OCP\UserMigration\IMigrator that
+	 * will handle the implementation of a migrator
+	 *
+	 * @param string $migratorClass
+	 * @psalm-param class-string<\OCP\UserMigration\IMigrator> $migratorClass
+	 * @return void
+	 * @since 24.0.0
+	 */
+	public function registerUserMigrator(string $migratorClass): void;
 }

lib/public/UserMigration/IExportDestination.php

@@ -0,0 +1,75 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * @copyright Copyright (c) 2022 Côme Chilliet <come.chilliet@nextcloud.com>
+ *
+ * @author Côme Chilliet <come.chilliet@nextcloud.com>
+ *
+ * @license GNU AGPL version 3 or any later version
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+namespace OCP\UserMigration;
+
+use OCP\Files\Folder;
+
+/**
+ * @since 24.0.0
+ */
+interface IExportDestination {
+
+	/**
+	 * Adds a file to the export
+	 *
+	 * @param string $path Full path to the file in the export archive. Parent directories will be created if needed.
+	 * @param string $content The full content of the file.
+	 * @return bool whether the file contents were successfully added.
+	 *
+	 * @since 24.0.0
+	 */
+	public function addFileContents(string $path, string $content): bool;
+
+	/**
+	 * Adds a file to the export as a stream
+	 *
+	 * @param string $path Full path to the file in the export archive. Parent directories will be created if needed.
+	 * @param resource $stream A stream resource to read from to get the file content.
+	 * @return bool whether the file stream was successfully added.
+	 *
+	 * @since 24.0.0
+	 */
+	public function addFileAsStream(string $path, $stream): bool;
+
+	/**
+	 * Copy a folder to the export
+	 *
+	 * @param Folder $folder folder to copy to the export archive.
+	 * @param string $destinationPath Full path to the folder in the export archive. Parent directories will be created if needed.
+	 * @return bool whether the folder was successfully added.
+	 *
+	 * @since 24.0.0
+	 */
+	public function copyFolder(Folder $folder, string $destinationPath): bool;
+
+	/**
+	 * Called after export is complete
+	 *
+	 * @since 24.0.0
+	 */
+	public function close(): void;
+}

lib/public/UserMigration/IImportSource.php

@@ -0,0 +1,72 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * @copyright Copyright (c) 2022 Côme Chilliet <come.chilliet@nextcloud.com>
+ *
+ * @author Côme Chilliet <come.chilliet@nextcloud.com>
+ *
+ * @license GNU AGPL version 3 or any later version
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+namespace OCP\UserMigration;
+
+use OCP\Files\Folder;
+
+/**
+ * @since 24.0.0
+ */
+interface IImportSource {
+
+	/**
+	 * Reads a file from the export
+	 *
+	 * @param string $path Full path to the file in the export archive.
+	 * @return string The full content of the file.
+	 *
+	 * @since 24.0.0
+	 */
+	public function getFileContents(string $path): string;
+
+	/**
+	 * Reads a file from the export as a stream
+	 *
+	 * @param string $path Full path to the file in the export archive.
+	 * @return resource A stream resource to read from to get the file content.
+	 *
+	 * @since 24.0.0
+	 */
+	public function getFileAsStream(string $path);
+
+	/**
+	 * Copy files from the export to a Folder
+	 *
+	 * Folder $destination folder to copy into
+	 * string $sourcePath path in the export archive
+	 *
+	 * @since 24.0.0
+	 */
+	public function copyToFolder(Folder $destination, string $sourcePath): bool;
+
+	/**
+	 * Called after import is complete
+	 *
+	 * @since 24.0.0
+	 */
+	public function close(): void;
+}

lib/public/UserMigration/IMigrator.php

@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * @copyright 2022 Christopher Ng <chrng8@gmail.com>
+ *
+ * @author Christopher Ng <chrng8@gmail.com>
+ *
+ * @license GNU AGPL version 3 or any later version
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+namespace OCP\UserMigration;
+
+use OCP\IUser;
+use Symfony\Component\Console\Output\OutputInterface;
+
+/**
+ * @since 24.0.0
+ */
+interface IMigrator {
+
+	/**
+	 * Export user data
+	 *
+	 * @since 24.0.0
+	 */
+	public function export(
+		IUser $user,
+		IExportDestination $exportDestination,
+		OutputInterface $output
+	): void;
+
+	/**
+	 * Import user data
+	 *
+	 * @since 24.0.0
+	 */
+	public function import(
+		IUser $user,
+		IImportSource $importSource,
+		OutputInterface $output
+	): void;
+}

tests/lib/AppFramework/Bootstrap/RegistrationContextTest.php

@@ -26,6 +26,7 @@ declare(strict_types=1);
 namespace lib\AppFramework\Bootstrap;
 
 use OC\AppFramework\Bootstrap\RegistrationContext;
+use OC\AppFramework\Bootstrap\ServiceRegistration;
 use OCP\AppFramework\App;
 use OCP\AppFramework\IAppContainer;
 use OCP\EventDispatcher\IEventDispatcher;
@@ -163,6 +164,32 @@ class RegistrationContextTest extends TestCase {
 		]);
 	}
 
+	public function testRegisterUserMigrator(): void {
+		$appIdA = 'myapp';
+		$migratorClassA = 'OCA\App\UserMigration\AppMigrator';
+
+		$appIdB = 'otherapp';
+		$migratorClassB = 'OCA\OtherApp\UserMigration\OtherAppMigrator';
+
+		$serviceRegistrationA = new ServiceRegistration($appIdA, $migratorClassA);
+		$serviceRegistrationB = new ServiceRegistration($appIdB, $migratorClassB);
+
+		$this->context
+			->for($appIdA)
+			->registerUserMigrator($migratorClassA);
+		$this->context
+			->for($appIdB)
+			->registerUserMigrator($migratorClassB);
+
+		$this->assertEquals(
+			[
+				$serviceRegistrationA,
+				$serviceRegistrationB,
+			],
+			$this->context->getUserMigrators(),
+		);
+	}
+
 	public function dataProvider_TrueFalse() {
 		return[
 			[true],