@muhkoo/connect 0.15.0-alpha.3 → 0.15.0-alpha.4

package/dist/connect.d.ts

@@ -4100,14 +4100,36 @@ interface OfflineStore {
  * Replays are idempotent by construction (kv/db are LWW-by-key, messages dedupe
  * by `clientId`, file PUTs are content-addressed), so re-running a partially
  * drained queue is safe.
+ *
+ * Every tab of an origin shares the queue. Given a `tryLock`, a drain runs
+ * only while holding `muhkoo:offline-drain:<commitment>`, so two tabs coming
+ * back online replay it once between them, not once each.
  */
 
 type Replayer = (entry: QueueEntry) => Promise<void>;
+/**
+ * Run `fn` holding lock `name` if no one else holds it: true once it has
+ * run, false - without running it - when another holder has it. Web Locks'
+ * `ifAvailable` in a browser tab; see `core/crossTab.ts`.
+ */
+type TryLock = (name: string, fn: () => Promise<void>) => Promise<boolean>;
+interface OutboundQueueOptions {
+    /**
+     * The lock that keeps two tabs from draining at once. Every tab of an
+     * origin shares one IndexedDB queue, and each replayed all of it when it
+     * came back online: two tabs, every queued write twice. Absent (Node,
+     * tests), every drain runs, as before.
+     */
+    tryLock?: TryLock;
+    /** Whose drain lock to take: the signed-in user's. With no one signed in, the drain runs unlocked. */
+    commitment?: () => string | null;
+}
 declare class OutboundQueue {
     private readonly store;
+    private readonly opts;
     private readonly replayers;
     private draining;
-    constructor(store: OfflineStore);
+    constructor(store: OfflineStore, opts?: OutboundQueueOptions);
     /** A domain registers how to replay its mutations. */
     register(domain: QueueEntry["domain"], replayer: Replayer): void;
     /** Record a mutation for later replay; resolves with its assigned seq. */
@@ -4120,6 +4142,13 @@ declare class OutboundQueue {
      * remaining entries for the next attempt.
      */
     drain(): Promise<void>;
+    /**
+     * One drain, holding the device-wide drain lock where there is one. A
+     * tab that finds another tab holding it leaves the queue to that one,
+     * which is replaying it already and removes each entry as it lands - so
+     * a drain after it finds only what it left.
+     */
+    private drainOnce;
     private runDrain;
 }
 
@@ -4249,6 +4278,12 @@ interface OfflineManagerDeps {
     session: SessionState;
     /** Whether offline support is active (browser) vs a no-op (Node/Workers). */
     enabled: boolean;
+    /**
+     * The drain lock the tabs of this origin share - Web Locks in a browser
+     * tab. Absent, every tab drains the shared queue itself, as before. See
+     * `OutboundQueue`.
+     */
+    locks?: TryLock;
 }
 declare class OfflineManager {
     /** True in browsers with IndexedDB; false when running over a NoopStore. */
@@ -6757,6 +6792,114 @@ declare class VfsLimitError extends Error {
     constructor(limit: VfsLimitError["limit"], max: number, path: string, at: string, doing?: string);
 }
 
+/**
+ * How `client.vfs` orders writes of one directory record between the tabs of
+ * an app on one device. Internal: nothing re-exports this module, and it is
+ * not public API.
+ *
+ * The personal space keeps whichever write of a key arrives last, so two tabs
+ * that each edit a copy of a folder and write it lose one tab's edit. A
+ * coordinator gives every namespace on the device one lock per record, held
+ * from the decision to write until the write has landed or failed, and a
+ * count of each record's writes, which a writer stores before it lets go of
+ * the lock and the next holder reads to tell whether its copy is current.
+ * It also tells the others which record was written, as a hint: that can
+ * reach them after the next holder has decided, or never. And it gives
+ * each file or folder being moved or deleted a lock, which a move or delete
+ * of it elsewhere takes only if it is free, and refuses otherwise (see
+ * `holdMoving`). `Client` builds one
+ * from Web Locks and a BroadcastChannel in a browser tab (see
+ * `core/crossTab.ts`); without one, writes are ordered within one namespace
+ * only, as they always were.
+ */
+interface VfsCoordinator {
+    /**
+     * Run `fn` holding the device-wide lock for record `id`, and settle as it
+     * does. Where the runtime refuses the lock to this document, as it then
+     * does to every tab of the app, `fn` runs without it.
+     */
+    lock<T>(id: string, fn: () => Promise<T>): Promise<T>;
+    /** Tell every other namespace that this one has just written record `id`. Called while holding its lock. */
+    announce(id: string): void;
+    /**
+     * Call `handler` with the id of each record another namespace announces -
+     * or with null when announcements may have been missed, because this one
+     * has only just started hearing them, or now hears them for someone else,
+     * so that every record held must be taken as written elsewhere. Returns a
+     * function that stops it.
+     */
+    onAnnounce(handler: (id: string | null) => void): () => void;
+    /**
+     * Make sure announcements for whoever is signed in now are being heard.
+     * Cheap; called before every read of a record from the store, so that
+     * nothing is read before this namespace can hear of a later write of it.
+     */
+    listen(): void;
+    /**
+     * How often each record in `ids` has been written by any namespace on
+     * the device, for whoever is signed in: one counter each, in order, read
+     * at one moment from storage every tab of the app shares (IndexedDB, in
+     * a browser). Null where it cannot be told: the storage cannot be read,
+     * or does not answer within a few seconds, or a write of the record has
+     * begun and not been counted (see `begin`). Never rejects.
+     *
+     * A copy of a record fetched after its counter was read holds every
+     * write the counter counts. Read again once its holder has taken a lock
+     * that another tab held while it wrote the record - the record's own, or
+     * a move lock - a counter that has not moved says no other tab has
+     * written it since: unlike an announcement, a count is stored before
+     * the writer lets go of its locks. See `VfsNamespace.sendLocked`.
+     */
+    counters(ids: readonly string[]): Promise<Array<string | null>>;
+    /**
+     * Called holding record `id`'s lock, before deciding whether a copy of it
+     * is current: its counter as the last tab to write it left it - one whose
+     * write began and was never counted, which no copy holds, included. And
+     * from then, stored with it, a mark that a write of it has begun, which
+     * `counters` reports as null until `bump`: a tab that goes, or cannot
+     * count its write, in between leaves every tab reading the record again.
+     * Null when the storage could not be read and marked within a few
+     * seconds. Never rejects.
+     */
+    begin(id: string): Promise<string | null>;
+    /**
+     * Called holding record `id`'s lock, after `begin`, once the write has
+     * landed or failed, or nothing was written after all: count it, and
+     * resolve to the record's new counter once that is stored - so before
+     * the lock is let go of. Null when it could not be stored within a few
+     * seconds. Never rejects.
+     */
+    bump(id: string): Promise<string | null>;
+    /**
+     * Hold the lock that says entry `id` - a file or a folder, by its id in
+     * the tree - is being moved or deleted on this device, if no one holds
+     * it. Never waits: resolves to null when another holder has it, in this
+     * tab or another, and otherwise to the function that lets go of it. A
+     * tab that dies lets go of everything it held. With no one signed in it
+     * holds nothing, and resolves to a function that does nothing; so too
+     * where the runtime refuses the lock to this document, as it then does
+     * to every tab of the app.
+     *
+     * `shared` holds a folder's lock as a place on the way to where a move
+     * is putting something. Any number of shared holders hold it at once,
+     * in any tab; a holder that is not shared cannot have it while they do,
+     * nor they while it does.
+     *
+     * A move marks its entry before it puts it in its second place, and a
+     * mark cannot tell a move still writing from one that was interrupted.
+     * Another tab took the first for the second: it finished the move too,
+     * naming the entry in two places, or let go of what the move was about
+     * to put somewhere else. So a move holds this from before it marks until
+     * it has taken the entry from where it was, a delete holds it for all it
+     * is deleting, and either refuses when it cannot have it. A move also
+     * holds the folder it is moving into, and every folder above that one,
+     * shared, for as long: a move into a folder that another tab was
+     * deleting put what it moved in a record the delete then purged. See
+     * `VfsNamespace.rename` and `VfsNamespace.delete`.
+     */
+    holdMoving(id: string, shared?: boolean): Promise<(() => void) | null>;
+}
+
 /**
  * `client.vfs` — a real filesystem over Muhkoo primitives.
  *
@@ -6769,21 +6912,25 @@ declare class VfsLimitError extends Error {
  *
  * Every mutation is a read-modify-write of exactly ONE directory record, so a
  * write cannot leave the tree half-updated: either the parent names the new
- * child or it does not. Two tabs writing different directories never conflict;
- * two tabs (or devices) writing the SAME directory are last-writer-wins. A VFS
- * write sends no HLC and the personal space has no compare-and-swap: it applies
- * puts of one key in the order they arrive, so whichever arrives last is kept,
- * and the other tab's edit is lost. Orphaned records (a directory whose parent
- * entry lost the race) are unreachable rather than corrupting — they cost
- * storage until a future sweep, which is the trade this shape makes in
+ * child or it does not. A VFS write sends no HLC and the personal space has
+ * no compare-and-swap: of two writes of one key it keeps whichever arrives
+ * last.
+ *
+ * Within ONE namespace, writes of a record are sent one at a time, in the
+ * order they were made - edits made while one is in flight go out together
+ * in the next (see `queue`) - and a read that has to fetch a record waits for
+ * its write in flight (see `writing`). Every edit of a record is made to one
+ * in-memory copy of it, and that copy is what is written (see `mutate`).
+ *
+ * Between the tabs of an app on one device, a coordinator (`VfsCoordinator`;
+ * `Client` wires one in a browser tab) gives each record one lock, and a tab
+ * reads a record another tab has written again before its next write of it
+ * (see `sendLocked`). Between devices - or a browser and the CLI - two writes
+ * of the same directory are still last-writer-wins, and the other edit is
+ * lost: that takes a compare-and-swap at the server. Orphaned records (a
+ * directory whose parent entry lost the race) are unreachable rather than
+ * corrupting - they cost storage until a sweep, the trade this shape makes in
  * exchange for single-record writes.
- *
- * Within ONE tab, writes of a record are queued and sent one at a time, in the
- * order they were made, and a read that has to fetch a record waits for its
- * write in flight (see `writing`). Every edit of a record is made to one
- * in-memory copy of it, and that copy is what is written (see `mutate`). All
- * of this is per namespace instance only; nothing orders writes across tabs
- * or devices - that would take a compare-and-swap at the server.
  */
 
 /**
@@ -6849,6 +6996,13 @@ interface VfsNamespaceDeps {
         entries?: number;
         pathChars?: number;
     };
+    /**
+     * Orders writes of a record with the other tabs of this app on the
+     * device. `Client` passes one in a browser tab; without it - Node, a
+     * test, a runtime with no Web Locks - writes are ordered within this
+     * namespace only. See `VfsCoordinator`.
+     */
+    coordinator?: VfsCoordinator;
 }
 declare class VfsNamespace {
     private readonly deps;
@@ -6892,6 +7046,81 @@ declare class VfsNamespace {
      * `openDirById`.
      */
     private readonly writing;
+    /**
+     * Every entry this namespace is moving right now, by id.
+     *
+     * A move between two directories marks the entry before it puts it in
+     * the second (see `rename`), and a mark is all a later operation can
+     * see. It cannot tell a move still writing from one that was
+     * interrupted, and was taken for the second: a delete that began after
+     * a move had marked a folder looked for the folder's other half, found
+     * none yet, and purged it while the move was putting it in its new
+     * place; a second move of a file finished the "interrupted" move and
+     * left it named in two places. So a move holds its entry here until it
+     * has taken it from where it was, and `rename` and `delete` refuse an
+     * entry that is here - or, for a delete, a folder holding one. A delete
+     * holds what it deletes the same way: see `deleting`.
+     *
+     * This set is one namespace's. With a coordinator, a move also holds
+     * the entry's move lock for every tab on the device, for as long as the
+     * entry is here: see `VfsCoordinator.holdMoving`.
+     */
+    private readonly inMotion;
+    /**
+     * What each delete under way in this namespace is deleting, by entry id,
+     * one set per delete: its target from the moment it has found the target
+     * not in `inMotion`, and everything it read below the target once it has
+     * read it. Each delete lets go of its own set when it is done.
+     *
+     * A delete waits after it has read what it will let go of: on more
+     * reads, and on a read of the whole tree for the other half of a move.
+     * A move of any of it that started meanwhile could put it in its new
+     * place, fail to take it from the old, and end, all before the delete's
+     * detach. Ended, it was no longer in `inMotion`; and an entry that was
+     * marked already showed no change. So the delete let go of what the
+     * move had just named somewhere else. Now `rename` refuses an entry that
+     * is here, or one on a way from the root that passes through a folder
+     * that is: everything below a delete's target, read yet or not.
+     */
+    private readonly deleting;
+    /**
+     * The write of each record that has not gone out yet, by id: the one
+     * the next edit of that record joins. See `queue`.
+     */
+    private readonly waiting;
+    /**
+     * Announcements heard from other tabs, counted. `heardAt` is the count
+     * at the last one for each record, `missedAt` the count when some may
+     * have been missed. A copy read after both holds every write announced:
+     * see `current`.
+     */
+    private hearing;
+    private missedAt;
+    private readonly heardAt;
+    /**
+     * Each record a write of which this namespace marked as begun and could
+     * not count, and has said so, until one is counted. And whether it has
+     * said that a write it could not mark or count may be lost, which it
+     * says only once. See `notCounted`.
+     */
+    private readonly uncounted;
+    private lossWarned;
+    /**
+     * The copy of each record this namespace is writing under the record's
+     * lock, by id, from when it has decided what to write until it has
+     * counted the write, or failed to. Its counter reads as unknown
+     * meanwhile, as this write has begun and is not counted yet, but the
+     * copy holds every write of the record another tab has counted, and no
+     * other tab can make one until this one lets go of the lock. See
+     * `dropStale`.
+     */
+    private readonly locked;
+    /**
+     * Each directory a `createDir` here has named whose write has not landed
+     * yet, by entry id: a promise that settles - and never rejects - once
+     * that write has landed or failed. See `mkdir`.
+     */
+    private readonly naming;
     private readonly historyLimit;
     private readonly maxEntries;
     private readonly maxPathChars;
@@ -7113,11 +7342,12 @@ declare class VfsNamespace {
      * Delete metadata records no longer reachable from the root.
      *
      * These accumulate because every write touches exactly one record: if two
-     * tabs or devices edit the same directory, the personal space keeps
-     * whichever put arrives last (a VFS write sends no HLC, and the space
-     * applies puts of one key in arrival order), which can leave a child whose
-     * parent entry lost the race. The per-record write queue (`writing`) only
-     * orders writes within one tab. Unreachable is harmless —
+     * devices edit the same directory - or two tabs, where there is no
+     * coordinator - the personal space keeps whichever put arrives last (a
+     * VFS write sends no HLC, and the space applies puts of one key in arrival
+     * order), which can leave a child whose parent entry lost the race. The
+     * per-record queue and the coordinator order writes within one device
+     * only. Unreachable is harmless —
      * it is invisible and undecryptable-by-nobody — but it costs storage, so
      * this reclaims it.
      *
@@ -7157,6 +7387,15 @@ declare class VfsNamespace {
      * the error names whichever asked first.
      */
     private openDirById;
+    /**
+     * Fetch record `id` from the store and open it. Whatever another tab
+     * announced before the fetch began is in what it returns (see
+     * `current`), and so is every write its counter counts: read here, or
+     * given as `counter` (see `OpenDir.counter`).
+     */
+    private fetchRecord;
+    /** Record `id`'s write counter now: see `OpenDir.counter`. */
+    private counterOf;
     /**
      * Turn a decrypted record into an OpenDir, or throw.
      *
@@ -7179,8 +7418,18 @@ declare class VfsNamespace {
      *
      * So `edit` must take what it writes from the record it is given, not
      * from anything read off `dir` before an await - and re-check whatever it
-     * relies on from then, throwing if another write changed it. Returning
-     * false writes nothing after all.
+     * relies on from then, throwing if another write changed it, before it
+     * changes anything. Returning false writes nothing after all.
+     *
+     * The write that carries the edit may carry others, made while an
+     * earlier write of the record was in flight (see `queue`): it lands, or
+     * fails, for all of them at once.
+     *
+     * With a coordinator, the edit may be made a second time, to the record
+     * as another tab left it, and refused then (see `replay`): an edit must
+     * check everything before it changes anything, and whatever it sets
+     * outside `node` and `record` must be safe to set again, since each run
+     * overwrites the last.
      */
     private mutate;
     /**
@@ -7206,6 +7455,112 @@ declare class VfsNamespace {
     private reopen;
     /** Make `dir` the cached copy of its record - unless the cache has been cleared since it was read. */
     private adopt;
+    /** After an edit of `copy`: its time, and any entry it cannot read that the edit replaced. */
+    private touch;
+    /**
+     * The write that will carry the edit just made to `copy`.
+     *
+     * Writes of a record go out one at a time, each once the one before it
+     * has landed or failed (see `writing`), and each seals the record as it
+     * stands when it goes out. So a write still waiting carries every edit
+     * made while it waits, and an edit made then joins it instead of
+     * queueing a write of its own: a burst of edits of one directory while a
+     * write of it is in flight costs two writes, not one per edit. Each is a
+     * billed write; a 20-file upload into one folder cost twenty.
+     */
+    private queue;
+    /**
+     * Send `batch`: from here on, an edit of its record goes in the next
+     * write. With a coordinator, holding the lock every tab of the device
+     * takes to write this record - see `sendLocked`.
+     */
+    private send;
+    /** Stop `batch` taking more edits, as it is sealed. */
+    private close;
+    /**
+     * Send `batch` while no other tab can write its record.
+     *
+     * If another tab wrote the record since this copy was read, the copy is
+     * out of date, and writing it would undo that tab's write. So it is read
+     * again, here, under the lock, and every edit the batch carries is made
+     * again to what was read (see `replay`). A copy no other tab has written
+     * over is sent as it is: one tab on its own costs no extra request.
+     *
+     * Which it is, the record's write counter says (see
+     * `VfsCoordinator.counters`). Read once the lock is granted, it counts
+     * every write of the record another tab made, because each counts its
+     * write, and waits for the count to be stored, before it lets go of the
+     * lock. If it has moved since the copy was read, or cannot be told, the
+     * copy is read again. Whether this tab has heard of another tab's write
+     * does not decide it: an announcement can reach this tab after the
+     * lock does, or never. One it has heard of can only add a read.
+     *
+     * The write is counted once it has landed or failed - one that failed
+     * may have landed even so - and the other tabs are then told of it,
+     * all before the lock is let go of.
+     */
+    private sendLocked;
+    /**
+     * Say that a write of `copy`'s record could not be counted.
+     *
+     * `marked`: `VfsCoordinator.begin` stored its mark, which stays until a
+     * count can be stored, so every tab reads the record again before it
+     * writes it. Said once for each record, until a write of it is counted.
+     *
+     * Not marked, a tab whose IndexedDB works may take its copy for current
+     * and write it over this write. Said once for this namespace, whatever
+     * the record: where IndexedDB cannot be used at all, no write of any
+     * folder is counted, and a warning for each said nothing new. And only
+     * where another tab can count its writes can one be lost, which the
+     * warning says: where no tab can, every tab reads each folder again.
+     */
+    private notCounted;
+    /**
+     * Make every edit in `batch` again, in order, to `fresh` - the record as
+     * another tab left it - and make that the copy. An edit that no longer
+     * applies throws, as it would have the first time, and is left out; its
+     * caller gets what it threw. Every edit checks before it changes
+     * anything (see `mutate`), so one that throws has changed nothing. True
+     * when what is left changes the record, and so needs writing.
+     */
+    private replay;
+    /**
+     * Another tab wrote record `id` - or, null, this namespace may have
+     * missed some announcements. What the cache holds is read again when
+     * next asked for, as a change frame from the personal space would have
+     * it, and a copy read before then is read again before the next write
+     * of its record (see `current`). A hint, not a guarantee: an
+     * announcement can reach this tab after the next lock does, or never.
+     * What decides whether a copy may be written over, or relied on under a
+     * move's or a delete's locks, is the record's counter: see `sendLocked`
+     * and `dropStale`.
+     */
+    private heard;
+    /**
+     * Does `copy` hold every write of its record another tab has announced
+     * that this one has heard of? See `heard`. Only ever a reason to read it
+     * again, never to take it for current: see `sendLocked`.
+     */
+    private current;
+    /**
+     * Drop from the cache every copy of a record in `ids` that may not hold
+     * every write of it another tab has made: its counter has moved since
+     * the copy was read, or cannot be told, or the copy is still being read.
+     * Returns every id whose copy here is not known to be current - those,
+     * and those not cached - so that the next read of each fetches it again,
+     * once any write of it in flight here has landed or failed. Not a copy
+     * this tab is writing under its lock (see `locked`): its counter reads
+     * as unknown only because that write is not counted yet, and dropped,
+     * the next read would wait for the write.
+     *
+     * The counters are read in one go, after the caller has taken the locks
+     * it relies on: another tab counts each write of a record before it lets
+     * go of the locks it held while writing it, the record's own and any
+     * move lock, so what it wrote before letting go of one of them is
+     * counted by then. Its announcements may not have reached this tab yet,
+     * or ever. See `sendLocked`.
+     */
+    private dropStale;
     /**
      * Seal a directory record as it stands NOW and put it in the store.
      *
@@ -7230,8 +7585,44 @@ declare class VfsNamespace {
      *
      * `moving` says whether anything in it is marked as half of an
      * interrupted move, which is what makes a delete look for the other half.
+     *
+     * `ids` is every entry id in it, and `shape` what each record named when
+     * it was read: see `currentSubtree`.
      */
     private subtree;
+    /**
+     * The records a recursive delete read, as they are now - or null when
+     * one has changed since in a way that purging it would get wrong.
+     *
+     * The delete decided what to let go of, and whether to look for the
+     * other half of a move, from what it read; then it waited, on reads and
+     * on the write of its parent. A record that is no longer named by the
+     * record it was read in has been moved out, and is not this delete's to
+     * purge; an entry marked since it was read is being moved, and is about
+     * to be named somewhere the delete never looked. Purging either purged
+     * the folder a move had just put somewhere else. Anything else - a file
+     * saved into one of them, or moved out - is purged as it now stands,
+     * which is why the copies to purge are what this returns.
+     *
+     * Synchronous, for an edit. A record whose copy is not to hand counts as
+     * changed.
+     *
+     * `held`, with a coordinator, is every entry whose move lock the delete
+     * holds. An entry named since the records were read - saved or moved in
+     * - is not among them, so nothing stops another tab moving it out while
+     * the delete writes the parent, and purging it then let go of what that
+     * move had put somewhere else. So with `held`, that counts as changed
+     * too, and the delete is tried again from the start.
+     */
+    private currentSubtree;
+    /**
+     * Hold the move lock of every entry in `ids` - see
+     * `VfsCoordinator.holdMoving` - or of none: null when another holder has
+     * any of them, and then nothing is held. Otherwise the function that
+     * lets go of them all. Asked for all at once: none of them waits.
+     * `shared` holds them as the folders a move goes into.
+     */
+    private holdAll;
     /**
      * Delete these records and let go of every file in them. The second half
      * of a recursive delete, run only once the subtree is detached. Cannot
@@ -9102,7 +9493,7 @@ declare function getId(row: {
  * expect (and isn't serving a stale cached bundle). Keep this in sync with
  * `package.json` `version`.
  */
-declare const VERSION = "0.15.0-alpha.3";
+declare const VERSION = "0.15.0-alpha.4";
 
 /**
  * The SDK's process-global logger.