@vrtmrz/livesync-commonlib 0.1.15 → 0.1.16

package/dist/replication/couchdb/LiveSyncReplicator.d.ts

@@ -1,10 +1,31 @@
 import { type EntryDoc, type RemoteDBSettings, type EntryLeaf, type SyncParameters, type DatabaseEntry, type NodeData, type RemotePreferredTweakResult } from "../../common/types.js";
 import { LiveSyncAbstractReplicator, type LiveSyncReplicatorEnv, type RemoteDBStatus } from "../LiveSyncAbstractReplicator.js";
 import type { ServiceHub } from "../../services/ServiceHub.js";
+import type { OwnedCouchDBConnection, RemoteConnectionOpenOptions } from "../../services/base/RemoteConnection.js";
+export type { OwnedCouchDBConnection, RemoteConnectionOpenOptions } from "../../services/base/RemoteConnection.js";
 export interface LiveSyncCouchDBReplicatorEnv extends LiveSyncReplicatorEnv {
     services: ServiceHub;
+    /** Internal injection point for the bounded one-shot connectivity preflight. */
+    oneShotConnectivityTimeoutMs?: number;
+}
+/**
+ * An owned CouchDB connection which has passed LiveSync's compatibility checks
+ * and carries the options required to start replication.
+ *
+ * @remarks
+ * The caller must transfer ownership or call
+ * {@link OwnedCouchDBConnection.close}.
+ * The connection retains the same `close()` implementation while compatibility
+ * checks add replication options to it.
+ */
+export interface CouchDBReplicationConnection extends OwnedCouchDBConnection<EntryDoc> {
+    /** Base options shared by finite and continuous replication. */
+    readonly syncOptionBase: PouchDB.Replication.SyncOptions;
+    /** Options selected for the requested finite or continuous replication. */
+    readonly syncOption: PouchDB.Replication.SyncOptions;
 }
 export declare class LiveSyncCouchDBReplicator extends LiveSyncAbstractReplicator {
+    env: LiveSyncCouchDBReplicatorEnv;
     isMobile(): boolean;
     constructor(env: LiveSyncCouchDBReplicatorEnv);
     getInitialSyncParameters(setting: RemoteDBSettings): Promise<SyncParameters>;
@@ -32,26 +53,28 @@ export declare class LiveSyncCouchDBReplicator extends LiveSyncAbstractReplicato
     updateMaxTransferredSeqOnChunks(localDB: PouchDB.Database, remoteID: number, seqStatusMap: Record<number, boolean>): Promise<ReturnType<typeof this.getEmptyMaxEntry>>;
     sendChunks(setting: RemoteDBSettings, remoteDB: PouchDB.Database<EntryDoc> | undefined, showResult: boolean, fromSeq?: number | string): Promise<boolean>;
     openOneShotReplication(setting: RemoteDBSettings, showResult: boolean, retrying: boolean, syncMode: "sync" | "pullOnly" | "pushOnly", ignoreCleanLock?: boolean): Promise<boolean>;
-    private closeRemoteDatabase;
-    private withRemoteDatabase;
+    private checkOneShotReplicationConnectivity;
+    private closeRemoteConnection;
+    private withRemoteConnection;
     replicateAllToServer(setting: RemoteDBSettings, showingNotice?: boolean): Promise<boolean>;
     replicateAllFromServer(setting: RemoteDBSettings, showingNotice?: boolean): Promise<boolean>;
-    checkReplicationConnectivity(setting: RemoteDBSettings, keepAlive: boolean, skipCheck: boolean, showResult: boolean, ignoreCleanLock?: boolean): Promise<false | {
-        db: PouchDB.Database<EntryDoc>;
-        info: PouchDB.Core.DatabaseInfo;
-        syncOptionBase: PouchDB.Replication.SyncOptions;
-        syncOption: PouchDB.Replication.SyncOptions;
-    }>;
+    private reportConnectivityPreflightTimeout;
+    checkReplicationConnectivity(setting: RemoteDBSettings, keepAlive: boolean, skipCheck: boolean, showResult: boolean, ignoreCleanLock?: boolean, connectionOptions?: RemoteConnectionOpenOptions): Promise<false | CouchDBReplicationConnection>;
     openContinuousReplication(setting: RemoteDBSettings, showResult: boolean, retrying: boolean): Promise<boolean>;
     closeReplication(): void;
     tryResetRemoteDatabase(setting: RemoteDBSettings): Promise<void>;
     tryCreateRemoteDatabase(setting: RemoteDBSettings): Promise<void>;
     markRemoteLocked(setting: RemoteDBSettings, locked: boolean, lockByClean: boolean): Promise<void>;
     markRemoteResolved(setting: RemoteDBSettings): Promise<void>;
-    connectRemoteCouchDBWithSetting(settings: RemoteDBSettings, isMobile: boolean, performSetup?: boolean, skipInfo?: boolean): Promise<string | {
-        db: PouchDB.Database<EntryDoc>;
-        info: PouchDB.Core.DatabaseInfo;
-    }> | "Empty passphrases cannot be used without explicit permission";
+    connectRemoteCouchDBWithSetting(settings: RemoteDBSettings, isMobile: boolean, performSetup?: boolean, skipInfo?: boolean, connectionOptions?: RemoteConnectionOpenOptions): Promise<string | OwnedCouchDBConnection<EntryDoc>> | "Empty passphrases cannot be used without explicit permission";
+    private openOwnedConnection;
+    /**
+     * Opens a raw PouchDB handle for compatibility with earlier Commonlib
+     * consumers.
+     *
+     * @deprecated Use {@link connectRemoteCouchDBWithSetting} and close the
+     * complete owned connection after use.
+     */
     _ensureConnection<T extends DatabaseEntry>(settings: RemoteDBSettings, performSetup?: boolean): Promise<PouchDB.Database<T>>;
     /**
      * Fetch a document from the remote database directly.

package/dist/replication/couchdb/LiveSyncReplicator.js

@@ -41,12 +41,20 @@ import {
   SyncParamsNotFoundError,
   SyncParamsUpdateError
 } from "../SyncParamsHandler.js";
+import { compatGlobal } from "../../common/coreEnvFunctions.js";
 const currentVersionRange = {
   min: 0,
   max: 2400,
   current: 2
 };
 const selectorOnDemandPull = { selector: { type: { $ne: "leaf" } } };
+const DEFAULT_ONE_SHOT_CONNECTIVITY_TIMEOUT_MS = 6e4;
+class OneShotConnectivityPreflightTimeoutError extends Error {
+  constructor(timeoutMs) {
+    super(`Remote connectivity preflight exceeded ${timeoutMs} ms.`);
+    this.name = "OneShotConnectivityPreflightTimeoutError";
+  }
+}
 async function* genReplication(s, signal) {
   const inbox = new StreamInbox({ capacity: 1e4 });
   const push = function(e) {
@@ -379,11 +387,11 @@ class LiveSyncCouchDBReplicator extends LiveSyncAbstractReplicator {
         );
         return false;
       }
-      return await this.withRemoteDatabase(d.db, async (db) => this.sendChunks(setting, db, showResult, fromSeq));
+      return await this.withRemoteConnection(d, async (db) => this.sendChunks(setting, db, showResult, fromSeq));
     }
     const connectivity = await this.checkReplicationConnectivity(setting, false, false, false, false);
     if (connectivity !== false) {
-      await this.closeRemoteDatabase(connectivity.db);
+      await this.closeRemoteConnection(connectivity);
     }
     Logger(`Bulk sending chunks to remote database...`, showResult ? LOG_LEVEL_NOTICE : LOG_LEVEL_INFO, "fetch");
     const remoteMilestone = await remoteDB.get(MILESTONE_DOCID);
@@ -534,7 +542,7 @@ ${sendingDocs}/(${sentDocsCount} done)`,
       }
       const localDB = this.rawDatabase;
       Logger(this.translate("liveSyncReplicator.oneShotSyncBegin", { syncMode }));
-      const ret = await this.checkReplicationConnectivity(setting, false, retrying, showResult, ignoreCleanLock);
+      const ret = await this.checkOneShotReplicationConnectivity(setting, retrying, showResult, ignoreCleanLock);
       if (ret === false) {
         Logger(
           this.translate("liveSyncReplicator.couldNotConnectToServer"),
@@ -613,7 +621,7 @@ ${sendingDocs}/(${sentDocsCount} done)`,
         }
         return false;
       } finally {
-        await this.closeRemoteDatabase(db);
+        await this.closeRemoteConnection(ret);
       }
     });
     if (typeof next === "boolean") {
@@ -621,21 +629,38 @@ ${sendingDocs}/(${sentDocsCount} done)`,
     }
     return await next();
   }
-  // One-shot attempts own their temporary remote handle. Continuous replication
-  // keeps its handle until the replication controller terminates it.
-  async closeRemoteDatabase(db) {
+  async checkOneShotReplicationConnectivity(setting, skipCheck, showResult, ignoreCleanLock) {
+    if (setting.useRequestAPI) {
+      return await this.checkReplicationConnectivity(setting, false, skipCheck, showResult, ignoreCleanLock);
+    }
+    const timeoutMs = this.env.oneShotConnectivityTimeoutMs ?? DEFAULT_ONE_SHOT_CONNECTIVITY_TIMEOUT_MS;
+    const controller = new AbortController();
+    const timeout = compatGlobal.setTimeout(
+      () => controller.abort(new OneShotConnectivityPreflightTimeoutError(timeoutMs)),
+      timeoutMs
+    );
+    try {
+      return await this.checkReplicationConnectivity(setting, false, skipCheck, showResult, ignoreCleanLock, {
+        signal: controller.signal,
+        allowNativeFallback: false
+      });
+    } finally {
+      compatGlobal.clearTimeout(timeout);
+    }
+  }
+  async closeRemoteConnection(connection) {
     try {
-      await db.close();
+      await connection.close();
     } catch (ex) {
       Logger("Failed to close remote database.", LOG_LEVEL_INFO, "sync");
       Logger(ex, LOG_LEVEL_VERBOSE, "sync");
     }
   }
-  async withRemoteDatabase(db, task) {
+  async withRemoteConnection(connection, task) {
     try {
-      return await task(db);
+      return await task(connection.db);
     } finally {
-      await this.closeRemoteDatabase(db);
+      await this.closeRemoteConnection(connection);
     }
   }
   replicateAllToServer(setting, showingNotice) {
@@ -644,7 +669,17 @@ ${sendingDocs}/(${sentDocsCount} done)`,
   replicateAllFromServer(setting, showingNotice) {
     return this.openOneShotReplication(setting, showingNotice ?? false, false, "pullOnly");
   }
-  async checkReplicationConnectivity(setting, keepAlive, skipCheck, showResult, ignoreCleanLock = false) {
+  reportConnectivityPreflightTimeout(connectionOptions, showResult, error) {
+    if (!connectionOptions?.signal?.aborted || !(connectionOptions.signal.reason instanceof OneShotConnectivityPreflightTimeoutError)) {
+      return false;
+    }
+    Logger("The remote connectivity check timed out.", showResult ? LOG_LEVEL_NOTICE : LOG_LEVEL_INFO, "sync");
+    if (error !== void 0) {
+      Logger(error, LOG_LEVEL_VERBOSE, "sync");
+    }
+    return true;
+  }
+  async checkReplicationConnectivity(setting, keepAlive, skipCheck, showResult, ignoreCleanLock = false, connectionOptions) {
     if (setting.versionUpFlash != "") {
       Logger(this.translate("Replicator.Message.VersionUpFlash"), LOG_LEVEL_NOTICE);
       return false;
@@ -654,8 +689,25 @@ ${sendingDocs}/(${sentDocsCount} done)`,
       Logger("Another replication running.");
       return false;
     }
-    const dbRet = await this.connectRemoteCouchDBWithSetting(setting, this.isMobile(), true);
+    let dbRet;
+    try {
+      dbRet = await this.connectRemoteCouchDBWithSetting(
+        setting,
+        this.isMobile(),
+        true,
+        false,
+        connectionOptions
+      );
+    } catch (ex) {
+      if (this.reportConnectivityPreflightTimeout(connectionOptions, showResult, ex)) {
+        return false;
+      }
+      throw ex;
+    }
     if (typeof dbRet === "string") {
+      if (this.reportConnectivityPreflightTimeout(connectionOptions, showResult)) {
+        return false;
+      }
       Logger(
         this.translate("liveSyncReplicator.couldNotConnectToURI", { uri, dbRet }),
         showResult ? LOG_LEVEL_NOTICE : LOG_LEVEL_INFO
@@ -734,13 +786,25 @@ ${sendingDocs}/(${sentDocsCount} done)`,
       if (setting.readChunksOnline) {
         syncOptionBase.pull = { ...selectorOnDemandPull };
       }
+      if (this.reportConnectivityPreflightTimeout(connectionOptions, showResult)) {
+        return false;
+      }
       const syncOption = keepAlive ? { live: true, retry: true, heartbeat: setting.useTimeouts ? false : 3e4, ...syncOptionBase } : { ...syncOptionBase };
-      const connection = { db: dbRet.db, info: dbRet.info, syncOptionBase, syncOption };
+      const connection = {
+        ...dbRet,
+        syncOptionBase,
+        syncOption
+      };
       ownershipTransferred = true;
       return connection;
+    } catch (ex) {
+      if (this.reportConnectivityPreflightTimeout(connectionOptions, showResult, ex)) {
+        return false;
+      }
+      throw ex;
     } finally {
       if (!ownershipTransferred) {
-        await this.closeRemoteDatabase(dbRet.db);
+        await this.closeRemoteConnection(dbRet);
       }
     }
   }
@@ -828,7 +892,7 @@ ${sendingDocs}/(${sentDocsCount} done)`,
             }
           }
         } finally {
-          await this.closeRemoteDatabase(db);
+          await this.closeRemoteConnection(ret);
         }
       }
       return false;
@@ -862,7 +926,7 @@ ${sendingDocs}/(${sentDocsCount} done)`,
         Logger(ex, LOG_LEVEL_NOTICE);
       }
     } finally {
-      await this.closeRemoteDatabase(con.db);
+      await this.closeRemoteConnection(con);
     }
     clearHandlers();
     await this.ensurePBKDF2Salt(setting, true, false);
@@ -871,7 +935,7 @@ ${sendingDocs}/(${sentDocsCount} done)`,
     this.closeReplication();
     const con2 = await this.connectRemoteCouchDBWithSetting(setting, this.isMobile(), true);
     if (typeof con2 === "string") return;
-    await this.closeRemoteDatabase(con2.db);
+    await this.closeRemoteConnection(con2);
     clearHandlers();
     await this.ensurePBKDF2Salt(setting, true, false);
     Logger(this.translate("liveSyncReplicator.remoteDbCreatedOrConnected"), LOG_LEVEL_NOTICE);
@@ -883,7 +947,7 @@ ${sendingDocs}/(${sentDocsCount} done)`,
       Logger(this.translate("liveSyncReplicator.couldNotConnectToURI", { uri, dbRet }), LOG_LEVEL_NOTICE);
       return;
     }
-    await this.withRemoteDatabase(dbRet.db, async (db) => {
+    await this.withRemoteConnection(dbRet, async (db) => {
       if (!await checkRemoteVersion(db, this.migrate.bind(this), VER)) {
         Logger(this.translate("liveSyncReplicator.remoteDbCorrupted"), LOG_LEVEL_NOTICE);
         return;
@@ -922,7 +986,7 @@ ${sendingDocs}/(${sentDocsCount} done)`,
       Logger(this.translate("liveSyncReplicator.couldNotConnectToURI", { uri, dbRet }), LOG_LEVEL_NOTICE);
       return;
     }
-    await this.withRemoteDatabase(dbRet.db, async (db) => {
+    await this.withRemoteConnection(dbRet, async (db) => {
       if (!await checkRemoteVersion(db, this.migrate.bind(this), VER)) {
         Logger(this.translate("liveSyncReplicator.remoteDbCorrupted"), LOG_LEVEL_NOTICE);
         return;
@@ -952,7 +1016,7 @@ ${sendingDocs}/(${sentDocsCount} done)`,
       }
     });
   }
-  connectRemoteCouchDBWithSetting(settings, isMobile, performSetup = false, skipInfo = false) {
+  connectRemoteCouchDBWithSetting(settings, isMobile, performSetup = false, skipInfo = false, connectionOptions) {
     if (settings.encrypt && settings.passphrase == "" && !settings.permitEmptyPassphrase) {
       return "Empty passphrases cannot be used without explicit permission";
     }
@@ -980,15 +1044,26 @@ ${sendingDocs}/(${sentDocsCount} done)`,
       settings.enableCompression,
       customHeaders,
       settings.useRequestAPI,
-      async () => await this.getReplicationPBKDF2Salt(settings)
+      async () => await this.getReplicationPBKDF2Salt(settings),
+      connectionOptions
     );
   }
-  async _ensureConnection(settings, performSetup = false) {
+  async openOwnedConnection(settings, performSetup = false) {
     const ret = await this.connectRemoteCouchDBWithSetting(settings, this.isMobile(), performSetup, true);
     if (typeof ret === "string") {
       throw new Error(`${this.translate("liveSyncReplicator.couldNotConnectToServer")}:${ret}`);
     }
-    return ret.db;
+    return ret;
+  }
+  /**
+   * Opens a raw PouchDB handle for compatibility with earlier Commonlib
+   * consumers.
+   *
+   * @deprecated Use {@link connectRemoteCouchDBWithSetting} and close the
+   * complete owned connection after use.
+   */
+  async _ensureConnection(settings, performSetup = false) {
+    return (await this.openOwnedConnection(settings, performSetup)).db;
   }
   /**
    * Fetch a document from the remote database directly.
@@ -999,8 +1074,8 @@ ${sendingDocs}/(${sentDocsCount} done)`,
    * @throws {Error} Other errors that may occur during the fetch operation.
    */
   async fetchRemoteDocument(settings, id, db) {
-    const ownsConnection = db === void 0;
-    const connDB = db ?? await this._ensureConnection(settings);
+    const connection = db === void 0 ? await this.openOwnedConnection(settings) : void 0;
+    const connDB = db ?? connection.db;
     try {
       return await connDB.get(id);
     } catch (ex) {
@@ -1009,8 +1084,8 @@ ${sendingDocs}/(${sentDocsCount} done)`,
       }
       throw ex;
     } finally {
-      if (ownsConnection) {
-        await this.closeRemoteDatabase(connDB);
+      if (connection) {
+        await this.closeRemoteConnection(connection);
       }
     }
   }
@@ -1023,13 +1098,13 @@ ${sendingDocs}/(${sentDocsCount} done)`,
    * @throws {Error} If the document could not be put.
    */
   async putRemoteDocument(settings, doc, db) {
-    const ownsConnection = db === void 0;
-    const connDB = db ?? await this._ensureConnection(settings, true);
+    const connection = db === void 0 ? await this.openOwnedConnection(settings, true) : void 0;
+    const connDB = db ?? connection.db;
     try {
       return await connDB.put(doc);
     } finally {
-      if (ownsConnection) {
-        await this.closeRemoteDatabase(connDB);
+      if (connection) {
+        await this.closeRemoteConnection(connection);
       }
     }
   }
@@ -1043,7 +1118,7 @@ ${sendingDocs}/(${sentDocsCount} done)`,
       );
       return false;
     }
-    return await this.withRemoteDatabase(ret.db, async (db) => {
+    return await this.withRemoteConnection(ret, async (db) => {
       const remoteChunks = await db.allDocs({ keys: missingChunks, include_docs: true });
       const errorRows = remoteChunks.rows.filter((e) => "error" in e);
       if (errorRows.length > 0) {
@@ -1074,7 +1149,7 @@ ${sendingDocs}/(${sentDocsCount} done)`,
       );
       return false;
     }
-    return await this.withRemoteDatabase(db.db, async () => {
+    return await this.withRemoteConnection(db, async () => {
       Logger(`Connected to ${db.info.db_name} successfully`, LOG_LEVEL_NOTICE);
       return true;
     });
@@ -1086,7 +1161,7 @@ ${sendingDocs}/(${sentDocsCount} done)`,
       Logger(this.translate("liveSyncReplicator.couldNotConnectToURI", { uri, dbRet }), LOG_LEVEL_NOTICE);
       return;
     }
-    await this.withRemoteDatabase(dbRet.db, async (db) => {
+    await this.withRemoteConnection(dbRet, async (db) => {
       if (!await checkRemoteVersion(db, this.migrate.bind(this), VER)) {
         Logger(this.translate("liveSyncReplicator.remoteDbCorrupted"), LOG_LEVEL_NOTICE);
         return;
@@ -1109,7 +1184,7 @@ ${sendingDocs}/(${sentDocsCount} done)`,
       Logger(this.translate("liveSyncReplicator.couldNotConnectToURI", { uri, dbRet }), LOG_LEVEL_NOTICE);
       return;
     }
-    await this.withRemoteDatabase(dbRet.db, async (db) => {
+    await this.withRemoteConnection(dbRet, async (db) => {
       if (!await checkRemoteVersion(db, this.migrate.bind(this), VER)) {
         Logger(this.translate("liveSyncReplicator.remoteDbCorrupted"), LOG_LEVEL_NOTICE);
         return;
@@ -1145,7 +1220,7 @@ ${sendingDocs}/(${sentDocsCount} done)`,
         error: new Error(dbRet)
       };
     }
-    return await this.withRemoteDatabase(dbRet.db, async (db) => {
+    return await this.withRemoteConnection(dbRet, async (db) => {
       try {
         if (!await checkRemoteVersion(db, this.migrate.bind(this), VER)) {
           const error = new Error("The remote database version is not compatible");
@@ -1205,7 +1280,7 @@ ${sendingDocs}/(${sentDocsCount} done)`,
       Logger(this.translate("liveSyncReplicator.couldNotConnectToURI", { uri, dbRet }), LOG_LEVEL_NOTICE);
       return false;
     }
-    return await this.withRemoteDatabase(dbRet.db, async (db) => (await db.compact({ interval: 1e3 })).ok);
+    return await this.withRemoteConnection(dbRet, async (db) => (await db.compact({ interval: 1e3 })).ok);
   }
   async getRemoteStatus(setting) {
     const dbRet = await this.connectRemoteCouchDBWithSetting(setting, this.isMobile(), true);
@@ -1214,7 +1289,7 @@ ${sendingDocs}/(${sentDocsCount} done)`,
       Logger(this.translate("liveSyncReplicator.couldNotConnectToURI", { uri, dbRet }), LOG_LEVEL_NOTICE);
       return false;
     }
-    return await this.withRemoteDatabase(dbRet.db, async (db) => {
+    return await this.withRemoteConnection(dbRet, async (db) => {
       const info = await db.info();
       return {
         ...info,
@@ -1229,7 +1304,7 @@ ${sendingDocs}/(${sentDocsCount} done)`,
       Logger(this.translate("liveSyncReplicator.couldNotConnectToURI", { uri, dbRet }), LOG_LEVEL_NOTICE);
       return false;
     }
-    return await this.withRemoteDatabase(dbRet.db, countCompromisedChunks);
+    return await this.withRemoteConnection(dbRet, countCompromisedChunks);
   }
   async getConnectedDeviceList(setting = this.currentSettings) {
     const dbRet = await this.connectRemoteCouchDBWithSetting(setting, this.isMobile(), true);
@@ -1238,7 +1313,7 @@ ${sendingDocs}/(${sentDocsCount} done)`,
       Logger(this.translate("liveSyncReplicator.couldNotConnectToURI", { uri, dbRet }), LOG_LEVEL_NOTICE);
       return false;
     }
-    return await this.withRemoteDatabase(dbRet.db, async (db) => {
+    return await this.withRemoteConnection(dbRet, async (db) => {
       const milestoneDoc = await db.get(MILESTONE_DOCID);
       if (!milestoneDoc) {
         Logger("Could not retrieve remote milestone", LOG_LEVEL_NOTICE);

package/dist/services/base/IService.d.ts

@@ -11,6 +11,7 @@ import type { ReplicatorService } from "./ReplicatorService.js";
 import type { DatabaseEventService } from "./DatabaseEventService.js";
 import type { BASE_IS_NEW, EVEN, TARGET_IS_NEW } from "../../common/models/shared.const.symbols.js";
 import type { AsyncActivityOptions } from "../../interfaces/AsyncActivityRunner.js";
+import type { OwnedCouchDBConnection, RemoteConnectionOpenOptions } from "./RemoteConnection.js";
 declare global {
     interface OPTIONAL_SYNC_FEATURES {
         DISABLE: "DISABLE";
@@ -135,10 +136,23 @@ export interface IReplicationService {
     markResolved(): Promise<void>;
 }
 export interface IRemoteService {
-    connect(uri: string, auth: CouchDBCredentials, disableRequestURI: boolean, passphrase: string | false, useDynamicIterationCount: boolean, performSetup: boolean, skipInfo: boolean, compression: boolean, customHeaders: Record<string, string>, useRequestAPI: boolean, getPBKDF2Salt: () => Promise<Uint8Array<ArrayBuffer>>): Promise<string | {
-        db: PouchDB.Database<EntryDoc>;
-        info: PouchDB.Core.DatabaseInfo;
-    }>;
+    /**
+     * Opens an owned remote CouchDB connection.
+     *
+     * @remarks
+     * The caller must transfer ownership or call `close()` on the returned
+     * connection. Closing it aborts outstanding abort-capable requests before
+     * closing the PouchDB handle. Host-native request adapters may not honour
+     * `AbortSignal`; callers must not report those requests as cancelled without
+     * a host guarantee.
+     *
+     * @returns An error description, or an owned remote connection. When
+     * `skipInfo` is true, the `info` field retains its compatibility placeholder.
+     *
+     * @throws When PouchDB construction or local connection configuration fails
+     * before a connection result can be produced.
+     */
+    connect(uri: string, auth: CouchDBCredentials, disableRequestURI: boolean, passphrase: string | false, useDynamicIterationCount: boolean, performSetup: boolean, skipInfo: boolean, compression: boolean, customHeaders: Record<string, string>, useRequestAPI: boolean, getPBKDF2Salt: () => Promise<Uint8Array<ArrayBuffer>>, options?: RemoteConnectionOpenOptions): Promise<string | OwnedCouchDBConnection<EntryDoc>>;
     /**
      * State if the last POST request failed due to payload size.
      */

package/dist/services/base/RemoteConnection.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Options which bind requests made through a remote CouchDB connection to the
+ * operation which owns it.
+ */
+export interface RemoteConnectionOpenOptions {
+    /**
+     * Cancels abort-capable requests made through the connection when the
+     * owning operation is cancelled.
+     */
+    readonly signal?: AbortSignal;
+    /**
+     * Allows the diagnostic fallback to a host-native request API after a
+     * web-compatible request reports a network `TypeError`.
+     *
+     * Set this to `false` when the owner must retain an abortable request path.
+     * A host-native adapter is not assumed to honour `AbortSignal`.
+     */
+    readonly allowNativeFallback?: boolean;
+}
+/**
+ * A remote PouchDB handle together with the lifecycle of requests created
+ * through that handle.
+ *
+ * @remarks
+ * The caller owns this connection and must call
+ * {@link OwnedCouchDBConnection.close} when ownership is not transferred.
+ * `close()` is idempotent: it first cancels abort-capable requests within this
+ * connection, then closes the PouchDB handle. Closing the PouchDB handle retains
+ * its normal `closed` event behaviour. This contract does not imply exclusive
+ * ownership of a physical HTTP socket.
+ *
+ * @typeParam T - The document type stored in the remote database.
+ */
+export interface OwnedCouchDBConnection<T extends object> {
+    /** The remote PouchDB database handle. */
+    readonly db: PouchDB.Database<T>;
+    /**
+     * The database information read while opening the connection. When the
+     * caller skips that read, compatibility placeholders are returned.
+     */
+    readonly info: PouchDB.Core.DatabaseInfo;
+    /** Cancels scoped requests and closes the PouchDB handle exactly once. */
+    close(): Promise<void>;
+}

package/dist/services/base/RemoteService.d.ts

@@ -9,6 +9,7 @@ import type { SettingService } from "./SettingService.js";
 import { UnresolvedErrorManager } from "./UnresolvedErrorManager.js";
 import { type LogFunction } from "../lib/logUtils.js";
 import type { PouchDBConstructor } from "../../pouchdb/PouchDBConstructor.js";
+import type { OwnedCouchDBConnection, RemoteConnectionOpenOptions } from "./RemoteConnection.js";
 export interface RemoteServiceDependencies {
     /** PouchDB with the HTTP adapter required by the host runtime already registered. */
     pouchDB: PouchDBConstructor;
@@ -25,21 +26,6 @@ type FetchMethod = (typeof FetchMethod)[keyof typeof FetchMethod];
  * The RemoteService provides methods for interacting with the remote database.
  */
 export declare abstract class RemoteService<T extends ServiceContext = ServiceContext> extends ServiceBase<T> implements IRemoteService {
-    /**
-     * Connect to the remote database with the provided settings.
-     * @param uri  The URI of the remote database.
-     * @param auth  The authentication credentials for the remote database.
-     * @param disableRequestURI  Whether to disable the request URI.
-     * @param passphrase  The passphrase for the remote database.
-     * @param useDynamicIterationCount  Whether to use dynamic iteration count.
-     * @param performSetup  Whether to perform setup.
-     * @param skipInfo  Whether to skip information retrieval.
-     * @param compression  Whether to enable compression.
-     * @param customHeaders  Custom headers to include in the request.
-     * @param useRequestAPI  Whether to use the request API.
-     * @param getPBKDF2Salt  Function to retrieve the PBKDF2 salt.
-     * Note that this function is used for CouchDB and compatible only.
-     */
     protected _log: LogFunction;
     protected _authHeader: AuthorizationHeaderGenerator;
     protected _APIService: APIService;
@@ -53,9 +39,27 @@ export declare abstract class RemoteService<T extends ServiceContext = ServiceCo
     showError(msg: string, max_log_level?: LOG_LEVEL): void;
     clearErrors(): void;
     performFetch(req: string | Request, opts?: RequestInit, fetchMethod?: FetchMethod): Promise<Response>;
-    connect(uri: string, auth: CouchDBCredentials, disableRequestURI: boolean, passphrase: string | false, useDynamicIterationCount: boolean, performSetup: boolean, skipInfo: boolean, compression: boolean, customHeaders: Record<string, string>, useRequestAPI: boolean, getPBKDF2Salt: () => Promise<Uint8Array<ArrayBuffer>>): Promise<string | {
-        db: PouchDB.Database<EntryDoc>;
-        info: PouchDB.Core.DatabaseInfo;
-    }>;
+    /**
+     * Opens a remote CouchDB connection with request cancellation bound to its
+     * owner.
+     *
+     * @param uri - The URI of the remote database.
+     * @param auth - Authentication credentials for the remote database.
+     * @param disableRequestURI - Whether request URI handling is disabled.
+     * @param passphrase - The database encryption passphrase, or `false` when
+     * encryption is disabled.
+     * @param useDynamicIterationCount - Whether legacy dynamic iteration counts
+     * are enabled.
+     * @param performSetup - Whether PouchDB may set up a missing database.
+     * @param skipInfo - Whether to omit the opening database information request.
+     * @param compression - Whether chunk compression is enabled.
+     * @param customHeaders - Additional HTTP headers for every request.
+     * @param useRequestAPI - Whether to use the host-native request adapter.
+     * @param getPBKDF2Salt - Resolves the PBKDF2 salt when encryption needs it.
+     * @param connectionOptions - Ownership and request fallback options.
+     * @returns An error description, or the owned connection. The caller must
+     * transfer ownership or call `close()`.
+     */
+    connect(uri: string, auth: CouchDBCredentials, disableRequestURI: boolean, passphrase: string | false, useDynamicIterationCount: boolean, performSetup: boolean, skipInfo: boolean, compression: boolean, customHeaders: Record<string, string>, useRequestAPI: boolean, getPBKDF2Salt: () => Promise<Uint8Array<ArrayBuffer>>, connectionOptions?: RemoteConnectionOpenOptions): Promise<string | OwnedCouchDBConnection<EntryDoc>>;
 }
 export {};

package/dist/services/base/RemoteService.js

@@ -13,26 +13,84 @@ import { UnresolvedErrorManager } from "./UnresolvedErrorManager.js";
 import { createInstanceLogFunction, MARK_LOG_NETWORK_ERROR } from "../lib/logUtils.js";
 import { runWithTrackedPhysicalRequest } from "../lib/remoteActivity.js";
 import { LiveSyncError } from "../../common/LSError.js";
+function createRemoteConnectionScope(ownerSignal) {
+  const controller = new AbortController();
+  const combinedSignals = /* @__PURE__ */ new WeakMap();
+  let detachOwner = () => {
+  };
+  const abort = (reason) => {
+    detachOwner();
+    if (!controller.signal.aborted) {
+      controller.abort(reason);
+    }
+  };
+  if (ownerSignal?.aborted) {
+    abort(ownerSignal.reason);
+  } else if (ownerSignal) {
+    const onOwnerAbort = () => abort(ownerSignal.reason);
+    ownerSignal.addEventListener("abort", onOwnerAbort, { once: true });
+    detachOwner = () => ownerSignal.removeEventListener("abort", onOwnerAbort);
+  }
+  const combine = (signal) => {
+    if (!signal || signal === controller.signal) return controller.signal;
+    const cached = combinedSignals.get(signal);
+    if (cached) return cached;
+    const combined = combineAbortSignals(signal, controller.signal);
+    combinedSignals.set(signal, combined);
+    return combined;
+  };
+  return { signal: controller.signal, combine, abort };
+}
+function combineAbortSignals(first, second) {
+  if (first === second) return first;
+  const abortSignalWithAny = AbortSignal;
+  if (typeof abortSignalWithAny.any === "function") {
+    return abortSignalWithAny.any([first, second]);
+  }
+  const controller = new AbortController();
+  const listeners = /* @__PURE__ */ new Map();
+  const detach = () => {
+    for (const [signal, listener] of listeners) {
+      signal.removeEventListener("abort", listener);
+    }
+    listeners.clear();
+  };
+  const abortFrom = (signal) => {
+    detach();
+    if (!controller.signal.aborted) {
+      controller.abort(signal.reason);
+    }
+  };
+  for (const signal of [first, second]) {
+    if (signal.aborted) {
+      abortFrom(signal);
+      break;
+    }
+    const listener = () => abortFrom(signal);
+    listeners.set(signal, listener);
+    signal.addEventListener("abort", listener, { once: true });
+  }
+  return controller.signal;
+}
+function createCouchDBConnection(db, info, scope) {
+  let closePromise;
+  return {
+    db,
+    info,
+    close: () => {
+      closePromise ??= (async () => {
+        scope.abort(new Error("Remote connection closed."));
+        await db.close();
+      })();
+      return closePromise;
+    }
+  };
+}
 const FetchMethod = {
   webCompat: 0,
   native: 1
 };
 class RemoteService extends ServiceBase {
-  /**
-   * Connect to the remote database with the provided settings.
-   * @param uri  The URI of the remote database.
-   * @param auth  The authentication credentials for the remote database.
-   * @param disableRequestURI  Whether to disable the request URI.
-   * @param passphrase  The passphrase for the remote database.
-   * @param useDynamicIterationCount  Whether to use dynamic iteration count.
-   * @param performSetup  Whether to perform setup.
-   * @param skipInfo  Whether to skip information retrieval.
-   * @param compression  Whether to enable compression.
-   * @param customHeaders  Custom headers to include in the request.
-   * @param useRequestAPI  Whether to use the request API.
-   * @param getPBKDF2Salt  Function to retrieve the PBKDF2 salt.
-   * Note that this function is used for CouchDB and compatible only.
-   */
   _log;
   _authHeader = new AuthorizationHeaderGenerator();
   _APIService;
@@ -101,13 +159,35 @@ class RemoteService extends ServiceBase {
       return response;
     });
   }
-  async connect(uri, auth, disableRequestURI, passphrase, useDynamicIterationCount, performSetup, skipInfo, compression, customHeaders, useRequestAPI, getPBKDF2Salt) {
+  /**
+   * Opens a remote CouchDB connection with request cancellation bound to its
+   * owner.
+   *
+   * @param uri - The URI of the remote database.
+   * @param auth - Authentication credentials for the remote database.
+   * @param disableRequestURI - Whether request URI handling is disabled.
+   * @param passphrase - The database encryption passphrase, or `false` when
+   * encryption is disabled.
+   * @param useDynamicIterationCount - Whether legacy dynamic iteration counts
+   * are enabled.
+   * @param performSetup - Whether PouchDB may set up a missing database.
+   * @param skipInfo - Whether to omit the opening database information request.
+   * @param compression - Whether chunk compression is enabled.
+   * @param customHeaders - Additional HTTP headers for every request.
+   * @param useRequestAPI - Whether to use the host-native request adapter.
+   * @param getPBKDF2Salt - Resolves the PBKDF2 salt when encryption needs it.
+   * @param connectionOptions - Ownership and request fallback options.
+   * @returns An error description, or the owned connection. The caller must
+   * transfer ownership or call `close()`.
+   */
+  async connect(uri, auth, disableRequestURI, passphrase, useDynamicIterationCount, performSetup, skipInfo, compression, customHeaders, useRequestAPI, getPBKDF2Salt, connectionOptions = {}) {
     if (!isValidRemoteCouchDBURI(uri)) return "Remote URI is not valid";
     if (uri.toLowerCase() != uri) return "Remote URI and database name could not contain capital letters.";
     if (uri.indexOf(" ") !== -1) return "Remote URI and database name could not contain spaces.";
     if (!this._APIService.isOnline) {
       return "Network is offline";
     }
+    const connectionScope = createRemoteConnectionScope(connectionOptions.signal);
     const conf = {
       adapter: "http",
       auth: "username" in auth ? auth : void 0,
@@ -143,14 +223,18 @@ class RemoteService extends ServiceBase {
             headers.append("authorization", authHeader);
           }
           try {
+            const signal = connectionScope.combine(opts?.signal);
             const response = await this.performFetch(
               requestSrc,
-              { ...opts, headers },
+              { ...opts, headers, signal },
               useRequestAPI ? FetchMethod.native : FetchMethod.webCompat
             );
             return response;
           } catch (ex) {
             if (ex instanceof TypeError) {
+              if (connectionScope.signal.aborted || connectionOptions.allowNativeFallback === false) {
+                throw ex;
+              }
               if (useRequestAPI) {
                 this._log("Failed to request by API.");
                 throw ex;
@@ -176,7 +260,12 @@ class RemoteService extends ServiceBase {
         } catch (ex) {
           this._log(`HTTP:${method}${size} to:${localURL} -> failed`, LOG_LEVEL_VERBOSE);
           const msg = ex instanceof Error ? `${ex?.name}:${ex?.message}` : ex?.toString();
-          this.showError(`${MARK_LOG_NETWORK_ERROR}Network Error: Failed to fetch: ${msg}`, LOG_LEVEL_INFO);
+          if (!connectionScope.signal.aborted) {
+            this.showError(
+              `${MARK_LOG_NETWORK_ERROR}Network Error: Failed to fetch: ${msg}`,
+              LOG_LEVEL_INFO
+            );
+          }
           this._log(ex, LOG_LEVEL_VERBOSE);
           if (url.toString().indexOf("_bulk_docs") !== -1) {
             this.last_successful_post = false;
@@ -187,28 +276,44 @@ class RemoteService extends ServiceBase {
       }
     };
     const setting = this._settingService.currentSettings();
-    const db = new this._pouchDB(uri, conf);
-    replicationFilter(db, compression);
-    disableEncryption();
-    if (passphrase !== "false" && typeof passphrase === "string") {
-      enableEncryption(db, passphrase, useDynamicIterationCount, false, getPBKDF2Salt, setting.E2EEAlgorithm);
+    let db;
+    try {
+      db = new this._pouchDB(uri, conf);
+    } catch (ex) {
+      connectionScope.abort(ex);
+      throw ex;
+    }
+    const compatibilityInfo = { db_name: "", doc_count: 0, update_seq: "" };
+    const connection = createCouchDBConnection(db, compatibilityInfo, connectionScope);
+    const closeAfterConnectionFailure = async () => {
+      try {
+        await connection.close();
+      } catch (closeError) {
+        this._log("Failed to close remote database after connection failure.", LOG_LEVEL_INFO);
+        this._log(closeError, LOG_LEVEL_VERBOSE);
+      }
+    };
+    try {
+      replicationFilter(db, compression);
+      disableEncryption();
+      if (passphrase !== "false" && typeof passphrase === "string") {
+        enableEncryption(db, passphrase, useDynamicIterationCount, false, getPBKDF2Salt, setting.E2EEAlgorithm);
+      }
+    } catch (ex) {
+      await closeAfterConnectionFailure();
+      throw ex;
     }
     if (skipInfo) {
-      return { db, info: { db_name: "", doc_count: 0, update_seq: "" } };
+      return connection;
     }
     try {
       const info = await db.info();
-      return { db, info };
+      return { ...connection, info };
     } catch (ex) {
       const exMsg = ex instanceof Error ? ex : LiveSyncError.fromError(ex);
       const msg = `${exMsg.name}:${exMsg.message}`;
       this._log(ex, LOG_LEVEL_VERBOSE);
-      try {
-        await db.close();
-      } catch (closeError) {
-        this._log("Failed to close remote database after connection failure.", LOG_LEVEL_INFO);
-        this._log(closeError, LOG_LEVEL_VERBOSE);
-      }
+      await closeAfterConnectionFailure();
       return msg;
     }
   }

package/docs/development.md

@@ -63,6 +63,10 @@ The revision-tree safety rules are documented in [Conflict resolution and file p
 
 `LiveSyncReplicator.unit.spec.ts` owns the CouchDB remote-chunk batch contract: a mixed `_all_docs` result must return each available document even when another keyed row reports an error. `ChunkFetcher.unit.spec.ts` owns the consumer behaviour: it writes valid returned chunks and emits `missingChunkRemote` only for requested IDs which are absent from the returned set. Extend both sides when changing remote chunk acquisition or missing-chunk delivery.
 
+`RemoteService.connect()` returns an owned CouchDB connection as the existing flat `{ db, info }` result with an idempotent `close()` method. `close()` first aborts outstanding abort-capable requests in that connection, then closes the PouchDB handle. The owner must transfer or close the complete connection; passing only `db` loses the cancellation boundary. A skipped information request retains the established placeholder in `info` for compatibility. `OwnedCouchDBConnection`, its opening options, and the checked `CouchDBReplicationConnection` are Commonlib-owned types exported by the existing CouchDB replicator module. The legacy `_ensureConnection()` helper continues to return a raw PouchDB handle for source compatibility; new Commonlib code must retain and close the complete owned connection instead.
+
+The one-shot CouchDB connectivity preflight is the first bounded consumer. It applies an internal 60-second safety fuse to the complete preflight on the web-compatible fetch path, disables fallback into the non-abortable native request adapter, and clears the fuse before transferring the connection to replication. The fuse is a last-resort wall-clock bound on an owner which would otherwise remain pending indefinitely; it is not the expected completion time, a per-request inactivity timeout, a user setting, or the `useTimeouts` changes-feed setting. The explicitly selected native Request API retains its previous unbounded behaviour because its current host adapter cannot honour `AbortSignal`. Extend `RemoteService.unit.spec.ts` and the one-shot ownership table in `LiveSyncReplicator.unit.spec.ts` when changing this boundary. Do not use `Promise.race()` to report a mutating native request as cancelled while it can still complete remotely.
+
 `openSimpleStore()` may create an inert namespace handle during composition, before the backing key-value database has opened. Maintained hosts must complete their sequential settings lifecycle before scans, watchers, or replication invoke the handle. Operations fail on a lifecycle violation rather than waiting for readiness; do not introduce an implicit wait which can hang after failed initialisation or become self-referential from an initialisation handler. Treat database reset as a transient unavailable boundary and reconstruct derived local state after reopening.
 
 ### P2P composition ownership

package/docs/proven-in-use.md

@@ -20,6 +20,8 @@ Commonlib's chunk-reachability tests use real PouchDB revision trees. They verif
 
 Commonlib's injected CouchDB tests verify that a mixed remote chunk batch preserves available documents when another requested ID is absent. Its chunk-delivery tests separately verify that available chunks reach local storage and only absent IDs are marked unavailable. Self-hosted LiveSync supplies the real CouchDB connection and start-up composition, so device-specific replication timing remains downstream integration evidence rather than Commonlib unit coverage.
 
+Commonlib's injected remote-service tests verify that an owning operation can abort a pending CouchDB request, that closing the flat connection interrupts a response body which is already being consumed, that repeated closure closes PouchDB once, and that a bounded request does not fall back into the non-abortable native adapter. Its one-shot replicator tests verify deadline expiry, distinct timeout reporting, cleanup before release of the shared attempt, later invocation, successful ownership transfer, and the unchanged native-request boundary. Self-hosted LiveSync still supplies the actual Obsidian fetch adapters and real CouchDB environment; confirmation on the reporter's platform remains downstream evidence rather than a Commonlib guarantee.
+
 Commonlib's remote-preference result contract distinguishes available synchronisation settings, a remote which has not stored those settings yet, a failed read, and a remote type which does not support central preferences. Focused CouchDB and Object Storage tests cover absent milestone data separately from transport failures, while Self-hosted LiveSync owns the initialisation choices, cancellation policy, and user-facing explanation.
 
 Commonlib's full offline scanner distinguishes completed, deliberately skipped, and failed storage/database pairs. Before pair construction, it withholds Metadata whose actual document ID disagrees with its recorded path, without reflection, deletion, or last-seen side effects. A consistently addressed entry for the same logical path continues through the established path-based flow; only a path without such an entry also withholds storage processing. The read-only actual-ID Inspector and separately invoked one-entry repair retain ambiguous states for review, revalidate an exact source revision, verify a target-first copy, and preserve the source on failure. Self-hosted LiveSync keeps the existing Fast Setup aggregate policy and owns confirmation and presentation in its file/database repair interface.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vrtmrz/livesync-commonlib",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "Shared data, storage, and replication primitives for Self-hosted LiveSync clients.",
   "type": "module",
   "types": "./dist/index.d.ts",