@itwin/core-backend 5.0.0-dev.99 → 5.1.0-dev.0

package/lib/esm/CloudSqlite.js

@@ -5,15 +5,17 @@
 /** @packageDocumentation
  * @module SQLiteDb
  */
+import * as semver from "semver";
 import { mkdirSync, unlinkSync } from "fs";
 import { dirname, join } from "path";
 import { NativeLibrary } from "@bentley/imodeljs-native";
 import { BeDuration, BriefcaseStatus, Logger, LogLevel, OpenMode, StopWatch, } from "@itwin/core-bentley";
+import { CloudSqliteError } from "@itwin/core-common";
 import { BlobContainer } from "./BlobContainerService";
 import { IModelHost, KnownLocations } from "./IModelHost";
 import { IModelJsFs } from "./IModelJsFs";
 import { RpcTrace } from "./rpc/tracing";
-// spell:ignore logmsg httpcode daemonless cachefile cacheslots ddthh
+// spell:ignore logmsg httpcode daemonless cachefile cacheslots ddthh cloudsqlite premajor preminor prepatch
 /**
  * Types for accessing SQLite databases stored in cloud containers.
  * @beta
@@ -22,6 +24,24 @@ export var CloudSqlite;
 (function (CloudSqlite) {
     const logInfo = (msg) => Logger.logInfo("CloudSqlite", msg);
     const logError = (msg) => Logger.logError("CloudSqlite", msg);
+    /** Add (or replace) a property to an object that is not enumerable.
+     * This is important so this member will be skipped when the object is the target of
+     * [structuredClone](https://developer.mozilla.org/docs/Web/API/Web_Workers_API/Structured_clone_algorithm)
+     * (e.g. when the object is part of an exception that is marshalled across process boundaries.)
+     */
+    function addHiddenProperty(o, p, value) {
+        return Object.defineProperty(o, p, { enumerable: false, writable: true, value });
+    }
+    CloudSqlite.addHiddenProperty = addHiddenProperty;
+    function verifyService(serviceName, service) {
+        if (undefined === service)
+            CloudSqliteError.throwError("service-not-available", { message: `${serviceName} service is not available` });
+        return service;
+    }
+    function getBlobService() {
+        return verifyService("BlobContainer", BlobContainer.service);
+    }
+    CloudSqlite.getBlobService = getBlobService;
     /**
      * Request a new AccessToken for a cloud container using the [[BlobContainer]] service.
      * If the service is unavailable or returns an error, an empty token is returned.
@@ -31,13 +51,21 @@ export var CloudSqlite;
         let userToken = args.userToken ? args.userToken : await IModelHost.getAccessToken();
         if (userToken === "")
             userToken = RpcTrace.currentActivity?.accessToken ?? "";
-        if (BlobContainer.service === undefined) {
-            throw new Error(`BlobContainer.service is not defined`);
-        }
-        const response = await BlobContainer.service.requestToken({ ...args, userToken });
+        const response = await getBlobService().requestToken({ ...args, userToken });
         return response?.token ?? "";
     }
     CloudSqlite.requestToken = requestToken;
+    function noLeadingOrTrailingSpaces(name, msg) {
+        if (name.trim() !== name)
+            CloudSqliteError.throwError("invalid-name", { message: `${msg} [${name}] may not have leading or trailing spaces` });
+    }
+    CloudSqlite.noLeadingOrTrailingSpaces = noLeadingOrTrailingSpaces;
+    function validateDbName(dbName) {
+        if (dbName === "" || dbName.length > 255 || /[#\.<>:"/\\"`'|?*\u0000-\u001F]/g.test(dbName) || /^(con|prn|aux|nul|com\d|lpt\d)$/i.test(dbName))
+            CloudSqliteError.throwError("invalid-name", { message: "invalid dbName", dbName });
+        noLeadingOrTrailingSpaces(dbName, "dbName");
+    }
+    CloudSqlite.validateDbName = validateDbName;
     /**
      * Create a new CloudContainer from a ContainerAccessProps. For non-public containers, a valid accessToken must be provided before the container
      * can be used (e.g. via [[CloudSqlite.requestToken]]).
@@ -46,6 +74,10 @@ export var CloudSqlite;
      */
     function createCloudContainer(args) {
         const container = new NativeLibrary.nativeLib.CloudContainer(args);
+        // we're going to add these fields to the newly created object. They should *not* be enumerable so they are not copied
+        // when the object is cloned (e.g. when included in an exception across processes).
+        addHiddenProperty(container, "timer");
+        addHiddenProperty(container, "refreshPromise");
         const refreshSeconds = (undefined !== args.tokenRefreshSeconds) ? args.tokenRefreshSeconds : 60 * 60; // default is 1 hour
         container.lockExpireSeconds = args.lockExpireSeconds ?? 60 * 60; // default is 1 hour
         // don't refresh tokens for public containers or if refreshSeconds<=0
@@ -71,13 +103,13 @@ export var CloudSqlite;
                     tokenRefreshFn(); // schedule next refresh
                 }, refreshSeconds * 1000);
             };
-            container.onConnected = tokenRefreshFn; // schedule the first refresh when the container is connected
-            container.onDisconnect = () => {
+            addHiddenProperty(container, "onConnected", tokenRefreshFn); // schedule the first refresh when the container is connected
+            addHiddenProperty(container, "onDisconnect", () => {
                 if (container.timer !== undefined) {
                     clearTimeout(container.timer);
                     container.timer = undefined;
                 }
-            };
+            });
         }
         return container;
     }
@@ -87,6 +119,7 @@ export var CloudSqlite;
         return new NativeLibrary.nativeLib.CloudPrefetch(container, dbName, args);
     }
     CloudSqlite.startCloudPrefetch = startCloudPrefetch;
+    ;
     /** Logging categories for `CloudCache.setLogMask` */
     let LoggingMask;
     (function (LoggingMask) {
@@ -209,50 +242,60 @@ export var CloudSqlite;
         const container = args.container;
         while (true) {
             try {
-                if (container.hasWriteLock) {
-                    if (container.writeLockHeldBy === args.user) {
-                        return container.acquireWriteLock(args.user); // refresh the write lock's expiry time.
-                    }
-                    const err = new Error(); // lock held by another user within this process
-                    err.errorNumber = 5;
-                    err.lockedBy = container.writeLockHeldBy;
-                    err.expires = container.writeLockExpires;
-                    throw err;
-                }
-                return container.acquireWriteLock(args.user);
+                // if the write is already held:
+                // - by the same user, just update the write lock expiry (by calling acquireWriteLock).
+                // - by another user, throw an error
+                if (container.hasWriteLock && container.writeLockHeldBy !== args.user)
+                    CloudSqliteError.throwError("write-lock-held", {
+                        message: "lock in use", errorNumber: 5,
+                        lockedBy: container.writeLockHeldBy ?? "",
+                        expires: container.writeLockExpires
+                    });
+                container.acquireWriteLock(args.user);
+                container.writeLockHeldBy = args.user;
+                return;
             }
             catch (e) {
                 if (e.errorNumber === 5 && args.busyHandler && "stop" !== await args.busyHandler(e.lockedBy, e.expires)) // 5 === BE_SQLITE_BUSY
                     continue; // busy handler wants to try again
-                throw e;
+                CloudSqliteError.throwError("write-lock-held", { message: e.message, ...e });
             }
         }
     }
     CloudSqlite.acquireWriteLock = acquireWriteLock;
+    function getWriteLockHeldBy(container) {
+        return container.writeLockHeldBy;
+    }
+    CloudSqlite.getWriteLockHeldBy = getWriteLockHeldBy;
+    /** release the write lock on a container. */
+    function releaseWriteLock(container) {
+        container.releaseWriteLock();
+        container.writeLockHeldBy = undefined;
+    }
+    CloudSqlite.releaseWriteLock = releaseWriteLock;
     /**
-   * Perform an asynchronous write operation on a CloudContainer with the write lock held.
-   * 1. if write lock is already held by the current user, refresh write lock's expiry time, call operation and return.
-   * 2. attempt to acquire the write lock, with retries. Throw if unable to obtain write lock.
-   * 3. perform the operation
-   * 3.a if the operation throws, abandon all changes and re-throw
-   * 4. release the write lock.
-   * 5. return value from operation
-   * @param user the name to be displayed to other users in the event they attempt to obtain the lock while it is held by us
-   * @param container the CloudContainer for which the lock is to be acquired
-   * @param operation an asynchronous operation performed with the write lock held.
-   * @param busyHandler if present, function called when the write lock is currently held by another user.
-   * @returns a Promise with the result of `operation`
-   */
+    * Perform an asynchronous write operation on a CloudContainer with the write lock held.
+    * 1. if write lock is already held by the current user, refresh write lock's expiry time, call operation and return.
+    * 2. attempt to acquire the write lock, with retries. Throw if unable to obtain write lock.
+    * 3. perform the operation
+    * 3.a if the operation throws, abandon all changes and re-throw
+    * 4. release the write lock.
+    * 5. return value from operation
+    * @param user the name to be displayed to other users in the event they attempt to obtain the lock while it is held by us
+    * @param container the CloudContainer for which the lock is to be acquired
+    * @param operation an asynchronous operation performed with the write lock held.
+    * @param busyHandler if present, function called when the write lock is currently held by another user.
+    * @returns a Promise with the result of `operation`
+    */
     async function withWriteLock(args, operation) {
-        await acquireWriteLock(args);
         const containerInternal = args.container;
+        const wasLockedBy = containerInternal.writeLockHeldBy;
+        await acquireWriteLock(args);
         try {
-            if (containerInternal.writeLockHeldBy === args.user) // If the user already had the write lock, then don't release it.
+            if (wasLockedBy === args.user) // If the user already had the write lock, then don't release it.
                 return await operation();
-            containerInternal.writeLockHeldBy = args.user;
             const val = await operation(); // wait for work to finish or fail
-            containerInternal.releaseWriteLock();
-            containerInternal.writeLockHeldBy = undefined;
+            releaseWriteLock(containerInternal);
             return val;
         }
         catch (e) {
@@ -262,6 +305,79 @@ export var CloudSqlite;
         }
     }
     CloudSqlite.withWriteLock = withWriteLock;
+    /**
+     * Parse the name of a Db stored in a CloudContainer into the dbName and version number. A single CloudContainer may hold
+     * many versions of the same Db. The name of the Db in the CloudContainer is in the format "name:version". This
+     * function splits them into separate strings.
+     */
+    function parseDbFileName(dbFileName) {
+        const parts = dbFileName.split(":");
+        return { dbName: parts[0], version: parts[1] ?? "" };
+    }
+    CloudSqlite.parseDbFileName = parseDbFileName;
+    function validateDbVersion(version) {
+        version = version ?? "0.0.0";
+        const opts = { loose: true, includePrerelease: true };
+        // clean allows prerelease, so try it first. If that fails attempt to coerce it (coerce strips prerelease even if you say not to.)
+        const semVersion = semver.clean(version, opts) ?? semver.coerce(version, opts)?.version;
+        if (!semVersion)
+            CloudSqliteError.throwError("invalid-name", { message: "invalid version specification" });
+        version = semVersion;
+        return version;
+    }
+    CloudSqlite.validateDbVersion = validateDbVersion;
+    function isSemverPrerelease(version) {
+        return semver.major(version) === 0 || semver.prerelease(version);
+    }
+    CloudSqlite.isSemverPrerelease = isSemverPrerelease;
+    function isSemverEditable(dbFullName, container) {
+        return isSemverPrerelease(parseDbFileName(dbFullName).version) || container.queryDatabase(dbFullName)?.state === "copied";
+    }
+    CloudSqlite.isSemverEditable = isSemverEditable;
+    /** Create a dbName for a database from its base name and version. This will be in the format "name:version" */
+    function makeSemverName(dbName, version) {
+        return `${dbName}:${validateDbVersion(version)}`;
+    }
+    CloudSqlite.makeSemverName = makeSemverName;
+    /** query the databases in the supplied container for the highest SemVer match according to the version range. Throws if no version available for the range. */
+    function querySemverMatch(props) {
+        const dbName = props.dbName;
+        const dbs = props.container.queryDatabases(`${dbName}*`); // get all databases that start with dbName
+        const versions = [];
+        for (const db of dbs) {
+            const thisDb = parseDbFileName(db);
+            if (thisDb.dbName === dbName && "string" === typeof thisDb.version && thisDb.version.length > 0)
+                versions.push(thisDb.version);
+        }
+        if (versions.length === 0)
+            versions[0] = "0.0.0";
+        const range = props.version ?? "*";
+        try {
+            const version = semver.maxSatisfying(versions, range, { loose: true, includePrerelease: props.includePrerelease });
+            if (version)
+                return `${dbName}:${version}`;
+        }
+        catch { }
+        CloudSqliteError.throwError("no-version-available", { message: `No version of '${dbName}' available for "${range}"`, ...props });
+    }
+    CloudSqlite.querySemverMatch = querySemverMatch;
+    async function createNewDbVersion(container, args) {
+        const oldFullName = CloudSqlite.querySemverMatch({ container, ...args.fromDb });
+        const oldDb = CloudSqlite.parseDbFileName(oldFullName);
+        const newVersion = semver.inc(oldDb.version, args.versionType, args.identifier);
+        if (!newVersion)
+            CloudSqliteError.throwError("invalid-name", { message: `cannot create new version for ${oldFullName}`, dbName: oldFullName, ...args });
+        const newName = makeSemverName(oldDb.dbName, newVersion);
+        try {
+            await container.copyDatabase(oldFullName, newName);
+        }
+        catch (e) {
+            CloudSqliteError.throwError("copy-error", { message: `Error attempting to create new version ${newName} from ${oldFullName}`, ...args, cause: e });
+        }
+        // return the old and new db names and versions
+        return { oldDb, newDb: { dbName: oldDb.dbName, version: newVersion } };
+    }
+    CloudSqlite.createNewDbVersion = createNewDbVersion;
     /** The collection of currently extant `CloudCache`s, by name. */
     class CloudCaches {
         static cloudCaches = new Map();
@@ -392,14 +508,9 @@ export var CloudSqlite;
          * @note the current user must have administrator rights to create containers.
          */
         static async createBlobContainer(args) {
-            const service = BlobContainer.service;
-            if (undefined === service)
-                throw new Error("no BlobContainer service available");
-            const auth = IModelHost.authorizationClient;
-            if (undefined === auth)
-                throw new Error("no authorization client available");
+            const auth = verifyService("Authorization Client", IModelHost.authorizationClient);
             const userToken = await auth.getAccessToken();
-            const cloudContainer = await service.create({ scope: args.scope, metadata: args.metadata, userToken });
+            const cloudContainer = await getBlobService().create({ scope: args.scope, metadata: args.metadata, userToken });
             return { baseUri: cloudContainer.baseUri, containerId: cloudContainer.containerId, storageType: cloudContainer.provider };
         }
         /**
@@ -469,7 +580,7 @@ export var CloudSqlite;
         getDbMethod(methodName) {
             const fn = this._cloudDb[methodName];
             if (typeof fn !== "function")
-                throw new Error(`illegal method name ${methodName}`);
+                CloudSqliteError.throwError("not-a-function", { message: `illegal method name ${methodName}`, dbName: this.dbName });
             return fn;
         }
         /**