From 12e2123142d286136fad44accc4240a59331bd5d Mon Sep 17 00:00:00 2001 From: Julius Knorr Date: Fri, 6 Nov 2026 09:36:52 +0100 Subject: [PATCH 1/3] feat(embedding): add native runtime compatibility Keep runtime discovery, request digest checks and build metadata generation in Text for the paired native collaboration client. Assisted-by: Codex:gpt-6.1-sol Signed-off-by: Julius Knorr --- .gitignore | 1 + appinfo/routes.php | 1 + composer/composer/autoload_classmap.php | 2 + composer/composer/autoload_static.php | 2 + docs/native-embedding.md | 47 +++++++++++ lib/Controller/EmbeddingController.php | 33 ++++++++ lib/Middleware/SessionMiddleware.php | 6 ++ lib/Service/RuntimeManifest.php | 52 +++++++++++++ tests/native_embedding/test_manifest.py | 52 +++++++++++++ tests/unit/Service/RuntimeManifestTest.php | 90 ++++++++++++++++++++++ tools/native-embedding.py | 54 +++++++++++++ 11 files changed, 340 insertions(+) create mode 100644 docs/native-embedding.md create mode 100644 lib/Controller/EmbeddingController.php create mode 100644 lib/Service/RuntimeManifest.php create mode 100644 tests/native_embedding/test_manifest.py create mode 100644 tests/unit/Service/RuntimeManifestTest.php create mode 100644 tools/native-embedding.py diff --git a/.gitignore b/.gitignore index 0f617bc0ce6..5eb4f5aa515 100644 --- a/.gitignore +++ b/.gitignore @@ -13,6 +13,7 @@ dist/ /vendor/ /vendor-bin/*/vendor webpack-stats.json +__pycache__/ # js folder, to be updated wth --force /js diff --git a/appinfo/routes.php b/appinfo/routes.php index 7495440142d..0d313d7ab45 100644 --- a/appinfo/routes.php +++ b/appinfo/routes.php @@ -12,6 +12,7 @@ return [ 'routes' => [ + ['name' => 'Embedding#get', 'url' => '/embedding', 'verb' => 'GET'], /** @see Controller\AttachmentController::getAttachmentList() */ ['name' => 'Attachment#getAttachmentList', 'url' => '/attachments', 'verb' => 'POST'], /** @see Controller\AttachmentController::insertAttachmentFile() */ diff --git a/composer/composer/autoload_classmap.php b/composer/composer/autoload_classmap.php index 91dc2b839a3..65fc2cfa580 100644 --- a/composer/composer/autoload_classmap.php +++ b/composer/composer/autoload_classmap.php @@ -21,6 +21,7 @@ 'OCA\\Text\\Context\\UnauthorizedFileContext' => $baseDir . '/../lib/Context/UnauthorizedFileContext.php', 'OCA\\Text\\Controller\\AiController' => $baseDir . '/../lib/Controller/AiController.php', 'OCA\\Text\\Controller\\AttachmentController' => $baseDir . '/../lib/Controller/AttachmentController.php', + 'OCA\\Text\\Controller\\EmbeddingController' => $baseDir . '/../lib/Controller/EmbeddingController.php', 'OCA\\Text\\Controller\\ISessionAwareController' => $baseDir . '/../lib/Controller/ISessionAwareController.php', 'OCA\\Text\\Controller\\NavigationController' => $baseDir . '/../lib/Controller/NavigationController.php', 'OCA\\Text\\Controller\\PublicSessionController' => $baseDir . '/../lib/Controller/PublicSessionController.php', @@ -96,6 +97,7 @@ 'OCA\\Text\\Service\\InitialStateProvider' => $baseDir . '/../lib/Service/InitialStateProvider.php', 'OCA\\Text\\Service\\LockService' => $baseDir . '/../lib/Service/LockService.php', 'OCA\\Text\\Service\\NotificationService' => $baseDir . '/../lib/Service/NotificationService.php', + 'OCA\\Text\\Service\\RuntimeManifest' => $baseDir . '/../lib/Service/RuntimeManifest.php', 'OCA\\Text\\Service\\SessionService' => $baseDir . '/../lib/Service/SessionService.php', 'OCA\\Text\\Service\\WorkspaceService' => $baseDir . '/../lib/Service/WorkspaceService.php', 'OCA\\Text\\TextFile' => $baseDir . '/../lib/TextFile.php', diff --git a/composer/composer/autoload_static.php b/composer/composer/autoload_static.php index 0a506511f39..7bd283c323e 100644 --- a/composer/composer/autoload_static.php +++ b/composer/composer/autoload_static.php @@ -36,6 +36,7 @@ class ComposerStaticInitText 'OCA\\Text\\Context\\UnauthorizedFileContext' => __DIR__ . '/..' . '/../lib/Context/UnauthorizedFileContext.php', 'OCA\\Text\\Controller\\AiController' => __DIR__ . '/..' . '/../lib/Controller/AiController.php', 'OCA\\Text\\Controller\\AttachmentController' => __DIR__ . '/..' . '/../lib/Controller/AttachmentController.php', + 'OCA\\Text\\Controller\\EmbeddingController' => __DIR__ . '/..' . '/../lib/Controller/EmbeddingController.php', 'OCA\\Text\\Controller\\ISessionAwareController' => __DIR__ . '/..' . '/../lib/Controller/ISessionAwareController.php', 'OCA\\Text\\Controller\\NavigationController' => __DIR__ . '/..' . '/../lib/Controller/NavigationController.php', 'OCA\\Text\\Controller\\PublicSessionController' => __DIR__ . '/..' . '/../lib/Controller/PublicSessionController.php', @@ -111,6 +112,7 @@ class ComposerStaticInitText 'OCA\\Text\\Service\\InitialStateProvider' => __DIR__ . '/..' . '/../lib/Service/InitialStateProvider.php', 'OCA\\Text\\Service\\LockService' => __DIR__ . '/..' . '/../lib/Service/LockService.php', 'OCA\\Text\\Service\\NotificationService' => __DIR__ . '/..' . '/../lib/Service/NotificationService.php', + 'OCA\\Text\\Service\\RuntimeManifest' => __DIR__ . '/..' . '/../lib/Service/RuntimeManifest.php', 'OCA\\Text\\Service\\SessionService' => __DIR__ . '/..' . '/../lib/Service/SessionService.php', 'OCA\\Text\\Service\\WorkspaceService' => __DIR__ . '/..' . '/../lib/Service/WorkspaceService.php', 'OCA\\Text\\TextFile' => __DIR__ . '/..' . '/../lib/TextFile.php', diff --git a/docs/native-embedding.md b/docs/native-embedding.md new file mode 100644 index 00000000000..cb8305c787d --- /dev/null +++ b/docs/native-embedding.md @@ -0,0 +1,47 @@ + +# Experimental native embedding compatibility + +This development branch provides compatibility metadata for a bundled native +Text client. It is not a supported public embedding API. The paired native +implementation lives on [the Collectives collaboration branch](https://github.com/juliusknorr/collectives-swiftui/tree/feat/text-collaboration). + +After building Text and regenerating its Composer class map, generate metadata: + +```sh +python3 tools/native-embedding.py --source-revision "$(git rev-parse HEAD)" +``` + +Archives without Git metadata must supply the full pinned commit explicitly. +The generated `js/native-embedding.json` is ignored and must be deployed +atomically alongside the corresponding code. Authenticated `GET /embedding` +returns its six fields: format, Text version, source revision, code digest, +session API and update encoding. Missing or invalid metadata, including a +mismatch with `appinfo/info.xml`, yields HTTP 503. Responses use `no-store`. + +The digest fingerprints sorted paths and SHA-256 hashes of `.mjs`, `.css`, `.php` +and `.xml` files in `js`, `css`, `lib`, `appinfo` and `composer/composer`. JSON +metadata excludes itself. The native bundle must use exactly the same manifest. +This trusts a coherent server deployment; manually editing same-version code +without regenerating metadata invalidates that guarantee. It avoids hashing +roughly 14 MB of JavaScript on every request. + +Session middleware optionally accepts `runtimeDigest`. A supplied incompatible +digest rejects create/sync/push/save with HTTP 412 before session handling. Native +clients always supply it. Browser clients without it retain their existing +behavior. Close remains available for cleanup after an upgrade and does not +prove that the document was saved. + +Run the parser and generator tests without a server: + +```sh +vendor/bin/phpunit --no-configuration --do-not-cache-result tests/unit/Service/RuntimeManifestTest.php +python3 -m unittest discover -s tests/native_embedding +``` + +The paired native WebKit smoke suite exercises the authenticated endpoint, +matching and incompatible session operations, collaboration, reconnect and save +confirmation against a real server. Transport injection and a durable editor +drain/save/close contract remain separate follow-up work. diff --git a/lib/Controller/EmbeddingController.php b/lib/Controller/EmbeddingController.php new file mode 100644 index 00000000000..72c23d8d843 --- /dev/null +++ b/lib/Controller/EmbeddingController.php @@ -0,0 +1,33 @@ +manifest->get(); + $response = new DataResponse($manifest ?? [], $manifest === null ? 503 : 200); + $response->addHeader('Cache-Control', 'no-store'); + return $response; + } +} diff --git a/lib/Middleware/SessionMiddleware.php b/lib/Middleware/SessionMiddleware.php index 942ff68ce33..b2827a841d1 100644 --- a/lib/Middleware/SessionMiddleware.php +++ b/lib/Middleware/SessionMiddleware.php @@ -57,6 +57,12 @@ public function beforeController(Controller $controller, string $methodName): vo return; } + $runtimeDigest = $this->request->getParam('runtimeDigest'); + if ($runtimeDigest !== null && $methodName !== 'close' + && (!is_string($runtimeDigest) || !(new \OCA\Text\Service\RuntimeManifest())->matches($runtimeDigest))) { + throw new InvalidDocumentBaseVersionEtagException(); + } + $reflectionMethod = new \ReflectionMethod($controller, $methodName); if (!empty($reflectionMethod->getAttributes(RequireDocumentSessionOrUserOrShareToken::class))) { diff --git a/lib/Service/RuntimeManifest.php b/lib/Service/RuntimeManifest.php new file mode 100644 index 00000000000..7eaa3615081 --- /dev/null +++ b/lib/Service/RuntimeManifest.php @@ -0,0 +1,52 @@ +manifestPath) || !is_file($this->versionPath)) { + return null; + } + try { + $manifest = json_decode(file_get_contents($this->manifestPath), true, 32, JSON_THROW_ON_ERROR); + } catch (\JsonException) { + return null; + } + if (!is_array($manifest) + || ($manifest['format'] ?? null) !== 1 + || ($manifest['sessionAPI'] ?? null) !== 'context-v1' + || ($manifest['updateEncoding'] ?? null) !== 'yjs-sync-v1') { + return null; + } + foreach (['sourceRevision' => 40, 'codeDigest' => 64] as $key => $length) { + if (!is_string($manifest[$key] ?? null) || !preg_match('/^[a-f0-9]{' . $length . '}$/D', $manifest[$key])) { + return null; + } + } + $info = simplexml_load_string(file_get_contents($this->versionPath), options: LIBXML_NONET); + if ($info === false || ($manifest['textVersion'] ?? null) !== (string)$info->version) { + return null; + } + return array_intersect_key($manifest, array_flip([ + 'format', 'textVersion', 'sourceRevision', 'codeDigest', 'sessionAPI', 'updateEncoding', + ])); + } + + public function matches(string $digest): bool { + $manifest = $this->get(); + return $manifest !== null && hash_equals($manifest['codeDigest'], $digest); + } +} diff --git a/tests/native_embedding/test_manifest.py b/tests/native_embedding/test_manifest.py new file mode 100644 index 00000000000..007977f1022 --- /dev/null +++ b/tests/native_embedding/test_manifest.py @@ -0,0 +1,52 @@ +# SPDX-FileCopyrightText: 2026 Nextcloud contributors +# SPDX-License-Identifier: AGPL-3.0-or-later +import importlib.util +from pathlib import Path +import tempfile +import unittest + +spec = importlib.util.spec_from_file_location('native_embedding', + Path(__file__).resolve().parents[2] / 'tools/native-embedding.py') +embedding = importlib.util.module_from_spec(spec) +spec.loader.exec_module(embedding) + + +class ManifestBuildTest(unittest.TestCase): + def setUp(self): + self.directory = tempfile.TemporaryDirectory() + self.addCleanup(self.directory.cleanup) + self.root = Path(self.directory.name) + for folder in ['appinfo', 'js', 'css', 'lib', 'composer/composer']: + (self.root / folder).mkdir(parents=True) + (self.root / 'appinfo/info.xml').write_text('10.0.0-dev.3') + (self.root / 'js/editor.mjs').write_text('export const editor = true;') + self.revision = 'a' * 40 + + def test_repeated_generation_is_identical_and_excludes_its_output(self): + first = embedding.write_manifest(self.root, self.revision) + before = (self.root / 'js/native-embedding.json').read_bytes() + self.assertEqual(first, embedding.write_manifest(self.root, self.revision)) + self.assertEqual(before, (self.root / 'js/native-embedding.json').read_bytes()) + self.assertEqual(0o644, (self.root / 'js/native-embedding.json').stat().st_mode & 0o777) + + def test_changed_deployed_code_changes_the_digest(self): + first = embedding.manifest_for(self.root, self.revision) + (self.root / 'lib/Service.php').write_text('') + with self.assertRaises(ValueError): + embedding.manifest_for(self.root, self.revision) + + def test_invalid_revision_is_rejected(self): + for revision in ['main', '../other', 'A' * 40, 'a' * 39]: + with self.assertRaises(ValueError): + embedding.manifest_for(self.root, revision) + + +if __name__ == '__main__': + unittest.main() diff --git a/tests/unit/Service/RuntimeManifestTest.php b/tests/unit/Service/RuntimeManifestTest.php new file mode 100644 index 00000000000..3479eb97cb8 --- /dev/null +++ b/tests/unit/Service/RuntimeManifestTest.php @@ -0,0 +1,90 @@ +directory = sys_get_temp_dir() . '/text-manifest-' . bin2hex(random_bytes(8)); + mkdir($this->directory); + $this->service = new RuntimeManifest($this->directory . '/manifest.json', $this->directory . '/info.xml'); + $this->manifest = [ + 'format' => 1, 'textVersion' => '10.0.0-dev.3', 'sourceRevision' => str_repeat('a', 40), + 'codeDigest' => str_repeat('b', 64), 'sessionAPI' => 'context-v1', 'updateEncoding' => 'yjs-sync-v1', + ]; + file_put_contents($this->directory . '/info.xml', '10.0.0-dev.3'); + $this->writeManifest(); + } + + protected function tearDown(): void { + foreach (glob($this->directory . '/*') as $file) { + unlink($file); + } + rmdir($this->directory); + } + + private function writeManifest(): void { + file_put_contents($this->directory . '/manifest.json', json_encode($this->manifest, JSON_THROW_ON_ERROR)); + } + + public function testMatchingManifestAndDigestAreAccepted(): void { + $this->assertSame($this->manifest, $this->service->get()); + $this->assertTrue($this->service->matches(str_repeat('b', 64))); + $this->assertFalse($this->service->matches(str_repeat('c', 64))); + } + + public function testManifestWorksWithExternalEntityLoadingDisabled(): void { + $previous = libxml_get_external_entity_loader(); + libxml_set_external_entity_loader(static fn () => null); + try { + $this->assertSame($this->manifest, $this->service->get()); + } finally { + libxml_set_external_entity_loader($previous); + } + } + + public function testMissingAndMalformedManifestFailClosed(): void { + unlink($this->directory . '/manifest.json'); + $this->assertNull($this->service->get()); + file_put_contents($this->directory . '/manifest.json', '{malformed'); + $this->assertNull($this->service->get()); + } + + public function testStaleManifestAfterAppUpgradeIsRejected(): void { + file_put_contents($this->directory . '/info.xml', '10.0.0-dev.4'); + $this->assertNull($this->service->get()); + $this->assertFalse($this->service->matches($this->manifest['codeDigest'])); + } + + public function testUnsupportedProtocolAndInvalidDigestAreRejected(): void { + $this->manifest['sessionAPI'] = 'context-v2'; + $this->writeManifest(); + $this->assertNull($this->service->get()); + $this->manifest['sessionAPI'] = 'context-v1'; + $this->manifest['codeDigest'] = '../invalid'; + $this->writeManifest(); + $this->assertNull($this->service->get()); + } + + public function testUnrelatedServerMetadataIsNotPublished(): void { + $this->manifest['privatePath'] = '/example/internal/path'; + $this->writeManifest(); + $result = $this->service->get(); + $this->assertArrayNotHasKey('privatePath', $result); + $this->assertCount(6, $result); + } +} diff --git a/tools/native-embedding.py b/tools/native-embedding.py new file mode 100644 index 00000000000..edf12d94809 --- /dev/null +++ b/tools/native-embedding.py @@ -0,0 +1,54 @@ +#!/usr/bin/env python3 +# SPDX-FileCopyrightText: 2026 Nextcloud contributors +# SPDX-License-Identifier: AGPL-3.0-or-later +"""Generate compatibility metadata alongside a built Text deployment.""" +import argparse +import hashlib +import json +import os +from pathlib import Path +import re +import tempfile +import xml.etree.ElementTree as ET + +ROOT = Path(__file__).resolve().parents[1] + + +def manifest_for(source, revision): + if not re.fullmatch(r'[a-f0-9]{40}', revision): + raise ValueError('Expected a full lowercase Git source revision') + version = ET.parse(source / 'appinfo/info.xml').getroot().findtext('version') + if not version: + raise ValueError('Text app version is missing') + fingerprints = {} + for folder in ['js', 'css', 'lib', 'appinfo', 'composer/composer']: + for file in sorted((source / folder).rglob('*')): + if file.is_file() and file.suffix in ['.mjs', '.css', '.php', '.xml']: + fingerprints[str(file.relative_to(source))] = hashlib.sha256(file.read_bytes()).hexdigest() + encoded = json.dumps(fingerprints, sort_keys=True, separators=(',', ':')).encode() + return dict(format=1, textVersion=version, sourceRevision=revision, + codeDigest=hashlib.sha256(encoded).hexdigest(), + sessionAPI='context-v1', updateEncoding='yjs-sync-v1') + + +def write_manifest(source, revision): + manifest = manifest_for(source, revision) + target = source / 'js/native-embedding.json' + temporary = None + try: + with tempfile.NamedTemporaryFile(mode='w', dir=target.parent, delete=False) as output: + temporary = Path(output.name) + output.write(json.dumps(manifest, indent=2) + '\n') + temporary.chmod(0o644) + os.replace(temporary, target) + finally: + if temporary is not None: + temporary.unlink(missing_ok=True) + return manifest + + +if __name__ == '__main__': + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument('--source-revision', required=True) + args = parser.parse_args() + write_manifest(ROOT, args.source_revision) From 5ab89e2bb9a8ad031304c1275635c0a3e27dd5bd Mon Sep 17 00:00:00 2001 From: Julius Knorr Date: Fri, 6 Nov 2026 13:16:01 +0100 Subject: [PATCH 2/3] feat(embedding): add a small native host seam Expose per-editor transport injection, Yjs snapshots and a drain acknowledgement. Keep persistence, save/close orchestration and the demo host in the native app repository. Assisted-by: Codex:gpt-6.1-sol Signed-off-by: Julius Knorr --- docs/native-embedding.md | 33 ++++++ playwright/e2e/embedding.spec.ts | 107 ++++++++++++++++++ src/TextEditorEmbed.ts | 17 +++ src/components/CollaborativeEditor.vue | 25 +++- src/components/EditorReloader.vue | 2 + src/composables/useConnection.ts | 26 +---- src/composables/useIndexedDbProvider.ts | 24 +++- src/composables/useSaveService.ts | 2 + src/composables/useSyncService.ts | 2 + src/createEditor.ts | 10 ++ src/services/Outbox.ts | 4 + src/services/PollingBackend.ts | 3 +- src/services/SaveService.ts | 13 ++- src/services/SessionTransport.ts | 22 ++++ src/services/SyncService.ts | 27 ++++- src/tests/services/EmbeddingIsolation.spec.ts | 57 ++++++++++ src/tests/services/EmbeddingTransport.spec.ts | 51 +++++++++ src/types/EmbeddingState.ts | 17 +++ 18 files changed, 407 insertions(+), 35 deletions(-) create mode 100644 playwright/e2e/embedding.spec.ts create mode 100644 src/services/SessionTransport.ts create mode 100644 src/tests/services/EmbeddingIsolation.spec.ts create mode 100644 src/tests/services/EmbeddingTransport.spec.ts create mode 100644 src/types/EmbeddingState.ts diff --git a/docs/native-embedding.md b/docs/native-embedding.md index cb8305c787d..4fb23f0dbb8 100644 --- a/docs/native-embedding.md +++ b/docs/native-embedding.md @@ -45,3 +45,36 @@ The paired native WebKit smoke suite exercises the authenticated endpoint, matching and incompatible session operations, collaboration, reconnect and save confirmation against a real server. Transport injection and a durable editor drain/save/close contract remain separate follow-up work. + +## Small public editor seam + +`createCollaborativeEditor({ el, context, sessionTransport })` accepts a per-editor +transport with the existing `openContext`, `sync`, `push`, `save` and `close` +shapes. The default browser transport is unchanged. Injected transports use +in-memory state instead of IndexedDB; the host owns account/file binding, +credentials, storage, request limits and timeouts. Public shares are not supported +by the injected transport yet. Browser sendBeacon never bypasses it. + +Two wrapper methods expose the required editor state without component accessors: + +```ts +const editor = await createCollaborativeEditor({ el, context, sessionTransport }) +const checkpoint = editor.exportState() +const drained = await editor.drain() +``` + +The snapshot contains a full base64 Yjs update, state vector, Markdown, version, +context and collaboration base ETag, without session credentials. `drain()` +freezes user input, waits for queued/in-flight provider updates, and returns a +snapshot; failures reject. It does not persist, save, or close the session. + +The host must persist recovery state, control file-save requests, verify the saved +version, close through its own transport, and fetch canonical DAV Markdown/ETag +before releasing ownership and destroying the editor. Automatic save requests +still go through the injected transport and can be deferred by the host. + +`playwright/e2e/embedding.spec.ts` uses the existing Text fixtures to test two +embedded clients, Unicode convergence, valid Yjs export and drain acknowledgements. +The larger demo and checkpoint/save/close coordinator live in the +[native app repository](https://github.com/juliusknorr/collectives-swiftui/tree/feat/text-collaboration/dev/text-collaboration/embedding). +Per-edit durability and cold-restart recovery remain host-side follow-up work. diff --git a/playwright/e2e/embedding.spec.ts b/playwright/e2e/embedding.spec.ts new file mode 100644 index 00000000000..3ecd13b9849 --- /dev/null +++ b/playwright/e2e/embedding.spec.ts @@ -0,0 +1,107 @@ +/** + * SPDX-FileCopyrightText: 2026 Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +import type { SessionTransport } from '../../src/services/SessionTransport.ts' +import type { TextEditorEmbed } from '../../src/TextEditorEmbed.ts' + +import { expect } from '@playwright/test' +import { randomUUID } from 'node:crypto' +import * as Y from 'yjs' +import { test } from '../support/fixtures/upload-file.ts' + +declare global { + interface Window { + embeddingInstances: TextEditorEmbed[] + embeddingHost: (peer: number, operation: string, data: object) => Promise + } +} + +test.use({ fileName: `embedding-seam-${randomUUID()}.md`, fileContent: '# Embedded Text\n\nShared text.\n' }) + +test('public transport joins two editors, exports Yjs state and acknowledges drain', async ({ page, file, baseURL }) => { + type Session = { documentId: string, sessionId: number, sessionToken: string, baseVersionEtag: string } + const sessions = new Map() + const operations = new Set() + const sanitize = (value: unknown): unknown => { + if (Array.isArray(value)) { + return value.map(sanitize) + } + if (!value || typeof value !== 'object') { + return value + } + return Object.fromEntries(Object.entries(value).map(([key, data]) => [key, ['token', 'sessiontoken'].includes(key.toLowerCase()) ? 'host-owned' : sanitize(data)])) + } + await page.exposeBinding('embeddingHost', async ({ frame }, peer, operation, data) => { + expect(frame).toBe(page.mainFrame()) + expect([0, 1]).toContain(peer) + expect(['create', 'sync', 'push', 'save', 'close']).toContain(operation) + operations.add(operation) + const session = sessions.get(peer) + const path = operation === 'create' ? `file/${file.id}/create` : `${session!.documentId}/${operation}` + const response = await page.request.fetch(new URL(`apps/text/session/${path}`, baseURL).href, { + method: operation === 'create' ? 'PUT' : 'POST', + data: { ...data, ...session }, + }) + expect(response.ok()).toBe(true) + const result = await response.json() + if (operation === 'create') { + sessions.set(peer, { documentId: result.document.id, sessionId: result.session.id, sessionToken: result.session.token, baseVersionEtag: result.document.baseVersionEtag }) + } + return sanitize(result) + }) + await page.goto('apps/files') + const root = await page.evaluate(() => (window as unknown as { OC: { appswebroots: { text: string } } }).OC.appswebroots.text) + await page.addScriptTag({ url: `${root}/js/text-editor.mjs`, type: 'module' }) + await page.evaluate(async (id) => { + window.embeddingInstances = [] + for (const peer of [0, 1]) { + const el = document.createElement('div') + el.id = `embedding-${peer}` + Object.assign(el.style, { position: 'fixed', top: '0', left: `${peer * 50}%`, width: '50%', height: '100%', zIndex: '10000', background: 'white' }) + document.body.append(el) + const sessionTransport: SessionTransport = { + async openContext() { + const data = await window.embeddingHost(peer, 'create', {}) + return { data, connection: { documentId: data.document.id, sessionId: data.session.id, sessionToken: data.session.token, baseVersionEtag: data.document.baseVersionEtag, filePath: '' } } + }, + async sync(_connection, data) { return { data: await window.embeddingHost(peer, 'sync', data) } }, + async push(_connection, data) { return { data: await window.embeddingHost(peer, 'push', data) } }, + async save(_connection, data) { return { data: await window.embeddingHost(peer, 'save', data) } }, + async close() { return window.embeddingHost(peer, 'close', {}) }, + } + window.embeddingInstances.push(await window.OCA.Text.createCollaborativeEditor({ + el, + context: { type: 'file', id }, + autofocus: false, + sessionTransport, + })) + } + }, file.id) + try { + for (const peer of [0, 1]) { + const editor = page.locator(`#embedding-${peer} .ProseMirror[contenteditable=true]`) + await expect(editor).toContainText('Shared text.', { timeout: 15_000 }) + await editor.click() + await editor.press('ControlOrMeta+End') + await editor.pressSequentially([' Client-α', ' Client-日本語'][peer]) + } + await expect.poll(() => page.evaluate(() => window.embeddingInstances.every((editor) => { + const markdown = editor.exportState().markdown + return markdown.includes('Client-α') && markdown.includes('Client-日本語') + })), { timeout: 15_000 }).toBe(true) + const states = await page.evaluate(() => Promise.all(window.embeddingInstances.map((editor) => editor.drain()))) + for (const state of states) { + const doc = new Y.Doc() + Y.applyUpdate(doc, Buffer.from(state.documentState, 'base64')) + expect([...Y.encodeStateVector(doc)]).toEqual([...Buffer.from(state.stateVector, 'base64')]) + expect(state.markdown).toContain('Client-α') + doc.destroy() + } + await expect(page.locator('#embedding-0 .ProseMirror')).toHaveAttribute('contenteditable', 'false') + expect([...operations]).toEqual(expect.arrayContaining(['create', 'sync', 'push'])) + } finally { + await page.evaluate(() => window.embeddingInstances.forEach((editor) => editor.destroy())) + } +}) diff --git a/src/TextEditorEmbed.ts b/src/TextEditorEmbed.ts index 049f74f74e9..adf6134a5e8 100644 --- a/src/TextEditorEmbed.ts +++ b/src/TextEditorEmbed.ts @@ -7,6 +7,7 @@ import type { EventHandler } from '@nextcloud/event-bus' import type { Editor } from '@tiptap/core' import type { Node } from '@tiptap/pm/model' import type { App, ComponentInstance, h, Reactive } from 'vue' +import type { EmbeddingState } from './types/EmbeddingState.ts' import type CollaborativeEditorApp from './views/CollaborativeEditorApp.vue' import type MarkdownContentEditorApp from './views/MarkdownContentEditorApp.vue' @@ -17,6 +18,8 @@ interface EditorComponent { editor: Editor setContent: (content: string, options?: { addToHistory: boolean | undefined }) => void save?: () => void + exportState?: () => EmbeddingState + drain?: () => Promise } type DataType = Reactive<{ @@ -50,6 +53,20 @@ export class TextEditorEmbed { this.#app.unmount() } + exportState(): EmbeddingState { + if (!this.#editorComponent.exportState) { + throw new Error('A collaborative editor is required') + } + return this.#editorComponent.exportState() + } + + drain(): Promise { + if (!this.#editorComponent.drain) { + throw new Error('A collaborative editor is required') + } + return this.#editorComponent.drain() + } + setContent(content: string) { // Update reactive prop for MarkdownContentEditor this.#data.content = content diff --git a/src/components/CollaborativeEditor.vue b/src/components/CollaborativeEditor.vue index fd805f18138..7d2d31c601b 100644 --- a/src/components/CollaborativeEditor.vue +++ b/src/components/CollaborativeEditor.vue @@ -86,7 +86,7 @@ import { Collaboration } from '@tiptap/extension-collaboration' import { useElementSize } from '@vueuse/core' import { defineAsyncComponent, defineComponent, inject, provide, ref, shallowRef, watch } from 'vue' import { Awareness } from 'y-protocols/awareness.js' -import { Doc, logUpdate } from 'yjs' +import { Doc, encodeStateVector, logUpdate } from 'yjs' import CollisionResolveDialog from './CollisionResolveDialog.vue' import ContentContainer from './Editor/ContentContainer.vue' import DocumentStatus from './Editor/DocumentStatus.vue' @@ -112,6 +112,7 @@ import { provideSyncService } from '../composables/useSyncService.ts' import { useSyntaxHighlighting } from '../composables/useSyntaxHighlighting.ts' import Autofocus from '../extensions/Autofocus.ts' import { CollaborationCaret } from '../extensions/index.js' +import { encodeArrayBuffer } from '../helpers/base64.ts' import { exposeForDebugging, removeFromDebugging } from '../helpers/debug.ts' import { logger } from '../helpers/logger.ts' import { setInitialYjsState } from '../helpers/setInitialYjsState.ts' @@ -257,6 +258,7 @@ export default defineComponent({ el.value.style.setProperty('--widget-full-width', `${maxWidth}px`) }) const ydoc = new Doc() + const embeddingDrained = ref(false) const awareness = new Awareness(ydoc) const { clearIndexedDb, @@ -314,7 +316,8 @@ export default defineComponent({ provideEditorHeadings(editor) - const { setEditable, updateUser } = useEditorMethods(editor) + const { setEditable: applyEditable, updateUser } = useEditorMethods(editor) + const setEditable = (value) => applyEditable(value && !embeddingDrained.value) const serialize = isRichEditor ? () => createMarkdownSerializer(editor.schema).serialize(editor.state.doc) @@ -350,6 +353,7 @@ export default defineComponent({ document, editor, editorReady, + embeddingDrained, el, getBaseVersionEtag, hasConnectionIssue, @@ -815,6 +819,23 @@ export default defineComponent({ this.saveService.save() }, + /** @return {import('../types/EmbeddingState.ts').EmbeddingState} */ + exportState() { + if (!this.contentLoaded || !this.connection) { + throw new Error('Text session is not ready') + } + const data = this.saveService.getSaveData() + return { format: 1, context: { type: this.context.type, id: this.context.id }, baseVersionEtag: this.connection.baseVersionEtag, version: data.version, markdown: data.autosaveContent, documentState: data.documentState, stateVector: encodeArrayBuffer(encodeStateVector(this.ydoc)) } + }, + + async drain() { + this.embeddingDrained = true + this.setEditable(false) + this.saveService.clearAutosave() + await this.syncService.drain() + return this.exportState() + }, + async save() { return await this.saveService.save() }, diff --git a/src/components/EditorReloader.vue b/src/components/EditorReloader.vue index 798e9d1981a..fc462e86bc1 100644 --- a/src/components/EditorReloader.vue +++ b/src/components/EditorReloader.vue @@ -39,6 +39,8 @@ watch(reloading, (val) => { const editorComponent = useTemplateRef('editor-component') as Readonly>> defineExpose({ + get exportState() { return editorComponent.value?.exportState }, + get drain() { return editorComponent.value?.drain }, get editor() { return editorComponent.value?.editor }, diff --git a/src/composables/useConnection.ts b/src/composables/useConnection.ts index cc704f20e59..bcc5ddb3c57 100644 --- a/src/composables/useConnection.ts +++ b/src/composables/useConnection.ts @@ -12,6 +12,7 @@ import type { Session } from '../types/Session.ts' import { inject, provide, shallowRef } from 'vue' import * as api from '../apis/connect.ts' +import { browserSessionTransport, sessionTransportKey } from '../services/SessionTransport.ts' export interface InitialData { document: Document @@ -52,6 +53,7 @@ export function provideConnection( getBaseVersionEtag: () => Promise, setBaseVersionEtag: (val: string) => Promise, ) { + const transport = (inject(sessionTransportKey, browserSessionTransport) ?? browserSessionTransport) const connection = shallowRef(undefined) const openData = shallowRef(undefined) const openConnection = async () => { @@ -60,7 +62,7 @@ export function provideConnection( const { connection: opened, data } = openInitialSession(props, baseVersionEtag) || await openShare(props, baseVersionEtag, guestName) - || await openContext(props, baseVersionEtag) + || await transport.openContext({ ...props.context, filePath: props.relativePath, baseVersionEtag }) await setBaseVersionEtag(data.document.baseVersionEtag) connection.value = opened openData.value = data @@ -153,25 +155,3 @@ async function openShare( }) } } - -/** - * Get the connection and additional data from the initial session if available. - * - * @param props Props of the editor component - * @param props.context of the document (i.e. type 'file' and id of the file) - * @param props.relativePath Relative path to the file. - * @param baseVersionEtag Etag from the last editing session. - */ -async function openContext( - props: { - context: Context - relativePath: string - }, - baseVersionEtag: string | undefined, -) { - return api.openContext({ - ...props.context, - filePath: props.relativePath, - baseVersionEtag, - }) -} diff --git a/src/composables/useIndexedDbProvider.ts b/src/composables/useIndexedDbProvider.ts index fb0fa8c11f7..6db57de6cc6 100644 --- a/src/composables/useIndexedDbProvider.ts +++ b/src/composables/useIndexedDbProvider.ts @@ -6,9 +6,10 @@ import type { Doc } from 'yjs' import type { Context } from '../types/Context.ts' -import { readonly, ref } from 'vue' +import { inject, readonly, ref } from 'vue' import { IndexeddbPersistence } from 'y-indexeddb' import { logger } from '../helpers/logger.js' +import { sessionTransportKey } from '../services/SessionTransport.ts' /** * Initialize a indexed db provider for the given ydoc @@ -23,6 +24,25 @@ export function useIndexedDbProvider( }, ydoc: Doc, ) { + if (inject(sessionTransportKey, undefined)) { + // Host transports own account-scoped persistence and recovery. + const dirty = ref(false) + let base: string | undefined + return { + dirty: readonly(dirty), + whenSynced: Promise.resolve(), + getBaseVersionEtag: async () => base, + setBaseVersionEtag: async (value: string) => { + base = value + return base + }, + setDirty: async (value: boolean) => { dirty.value = value }, + clearIndexedDb: async () => { + base = undefined + dirty.value = false + }, + } + } const name = `text-${props.context.type}-${props.context.id}` const indexedDbProvider = new IndexeddbPersistence(name, ydoc) const dirty = ref(false) @@ -73,7 +93,7 @@ export function useIndexedDbProvider( logger.debug('IndexedDB already destroyed, skipping setBaseVersionEtag') return Promise.resolve(undefined) } - return indexedDbProvider.set('baseVersionEtag', val) + return indexedDbProvider.set('baseVersionEtag', val).then(() => val) } /** diff --git a/src/composables/useSaveService.ts b/src/composables/useSaveService.ts index 8583a830753..6b6d1cd2c9b 100644 --- a/src/composables/useSaveService.ts +++ b/src/composables/useSaveService.ts @@ -15,6 +15,7 @@ import type { Document } from '../types/Document.ts' import { computed, inject, onUnmounted, provide, ref, watch } from 'vue' import { getDocumentState } from '../helpers/yjs.ts' import { SaveService } from '../services/SaveService.ts' +import { browserSessionTransport, sessionTransportKey } from '../services/SessionTransport.ts' const saveServiceKey = Symbol('text:save') as InjectionKey @@ -53,6 +54,7 @@ export function provideSaveService( connection, getSaveData, pushChanges: () => syncService.sendRemainingSteps(), + transport: inject(sessionTransportKey, browserSessionTransport) ?? browserSessionTransport, }) const autosaveOnUpdate = ({ transaction }: { transaction: Transaction }) => { diff --git a/src/composables/useSyncService.ts b/src/composables/useSyncService.ts index 1743f1cdbb1..e6de25ce78c 100644 --- a/src/composables/useSyncService.ts +++ b/src/composables/useSyncService.ts @@ -8,6 +8,7 @@ import type { Connection } from '../types/Connection.ts' import type { InitialData } from './useConnection.ts' import { inject, provide } from 'vue' +import { browserSessionTransport, sessionTransportKey } from '../services/SessionTransport.ts' import { SyncService } from '../services/SyncService.ts' const syncServiceKey = Symbol('text:sync') as InjectionKey @@ -25,6 +26,7 @@ export function provideSyncService( const syncService = new SyncService({ connection, openConnection, + transport: (inject(sessionTransportKey, browserSessionTransport) ?? browserSessionTransport), }) provide(syncServiceKey, syncService) diff --git a/src/createEditor.ts b/src/createEditor.ts index d966b07d6a3..90e89f5b9f7 100644 --- a/src/createEditor.ts +++ b/src/createEditor.ts @@ -5,6 +5,7 @@ import type { EventHandler } from '@nextcloud/event-bus' import type { App } from 'vue' +import type { SessionTransport } from './services/SessionTransport.ts' import type { TextEditorEmbed } from './TextEditorEmbed.ts' import type { Context } from './types/Context.ts' @@ -19,6 +20,7 @@ import { import { ACTION_ATTACHMENT_PROMPT } from './components/Editor/MediaHandler.provider.js' import { OPEN_LINK_HANDLER } from './composables/useOpenLinkHandler.ts' import { openLink } from './helpers/links.js' +import { sessionTransportKey } from './services/SessionTransport.ts' import { TextEditorEmbedBuilder } from './TextEditorEmbed.ts' interface ReadonlyBar { @@ -27,6 +29,8 @@ interface ReadonlyBar { } interface CollaborativeEditorOptions { + /** Host transport; persistence is in memory when supplied. */ + sessionTransport?: SessionTransport /** * Element to render the editor to */ @@ -119,6 +123,9 @@ export async function createEditor(options: EditorOptions) { * @param options for the editor */ export async function createCollaborativeEditor(options: CollaborativeEditorOptions) { + if (options.sessionTransport && options.shareToken) { + throw new Error('Host transports currently support authenticated contexts only') + } const { default: CollaborativeEditorApp } = await import('./views/CollaborativeEditorApp.vue') const data = reactiveData(options) const app = createApp( @@ -138,6 +145,9 @@ export async function createCollaborativeEditor(options: CollaborativeEditorOpti 'onUpdate:content': options.onUpdate ?? (() => { }), }, ) + if (options.sessionTransport) { + app.provide(sessionTransportKey, options.sessionTransport) + } app.provide(EDITOR_UPLOAD, true) provideHooks(app, options) return createTextEditorEmbed(app, data, options) diff --git a/src/services/Outbox.ts b/src/services/Outbox.ts index 3bab6151a62..29dc286a867 100644 --- a/src/services/Outbox.ts +++ b/src/services/Outbox.ts @@ -63,6 +63,10 @@ export default class Outbox { : {} } + get hasPending(): boolean { + return !!(this.#syncUpdate || this.#syncQuery || this.#awarenessUpdate) + } + get hasUpdate(): boolean { return !!this.#syncUpdate } diff --git a/src/services/PollingBackend.ts b/src/services/PollingBackend.ts index 271bc145681..d4a7f115527 100644 --- a/src/services/PollingBackend.ts +++ b/src/services/PollingBackend.ts @@ -11,7 +11,6 @@ import type { Step } from '../types/Step.ts' import type { EventTypes } from './NotifyService.ts' import type { SyncService } from './SyncService.js' -import { sync } from '../apis/sync.ts' import { logger } from '../helpers/logger.js' import { ERROR_TYPE } from '../types/ErrorType.ts' import getNotifyBus from './NotifyService.ts' @@ -135,7 +134,7 @@ class PollingBackend { logger.debug('[PollingBackend] Fetching steps', { version: this.#syncService.version, }) - await sync(this.#connection, { + await this.#syncService.transport.sync(this.#connection, { version: this.#syncService.version, }).then(this._handleResponse.bind(this), this._handleError.bind(this)) this.#lastPoll = Date.now() diff --git a/src/services/SaveService.ts b/src/services/SaveService.ts index 0b50e894e49..071bc925c6b 100644 --- a/src/services/SaveService.ts +++ b/src/services/SaveService.ts @@ -7,13 +7,15 @@ import type { ShallowRef } from 'vue' import type { SaveData } from '../apis/save.ts' import type { Connection } from '../types/Connection.ts' import type { Document } from '../types/Document.ts' +import type { SessionTransport } from './SessionTransport.ts' import { showError } from '@nextcloud/dialogs' import debounce from 'debounce' import mitt from 'mitt' -import { save, saveViaSendBeacon } from '../apis/save.ts' +import { saveViaSendBeacon } from '../apis/save.ts' import { logger } from '../helpers/logger.js' import { ERROR_TYPE } from '../types/ErrorType.ts' +import { browserSessionTransport } from './SessionTransport.ts' // Time constants in seconds: // Only autosave after 1 second typing breaks @@ -40,16 +42,20 @@ class SaveService { pushChanges autosave clear + readonly transport: SessionTransport constructor({ connection, getSaveData, pushChanges = async () => {}, + transport = browserSessionTransport, }: { connection: ShallowRef getSaveData: () => SaveData pushChanges?: () => Promise + transport?: SessionTransport }) { + this.transport = transport this.connection = connection this.getSaveData = getSaveData this.pushChanges = pushChanges @@ -77,7 +83,7 @@ class SaveService { const data = this.getSaveData() try { this.lastSaveAttempt = Date.now() - const response = await save(this.connection.value, { + const response = await this.transport.save(this.connection.value, { ...data, force, manualSave, @@ -125,6 +131,9 @@ class SaveService { } saveViaSendBeacon() { + if (this.transport !== browserSessionTransport) { + return false + } if (!this.connection.value) { return } diff --git a/src/services/SessionTransport.ts b/src/services/SessionTransport.ts new file mode 100644 index 00000000000..a6377f47fc8 --- /dev/null +++ b/src/services/SessionTransport.ts @@ -0,0 +1,22 @@ +/** + * SPDX-FileCopyrightText: 2026 Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +import type { InjectionKey } from 'vue' + +import { close, openContext } from '../apis/connect.ts' +import { save } from '../apis/save.ts' +import { push, sync } from '../apis/sync.ts' + +/** Per-editor transport. Hosts must bind requests to their account and file. */ +export interface SessionTransport { + openContext: typeof openContext + sync: typeof sync + push: typeof push + save: typeof save + close: typeof close +} + +export const browserSessionTransport: SessionTransport = { openContext, sync, push, save, close } +export const sessionTransportKey = Symbol('text:session-transport') as InjectionKey diff --git a/src/services/SyncService.ts b/src/services/SyncService.ts index 69e3d952007..7a092862948 100644 --- a/src/services/SyncService.ts +++ b/src/services/SyncService.ts @@ -10,16 +10,16 @@ import type { Document } from '../types/Document.ts' import type { ErrorType } from '../types/ErrorType.ts' import type { GuestSession, Session, UserSession } from '../types/Session.ts' import type { Step } from '../types/Step.ts' +import type { SessionTransport } from './SessionTransport.ts' import mitt from 'mitt' -import { close } from '../apis/connect.ts' -import { push } from '../apis/sync.ts' import { logger } from '../helpers/logger.js' import { awarenessSteps } from '../helpers/steps.ts' import { documentStateToStep } from '../helpers/yjs.ts' import { ERROR_TYPE } from '../types/ErrorType.ts' import Outbox from './Outbox.ts' import PollingBackend from './PollingBackend.ts' +import { browserSessionTransport } from './SessionTransport.ts' /** * Timeout after which the editor will consider a document without changes being synced as idle @@ -96,14 +96,18 @@ class SyncService { #openConnection: () => Promise #lastStepPush = Date.now() #pushing?: Promise + readonly transport: SessionTransport constructor({ connection, openConnection, + transport = browserSessionTransport, }: { connection: ShallowRef openConnection: () => Promise + transport?: SessionTransport }) { + this.transport = transport this.connection = connection this.#openConnection = openConnection } @@ -196,6 +200,21 @@ class SyncService { return this.#pushing } + async drain() { + clearInterval(this.#sendIntervalId) + this.#sendIntervalId = undefined + for (let pass = 0; pass < 32; pass++) { + if (!this.hasActiveConnection()) { + throw new Error('No active Text session') + } + if (!this.#pushing && !this.#outbox.hasPending) { + return this.version + } + await (this.#pushing ?? this.sendStepsNow()) + } + throw new Error('Text updates did not drain') + } + async #push() { clearInterval(this.#sendIntervalId) this.#sendIntervalId = undefined @@ -204,7 +223,7 @@ class SyncService { return } const sendable = this.#outbox.getDataToSend() - return push(this.connection, { + return this.transport.push(this.connection, { version: this.version, ...sendable, }) @@ -316,7 +335,7 @@ class SyncService { this.bus.emit('close') if (activeConnection) { - await close(activeConnection) + await this.transport.close(activeConnection) // Log and ignore possible network issues. .catch((e) => { logger.info('Failed to close connection.', { e }) diff --git a/src/tests/services/EmbeddingIsolation.spec.ts b/src/tests/services/EmbeddingIsolation.spec.ts new file mode 100644 index 00000000000..360d062d5cf --- /dev/null +++ b/src/tests/services/EmbeddingIsolation.spec.ts @@ -0,0 +1,57 @@ +/** + * SPDX-FileCopyrightText: 2026 Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +import type { SessionTransport } from '../../services/SessionTransport.ts' + +import { describe, expect, it, vi } from 'vitest' +import { createApp, defineComponent } from 'vue' +import { IndexeddbPersistence } from 'y-indexeddb' +import { Doc } from 'yjs' +import { provideConnection } from '../../composables/useConnection.ts' +import { useIndexedDbProvider } from '../../composables/useIndexedDbProvider.ts' +import { sessionTransportKey } from '../../services/SessionTransport.ts' + +vi.mock('y-indexeddb', () => ({ IndexeddbPersistence: vi.fn() })) + +describe('embedding instance isolation', () => { + it('keeps transports and in-memory bases separate for matching file IDs', async () => { + const mounts = ['account-a', 'account-b'].map((base) => { + const transport = { openContext: vi.fn(async () => ({ + connection: { documentId: base, sessionId: 7, sessionToken: 'host-owned', baseVersionEtag: base, filePath: '' }, + data: { document: { baseVersionEtag: base } }, + })) } as unknown as SessionTransport + let binding!: ReturnType + let persistence!: ReturnType + const doc = new Doc() + const app = createApp(defineComponent({ + setup() { + const props = { context: { type: 'file', id: 42 }, relativePath: '' } + persistence = useIndexedDbProvider(props, doc) + binding = provideConnection(props, persistence.getBaseVersionEtag, persistence.setBaseVersionEtag) + return () => null + }, + })) + app.provide(sessionTransportKey, transport) + app.mount(document.createElement('div')) + return { app, doc, binding, persistence, transport } + }) + try { + await Promise.all(mounts.map((mount) => mount.binding.openConnection())) + expect(mounts[0].binding.connection.value?.documentId).toBe('account-a') + expect(mounts[1].binding.connection.value?.documentId).toBe('account-b') + expect(await mounts[0].persistence.getBaseVersionEtag()).toBe('account-a') + expect(await mounts[1].persistence.getBaseVersionEtag()).toBe('account-b') + for (const mount of mounts) { + expect(mount.transport.openContext).toHaveBeenCalledOnce() + } + expect(IndexeddbPersistence).not.toHaveBeenCalled() + } finally { + for (const mount of mounts) { + mount.app.unmount() + mount.doc.destroy() + } + } + }) +}) diff --git a/src/tests/services/EmbeddingTransport.spec.ts b/src/tests/services/EmbeddingTransport.spec.ts new file mode 100644 index 00000000000..b03e51f308d --- /dev/null +++ b/src/tests/services/EmbeddingTransport.spec.ts @@ -0,0 +1,51 @@ +/** + * SPDX-FileCopyrightText: 2026 Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +import type { SessionTransport } from '../../services/SessionTransport.ts' + +import { describe, expect, it, vi } from 'vitest' +import { shallowRef } from 'vue' +import { SaveService } from '../../services/SaveService.ts' +import { SyncService } from '../../services/SyncService.ts' + +const connection = { documentId: 'doc', sessionId: 7, sessionToken: 'host-owned', baseVersionEtag: 'base', filePath: '' } +function transport() { + return { openContext: vi.fn(), sync: vi.fn(), push: vi.fn(async () => ({ data: { steps: [] } })), save: vi.fn(async () => ({ data: { document: { lastSavedVersion: 3 } } })), close: vi.fn(async () => ({})) } +} + +describe('per-editor session transport', () => { + it('waits for an in-flight push and drains work queued during that push', async () => { + const host = transport() + let resolve!: () => void + host.push.mockImplementationOnce(() => new Promise((done) => { + resolve = () => done({ + data: { + steps: [], + }, + }) + })) + const service = new SyncService({ connection: shallowRef(connection), openConnection: vi.fn(), transport: host as unknown as SessionTransport }) + service.sendStep(new Uint8Array([0, 1, 0])) + const sending = service.sendStepsNow() + service.sendStep(new Uint8Array([0, 1, 1])) + const drained = service.drain() + expect(service.sendStepsNow()).toBe(sending) + expect(host.push).toHaveBeenCalledTimes(1) + resolve() + await drained + expect(host.push).toHaveBeenCalledTimes(2) + await service.close() + }) + it('uses the supplied save transport and never falls back to sendBeacon', async () => { + const host = transport() + const beacon = vi.fn() + Object.defineProperty(navigator, 'sendBeacon', { value: beacon, configurable: true }) + const service = new SaveService({ connection: shallowRef(connection), transport: host as unknown as SessionTransport, getSaveData: () => ({ version: 3, autosaveContent: 'Text', documentState: 'AA==' }) }) + expect(await service.save()).toBe(true) + expect(host.save).toHaveBeenCalledOnce() + expect(service.saveViaSendBeacon()).toBe(false) + expect(beacon).not.toHaveBeenCalled() + }) +}) diff --git a/src/types/EmbeddingState.ts b/src/types/EmbeddingState.ts new file mode 100644 index 00000000000..0e90af7f4ad --- /dev/null +++ b/src/types/EmbeddingState.ts @@ -0,0 +1,17 @@ +/** + * SPDX-FileCopyrightText: 2026 Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +import type { Context } from './Context.ts' + +/** A full Yjs update, not a framed wire step. Host credentials are excluded. */ +export interface EmbeddingState { + format: 1 + context: Context + baseVersionEtag: string + version: number + markdown: string + documentState: string + stateVector: string +} From 4ff4060878454074f0332e7d97032eac832387ed Mon Sep 17 00:00:00 2001 From: Julius Knorr Date: Wed, 11 Nov 2026 14:32:04 +0100 Subject: [PATCH 3/3] fix(embedding): preserve recovery exports and identify local edits Assisted-by: Codex:gpt-6-astra Signed-off-by: Julius Knorr --- docs/native-embedding.md | 6 ++ src/components/CollaborativeEditor.vue | 12 ++-- src/createEditor.ts | 2 +- .../components/EmbeddingRecovery.spec.ts | 69 +++++++++++++++++++ src/views/CollaborativeEditorApp.vue | 4 +- 5 files changed, 86 insertions(+), 7 deletions(-) create mode 100644 src/tests/components/EmbeddingRecovery.spec.ts diff --git a/docs/native-embedding.md b/docs/native-embedding.md index 4fb23f0dbb8..3ee362e68c6 100644 --- a/docs/native-embedding.md +++ b/docs/native-embedding.md @@ -67,6 +67,12 @@ The snapshot contains a full base64 Yjs update, state vector, Markdown, version, context and collaboration base ETag, without session credentials. `drain()` freezes user input, waits for queued/in-flight provider updates, and returns a snapshot; failures reject. It does not persist, save, or close the session. +After session rejection, `exportState()` still returns recovery state with the +original base ETag; it does not require an active connection. + +The existing `onUpdate({ markdown, local })` callback reports document changes, +including toolbar and programmatic edits. `local` distinguishes local edits +(including undo/redo) from remote updates and initial Yjs content. The host must persist recovery state, control file-save requests, verify the saved version, close through its own transport, and fetch canonical DAV Markdown/ETag diff --git a/src/components/CollaborativeEditor.vue b/src/components/CollaborativeEditor.vue index 7d2d31c601b..cbe3a03f009 100644 --- a/src/components/CollaborativeEditor.vue +++ b/src/components/CollaborativeEditor.vue @@ -83,6 +83,7 @@ import { File } from '@nextcloud/files' import { loadState } from '@nextcloud/initial-state' import { generateRemoteUrl } from '@nextcloud/router' import { Collaboration } from '@tiptap/extension-collaboration' +import { ySyncPluginKey } from '@tiptap/y-tiptap' import { useElementSize } from '@vueuse/core' import { defineAsyncComponent, defineComponent, inject, provide, ref, shallowRef, watch } from 'vue' import { Awareness } from 'y-protocols/awareness.js' @@ -285,7 +286,7 @@ export default defineComponent({ isRichEditor, props, ) - const { connection, openConnection } = provideConnection( + const { connection, openConnection, openData } = provideConnection( props, getBaseVersionEtag, setBaseVersionEtag, @@ -349,6 +350,7 @@ export default defineComponent({ awareness, clearIndexedDb, connection, + openData, dirty, document, editor, @@ -689,15 +691,17 @@ export default defineComponent({ }) }, - onUpdate({ editor }) { + onUpdate({ editor, transaction }) { if (window.OCA.Text.logEditorUpdates) { this.debugContent(editor) } const serialize = this.serialize + const origin = transaction.getMeta(ySyncPluginKey) this.$emit('update:content', { get markdown() { return serialize() }, + local: transaction.docChanged && (!origin?.isChangeOrigin || !!origin?.isUndoRedoOperation), }) }, @@ -821,11 +825,11 @@ export default defineComponent({ /** @return {import('../types/EmbeddingState.ts').EmbeddingState} */ exportState() { - if (!this.contentLoaded || !this.connection) { + if (!this.contentLoaded || !this.openData) { throw new Error('Text session is not ready') } const data = this.saveService.getSaveData() - return { format: 1, context: { type: this.context.type, id: this.context.id }, baseVersionEtag: this.connection.baseVersionEtag, version: data.version, markdown: data.autosaveContent, documentState: data.documentState, stateVector: encodeArrayBuffer(encodeStateVector(this.ydoc)) } + return { format: 1, context: { type: this.context.type, id: this.context.id }, baseVersionEtag: this.openData.document.baseVersionEtag, version: data.version, markdown: data.autosaveContent, documentState: data.documentState, stateVector: encodeArrayBuffer(encodeStateVector(this.ydoc)) } }, async drain() { diff --git a/src/createEditor.ts b/src/createEditor.ts index 90e89f5b9f7..8ad1f010e83 100644 --- a/src/createEditor.ts +++ b/src/createEditor.ts @@ -46,7 +46,7 @@ interface CollaborativeEditorOptions { menubarLinkCustomAction?: () => void onCreate?: ({ markdown }: { markdown: string }) => void onLoaded?: () => void - onUpdate?: ({ markdown }: { markdown: string }) => void + onUpdate?: ({ markdown, local }: { markdown: string, local?: boolean }) => void onTocToggle?: EventHandler onOutlineToggle?: EventHandler // deprecated, use `onTocToggle` onTocPin?: EventHandler<{ fileId: number, keep: boolean }> diff --git a/src/tests/components/EmbeddingRecovery.spec.ts b/src/tests/components/EmbeddingRecovery.spec.ts new file mode 100644 index 00000000000..d5735669c32 --- /dev/null +++ b/src/tests/components/EmbeddingRecovery.spec.ts @@ -0,0 +1,69 @@ +/** + * SPDX-FileCopyrightText: 2026 Nextcloud contributors + * SPDX-License-Identifier: AGPL-3.0-or-later + */ + +import type { SessionTransport } from '../../services/SessionTransport.ts' + +import { ySyncPluginKey } from '@tiptap/y-tiptap' +import { describe, expect, it, vi } from 'vitest' +import { shallowRef } from 'vue' +import * as Y from 'yjs' +import CollaborativeEditor from '../../components/CollaborativeEditor.vue' +import { encodeArrayBuffer } from '../../helpers/base64.ts' +import { SyncService } from '../../services/SyncService.ts' + +const methods = CollaborativeEditor.methods! + +describe('embedding recovery', () => { + it('exports unsynced state with its original base after a forbidden push', async () => { + const connection = shallowRef({ documentId: 'doc', sessionId: 7, sessionToken: 'secret', baseVersionEtag: 'original-base', filePath: '' }) + const transport = { push: vi.fn().mockRejectedValue({ response: { status: 403 } }) } as unknown as SessionTransport + const service = new SyncService({ connection, openConnection: vi.fn(), transport }) + const ydoc = new Y.Doc() + ydoc.getText('recovery').insert(0, 'Unsynced edits') + const context = { + contentLoaded: true, + connection: connection.value, + openData: { document: { baseVersionEtag: 'original-base' } }, + context: { type: 'file', id: 42 }, + ydoc, + saveService: { getSaveData: () => ({ version: service.version, autosaveContent: 'Unsynced edits', documentState: encodeArrayBuffer(Y.encodeStateAsUpdate(ydoc)) }) }, + } + try { + service.sendStep(new Uint8Array([0, 1, 0])) + await expect(service.sendStepsNow()).rejects.toThrow('Failed to apply steps') + expect(connection.value).toBeUndefined() + context.connection = connection.value + const state = methods.exportState.call(context) + expect(state.baseVersionEtag).toBe('original-base') + expect(state.markdown).toBe('Unsynced edits') + const restored = new Y.Doc() + Y.applyUpdate(restored, Buffer.from(state.documentState, 'base64')) + expect(restored.getText('recovery').toString()).toBe('Unsynced edits') + expect(encodeArrayBuffer(Y.encodeStateVector(restored))).toBe(state.stateVector) + expect(JSON.stringify(state)).not.toContain('secret') + restored.destroy() + } finally { + ydoc.destroy() + } + }) + + it('rejects export before the document has loaded', () => { + expect(() => methods.exportState.call({ contentLoaded: false })).toThrow('not ready') + }) + + it.each([ + [undefined, true, true], + [undefined, false, false], + [{ isChangeOrigin: true }, true, false], + [{ isChangeOrigin: true, isUndoRedoOperation: true }, true, true], + ])('reports whether an editor update is local (%j)', (origin, docChanged, local) => { + const emit = vi.fn() + methods.onUpdate.call({ serialize: () => '**Formatted**', $emit: emit }, { + editor: {}, + transaction: { docChanged, getMeta: (key: unknown) => key === ySyncPluginKey ? origin : undefined }, + }) + expect(emit).toHaveBeenCalledWith('update:content', { markdown: '**Formatted**', local }) + }) +}) diff --git a/src/views/CollaborativeEditorApp.vue b/src/views/CollaborativeEditorApp.vue index c686b2d3f98..4661f2cf9b9 100644 --- a/src/views/CollaborativeEditorApp.vue +++ b/src/views/CollaborativeEditorApp.vue @@ -15,7 +15,7 @@ :autofocus @ready="emit('ready')" @create:content="(c: { markdown: string }) => emit('create:content', c)" - @update:content="(c: { markdown: string }) => emit('update:content', c)"> + @update:content="(c: { markdown: string, local: boolean }) => emit('update:content', c)"> @@ -42,7 +42,7 @@ defineProps<{ const emit = defineEmits<{ (e: 'ready'): void (e: 'create:content', content: { markdown: string }): void - (e: 'update:content', content: { markdown: string }): void + (e: 'update:content', content: { markdown: string, local: boolean }): void }>() const editorContainer = useTemplateRef('editor-container') as Readonly>>