Feat/wopi phase 5

README.md

@@ -1,19 +1,20 @@
 # Office
 
-A Nextcloud app that provides a dedicated hub for office documents. Users can browse,
-filter, search, and create Documents, Spreadsheets, Presentations, and Diagrams from
-a single page — without going through the Files app.
+A Nextcloud app that integrates Euro-Office as a WOPI host, providing a full-page
+editor and a document hub. Nextcloud acts as the WOPI host (file storage, token
+authority, lock manager); Euro-Office acts as the WOPI client (rendering, editing).
 
 ---
 
 ## Features
 
-- **Overview page** at `/apps/office` — categorised file list with sidebar navigation
-- **Filters** — All / Mine / Shared with me
-- **Search** — within the active category, with an "Open in Files" escape hatch
-- **View toggle** — Grid (thumbnail previews) or List, persisted per user
-- **Template creator** — create new files from editor-provided templates
-- **Editor integration** — opens files directly in the configured office editor
+- **Full-page editor** at `/apps/office/open?fileId=N`
+- **Document overview** — browse, filter, search, and create office documents
+- **WOPI host implementation** — see [WOPI spec compliance](#wopi-spec-compliance) below
+- **Files app integration** — DEFAULT file action for all MIME types advertised by the editor
+- **Public share support** — guest tokens for link-share access
+- **Range reads** — partial file delivery via HTTP Range for large documents
+- **Conflict-free close** — editor close returns the user to the overview via `history.back()`
 
 ---
 
@@ -22,8 +23,9 @@ a single page — without going through the Files app.
 ### Requirements
 
 - [nextcloud-docker-dev](https://github.com/juliushaertl/nextcloud-docker-dev)
-- NC ≥ 33
-- Node 24 / npm 11
+- NC ≥ 31
+- Node ≥ 24 / npm ≥ 11
+- Euro-Office server reachable from the NC container
 
 ### 1. Mount the app into the container
 
@@ -41,8 +43,14 @@ Restart the container after saving.
 ### 2. Enable the app
 
 ```bash
-docker exec -u www-data nextcloud-docker-dev-nextcloud-1 \
-  php occ app:enable office
+docker compose exec --user www-data nextcloud php occ app:enable office
+```
+
+If the Euro-Office connector app is also installed, disable it to prevent it from
+competing for the DEFAULT file action:
+
+```bash
+docker compose exec --user www-data nextcloud php occ app:disable eurooffice
 ```
 
 ### 3. Build the frontend
@@ -90,6 +98,48 @@ recompiled assets as a `chore(assets): Recompile assets` commit.
 
 ---
 
+## How it works
+
+### WOPI flow
+
+```
+Browser                  NC (WOPI host)                  Euro-Office (WOPI client)
+   |                          |                                   |
+   |  GET /apps/office/open   |                                   |
+   |------------------------->|                                   |
+   |                          | mint WOPI token (TokenManager)    |
+   |                          | build editor URL with wopisrc     |
+   |   editor iframe / page   |                                   |
+   |<-------------------------|                                   |
+   |                          |  GET /wopi/files/{id}?token=...  |
+   |                          |<----------------------------------|
+   |                          |  CheckFileInfo response           |
+   |                          |---------------------------------->|
+   |                          |  GET /wopi/files/{id}/contents   |
+   |                          |<----------------------------------|
+   |                          |  file bytes                       |
+   |                          |---------------------------------->|
+   |   ← editing session →    |                                   |
+   |                          |  POST /wopi/files/{id}/contents  |
+   |                          |<----------------------------------|
+   |                          |  204 No Content                   |
+   |                          |---------------------------------->|
+```
+
+### Key classes
+
+| Class | Responsibility |
+|---|---|
+| `EditorController` | Renders editor page; mints WOPI token; builds editor URL from discovery XML |
+| `WopiController` | WOPI protocol endpoint — handles all `/wopi/files/` requests |
+| `TokenManager` | Creates and validates WOPI tokens; manages token TTL and guest vs user access |
+| `DiscoveryService` | Fetches and caches the editor's discovery XML; resolves MIME → action URL |
+| `ShareController` | Issues guest tokens for public share links |
+| `WopiMapper` / `WopiLockMapper` | Persistence for WOPI tokens and file locks |
+| `CleanupJob` | Background job — expires stale locks and tokens |
+
+---
+
 ## Editor integration
 
 The overview opens files via NC's file shortlink (`/f/{fileid}`), which
@@ -103,7 +153,61 @@ present, navigates directly to that URL instead of `/f/{fileid}`.
 
 ---
 
-## Architecture
+## WOPI spec compliance
+
+### Operations
+
+| Operation | `X-WOPI-Override` | Status | Notes |
+|---|---|---|---|
+| CheckFileInfo | — | ✅ | `GET /wopi/files/{id}` |
+| GetFile | — | ✅ | `GET /wopi/files/{id}/contents`; HTTP Range supported |
+| PutFile | — | ✅ | `POST /wopi/files/{id}/contents`; lock-enforced, optimistic version check, quota check |
+| Lock | `LOCK` | ✅ | |
+| Unlock | `UNLOCK` | ✅ | |
+| RefreshLock | `REFRESH_LOCK` | ✅ | |
+| GetLock | `GET_LOCK` | ✅ | |
+| UnlockAndRelock | `LOCK` + `X-WOPI-OldLock` | ✅ | |
+| RenameFile | `RENAME_FILE` | ✅ | Authenticated users only; conflict returns 400 + `X-WOPI-InvalidFileNameError` |
+| PutRelativeFile | `PUT_RELATIVE_FILE` | ⏳ Phase 6 | `UserCanNotWriteRelative: true` suppresses Save As in the editor UI |
+| DeleteFile | `DELETE` | — | Deletion is handled by NC outside WOPI |
+
+### CheckFileInfo capability flags
+
+| Flag | Value | Notes |
+|---|---|---|
+| `SupportsUpdate` | `true` | PutFile is implemented |
+| `SupportsLocks` | dynamic | `true` when an NC lock provider is available |
+| `SupportsGetLock` | `true` | GetLock is implemented |
+| `SupportsExtendedLockLength` | `true` | `lock_id` column is `VARCHAR(1024)` |
+| `SupportsRename` | per session | `true` for authenticated users; `false` for guests |
+| `UserCanRename` | per session | `true` for authenticated users; `false` for guests |
+| `UserCanNotWriteRelative` | `true` | PutRelativeFile deferred to Phase 6 |
+| `UserCanWrite` | per token | stamped at token-issue time from file/share permissions |
+| `IsAnonymousUser` | per session | `true` for guest (share-link) sessions |
+| `HasContentRange` | `true` | partial file reads via HTTP Range are supported |
+| `HideExportOption` | per token | derived from share `hide_download` flag |
+| `DisablePrint` | per token | derived from share `hide_download` flag |
+| `DisableExport` | per token | derived from share `hide_download` flag |
+
+---
+
+## Public share support
+
+Share link visitors (`/s/{token}`) receive a guest WOPI token via `ShareController`.
+File access, locking, and `CheckFileInfo` flags (`HideExportOption`, `DisablePrint`,
+`UserCanWrite`, etc.) are all derived from the share's permissions and `hide_download`
+flag at token-issue time.
+
+**Known gaps:**
+
+- **KG1** — Password-protected shares: users must authenticate at `/s/{token}` before
+  navigating to the editor.
+- **KG2** — Authenticated users arriving through share links receive guest tokens.
+- **KG3** — Federated/remote shares not tested.
+
+---
+
+## Frontend architecture
 
 ```
 /apps/office
@@ -120,3 +224,14 @@ present, navigates directly to that URL instead of `/f/{fileid}`.
                 ├── fileCategories.ts  Mime → category mapping (pure)
                 └── validateFilename.ts
 ```
+
+---
+
+## Backend architecture notes
+
+The WOPI token row (`oc_office_wopi`) is the authority for per-session flags
+(`canwrite`, `hideDownload`, `ownerUid`). Flags are stamped at token-generation
+time and not re-read on subsequent WOPI requests — this avoids a per-request
+`IShareManager` lookup on every CheckFileInfo heartbeat, matching the richdocuments
+pattern. Trade-off: share revocation mid-session is not enforced within the token TTL
+(10 h).

appinfo/info.xml

@@ -14,6 +14,12 @@
 	<dependencies>
 		<nextcloud min-version="36" max-version="36"/>
 	</dependencies>
+	<background-jobs>
+		<job>OCA\Office\BackgroundJob\CleanupJob</job>
+	</background-jobs>
+	<settings>
+		<admin>OCA\Office\Settings\Admin</admin>
+	</settings>
 	<navigations>
 		<navigation>
 			<id>office</id>

composer.json

@@ -13,6 +13,12 @@
 			"OCA\\Office\\": "lib/"
 		}
 	},
+	"autoload-dev": {
+		"psr-4": {
+			"OCP\\": "vendor/nextcloud/ocp/OCP/",
+			"OCA\\Office\\Tests\\": "tests/"
+		}
+	},
 	"scripts": {
 		"post-install-cmd": [
 			"@composer bin all install --ansi"
@@ -24,7 +30,8 @@
 		"cs:check": "php-cs-fixer fix --dry-run --diff",
 		"cs:fix": "php-cs-fixer fix",
 		"psalm": "psalm --threads=1 --no-cache",
-		"test:unit": "phpunit tests -c tests/phpunit.xml --colors=always --fail-on-warning --fail-on-risky",
+		"test:unit": "phpunit -c tests/phpunit.xml --colors=always --fail-on-warning --fail-on-risky",
+		"test:integration": "echo 'Integration tests run in-container only: docker exec -u www-data -w /var/www/html/apps-extra/office nextcloud php vendor/bin/phpunit tests/integration -c tests/phpunit.integration.xml' && exit 1",
 		"openapi": "generate-spec",
 		"rector": "rector && composer cs:fix"
 	},

lib/AppInfo/Application.php

@@ -5,10 +5,12 @@
 namespace OCA\Office\AppInfo;
 
 use OCA\Office\Listener\AppMenuActionListener;
+use OCA\Office\Listener\LoadAdditionalScriptsListener;
 use OCP\AppFramework\App;
 use OCP\AppFramework\Bootstrap\IBootContext;
 use OCP\AppFramework\Bootstrap\IBootstrap;
 use OCP\AppFramework\Bootstrap\IRegistrationContext;
+use OCP\Collaboration\Resources\LoadAdditionalScriptsEvent;
 use OCP\Navigation\Events\LoadAdditionalEntriesEvent;
 
 final class Application extends App implements IBootstrap {
@@ -22,6 +24,7 @@ public function __construct() {
 	#[\Override]
 	public function register(IRegistrationContext $context): void {
 		$context->registerEventListener(LoadAdditionalEntriesEvent::class, AppMenuActionListener::class);
+		$context->registerEventListener(LoadAdditionalScriptsEvent::class, LoadAdditionalScriptsListener::class);
 	}
 
 	#[\Override]

lib/BackgroundJob/CleanupJob.php

@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Office\BackgroundJob;
+
+use OCA\Office\Db\WopiLockMapper;
+use OCA\Office\Db\WopiMapper;
+use OCP\AppFramework\Utility\ITimeFactory;
+use OCP\BackgroundJob\TimedJob;
+
+class CleanupJob extends TimedJob {
+	private const BATCH_SIZE = 500;
+
+	public function __construct(
+		ITimeFactory $time,
+		private WopiMapper $wopiMapper,
+		private WopiLockMapper $wopiLockMapper,
+	) {
+		parent::__construct($time);
+		$this->setInterval(3600); // run hourly
+	}
+
+	protected function run(mixed $argument): void {
+		$tokenIds = $this->wopiMapper->getExpiredTokenIds(self::BATCH_SIZE);
+		if (!empty($tokenIds)) {
+			$this->wopiMapper->deleteByIds($tokenIds);
+		}
+
+		$lockIds = $this->wopiLockMapper->getExpiredLockIds(self::BATCH_SIZE);
+		if (!empty($lockIds)) {
+			$this->wopiLockMapper->deleteByIds($lockIds);
+		}
+	}
+}

lib/Controller/EditorController.php

@@ -0,0 +1,96 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Office\Controller;
+
+use OCA\Office\AppInfo\Application;
+use OCA\Office\Service\DiscoveryService;
+use OCA\Office\TokenManager;
+use OCP\AppFramework\Controller;
+use OCP\AppFramework\Http\Attribute\FrontpageRoute;
+use OCP\AppFramework\Http\Attribute\NoAdminRequired;
+use OCP\AppFramework\Http\Attribute\NoCSRFRequired;
+use OCP\AppFramework\Http\JSONResponse;
+use OCP\AppFramework\Http\TemplateResponse;
+use OCP\Files\File;
+use OCP\Files\IRootFolder;
+use OCP\Files\NotFoundException;
+use OCP\Files\NotPermittedException;
+use OCP\IRequest;
+use OCP\IURLGenerator;
+use Psr\Log\LoggerInterface;
+
+class EditorController extends Controller {
+	public function __construct(
+		string $appName,
+		IRequest $request,
+		private IRootFolder $rootFolder,
+		private TokenManager $tokenManager,
+		private DiscoveryService $discoveryService,
+		private IURLGenerator $urlGenerator,
+		private LoggerInterface $logger,
+		private ?string $userId,
+	) {
+		parent::__construct($appName, $request);
+	}
+
+	/**
+	 * Open a file in the WOPI editor.
+	 *
+	 * Returns an HTML page that embeds the editor in a full-screen iframe.
+	 */
+	#[NoAdminRequired]
+	#[NoCSRFRequired]
+	#[FrontpageRoute(verb: 'GET', url: '/open')]
+	public function open(int $fileId): TemplateResponse|JSONResponse {
+		try {
+			$userFolder = $this->rootFolder->getUserFolder((string)$this->userId);
+			$file = $userFolder->getFirstNodeById($fileId);
+
+			if (!$file instanceof File) {
+				return new JSONResponse(['error' => 'File not found'], \OCP\AppFramework\Http::STATUS_NOT_FOUND);
+			}
+
+			$extension = pathinfo($file->getName(), PATHINFO_EXTENSION);
+			$urlsrc = $this->discoveryService->getUrlSrc($extension, 'edit')
+				?? $this->discoveryService->getUrlSrc($extension, 'view');
+
+			if ($urlsrc === null) {
+				return new JSONResponse(
+					['error' => 'File type not supported by the editor'],
+					\OCP\AppFramework\Http::STATUS_UNSUPPORTED_MEDIA_TYPE
+				);
+			}
+
+			$wopi = $this->tokenManager->generateToken($fileId);
+
+			$wopiSrc = $this->urlGenerator->linkToRouteAbsolute(
+				'office.wopi.checkFileInfo',
+				['fileId' => $fileId]
+			);
+
+			$editorUrl = $this->discoveryService->buildEditorUrl($urlsrc, $wopiSrc, $wopi->getToken());
+
+		} catch (NotFoundException|NotPermittedException $e) {
+			$this->logger->warning($e->getMessage(), ['exception' => $e]);
+			return new JSONResponse(['error' => 'File not accessible'], \OCP\AppFramework\Http::STATUS_FORBIDDEN);
+		} catch (\Throwable $e) {
+			$this->logger->error($e->getMessage(), ['exception' => $e]);
+			return new JSONResponse(['error' => 'Internal error'], \OCP\AppFramework\Http::STATUS_INTERNAL_SERVER_ERROR);
+		}
+
+		$response = new TemplateResponse(Application::APP_ID, 'editor', [], 'base');
+		$response->setParams([
+			'editorUrl' => $editorUrl,
+			'postMessageOrigin' => $wopi->getServerHost(),
+			'fileName' => $file->getName(),
+		]);
+		return $response;
+	}
+}