@docstack/pouchdb-adapter-googledrive 0.1.5 → 0.1.6

package/lib/drive.d.ts

@@ -1,4 +1,25 @@
-import { GoogleDriveAdapterOptions, ChangeEntry, IndexEntry } from './types';
+import { GoogleDriveAdapterOptions, ChangeEntry, IndexEntry, FilePointer } from './types';
+/**
+ * Sequence numbers are `tick * SEQ_SLOTS + writerSlot`.
+ *
+ * Writers mint them blind to one another - there is no lock and no compare-and-swap -
+ * so two clients reading the same counter will always be able to derive the same next
+ * tick. Reserving the low digits for a per-writer slot means they can share a tick and
+ * still never share a *sequence number*, which is the part that matters: `_changes`
+ * filters on `seq > since`, so a second document sharing a checkpointed sequence
+ * number is never emitted to a replication target again.
+ *
+ * A million slots keeps the chance that two concurrent writers hash to the same one
+ * near 1 in 20,000 for a ten-client fleet, and leaves room for 9e9 ticks inside
+ * Number.MAX_SAFE_INTEGER.
+ */
+export declare const SEQ_SLOTS = 1000000;
+/** Stable slot for a writer id. FNV-1a, folded into the slot space. */
+export declare function writerSlotFor(writerId: string): number;
+/** The writer id embedded in a change-log filename, if the name carries one.
+ *  New format: changes-<seq>-<writerId>-<random>.ndjson (4 dash-parts).
+ *  Old format: changes-<seq>-<random>.ndjson (3 parts) - no id to extract. */
+export declare function writerIdFromLogName(name: string): string | null;
 /**
  * DriveHandler - Lazy Loading Implementation
  *
@@ -22,6 +43,27 @@ export declare class DriveHandler {
     private metaMd5;
     private metaModifiedTime;
     private localDocsEtag;
+    private metaFileId;
+    /** Identifies this handler among the writers sharing a folder. Change-log
+     *  filenames carry it, so two writers can never produce the same name and an
+     *  orphaned log can be traced back to whoever wrote it. Not readonly: if the
+     *  folder shows another writer whose id hashes to our sequence slot, we re-roll
+     *  to a free one before minting anything (see rerollIfSlotContested). */
+    private writerId;
+    /** Change-log file ids this handler wrote, minus any a compaction has retired.
+     *  Drive API v3 has no compare-and-swap (ETags were dropped), so another
+     *  writer's read-modify-write of _meta.json can drop a log id that landed in
+     *  between. Anything still in here but missing from the remote changeLogIds was
+     *  dropped that way and gets put back - see reconcileOwnLogs(). */
+    private ownLogIds;
+    /** This writer's reservation in the low digits of every sequence number it mints.
+     *  Derived from writerId; changes only when writerId is re-rolled off a
+     *  contested slot. */
+    private writerSlot;
+    /** Serializes this handler's own _meta.json read-modify-write cycles. Says
+     *  nothing about other clients - that is what commitMeta's verify pass is for -
+     *  but stops one handler racing itself when several writes are in flight. */
+    private metaLock;
     private index;
     private docCache;
     private pendingChanges;
@@ -48,6 +90,15 @@ export declare class DriveHandler {
      * Index -> Cache -> Fetch
      */
     get(id: string): Promise<any | null>;
+    /**
+     * Fetch a specific (possibly non-winning/conflicting) revision's body by its
+     * own tracked location - used by _get(opts.rev)/_bulkGet when the requested
+     * rev isn't the current winner. Deliberately doesn't touch docCache (keyed
+     * per-id, not per-rev - a conflict fetch is rare enough not to warrant a
+     * per-rev cache key) and doesn't force `_rev` to the index's winning rev the
+     * way get() does.
+     */
+    getRevisionBody(id: string, rev: string, location: FilePointer): Promise<any | null>;
     /** Generic Download with Caching and Parsing */
     private fetchFile;
     /** Get multiple docs (Atomic-ish) used for _allDocs */
@@ -62,21 +113,104 @@ export declare class DriveHandler {
     appendChanges(changes: ChangeEntry[]): Promise<void>;
     private appendLocalDocs;
     private tryAppendChanges;
+    /** Forget a change log we uploaded but never managed to reference from
+     *  _meta.json. Nothing points at it, so it is safe to remove. */
+    private discardLog;
     /** Update Index with a new change */
     private updateIndex;
     private checkConflicts;
     /** Compact: Create SnapshotIndex + SnapshotData */
     compact(): Promise<void>;
-    private atomicUpdateMeta;
+    /** Run `fn` after every meta mutation this handler has already queued has
+     *  settled. Never call this from inside a commitMeta modifier - it would wait on
+     *  itself. */
+    private withMetaLock;
+    private backoff;
+    /** Locate _meta.json and read its body straight from Drive, past every cache. */
+    private readRemoteMeta;
+    /** Read a known _meta.json by id - no folder listing, no cache. Used by the
+     *  post-write verification pass, which only needs the body. */
+    private readMetaBody;
+    private adoptMeta;
+    /** True when the folder holds changes this handler has not replayed - another
+     *  writer appended, or compacted, since our last load. */
+    private hasUnprocessedLogs;
+    /** True when a change log we wrote has fallen out of `changeLogIds` without a
+     *  compaction retiring it - i.e. someone else's write dropped it. */
+    private hasOrphanedOwnLogs;
+    /** Put back any such log. Returns `latest` by identity when there is nothing to
+     *  repair, so callers can tell the two cases apart. */
+    private reconcileOwnLogs;
+    /**
+     * Read-modify-write `_meta.json`.
+     *
+     * `modify` receives the current remote metadata (with any of our dropped logs
+     * already restored, which `repaired` reports) and returns the value to write, or
+     * null to abandon the commit because its assumptions no longer hold. This method
+     * also returns null when it runs out of attempts. Either way nothing durable has
+     * changed and the caller must not act as though it had.
+     */
+    private commitMeta;
+    /** Create _meta.json for a folder that has none. Two clients opening the same
+     *  empty folder both end up here and Drive will happily keep two files with the
+     *  same name, after which every client picks between them at random. Settle it
+     *  deterministically instead: lowest file id wins, the loser deletes its own and
+     *  adopts the winner. */
+    private ensureMetaFile;
     private findOrCreateFolder;
+    /** Every change log in the folder, whatever _meta.json has to say about them.
+     *
+     *  The folder is the authority on which change logs exist; _meta.json is only a
+     *  cache of that, and a lossy one - it is a whole-file read-modify-write with no
+     *  compare-and-swap behind it, so a writer whose metadata lands and is then
+     *  overwritten by a slower writer loses its reference. The file is still right
+     *  here. Listing for it is what stops a lost update from becoming a lost
+     *  document. */
+    private listChangeLogs;
+    /**
+     * Give up a sequence slot another writer is already using.
+     *
+     * Slots make sequence collisions structurally impossible only between writers on
+     * *different* slots; two ids hashing to the same slot are back to the dense
+     * allocation this scheme replaced. The filenames the folder listing hands us
+     * carry every writer's id, so a contested slot is visible - and since this
+     * handler re-rolls before minting anything against what it just saw, the
+     * exposure shrinks from "the whole session" to "rival's first log not yet
+     * visible in a listing".
+     *
+     * Logs already written keep their old name and numbers; ownLogIds tracks file
+     * ids, not names, so nothing else cares.
+     */
+    private rerollIfSlotContested;
+    /** Every file in the folder with this name. Drive allows duplicates, so this is
+     *  how the callers that care (see ensureMetaFile) find out there are any. */
+    private findFiles;
     private findFile;
     private downloadJson;
     private downloadFileAny;
     private downloadNdjson;
     private writeChangeFile;
+    /** Write `meta` to _meta.json. `target` is the file to write, as already
+     *  located by the caller; pass null to force creation, or omit it to look the
+     *  file up. */
     private saveMeta;
     private countTotalChanges;
     private cleanupOldFiles;
+    /**
+     * Watch _meta.json for writes by other clients.
+     *
+     * This is the only thing that makes `db.changes({ live: true })` fire for a
+     * *remote* write: on a change it calls load(), which replays the newly
+     * referenced logs and emits exactly those through notifyListeners. Without it a
+     * client only ever hears about what it wrote itself, so connect-and-read works
+     * and continuous sync between two connected clients does not.
+     *
+     * Change is detected by md5Checksum, falling back to modifiedTime. There is
+     * deliberately no ETag comparison: Drive API v3 has none (see
+     * docs/adr/0001-metadata-writes-without-compare-and-swap.md), so that branch
+     * could only ever compare '' against '' - and sitting first in the chain, it
+     * shadowed the two comparisons that do work.
+     */
     private startPolling;
     private notifyListeners;
     onChange(cb: (changes: Record<string, any>) => void): () => void;