@fluidframework/driver-utils 0.56.7 → 0.57.1

package/lib/treeConversions.js

@@ -0,0 +1,62 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { Uint8ArrayToString, unreachableCase, } from "@fluidframework/common-utils";
+import { AttachmentTreeEntry, BlobTreeEntry, TreeTreeEntry, } from "@fluidframework/protocol-base";
+import { SummaryType, } from "@fluidframework/protocol-definitions";
+/**
+ * Converts ISummaryTree to ITree format.
+ * @param summaryTree - summary tree in ISummaryTree format
+ */
+export function convertSummaryTreeToSnapshotITree(summaryTree) {
+    const entries = [];
+    const protocolSummary = summaryTree.tree[".protocol"];
+    const appSummary = summaryTree.tree[".app"];
+    // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
+    const adaptSumaryTree = protocolSummary && appSummary;
+    // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
+    const allSummaryEntries = adaptSumaryTree
+        ? [
+            ...Object.entries(protocolSummary.tree),
+            ...Object.entries(appSummary.tree),
+        ]
+        : Object.entries(summaryTree.tree);
+    for (const [key, value] of allSummaryEntries) {
+        // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
+        const k = adaptSumaryTree && ["attributes"].includes(key) ? `.${key}` : key;
+        switch (value.type) {
+            case SummaryType.Blob: {
+                let parsedContent;
+                let encoding = "utf-8";
+                if (typeof value.content === "string") {
+                    parsedContent = value.content;
+                }
+                else {
+                    parsedContent = Uint8ArrayToString(value.content, "base64");
+                    encoding = "base64";
+                }
+                entries.push(new BlobTreeEntry(k, parsedContent, encoding));
+                break;
+            }
+            case SummaryType.Tree: {
+                entries.push(new TreeTreeEntry(k, convertSummaryTreeToSnapshotITree(value)));
+                break;
+            }
+            case SummaryType.Attachment: {
+                entries.push(new AttachmentTreeEntry(k, value.id));
+                break;
+            }
+            case SummaryType.Handle: {
+                throw new Error("Should not have Handle type in summary tree");
+            }
+            default:
+                unreachableCase(value, "Unexpected summary tree type");
+        }
+    }
+    return {
+        entries,
+        unreferenced: summaryTree.unreferenced,
+    };
+}
+//# sourceMappingURL=treeConversions.js.map

package/lib/treeConversions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"treeConversions.js","sourceRoot":"","sources":["../src/treeConversions.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACH,kBAAkB,EAClB,eAAe,GAClB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACH,mBAAmB,EACnB,aAAa,EACb,aAAa,GAChB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAIH,WAAW,GACd,MAAM,sCAAsC,CAAC;AAE9C;;;GAGG;AACH,MAAM,UAAU,iCAAiC,CAC7C,WAAyB;IAEzB,MAAM,OAAO,GAAiB,EAAE,CAAC;IACjC,MAAM,eAAe,GAAG,WAAW,CAAC,IAAI,CAAC,WAAW,CAAiB,CAAC;IACtE,MAAM,UAAU,GAAG,WAAW,CAAC,IAAI,CAAC,MAAM,CAAiB,CAAC;IAC5D,yEAAyE;IACzE,MAAM,eAAe,GAAG,eAAe,IAAI,UAAU,CAAC;IACtD,yEAAyE;IACzE,MAAM,iBAAiB,GAAG,eAAe;QACrC,CAAC,CAAC;YACI,GAAG,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC,IAAI,CAAC;YACvC,GAAG,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC;SACrC;QACH,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;IAEvC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,iBAAiB,EAAE;QAC1C,yEAAyE;QACzE,MAAM,CAAC,GAAG,eAAe,IAAI,CAAC,YAAY,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;QAC5E,QAAQ,KAAK,CAAC,IAAI,EAAE;YAChB,KAAK,WAAW,CAAC,IAAI,CAAC,CAAC;gBACnB,IAAI,aAAqB,CAAC;gBAC1B,IAAI,QAAQ,GAAuB,OAAO,CAAC;gBAC3C,IAAI,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,EAAE;oBACnC,aAAa,GAAG,KAAK,CAAC,OAAO,CAAC;iBACjC;qBAAM;oBACH,aAAa,GAAG,kBAAkB,CAAC,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;oBAC5D,QAAQ,GAAG,QAAQ,CAAC;iBACvB;gBACD,OAAO,CAAC,IAAI,CAAC,IAAI,aAAa,CAAC,CAAC,EAAE,aAAa,EAAE,QAAQ,CAAC,CAAC,CAAC;gBAC5D,MAAM;aACT;YAED,KAAK,WAAW,CAAC,IAAI,CAAC,CAAC;gBACnB,OAAO,CAAC,IAAI,CACR,IAAI,aAAa,CACb,CAAC,EACD,iCAAiC,CAAC,KAAK,CAAC,CAC3C,CACJ,CAAC;gBACF,MAAM;aACT;YAED,KAAK,WAAW,CAAC,UAAU,CAAC,CAAC;gBACzB,OAAO,CAAC,IAAI,CAAC,IAAI,mBAAmB,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;gBACnD,MAAM;aACT;YAED,KAAK,WAAW,CAAC,MAAM,CAAC,CAAC;gBACrB,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;aAClE;YAED;gBACI,eAAe,CAAC,KAAK,EAAE,8BAA8B,CAAC,CAAC;SAC9D;KACJ;IACD,OAAO;QACH,OAAO;QACP,YAAY,EAAE,WAAW,CAAC,YAAY;KACzC,CAAC;AACN,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport {\n    Uint8ArrayToString,\n    unreachableCase,\n} from \"@fluidframework/common-utils\";\nimport {\n    AttachmentTreeEntry,\n    BlobTreeEntry,\n    TreeTreeEntry,\n} from \"@fluidframework/protocol-base\";\nimport {\n    ISummaryTree,\n    ITree,\n    ITreeEntry,\n    SummaryType,\n} from \"@fluidframework/protocol-definitions\";\n\n/**\n * Converts ISummaryTree to ITree format.\n * @param summaryTree - summary tree in ISummaryTree format\n */\nexport function convertSummaryTreeToSnapshotITree(\n    summaryTree: ISummaryTree,\n): ITree {\n    const entries: ITreeEntry[] = [];\n    const protocolSummary = summaryTree.tree[\".protocol\"] as ISummaryTree;\n    const appSummary = summaryTree.tree[\".app\"] as ISummaryTree;\n    // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions\n    const adaptSumaryTree = protocolSummary && appSummary;\n    // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions\n    const allSummaryEntries = adaptSumaryTree\n        ? [\n              ...Object.entries(protocolSummary.tree),\n              ...Object.entries(appSummary.tree),\n          ]\n        : Object.entries(summaryTree.tree);\n\n    for (const [key, value] of allSummaryEntries) {\n        // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions\n        const k = adaptSumaryTree && [\"attributes\"].includes(key) ? `.${key}` : key;\n        switch (value.type) {\n            case SummaryType.Blob: {\n                let parsedContent: string;\n                let encoding: \"utf-8\" | \"base64\" = \"utf-8\";\n                if (typeof value.content === \"string\") {\n                    parsedContent = value.content;\n                } else {\n                    parsedContent = Uint8ArrayToString(value.content, \"base64\");\n                    encoding = \"base64\";\n                }\n                entries.push(new BlobTreeEntry(k, parsedContent, encoding));\n                break;\n            }\n\n            case SummaryType.Tree: {\n                entries.push(\n                    new TreeTreeEntry(\n                        k,\n                        convertSummaryTreeToSnapshotITree(value),\n                    ),\n                );\n                break;\n            }\n\n            case SummaryType.Attachment: {\n                entries.push(new AttachmentTreeEntry(k, value.id));\n                break;\n            }\n\n            case SummaryType.Handle: {\n                throw new Error(\"Should not have Handle type in summary tree\");\n            }\n\n            default:\n                unreachableCase(value, \"Unexpected summary tree type\");\n        }\n    }\n    return {\n        entries,\n        unreferenced: summaryTree.unreferenced,\n    };\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/driver-utils",
-  "version": "0.56.7",
+  "version": "0.57.1",
   "description": "Collection of utility functions for Fluid drivers",
   "homepage": "https://fluidframework.com",
   "repository": "https://github.com/microsoft/FluidFramework",
@@ -62,15 +62,15 @@
     "@fluidframework/gitresources": "^0.1034.0",
     "@fluidframework/protocol-base": "^0.1034.0",
     "@fluidframework/protocol-definitions": "^0.1026.0",
-    "@fluidframework/telemetry-utils": "^0.56.7",
+    "@fluidframework/telemetry-utils": "^0.57.1",
     "axios": "^0.21.2",
     "uuid": "^8.3.1"
   },
   "devDependencies": {
     "@fluidframework/build-common": "^0.23.0",
-    "@fluidframework/eslint-config-fluid": "^0.25.0",
-    "@fluidframework/mocha-test-setup": "^0.56.7",
-    "@fluidframework/runtime-utils": "^0.56.7",
+    "@fluidframework/eslint-config-fluid": "^0.26.0",
+    "@fluidframework/mocha-test-setup": "^0.57.1",
+    "@fluidframework/runtime-utils": "^0.57.1",
     "@microsoft/api-extractor": "^7.16.1",
     "@rushstack/eslint-config": "^2.5.1",
     "@types/mocha": "^8.2.2",

package/src/blobAggregationStorage.ts

@@ -43,7 +43,7 @@ function bufferToString2(blob: ArrayBufferLike, encoding: "utf-8" | "base64"): s
   * Class responsible for aggregating smaller blobs into one and unpacking it later on.
   */
 class BlobAggregator {
-    private readonly content: [string, string][]= [];
+    private readonly content: [string, string][] = [];
 
     public addBlob(key: string, content: string) {
         this.content.push([key, content]);
@@ -172,7 +172,7 @@ export class BlobAggregationStorage extends SnapshotExtractor implements IDocume
             return storage;
         }
         const mc = loggerToMonitoringContext(logger);
-        const realAllowPackaging = mc.config.getBoolean("FluidAggregateBlobs") ??  allowPacking ?? false;
+        const realAllowPackaging = mc.config.getBoolean("FluidAggregateBlobs") ?? allowPacking ?? false;
 
         // Always create BlobAggregationStorage even if storage is not asking for packing.
         // This is mostly to avoid cases where future changes in policy would result in inability to

package/src/index.ts

@@ -19,3 +19,4 @@ export * from "./prefetchDocumentStorageService";
 export * from "./networkUtils";
 export * from "./rateLimiter";
 export * from "./runWithRetry";
+export * from "./treeConversions";

package/src/multiDocumentServiceFactory.ts

@@ -45,7 +45,6 @@ export class MultiDocumentServiceFactory implements IDocumentServiceFactory {
     async createDocumentService(resolvedUrl: IResolvedUrl, logger?: ITelemetryBaseLogger): Promise<IDocumentService> {
         ensureFluidResolvedUrl(resolvedUrl);
         const urlObj = parse(resolvedUrl.url);
-        // eslint-disable-next-line no-null/no-null
         if (urlObj.protocol === undefined || urlObj.protocol === null) {
             throw new Error("No protocol provided");
         }
@@ -64,7 +63,6 @@ export class MultiDocumentServiceFactory implements IDocumentServiceFactory {
     ): Promise<IDocumentService> {
         ensureFluidResolvedUrl(createNewResolvedUrl);
         const urlObj = parse(createNewResolvedUrl.url);
-        // eslint-disable-next-line no-null/no-null
         if (urlObj.protocol === undefined || urlObj.protocol === null) {
             throw new Error("No protocol provided");
         }

package/src/network.ts

@@ -22,13 +22,31 @@ export enum OnlineStatus {
 // No solution for node.js (other than resolve dns names / ping specific sites)
 // Can also use window.addEventListener("online" / "offline")
 export function isOnline(): OnlineStatus {
-    // eslint-disable-next-line no-null/no-null
     if (typeof navigator === "object" && navigator !== null && typeof navigator.onLine === "boolean") {
         return navigator.onLine ? OnlineStatus.Online : OnlineStatus.Offline;
     }
     return OnlineStatus.Unknown;
 }
 
+/**
+ * Interface describing errors and warnings raised by any driver code.
+ * Not expected to be implemented by a class or an object literal, but rather used in place of
+ * any or unknown in various function signatures that pass errors around.
+ *
+ * "Any" in the interface name is a nod to the fact that errorType has lost its type constraint.
+ * It will be either DriverErrorType or the specific driver's specialized error type enum,
+ * but we can't reference a specific driver's error type enum in this code.
+ */
+ export interface IAnyDriverError {
+    readonly errorType: string;
+    readonly message: string;
+    canRetry: boolean;
+    online?: string;
+}
+
+/** Telemetry props with driver-specific required properties */
+export type DriverErrorTelemetryProps = ITelemetryProperties & { driverVersion: string | undefined };
+
 /**
  * Generic network error class.
  */
@@ -39,7 +57,7 @@ export class GenericNetworkError extends LoggingError implements IDriverErrorBas
         readonly fluidErrorCode: string,
         message: string,
         readonly canRetry: boolean,
-        props?: ITelemetryProperties,
+        props: DriverErrorTelemetryProps,
     ) {
         super(message, props);
     }
@@ -57,8 +75,8 @@ export class DeltaStreamConnectionForbiddenError extends LoggingError implements
     readonly errorType: string = DeltaStreamConnectionForbiddenError.errorType;
     readonly canRetry = false;
 
-    constructor(readonly fluidErrorCode: string) {
-        super(fluidErrorCode, { statusCode: 400 });
+    constructor(readonly fluidErrorCode: string, props: DriverErrorTelemetryProps) {
+        super(fluidErrorCode, { ...props, statusCode: 400 });
     }
 }
 
@@ -71,7 +89,7 @@ export class AuthorizationError extends LoggingError implements IAuthorizationEr
         message: string,
         readonly claims: string | undefined,
         readonly tenantId: string | undefined,
-        props?: ITelemetryProperties,
+        props: DriverErrorTelemetryProps,
     ) {
         // don't log claims or tenantId
         super(message, props, new Set(["claims", "tenantId"]));
@@ -84,7 +102,7 @@ export class NetworkErrorBasic<T extends string> extends LoggingError implements
         message: string,
         readonly errorType: T,
         readonly canRetry: boolean,
-        props?: ITelemetryProperties,
+        props: DriverErrorTelemetryProps,
     ) {
         super(message, props);
     }
@@ -95,7 +113,7 @@ export class NonRetryableError<T extends string> extends NetworkErrorBasic<T> {
         fluidErrorCode: string,
         message: string | undefined,
         readonly errorType: T,
-        props?: ITelemetryProperties,
+        props: DriverErrorTelemetryProps,
     ) {
         super(fluidErrorCode, message ?? fluidErrorCode, errorType, false, props);
     }
@@ -106,13 +124,12 @@ export class RetryableError<T extends string> extends NetworkErrorBasic<T> {
         fluidErrorCode: string,
         message: string | undefined,
         readonly errorType: T,
-        props?: ITelemetryProperties,
+        props: DriverErrorTelemetryProps,
     ) {
         super(fluidErrorCode, message ?? fluidErrorCode, errorType, true, props);
     }
 }
 
-//* Check
 /**
  * Throttling error class - used to communicate all throttling errors
  */
@@ -124,26 +141,26 @@ export class ThrottlingError extends LoggingError implements IThrottlingWarning,
         readonly fluidErrorCode: string,
         message: string,
         readonly retryAfterSeconds: number,
-        props?: ITelemetryProperties,
+        props: DriverErrorTelemetryProps,
     ) {
         super(message, props);
     }
 }
 
-export const createWriteError = (fluidErrorCode: string) =>
-    new NonRetryableError(fluidErrorCode, undefined, DriverErrorType.writeError);
+export const createWriteError = (fluidErrorCode: string, props: DriverErrorTelemetryProps) =>
+    new NonRetryableError(fluidErrorCode, undefined, DriverErrorType.writeError, props);
 
 export function createGenericNetworkError(
     fluidErrorCode: string,
     message: string | undefined,
-    canRetry: boolean,
-    retryAfterMs?: number,
-    props?: ITelemetryProperties,
+    retryInfo: {canRetry: boolean, retryAfterMs?: number },
+    props: DriverErrorTelemetryProps,
 ): ThrottlingError | GenericNetworkError {
-    if (retryAfterMs !== undefined && canRetry) {
-        return new ThrottlingError(fluidErrorCode, message ?? fluidErrorCode, retryAfterMs / 1000, props);
+    if (retryInfo.retryAfterMs !== undefined && retryInfo.canRetry) {
+        return new ThrottlingError(
+            fluidErrorCode, message ?? fluidErrorCode, retryInfo.retryAfterMs / 1000, props);
     }
-    return new GenericNetworkError(fluidErrorCode, message ?? fluidErrorCode, canRetry, props);
+    return new GenericNetworkError(fluidErrorCode, message ?? fluidErrorCode, retryInfo.canRetry, props);
 }
 
 /**

package/src/networkUtils.ts

@@ -12,12 +12,9 @@ export function logNetworkFailure(logger: ITelemetryLogger, event: ITelemetryErr
     if (error?.online !== undefined) {
         newEvent.online = error.online as string;
     }
-
-    // eslint-disable-next-line no-null/no-null
     if (typeof navigator === "object" && navigator !== null) {
         const nav = navigator as any;
         const connection = nav.connection ?? nav.mozConnection ?? nav.webkitConnection;
-        // eslint-disable-next-line no-null/no-null
         if (connection !== null && typeof connection === "object") {
             newEvent.connectionType = connection.type;
         }

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/driver-utils";
-export const pkgVersion = "0.56.7";
+export const pkgVersion = "0.57.1";

package/src/parallelRequests.ts

@@ -9,6 +9,8 @@ import { ISequencedDocumentMessage } from "@fluidframework/protocol-definitions"
 import { IDeltasFetchResult, IStream, IStreamResult } from "@fluidframework/driver-definitions";
 import { getRetryDelayFromError, canRetryOnError, createGenericNetworkError } from "./network";
 import { waitForConnectedState, logNetworkFailure } from "./networkUtils";
+// For now, this package is versioned and released in unison with the specific drivers
+import { pkgVersion as driverVersion } from "./packageVersion";
 
 const MaxFetchDelayInMs = 10000;
 const MissingFetchDelayInMs = 100;
@@ -402,10 +404,10 @@ async function getSingleOpBatch(
                 throw createGenericNetworkError(
                     "failedToRetrieveOpsFromStorage:TooManyRetries",
                     undefined,
-                    false /* canRetry */,
-                    undefined /* retryAfterSeconds */,
+                    { canRetry: false },
                     {
                         retry,
+                        driverVersion,
                         ...props,
                     },
                 );

package/src/prefetchDocumentStorageService.ts

@@ -2,7 +2,6 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-/* eslint-disable no-null/no-null */
 import { LoaderCachingPolicy } from "@fluidframework/driver-definitions";
 import {
     ISnapshotTree,

package/src/treeConversions.ts

@@ -0,0 +1,86 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import {
+    Uint8ArrayToString,
+    unreachableCase,
+} from "@fluidframework/common-utils";
+import {
+    AttachmentTreeEntry,
+    BlobTreeEntry,
+    TreeTreeEntry,
+} from "@fluidframework/protocol-base";
+import {
+    ISummaryTree,
+    ITree,
+    ITreeEntry,
+    SummaryType,
+} from "@fluidframework/protocol-definitions";
+
+/**
+ * Converts ISummaryTree to ITree format.
+ * @param summaryTree - summary tree in ISummaryTree format
+ */
+export function convertSummaryTreeToSnapshotITree(
+    summaryTree: ISummaryTree,
+): ITree {
+    const entries: ITreeEntry[] = [];
+    const protocolSummary = summaryTree.tree[".protocol"] as ISummaryTree;
+    const appSummary = summaryTree.tree[".app"] as ISummaryTree;
+    // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
+    const adaptSumaryTree = protocolSummary && appSummary;
+    // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
+    const allSummaryEntries = adaptSumaryTree
+        ? [
+              ...Object.entries(protocolSummary.tree),
+              ...Object.entries(appSummary.tree),
+          ]
+        : Object.entries(summaryTree.tree);
+
+    for (const [key, value] of allSummaryEntries) {
+        // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
+        const k = adaptSumaryTree && ["attributes"].includes(key) ? `.${key}` : key;
+        switch (value.type) {
+            case SummaryType.Blob: {
+                let parsedContent: string;
+                let encoding: "utf-8" | "base64" = "utf-8";
+                if (typeof value.content === "string") {
+                    parsedContent = value.content;
+                } else {
+                    parsedContent = Uint8ArrayToString(value.content, "base64");
+                    encoding = "base64";
+                }
+                entries.push(new BlobTreeEntry(k, parsedContent, encoding));
+                break;
+            }
+
+            case SummaryType.Tree: {
+                entries.push(
+                    new TreeTreeEntry(
+                        k,
+                        convertSummaryTreeToSnapshotITree(value),
+                    ),
+                );
+                break;
+            }
+
+            case SummaryType.Attachment: {
+                entries.push(new AttachmentTreeEntry(k, value.id));
+                break;
+            }
+
+            case SummaryType.Handle: {
+                throw new Error("Should not have Handle type in summary tree");
+            }
+
+            default:
+                unreachableCase(value, "Unexpected summary tree type");
+        }
+    }
+    return {
+        entries,
+        unreferenced: summaryTree.unreferenced,
+    };
+}