@fluidframework/driver-utils 1.2.7 → 2.0.0-dev.1.3.0.96595

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/driver-utils",
-  "version": "1.2.7",
+  "version": "2.0.0-dev.1.3.0.96595",
   "description": "Collection of utility functions for Fluid drivers",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -61,29 +61,30 @@
   },
   "dependencies": {
     "@fluidframework/common-definitions": "^0.20.1",
-    "@fluidframework/common-utils": "^0.32.1",
-    "@fluidframework/core-interfaces": "^1.2.7",
-    "@fluidframework/driver-definitions": "^1.2.7",
-    "@fluidframework/gitresources": "^0.1036.5000",
-    "@fluidframework/protocol-base": "^0.1036.5000",
-    "@fluidframework/protocol-definitions": "^0.1028.2000",
-    "@fluidframework/telemetry-utils": "^1.2.7",
+    "@fluidframework/common-utils": "^1.0.0",
+    "@fluidframework/core-interfaces": "2.0.0-dev.1.3.0.96595",
+    "@fluidframework/driver-definitions": "2.0.0-dev.1.3.0.96595",
+    "@fluidframework/gitresources": "^0.1037.2001",
+    "@fluidframework/protocol-base": "^0.1037.2001",
+    "@fluidframework/protocol-definitions": "^1.0.0",
+    "@fluidframework/telemetry-utils": "2.0.0-dev.1.3.0.96595",
     "axios": "^0.26.0",
+    "url": "^0.11.0",
     "uuid": "^8.3.1"
   },
   "devDependencies": {
-    "@fluidframework/build-common": "^0.24.0",
-    "@fluidframework/build-tools": "^0.2.74327",
-    "@fluidframework/driver-utils-previous": "npm:@fluidframework/driver-utils@1.2.1",
-    "@fluidframework/eslint-config-fluid": "^0.28.2000",
-    "@fluidframework/mocha-test-setup": "^1.2.7",
-    "@fluidframework/runtime-utils": "^1.2.7",
+    "@fluidframework/build-common": "^1.0.0",
+    "@fluidframework/build-tools": "^0.4.6000",
+    "@fluidframework/driver-utils-previous": "npm:@fluidframework/driver-utils@^1.0.0",
+    "@fluidframework/eslint-config-fluid": "^1.0.0",
+    "@fluidframework/mocha-test-setup": "2.0.0-dev.1.3.0.96595",
+    "@fluidframework/runtime-utils": "2.0.0-dev.1.3.0.96595",
     "@microsoft/api-extractor": "^7.22.2",
     "@rushstack/eslint-config": "^2.5.1",
     "@types/mocha": "^9.1.1",
     "@types/node": "^14.18.0",
     "concurrently": "^6.2.0",
-    "copyfiles": "^2.1.0",
+    "copyfiles": "^2.4.1",
     "cross-env": "^7.0.2",
     "eslint": "~8.6.0",
     "mocha": "^10.0.0",
@@ -93,7 +94,29 @@
     "typescript-formatter": "7.1.0"
   },
   "typeValidation": {
-    "version": "1.2.2",
-    "broken": {}
+    "version": "2.0.0",
+    "broken": {
+      "RemovedFunctionDeclaration_convertSnapshotAndBlobsToSummaryTree": {
+        "forwardCompat": false,
+        "backCompat": false
+      },
+      "RemovedInterfaceDeclaration_ISummaryTreeAssemblerProps": {
+        "forwardCompat": false,
+        "backCompat": false
+      },
+      "RemovedClassDeclaration_SummaryTreeAssembler": {
+        "forwardCompat": false,
+        "backCompat": false
+      },
+      "ClassDeclaration_AuthorizationError": {
+        "backCompat": false
+      },
+      "ClassDeclaration_GenericNetworkError": {
+        "backCompat": false
+      },
+      "ClassDeclaration_ThrottlingError": {
+        "backCompat": false
+      }
+    }
   }
 }

package/src/documentStorageServiceProxy.ts

@@ -4,6 +4,7 @@
  */
 
 import {
+    FetchSource,
     IDocumentStorageService,
     IDocumentStorageServicePolicies,
     ISummaryContext,
@@ -37,8 +38,13 @@ export class DocumentStorageServiceProxy implements IDocumentStorageService {
         return this.internalStorageService.getSnapshotTree(version, scenarioName);
     }
 
-    public async getVersions(versionId: string | null, count: number, scenarioName?: string): Promise<IVersion[]> {
-        return this.internalStorageService.getVersions(versionId, count, scenarioName);
+    public async getVersions(
+        versionId: string | null,
+        count: number,
+        scenarioName?: string,
+        fetchSource?: FetchSource,
+    ): Promise<IVersion[]> {
+        return this.internalStorageService.getVersions(versionId, count, scenarioName, fetchSource);
     }
 
     public async uploadSummaryWithContext(summary: ISummaryTree, context: ISummaryContext): Promise<string> {

package/src/messageRecognition.ts

@@ -5,14 +5,19 @@
 import { IDocumentMessage, ISequencedDocumentMessage, MessageType } from "@fluidframework/protocol-definitions";
 
 /**
+ * Determines whether or not the message type is one of the following:
  *
- * @param message-message
- * @returns whether or not the message type is one listed below
- * "op"
- * "summarize"
- * "propose"
- * "reject"
- * "noop"
+ * - {@link @fluidframework/protocol-definitions#MessageType.Operation}
+ *
+ * - {@link @fluidframework/protocol-definitions#MessageType.Summarize}
+ *
+ * - {@link @fluidframework/protocol-definitions#MessageType.Propose}
+ *
+ * - {@link @fluidframework/protocol-definitions#MessageType.Reject}
+ *
+ * - {@link @fluidframework/protocol-definitions#MessageType2.Accept}
+ *
+ * - {@link @fluidframework/protocol-definitions#MessageType.NoOp}
  */
 export function isClientMessage(message: ISequencedDocumentMessage | IDocumentMessage): boolean {
     if (isRuntimeMessage(message)) {
@@ -22,6 +27,8 @@ export function isClientMessage(message: ISequencedDocumentMessage | IDocumentMe
         case MessageType.Propose:
         case MessageType.Reject:
         case MessageType.NoOp:
+        case MessageType2.Accept:
+        case MessageType.Summarize:
             return true;
         default:
             return false;
@@ -29,14 +36,12 @@ export function isClientMessage(message: ISequencedDocumentMessage | IDocumentMe
 }
 
 /**
- *
- * @param message-message
- * @returns whether or not the message type is one listed below
- * "op"
- * "summarize"
+ * Tells if message was sent by container runtime
+ * @privateRemarks ADO #1385: To be moved to container-definitions
+ * @returns whether the message is a runtime message
  */
-export function isRuntimeMessage(message: ISequencedDocumentMessage | IDocumentMessage): boolean {
-    return message.type === MessageType.Operation || message.type === MessageType.Summarize;
+export function isRuntimeMessage(message: { type: string; }): boolean {
+    return message.type === MessageType.Operation;
 }
 
 enum RuntimeMessage {
@@ -50,16 +55,23 @@ enum RuntimeMessage {
 }
 
 /**
+ * Determines whether or not the message type is one of the following: (legacy)
+ *
+ * - "component"
+ *
+ * - "attach"
+ *
+ * - "chunkedOp"
  *
- * @param message-message
- * @returns whether or not the message type is one listed below (legacy)
- * "component"
- * "attach"
- * "chunkedOp"
- * "blobAttach"
- * "rejoin"
- * "alias"
- * "op"
+ * - "blobAttach"
+ *
+ * - "rejoin"
+ *
+ * - "alias"
+ *
+ * - "op"
+ *
+ * @deprecated This API should not be used.
  */
 export function isUnpackedRuntimeMessage(message: ISequencedDocumentMessage): boolean {
     if ((Object.values(RuntimeMessage) as string[]).includes(message.type)) {
@@ -67,3 +79,16 @@ export function isUnpackedRuntimeMessage(message: ISequencedDocumentMessage): bo
     }
     return false;
 }
+
+// ADO #1385: staging code changes across layers.
+// Eventually to be replaced by MessageType.accept
+export enum MessageType2 {
+    Accept = "accept",
+}
+
+// ADO #1385: To be moved to packages/protocol-base/src/protocol.ts
+export function canBeCoalescedByService(message: ISequencedDocumentMessage | IDocumentMessage): boolean {
+    // This assumes that in the future relay service may implement coalescing of accept messages,
+    // same way it was doing coalescing of immediate noops in the past.
+    return message.type === MessageType.NoOp || message.type === MessageType2.Accept;
+}

package/src/network.ts

@@ -8,6 +8,8 @@ import {
     IDriverErrorBase,
     IAuthorizationError,
     DriverErrorType,
+    ILocationRedirectionError,
+    IResolvedUrl,
 } from "@fluidframework/driver-definitions";
 import { ITelemetryProperties } from "@fluidframework/common-definitions";
 import { IFluidErrorBase, LoggingError } from "@fluidframework/telemetry-utils";
@@ -59,6 +61,21 @@ export class GenericNetworkError extends LoggingError implements IDriverErrorBas
     }
 }
 
+/**
+ * FluidInvalidSchema error class.
+ */
+ export class FluidInvalidSchemaError extends LoggingError implements IDriverErrorBase, IFluidErrorBase {
+    readonly errorType = DriverErrorType.fluidInvalidSchema;
+    readonly canRetry = false;
+
+    constructor(
+        message: string,
+        props: DriverErrorTelemetryProps,
+    ) {
+        super(message, props);
+    }
+}
+
 // Todo GH #6214: Remove after next drive def bump. This is necessary as there is no
 // compatible way to augment an enum, as it can't be optional. So for now
 // we need to duplicate the value here. We likely need to rethink our
@@ -91,6 +108,20 @@ export class AuthorizationError extends LoggingError implements IAuthorizationEr
     }
 }
 
+export class LocationRedirectionError extends LoggingError implements ILocationRedirectionError, IFluidErrorBase {
+    readonly errorType = DriverErrorType.locationRedirection;
+    readonly canRetry = false;
+
+    constructor(
+        message: string,
+        readonly redirectUrl: IResolvedUrl,
+        props: DriverErrorTelemetryProps,
+    ) {
+        // do not log redirectURL
+        super(message, props, new Set(["redirectUrl"]));
+    }
+}
+
 export class NetworkErrorBasic<T extends string> extends LoggingError implements IFluidErrorBase {
     constructor(
         message: string,

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/driver-utils";
-export const pkgVersion = "1.2.7";
+export const pkgVersion = "2.0.0-dev.1.3.0.96595";

package/src/parallelRequests.ts

@@ -23,7 +23,7 @@ type WorkingState = "working" | "done" | "canceled";
  * data in the right order. Take a look at UT for examples.
  * @param concurrency - level of concurrency
  * @param from - starting point of fetching data (inclusive)
- * @param to  - ending point of fetching data. exclusive, or undefined if unknown
+ * @param to - ending point of fetching data. exclusive, or undefined if unknown
  * @param payloadSize - batch size
  * @param logger - logger to use
  * @param requestCallback - callback to request batches
@@ -354,6 +354,9 @@ export class Queue<T> implements IStream<T> {
  * @param telemetryEvent - telemetry event used to track consecutive batch of requests
  * @param strongTo - tells if ops in range from...to have to be there and have to be retrieved.
  * If false, returning less ops would mean we reached end of file.
+ * @param logger - logger object to use to log progress & errors
+ * @param signal - cancelation signal
+ * @param scenarioName - reason for fetching ops
  * @returns - an object with resulting ops and cancellation / partial result flags
  */
 async function getSingleOpBatch(
@@ -362,7 +365,7 @@ async function getSingleOpBatch(
     strongTo: boolean,
     logger: ITelemetryLogger,
     signal?: AbortSignal,
-    fetchReason?: string):
+    scenarioName?: string):
         Promise<{ partial: boolean; cancel: boolean; payload: ISequencedDocumentMessage[]; }> {
     let lastSuccessTime: number | undefined;
 
@@ -426,7 +429,7 @@ async function getSingleOpBatch(
                     retry,
                     duration: performance.now() - startTime,
                     retryAfter,
-                    fetchReason,
+                    reason: scenarioName,
                 },
                 error);
 
@@ -446,6 +449,18 @@ async function getSingleOpBatch(
     return nothing;
 }
 
+/**
+ * Request ops from storage
+ * @param get - Getter callback to get individual batches
+ * @param concurrency - Number of concurrent requests to make
+ * @param fromTotal - starting sequence number to fetch (inclusive)
+ * @param toTotal - max (exclusive) sequence number to fetch
+ * @param payloadSize - Payload size
+ * @param logger - Logger to log progress and errors
+ * @param signal - Cancelation signal
+ * @param scenarioName - Reason for fetching ops
+ * @returns - Messages fetched
+ */
 export function requestOps(
     get: (from: number, to: number, telemetryProps: ITelemetryProperties) => Promise<IDeltasFetchResult>,
     concurrency: number,
@@ -454,7 +469,7 @@ export function requestOps(
     payloadSize: number,
     logger: ITelemetryLogger,
     signal?: AbortSignal,
-    fetchReason?: string,
+    scenarioName?: string,
 ): IStream<ISequencedDocumentMessage[]> {
     let requests = 0;
     let lastFetch: number | undefined;
@@ -469,7 +484,7 @@ export function requestOps(
     const telemetryEvent = PerformanceEvent.start(logger, {
         eventName: "GetDeltas",
         ...propsTotal,
-        fetchReason,
+        reason: scenarioName,
     });
 
     const manager = new ParallelRequests<ISequencedDocumentMessage>(
@@ -485,7 +500,7 @@ export function requestOps(
                 strongTo,
                 logger,
                 signal,
-                fetchReason,
+                scenarioName,
             );
         },
         (deltas: ISequencedDocumentMessage[]) => {

package/src/readAndParse.ts

@@ -7,11 +7,16 @@ import { bufferToString } from "@fluidframework/common-utils";
 import { IDocumentStorageService } from "@fluidframework/driver-definitions";
 
 /**
- * Read a blob from IDocumentStorageService and JSON.parse it into object of type T
+ * Read a blob from {@link @fluidframework/driver-definitions#IDocumentStorageService} and
+ * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse | JSON.parse}
+ * it into object of type `T`.
  *
- * @param storage - the IDocumentStorageService to read from
- * @param id - the id of the blob to read and parse
- * @returns the object that we decoded and JSON.parse
+ * @param storage - The `DocumentStorageService` to read from.
+ * @param id - The ID of the blob to read and parse.
+ *
+ * @typeParam T - Output type matching JSON format of inpyt blob data.
+ *
+ * @returns The object that we decoded and parsed via `JSON.parse`.
  */
 export async function readAndParse<T>(storage: Pick<IDocumentStorageService, "readBlob">, id: string): Promise<T> {
     const blob = await storage.readBlob(id);

package/src/runWithRetry.ts

@@ -16,14 +16,18 @@ import { NonRetryableError } from ".";
  */
 export interface IProgress {
     /**
-     * Abort signal used to cancel operation
-     * Note that most of the layers do not use this signal yet. We need to change that over time.
+     * Abort signal used to cancel operation.
+     *
+     * @remarks Note that most of the layers do not use this signal yet. We need to change that over time.
      * Please consult with API documentation / implementation.
      * Note that  number of layers may not check this signal while holding this request in a queue,
      * so it may take a while it takes effect. This can be improved in the future.
-     * Layers in question are:
-     *    - driver (RateLimiter)
-     *    - runWithRetry
+     *
+     * The layers in question are:
+     *
+     * - driver (RateLimiter)
+     *
+     * - runWithRetry
      */
     cancel?: AbortSignal;