Direct editing API to allow file editing using a one-time token for

mobile apps

Signed-off-by: Julius Härtl <jus@bitgrid.net>

7 files changed, 502 insertions, 0 deletions

diff --git a/lib/public/DirectEditing/ACreateEmpty.php b/lib/public/DirectEditing/ACreateEmpty.php
new file mode 100644
index 00000000000..79684e33b80
--- /dev/null
+++ b/lib/public/DirectEditing/ACreateEmpty.php
@@ -0,0 +1,71 @@
+<?php
+/**
+ * @copyright Copyright (c) 2019 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\DirectEditing;
+
+
+use OCP\Files\File;
+
+/**
+ * @since 18.0.0
+ */
+abstract class ACreateEmpty {
+
+	/**
+	 * Unique id for the creator to filter templates
+	 *
+	 * e.g. document/spreadsheet/presentation
+	 *
+	 * @since 18.0.0
+	 * @return string
+	 */
+	abstract public function getId(): string;
+
+	/**
+	 * Descriptive name for the create action
+	 *
+	 * e.g Create a new document
+	 *
+	 * @since 18.0.0
+	 * @return string
+	 */
+	abstract public function getName(): string;
+
+	/**
+	 * Default file extension for the new file
+	 *
+	 * @since 18.0.0
+	 * @return string
+	 */
+	abstract public function getExtension(): string;
+
+	/**
+	 * Add content when creating empty files
+	 *
+	 * @since 18.0.0
+	 * @param File $file
+	 */
+	public function create(File $file, string $creatorId = null, string $templateId = null): void {
+
+	}
+}
diff --git a/lib/public/DirectEditing/ACreateFromTemplate.php b/lib/public/DirectEditing/ACreateFromTemplate.php
new file mode 100644
index 00000000000..a731e8be595
--- /dev/null
+++ b/lib/public/DirectEditing/ACreateFromTemplate.php
@@ -0,0 +1,39 @@
+<?php
+/**
+ * @copyright Copyright (c) 2019 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\DirectEditing;
+
+/**
+ * @since 18.0.0
+ */
+abstract class ACreateFromTemplate extends ACreateEmpty {
+
+	/**
+	 * List of available templates for the create from template action
+	 *
+	 * @since 18.0.0
+	 * @return array
+	 */
+	abstract public function getTemplates(): array;
+
+}
diff --git a/lib/public/DirectEditing/ATemplate.php b/lib/public/DirectEditing/ATemplate.php
new file mode 100644
index 00000000000..734317eebef
--- /dev/null
+++ b/lib/public/DirectEditing/ATemplate.php
@@ -0,0 +1,71 @@
+<?php
+/**
+ * @copyright Copyright (c) 2019 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\DirectEditing;
+
+use JsonSerializable;
+
+/**
+ * Class ATemplate
+ *
+ * @package OCP\DirectEditing
+ * @since 18.0.0
+ */
+abstract class ATemplate implements JsonSerializable {
+
+	/**
+	 * Return a unique id so the app can identify the template
+	 *
+	 * @since 18.0.0
+	 * @return string
+	 */
+	abstract public function getId(): string;
+
+	/**
+	 * Return a title that is displayed to the user
+	 *
+	 * @since 18.0.0
+	 * @return string
+	 */
+	abstract public function getTitle(): string;
+
+	/**
+	 * Return a link to the template preview image
+	 *
+	 * @since 18.0.0
+	 * @return string
+	 */
+	abstract public function getPreview(): string;
+
+	/**
+	 * @since 18.0.0
+	 * @return array|mixed
+	 */
+	public function jsonSerialize() {
+		return [
+			'id' => $this->getId(),
+			'title' => $this->getTitle(),
+			'preview' => $this->getPreview(),
+		];
+	}
+}
diff --git a/lib/public/DirectEditing/IEditor.php b/lib/public/DirectEditing/IEditor.php
new file mode 100644
index 00000000000..a4fc87f7e15
--- /dev/null
+++ b/lib/public/DirectEditing/IEditor.php
@@ -0,0 +1,99 @@
+<?php
+declare(strict_types=1);
+/**
+ * @copyright Copyright (c) 2019 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\DirectEditing;
+
+
+use OCP\AppFramework\Http\Response;
+
+/**
+ * @since 18.0.0
+ */
+interface IEditor {
+
+	/**
+	 * Return a unique identifier for the editor
+	 *
+	 * e.g. richdocuments
+	 *
+	 * @since 18.0.0
+	 * @return string
+	 */
+	public function getId(): string;
+
+	/**
+	 * Return a readable name for the editor
+	 *
+	 * e.g. Collabora Online
+	 *
+	 * @since 18.0.0
+	 * @return string
+	 */
+	public function getName(): string;
+
+	/**
+	 * A list of mimetypes that should open the editor by default
+	 *
+	 * @since 18.0.0
+	 * @return array
+	 */
+	public function getMimetypes(): array;
+
+	/**
+	 * A list of mimetypes that can be opened in the editor optionally
+	 *
+	 * @since 18.0.0
+	 * @return array
+	 */
+	public function getMimetypesOptional(): array;
+
+	/**
+	 * Return a list of file creation options to be presented to the user
+	 *
+	 * @since 18.0.0
+	 * @return array of ICreateFromTemplate|ICreateEmpty
+	 */
+	public function getCreators(): array;
+
+	/**
+	 * Return if the view is able to securely view a file without downloading it to the browser
+	 *
+	 * @since 18.0.0
+	 * @return bool
+	 */
+	public function isSecure(): bool;
+
+	/**
+	 * Return a template response for displaying the editor
+	 *
+	 * open can only be called once when the client requests the editor with a one-time-use token
+	 * For handling editing and later requests, editors need to impelement their own token handling and take care of invalidation
+	 *
+	 * This behavior is similar to the current direct editing implementation in collabora where we generate a one-time token and switch over to the regular wopi token for the actual editing/saving process
+	 *
+	 * @since 18.0.0
+	 * @return Response
+	 */
+	public function open(IToken $token): Response;
+}
diff --git a/lib/public/DirectEditing/IManager.php b/lib/public/DirectEditing/IManager.php
new file mode 100644
index 00000000000..07b9c5a1e4e
--- /dev/null
+++ b/lib/public/DirectEditing/IManager.php
@@ -0,0 +1,88 @@
+<?php
+declare(strict_types=1);
+/**
+ * @copyright Copyright (c) 2019 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\DirectEditing;
+
+use OCP\AppFramework\Http\Response;
+use OCP\Files\NotPermittedException;
+use RuntimeException;
+
+/**
+ * Interface IManager
+ *
+ * @package OCP\DirectEditing
+ * @since 18.0.0
+ */
+interface IManager {
+
+	/**
+	 * Register a new editor
+	 *
+	 * @since 18.0.0
+	 * @param IEditor $directEditor
+	 */
+	public function registerDirectEditor(IEditor $directEditor): void;
+
+	/**
+	 * Open the editing page for a provided token
+	 *
+	 * @since 18.0.0
+	 * @param string $token
+	 * @return Response
+	 */
+	public function edit(string $token): Response;
+
+	/**
+	 * Create a new token based on the file path and editor details
+	 *
+	 * @since 18.0.0
+	 * @param string $path
+	 * @param string $editorId
+	 * @param string $creatorId
+	 * @param null $templateId
+	 * @return string
+	 * @throws NotPermittedException
+	 * @throws RuntimeException
+	 */
+	public function create(string $path, string $editorId, string $creatorId, $templateId = null): string;
+
+	/**
+	 * Get the token details for a given token
+	 *
+	 * @since 18.0.0
+	 * @param string $token
+	 * @return IToken
+	 */
+	public function getToken(string $token): IToken;
+
+	/**
+	 * Cleanup expired tokens
+	 *
+	 * @since 18.0.0
+	 * @return int number of deleted tokens
+	 */
+	public function cleanup(): int;
+
+}
+
diff --git a/lib/public/DirectEditing/IToken.php b/lib/public/DirectEditing/IToken.php
new file mode 100644
index 00000000000..a730493d76e
--- /dev/null
+++ b/lib/public/DirectEditing/IToken.php
@@ -0,0 +1,77 @@
+<?php
+/**
+ * @copyright Copyright (c) 2019 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\DirectEditing;
+
+
+use OCP\Files\File;
+
+/**
+ * @since 18.0.0
+ */
+interface IToken {
+
+	/**
+	 * Extend the token validity time
+	 *
+	 * @since 18.0.0
+	 */
+	public function extend(): void;
+
+	/**
+	 * Invalidate the token
+	 *
+	 * @since 18.0.0
+	 */
+	public function invalidate(): void;
+
+	/**
+	 * Check if the token has already been used
+	 *
+	 * @since 18.0.0
+	 * @return bool
+	 */
+	public function hasBeenAccessed(): bool;
+
+	/**
+	 * Change to the user scope of the token
+	 *
+	 * @since 18.0.0
+	 */
+	public function useTokenScope(): void;
+
+	/**
+	 * Get the file that is related to the token
+	 *
+	 * @since 18.0.0
+	 * @return File
+	 */
+	public function getFile(): File;
+
+	/**
+	 * @since 18.0.0
+	 * @return string
+	 */
+	public function getEditor(): string;
+
+}
diff --git a/lib/public/DirectEditing/RegisterDirectEditorEvent.php b/lib/public/DirectEditing/RegisterDirectEditorEvent.php
new file mode 100644
index 00000000000..801e9f8fb1b
--- /dev/null
+++ b/lib/public/DirectEditing/RegisterDirectEditorEvent.php
@@ -0,0 +1,57 @@
+<?php
+/**
+ * @copyright Copyright (c) 2019 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\DirectEditing;
+
+use OCP\EventDispatcher\Event;
+
+/**
+ * @since 18.0.0
+ */
+class RegisterDirectEditorEvent extends Event {
+
+	/**
+	 * @var IManager
+	 */
+	private $manager;
+
+	/**
+	 * RegisterDirectEditorEvent constructor.
+	 *
+	 * @param IManager $manager
+	 * @since 18.0.0
+	 */
+	public function __construct(IManager $manager) {
+		parent::__construct();
+		$this->manager = $manager;
+	}
+
+	/**
+	 * @since 18.0.0
+	 * @param IEditor $editor
+	 */
+	public function register(IEditor $editor): void {
+		$this->manager->registerDirectEditor($editor);
+	}
+
+}