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
@@ -55,26 +63,107 @@ npm run watch      # rebuild on file changes
 
 ---
 
-## Editor integration
+## How it works
+
+### WOPI flow
 
-The overview opens files via NC's file shortlink (`/f/{fileid}`), which
-redirects to the Files app and triggers the default file action for the
-installed office editor.
+```
+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
 
-To inject a custom editor URL, a backend component can call
-`provideInitialState('office', 'editor-url', $url)` before the page renders.
-The frontend reads this via `loadState('office', 'editor-url', null)` and, when
-present, navigates directly to that URL instead of `/f/{fileid}`.
+| 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 |
 
 ---
 
-## 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 |
 
-```
-/apps/office
-└── PageController::index()       Renders the SPA shell
-    └── OfficeOverview.vue        Full Vue 3 SPA
-        ├── officeFiles.ts        WebDAV file listing via @nextcloud/files
-        ├── templates.ts          Template discovery and file creation
-        └── config.ts             User preference persistence (grid/list view)
-```
+---
+
+## 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.
+
+---
+
+## 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="35" max-version="35"/>
 	</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"
 	},