@vrtmrz/livesync-commonlib 0.1.14 → 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 {};