@itwin/core-backend 3.0.0-dev.100

package/lib/cjs/IModelHost.d.ts

@@ -0,0 +1,284 @@
+/** @packageDocumentation
+ * @module IModelHost
+ */
+import { IModelJsNative } from "@bentley/imodeljs-native";
+import { TelemetryManager } from "@bentley/telemetry-client";
+import { AccessToken, BeEvent, GuidString, Mutable } from "@itwin/core-bentley";
+import { AuthorizationClient, SessionProps } from "@itwin/core-common";
+import { BackendHubAccess } from "./BackendHubAccess";
+import { CloudStorageService, CloudStorageServiceCredentials, CloudStorageTileUploader } from "./CloudStorageBackend";
+/** @alpha */
+export interface CrashReportingConfigNameValuePair {
+    name: string;
+    value: string;
+}
+/** Configuration of the crash-reporting system.
+ * @alpha
+ */
+export interface CrashReportingConfig {
+    /** The directory to which *.dmp and/or iModelJsNativeCrash*.properties.txt files are written. This directory will be created if it does not already exist. */
+    crashDir: string;
+    /** max # .dmp files that may exist in crashDir. The default is 50. */
+    maxDumpsInDir?: number;
+    /** Enable crash-dumps? If so, .dmp and .properties.txt files will be generated and written to crashDir in the event of an unhandled native-code exception. If not, only .properties.txt files will be written. The default is false. */
+    enableCrashDumps?: boolean;
+    /** If enableCrashDumps is true, do you want a full-memory dump? Defaults to false. */
+    wantFullMemoryDumps?: boolean;
+    /** Enable node-report? If so, node-report files will be generated in the event of an unhandled exception or fatal error and written to crashDir. The default is false. */
+    enableNodeReport?: boolean;
+    /** Additional name, value pairs to write to iModelJsNativeCrash*.properties.txt file in the event of a crash. */
+    params?: CrashReportingConfigNameValuePair[];
+    /** Run this .js file to process .dmp and node-report files in the event of a crash.
+     * This script will be executed with a single command-line parameter: the name of the dump or node-report file.
+     * In the case of a dump file, there will be a second file with the same basename and the extension ".properties.txt".
+     * Since it runs in a separate process, this script will have no access to the Javascript
+     * context of the exiting backend. No default.
+     */
+    dumpProcessorScriptFileName?: string;
+    /** Upload crash dump and node-reports to Bentley's crash-reporting service? Defaults to false */
+    uploadToBentley?: boolean;
+}
+/** Configuration of core-backend.
+ * @public
+ */
+export declare class IModelHostConfiguration {
+    /**
+     * Root of the directory holding all the files that iModel.js caches
+     * - If not specified at startup a platform specific default is used -
+     *   - Windows: $(HOMEDIR)/AppData/Local/iModelJs/
+     *   - Mac/iOS: $(HOMEDIR)/Library/Caches/iModelJs/
+     *   - Linux:   $(HOMEDIR)/.cache/iModelJs/
+     *   where $(HOMEDIR) is documented [here](https://nodejs.org/api/os.html#os_os_homedir)
+     * - if specified, ensure it is set to a folder with read/write access.
+     * - Sub-folders within this folder organize various caches -
+     *   - bc/ -> Briefcases
+     *   - appSettings/ -> Offline application settings (only relevant in native applications)
+     *   - etc.
+     * @see [[IModelHost.cacheDir]] for the value it's set to after startup
+     */
+    cacheDir?: string;
+    /** The directory where the app's assets are found. */
+    appAssetsDir?: string;
+    /** The kind of iModel hub server to use.
+     * @beta
+     */
+    hubAccess?: BackendHubAccess;
+    /** The credentials to use for the tile cache service. If omitted, a local cache will be used.
+     * @beta
+     */
+    tileCacheCredentials?: CloudStorageServiceCredentials;
+    /** Whether to restrict tile cache URLs by client IP address (if available).
+     * @beta
+     */
+    restrictTileUrlsByClientIp?: boolean;
+    /** Whether to compress cached tiles.
+     * Defaults to `true`.
+     */
+    compressCachedTiles?: boolean;
+    /** The time, in milliseconds, for which [IModelTileRpcInterface.requestTileTreeProps]($common) should wait before returning a "pending" status.
+     * @internal
+     */
+    tileTreeRequestTimeout: number;
+    /** The time, in milliseconds, for which [IModelTileRpcInterface.requestTileContent]($common) should wait before returning a "pending" status.
+     * @internal
+     */
+    tileContentRequestTimeout: number;
+    /** The default time, in milliseconds, used for [[tileTreeRequestTimeout]] and [[tileContentRequestTimeout]]. To change this, override one or both of those properties.
+     * @internal
+     */
+    static defaultTileRequestTimeout: number;
+    /** The default time, in seconds, used for [[logTileLoadTimeThreshold]]. To change this, override that property.
+     * @internal
+     */
+    static defaultLogTileLoadTimeThreshold: number;
+    /** The backend will log when a tile took longer to load than this threshold in seconds.
+     * @internal
+     */
+    logTileLoadTimeThreshold: number;
+    /** The default size, in bytes, used for [[logTileSizeThreshold]]. To change this, override that property.
+     * @internal
+     */
+    static defaultLogTileSizeThreshold: number;
+    /** The backend will log when a tile is loaded with a size in bytes above this threshold.
+     * @internal
+     */
+    logTileSizeThreshold: number;
+    /** Crash-reporting configuration
+     * @alpha
+     */
+    crashReportingConfig?: CrashReportingConfig;
+}
+/** IModelHost initializes ($backend) and captures its configuration. A backend must call [[IModelHost.startup]] before using any backend classes.
+ * See [the learning article]($docs/learning/backend/IModelHost.md)
+ * @public
+ */
+export declare class IModelHost {
+    private constructor();
+    static authorizationClient?: AuthorizationClient;
+    /** @alpha */
+    static readonly telemetry: TelemetryManager;
+    static backendVersion: string;
+    private static _cacheDir;
+    private static _platform?;
+    /** @internal */
+    static get platform(): typeof IModelJsNative;
+    static configuration?: IModelHostConfiguration;
+    /** Event raised just after the backend IModelHost was started */
+    static readonly onAfterStartup: BeEvent<() => void>;
+    /** Event raised just before the backend IModelHost is to be shut down */
+    static readonly onBeforeShutdown: BeEvent<() => void>;
+    /** @internal */
+    static readonly session: Mutable<SessionProps>;
+    /** A uniqueId for this session */
+    static get sessionId(): GuidString;
+    static set sessionId(id: GuidString);
+    /** The Id of this application - needs to be set only if it is an agent application. The applicationId will otherwise originate at the frontend. */
+    static get applicationId(): string;
+    static set applicationId(id: string);
+    /** The version of this application - needs to be set if is an agent application. The applicationVersion will otherwise originate at the frontend. */
+    static get applicationVersion(): string;
+    static set applicationVersion(version: string);
+    /** Root of the directory holding all the files that iModel.js caches */
+    static get cacheDir(): string;
+    /** The optional [[FileNameResolver]] that resolves keys and partial file names for snapshot iModels. */
+    static snapshotFileNameResolver?: FileNameResolver;
+    /** Get the current access token for this IModelHost, or a blank string if none is available.
+     * @note for web backends, this will *always* return a blank string because the backend itself has no token (but never needs one either.)
+     * For all IpcHosts, where this backend is servicing a single frontend, this will be the user's token. For ElectronHost, the backend
+     * obtains the token and forwards it to the frontend.
+     * @note accessTokens expire periodically and are automatically refreshed, if possible. Therefore tokens should not be saved, and the value
+     * returned by this method may change over time throughout the course of a session.
+     */
+    static getAccessToken(): Promise<AccessToken>;
+    /** @internal */
+    static flushLog(): void;
+    /** @internal */
+    static loadNative(): void;
+    private static registerPlatform;
+    private static validateNativePlatformVersion;
+    /**
+     * @beta
+     * @note A reference implementation is set by default for [AzureBlobStorage]. To supply a different implementation for any service provider (such as AWS),
+     *       set this property with a custom [CloudStorageService] and also set [IModelHostConfiguration.tileCacheCredentials] using "external" for the service name.
+     *       Note that the account and access key members of [CloudStorageServiceCredentials] may have blank values unless the custom service implementation uses them.
+     */
+    static tileCacheService: CloudStorageService;
+    /** @internal */
+    static tileUploader: CloudStorageTileUploader;
+    private static _hubAccess;
+    /** @internal */
+    static setHubAccess(hubAccess: BackendHubAccess): void;
+    /** Provides access to the IModelHub for this IModelHost
+     * @beta
+     */
+    static get hubAccess(): BackendHubAccess;
+    private static _isValid;
+    /** Returns true if IModelHost is started.  */
+    static get isValid(): boolean;
+    /** This method must be called before any iModel.js services are used.
+     * @param configuration Host configuration data.
+     * Raises [[onAfterStartup]].
+     * @see [[shutdown]].
+     */
+    static startup(configuration?: IModelHostConfiguration): Promise<void>;
+    private static _briefcaseCacheDir;
+    private static logStartup;
+    private static setupCacheDirs;
+    /** This method must be called when an iModel.js services is shut down. Raises [[onBeforeShutdown]] */
+    static shutdown(): Promise<void>;
+    /**
+     * Add or update a property that should be included in a crash report.
+     * @param name The name of the property
+     * @param value The value of the property
+     * @alpha
+     */
+    static setCrashReportProperty(name: string, value: string): void;
+    /**
+     * Remove a previously defined property so that will not be included in a crash report.
+     * @param name The name of the property
+     * @alpha
+     */
+    static removeCrashReportProperty(name: string): void;
+    /**
+     * Get all properties that will be included in a crash report.
+     * @alpha
+     */
+    static getCrashReportProperties(): CrashReportingConfigNameValuePair[];
+    /** The directory where application assets may be found */
+    static get appAssetsDir(): string | undefined;
+    /** The time, in milliseconds, for which [IModelTileRpcInterface.requestTileTreeProps]($common) should wait before returning a "pending" status.
+     * @internal
+     */
+    static get tileTreeRequestTimeout(): number;
+    /** The time, in milliseconds, for which [IModelTileRpcInterface.requestTileContent]($common) should wait before returning a "pending" status.
+     * @internal
+     */
+    static get tileContentRequestTimeout(): number;
+    /** The backend will log when a tile took longer to load than this threshold in seconds. */
+    static get logTileLoadTimeThreshold(): number;
+    /** The backend will log when a tile is loaded with a size in bytes above this threshold. */
+    static get logTileSizeThreshold(): number;
+    /** Whether external tile caching is active.
+     * @internal
+     */
+    static get usingExternalTileCache(): boolean;
+    /** Whether to restrict tile cache URLs by client IP address.
+     * @internal
+     */
+    static get restrictTileUrlsByClientIp(): boolean;
+    /** Whether to compress cached tiles.
+     * @internal
+     */
+    static get compressCachedTiles(): boolean;
+    private static setupTileCache;
+}
+/** Information about the platform on which the app is running. Also see [[KnownLocations]] and [[IModelJsFs]].
+ * @public
+ */
+export declare class Platform {
+    /** Get the name of the platform. */
+    static get platformName(): "win32" | "linux" | "darwin" | "ios" | "android" | "uwp";
+    /** @internal */
+    static load(): typeof IModelJsNative;
+}
+/** Well known directories that may be used by the application. Also see [[Platform]]
+ * @public
+ */
+export declare class KnownLocations {
+    /** The directory where the imodeljs-native assets are stored. */
+    static get nativeAssetsDir(): string;
+    /** The directory where the core-backend assets are stored. */
+    static get packageAssetsDir(): string;
+    /** The temporary directory. */
+    static get tmpdir(): string;
+}
+/** Extend this class to provide custom file name resolution behavior.
+ * @note Only `tryResolveKey` and/or `tryResolveFileName` need to be overridden as the implementations of `resolveKey` and `resolveFileName` work for most purposes.
+ * @see [[IModelHost.snapshotFileNameResolver]]
+ * @public
+ */
+export declare abstract class FileNameResolver {
+    /** Resolve a file name from the specified key.
+     * @param _fileKey The key that identifies the file name in a `Map` or other similar data structure.
+     * @returns The resolved file name or `undefined` if not found.
+     */
+    tryResolveKey(_fileKey: string): string | undefined;
+    /** Resolve a file name from the specified key.
+     * @param fileKey The key that identifies the file name in a `Map` or other similar data structure.
+     * @returns The resolved file name.
+     * @throws [[IModelError]] if not found.
+     */
+    resolveKey(fileKey: string): string;
+    /** Resolve the input file name, which may be a partial name, into a full path file name.
+     * @param inFileName The partial file name.
+     * @returns The resolved full path file name or `undefined` if not found.
+     */
+    tryResolveFileName(inFileName: string): string | undefined;
+    /** Resolve the input file name, which may be a partial name, into a full path file name.
+     * @param inFileName The partial file name.
+     * @returns The resolved full path file name.
+     * @throws [[IModelError]] if not found.
+     */
+    resolveFileName(inFileName: string): string;
+}
+//# sourceMappingURL=IModelHost.d.ts.map

package/lib/cjs/IModelHost.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IModelHost.d.ts","sourceRoot":"","sources":["../../src/IModelHost.ts"],"names":[],"mappings":"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"}