@glance-apps/sync 1.6.0 → 1.6.1

package/CHANGELOG.md

@@ -7,6 +7,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.6.1] - 2026-07-19
+
+### Fixed
+
+- **File engine: persistent PRECONDITION_FAILED (412) sync loop on servers
+  that mangle ETags** (lastGLANCE issue #232). The optimistic-concurrency
+  cycle (GET capturing an ETag, merge, PUT with If-Match) can never converge
+  against a server whose GET responses carry a mangled validator: Apache
+  mod_deflate rewrites the ETag on gzip-encoded responses to `"xyz-gzip"`
+  (Android's HttpURLConnection silently requests gzip, so native apps always
+  hit this on Apache-fronted servers such as standard Nextcloud installs), and
+  nginx's gzip filter downgrades strong ETags to weak (`W/"xyz"`), which
+  If-Match's strong comparison rejects. Either way every PUT 412s, the
+  single conditional retry fetches another mangled ETag and 412s again, and
+  sync wedges until the user hand-deletes the sync file from the server. Two
+  complementary fixes:
+  - **ETag normalization at capture time.** A new exported pure helper,
+    `normalizeEtag(raw)`, strips the weak-validator prefix (`W/"abc"` becomes
+    `"abc"`) and the known content-coding suffixes Apache appends inside the
+    quotes (`"abc-gzip"` / `"abc-br"` become `"abc"`), preserving surrounding
+    quotes and passing null/undefined through. `parseDownloadResponse` now
+    normalizes every ETag it captures, so If-Match round-trips the entity's
+    real validator. Clean ETags are unchanged, so servers that never mangle
+    see identical behavior.
+  - **Termination guarantee: a second consecutive 412 falls back to an
+    unconditional upload.** If the conditional retry after a 412 itself fails
+    with PRECONDITION_FAILED (any other error keeps the existing
+    backoff-and-surface behavior), the engine runs one final
+    download-merge-upload cycle whose PUT omits If-Match entirely
+    (last-writer-wins). The uploaded payload is the merge of local state with
+    the remote fetched milliseconds earlier in the same cycle, so the
+    lost-update window is tiny - far safer than a permanently wedged sync
+    that pushes users toward deleting the sync file. If the fallback cycle
+    itself fails, the error is surfaced exactly as the old retry-failure path
+    did (exponential backoff, `onError`, status `'error'`).
+
+### Added
+
+- `normalizeEtag(raw)` exported from the package root for reuse by apps.
+
 ## [1.6.0] - 2026-07-10
 
 ### Fixed
@@ -374,7 +414,8 @@ entire sync infrastructure can be shared across the GLANCE app family.
 - TypeScript declarations in `types/index.d.ts`.
 - WebDAV CORS proxy handler in `api/webdav-proxy.js`.
 
-[Unreleased]: https://github.com/glance-apps/glance-sync/compare/v1.6.0...HEAD
+[Unreleased]: https://github.com/glance-apps/glance-sync/compare/v1.6.1...HEAD
+[1.6.1]: https://github.com/glance-apps/glance-sync/compare/v1.6.0...v1.6.1
 [1.6.0]: https://github.com/glance-apps/glance-sync/compare/v1.5.3...v1.6.0
 [1.5.3]: https://github.com/glance-apps/glance-sync/compare/v1.5.2...v1.5.3
 [1.5.2]: https://github.com/glance-apps/glance-sync/compare/v1.5.1...v1.5.2

package/README.md

@@ -156,6 +156,7 @@ Pass `encryptionEnabled: true` in the sync config object stored via `engine.setC
 |--------|-------------|
 | `webdavFetch(config)` | Creates a transport-selecting WebDAV fetcher. Prefers Android HTTP bridge → Electron proxy → CORS proxy, in that order. |
 | `createProviders(config)` | Creates cloud sync provider objects (`nextcloud`, `koofr`, `webdav`). |
+| `normalizeEtag(raw)` | Normalizes a raw ETag header value for If-Match use: strips a weak-validator prefix (`W/"abc"` → `"abc"`) and the content-coding suffixes some servers append inside the quotes (`"abc-gzip"` / `"abc-br"` → `"abc"`). Quotes are preserved; `null`/`undefined` pass through unchanged. |
 
 ### Auto-backup
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glance-apps/sync",
-  "version": "1.6.0",
+  "version": "1.6.1",
   "license": "MIT",
   "type": "module",
   "main": "src/index.js",

package/src/engine.js

@@ -314,7 +314,9 @@ export const createSyncEngine = (config) => {
 
     // Inner helper: download, merge, apply, upload (if anything changed).
     // Returns true if a reload was triggered (caller should bail).
-    const doCycle = async (overrideEtag) => {
+    // skipIfMatch forces an unconditional upload (no If-Match) — the
+    // last-writer-wins fallback used after two consecutive 412s.
+    const doCycle = async (overrideEtag, { skipIfMatch = false } = {}) => {
       const downloaded = await provider.download(cfg);
       if (!downloaded) {
         // Empty remote — seed it with local state.
@@ -365,7 +367,7 @@ export const createSyncEngine = (config) => {
         await upload({
           prebuiltPayload: mergedPayload,
           skipLockCheck: true,
-          etag: etag || overrideEtag || null,
+          etag: skipIfMatch ? null : (etag || overrideEtag || null),
         });
 
         if (localChanged) {
@@ -425,6 +427,7 @@ export const createSyncEngine = (config) => {
         // jitter (1–3 s) to reduce collision probability, then retry once.
         const jitterMs = 1000 + Math.random() * 2000;
         await new Promise(r => setTimeout(r, jitterMs));
+        let finalErr = null;
         try {
           await doCycle(null);
           downloadErrorCount = 0;
@@ -432,12 +435,35 @@ export const createSyncEngine = (config) => {
         } catch (retryErr) {
           // eslint-disable-next-line no-console
           console.error(`[${appId}] cloud sync retry after 412 failed:`, retryErr);
+          if (classifyError(retryErr).code === 'PRECONDITION_FAILED') {
+            // Two consecutive 412s with fresh ETags is not a write race — it's
+            // a server whose ETags can't round-trip through If-Match (e.g. a
+            // proxy mangling them in a way normalizeEtag doesn't cover), and a
+            // conditional retry can never succeed. Run one last cycle whose
+            // upload omits If-Match (last-writer-wins). The payload is the
+            // merge of local state with the remote fetched milliseconds
+            // earlier in the same cycle, so the lost-update window is tiny —
+            // far safer than a permanently wedged sync.
+            try {
+              await doCycle(null, { skipIfMatch: true });
+              downloadErrorCount = 0;
+              downloadBackoffUntil = 0;
+            } catch (fallbackErr) {
+              // eslint-disable-next-line no-console
+              console.error(`[${appId}] cloud sync unconditional fallback after 412 failed:`, fallbackErr);
+              finalErr = fallbackErr;
+            }
+          } else {
+            finalErr = retryErr;
+          }
+        }
+        if (finalErr) {
           // Apply the same exponential backoff used for other transient errors so
           // the engine backs off rather than hammering the server every poll cycle.
           downloadErrorCount += 1;
           const ms = Math.min(30 * Math.pow(2, downloadErrorCount - 1), MAX_DOWNLOAD_BACKOFF_S) * 1000;
           downloadBackoffUntil = Date.now() + ms;
-          onError?.(formatErrorMessage(classifyError(retryErr)), classifyError(retryErr).code, false);
+          onError?.(formatErrorMessage(classifyError(finalErr)), classifyError(finalErr).code, false);
           onStatusChange?.('error');
           scheduleAutoRevert('error', ERROR_HOLD_MS);
         }

package/src/index.js

@@ -24,7 +24,7 @@ export {
 
 // webdavFetch and createProviders are internal to the engine (Step 6) but
 // exported here so shims can wire them before the engine exists.
-export { webdavFetch, createProviders } from './providers.js';
+export { webdavFetch, createProviders, normalizeEtag } from './providers.js';
 
 export {
   createAutoBackupDB,

package/src/providers.js

@@ -89,6 +89,39 @@ export const webdavFetch = (config) => async (method, targetUrl, authHeaders, bo
   });
 };
 
+// ---------------------------------------------------------------------------
+// ETag normalization
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalizes an ETag as captured from a GET response so it can be echoed back
+ * in If-Match. Proxies and content-encoding filters mangle ETags in ways that
+ * make the stored entity's validator unreachable:
+ *   - Apache mod_deflate/mod_brotli append `-gzip`/`-br` inside the quotes
+ *     (`"abc"` becomes `"abc-gzip"` on gzip-encoded responses).
+ *   - nginx's gzip filter downgrades strong ETags to weak (`W/"abc"`), and
+ *     If-Match requires strong comparison.
+ * Either way, a PUT with the mangled value 412s forever. Stripping the weak
+ * prefix and the known coding suffixes recovers the entity's real validator.
+ *
+ * Surrounding quotes are preserved; null/undefined pass through unchanged.
+ *
+ * @param {string|null|undefined} raw - raw ETag header value
+ * @returns {string|null|undefined} normalized ETag
+ */
+export function normalizeEtag(raw) {
+  if (raw == null) return raw;
+  let etag = raw;
+  if (etag.startsWith('W/')) etag = etag.slice(2);
+  if (etag.length >= 2 && etag.startsWith('"') && etag.endsWith('"')) {
+    const inner = etag.slice(1, -1).replace(/-(gzip|br)$/, '');
+    etag = `"${inner}"`;
+  } else {
+    etag = etag.replace(/-(gzip|br)$/, '');
+  }
+  return etag;
+}
+
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
@@ -96,7 +129,7 @@ export const webdavFetch = (config) => async (method, targetUrl, authHeaders, bo
 async function parseDownloadResponse(res, engineConfig) {
   const parsed = await res.json();
   const payload = isEncryptedEnvelope(parsed) ? await decryptData(parsed, engineConfig) : parsed;
-  const etag = res.headers.get('etag') || null;
+  const etag = normalizeEtag(res.headers.get('etag')) || null;
   return { payload, etag };
 }
 

package/types/index.d.ts

@@ -266,6 +266,14 @@ export interface CloudSyncProvider {
 export function webdavFetch(config: SyncEngineConfig): WebdavFetch;
 export function createProviders(config: SyncEngineConfig): Record<string, CloudSyncProvider>;
 
+/**
+ * Normalizes a raw ETag header value for use in If-Match: strips a weak-
+ * validator prefix (`W/"abc"` -> `"abc"`) and the content-coding suffixes
+ * Apache mod_deflate/mod_brotli append inside the quotes (`"abc-gzip"` /
+ * `"abc-br"` -> `"abc"`). Quotes are preserved; null/undefined pass through.
+ */
+export function normalizeEtag(raw: string | null | undefined): string | null | undefined;
+
 // ---------------------------------------------------------------------------
 // Sync engine
 // ---------------------------------------------------------------------------