@glance-apps/sync 1.5.3 → 1.6.1

package/CHANGELOG.md

@@ -7,6 +7,105 @@ 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
+
+- **DB engine: a pulled delete no longer unconditionally beats a newer local
+  edit.** `applyRemoteRow` applied a pulled `deleted: true` row without any
+  timestamp comparison AND pruned the entity from the dirty set, so a device
+  that edited an entity offline (with a newer `lastModified`) and then pulled a
+  peer's delete before pushing silently discarded its own newer edit — the
+  opposite of the engine's upsert conflict rule and of the file tier's
+  newest-write-wins over tombstones. Deletes now participate in the same
+  entity-grain LWW: the engine stamps each pushed soft-delete with a
+  `deletedAt` (epoch ms, taken at push time) and applies a pulled delete only
+  when the local copy's `lastModified` does not exceed that stamp. When the
+  local edit is strictly newer, the delete is discarded and the entity is
+  marked (or kept) dirty so the next push re-upserts it over the tombstone and
+  restores the row fleet-wide.
+  - **Tie-break:** on an exact timestamp tie the DELETE wins (unlike the upsert
+    rule, where local wins ties), because `deletedAt` is stamped at push time
+    and therefore already post-dates the deleting device's own last edit.
+  - **Backward compatibility:** a tombstone with no `deletedAt` — from a
+    GLANCEvault server that predates the stamp, or a row deleted by an older
+    client — keeps the previous unconditional delete-wins behavior. `deletedAt`
+    rides the DELETE request as an extra query param, which old servers ignore.
+- **DB engine: push sends upserts before deletes, closing the transient
+  fleet-wide delete window.** `pushDirtyRows` used to issue the per-entity
+  `deleteRow` calls before the batched upserts. A cross-list move (delete
+  `unscheduledTasks:X` + upsert `tasks:X` in the same dirty set) that failed
+  between the two steps (5xx / network drop) left the delete on the server with
+  no replacement row, so every peer pulled a bare delete and the entity
+  vanished fleet-wide until the origin device successfully retried. The batch
+  upsert now runs first; a failure between the steps leaves the benign inverse
+  (both rows briefly exist) and the retained dirty set retries both
+  idempotently. No invariant depended on the old order: upserts and deletes in
+  one push can never share an `entityId`, and `maxSeq`/ack accounting is
+  order-independent.
+
+### Changed — behavior notes for consumers
+
+- Delete/edit races now resolve by newest-write-wins instead of delete-always-
+  wins. An entity edited on one device *after* (per wall clock) another
+  device's deletion will be **restored on all devices** rather than deleted.
+  Apps relying on "delete always sticks" semantics should treat this as a
+  breaking behavior change. Clock skew caveat: `deletedAt` comes from the
+  deleting device's clock at push time, so a device with a fast clock can win
+  conflicts it shouldn't — same trust model as the existing `lastModified` LWW.
+- During a partial push failure, peers may transiently observe a moved entity
+  in both its old and new lists (previously: in neither) until the retry lands.
+- Unchanged (regression-guarded): upsert LWW keeps local on ties and prunes a
+  remotely-superseded entity from the dirty set; the split pull/push cursors
+  and their persistence keys; the exported `getRow` vault surface and
+  `decryptEntity`; push idempotency for re-sent upserts and soft-deletes.
+
+### Added
+
+- `createVaultClient().deleteRow(app, entityId, accountId, { deletedAt })` —
+  optional fourth argument; the stamp is sent as a `deletedAt` query param.
+  `VaultPulledRow` gains an optional `deletedAt` field.
+
 ## [1.5.3] - 2026-07-04
 
 ### Fixed
@@ -315,7 +414,9 @@ 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.5.3...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
 [1.1.2]: https://github.com/glance-apps/glance-sync/compare/v1.1.1...v1.1.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.5.3",
+  "version": "1.6.1",
   "license": "MIT",
   "type": "module",
   "main": "src/index.js",

package/src/dbEngine.js

@@ -373,18 +373,34 @@ export const createDbSyncEngine = (config) => {
       }
     }
 
-    // Soft-delete first, then batch the upserts. If any call throws, we fall out
-    // before clearing the dirty set or advancing the push-ack marker.
+    // Batch the upserts FIRST, then soft-delete. If any call throws, we fall
+    // out before clearing the dirty set or advancing the push-ack marker.
+    //
+    // The order matters for partial-failure safety: a cross-list move puts a
+    // delete ("old-list:X") and its replacement upsert ("new-list:X") in the
+    // same dirty set. Deleting first opened a window where the delete landed,
+    // the batch failed, and every peer pulled a delete with no replacement —
+    // the entity vanished fleet-wide until this device successfully retried.
+    // Upserting first inverts the partial state into a benign one (both rows
+    // briefly exist) that the retried delete cleans up. Nothing depends on
+    // deletes landing first: upserts and deletes in one push never share an
+    // entityId (an entity is either present locally or not), and maxSeq is
+    // order-independent.
+    //
+    // Each delete carries a deletedAt stamp so pulling devices can run LWW
+    // against it (see applyRemoteRow). Servers that predate the stamp ignore
+    // the extra field, in which case pulled tombstones simply lack deletedAt
+    // and fall back to the old delete-wins behavior.
     let maxSeq = getPushAck();
-    for (const entityId of deletes) {
-      const r = await vault.deleteRow(app, entityId, accountId);
-      if (r && typeof r.seq === 'number') maxSeq = Math.max(maxSeq, r.seq);
-      if (r && typeof r.maxSeq === 'number') maxSeq = Math.max(maxSeq, r.maxSeq);
-    }
     if (upserts.length > 0) {
       const result = await vault.batch(app, { accountId, rows: upserts });
       if (result && typeof result.maxSeq === 'number') maxSeq = Math.max(maxSeq, result.maxSeq);
     }
+    for (const entityId of deletes) {
+      const r = await vault.deleteRow(app, entityId, accountId, { deletedAt: Date.now() });
+      if (r && typeof r.seq === 'number') maxSeq = Math.max(maxSeq, r.seq);
+      if (r && typeof r.maxSeq === 'number') maxSeq = Math.max(maxSeq, r.maxSeq);
+    }
 
     // Full acknowledgment: safe to mark clean. Advance the push-ack marker only;
     // the pull cursor stays put so the next pull still lists from the highest
@@ -401,6 +417,29 @@ export const createDbSyncEngine = (config) => {
   // failure — the caller decides whether to quarantine.
   const applyRemoteRow = async (R, dirty) => {
     if (R.deleted) {
+      // A tombstone participates in the same entity-grain LWW as an upsert,
+      // using the deletedAt stamp the pushing device attached (see
+      // pushDirtyRows). A local copy KEEPS only when its lastModified strictly
+      // exceeds deletedAt: the delete wins ties, because deletedAt is stamped
+      // at push time and therefore already post-dates the edit that produced
+      // it on the deleting device. Tombstones from servers/devices that
+      // predate the stamp carry no deletedAt (ts -> 0); those keep the old
+      // unconditional delete-wins behavior.
+      const deletedAt = ts(R.deletedAt);
+      if (deletedAt > 0) {
+        const local = await getLocalEntity(R.entityId);
+        if (local != null && ts(lastModifiedOf(local)) > deletedAt) {
+          // The local edit is newer than the delete: keep it, and make sure it
+          // is dirty so the next push re-upserts it over the tombstone and
+          // restores the row fleet-wide (matching the file tier's
+          // newest-write-wins over tombstones).
+          if (!dirty.has(R.entityId)) {
+            dirty.add(R.entityId);
+            writeDirtySet([...dirty]);
+          }
+          return false;
+        }
+      }
       await applyRemoteDelete(R.entityId);
       if (dirty.delete(R.entityId)) writeDirtySet([...dirty]);
       return true;

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/src/vaultClient.js

@@ -10,7 +10,7 @@
 //   POST   /sync/:app/batch                     upsert rows, returns { written, maxSeq }
 //   GET    /sync/:app/list?accountId=&since=     incremental fetch, { rows, hasMore }
 //   GET    /sync/:app/:entityId?accountId=       fetch one row
-//   DELETE /sync/:app/:entityId?accountId=       soft-delete a row
+//   DELETE /sync/:app/:entityId?accountId=&deletedAt=  soft-delete a row (deletedAt optional)
 //   POST   /sync/:app/device                     update device cursor, { updated }
 //   GET    /salt/:accountId                      fetch the account root-key salt
 //   PUT    /salt/:accountId                      register a salt (first-write-wins)
@@ -127,11 +127,18 @@ export function createVaultClient({ vaultUrl, vaultToken, fetchImpl } = {}) {
     /**
      * Soft-deletes a row by entityId. Returns the server response (may include
      * the new seq for the tombstone).
+     *
+     * opts.deletedAt (epoch ms) stamps the tombstone so pulling devices can
+     * resolve delete-vs-edit conflicts with LWW. It rides as a query param, so
+     * servers that predate the stamp simply ignore it (their tombstones come
+     * back without deletedAt and the engine falls back to delete-wins).
      */
-    async deleteRow(app, entityId, accountId) {
+    async deleteRow(app, entityId, accountId, opts = {}) {
       requireAccountId(accountId, 'delete row');
+      const query = { accountId };
+      if (opts && opts.deletedAt != null) query.deletedAt = String(opts.deletedAt);
       const res = await request('DELETE', `/sync/${encodeURIComponent(app)}/${encodeURIComponent(entityId)}`, {
-        query: { accountId },
+        query,
       });
       if (res.status === 404) return null;
       return jsonOrThrow(res, 'delete row');

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
 // ---------------------------------------------------------------------------
@@ -396,6 +404,8 @@ export interface VaultPulledRow extends Partial<VaultRow> {
   entityId: string;
   seq: number;
   deleted?: boolean;
+  /** Tombstone LWW stamp (epoch ms or date string). Absent on rows from servers that predate it: the engine then treats the delete as unconditionally winning. */
+  deletedAt?: number | string;
   envelope?: string;
 }
 
@@ -403,7 +413,7 @@ export interface VaultClient {
   batch(app: string, args: { accountId: string; rows: VaultRow[] }): Promise<{ written: number; maxSeq: number }>;
   list(app: string, args: { accountId: string; since: number }): Promise<{ rows: VaultPulledRow[]; hasMore: boolean }>;
   getRow(app: string, entityId: string, accountId: string): Promise<VaultPulledRow | null>;
-  deleteRow(app: string, entityId: string, accountId: string): Promise<{ seq?: number } | null>;
+  deleteRow(app: string, entityId: string, accountId: string, opts?: { deletedAt?: number }): Promise<{ seq?: number } | null>;
   device(app: string, args: { accountId: string; deviceId: string; lastSeenSeq: number }): Promise<{ updated: boolean }>;
   getSalt(accountId: string): Promise<Uint8Array | null>;
   putSalt(accountId: string, salt: Uint8Array): Promise<Uint8Array>;