@docstack/pouchdb-adapter-googledrive 0.0.9 → 0.1.0

package/docs/REPLICATION_ISSUE.md

@@ -1,63 +0,0 @@
-# Root Cause Analysis: Replication FROM Google Drive Issues
-
-After extensive debugging with a live emulation test suite, multiple critical issues were identified in the `_changes` and `notifyListeners` implementations.
-
-## 1. Missing `seq` Property in Notifications (CRITICAL)
-**Location**: `src/drive.ts` -> `notifyListeners()`
-
-**Problem**: 
-The `notifyListeners` method was emitting change objects that included `id`, `rev`, and `deleted`, but omitted the `seq` (sequence number). 
-
-**Consequence**: 
-PouchDB's replication engine uses the `seq` to track checkpoints. If a change arrives without a `seq`, PouchDB silently ignores it or fails to update its "since" pointer, meaning the replication appears to "detect" a change but never actually processes the document.
-
-**Fix**: 
-Updated the notification object to include the correct sequence number from the index.
-
----
-
-## 2. Infinite Reconnect Loop in Live Changes
-**Location**: `src/adapter.ts` -> `_changes()`
-
-**Problem**: 
-An initial "fix" (based on standard CouchDB behavior) suggested calling `opts.complete()` at the end of the initial changes batch, even for live feeds. 
-
-**Consequence**: 
-In PouchDB, calling `complete()` on a **live** stream signals that the stream has ended gracefully. Because the replication is set to `live: true`, PouchDB interprets this as a connection drop and immediately restarts the changes feed. This created an infinite loop of:
-`Connect -> Fetch Batch -> Call Complete -> Disconnect -> Reconnect`
-This loop caused high CPU usage and eventually a "JavaScript heap out of memory" crash.
-
-**Fix**: 
-Restricted `opts.complete()` to only be called if `!opts.live`.
-
----
-
-## 3. System Document Leakage (`_local/`)
-**Location**: `src/adapter.ts` -> `_changes()`
-
-**Problem**: 
-PouchDB uses local documents (IDs starting with `_local/`) to store replication checkpoints. Our adapter was incorrectly including these internal documents in the `_changes` feed results.
-
-**Consequence**: 
-When the remote side (Google Drive) reported a change to a `_local/` document, the local PouchDB tried to fetch it to replicate it. However, local documents are non-replicable and often missing from the full document fetch logic, leading to `not_found: missing` errors that crashed the replication process.
-
-**Fix**: 
-Added a filter to both the initial batch and the live listener to ignore any document ID starting with `_local/`.
-
----
-
-## 4. Inefficient Polling & Redundant `load()` Calls
-**Location**: `src/drive.ts` -> `startPolling()` / `load()`
-
-**Problem**: 
-The polling mechanism was frequently triggering `load()`, which cleared the entire `processedLogIds` cache and re-downloaded all change logs from Google Drive. Additionally, `load()` was being called on every conflict retry without checking if the metadata had actually changed.
-
-**Fix**: 
-1. Implemented **ETag-based change detection** in polling.
-2. Added an **ETag check at the start of `load()`** to skip processing if the metadata on the server haven't changed since the last load.
-3. Updated `tryAppendChanges` to proactively call `notifyListeners()` for local writes, reducing reliance on the next polling tick for local UI updates.
-
----
-
-## Summary of Results
-With these fixes applied, bidirectional replication is now stable and efficient. The "Out of Memory" crashes have been resolved, and changes from Google Drive are correctly detected and propagated to the local database within the specified polling interval.

package/emulation-test.log

@@ -1,163 +0,0 @@
-
-> @docstack/pouchdb-adapter-googledrive@0.0.7 test
-> jest tests/emulation.test.ts
-
-  console.log
-    Test Drive Server running on port 46325
-
-      at Server.<anonymous> (src/test-utils/server.ts:47:25)
-
-  console.log
-    Server started on port 46325
-
-      at Object.<anonymous> (tests/emulation.test.ts:22:17)
-
-  console.log
-    GET /drive/v3/files
-
-      at src/test-utils/server.ts:23:21
-
-  console.log
-    Self-test fetch status: 200
-
-      at Object.<anonymous> (tests/emulation.test.ts:25:21)
-
-  console.log
-    Initializing DriveHandler with options: {
-      adapter: 'googledrive',
-      testMode: true,
-      testServerUrl: 'http://127.0.0.1:46325',
-      accessToken: 'mock-token',
-      deterministic_revs: true,
-      name: 'testdb'
-    }
-
-      at PouchDB.GoogleDrivePouch (src/adapter.ts:42:17)
-
-  console.log
-    [googledrive-drive] [testdb] Loading database, options {
-      options: {
-        adapter: 'googledrive',
-        testMode: true,
-        testServerUrl: 'http://127.0.0.1:46325',
-        accessToken: 'mock-token',
-        deterministic_revs: true,
-        name: 'testdb'
-      }
-    }
-
-      at DriveHandler.log (src/drive.ts:68:17)
-
-  console.log
-    GET /drive/v3/files?q=name%20%3D%20%27testdb%27%20and%20mimeType%20%3D%20%27application%2Fvnd.google-apps.folder%27%20and%20trashed%20%3D%20false&fields=files%28id%2Cname%2CmimeType%2Cparents%2CmodifiedTime%29
-
-      at src/test-utils/server.ts:23:21
-
-  console.log
-    POST /drive/v3/files?fields=id,modifiedTime
-
-      at src/test-utils/server.ts:23:21
-
-  console.log
-    [googledrive-drive] [testdb] Retrieved folder { folderId: 'r8bf1gdzs2' }
-
-      at DriveHandler.log (src/drive.ts:68:17)
-
-  console.log
-    GET /drive/v3/files?q=name%20%3D%20%27_meta.json%27%20and%20%27r8bf1gdzs2%27%20in%20parents%20and%20trashed%20%3D%20false&fields=files%28id%2Cname%2CmimeType%2Cparents%2CmodifiedTime%29
-
-      at src/test-utils/server.ts:23:21
-
-  console.log
-    [googledrive-drive] [testdb] Meta file not found, creating new
-
-      at DriveHandler.log (src/drive.ts:68:17)
-
-  console.log
-    GET /drive/v3/files?q=name%20%3D%20%27_meta.json%27%20and%20%27r8bf1gdzs2%27%20in%20parents%20and%20trashed%20%3D%20false&fields=files%28id%2Cname%2CmimeType%2Cparents%2CmodifiedTime%29
-
-      at src/test-utils/server.ts:23:21
-
-  console.log
-    POST /upload/drive/v3/files?uploadType=multipart&fields=id,modifiedTime
-
-      at src/test-utils/server.ts:23:21
-
-  console.log
-    [googledrive-drive] [testdb] Replaying change logs
-
-      at DriveHandler.log (src/drive.ts:68:17)
-
-  console.log
-    [googledrive-drive] [testdb] Polling disabled (no interval provided)
-
-      at DriveHandler.log (src/drive.ts:68:17)
-
-  console.log
-    POST /upload/drive/v3/files?uploadType=multipart&fields=id,modifiedTime
-
-      at src/test-utils/server.ts:23:21
-
-  console.log
-    GET /drive/v3/files?q=name%20%3D%20%27_meta.json%27%20and%20%27r8bf1gdzs2%27%20in%20parents%20and%20trashed%20%3D%20false&fields=files%28id%2Cname%2CmimeType%2Cparents%2CmodifiedTime%29
-
-      at src/test-utils/server.ts:23:21
-
-  console.log
-    PATCH /upload/drive/v3/files/u4t2406y2fh?uploadType=media&fields=id,modifiedTime
-
-      at src/test-utils/server.ts:23:21
-
-  console.log
-    Initializing DriveHandler with options: {
-      adapter: 'googledrive',
-      testMode: true,
-      testServerUrl: 'http://127.0.0.1:46325',
-      accessToken: 'mock-token',
-      deterministic_revs: true,
-      name: 'remote'
-    }
-
-      at PouchDB.GoogleDrivePouch (src/adapter.ts:42:17)
-
-  console.log
-    [googledrive-drive] [remote] Loading database, options {
-      options: {
-        adapter: 'googledrive',
-        testMode: true,
-        testServerUrl: 'http://127.0.0.1:46325',
-        accessToken: 'mock-token',
-        deterministic_revs: true,
-        name: 'remote'
-      }
-    }
-
-      at DriveHandler.log (src/drive.ts:68:17)
-
-PASS tests/emulation.test.ts
-  Google Drive Emulation Integration
-    ✓ should create database and write documents (139 ms)
-    ✓ should replicate (11 ms)
-
-Test Suites: 1 passed, 1 total
-Tests:       2 passed, 2 total
-Snapshots:   0 total
-Time:        4.057 s
-Ran all test suites matching tests/emulation.test.ts.
-  console.error
-    Failed to load database [Error: Network Error: fetch failed (GET http://127.0.0.1:46325/drive/v3/files?q=name%20%3D%20%27remote%27%20and%20mimeType%20%3D%20%27application%2Fvnd.google-apps.folder%27%20and%20trashed%20%3D%20false&fields=files%28id%2Cname%2CmimeType%2Cparents%2CmodifiedTime%29)] {
-      code: 'network_error',
-      url: 'http://127.0.0.1:46325/drive/v3/files?q=name%20%3D%20%27remote%27%20and%20mimeType%20%3D%20%27application%2Fvnd.google-apps.folder%27%20and%20trashed%20%3D%20false&fields=files%28id%2Cname%2CmimeType%2Cparents%2CmodifiedTime%29',
-      method: 'GET'
-    }
-
-      208 |                 }
-      209 |             } catch (e) {
-    > 210 |                 console.error('Failed to load database', e);
-          |                         ^
-      211 |             } finally {
-      212 |                 this.loadingPromise = null;
-      213 |             }
-
-      at src/drive.ts:210:25
-

package/failing_test.log

@@ -1,31 +0,0 @@
-  ● Concurrency & Race Conditions › should handle race condition when two clients append simultaneously
-
-    expect(received).toBe(expected) // Object.is equality
-
-    Expected: 2
-    Received: 1
-
-      107 |         expect(doc1).toBeDefined();
-      108 |         expect(doc2).toBeDefined();
-    > 109 |         expect(driveHandler1.seq).toBe(2);
-          |                                   ^
-      110 |     });
-      111 |
-      112 |     it('should detect conflicting updates', async () => {
-
-      at Object.<anonymous> (tests/concurrency_mock.test.ts:109:35)
-
-  ● Concurrency & Race Conditions › should detect conflicting updates
-
-    expect(received).toBe(expected) // Object.is equality
-
-    Expected: 409
-    Received: undefined
-
-      122 |             throw new Error('Should have thrown conflict');
-      123 |         } catch (e: any) {
-    > 124 |             expect(e.status).toBe(409); // Conflict
-          |                              ^
-      125 |         }
-      126 |     });
-      127 | });