@fgv/ts-web-extras 5.1.0-1 → 5.1.0-10

package/dist/test/unit/httpTreeAccessors.test.js

@@ -27,6 +27,7 @@ function makeMockResponse(options) {
     return {
         ok,
         status,
+        statusText: ok ? 'OK' : `Error ${status}`,
         json: throwOnJson
             ? () => Promise.reject(new Error('JSON parse error'))
             : () => Promise.resolve(jsonValue),
@@ -595,65 +596,99 @@ describe('HttpTreeAccessors', () => {
             expect(result).toFailWith(/sync.*data\.json.*server error/i);
         });
         test('fails when PUT for a dirty file encounters a network error', async () => {
-            let callCount = 0;
-            const fetchImpl = (_url, _init) => {
-                callCount++;
-                if (callCount === 1) {
-                    return Promise.resolve(makeMockResponse({ ok: true, jsonValue: rootWithOneFile('data.json') }));
-                }
-                if (callCount === 2) {
-                    return Promise.resolve(makeMockResponse({ ok: true, jsonValue: fileResponse('/data.json', '{}') }));
-                }
-                return Promise.reject(new Error('PUT network error'));
-            };
-            const accessors = (await HttpTreeAccessors.fromHttp({
-                baseUrl: 'http://localhost:3000',
-                fetchImpl,
-                mutable: true
-            })).orThrow();
-            accessors.saveFileContents('/data.json', '"updated"').orThrow();
-            const result = await accessors.syncToDisk();
-            expect(result).toFailWith(/put network error/i);
+            jest.useFakeTimers();
+            try {
+                let callCount = 0;
+                const fetchImpl = (_url, _init) => {
+                    callCount++;
+                    if (callCount === 1) {
+                        return Promise.resolve(makeMockResponse({ ok: true, jsonValue: rootWithOneFile('data.json') }));
+                    }
+                    if (callCount === 2) {
+                        return Promise.resolve(makeMockResponse({ ok: true, jsonValue: fileResponse('/data.json', '{}') }));
+                    }
+                    return Promise.reject(new Error('PUT network error'));
+                };
+                const accessors = (await HttpTreeAccessors.fromHttp({
+                    baseUrl: 'http://localhost:3000',
+                    fetchImpl,
+                    mutable: true
+                })).orThrow();
+                accessors.saveFileContents('/data.json', '"updated"').orThrow();
+                const syncPromise = accessors.syncToDisk();
+                await jest.advanceTimersByTimeAsync(1500);
+                const result = await syncPromise;
+                expect(result).toFailWith(/put network error/i);
+            }
+            finally {
+                jest.useRealTimers();
+            }
         });
         test('fails when POST /sync returns a non-ok response', async () => {
-            const { fetchImpl } = makeMockFetch([
-                { ok: true, jsonValue: rootWithOneFile('data.json') },
-                { ok: true, jsonValue: fileResponse('/data.json', '{}') },
-                { ok: true, jsonValue: fileResponse('/data.json', '"v2"') },
-                { ok: false, status: 503, textValue: 'Service Unavailable' }
-            ]);
-            const accessors = (await HttpTreeAccessors.fromHttp({
-                baseUrl: 'http://localhost:3000',
-                fetchImpl,
-                mutable: true
-            })).orThrow();
-            accessors.saveFileContents('/data.json', '"v2"').orThrow();
-            const result = await accessors.syncToDisk();
-            expect(result).toFailWith(/service unavailable/i);
+            jest.useFakeTimers();
+            try {
+                let callCount = 0;
+                const fetchImpl = (_url, _init) => {
+                    callCount++;
+                    if (callCount === 1) {
+                        return Promise.resolve(makeMockResponse({ ok: true, jsonValue: rootWithOneFile('data.json') }));
+                    }
+                    if (callCount === 2) {
+                        return Promise.resolve(makeMockResponse({ ok: true, jsonValue: fileResponse('/data.json', '{}') }));
+                    }
+                    if (callCount === 3) {
+                        return Promise.resolve(makeMockResponse({ ok: true, jsonValue: fileResponse('/data.json', '"v2"') }));
+                    }
+                    // All /sync attempts: persistent 503
+                    return Promise.resolve(makeMockResponse({ ok: false, status: 503, textValue: 'Service Unavailable' }));
+                };
+                const accessors = (await HttpTreeAccessors.fromHttp({
+                    baseUrl: 'http://localhost:3000',
+                    fetchImpl,
+                    mutable: true
+                })).orThrow();
+                accessors.saveFileContents('/data.json', '"v2"').orThrow();
+                const syncPromise = accessors.syncToDisk();
+                // Advance past both backoff delays: 500ms + 1000ms
+                await jest.advanceTimersByTimeAsync(1500);
+                const result = await syncPromise;
+                expect(result).toFailWith(/service unavailable/i);
+            }
+            finally {
+                jest.useRealTimers();
+            }
         });
         test('fails when POST /sync encounters a network error', async () => {
-            let callCount = 0;
-            const fetchImpl = (_url, _init) => {
-                callCount++;
-                if (callCount === 1) {
-                    return Promise.resolve(makeMockResponse({ ok: true, jsonValue: rootWithOneFile('data.json') }));
-                }
-                if (callCount === 2) {
-                    return Promise.resolve(makeMockResponse({ ok: true, jsonValue: fileResponse('/data.json', '{}') }));
-                }
-                if (callCount === 3) {
-                    return Promise.resolve(makeMockResponse({ ok: true, jsonValue: fileResponse('/data.json', '"v2"') }));
-                }
-                return Promise.reject(new Error('POST network error'));
-            };
-            const accessors = (await HttpTreeAccessors.fromHttp({
-                baseUrl: 'http://localhost:3000',
-                fetchImpl,
-                mutable: true
-            })).orThrow();
-            accessors.saveFileContents('/data.json', '"v2"').orThrow();
-            const result = await accessors.syncToDisk();
-            expect(result).toFailWith(/post network error/i);
+            jest.useFakeTimers();
+            try {
+                let callCount = 0;
+                const fetchImpl = (_url, _init) => {
+                    callCount++;
+                    if (callCount === 1) {
+                        return Promise.resolve(makeMockResponse({ ok: true, jsonValue: rootWithOneFile('data.json') }));
+                    }
+                    if (callCount === 2) {
+                        return Promise.resolve(makeMockResponse({ ok: true, jsonValue: fileResponse('/data.json', '{}') }));
+                    }
+                    if (callCount === 3) {
+                        return Promise.resolve(makeMockResponse({ ok: true, jsonValue: fileResponse('/data.json', '"v2"') }));
+                    }
+                    return Promise.reject(new Error('POST network error'));
+                };
+                const accessors = (await HttpTreeAccessors.fromHttp({
+                    baseUrl: 'http://localhost:3000',
+                    fetchImpl,
+                    mutable: true
+                })).orThrow();
+                accessors.saveFileContents('/data.json', '"v2"').orThrow();
+                const syncPromise = accessors.syncToDisk();
+                await jest.advanceTimersByTimeAsync(1500);
+                const result = await syncPromise;
+                expect(result).toFailWith(/post network error/i);
+            }
+            finally {
+                jest.useRealTimers();
+            }
         });
         test('syncs multiple dirty files in order', async () => {
             const { fetchImpl, calls } = makeMockFetch([
@@ -846,25 +881,34 @@ describe('HttpTreeAccessors', () => {
         });
         test('returns failure with HTTP status fallback when response.text() throws during sync', async () => {
             // Covers the text() catch branch in _request(): uses `HTTP ${status}` fallback
-            let callCount = 0;
-            const fetchImpl = (_url, _init) => {
-                callCount++;
-                if (callCount === 1) {
-                    return Promise.resolve(makeMockResponse({ ok: true, jsonValue: rootWithOneFile('data.json') }));
-                }
-                if (callCount === 2) {
-                    return Promise.resolve(makeMockResponse({ ok: true, jsonValue: fileResponse('/data.json', '{}') }));
-                }
-                return Promise.resolve(makeMockResponse({ ok: false, status: 502, throwOnText: true }));
-            };
-            const accessors = (await HttpTreeAccessors.fromHttp({
-                baseUrl: 'http://localhost:3000',
-                fetchImpl,
-                mutable: true
-            })).orThrow();
-            accessors.saveFileContents('/data.json', '"updated"').orThrow();
-            const result = await accessors.syncToDisk();
-            expect(result).toFailWith(/http 502/i);
+            // 502 is transient so retries will be attempted; use fake timers to avoid real delays
+            jest.useFakeTimers();
+            try {
+                let callCount = 0;
+                const fetchImpl = (_url, _init) => {
+                    callCount++;
+                    if (callCount === 1) {
+                        return Promise.resolve(makeMockResponse({ ok: true, jsonValue: rootWithOneFile('data.json') }));
+                    }
+                    if (callCount === 2) {
+                        return Promise.resolve(makeMockResponse({ ok: true, jsonValue: fileResponse('/data.json', '{}') }));
+                    }
+                    return Promise.resolve(makeMockResponse({ ok: false, status: 502, throwOnText: true }));
+                };
+                const accessors = (await HttpTreeAccessors.fromHttp({
+                    baseUrl: 'http://localhost:3000',
+                    fetchImpl,
+                    mutable: true
+                })).orThrow();
+                accessors.saveFileContents('/data.json', '"updated"').orThrow();
+                const syncPromise = accessors.syncToDisk();
+                await jest.advanceTimersByTimeAsync(1500);
+                const result = await syncPromise;
+                expect(result).toFailWith(/http 502/i);
+            }
+            finally {
+                jest.useRealTimers();
+            }
         });
     });
     describe('_requestWithParams() error handling', () => {
@@ -996,5 +1040,325 @@ describe('HttpTreeAccessors', () => {
             expect(methodCalls).toContain('POST');
         });
     });
+    describe('_requestWithRetry()', () => {
+        test('succeeds on second attempt after a transient 503 error', async () => {
+            jest.useFakeTimers();
+            try {
+                // Responses: init (GET tree/children), then PUT fails with 503, then PUT succeeds, then POST /sync succeeds
+                let callCount = 0;
+                const fetchImpl = (_url, _init) => {
+                    callCount++;
+                    if (callCount === 1) {
+                        return Promise.resolve(makeMockResponse({ ok: true, jsonValue: rootWithOneFile('data.json') }));
+                    }
+                    if (callCount === 2) {
+                        return Promise.resolve(makeMockResponse({ ok: true, jsonValue: fileResponse('/data.json', '{}') }));
+                    }
+                    // First PUT attempt: transient 503
+                    if (callCount === 3) {
+                        return Promise.resolve(makeMockResponse({ ok: false, status: 503, textValue: '503 Service Unavailable' }));
+                    }
+                    // Second PUT attempt: success
+                    if (callCount === 4) {
+                        return Promise.resolve(makeMockResponse({ ok: true, jsonValue: fileResponse('/data.json', '"updated"') }));
+                    }
+                    // POST /sync
+                    return Promise.resolve(makeMockResponse({ ok: true, jsonValue: { synced: 1 } }));
+                };
+                const accessors = (await HttpTreeAccessors.fromHttp({
+                    baseUrl: 'http://localhost:3000',
+                    fetchImpl,
+                    mutable: true
+                })).orThrow();
+                accessors.saveFileContents('/data.json', '"updated"').orThrow();
+                const syncPromise = accessors.syncToDisk();
+                // Advance past the 500ms backoff for the first retry
+                await jest.advanceTimersByTimeAsync(500);
+                const result = await syncPromise;
+                expect(result).toSucceed();
+                // Three PUT-related calls: init (2) + first PUT attempt (1) + retry PUT (1) + POST sync (1)
+                expect(callCount).toBe(5);
+            }
+            finally {
+                jest.useRealTimers();
+            }
+        });
+        test('does not retry on a non-transient error (e.g. 404)', async () => {
+            jest.useFakeTimers();
+            try {
+                let callCount = 0;
+                const fetchImpl = (_url, _init) => {
+                    callCount++;
+                    if (callCount === 1) {
+                        return Promise.resolve(makeMockResponse({ ok: true, jsonValue: rootWithOneFile('data.json') }));
+                    }
+                    if (callCount === 2) {
+                        return Promise.resolve(makeMockResponse({ ok: true, jsonValue: fileResponse('/data.json', '{}') }));
+                    }
+                    // PUT attempt: non-transient 404
+                    return Promise.resolve(makeMockResponse({ ok: false, status: 404, textValue: 'Not Found' }));
+                };
+                const accessors = (await HttpTreeAccessors.fromHttp({
+                    baseUrl: 'http://localhost:3000',
+                    fetchImpl,
+                    mutable: true
+                })).orThrow();
+                accessors.saveFileContents('/data.json', '"updated"').orThrow();
+                const result = await accessors.syncToDisk();
+                // No timers should need advancing - non-transient errors return immediately
+                expect(result).toFailWith(/not found/i);
+                // Only 3 calls: 2 init + 1 PUT (no retries)
+                expect(callCount).toBe(3);
+            }
+            finally {
+                jest.useRealTimers();
+            }
+        });
+        test('returns the last error after exhausting all retries on persistent transient errors', async () => {
+            jest.useFakeTimers();
+            try {
+                let callCount = 0;
+                const fetchImpl = (_url, _init) => {
+                    callCount++;
+                    if (callCount === 1) {
+                        return Promise.resolve(makeMockResponse({ ok: true, jsonValue: rootWithOneFile('data.json') }));
+                    }
+                    if (callCount === 2) {
+                        return Promise.resolve(makeMockResponse({ ok: true, jsonValue: fileResponse('/data.json', '{}') }));
+                    }
+                    // All PUT attempts: transient 502 every time
+                    return Promise.resolve(makeMockResponse({ ok: false, status: 502, textValue: '502 Bad Gateway' }));
+                };
+                const accessors = (await HttpTreeAccessors.fromHttp({
+                    baseUrl: 'http://localhost:3000',
+                    fetchImpl,
+                    mutable: true
+                })).orThrow();
+                accessors.saveFileContents('/data.json', '"updated"').orThrow();
+                const syncPromise = accessors.syncToDisk();
+                // Advance past both backoff delays: 500ms (attempt 1) + 1000ms (attempt 2)
+                await jest.advanceTimersByTimeAsync(1500);
+                const result = await syncPromise;
+                expect(result).toFailWith(/502 bad gateway/i);
+                // 2 init + 3 PUT attempts (maxAttempts = 3)
+                expect(callCount).toBe(5);
+            }
+            finally {
+                jest.useRealTimers();
+            }
+        });
+        test('logs retry message with method name from init when retrying', async () => {
+            jest.useFakeTimers();
+            try {
+                const logger = {
+                    detail: jest.fn(),
+                    info: jest.fn(),
+                    warn: jest.fn(),
+                    error: jest.fn()
+                };
+                let callCount = 0;
+                const fetchImpl = (_url, _init) => {
+                    callCount++;
+                    if (callCount === 1) {
+                        return Promise.resolve(makeMockResponse({ ok: true, jsonValue: rootWithOneFile('data.json') }));
+                    }
+                    if (callCount === 2) {
+                        return Promise.resolve(makeMockResponse({ ok: true, jsonValue: fileResponse('/data.json', '{}') }));
+                    }
+                    // First PUT attempt: transient 503
+                    if (callCount === 3) {
+                        return Promise.resolve(makeMockResponse({ ok: false, status: 503, textValue: '503 Service Unavailable' }));
+                    }
+                    // Second PUT attempt: success
+                    if (callCount === 4) {
+                        return Promise.resolve(makeMockResponse({ ok: true, jsonValue: fileResponse('/data.json', '"updated"') }));
+                    }
+                    // POST /sync
+                    return Promise.resolve(makeMockResponse({ ok: true, jsonValue: { synced: 1 } }));
+                };
+                const accessors = (await HttpTreeAccessors.fromHttp({
+                    baseUrl: 'http://localhost:3000',
+                    fetchImpl,
+                    mutable: true,
+                    logger
+                })).orThrow();
+                accessors.saveFileContents('/data.json', '"updated"').orThrow();
+                const syncPromise = accessors.syncToDisk();
+                await jest.advanceTimersByTimeAsync(500);
+                await syncPromise;
+                // The retry log message should include the method name (PUT) from init
+                expect(logger.detail).toHaveBeenCalledWith(expect.stringContaining('PUT'));
+            }
+            finally {
+                jest.useRealTimers();
+            }
+        });
+    });
+    describe('syncToDisk() concurrency guard', () => {
+        test('concurrent syncToDisk calls share the same promise and only make one set of network calls', async () => {
+            const { fetchImpl, calls } = makeMockFetch([
+                { ok: true, jsonValue: rootWithOneFile('data.json') },
+                { ok: true, jsonValue: fileResponse('/data.json', '{}') },
+                // PUT /file for the single sync
+                { ok: true, jsonValue: fileResponse('/data.json', '"updated"') },
+                // POST /sync
+                { ok: true, jsonValue: { synced: 1 } }
+            ]);
+            const accessors = (await HttpTreeAccessors.fromHttp({
+                baseUrl: 'http://localhost:3000',
+                fetchImpl,
+                mutable: true
+            })).orThrow();
+            accessors.saveFileContents('/data.json', '"updated"').orThrow();
+            // Start two concurrent syncToDisk calls without awaiting the first
+            const promise1 = accessors.syncToDisk();
+            const promise2 = accessors.syncToDisk();
+            const [result1, result2] = await Promise.all([promise1, promise2]);
+            expect(result1).toSucceed();
+            expect(result2).toSucceed();
+            // Both promises should have resolved to the same underlying promise result.
+            // Only one PUT and one POST /sync should have been issued (not doubled).
+            const syncCalls = calls.slice(2);
+            const putCalls = syncCalls.filter((c) => { var _a; return ((_a = c.init) === null || _a === void 0 ? void 0 : _a.method) === 'PUT'; });
+            const postCalls = syncCalls.filter((c) => { var _a; return ((_a = c.init) === null || _a === void 0 ? void 0 : _a.method) === 'POST'; });
+            expect(putCalls).toHaveLength(1);
+            expect(postCalls).toHaveLength(1);
+        });
+        test('drains items written during an in-flight sync within the same _doSync call', async () => {
+            // This tests the drain loop fix for the race where:
+            // 1. sync starts, snapshots dirty set {a.json}
+            // 2. during the PUT for a.json, a new write arrives adding a.json back
+            // 3. _doSync loops back, snapshots the new item, and syncs it too
+            // 4. Only one POST /sync is sent at the end, after all items are drained
+            let callCount = 0;
+            let saveHook;
+            const fetchImpl = (url, init) => {
+                callCount++;
+                const urlStr = url.toString();
+                // Calls 1-2: fromHttp load
+                if (callCount <= 2) {
+                    if (callCount === 1) {
+                        return Promise.resolve(makeMockResponse({ ok: true, jsonValue: rootWithOneFile('a.json') }));
+                    }
+                    return Promise.resolve(makeMockResponse({ ok: true, jsonValue: fileResponse('/a.json', '"orig"') }));
+                }
+                // Call 3: first PUT /file for a.json — trigger a write mid-sync
+                if (callCount === 3 && (init === null || init === void 0 ? void 0 : init.method) === 'PUT') {
+                    saveHook === null || saveHook === void 0 ? void 0 : saveHook();
+                    return Promise.resolve(makeMockResponse({ ok: true, jsonValue: fileResponse('/a.json', '"v1"') }));
+                }
+                // Call 4: second PUT /file for a.json (drain loop iteration)
+                if (callCount === 4 && (init === null || init === void 0 ? void 0 : init.method) === 'PUT') {
+                    return Promise.resolve(makeMockResponse({ ok: true, jsonValue: fileResponse('/a.json', '"v2"') }));
+                }
+                // Call 5: single POST /sync after drain loop exits
+                if (callCount === 5 && urlStr.includes('/sync')) {
+                    return Promise.resolve(makeMockResponse({ ok: true, jsonValue: { synced: 1 } }));
+                }
+                return Promise.reject(new Error(`Unexpected call #${callCount} to ${urlStr}`));
+            };
+            const accessors = (await HttpTreeAccessors.fromHttp({
+                baseUrl: 'http://localhost:3000',
+                fetchImpl: fetchImpl,
+                mutable: true
+            })).orThrow();
+            // Write a.json
+            accessors.saveFileContents('/a.json', '"v1"').orThrow();
+            // Set up the hook BEFORE starting sync — the mock fetch for the PUT
+            // runs synchronously within syncToDisk(), so the hook must be in place.
+            saveHook = () => {
+                accessors.saveFileContents('/a.json', '"v2"').orThrow();
+            };
+            // Start sync — during the first PUT, saveHook fires and writes v2.
+            // The drain loop in _doSync picks this up and PUTs again before
+            // sending the final POST /sync.
+            const result = await accessors.syncToDisk();
+            expect(result).toSucceed();
+            expect(accessors.isDirty()).toBe(false);
+            // 5 calls: 2 load + 2 PUTs (v1, v2) + 1 POST /sync
+            expect(callCount).toBe(5);
+        });
+    });
+    describe('syncToDisk() error recovery', () => {
+        test('restores dirty files when PUT fails so they can be retried', async () => {
+            const { fetchImpl } = makeMockFetch([
+                { ok: true, jsonValue: rootWithOneFile('data.json') },
+                { ok: true, jsonValue: fileResponse('/data.json', '{}') },
+                // PUT /file fails with non-transient error
+                { ok: false, status: 500, textValue: 'Server Error' }
+            ]);
+            const accessors = (await HttpTreeAccessors.fromHttp({
+                baseUrl: 'http://localhost:3000',
+                fetchImpl,
+                mutable: true
+            })).orThrow();
+            accessors.saveFileContents('/data.json', '"updated"').orThrow();
+            expect(accessors.isDirty()).toBe(true);
+            const result = await accessors.syncToDisk();
+            expect(result).toFailWith(/sync.*data\.json.*server error/i);
+            // The file should still be dirty so a retry is possible
+            expect(accessors.isDirty()).toBe(true);
+            expect(accessors.getDirtyPaths()).toContain('/data.json');
+        });
+        test('restores pending deletions when DELETE fails so they can be retried', async () => {
+            const { fetchImpl } = makeMockFetch([
+                { ok: true, jsonValue: rootWithOneFile('data.json') },
+                { ok: true, jsonValue: fileResponse('/data.json', '{}') },
+                // DELETE fails with non-transient error
+                { ok: false, status: 500, textValue: 'Server Error' }
+            ]);
+            const accessors = (await HttpTreeAccessors.fromHttp({
+                baseUrl: 'http://localhost:3000',
+                fetchImpl,
+                mutable: true
+            })).orThrow();
+            accessors.deleteFile('/data.json').orThrow();
+            expect(accessors.isDirty()).toBe(true);
+            const result = await accessors.syncToDisk();
+            expect(result).toFailWith(/delete.*data\.json.*server error/i);
+            // The deletion should still be pending so a retry is possible
+            expect(accessors.isDirty()).toBe(true);
+            expect(accessors.getDirtyPaths()).toContain('/data.json');
+        });
+        test('restores dirty files when POST /sync fails so they can be retried', async () => {
+            jest.useFakeTimers();
+            try {
+                let callCount = 0;
+                const fetchImpl = (_url, _init) => {
+                    callCount++;
+                    if (callCount === 1) {
+                        return Promise.resolve(makeMockResponse({ ok: true, jsonValue: rootWithOneFile('data.json') }));
+                    }
+                    if (callCount === 2) {
+                        return Promise.resolve(makeMockResponse({ ok: true, jsonValue: fileResponse('/data.json', '{}') }));
+                    }
+                    if (callCount === 3) {
+                        // PUT succeeds
+                        return Promise.resolve(makeMockResponse({ ok: true, jsonValue: fileResponse('/data.json', '"v2"') }));
+                    }
+                    // All /sync attempts: persistent 503
+                    return Promise.resolve(makeMockResponse({ ok: false, status: 503, textValue: 'Service Unavailable' }));
+                };
+                const accessors = (await HttpTreeAccessors.fromHttp({
+                    baseUrl: 'http://localhost:3000',
+                    fetchImpl,
+                    mutable: true
+                })).orThrow();
+                accessors.saveFileContents('/data.json', '"v2"').orThrow();
+                const syncPromise = accessors.syncToDisk();
+                await jest.advanceTimersByTimeAsync(1500);
+                const result = await syncPromise;
+                expect(result).toFailWith(/service unavailable/i);
+                // The PUT succeeded — data is on the server — so the file is no
+                // longer dirty. Only the server-side /sync acknowledgement failed,
+                // which is not something the client can meaningfully retry via
+                // re-sending the file contents.
+                expect(accessors.isDirty()).toBe(false);
+            }
+            finally {
+                jest.useRealTimers();
+            }
+        });
+    });
 });
 //# sourceMappingURL=httpTreeAccessors.test.js.map