diff options
Diffstat (limited to 'lib/public/UserMigration')
| -rw-r--r-- | lib/public/UserMigration/IExportDestination.php | 68 | ||||
| -rw-r--r-- | lib/public/UserMigration/IImportSource.php | 111 | ||||
| -rw-r--r-- | lib/public/UserMigration/IMigrator.php | 80 | ||||
| -rw-r--r-- | lib/public/UserMigration/ISizeEstimationMigrator.php | 26 | ||||
| -rw-r--r-- | lib/public/UserMigration/TMigratorBasicVersionHandling.php | 42 | ||||
| -rw-r--r-- | lib/public/UserMigration/UserMigrationException.php | 16 |
6 files changed, 343 insertions, 0 deletions
diff --git a/lib/public/UserMigration/IExportDestination.php b/lib/public/UserMigration/IExportDestination.php new file mode 100644 index 00000000000..ee53d2eccb3 --- /dev/null +++ b/lib/public/UserMigration/IExportDestination.php @@ -0,0 +1,68 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2022 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +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. + * @throws UserMigrationException + * + * @since 24.0.0 + */ + public function addFileContents(string $path, string $content): void; + + /** + * 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. + * @throws UserMigrationException + * + * @since 24.0.0 + */ + public function addFileAsStream(string $path, $stream): void; + + /** + * 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. + * @param ?callable(\OCP\Files\Node):bool $nodeFilter Callback to filter nodes to copy + * @throws UserMigrationException + * + * @since 24.0.0 + */ + public function copyFolder(Folder $folder, string $destinationPath, ?callable $nodeFilter = null): void; + + /** + * @param array<string,int> $versions Migrators and their versions. + * @throws UserMigrationException + * + * @since 24.0.0 + */ + public function setMigratorVersions(array $versions): void; + + /** + * Called after export is complete + * + * @throws UserMigrationException + * + * @since 24.0.0 + */ + public function close(): void; +} diff --git a/lib/public/UserMigration/IImportSource.php b/lib/public/UserMigration/IImportSource.php new file mode 100644 index 00000000000..3818895932e --- /dev/null +++ b/lib/public/UserMigration/IImportSource.php @@ -0,0 +1,111 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2022 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +namespace OCP\UserMigration; + +use OCP\Files\Folder; + +/** + * @since 24.0.0 + */ +interface IImportSource { + /** + * @since 24.0.0 + */ + public const PATH_USER = 'user.json'; + + /** + * 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. + * @throws UserMigrationException + * + * @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. + * @throws UserMigrationException + * + * @since 24.0.0 + */ + public function getFileAsStream(string $path); + + /** + * List the files of a folder + * + * @param string $path Full path to the folder in the export archive. + * @return array The list of files. + * @throws UserMigrationException + * + * @since 24.0.0 + */ + public function getFolderListing(string $path): array; + + /** + * Test if a path exists, which may be a file or a folder + * + * @throws UserMigrationException + * + * @since 24.0.0 + */ + public function pathExists(string $path): bool; + + /** + * Copy files from the export to a Folder + * + * Folder $destination folder to copy into + * string $sourcePath path in the export archive + * + * @throws UserMigrationException + * + * @since 24.0.0 + */ + public function copyToFolder(Folder $destination, string $sourcePath): void; + + /** + * @return array<string,int> Migrators and their versions from the export archive. + * @throws UserMigrationException + * + * @since 24.0.0 + */ + public function getMigratorVersions(): array; + + /** + * @return ?int Version for this migrator from the export archive. Null means migrator missing. + * @throws UserMigrationException + * @param string $migrator Migrator id (as returned by IMigrator::getId) + * + * @since 24.0.0 + */ + public function getMigratorVersion(string $migrator): ?int; + + /** + * Get original uid of the imported account + * + * @throws UserMigrationException + * + * @since 24.0.0 + */ + public function getOriginalUid(): string; + + /** + * Called after import is complete + * + * @throws UserMigrationException + * + * @since 24.0.0 + */ + public function close(): void; +} diff --git a/lib/public/UserMigration/IMigrator.php b/lib/public/UserMigration/IMigrator.php new file mode 100644 index 00000000000..8ce2cca8f98 --- /dev/null +++ b/lib/public/UserMigration/IMigrator.php @@ -0,0 +1,80 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2022 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +namespace OCP\UserMigration; + +use OCP\IUser; +use Symfony\Component\Console\Output\OutputInterface; + +/** + * @since 24.0.0 + */ +interface IMigrator { + /** + * Export user data + * + * @throws UserMigrationException + * @since 24.0.0 + */ + public function export( + IUser $user, + IExportDestination $exportDestination, + OutputInterface $output, + ): void; + + /** + * Import user data + * + * @throws UserMigrationException + * @since 24.0.0 + */ + public function import( + IUser $user, + IImportSource $importSource, + OutputInterface $output, + ): void; + + /** + * Returns the unique ID + * + * @since 24.0.0 + */ + public function getId(): string; + + /** + * Returns the display name + * + * @since 24.0.0 + */ + public function getDisplayName(): string; + + /** + * Returns the description + * + * @since 24.0.0 + */ + public function getDescription(): string; + + /** + * 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($this->getId()) to get the version from the archive + * + * @since 24.0.0 + */ + public function canImport( + IImportSource $importSource, + ): bool; +} diff --git a/lib/public/UserMigration/ISizeEstimationMigrator.php b/lib/public/UserMigration/ISizeEstimationMigrator.php new file mode 100644 index 00000000000..2d1f3466f2c --- /dev/null +++ b/lib/public/UserMigration/ISizeEstimationMigrator.php @@ -0,0 +1,26 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2022 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +namespace OCP\UserMigration; + +use OCP\IUser; + +/** + * @since 25.0.0 + */ +interface ISizeEstimationMigrator { + /** + * Returns an estimate of the exported data size in KiB. + * Should be fast, favor performance over accuracy. + * + * @since 25.0.0 + * @since 27.0.0 return value may overflow from int to float + */ + public function getEstimatedExportSize(IUser $user): int|float; +} diff --git a/lib/public/UserMigration/TMigratorBasicVersionHandling.php b/lib/public/UserMigration/TMigratorBasicVersionHandling.php new file mode 100644 index 00000000000..b33425a023d --- /dev/null +++ b/lib/public/UserMigration/TMigratorBasicVersionHandling.php @@ -0,0 +1,42 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2022 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +namespace OCP\UserMigration; + +/** + * Basic version handling: we can import older versions but not newer ones + * @since 24.0.0 + */ +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($this->getId()); + if ($version === null) { + return !$this->mandatory; + } + return ($this->version >= $version); + } +} diff --git a/lib/public/UserMigration/UserMigrationException.php b/lib/public/UserMigration/UserMigrationException.php new file mode 100644 index 00000000000..f1b1d83466e --- /dev/null +++ b/lib/public/UserMigration/UserMigrationException.php @@ -0,0 +1,16 @@ +<?php + +declare(strict_types=1); + +/** + * SPDX-FileCopyrightText: 2022 Nextcloud GmbH and Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +namespace OCP\UserMigration; + +/** + * @since 24.0.0 + */ +class UserMigrationException extends \Exception { +} |