@itwin/core-backend 3.6.1 → 3.6.3

package/lib/cjs/CheckpointManager.js

@@ -1,350 +1,350 @@
-"use strict";
-/*---------------------------------------------------------------------------------------------
-* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
-* See LICENSE.md in the project root for license terms and full copyright notice.
-*--------------------------------------------------------------------------------------------*/
-/** @packageDocumentation
- * @module iModels
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.CheckpointManager = exports.V1CheckpointManager = exports.V2CheckpointManager = exports.Downloads = exports.ProgressStatus = void 0;
-// cspell:ignore BLOCKCACHE
-const path = require("path");
-const core_bentley_1 = require("@itwin/core-bentley");
-const core_common_1 = require("@itwin/core-common");
-const BackendLoggerCategory_1 = require("./BackendLoggerCategory");
-const BriefcaseManager_1 = require("./BriefcaseManager");
-const CloudSqlite_1 = require("./CloudSqlite");
-const IModelDb_1 = require("./IModelDb");
-const IModelHost_1 = require("./IModelHost");
-const IModelJsFs_1 = require("./IModelJsFs");
-const loggerCategory = BackendLoggerCategory_1.BackendLoggerCategory.IModelDb;
-/** Return value from [[ProgressFunction]].
- *  @public
- */
-var ProgressStatus;
-(function (ProgressStatus) {
-    /** Continue download. */
-    ProgressStatus[ProgressStatus["Continue"] = 0] = "Continue";
-    /** Abort download. */
-    ProgressStatus[ProgressStatus["Abort"] = 1] = "Abort";
-})(ProgressStatus = exports.ProgressStatus || (exports.ProgressStatus = {}));
-/** @internal */
-class Downloads {
-    static async process(job, fn) {
-        const jobName = job.request.localFile; // save this, it can change inside call to `fn`!
-        this._active.set(jobName, job);
-        try {
-            return await fn(job);
-        }
-        finally {
-            this._active.delete(jobName);
-        }
-    }
-    static isInProgress(pathName) {
-        return this._active.get(pathName);
-    }
-    static async download(request, downloadFn) {
-        const pathName = request.localFile;
-        let job = this.isInProgress(pathName);
-        if (undefined !== job)
-            return job.promise;
-        IModelJsFs_1.IModelJsFs.recursiveMkDirSync(path.dirname(pathName));
-        job = { request };
-        return job.promise = this.process(job, downloadFn);
-    }
-}
-exports.Downloads = Downloads;
-Downloads._active = new Map();
-/**
- * Utility class for opening V2 checkpoints from cloud containers, and also for downloading them.
- * @internal
-*/
-class V2CheckpointManager {
-    static getFolder() {
-        const cloudCachePath = path.join(BriefcaseManager_1.BriefcaseManager.cacheDir, V2CheckpointManager.cloudCacheName);
-        if (!(IModelJsFs_1.IModelJsFs.existsSync(cloudCachePath))) {
-            IModelJsFs_1.IModelJsFs.recursiveMkDirSync(cloudCachePath);
-        }
-        return cloudCachePath;
-    }
-    /* only used by tests that reset the state of the v2checkpointmanager. all dbs should be closed before calling this function. */
-    static cleanup() {
-        var _a;
-        for (const [_, value] of this.containers.entries()) {
-            if (value.isConnected)
-                value.detach();
-        }
-        (_a = this._cloudCache) === null || _a === void 0 ? void 0 : _a.destroy();
-        this._cloudCache = undefined;
-        this.containers.clear();
-    }
-    static getFileName(checkpoint) {
-        const changesetId = checkpoint.changeset.id || "first";
-        return path.join(this.getFolder(), `${changesetId}.bim`);
-    }
-    static get cloudCache() {
-        if (!this._cloudCache) {
-            let rootDir = process.env.CHECKPOINT_CACHE_DIR;
-            if (!rootDir) {
-                rootDir = this.getFolder();
-                core_bentley_1.Logger.logWarning(loggerCategory, `No CHECKPOINT_CACHE_DIR found in process.env, using ${rootDir} instead.`);
-            }
-            else {
-                // Make sure the checkpoint_cache_dir has an iTwinDaemon specific file in it, otherwise fall back to other directory.
-                if (!(IModelJsFs_1.IModelJsFs.existsSync(path.join(rootDir, "portnumber.bcv")))) {
-                    rootDir = this.getFolder();
-                    core_bentley_1.Logger.logWarning(loggerCategory, `No evidence of the iTwinDaemon in provided CHECKPOINT_CACHE_DIR: ${process.env.CHECKPOINT_CACHE_DIR}, using ${rootDir} instead.`);
-                }
-            }
-            this._cloudCache = CloudSqlite_1.CloudSqlite.createCloudCache({ name: this.cloudCacheName, rootDir });
-            // Its fine if its not a daemon, but lets log an info message
-            if (!this._cloudCache.isDaemon)
-                core_bentley_1.Logger.logInfo(loggerCategory, "V2Checkpoint manager running with no iTwinDaemon.");
-        }
-        return this._cloudCache;
-    }
-    /** Member names differ slightly between the V2Checkpoint api and the CloudSqlite api. Add aliases `accessName` for `accountName` and `accessToken` for `sasToken` */
-    static toCloudContainerProps(from) {
-        return { ...from, accessName: from.accountName, accessToken: from.sasToken };
-    }
-    static getContainer(v2Props) {
-        let container = this.containers.get(v2Props.containerId);
-        if (!container) {
-            container = CloudSqlite_1.CloudSqlite.createCloudContainer(this.toCloudContainerProps(v2Props));
-            this.containers.set(v2Props.containerId, container);
-        }
-        return container;
-    }
-    static async attach(checkpoint) {
-        let v2props;
-        try {
-            v2props = await IModelHost_1.IModelHost.hubAccess.queryV2Checkpoint(checkpoint);
-            if (!v2props)
-                throw new Error("no checkpoint");
-        }
-        catch (err) {
-            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.NotFound, `V2 checkpoint not found: err: ${err.message}`);
-        }
-        try {
-            const container = this.getContainer(v2props);
-            const dbName = v2props.dbName;
-            if (!container.isConnected)
-                container.connect(this.cloudCache);
-            container.checkForChanges();
-            if (IModelHost_1.IModelHost.appWorkspace.settings.getBoolean("Checkpoints/prefetch", false)) {
-                const logPrefetch = async (prefetch) => {
-                    const stopwatch = new core_bentley_1.StopWatch(`[${container.containerId}/${dbName}]`, true);
-                    core_bentley_1.Logger.logInfo(loggerCategory, `Starting prefetch of ${stopwatch.description}`);
-                    const done = await prefetch.promise;
-                    core_bentley_1.Logger.logInfo(loggerCategory, `Prefetch of ${stopwatch.description} complete=${done} (${stopwatch.elapsedSeconds} seconds)`);
-                };
-                // eslint-disable-next-line @typescript-eslint/no-floating-promises
-                logPrefetch(CloudSqlite_1.CloudSqlite.startCloudPrefetch(container, dbName));
-            }
-            return { dbName, container };
-        }
-        catch (e) {
-            const error = `Cloud cache connect failed: ${e.message}`;
-            if (checkpoint.expectV2)
-                core_bentley_1.Logger.logError(loggerCategory, error);
-            throw new core_common_1.IModelError(e.errorNumber, error);
-        }
-    }
-    static async performDownload(job) {
-        const request = job.request;
-        const v2props = await IModelHost_1.IModelHost.hubAccess.queryV2Checkpoint({ ...request.checkpoint, allowPreceding: true });
-        if (!v2props)
-            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.NotFound, "V2 checkpoint not found");
-        CheckpointManager.onDownloadV2.raiseEvent(job);
-        const container = CloudSqlite_1.CloudSqlite.createCloudContainer(this.toCloudContainerProps(v2props));
-        await CloudSqlite_1.CloudSqlite.transferDb("download", container, { dbName: v2props.dbName, localFileName: request.localFile, onProgress: request.onProgress });
-        return request.checkpoint.changeset.id;
-    }
-    /** Fully download a V2 checkpoint to a local file that can be used to create a briefcase or to work offline.
-     * @returns a Promise that is resolved when the download completes with the changesetId of the downloaded checkpoint (which will
-     * be the same as the requested changesetId or the most recent checkpoint before it.)
-     */
-    static async downloadCheckpoint(request) {
-        return Downloads.download(request, async (job) => this.performDownload(job));
-    }
-}
-exports.V2CheckpointManager = V2CheckpointManager;
-V2CheckpointManager.cloudCacheName = "v2Checkpoints";
-V2CheckpointManager.containers = new Map();
-/** Utility class to deal with downloading V1 checkpoints from iModelHub.
- * @internal
- */
-class V1CheckpointManager {
-    static getFolder(iModelId) {
-        return path.join(BriefcaseManager_1.BriefcaseManager.getIModelPath(iModelId), "checkpoints");
-    }
-    static getFileName(checkpoint) {
-        const changesetId = checkpoint.changeset.id || "first";
-        return path.join(this.getFolder(checkpoint.iModelId), `${changesetId}.bim`);
-    }
-    static async getCheckpointDb(request) {
-        const db = IModelDb_1.SnapshotDb.tryFindByKey(CheckpointManager.getKey(request.checkpoint));
-        return (undefined !== db) ? db : Downloads.download(request, async (job) => this.downloadAndOpen(job));
-    }
-    /** Download a V1 checkpoint */
-    static async downloadCheckpoint(request) {
-        return Downloads.download(request, async (job) => this.performDownload(job));
-    }
-    static async downloadAndOpen(job) {
-        const db = CheckpointManager.tryOpenLocalFile(job.request);
-        if (db)
-            return db;
-        await this.performDownload(job);
-        await CheckpointManager.updateToRequestedVersion(job.request);
-        return IModelDb_1.SnapshotDb.openCheckpointV1(job.request.localFile, job.request.checkpoint);
-    }
-    static async performDownload(job) {
-        CheckpointManager.onDownloadV1.raiseEvent(job);
-        // eslint-disable-next-line deprecation/deprecation
-        return (await IModelHost_1.IModelHost.hubAccess.downloadV1Checkpoint(job.request)).id;
-    }
-}
-exports.V1CheckpointManager = V1CheckpointManager;
-/** @internal  */
-class CheckpointManager {
-    static getKey(checkpoint) { return `${checkpoint.iModelId}:${checkpoint.changeset.id}`; }
-    static async doDownload(request) {
-        try {
-            // first see if there's a V2 checkpoint available.
-            const changesetId = await V2CheckpointManager.downloadCheckpoint(request);
-            if (changesetId !== request.checkpoint.changeset.id)
-                core_bentley_1.Logger.logInfo(loggerCategory, `Downloaded previous v2 checkpoint because requested checkpoint not found.`, { requestedChangesetId: request.checkpoint.changeset.id, iModelId: request.checkpoint.iModelId, changesetId, iTwinId: request.checkpoint.iTwinId });
-            else
-                core_bentley_1.Logger.logInfo(loggerCategory, `Downloaded v2 checkpoint.`, { iModelId: request.checkpoint.iModelId, changesetId: request.checkpoint.changeset.id, iTwinId: request.checkpoint.iTwinId });
-            return changesetId;
-        }
-        catch (error) {
-            if (error.errorNumber === core_bentley_1.IModelStatus.NotFound) { // No V2 checkpoint available, try a v1 checkpoint
-                const changeset = await V1CheckpointManager.downloadCheckpoint(request);
-                core_bentley_1.Logger.logWarning(loggerCategory, `Got an error downloading v2 checkpoint, but downloaded v1 checkpoint successfully!`, { error, iModelId: request.checkpoint.iModelId, iTwinId: request.checkpoint.iTwinId, requestedChangesetId: request.checkpoint.changeset.id, changesetId: changeset });
-                return changeset;
-            }
-            throw error; // most likely, was aborted
-        }
-    }
-    static async updateToRequestedVersion(request) {
-        var _a;
-        const checkpoint = request.checkpoint;
-        const targetFile = request.localFile;
-        const traceInfo = { iTwinId: checkpoint.iTwinId, iModelId: checkpoint.iModelId, changeset: checkpoint.changeset };
-        try {
-            // Open checkpoint for write
-            const db = IModelDb_1.SnapshotDb.openForApplyChangesets(targetFile);
-            const nativeDb = db.nativeDb;
-            try {
-                if (nativeDb.hasPendingTxns()) {
-                    core_bentley_1.Logger.logWarning(loggerCategory, "Checkpoint with Txns found - deleting them", () => traceInfo);
-                    nativeDb.deleteAllTxns();
-                }
-                if (nativeDb.getBriefcaseId() !== core_common_1.BriefcaseIdValue.Unassigned)
-                    nativeDb.resetBriefcaseId(core_common_1.BriefcaseIdValue.Unassigned);
-                CheckpointManager.validateCheckpointGuids(checkpoint, db);
-                // Apply change sets if necessary
-                const currentChangeset = nativeDb.getCurrentChangeset();
-                if (currentChangeset.id !== checkpoint.changeset.id) {
-                    const accessToken = checkpoint.accessToken;
-                    const toIndex = (_a = checkpoint.changeset.index) !== null && _a !== void 0 ? _a : (await IModelHost_1.IModelHost.hubAccess.getChangesetFromVersion({ accessToken, iModelId: checkpoint.iModelId, version: core_common_1.IModelVersion.asOfChangeSet(checkpoint.changeset.id) })).index;
-                    await BriefcaseManager_1.BriefcaseManager.pullAndApplyChangesets(db, { accessToken, toIndex });
-                }
-                else {
-                    // make sure the parent changeset index is saved in the file - old versions didn't have it.
-                    currentChangeset.index = checkpoint.changeset.index; // eslint-disable-line @typescript-eslint/no-non-null-assertion
-                    nativeDb.saveLocalValue("parentChangeSet", JSON.stringify(currentChangeset));
-                }
-            }
-            finally {
-                db.saveChanges();
-                db.close();
-            }
-        }
-        catch (error) {
-            core_bentley_1.Logger.logError(loggerCategory, "Error downloading checkpoint - deleting it", () => traceInfo);
-            IModelJsFs_1.IModelJsFs.removeSync(targetFile);
-            if (error.errorNumber === core_bentley_1.ChangeSetStatus.CorruptedChangeStream || error.errorNumber === core_bentley_1.ChangeSetStatus.InvalidId || error.errorNumber === core_bentley_1.ChangeSetStatus.InvalidVersion) {
-                core_bentley_1.Logger.logError(loggerCategory, "Detected potential corruption of change sets. Deleting them to enable retries", () => traceInfo);
-                BriefcaseManager_1.BriefcaseManager.deleteChangeSetsFromLocalDisk(checkpoint.iModelId);
-            }
-            throw error;
-        }
-    }
-    /** Download a checkpoint file from iModelHub into a local file specified in the request parameters. */
-    static async downloadCheckpoint(request) {
-        if (this.verifyCheckpoint(request.checkpoint, request.localFile))
-            return;
-        if (request.aliasFiles) {
-            for (const alias of request.aliasFiles) {
-                if (this.verifyCheckpoint(request.checkpoint, alias)) {
-                    request.localFile = alias;
-                    return;
-                }
-            }
-        }
-        await this.doDownload(request);
-        return this.updateToRequestedVersion(request);
-    }
-    /** checks a file's dbGuid & iTwinId for consistency, and updates the dbGuid when possible */
-    static validateCheckpointGuids(checkpoint, snapshotDb) {
-        const traceInfo = { iTwinId: checkpoint.iTwinId, iModelId: checkpoint.iModelId };
-        const nativeDb = snapshotDb.nativeDb;
-        const dbChangeset = nativeDb.getCurrentChangeset();
-        const iModelId = core_bentley_1.Guid.normalize(nativeDb.getIModelId());
-        if (iModelId !== core_bentley_1.Guid.normalize(checkpoint.iModelId)) {
-            if (nativeDb.isReadonly())
-                throw new core_common_1.IModelError(core_bentley_1.IModelStatus.ValidationFailed, "iModelId is not properly set up in the checkpoint");
-            core_bentley_1.Logger.logWarning(loggerCategory, "iModelId is not properly set up in the checkpoint. Updated checkpoint to the correct iModelId.", () => ({ ...traceInfo, dbGuid: iModelId }));
-            const iModelIdNormalized = core_bentley_1.Guid.normalize(checkpoint.iModelId);
-            nativeDb.setIModelId(iModelIdNormalized);
-            snapshotDb._iModelId = iModelIdNormalized;
-            // Required to reset the ChangeSetId because setDbGuid clears the value.
-            nativeDb.saveLocalValue("ParentChangeSetId", dbChangeset.id);
-            if (undefined !== dbChangeset.index)
-                nativeDb.saveLocalValue("parentChangeSet", JSON.stringify(dbChangeset));
-        }
-        const iTwinId = core_bentley_1.Guid.normalize(nativeDb.getITwinId());
-        if (iTwinId !== core_bentley_1.Guid.normalize(checkpoint.iTwinId))
-            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.ValidationFailed, "iTwinId was not properly set up in the checkpoint");
-    }
-    /** @returns true if the file is the checkpoint requested */
-    static verifyCheckpoint(checkpoint, fileName) {
-        if (!IModelJsFs_1.IModelJsFs.existsSync(fileName))
-            return false;
-        const nativeDb = new IModelHost_1.IModelHost.platform.DgnDb();
-        try {
-            nativeDb.openIModel(fileName, core_bentley_1.OpenMode.Readonly);
-        }
-        catch (error) {
-            return false;
-        }
-        const isValid = checkpoint.iModelId === nativeDb.getIModelId() && checkpoint.changeset.id === nativeDb.getCurrentChangeset().id;
-        nativeDb.closeIModel();
-        if (!isValid)
-            IModelJsFs_1.IModelJsFs.removeSync(fileName);
-        return isValid;
-    }
-    /** try to open an existing local file to satisfy a download request */
-    static tryOpenLocalFile(request) {
-        const checkpoint = request.checkpoint;
-        if (this.verifyCheckpoint(checkpoint, request.localFile))
-            return IModelDb_1.SnapshotDb.openCheckpointV1(request.localFile, checkpoint);
-        // check a list of aliases for finding checkpoints downloaded to non-default locations (e.g. from older versions)
-        if (request.aliasFiles) {
-            for (const alias of request.aliasFiles) {
-                if (this.verifyCheckpoint(checkpoint, alias)) {
-                    request.localFile = alias;
-                    return IModelDb_1.SnapshotDb.openCheckpointV1(alias, checkpoint);
-                }
-            }
-        }
-        return undefined;
-    }
-}
-exports.CheckpointManager = CheckpointManager;
-CheckpointManager.onDownloadV1 = new core_bentley_1.BeEvent();
-CheckpointManager.onDownloadV2 = new core_bentley_1.BeEvent();
+"use strict";
+/*---------------------------------------------------------------------------------------------
+* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+* See LICENSE.md in the project root for license terms and full copyright notice.
+*--------------------------------------------------------------------------------------------*/
+/** @packageDocumentation
+ * @module iModels
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CheckpointManager = exports.V1CheckpointManager = exports.V2CheckpointManager = exports.Downloads = exports.ProgressStatus = void 0;
+// cspell:ignore BLOCKCACHE
+const path = require("path");
+const core_bentley_1 = require("@itwin/core-bentley");
+const core_common_1 = require("@itwin/core-common");
+const BackendLoggerCategory_1 = require("./BackendLoggerCategory");
+const BriefcaseManager_1 = require("./BriefcaseManager");
+const CloudSqlite_1 = require("./CloudSqlite");
+const IModelDb_1 = require("./IModelDb");
+const IModelHost_1 = require("./IModelHost");
+const IModelJsFs_1 = require("./IModelJsFs");
+const loggerCategory = BackendLoggerCategory_1.BackendLoggerCategory.IModelDb;
+/** Return value from [[ProgressFunction]].
+ *  @public
+ */
+var ProgressStatus;
+(function (ProgressStatus) {
+    /** Continue download. */
+    ProgressStatus[ProgressStatus["Continue"] = 0] = "Continue";
+    /** Abort download. */
+    ProgressStatus[ProgressStatus["Abort"] = 1] = "Abort";
+})(ProgressStatus = exports.ProgressStatus || (exports.ProgressStatus = {}));
+/** @internal */
+class Downloads {
+    static async process(job, fn) {
+        const jobName = job.request.localFile; // save this, it can change inside call to `fn`!
+        this._active.set(jobName, job);
+        try {
+            return await fn(job);
+        }
+        finally {
+            this._active.delete(jobName);
+        }
+    }
+    static isInProgress(pathName) {
+        return this._active.get(pathName);
+    }
+    static async download(request, downloadFn) {
+        const pathName = request.localFile;
+        let job = this.isInProgress(pathName);
+        if (undefined !== job)
+            return job.promise;
+        IModelJsFs_1.IModelJsFs.recursiveMkDirSync(path.dirname(pathName));
+        job = { request };
+        return job.promise = this.process(job, downloadFn);
+    }
+}
+exports.Downloads = Downloads;
+Downloads._active = new Map();
+/**
+ * Utility class for opening V2 checkpoints from cloud containers, and also for downloading them.
+ * @internal
+*/
+class V2CheckpointManager {
+    static getFolder() {
+        const cloudCachePath = path.join(BriefcaseManager_1.BriefcaseManager.cacheDir, V2CheckpointManager.cloudCacheName);
+        if (!(IModelJsFs_1.IModelJsFs.existsSync(cloudCachePath))) {
+            IModelJsFs_1.IModelJsFs.recursiveMkDirSync(cloudCachePath);
+        }
+        return cloudCachePath;
+    }
+    /* only used by tests that reset the state of the v2checkpointmanager. all dbs should be closed before calling this function. */
+    static cleanup() {
+        var _a;
+        for (const [_, value] of this.containers.entries()) {
+            if (value.isConnected)
+                value.detach();
+        }
+        (_a = this._cloudCache) === null || _a === void 0 ? void 0 : _a.destroy();
+        this._cloudCache = undefined;
+        this.containers.clear();
+    }
+    static getFileName(checkpoint) {
+        const changesetId = checkpoint.changeset.id || "first";
+        return path.join(this.getFolder(), `${changesetId}.bim`);
+    }
+    static get cloudCache() {
+        if (!this._cloudCache) {
+            let rootDir = process.env.CHECKPOINT_CACHE_DIR;
+            if (!rootDir) {
+                rootDir = this.getFolder();
+                core_bentley_1.Logger.logWarning(loggerCategory, `No CHECKPOINT_CACHE_DIR found in process.env, using ${rootDir} instead.`);
+            }
+            else {
+                // Make sure the checkpoint_cache_dir has an iTwinDaemon specific file in it, otherwise fall back to other directory.
+                if (!(IModelJsFs_1.IModelJsFs.existsSync(path.join(rootDir, "portnumber.bcv")))) {
+                    rootDir = this.getFolder();
+                    core_bentley_1.Logger.logWarning(loggerCategory, `No evidence of the iTwinDaemon in provided CHECKPOINT_CACHE_DIR: ${process.env.CHECKPOINT_CACHE_DIR}, using ${rootDir} instead.`);
+                }
+            }
+            this._cloudCache = CloudSqlite_1.CloudSqlite.createCloudCache({ name: this.cloudCacheName, rootDir });
+            // Its fine if its not a daemon, but lets log an info message
+            if (!this._cloudCache.isDaemon)
+                core_bentley_1.Logger.logInfo(loggerCategory, "V2Checkpoint manager running with no iTwinDaemon.");
+        }
+        return this._cloudCache;
+    }
+    /** Member names differ slightly between the V2Checkpoint api and the CloudSqlite api. Add aliases `accessName` for `accountName` and `accessToken` for `sasToken` */
+    static toCloudContainerProps(from) {
+        return { ...from, accessName: from.accountName, accessToken: from.sasToken };
+    }
+    static getContainer(v2Props) {
+        let container = this.containers.get(v2Props.containerId);
+        if (!container) {
+            container = CloudSqlite_1.CloudSqlite.createCloudContainer(this.toCloudContainerProps(v2Props));
+            this.containers.set(v2Props.containerId, container);
+        }
+        return container;
+    }
+    static async attach(checkpoint) {
+        let v2props;
+        try {
+            v2props = await IModelHost_1.IModelHost.hubAccess.queryV2Checkpoint(checkpoint);
+            if (!v2props)
+                throw new Error("no checkpoint");
+        }
+        catch (err) {
+            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.NotFound, `V2 checkpoint not found: err: ${err.message}`);
+        }
+        try {
+            const container = this.getContainer(v2props);
+            const dbName = v2props.dbName;
+            if (!container.isConnected)
+                container.connect(this.cloudCache);
+            container.checkForChanges();
+            if (IModelHost_1.IModelHost.appWorkspace.settings.getBoolean("Checkpoints/prefetch", false)) {
+                const logPrefetch = async (prefetch) => {
+                    const stopwatch = new core_bentley_1.StopWatch(`[${container.containerId}/${dbName}]`, true);
+                    core_bentley_1.Logger.logInfo(loggerCategory, `Starting prefetch of ${stopwatch.description}`);
+                    const done = await prefetch.promise;
+                    core_bentley_1.Logger.logInfo(loggerCategory, `Prefetch of ${stopwatch.description} complete=${done} (${stopwatch.elapsedSeconds} seconds)`);
+                };
+                // eslint-disable-next-line @typescript-eslint/no-floating-promises
+                logPrefetch(CloudSqlite_1.CloudSqlite.startCloudPrefetch(container, dbName));
+            }
+            return { dbName, container };
+        }
+        catch (e) {
+            const error = `Cloud cache connect failed: ${e.message}`;
+            if (checkpoint.expectV2)
+                core_bentley_1.Logger.logError(loggerCategory, error);
+            throw new core_common_1.IModelError(e.errorNumber, error);
+        }
+    }
+    static async performDownload(job) {
+        const request = job.request;
+        const v2props = await IModelHost_1.IModelHost.hubAccess.queryV2Checkpoint({ ...request.checkpoint, allowPreceding: true });
+        if (!v2props)
+            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.NotFound, "V2 checkpoint not found");
+        CheckpointManager.onDownloadV2.raiseEvent(job);
+        const container = CloudSqlite_1.CloudSqlite.createCloudContainer(this.toCloudContainerProps(v2props));
+        await CloudSqlite_1.CloudSqlite.transferDb("download", container, { dbName: v2props.dbName, localFileName: request.localFile, onProgress: request.onProgress });
+        return request.checkpoint.changeset.id;
+    }
+    /** Fully download a V2 checkpoint to a local file that can be used to create a briefcase or to work offline.
+     * @returns a Promise that is resolved when the download completes with the changesetId of the downloaded checkpoint (which will
+     * be the same as the requested changesetId or the most recent checkpoint before it.)
+     */
+    static async downloadCheckpoint(request) {
+        return Downloads.download(request, async (job) => this.performDownload(job));
+    }
+}
+exports.V2CheckpointManager = V2CheckpointManager;
+V2CheckpointManager.cloudCacheName = "v2Checkpoints";
+V2CheckpointManager.containers = new Map();
+/** Utility class to deal with downloading V1 checkpoints from iModelHub.
+ * @internal
+ */
+class V1CheckpointManager {
+    static getFolder(iModelId) {
+        return path.join(BriefcaseManager_1.BriefcaseManager.getIModelPath(iModelId), "checkpoints");
+    }
+    static getFileName(checkpoint) {
+        const changesetId = checkpoint.changeset.id || "first";
+        return path.join(this.getFolder(checkpoint.iModelId), `${changesetId}.bim`);
+    }
+    static async getCheckpointDb(request) {
+        const db = IModelDb_1.SnapshotDb.tryFindByKey(CheckpointManager.getKey(request.checkpoint));
+        return (undefined !== db) ? db : Downloads.download(request, async (job) => this.downloadAndOpen(job));
+    }
+    /** Download a V1 checkpoint */
+    static async downloadCheckpoint(request) {
+        return Downloads.download(request, async (job) => this.performDownload(job));
+    }
+    static async downloadAndOpen(job) {
+        const db = CheckpointManager.tryOpenLocalFile(job.request);
+        if (db)
+            return db;
+        await this.performDownload(job);
+        await CheckpointManager.updateToRequestedVersion(job.request);
+        return IModelDb_1.SnapshotDb.openCheckpointV1(job.request.localFile, job.request.checkpoint);
+    }
+    static async performDownload(job) {
+        CheckpointManager.onDownloadV1.raiseEvent(job);
+        // eslint-disable-next-line deprecation/deprecation
+        return (await IModelHost_1.IModelHost.hubAccess.downloadV1Checkpoint(job.request)).id;
+    }
+}
+exports.V1CheckpointManager = V1CheckpointManager;
+/** @internal  */
+class CheckpointManager {
+    static getKey(checkpoint) { return `${checkpoint.iModelId}:${checkpoint.changeset.id}`; }
+    static async doDownload(request) {
+        try {
+            // first see if there's a V2 checkpoint available.
+            const changesetId = await V2CheckpointManager.downloadCheckpoint(request);
+            if (changesetId !== request.checkpoint.changeset.id)
+                core_bentley_1.Logger.logInfo(loggerCategory, `Downloaded previous v2 checkpoint because requested checkpoint not found.`, { requestedChangesetId: request.checkpoint.changeset.id, iModelId: request.checkpoint.iModelId, changesetId, iTwinId: request.checkpoint.iTwinId });
+            else
+                core_bentley_1.Logger.logInfo(loggerCategory, `Downloaded v2 checkpoint.`, { iModelId: request.checkpoint.iModelId, changesetId: request.checkpoint.changeset.id, iTwinId: request.checkpoint.iTwinId });
+            return changesetId;
+        }
+        catch (error) {
+            if (error.errorNumber === core_bentley_1.IModelStatus.NotFound) { // No V2 checkpoint available, try a v1 checkpoint
+                const changeset = await V1CheckpointManager.downloadCheckpoint(request);
+                core_bentley_1.Logger.logWarning(loggerCategory, `Got an error downloading v2 checkpoint, but downloaded v1 checkpoint successfully!`, { error, iModelId: request.checkpoint.iModelId, iTwinId: request.checkpoint.iTwinId, requestedChangesetId: request.checkpoint.changeset.id, changesetId: changeset });
+                return changeset;
+            }
+            throw error; // most likely, was aborted
+        }
+    }
+    static async updateToRequestedVersion(request) {
+        var _a;
+        const checkpoint = request.checkpoint;
+        const targetFile = request.localFile;
+        const traceInfo = { iTwinId: checkpoint.iTwinId, iModelId: checkpoint.iModelId, changeset: checkpoint.changeset };
+        try {
+            // Open checkpoint for write
+            const db = IModelDb_1.SnapshotDb.openForApplyChangesets(targetFile);
+            const nativeDb = db.nativeDb;
+            try {
+                if (nativeDb.hasPendingTxns()) {
+                    core_bentley_1.Logger.logWarning(loggerCategory, "Checkpoint with Txns found - deleting them", () => traceInfo);
+                    nativeDb.deleteAllTxns();
+                }
+                if (nativeDb.getBriefcaseId() !== core_common_1.BriefcaseIdValue.Unassigned)
+                    nativeDb.resetBriefcaseId(core_common_1.BriefcaseIdValue.Unassigned);
+                CheckpointManager.validateCheckpointGuids(checkpoint, db);
+                // Apply change sets if necessary
+                const currentChangeset = nativeDb.getCurrentChangeset();
+                if (currentChangeset.id !== checkpoint.changeset.id) {
+                    const accessToken = checkpoint.accessToken;
+                    const toIndex = (_a = checkpoint.changeset.index) !== null && _a !== void 0 ? _a : (await IModelHost_1.IModelHost.hubAccess.getChangesetFromVersion({ accessToken, iModelId: checkpoint.iModelId, version: core_common_1.IModelVersion.asOfChangeSet(checkpoint.changeset.id) })).index;
+                    await BriefcaseManager_1.BriefcaseManager.pullAndApplyChangesets(db, { accessToken, toIndex });
+                }
+                else {
+                    // make sure the parent changeset index is saved in the file - old versions didn't have it.
+                    currentChangeset.index = checkpoint.changeset.index; // eslint-disable-line @typescript-eslint/no-non-null-assertion
+                    nativeDb.saveLocalValue("parentChangeSet", JSON.stringify(currentChangeset));
+                }
+            }
+            finally {
+                db.saveChanges();
+                db.close();
+            }
+        }
+        catch (error) {
+            core_bentley_1.Logger.logError(loggerCategory, "Error downloading checkpoint - deleting it", () => traceInfo);
+            IModelJsFs_1.IModelJsFs.removeSync(targetFile);
+            if (error.errorNumber === core_bentley_1.ChangeSetStatus.CorruptedChangeStream || error.errorNumber === core_bentley_1.ChangeSetStatus.InvalidId || error.errorNumber === core_bentley_1.ChangeSetStatus.InvalidVersion) {
+                core_bentley_1.Logger.logError(loggerCategory, "Detected potential corruption of change sets. Deleting them to enable retries", () => traceInfo);
+                BriefcaseManager_1.BriefcaseManager.deleteChangeSetsFromLocalDisk(checkpoint.iModelId);
+            }
+            throw error;
+        }
+    }
+    /** Download a checkpoint file from iModelHub into a local file specified in the request parameters. */
+    static async downloadCheckpoint(request) {
+        if (this.verifyCheckpoint(request.checkpoint, request.localFile))
+            return;
+        if (request.aliasFiles) {
+            for (const alias of request.aliasFiles) {
+                if (this.verifyCheckpoint(request.checkpoint, alias)) {
+                    request.localFile = alias;
+                    return;
+                }
+            }
+        }
+        await this.doDownload(request);
+        return this.updateToRequestedVersion(request);
+    }
+    /** checks a file's dbGuid & iTwinId for consistency, and updates the dbGuid when possible */
+    static validateCheckpointGuids(checkpoint, snapshotDb) {
+        const traceInfo = { iTwinId: checkpoint.iTwinId, iModelId: checkpoint.iModelId };
+        const nativeDb = snapshotDb.nativeDb;
+        const dbChangeset = nativeDb.getCurrentChangeset();
+        const iModelId = core_bentley_1.Guid.normalize(nativeDb.getIModelId());
+        if (iModelId !== core_bentley_1.Guid.normalize(checkpoint.iModelId)) {
+            if (nativeDb.isReadonly())
+                throw new core_common_1.IModelError(core_bentley_1.IModelStatus.ValidationFailed, "iModelId is not properly set up in the checkpoint");
+            core_bentley_1.Logger.logWarning(loggerCategory, "iModelId is not properly set up in the checkpoint. Updated checkpoint to the correct iModelId.", () => ({ ...traceInfo, dbGuid: iModelId }));
+            const iModelIdNormalized = core_bentley_1.Guid.normalize(checkpoint.iModelId);
+            nativeDb.setIModelId(iModelIdNormalized);
+            snapshotDb._iModelId = iModelIdNormalized;
+            // Required to reset the ChangeSetId because setDbGuid clears the value.
+            nativeDb.saveLocalValue("ParentChangeSetId", dbChangeset.id);
+            if (undefined !== dbChangeset.index)
+                nativeDb.saveLocalValue("parentChangeSet", JSON.stringify(dbChangeset));
+        }
+        const iTwinId = core_bentley_1.Guid.normalize(nativeDb.getITwinId());
+        if (iTwinId !== core_bentley_1.Guid.normalize(checkpoint.iTwinId))
+            throw new core_common_1.IModelError(core_bentley_1.IModelStatus.ValidationFailed, "iTwinId was not properly set up in the checkpoint");
+    }
+    /** @returns true if the file is the checkpoint requested */
+    static verifyCheckpoint(checkpoint, fileName) {
+        if (!IModelJsFs_1.IModelJsFs.existsSync(fileName))
+            return false;
+        const nativeDb = new IModelHost_1.IModelHost.platform.DgnDb();
+        try {
+            nativeDb.openIModel(fileName, core_bentley_1.OpenMode.Readonly);
+        }
+        catch (error) {
+            return false;
+        }
+        const isValid = checkpoint.iModelId === nativeDb.getIModelId() && checkpoint.changeset.id === nativeDb.getCurrentChangeset().id;
+        nativeDb.closeIModel();
+        if (!isValid)
+            IModelJsFs_1.IModelJsFs.removeSync(fileName);
+        return isValid;
+    }
+    /** try to open an existing local file to satisfy a download request */
+    static tryOpenLocalFile(request) {
+        const checkpoint = request.checkpoint;
+        if (this.verifyCheckpoint(checkpoint, request.localFile))
+            return IModelDb_1.SnapshotDb.openCheckpointV1(request.localFile, checkpoint);
+        // check a list of aliases for finding checkpoints downloaded to non-default locations (e.g. from older versions)
+        if (request.aliasFiles) {
+            for (const alias of request.aliasFiles) {
+                if (this.verifyCheckpoint(checkpoint, alias)) {
+                    request.localFile = alias;
+                    return IModelDb_1.SnapshotDb.openCheckpointV1(alias, checkpoint);
+                }
+            }
+        }
+        return undefined;
+    }
+}
+exports.CheckpointManager = CheckpointManager;
+CheckpointManager.onDownloadV1 = new core_bentley_1.BeEvent();
+CheckpointManager.onDownloadV2 = new core_bentley_1.BeEvent();
 //# sourceMappingURL=CheckpointManager.js.map