Merge pull request #31676 from nextcloud/enh/ocp-owner-lock

Add public API for owner based file locking

6 files changed, 477 insertions, 0 deletions

diff --git a/lib/public/Files/Lock/ILock.php b/lib/public/Files/Lock/ILock.php
new file mode 100644
index 00000000000..03737a178c6
--- /dev/null
+++ b/lib/public/Files/Lock/ILock.php
@@ -0,0 +1,163 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * @copyright Copyright (c) 2022 Julius Härtl <jus@bitgrid.net>
+ *
+ * @author Julius Härtl <jus@bitgrid.net>
+ *
+ * @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\Files\Lock;
+
+/**
+ * @since 24.0.0
+ */
+interface ILock {
+
+	/**
+	 * User owned manual lock
+	 *
+	 * This lock type is initiated by a user manually through the web UI or clients
+	 * and will limit editing capabilities on the file to the lock owning user.
+	 *
+	 * @since 24.0.0
+	 */
+	public const TYPE_USER = 0;
+
+	/**
+	 * App owned lock
+	 *
+	 * This lock type is created by collaborative apps like Text or Office to avoid
+	 * outside changes through WevDAV or other apps.
+	 * @since 24.0.0
+	 *
+	 */
+	public const TYPE_APP = 1;
+
+	/**
+	 * Token owned lock
+	 *
+	 * This lock type will bind the ownership to the provided lock token. Any request
+	 * that aims to modify the file will be required to sent the token, the user
+	 * itself is not able to write to files without the token. This will allow
+	 * to limit the locking to an individual client.
+	 *
+	 * @since 24.0.0
+	 */
+	public const TYPE_TOKEN = 2;
+
+	/**
+	 * WebDAV Lock scope exclusive
+	 *
+	 * @since 24.0.0
+	 */
+	public const LOCK_EXCLUSIVE = 1;
+
+	/**
+	 * WebDAV Lock scope shared
+	 *
+	 * @since 24.0.0
+	 */
+	public const LOCK_SHARED = 2;
+
+	/**
+	 * Lock only the resource the lock is applied to
+	 *
+	 * @since 24.0.0
+	 */
+	public const LOCK_DEPTH_ZERO = 0;
+
+	/**
+	 * Lock app resources under the locked one with infinite depth
+	 *
+	 * @since 24.0.0
+	 */
+	public const LOCK_DEPTH_INFINITE = -1;
+
+	/**
+	 * Type of the lock
+	 *
+	 * @psalm-return ILock::TYPE_*
+	 * @since 24.0.0
+	 */
+	public function getType(): int;
+
+	/**
+	 * Owner that holds the lock
+	 *
+	 * Depending on the lock type this is:
+	 * - ILock::TYPE_USER: A user id
+	 * - ILock::TYPE_APP: An app id
+	 * - ILock::TYPE_TOKEN: A user id
+	 *
+	 * @since 24.0.0
+	 */
+	public function getOwner(): string;
+
+	/**
+	 * File id that the lock is holding
+	 *
+	 * @since 24.0.0
+	 */
+	public function getFileId(): int;
+
+	/**
+	 * Timeout of the lock in seconds starting from the created at time
+	 *
+	 * @since 24.0.0
+	 */
+	public function getTimeout(): int;
+
+	/**
+	 * Unix timestamp of the lock creation time
+	 *
+	 * @since 24.0.0
+	 */
+	public function getCreatedAt(): int;
+
+	/**
+	 * Token string as a unique identifier for the lock, usually a UUID
+	 *
+	 * @since 24.0.0
+	 */
+	public function getToken(): string;
+
+	/**
+	 * Lock depth to apply the lock to child resources
+	 *
+	 * @since 24.0.0
+	 */
+	public function getDepth(): int;
+
+	/**
+	 * WebDAV lock scope
+	 *
+	 * @since 24.0.0
+	 * @psalm-return ILock::LOCK_EXCLUSIVE|ILock::LOCK_SHARED
+	 */
+	public function getScope(): int;
+
+	/**
+	 * String representation of the lock to identify it through logging
+	 *
+	 * @since 24.0.0
+	 */
+	public function __toString(): string;
+}
diff --git a/lib/public/Files/Lock/ILockManager.php b/lib/public/Files/Lock/ILockManager.php
new file mode 100644
index 00000000000..cad66380e93
--- /dev/null
+++ b/lib/public/Files/Lock/ILockManager.php
@@ -0,0 +1,69 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * @copyright Copyright (c) 2022 Julius Härtl <jus@bitgrid.net>
+ *
+ * @author Julius Härtl <jus@bitgrid.net>
+ *
+ * @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\Files\Lock;
+
+use OCP\PreConditionNotMetException;
+
+/**
+ * Manage app integrations with files_lock with collaborative editors
+ *
+ * The OCP parts are mainly for exposing the ability to lock/unlock for apps and
+ * to give the files_lock app a way to register and then be triggered by the apps
+ * while the actual locking implementation is kept in the LockProvider and DAV
+ * plugin from files_lock app.
+ *
+ * @since 24.0.0
+ */
+interface ILockManager extends ILockProvider {
+
+	/**
+	 * @throws PreConditionNotMetException if there is already a lock provider registered
+	 * @since 24.0.0
+	 */
+	public function registerLockProvider(ILockProvider $lockProvider): void;
+
+	/**
+	 * @return bool
+	 * @since 24.0.0
+	 */
+	public function isLockProviderAvailable(): bool;
+
+	/**
+	 * Run within the scope of a given lock condition
+	 *
+	 * The callback will also be executed if no lock provider is present
+	 *
+	 * @since 24.0.0
+	 */
+	public function runInScope(LockContext $lock, callable $callback): void;
+
+	/**
+	 * @throws NoLockProviderException if there is no lock provider available
+	 * @since 24.0.0
+	 */
+	public function getLockInScope(): ?LockContext;
+}
diff --git a/lib/public/Files/Lock/ILockProvider.php b/lib/public/Files/Lock/ILockProvider.php
new file mode 100644
index 00000000000..50326c427e4
--- /dev/null
+++ b/lib/public/Files/Lock/ILockProvider.php
@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * @copyright Copyright (c) 2022 Julius Härtl <jus@bitgrid.net>
+ *
+ * @author Julius Härtl <jus@bitgrid.net>
+ *
+ * @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\Files\Lock;
+
+use OCP\PreConditionNotMetException;
+
+/**
+ * @since 24.0.0
+ */
+interface ILockProvider {
+
+	/**
+	 * @throws PreConditionNotMetException
+	 * @throws NoLockProviderException
+	 * @psalm-return list<ILock>
+	 * @since 24.0.0
+	 */
+	public function getLocks(int $fileId): array;
+
+	/**
+	 * @throws PreConditionNotMetException
+	 * @throws OwnerLockedException
+	 * @throws NoLockProviderException
+	 * @since 24.0.0
+	 */
+	public function lock(LockContext $lockInfo): ILock;
+
+	/**
+	 * @throws PreConditionNotMetException
+	 * @throws NoLockProviderException
+	 * @since 24.0.0
+	 */
+	public function unlock(LockContext $lockInfo): void;
+}
diff --git a/lib/public/Files/Lock/LockContext.php b/lib/public/Files/Lock/LockContext.php
new file mode 100644
index 00000000000..1466cb41ae1
--- /dev/null
+++ b/lib/public/Files/Lock/LockContext.php
@@ -0,0 +1,99 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * @copyright Copyright (c) 2022 Julius Härtl <jus@bitgrid.net>
+ *
+ * @author Julius Härtl <jus@bitgrid.net>
+ *
+ * @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\Files\Lock;
+
+use OCP\Files\Node;
+
+/**
+ * Structure to identify a specific lock context to request or
+ * describe a lock with the affected node and ownership information
+ *
+ * This is used to match a lock/unlock request or file operation to existing locks
+ *
+ * @since 24.0.0
+ */
+final class LockContext {
+	private Node $node;
+	private int $type;
+	private string $owner;
+
+	/**
+	 * @param Node $node Node that is owned by the lock
+	 * @param int $type Type of the lock owner
+	 * @param string $owner Unique identifier for the lock owner based on the type
+	 * @since 24.0.0
+	 */
+	public function __construct(
+		Node $node,
+		int $type,
+		string $owner
+	) {
+		$this->node = $node;
+		$this->type = $type;
+		$this->owner = $owner;
+	}
+
+	/**
+	 * @since 24.0.0
+	 */
+	public function getNode(): Node {
+		return $this->node;
+	}
+
+	/**
+	 * @return int
+	 * @since 24.0.0
+	 */
+	public function getType(): int {
+		return $this->type;
+	}
+
+	/**
+	 * @return string user id / app id / lock token depending on the type
+	 * @since 24.0.0
+	 */
+	public function getOwner(): string {
+		return $this->owner;
+	}
+
+	/**
+	 * @since 24.0.0
+	 */
+	public function __toString(): string {
+		$typeString = 'unknown';
+		if ($this->type === ILock::TYPE_USER) {
+			$typeString = 'ILock::TYPE_USER';
+		}
+		if ($this->type === ILock::TYPE_APP) {
+			$typeString = 'ILock::TYPE_APP';
+		}
+		if ($this->type === ILock::TYPE_TOKEN) {
+			$typeString = 'ILock::TYPE_TOKEN';
+		}
+		return "$typeString  $this->owner " . $this->getNode()->getId();
+	}
+}
diff --git a/lib/public/Files/Lock/NoLockProviderException.php b/lib/public/Files/Lock/NoLockProviderException.php
new file mode 100644
index 00000000000..ab727348e87
--- /dev/null
+++ b/lib/public/Files/Lock/NoLockProviderException.php
@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * @copyright Copyright (c) 2022 Julius Härtl <jus@bitgrid.net>
+ *
+ * @author Julius Härtl <jus@bitgrid.net>
+ *
+ * @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\Files\Lock;
+
+use Exception;
+
+/**
+ * @since 24.0.0
+ */
+class NoLockProviderException extends Exception {
+}
diff --git a/lib/public/Files/Lock/OwnerLockedException.php b/lib/public/Files/Lock/OwnerLockedException.php
new file mode 100644
index 00000000000..fc4530cb29e
--- /dev/null
+++ b/lib/public/Files/Lock/OwnerLockedException.php
@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * @copyright Copyright (c) 2022 Julius Härtl <jus@bitgrid.net>
+ *
+ * @author Julius Härtl <jus@bitgrid.net>
+ *
+ * @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\Files\Lock;
+
+use OCP\Lock\LockedException;
+
+/**
+ * @since 24.0.0
+ */
+class OwnerLockedException extends LockedException {
+	private ILock $lock;
+
+	/**
+	 * @since 24.0.0
+	 */
+	public function __construct(ILock $lock) {
+		$this->lock = $lock;
+		$path = '';
+		$readablePath = '';
+		parent::__construct($path, null, $lock->getOwner(), $readablePath);
+	}
+
+	/**
+	 * @since 24.0.0
+	 */
+	public function getLock(): ILock {
+		return $this->lock;
+	}
+}