@fluidframework/container-loader 1.4.0-121020 → 2.0.0-dev-rc.1.0.0.224419

package/lib/containerStorageAdapter.mjs

@@ -0,0 +1,228 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { bufferToString, stringToBuffer } from "@fluid-internal/client-utils";
+import { assert } from "@fluidframework/core-utils";
+import { UsageError } from "@fluidframework/driver-utils";
+import { ProtocolTreeStorageService } from "./protocolTreeDocumentStorageService.mjs";
+import { RetriableDocumentStorageService } from "./retriableDocumentStorageService.mjs";
+/**
+ * This class wraps the actual storage and make sure no wrong apis are called according to
+ * container attach state.
+ */
+export class ContainerStorageAdapter {
+    /**
+     * Whether the adapter will enforce sending combined summary trees.
+     */
+    get summarizeProtocolTree() {
+        return this._summarizeProtocolTree === true;
+    }
+    /**
+     * An adapter that ensures we're using detachedBlobStorage up until we connect to a real service, and then
+     * after connecting to a real service augments it with retry and combined summary tree enforcement.
+     * @param detachedBlobStorage - The detached blob storage to use up until we connect to a real service
+     * @param logger - Telemetry logger
+     * @param addProtocolSummaryIfMissing - a callback to permit the container to inspect the summary we're about to
+     * upload, and fix it up with a protocol tree if needed
+     * @param forceEnableSummarizeProtocolTree - Enforce uploading a protocol summary regardless of the service's policy
+     */
+    constructor(detachedBlobStorage, logger, 
+    /**
+     * ArrayBufferLikes or utf8 encoded strings, containing blobs from a snapshot
+     */
+    blobContents = {}, addProtocolSummaryIfMissing, forceEnableSummarizeProtocolTree) {
+        this.logger = logger;
+        this.blobContents = blobContents;
+        this.addProtocolSummaryIfMissing = addProtocolSummaryIfMissing;
+        this.disposed = false;
+        this._storageService = new BlobOnlyStorage(detachedBlobStorage, logger);
+        this._summarizeProtocolTree = forceEnableSummarizeProtocolTree;
+    }
+    dispose(error) {
+        this._storageService?.dispose?.(error);
+        this.disposed = true;
+    }
+    connectToService(service) {
+        if (!(this._storageService instanceof BlobOnlyStorage)) {
+            return;
+        }
+        const storageServiceP = service.connectToStorage();
+        const retriableStorage = (this._storageService = new RetriableDocumentStorageService(storageServiceP, this.logger));
+        this._summarizeProtocolTree =
+            this._summarizeProtocolTree ?? service.policies?.summarizeProtocolTree;
+        if (this.summarizeProtocolTree) {
+            this.logger.sendTelemetryEvent({ eventName: "summarizeProtocolTreeEnabled" });
+            this._storageService = new ProtocolTreeStorageService(retriableStorage, this.addProtocolSummaryIfMissing);
+        }
+    }
+    loadSnapshotForRehydratingContainer(snapshotTree) {
+        this.getBlobContents(snapshotTree);
+    }
+    getBlobContents(snapshotTree) {
+        if (snapshotTree.blobsContents !== undefined) {
+            for (const [id, value] of Object.entries(snapshotTree.blobsContents ?? {})) {
+                this.blobContents[id] = value;
+            }
+        }
+        for (const [_, tree] of Object.entries(snapshotTree.trees)) {
+            this.getBlobContents(tree);
+        }
+    }
+    get policies() {
+        // back-compat 0.40 containerRuntime requests policies even in detached container if storage is present
+        // and storage is always present in >=0.41.
+        try {
+            return this._storageService.policies;
+        }
+        catch (e) { }
+        return undefined;
+    }
+    get repositoryUrl() {
+        return this._storageService.repositoryUrl;
+    }
+    async getSnapshotTree(version, scenarioName) {
+        return this._storageService.getSnapshotTree(version, scenarioName);
+    }
+    async readBlob(id) {
+        const maybeBlob = this.blobContents[id];
+        if (maybeBlob !== undefined) {
+            if (typeof maybeBlob === "string") {
+                const blob = stringToBuffer(maybeBlob, "utf8");
+                return blob;
+            }
+            return maybeBlob;
+        }
+        return this._storageService.readBlob(id);
+    }
+    async getVersions(versionId, count, scenarioName, fetchSource) {
+        return this._storageService.getVersions(versionId, count, scenarioName, fetchSource);
+    }
+    async uploadSummaryWithContext(summary, context) {
+        return this._storageService.uploadSummaryWithContext(summary, context);
+    }
+    async downloadSummary(handle) {
+        return this._storageService.downloadSummary(handle);
+    }
+    async createBlob(file) {
+        return this._storageService.createBlob(file);
+    }
+}
+/**
+ * Storage which only supports createBlob() and readBlob(). This is used with IDetachedBlobStorage to support
+ * blobs in detached containers.
+ */
+class BlobOnlyStorage {
+    constructor(detachedStorage, logger) {
+        this.detachedStorage = detachedStorage;
+        this.logger = logger;
+        /* eslint-disable @typescript-eslint/unbound-method */
+        this.getSnapshotTree = this.notCalled;
+        this.getVersions = this.notCalled;
+        this.write = this.notCalled;
+        this.uploadSummaryWithContext = this.notCalled;
+        this.downloadSummary = this.notCalled;
+    }
+    async createBlob(content) {
+        return this.verifyStorage().createBlob(content);
+    }
+    async readBlob(blobId) {
+        return this.verifyStorage().readBlob(blobId);
+    }
+    verifyStorage() {
+        if (this.detachedStorage === undefined) {
+            throw new UsageError("Real storage calls not allowed in Unattached container");
+        }
+        return this.detachedStorage;
+    }
+    get policies() {
+        return this.notCalled();
+    }
+    get repositoryUrl() {
+        return this.notCalled();
+    }
+    /* eslint-enable @typescript-eslint/unbound-method */
+    notCalled() {
+        this.verifyStorage();
+        try {
+            // some browsers may not populate stack unless exception is thrown
+            throw new Error("BlobOnlyStorage not implemented method used");
+        }
+        catch (err) {
+            this.logger.sendTelemetryEvent({ eventName: "BlobOnlyStorageWrongCall" }, err);
+            throw err;
+        }
+    }
+}
+// runtime will write a tree to the summary containing "attachment" type entries
+// which reference attachment blobs by ID, along with a blob containing the blob redirect table.
+// However, some drivers do not support the "attachment" type and will convert them to "blob" type
+// entries. We want to avoid saving these to reduce the size of stashed change blobs, but we
+// need to make sure the blob redirect table is saved.
+const blobsTreeName = ".blobs";
+const redirectTableBlobName = ".redirectTable";
+/**
+ * Get blob contents of a snapshot tree from storage (or, ideally, cache)
+ */
+export async function getBlobContentsFromTree(snapshot, storage) {
+    const blobs = {};
+    await getBlobContentsFromTreeCore(snapshot, blobs, storage);
+    return blobs;
+}
+async function getBlobContentsFromTreeCore(tree, blobs, storage, root = true) {
+    const treePs = [];
+    for (const [key, subTree] of Object.entries(tree.trees)) {
+        if (root && key === blobsTreeName) {
+            treePs.push(getBlobManagerTreeFromTree(subTree, blobs, storage));
+        }
+        else {
+            treePs.push(getBlobContentsFromTreeCore(subTree, blobs, storage, false));
+        }
+    }
+    for (const id of Object.values(tree.blobs)) {
+        const blob = await storage.readBlob(id);
+        // ArrayBufferLike will not survive JSON.stringify()
+        blobs[id] = bufferToString(blob, "utf8");
+    }
+    return Promise.all(treePs);
+}
+// save redirect table from .blobs tree but nothing else
+async function getBlobManagerTreeFromTree(tree, blobs, storage) {
+    const id = tree.blobs[redirectTableBlobName];
+    const blob = await storage.readBlob(id);
+    // ArrayBufferLike will not survive JSON.stringify()
+    blobs[id] = bufferToString(blob, "utf8");
+}
+/**
+ * Extract blob contents from a snapshot tree with blob contents
+ */
+export function getBlobContentsFromTreeWithBlobContents(snapshot) {
+    const blobs = {};
+    getBlobContentsFromTreeWithBlobContentsCore(snapshot, blobs);
+    return blobs;
+}
+function getBlobContentsFromTreeWithBlobContentsCore(tree, blobs, root = true) {
+    for (const [key, subTree] of Object.entries(tree.trees)) {
+        if (root && key === blobsTreeName) {
+            getBlobManagerTreeFromTreeWithBlobContents(subTree, blobs);
+        }
+        else {
+            getBlobContentsFromTreeWithBlobContentsCore(subTree, blobs, false);
+        }
+    }
+    for (const id of Object.values(tree.blobs)) {
+        const blob = tree.blobsContents?.[id];
+        assert(blob !== undefined, 0x2ec /* "Blob must be present in blobsContents" */);
+        // ArrayBufferLike will not survive JSON.stringify()
+        blobs[id] = bufferToString(blob, "utf8");
+    }
+}
+// save redirect table from .blobs tree but nothing else
+function getBlobManagerTreeFromTreeWithBlobContents(tree, blobs) {
+    const id = tree.blobs[redirectTableBlobName];
+    const blob = tree.blobsContents?.[id];
+    assert(blob !== undefined, 0x70f /* Blob must be present in blobsContents */);
+    // ArrayBufferLike will not survive JSON.stringify()
+    blobs[id] = bufferToString(blob, "utf8");
+}
+//# sourceMappingURL=containerStorageAdapter.mjs.map

package/lib/containerStorageAdapter.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"containerStorageAdapter.mjs","sourceRoot":"","sources":["../src/containerStorageAdapter.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { IDisposable } from \"@fluidframework/core-interfaces\";\nimport { ITelemetryLoggerExt } from \"@fluidframework/telemetry-utils\";\nimport { bufferToString, stringToBuffer } from \"@fluid-internal/client-utils\";\nimport { assert } from \"@fluidframework/core-utils\";\nimport { ISnapshotTreeWithBlobContents } from \"@fluidframework/container-definitions\";\nimport {\n\tFetchSource,\n\tIDocumentService,\n\tIDocumentStorageService,\n\tIDocumentStorageServicePolicies,\n\tISummaryContext,\n} from \"@fluidframework/driver-definitions\";\nimport { UsageError } from \"@fluidframework/driver-utils\";\nimport {\n\tICreateBlobResponse,\n\tISnapshotTree,\n\tISummaryHandle,\n\tISummaryTree,\n\tIVersion,\n} from \"@fluidframework/protocol-definitions\";\nimport { IDetachedBlobStorage } from \"./loader\";\nimport { ProtocolTreeStorageService } from \"./protocolTreeDocumentStorageService\";\nimport { RetriableDocumentStorageService } from \"./retriableDocumentStorageService\";\n\n/**\n * Stringified blobs from a summary/snapshot tree.\n * @internal\n */\nexport interface ISerializableBlobContents {\n\t[id: string]: string;\n}\n\n/**\n * This class wraps the actual storage and make sure no wrong apis are called according to\n * container attach state.\n */\nexport class ContainerStorageAdapter implements IDocumentStorageService, IDisposable {\n\tprivate _storageService: IDocumentStorageService & Partial<IDisposable>;\n\n\tprivate _summarizeProtocolTree: boolean | undefined;\n\t/**\n\t * Whether the adapter will enforce sending combined summary trees.\n\t */\n\tpublic get summarizeProtocolTree() {\n\t\treturn this._summarizeProtocolTree === true;\n\t}\n\n\t/**\n\t * An adapter that ensures we're using detachedBlobStorage up until we connect to a real service, and then\n\t * after connecting to a real service augments it with retry and combined summary tree enforcement.\n\t * @param detachedBlobStorage - The detached blob storage to use up until we connect to a real service\n\t * @param logger - Telemetry logger\n\t * @param addProtocolSummaryIfMissing - a callback to permit the container to inspect the summary we're about to\n\t * upload, and fix it up with a protocol tree if needed\n\t * @param forceEnableSummarizeProtocolTree - Enforce uploading a protocol summary regardless of the service's policy\n\t */\n\tpublic constructor(\n\t\tdetachedBlobStorage: IDetachedBlobStorage | undefined,\n\t\tprivate readonly logger: ITelemetryLoggerExt,\n\t\t/**\n\t\t * ArrayBufferLikes or utf8 encoded strings, containing blobs from a snapshot\n\t\t */\n\t\tprivate readonly blobContents: { [id: string]: ArrayBufferLike | string } = {},\n\t\tprivate readonly addProtocolSummaryIfMissing: (summaryTree: ISummaryTree) => ISummaryTree,\n\t\tforceEnableSummarizeProtocolTree: boolean | undefined,\n\t) {\n\t\tthis._storageService = new BlobOnlyStorage(detachedBlobStorage, logger);\n\t\tthis._summarizeProtocolTree = forceEnableSummarizeProtocolTree;\n\t}\n\n\tdisposed: boolean = false;\n\tdispose(error?: Error): void {\n\t\tthis._storageService?.dispose?.(error);\n\t\tthis.disposed = true;\n\t}\n\n\tpublic connectToService(service: IDocumentService): void {\n\t\tif (!(this._storageService instanceof BlobOnlyStorage)) {\n\t\t\treturn;\n\t\t}\n\n\t\tconst storageServiceP = service.connectToStorage();\n\t\tconst retriableStorage = (this._storageService = new RetriableDocumentStorageService(\n\t\t\tstorageServiceP,\n\t\t\tthis.logger,\n\t\t));\n\n\t\tthis._summarizeProtocolTree =\n\t\t\tthis._summarizeProtocolTree ?? service.policies?.summarizeProtocolTree;\n\t\tif (this.summarizeProtocolTree) {\n\t\t\tthis.logger.sendTelemetryEvent({ eventName: \"summarizeProtocolTreeEnabled\" });\n\t\t\tthis._storageService = new ProtocolTreeStorageService(\n\t\t\t\tretriableStorage,\n\t\t\t\tthis.addProtocolSummaryIfMissing,\n\t\t\t);\n\t\t}\n\t}\n\n\tpublic loadSnapshotForRehydratingContainer(snapshotTree: ISnapshotTreeWithBlobContents) {\n\t\tthis.getBlobContents(snapshotTree);\n\t}\n\n\tprivate getBlobContents(snapshotTree: ISnapshotTreeWithBlobContents) {\n\t\tif (snapshotTree.blobsContents !== undefined) {\n\t\t\tfor (const [id, value] of Object.entries(snapshotTree.blobsContents ?? {})) {\n\t\t\t\tthis.blobContents[id] = value;\n\t\t\t}\n\t\t}\n\t\tfor (const [_, tree] of Object.entries(snapshotTree.trees)) {\n\t\t\tthis.getBlobContents(tree);\n\t\t}\n\t}\n\n\tpublic get policies(): IDocumentStorageServicePolicies | undefined {\n\t\t// back-compat 0.40 containerRuntime requests policies even in detached container if storage is present\n\t\t// and storage is always present in >=0.41.\n\t\ttry {\n\t\t\treturn this._storageService.policies;\n\t\t} catch (e) {}\n\t\treturn undefined;\n\t}\n\n\tpublic get repositoryUrl(): string {\n\t\treturn this._storageService.repositoryUrl;\n\t}\n\n\tpublic async getSnapshotTree(\n\t\tversion?: IVersion,\n\t\tscenarioName?: string,\n\t): Promise<ISnapshotTree | null> {\n\t\treturn this._storageService.getSnapshotTree(version, scenarioName);\n\t}\n\n\tpublic async readBlob(id: string): Promise<ArrayBufferLike> {\n\t\tconst maybeBlob = this.blobContents[id];\n\t\tif (maybeBlob !== undefined) {\n\t\t\tif (typeof maybeBlob === \"string\") {\n\t\t\t\tconst blob = stringToBuffer(maybeBlob, \"utf8\");\n\t\t\t\treturn blob;\n\t\t\t}\n\t\t\treturn maybeBlob;\n\t\t}\n\t\treturn this._storageService.readBlob(id);\n\t}\n\n\tpublic async getVersions(\n\t\tversionId: string | null,\n\t\tcount: number,\n\t\tscenarioName?: string,\n\t\tfetchSource?: FetchSource,\n\t): Promise<IVersion[]> {\n\t\treturn this._storageService.getVersions(versionId, count, scenarioName, fetchSource);\n\t}\n\n\tpublic async uploadSummaryWithContext(\n\t\tsummary: ISummaryTree,\n\t\tcontext: ISummaryContext,\n\t): Promise<string> {\n\t\treturn this._storageService.uploadSummaryWithContext(summary, context);\n\t}\n\n\tpublic async downloadSummary(handle: ISummaryHandle): Promise<ISummaryTree> {\n\t\treturn this._storageService.downloadSummary(handle);\n\t}\n\n\tpublic async createBlob(file: ArrayBufferLike): Promise<ICreateBlobResponse> {\n\t\treturn this._storageService.createBlob(file);\n\t}\n}\n\n/**\n * Storage which only supports createBlob() and readBlob(). This is used with IDetachedBlobStorage to support\n * blobs in detached containers.\n */\nclass BlobOnlyStorage implements IDocumentStorageService {\n\tconstructor(\n\t\tprivate readonly detachedStorage: IDetachedBlobStorage | undefined,\n\t\tprivate readonly logger: ITelemetryLoggerExt,\n\t) {}\n\n\tpublic async createBlob(content: ArrayBufferLike): Promise<ICreateBlobResponse> {\n\t\treturn this.verifyStorage().createBlob(content);\n\t}\n\n\tpublic async readBlob(blobId: string): Promise<ArrayBufferLike> {\n\t\treturn this.verifyStorage().readBlob(blobId);\n\t}\n\n\tprivate verifyStorage(): IDetachedBlobStorage {\n\t\tif (this.detachedStorage === undefined) {\n\t\t\tthrow new UsageError(\"Real storage calls not allowed in Unattached container\");\n\t\t}\n\t\treturn this.detachedStorage;\n\t}\n\n\tpublic get policies(): IDocumentStorageServicePolicies | undefined {\n\t\treturn this.notCalled();\n\t}\n\n\tpublic get repositoryUrl(): string {\n\t\treturn this.notCalled();\n\t}\n\n\t/* eslint-disable @typescript-eslint/unbound-method */\n\tpublic getSnapshotTree: () => Promise<ISnapshotTree | null> = this.notCalled;\n\tpublic getVersions: () => Promise<IVersion[]> = this.notCalled;\n\tpublic write: () => Promise<IVersion> = this.notCalled;\n\tpublic uploadSummaryWithContext: () => Promise<string> = this.notCalled;\n\tpublic downloadSummary: () => Promise<ISummaryTree> = this.notCalled;\n\t/* eslint-enable @typescript-eslint/unbound-method */\n\n\tprivate notCalled(): never {\n\t\tthis.verifyStorage();\n\t\ttry {\n\t\t\t// some browsers may not populate stack unless exception is thrown\n\t\t\tthrow new Error(\"BlobOnlyStorage not implemented method used\");\n\t\t} catch (err) {\n\t\t\tthis.logger.sendTelemetryEvent({ eventName: \"BlobOnlyStorageWrongCall\" }, err);\n\t\t\tthrow err;\n\t\t}\n\t}\n}\n\n// runtime will write a tree to the summary containing \"attachment\" type entries\n// which reference attachment blobs by ID, along with a blob containing the blob redirect table.\n// However, some drivers do not support the \"attachment\" type and will convert them to \"blob\" type\n// entries. We want to avoid saving these to reduce the size of stashed change blobs, but we\n// need to make sure the blob redirect table is saved.\nconst blobsTreeName = \".blobs\";\nconst redirectTableBlobName = \".redirectTable\";\n\n/**\n * Get blob contents of a snapshot tree from storage (or, ideally, cache)\n */\nexport async function getBlobContentsFromTree(\n\tsnapshot: ISnapshotTree,\n\tstorage: IDocumentStorageService,\n): Promise<ISerializableBlobContents> {\n\tconst blobs = {};\n\tawait getBlobContentsFromTreeCore(snapshot, blobs, storage);\n\treturn blobs;\n}\n\nasync function getBlobContentsFromTreeCore(\n\ttree: ISnapshotTree,\n\tblobs: ISerializableBlobContents,\n\tstorage: IDocumentStorageService,\n\troot = true,\n) {\n\tconst treePs: Promise<any>[] = [];\n\tfor (const [key, subTree] of Object.entries(tree.trees)) {\n\t\tif (root && key === blobsTreeName) {\n\t\t\ttreePs.push(getBlobManagerTreeFromTree(subTree, blobs, storage));\n\t\t} else {\n\t\t\ttreePs.push(getBlobContentsFromTreeCore(subTree, blobs, storage, false));\n\t\t}\n\t}\n\tfor (const id of Object.values(tree.blobs)) {\n\t\tconst blob = await storage.readBlob(id);\n\t\t// ArrayBufferLike will not survive JSON.stringify()\n\t\tblobs[id] = bufferToString(blob, \"utf8\");\n\t}\n\treturn Promise.all(treePs);\n}\n\n// save redirect table from .blobs tree but nothing else\nasync function getBlobManagerTreeFromTree(\n\ttree: ISnapshotTree,\n\tblobs: ISerializableBlobContents,\n\tstorage: IDocumentStorageService,\n) {\n\tconst id = tree.blobs[redirectTableBlobName];\n\tconst blob = await storage.readBlob(id);\n\t// ArrayBufferLike will not survive JSON.stringify()\n\tblobs[id] = bufferToString(blob, \"utf8\");\n}\n\n/**\n * Extract blob contents from a snapshot tree with blob contents\n */\nexport function getBlobContentsFromTreeWithBlobContents(\n\tsnapshot: ISnapshotTreeWithBlobContents,\n): ISerializableBlobContents {\n\tconst blobs = {};\n\tgetBlobContentsFromTreeWithBlobContentsCore(snapshot, blobs);\n\treturn blobs;\n}\n\nfunction getBlobContentsFromTreeWithBlobContentsCore(\n\ttree: ISnapshotTreeWithBlobContents,\n\tblobs: ISerializableBlobContents,\n\troot = true,\n) {\n\tfor (const [key, subTree] of Object.entries(tree.trees)) {\n\t\tif (root && key === blobsTreeName) {\n\t\t\tgetBlobManagerTreeFromTreeWithBlobContents(subTree, blobs);\n\t\t} else {\n\t\t\tgetBlobContentsFromTreeWithBlobContentsCore(subTree, blobs, false);\n\t\t}\n\t}\n\tfor (const id of Object.values(tree.blobs)) {\n\t\tconst blob = tree.blobsContents?.[id];\n\t\tassert(blob !== undefined, 0x2ec /* \"Blob must be present in blobsContents\" */);\n\t\t// ArrayBufferLike will not survive JSON.stringify()\n\t\tblobs[id] = bufferToString(blob, \"utf8\");\n\t}\n}\n\n// save redirect table from .blobs tree but nothing else\nfunction getBlobManagerTreeFromTreeWithBlobContents(\n\ttree: ISnapshotTreeWithBlobContents,\n\tblobs: ISerializableBlobContents,\n) {\n\tconst id = tree.blobs[redirectTableBlobName];\n\tconst blob = tree.blobsContents?.[id];\n\tassert(blob !== undefined, 0x70f /* Blob must be present in blobsContents */);\n\t// ArrayBufferLike will not survive JSON.stringify()\n\tblobs[id] = bufferToString(blob, \"utf8\");\n}\n"]}

package/lib/{contracts.d.ts → contracts.d.mts}

@@ -2,15 +2,28 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import { ITelemetryProperties } from "@fluidframework/common-definitions";
-import { IDeltaQueue, ReadOnlyInfo, IConnectionDetails, ICriticalContainerError, IFluidCodeDetails } from "@fluidframework/container-definitions";
-import { ConnectionMode, IDocumentMessage, ISequencedDocumentMessage, IClientConfiguration, IClientDetails, ISignalMessage } from "@fluidframework/protocol-definitions";
+import { IErrorBase, ITelemetryProperties } from "@fluidframework/core-interfaces";
+import { IConnectionDetails, ICriticalContainerError, IDeltaQueue, IFluidCodeDetails, ReadOnlyInfo } from "@fluidframework/container-definitions";
+import { ConnectionMode, IClientConfiguration, IClientDetails, IDocumentMessage, ISequencedDocumentMessage, ISignalClient, ISignalMessage } from "@fluidframework/protocol-definitions";
 import { IContainerPackageInfo } from "@fluidframework/driver-definitions";
 export declare enum ReconnectMode {
     Never = "Never",
     Disabled = "Disabled",
     Enabled = "Enabled"
 }
+export interface IConnectionStateChangeReason<T extends IErrorBase = IErrorBase> {
+    text: string;
+    error?: T;
+}
+/**
+ * Internal version of IConnectionDetails with props are only exposed internally
+ */
+export interface IConnectionDetailsInternal extends IConnectionDetails {
+    mode: ConnectionMode;
+    version: string;
+    initialClients: ISignalClient[];
+    reason: IConnectionStateChangeReason;
+}
 /**
  * Connection manager (implements this interface) is responsible for maintaining connection
  * to relay service.
@@ -37,7 +50,7 @@ export interface IConnectionManager {
      */
     prepareMessageToSend(message: Omit<IDocumentMessage, "clientSequenceNumber">): IDocumentMessage | undefined;
     /**
-     * Called before incomming message is processed. Incomming messages can be comming from connection,
+     * Called before incoming message is processed. Incoming messages can be combing from connection,
      * but also could come from storage.
      * This call allows connection manager to adjust knowledge about acked ops sent on previous connection.
      * Can be called at any time, including when there is no active connection.
@@ -47,7 +60,7 @@ export interface IConnectionManager {
      * Submits signal to relay service.
      * Called only when active connection is present.
      */
-    submitSignal(content: any): void;
+    submitSignal(content: any, targetClientId?: string): void;
     /**
      * Submits messages to relay service.
      * Called only when active connection is present.
@@ -56,28 +69,28 @@ export interface IConnectionManager {
     /**
      * Initiates connection to relay service (noop if already connected).
      */
-    connect(connectionMode?: ConnectionMode): void;
+    connect(reason: IConnectionStateChangeReason, connectionMode?: ConnectionMode): void;
     /**
      * Disposed connection manager
      */
-    dispose(error?: ICriticalContainerError): void;
+    dispose(error?: ICriticalContainerError, switchToReadonly?: boolean): void;
     get connectionMode(): ConnectionMode;
 }
 /**
  * This interface represents a set of callbacks provided by DeltaManager to IConnectionManager on its creation
- * IConnectionManager instance will use them to communicate to DeltaManager abour various events.
+ * IConnectionManager instance will use them to communicate to DeltaManager about various events.
  */
 export interface IConnectionManagerFactoryArgs {
     /**
-     * Called by connection manager for each incomming op. Some ops maybe delivered before
+     * Called by connection manager for each incoming op. Some ops maybe delivered before
      * connectHandler is called (initial ops on socket connection)
      */
     readonly incomingOpHandler: (messages: ISequencedDocumentMessage[], reason: string) => void;
     /**
-     * Called by connection manager for each incoming signals.
-     * Maybe called before connectHandler is called (initial signals on socket connection)
+     * Called by connection manager for each incoming signal.
+     * May be called before connectHandler is called (due to initial signals on socket connection)
      */
-    readonly signalHandler: (message: ISignalMessage) => void;
+    readonly signalHandler: (signals: ISignalMessage[]) => void;
     /**
      * Called when connection manager experiences delay in connecting to relay service.
      * This can happen because client is offline, or service is busy and asks to not connect for some time.
@@ -86,30 +99,45 @@ export interface IConnectionManagerFactoryArgs {
      */
     readonly reconnectionDelayHandler: (delayMs: number, error: unknown) => void;
     /**
-     * Called by connection manager whwnever critical error happens and container should be closed.
-     * Expects dispose() call in respose to this call.
+     * Called by connection manager whenever critical error happens and container should be closed.
+     * Expects dispose() call in response to this call.
      */
     readonly closeHandler: (error?: any) => void;
     /**
      * Called whenever connection to relay service is lost.
      */
-    readonly disconnectHandler: (reason: string) => void;
+    readonly disconnectHandler: (reason: IConnectionStateChangeReason) => void;
     /**
      * Called whenever new connection to rely service is established
      */
-    readonly connectHandler: (connection: IConnectionDetails) => void;
+    readonly connectHandler: (connection: IConnectionDetailsInternal) => void;
     /**
      * Called whenever ping/pong messages are roundtripped on connection.
      */
     readonly pongHandler: (latency: number) => void;
     /**
      * Called whenever connection type changes from writable to read-only or vice versa.
+     *
+     * @remarks
+     *
      * Connection can be read-only if user has no edit permissions, or if container forced
      * connection to be read-only.
      * This should not be confused with "read" / "write"connection mode which is internal
      * optimization.
+     *
+     * @param readonly - Whether or not the container is now read-only.
+     * `undefined` indicates that user permissions are not yet known.
+     * @param readonlyConnectionReason - reason/error if any for the change
+     */
+    readonly readonlyChangeHandler: (readonly?: boolean, readonlyConnectionReason?: IConnectionStateChangeReason) => void;
+    /**
+     * Called whenever we try to start establishing a new connection.
+     */
+    readonly establishConnectionHandler: (reason: IConnectionStateChangeReason) => void;
+    /**
+     * Called whenever we cancel the connection in progress.
      */
-    readonly readonlyChangeHandler: (readonly?: boolean) => void;
+    readonly cancelConnectionHandler: (reason: IConnectionStateChangeReason) => void;
 }
 /**
  *

package/lib/contracts.d.mts.map

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

package/lib/{contracts.js → contracts.mjs}

@@ -19,12 +19,12 @@ export const getPackageName = (codeDetails) => {
     if (codeDetails && "name" in codeDetails) {
         containerPackageName = codeDetails;
     }
-    else if (isFluidPackage(codeDetails === null || codeDetails === void 0 ? void 0 : codeDetails.package)) {
-        containerPackageName = codeDetails === null || codeDetails === void 0 ? void 0 : codeDetails.package.name;
+    else if (isFluidPackage(codeDetails?.package)) {
+        containerPackageName = codeDetails?.package.name;
     }
     else {
-        containerPackageName = codeDetails === null || codeDetails === void 0 ? void 0 : codeDetails.package;
+        containerPackageName = codeDetails?.package;
     }
     return { name: containerPackageName };
 };
-//# sourceMappingURL=contracts.js.map
+//# sourceMappingURL=contracts.mjs.map

package/lib/contracts.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.mjs","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"AAAA;;;GAGG;OAGI,EAKN,cAAc,GAEd,MAAM,uCAAuC;AAY9C,MAAM,CAAN,IAAY,aAIX;AAJD,WAAY,aAAa;IACxB,gCAAe,CAAA;IACf,sCAAqB,CAAA;IACrB,oCAAmB,CAAA;AACpB,CAAC,EAJW,aAAa,KAAb,aAAa,QAIxB;AA0KD;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAC7B,WAA0C,EAClB,EAAE;IAC1B,IAAI,oBAAoB,CAAC;IACzB,IAAI,WAAW,IAAI,MAAM,IAAI,WAAW,EAAE;QACzC,oBAAoB,GAAG,WAAW,CAAC;KACnC;SAAM,IAAI,cAAc,CAAC,WAAW,EAAE,OAAO,CAAC,EAAE;QAChD,oBAAoB,GAAG,WAAW,EAAE,OAAO,CAAC,IAAI,CAAC;KACjD;SAAM;QACN,oBAAoB,GAAG,WAAW,EAAE,OAAO,CAAC;KAC5C;IACD,OAAO,EAAE,IAAI,EAAE,oBAAoB,EAAE,CAAC;AACvC,CAAC,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { IErrorBase, ITelemetryProperties } from \"@fluidframework/core-interfaces\";\nimport {\n\tIConnectionDetails,\n\tICriticalContainerError,\n\tIDeltaQueue,\n\tIFluidCodeDetails,\n\tisFluidPackage,\n\tReadOnlyInfo,\n} from \"@fluidframework/container-definitions\";\nimport {\n\tConnectionMode,\n\tIClientConfiguration,\n\tIClientDetails,\n\tIDocumentMessage,\n\tISequencedDocumentMessage,\n\tISignalClient,\n\tISignalMessage,\n} from \"@fluidframework/protocol-definitions\";\nimport { IContainerPackageInfo } from \"@fluidframework/driver-definitions\";\n\nexport enum ReconnectMode {\n\tNever = \"Never\",\n\tDisabled = \"Disabled\",\n\tEnabled = \"Enabled\",\n}\n\nexport interface IConnectionStateChangeReason<T extends IErrorBase = IErrorBase> {\n\ttext: string;\n\terror?: T;\n}\n\n/**\n * Internal version of IConnectionDetails with props are only exposed internally\n */\nexport interface IConnectionDetailsInternal extends IConnectionDetails {\n\tmode: ConnectionMode;\n\tversion: string;\n\tinitialClients: ISignalClient[];\n\treason: IConnectionStateChangeReason;\n}\n\n/**\n * Connection manager (implements this interface) is responsible for maintaining connection\n * to relay service.\n */\nexport interface IConnectionManager {\n\treadonly connected: boolean;\n\n\treadonly clientId: string | undefined;\n\n\t/** The queue of outbound delta messages */\n\treadonly outbound: IDeltaQueue<IDocumentMessage[]>;\n\n\t/** Details of client */\n\treadonly clientDetails: IClientDetails;\n\n\t/** Protocol version being used to communicate with the service */\n\treadonly version: string;\n\n\t/** Max message size allowed to the delta manager */\n\treadonly maxMessageSize: number;\n\n\t/** Service configuration provided by the service. */\n\treadonly serviceConfiguration: IClientConfiguration | undefined;\n\n\treadonly readOnlyInfo: ReadOnlyInfo;\n\n\t// Various connectivity properties for telemetry describing type of current connection\n\t// Things like connection mode, service info, etc.\n\t// Called when connection state changes (connect / disconnect)\n\treadonly connectionProps: ITelemetryProperties;\n\n\t// Verbose information about connection logged to telemetry in case of issues with\n\t// maintaining healthy connection, including op gaps, not receiving join op in time, etc.\n\t// Contains details information, like sequence numbers at connection time, initial ops info, etc.\n\treadonly connectionVerboseProps: ITelemetryProperties;\n\n\t/**\n\t * Prepares message to be sent. Fills in clientSequenceNumber.\n\t * Called only when active connection is present.\n\t */\n\tprepareMessageToSend(\n\t\tmessage: Omit<IDocumentMessage, \"clientSequenceNumber\">,\n\t): IDocumentMessage | undefined;\n\n\t/**\n\t * Called before incoming message is processed. Incoming messages can be combing from connection,\n\t * but also could come from storage.\n\t * This call allows connection manager to adjust knowledge about acked ops sent on previous connection.\n\t * Can be called at any time, including when there is no active connection.\n\t */\n\tbeforeProcessingIncomingOp(message: ISequencedDocumentMessage): void;\n\n\t/**\n\t * Submits signal to relay service.\n\t * Called only when active connection is present.\n\t */\n\tsubmitSignal(content: any, targetClientId?: string): void;\n\n\t/**\n\t * Submits messages to relay service.\n\t * Called only when active connection is present.\n\t */\n\tsendMessages(messages: IDocumentMessage[]): void;\n\n\t/**\n\t * Initiates connection to relay service (noop if already connected).\n\t */\n\tconnect(reason: IConnectionStateChangeReason, connectionMode?: ConnectionMode): void;\n\n\t/**\n\t * Disposed connection manager\n\t */\n\tdispose(error?: ICriticalContainerError, switchToReadonly?: boolean): void;\n\n\tget connectionMode(): ConnectionMode;\n}\n\n/**\n * This interface represents a set of callbacks provided by DeltaManager to IConnectionManager on its creation\n * IConnectionManager instance will use them to communicate to DeltaManager about various events.\n */\nexport interface IConnectionManagerFactoryArgs {\n\t/**\n\t * Called by connection manager for each incoming op. Some ops maybe delivered before\n\t * connectHandler is called (initial ops on socket connection)\n\t */\n\treadonly incomingOpHandler: (messages: ISequencedDocumentMessage[], reason: string) => void;\n\n\t/**\n\t * Called by connection manager for each incoming signal.\n\t * May be called before connectHandler is called (due to initial signals on socket connection)\n\t */\n\treadonly signalHandler: (signals: ISignalMessage[]) => void;\n\n\t/**\n\t * Called when connection manager experiences delay in connecting to relay service.\n\t * This can happen because client is offline, or service is busy and asks to not connect for some time.\n\t * Can be called many times while not connected.\n\t * Situation is considered resolved when connection is established and connectHandler is called.\n\t */\n\treadonly reconnectionDelayHandler: (delayMs: number, error: unknown) => void;\n\n\t/**\n\t * Called by connection manager whenever critical error happens and container should be closed.\n\t * Expects dispose() call in response to this call.\n\t */\n\treadonly closeHandler: (error?: any) => void;\n\n\t/**\n\t * Called whenever connection to relay service is lost.\n\t */\n\treadonly disconnectHandler: (reason: IConnectionStateChangeReason) => void;\n\n\t/**\n\t * Called whenever new connection to rely service is established\n\t */\n\treadonly connectHandler: (connection: IConnectionDetailsInternal) => void;\n\n\t/**\n\t * Called whenever ping/pong messages are roundtripped on connection.\n\t */\n\treadonly pongHandler: (latency: number) => void;\n\n\t/**\n\t * Called whenever connection type changes from writable to read-only or vice versa.\n\t *\n\t * @remarks\n\t *\n\t * Connection can be read-only if user has no edit permissions, or if container forced\n\t * connection to be read-only.\n\t * This should not be confused with \"read\" / \"write\"connection mode which is internal\n\t * optimization.\n\t *\n\t * @param readonly - Whether or not the container is now read-only.\n\t * `undefined` indicates that user permissions are not yet known.\n\t * @param readonlyConnectionReason - reason/error if any for the change\n\t */\n\treadonly readonlyChangeHandler: (\n\t\treadonly?: boolean,\n\t\treadonlyConnectionReason?: IConnectionStateChangeReason,\n\t) => void;\n\n\t/**\n\t * Called whenever we try to start establishing a new connection.\n\t */\n\treadonly establishConnectionHandler: (reason: IConnectionStateChangeReason) => void;\n\n\t/**\n\t * Called whenever we cancel the connection in progress.\n\t */\n\treadonly cancelConnectionHandler: (reason: IConnectionStateChangeReason) => void;\n}\n\n/**\n *\n * @param codeDetails- - Data structure used to describe the code to load on the Fluid document\n * @returns The name of the Fluid package\n */\nexport const getPackageName = (\n\tcodeDetails: IFluidCodeDetails | undefined,\n): IContainerPackageInfo => {\n\tlet containerPackageName;\n\tif (codeDetails && \"name\" in codeDetails) {\n\t\tcontainerPackageName = codeDetails;\n\t} else if (isFluidPackage(codeDetails?.package)) {\n\t\tcontainerPackageName = codeDetails?.package.name;\n\t} else {\n\t\tcontainerPackageName = codeDetails?.package;\n\t}\n\treturn { name: containerPackageName };\n};\n"]}

package/lib/debugLogger.d.mts

@@ -0,0 +1,30 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { ITelemetryBaseEvent, ITelemetryBaseLogger } from "@fluidframework/core-interfaces";
+import { ITelemetryLoggerExt, ITelemetryLoggerPropertyBags } from "@fluidframework/telemetry-utils";
+/**
+ * Implementation of debug logger
+ */
+export declare class DebugLogger implements ITelemetryBaseLogger {
+    private readonly debug;
+    private readonly debugErr;
+    /**
+     * Mix in debug logger with another logger.
+     * Returned logger will output events to both newly created debug logger, as well as base logger
+     * @param namespace - Telemetry event name prefix to add to all events
+     * @param properties - Base properties to add to all events
+     * @param propertyGetters - Getters to add additional properties to all events
+     * @param baseLogger - Base logger to output events (in addition to debug logger being created). Can be undefined.
+     */
+    static mixinDebugLogger(namespace: string, baseLogger?: ITelemetryBaseLogger, properties?: ITelemetryLoggerPropertyBags): ITelemetryLoggerExt;
+    private constructor();
+    /**
+     * Send an event to debug loggers
+     *
+     * @param event - the event to send
+     */
+    send(event: ITelemetryBaseEvent): void;
+}
+//# sourceMappingURL=debugLogger.d.ts.map

package/lib/debugLogger.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debugLogger.d.ts","sourceRoot":"","sources":["../src/debugLogger.ts"],"names":[],"mappings":"AAAA;;;GAGG;OAEI,EACN,mBAAmB,EACnB,oBAAoB,EAEpB,MAAM,iCAAiC;OAGjC,EACN,mBAAmB,EACnB,4BAA4B,EAI5B,MAAM,iCAAiC;AAQxC;;GAEG;AACH,qBAAa,WAAY,YAAW,oBAAoB;IAwCtD,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAxC1B;;;;;;;OAOG;WACW,gBAAgB,CAC7B,SAAS,EAAE,MAAM,EACjB,UAAU,CAAC,EAAE,oBAAoB,EACjC,UAAU,CAAC,EAAE,4BAA4B,GACvC,mBAAmB;IA0BtB,OAAO;IAKP;;;;OAIG;IACI,IAAI,CAAC,KAAK,EAAE,mBAAmB,GAAG,IAAI;CA4C7C"}

package/lib/debugLogger.mjs

@@ -0,0 +1,93 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { performance } from "@fluid-internal/client-utils";
+import { createMultiSinkLogger, eventNamespaceSeparator, formatTick, } from "@fluidframework/telemetry-utils";
+import debugPkg from "debug";
+const { debug: registerDebug } = debugPkg;
+/**
+ * Implementation of debug logger
+ */
+export class DebugLogger {
+    /**
+     * Mix in debug logger with another logger.
+     * Returned logger will output events to both newly created debug logger, as well as base logger
+     * @param namespace - Telemetry event name prefix to add to all events
+     * @param properties - Base properties to add to all events
+     * @param propertyGetters - Getters to add additional properties to all events
+     * @param baseLogger - Base logger to output events (in addition to debug logger being created). Can be undefined.
+     */
+    static mixinDebugLogger(namespace, baseLogger, properties) {
+        // Setup base logger upfront, such that host can disable it (if needed)
+        const debug = registerDebug(namespace);
+        // Create one for errors that is always enabled
+        // It can be silenced by replacing console.error if the debug namespace is not enabled.
+        const debugErr = registerDebug(namespace);
+        debugErr.log = function (...args) {
+            if (debug.enabled === true) {
+                // if the namespace is enabled, just use the default logger
+                registerDebug.log(...args);
+            }
+            else {
+                // other wise, use the console logger (which could be replaced and silenced)
+                console.error(...args);
+            }
+        };
+        debugErr.enabled = true;
+        return createMultiSinkLogger({
+            namespace,
+            loggers: [baseLogger, new DebugLogger(debug, debugErr)],
+            properties,
+            tryInheritProperties: true,
+        });
+    }
+    constructor(debug, debugErr) {
+        this.debug = debug;
+        this.debugErr = debugErr;
+    }
+    /**
+     * Send an event to debug loggers
+     *
+     * @param event - the event to send
+     */
+    send(event) {
+        const newEvent = { ...event };
+        const isError = newEvent.category === "error";
+        let logger = isError ? this.debugErr : this.debug;
+        // Use debug's coloring schema for base of the event
+        const index = event.eventName.lastIndexOf(eventNamespaceSeparator);
+        const name = event.eventName.substring(index + 1);
+        if (index > 0) {
+            logger = logger.extend(event.eventName.substring(0, index));
+        }
+        newEvent.eventName = undefined;
+        let tick = "";
+        tick = `tick=${formatTick(performance.now())}`;
+        // Extract stack to put it last, but also to avoid escaping '\n' in it by JSON.stringify below
+        const stack = newEvent.stack ?? "";
+        newEvent.stack = undefined;
+        // Watch out for circular references - they can come from two sources
+        // 1) error object - we do not control it and should remove it and retry
+        // 2) properties supplied by telemetry caller - that's a bug that should be addressed!
+        let payload;
+        try {
+            payload = JSON.stringify(newEvent);
+        }
+        catch (error) {
+            newEvent.error = undefined;
+            payload = JSON.stringify(newEvent);
+        }
+        if (payload === "{}") {
+            payload = "";
+        }
+        // Force errors out, to help with diagnostics
+        if (isError) {
+            logger.enabled = true;
+        }
+        // Print multi-line.
+        // eslint-disable-next-line @typescript-eslint/no-base-to-string
+        logger(`${name} ${payload} ${tick} ${stack}`);
+    }
+}
+//# sourceMappingURL=debugLogger.mjs.map

package/lib/debugLogger.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"debugLogger.mjs","sourceRoot":"","sources":["../src/debugLogger.ts"],"names":[],"mappings":"AAAA;;;GAGG;OAOI,EAAE,WAAW,EAAE,MAAM,8BAA8B;OAEnD,EAGN,qBAAqB,EACrB,uBAAuB,EACvB,UAAU,GACV,MAAM,iCAAiC;OAGjC,QAAQ,MAAM,OAAO;AAC5B,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,QAAQ,CAAC;AAI1C;;GAEG;AACH,MAAM,OAAO,WAAW;IACvB;;;;;;;OAOG;IACI,MAAM,CAAC,gBAAgB,CAC7B,SAAiB,EACjB,UAAiC,EACjC,UAAyC;QAEzC,uEAAuE;QACvE,MAAM,KAAK,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;QAEvC,+CAA+C;QAC/C,uFAAuF;QACvF,MAAM,QAAQ,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;QAC1C,QAAQ,CAAC,GAAG,GAAG,UAAU,GAAG,IAAI;YAC/B,IAAI,KAAK,CAAC,OAAO,KAAK,IAAI,EAAE;gBAC3B,2DAA2D;gBAC3D,aAAa,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;aAC3B;iBAAM;gBACN,4EAA4E;gBAC5E,OAAO,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,CAAC;aACvB;QACF,CAAC,CAAC;QACF,QAAQ,CAAC,OAAO,GAAG,IAAI,CAAC;QAExB,OAAO,qBAAqB,CAAC;YAC5B,SAAS;YACT,OAAO,EAAE,CAAC,UAAU,EAAE,IAAI,WAAW,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;YACvD,UAAU;YACV,oBAAoB,EAAE,IAAI;SAC1B,CAAC,CAAC;IACJ,CAAC;IAED,YACkB,KAAgB,EAChB,QAAmB;QADnB,UAAK,GAAL,KAAK,CAAW;QAChB,aAAQ,GAAR,QAAQ,CAAW;IAClC,CAAC;IAEJ;;;;OAIG;IACI,IAAI,CAAC,KAA0B;QACrC,MAAM,QAAQ,GAAyB,EAAE,GAAG,KAAK,EAAE,CAAC;QACpD,MAAM,OAAO,GAAG,QAAQ,CAAC,QAAQ,KAAK,OAAO,CAAC;QAC9C,IAAI,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC;QAElD,oDAAoD;QACpD,MAAM,KAAK,GAAG,KAAK,CAAC,SAAS,CAAC,WAAW,CAAC,uBAAuB,CAAC,CAAC;QACnE,MAAM,IAAI,GAAG,KAAK,CAAC,SAAS,CAAC,SAAS,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;QAClD,IAAI,KAAK,GAAG,CAAC,EAAE;YACd,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;SAC5D;QACD,QAAQ,CAAC,SAAS,GAAG,SAAS,CAAC;QAE/B,IAAI,IAAI,GAAG,EAAE,CAAC;QACd,IAAI,GAAG,QAAQ,UAAU,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC;QAE/C,8FAA8F;QAC9F,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,IAAI,EAAE,CAAC;QACnC,QAAQ,CAAC,KAAK,GAAG,SAAS,CAAC;QAE3B,qEAAqE;QACrE,wEAAwE;QACxE,sFAAsF;QACtF,IAAI,OAAe,CAAC;QACpB,IAAI;YACH,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;SACnC;QAAC,OAAO,KAAK,EAAE;YACf,QAAQ,CAAC,KAAK,GAAG,SAAS,CAAC;YAC3B,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;SACnC;QAED,IAAI,OAAO,KAAK,IAAI,EAAE;YACrB,OAAO,GAAG,EAAE,CAAC;SACb;QAED,6CAA6C;QAC7C,IAAI,OAAO,EAAE;YACZ,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;SACtB;QAED,oBAAoB;QACpB,gEAAgE;QAChE,MAAM,CAAC,GAAG,IAAI,IAAI,OAAO,IAAI,IAAI,IAAI,KAAK,EAAE,CAAC,CAAC;IAC/C,CAAC;CACD","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport {\n\tITelemetryBaseEvent,\n\tITelemetryBaseLogger,\n\tITelemetryProperties,\n} from \"@fluidframework/core-interfaces\";\nimport { performance } from \"@fluid-internal/client-utils\";\n\nimport {\n\tITelemetryLoggerExt,\n\tITelemetryLoggerPropertyBags,\n\tcreateMultiSinkLogger,\n\teventNamespaceSeparator,\n\tformatTick,\n} from \"@fluidframework/telemetry-utils\";\n\n// This import style is necessary to ensure the emitted JS code works in both CJS and ESM.\nimport debugPkg from \"debug\";\nconst { debug: registerDebug } = debugPkg;\n\nimport type { IDebugger } from \"debug\";\n\n/**\n * Implementation of debug logger\n */\nexport class DebugLogger implements ITelemetryBaseLogger {\n\t/**\n\t * Mix in debug logger with another logger.\n\t * Returned logger will output events to both newly created debug logger, as well as base logger\n\t * @param namespace - Telemetry event name prefix to add to all events\n\t * @param properties - Base properties to add to all events\n\t * @param propertyGetters - Getters to add additional properties to all events\n\t * @param baseLogger - Base logger to output events (in addition to debug logger being created). Can be undefined.\n\t */\n\tpublic static mixinDebugLogger(\n\t\tnamespace: string,\n\t\tbaseLogger?: ITelemetryBaseLogger,\n\t\tproperties?: ITelemetryLoggerPropertyBags,\n\t): ITelemetryLoggerExt {\n\t\t// Setup base logger upfront, such that host can disable it (if needed)\n\t\tconst debug = registerDebug(namespace);\n\n\t\t// Create one for errors that is always enabled\n\t\t// It can be silenced by replacing console.error if the debug namespace is not enabled.\n\t\tconst debugErr = registerDebug(namespace);\n\t\tdebugErr.log = function (...args) {\n\t\t\tif (debug.enabled === true) {\n\t\t\t\t// if the namespace is enabled, just use the default logger\n\t\t\t\tregisterDebug.log(...args);\n\t\t\t} else {\n\t\t\t\t// other wise, use the console logger (which could be replaced and silenced)\n\t\t\t\tconsole.error(...args);\n\t\t\t}\n\t\t};\n\t\tdebugErr.enabled = true;\n\n\t\treturn createMultiSinkLogger({\n\t\t\tnamespace,\n\t\t\tloggers: [baseLogger, new DebugLogger(debug, debugErr)],\n\t\t\tproperties,\n\t\t\ttryInheritProperties: true,\n\t\t});\n\t}\n\n\tprivate constructor(\n\t\tprivate readonly debug: IDebugger,\n\t\tprivate readonly debugErr: IDebugger,\n\t) {}\n\n\t/**\n\t * Send an event to debug loggers\n\t *\n\t * @param event - the event to send\n\t */\n\tpublic send(event: ITelemetryBaseEvent): void {\n\t\tconst newEvent: ITelemetryProperties = { ...event };\n\t\tconst isError = newEvent.category === \"error\";\n\t\tlet logger = isError ? this.debugErr : this.debug;\n\n\t\t// Use debug's coloring schema for base of the event\n\t\tconst index = event.eventName.lastIndexOf(eventNamespaceSeparator);\n\t\tconst name = event.eventName.substring(index + 1);\n\t\tif (index > 0) {\n\t\t\tlogger = logger.extend(event.eventName.substring(0, index));\n\t\t}\n\t\tnewEvent.eventName = undefined;\n\n\t\tlet tick = \"\";\n\t\ttick = `tick=${formatTick(performance.now())}`;\n\n\t\t// Extract stack to put it last, but also to avoid escaping '\\n' in it by JSON.stringify below\n\t\tconst stack = newEvent.stack ?? \"\";\n\t\tnewEvent.stack = undefined;\n\n\t\t// Watch out for circular references - they can come from two sources\n\t\t// 1) error object - we do not control it and should remove it and retry\n\t\t// 2) properties supplied by telemetry caller - that's a bug that should be addressed!\n\t\tlet payload: string;\n\t\ttry {\n\t\t\tpayload = JSON.stringify(newEvent);\n\t\t} catch (error) {\n\t\t\tnewEvent.error = undefined;\n\t\t\tpayload = JSON.stringify(newEvent);\n\t\t}\n\n\t\tif (payload === \"{}\") {\n\t\t\tpayload = \"\";\n\t\t}\n\n\t\t// Force errors out, to help with diagnostics\n\t\tif (isError) {\n\t\t\tlogger.enabled = true;\n\t\t}\n\n\t\t// Print multi-line.\n\t\t// eslint-disable-next-line @typescript-eslint/no-base-to-string\n\t\tlogger(`${name} ${payload} ${tick} ${stack}`);\n\t}\n}\n"]}