Merge pull request #31173 from nextcloud/enhancement/user_migration-version-handling

Add version handling to IMigrator

Author: come-nc

lib/composer/composer/autoload_classmap.php

@@ -547,6 +547,7 @@
     '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\\UserMigration\\TMigratorBasicVersionHandling' => $baseDir . '/lib/public/UserMigration/TMigratorBasicVersionHandling.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

@@ -576,6 +576,7 @@ class ComposerStaticInit53792487c5a8370acc0b06b1a864ff4c
         '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\\UserMigration\\TMigratorBasicVersionHandling' => __DIR__ . '/../../..' . '/lib/public/UserMigration/TMigratorBasicVersionHandling.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/public/UserMigration/IExportDestination.php

@@ -66,6 +66,13 @@ public function addFileAsStream(string $path, $stream): bool;
 	 */
 	public function copyFolder(Folder $folder, string $destinationPath): bool;
 
+	/**
+	 * @param array<string,int> $versions Migrators and their versions.
+	 *
+	 * @since 24.0.0
+	 */
+	public function setMigratorVersions(array $versions): bool;
+
 	/**
 	 * Called after export is complete
 	 *

lib/public/UserMigration/IImportSource.php

@@ -63,6 +63,22 @@ public function getFileAsStream(string $path);
 	 */
 	public function copyToFolder(Folder $destination, string $sourcePath): bool;
 
+	/**
+	 * @return array<string,int> Migrators and their versions from the export archive.
+	 *
+	 * @since 24.0.0
+	 */
+	public function getMigratorVersions(): array;
+
+	/**
+	 * @return ?int Version for this migrator from the export archive. Null means migrator missing.
+	 *
+	 * @param class-string<IMigrator> $migrator
+	 *
+	 * @since 24.0.0
+	 */
+	public function getMigratorVersion(string $migrator): ?int;
+
 	/**
 	 * Called after import is complete
 	 *

lib/public/UserMigration/IMigrator.php

@@ -6,6 +6,7 @@
  * @copyright 2022 Christopher Ng <[email protected]>
  *
  * @author Christopher Ng <[email protected]>
+ * @author Côme Chilliet <[email protected]>
  *
  * @license GNU AGPL version 3 or any later version
  *
@@ -55,4 +56,21 @@ public function import(
 		IImportSource $importSource,
 		OutputInterface $output
 	): void;
+
+	/**
+	 * Returns the version of the export format for this migrator
+	 *
+	 * @since 24.0.0
+	 */
+	public function getVersion(): int;
+
+	/**
+	 * Checks whether it is able to import a version of the export format for this migrator
+	 * Use $importSource->getMigratorVersion(static::class) to get the version from the archive
+	 *
+	 * @since 24.0.0
+	 */
+	public function canImport(
+		IImportSource $importSource
+	): bool;
 }

lib/public/UserMigration/TMigratorBasicVersionHandling.php

@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * @copyright Copyright (c) 2022 Côme Chilliet <[email protected]>
+ *
+ * @author Côme Chilliet <[email protected]>
+ *
+ * @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;
+
+/**
+ * Basic version handling: we can import older versions but not newer ones
+ */
+trait TMigratorBasicVersionHandling {
+	protected int $version = 1;
+
+	protected bool $mandatory = false;
+
+	/**
+	 * {@inheritDoc}
+	 * @since 24.0.0
+	 */
+	public function getVersion(): int {
+		return $this->version;
+	}
+
+	/**
+	 * {@inheritDoc}
+	 * @since 24.0.0
+	 */
+	public function canImport(
+		IImportSource $importSource
+	): bool {
+		$version = $importSource->getMigratorVersion(static::class);
+		if ($version === null) {
+			return !$this->mandatory;
+		}
+		return ($this->version >= $version);
+	}
+}