@fluidframework/container-loader 2.0.0-internal.7.3.0 → 2.0.0-internal.7.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluidframework/container-loader",
-  "version": "2.0.0-internal.7.3.0",
+  "version": "2.0.0-internal.7.4.0",
   "description": "Fluid container loader",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -35,15 +35,15 @@
     "temp-directory": "nyc/.nyc_output"
   },
   "dependencies": {
-    "@fluid-internal/client-utils": ">=2.0.0-internal.7.3.0 <2.0.0-internal.7.4.0",
-    "@fluidframework/container-definitions": ">=2.0.0-internal.7.3.0 <2.0.0-internal.7.4.0",
-    "@fluidframework/core-interfaces": ">=2.0.0-internal.7.3.0 <2.0.0-internal.7.4.0",
-    "@fluidframework/core-utils": ">=2.0.0-internal.7.3.0 <2.0.0-internal.7.4.0",
-    "@fluidframework/driver-definitions": ">=2.0.0-internal.7.3.0 <2.0.0-internal.7.4.0",
-    "@fluidframework/driver-utils": ">=2.0.0-internal.7.3.0 <2.0.0-internal.7.4.0",
+    "@fluid-internal/client-utils": ">=2.0.0-internal.7.4.0 <2.0.0-internal.7.5.0",
+    "@fluidframework/container-definitions": ">=2.0.0-internal.7.4.0 <2.0.0-internal.7.5.0",
+    "@fluidframework/core-interfaces": ">=2.0.0-internal.7.4.0 <2.0.0-internal.7.5.0",
+    "@fluidframework/core-utils": ">=2.0.0-internal.7.4.0 <2.0.0-internal.7.5.0",
+    "@fluidframework/driver-definitions": ">=2.0.0-internal.7.4.0 <2.0.0-internal.7.5.0",
+    "@fluidframework/driver-utils": ">=2.0.0-internal.7.4.0 <2.0.0-internal.7.5.0",
     "@fluidframework/protocol-base": "^2.0.1",
     "@fluidframework/protocol-definitions": "^3.0.0",
-    "@fluidframework/telemetry-utils": ">=2.0.0-internal.7.3.0 <2.0.0-internal.7.4.0",
+    "@fluidframework/telemetry-utils": ">=2.0.0-internal.7.4.0 <2.0.0-internal.7.5.0",
     "debug": "^4.3.4",
     "double-ended-queue": "^2.1.0-0",
     "events": "^3.1.0",
@@ -51,21 +51,23 @@
     "uuid": "^9.0.0"
   },
   "devDependencies": {
-    "@fluid-private/test-loader-utils": ">=2.0.0-internal.7.3.0 <2.0.0-internal.7.4.0",
+    "@arethetypeswrong/cli": "^0.13.3",
+    "@fluid-private/test-loader-utils": ">=2.0.0-internal.7.4.0 <2.0.0-internal.7.5.0",
     "@fluid-tools/build-cli": "^0.28.0",
     "@fluidframework/build-common": "^2.0.3",
     "@fluidframework/build-tools": "^0.28.0",
     "@fluidframework/container-loader-previous": "npm:@fluidframework/container-loader@2.0.0-internal.7.2.0",
     "@fluidframework/eslint-config-fluid": "^3.1.0",
-    "@fluidframework/mocha-test-setup": ">=2.0.0-internal.7.3.0 <2.0.0-internal.7.4.0",
+    "@fluidframework/mocha-test-setup": ">=2.0.0-internal.7.4.0 <2.0.0-internal.7.5.0",
     "@microsoft/api-extractor": "^7.38.3",
     "@types/debug": "^4.1.5",
     "@types/double-ended-queue": "^2.1.0",
     "@types/events": "^3.0.0",
     "@types/mocha": "^9.1.1",
-    "@types/node": "^16.18.38",
+    "@types/node": "^18.19.0",
     "@types/sinon": "^7.0.13",
     "c8": "^7.7.1",
+    "copyfiles": "^2.4.1",
     "cross-env": "^7.0.3",
     "eslint": "~8.50.0",
     "mocha": "^10.2.0",
@@ -78,26 +80,43 @@
     "tsc-multi": "^1.1.0",
     "typescript": "~5.1.6"
   },
+  "fluidBuild": {
+    "tasks": {
+      "build:docs": {
+        "dependsOn": [
+          "...",
+          "api-extractor:commonjs",
+          "api-extractor:esnext"
+        ],
+        "script": false
+      }
+    }
+  },
   "typeValidation": {
     "broken": {}
   },
   "scripts": {
+    "api": "fluid-build . --task api",
+    "api-extractor:commonjs": "api-extractor run --local",
+    "api-extractor:esnext": "copyfiles -u 1 \"dist/**/*-@(alpha|beta|public|untrimmed).d.ts\" lib",
     "build": "fluid-build . --task build",
     "build:commonjs": "fluid-build . --task commonjs",
     "build:compile": "fluid-build . --task compile",
-    "build:docs": "api-extractor run --local",
+    "build:docs": "fluid-build . --task api",
     "build:esnext": "tsc-multi --config ../../../common/build/build-common/tsc-multi.esm.json",
     "build:genver": "gen-version",
     "build:test": "tsc-multi --config tsc-multi.test.json",
+    "check:are-the-types-wrong": "attw --pack",
+    "check:release-tags": "api-extractor run --local --config ./api-extractor-lint.json",
     "ci:build:docs": "api-extractor run",
     "clean": "rimraf --glob dist lib \"**/*.tsbuildinfo\" \"**/*.build.log\" _api-extractor-temp nyc",
     "eslint": "eslint --format stylish src",
     "eslint:fix": "eslint --format stylish src --fix --fix-type problem,suggestion,layout",
     "format": "npm run prettier:fix",
-    "lint": "npm run prettier && npm run eslint",
+    "lint": "npm run prettier && npm run check:release-tags && npm run eslint",
     "lint:fix": "npm run prettier:fix && npm run eslint:fix",
-    "prettier": "prettier --check . --ignore-path ../../../.prettierignore",
-    "prettier:fix": "prettier --write . --ignore-path ../../../.prettierignore",
+    "prettier": "prettier --check . --cache --ignore-path ../../../.prettierignore",
+    "prettier:fix": "prettier --write . --cache --ignore-path ../../../.prettierignore",
     "test": "npm run test:mocha",
     "test:coverage": "c8 npm test",
     "test:mocha": "mocha --ignore \"dist/test/types/*\" --recursive dist/test -r node_modules/@fluidframework/mocha-test-setup",

package/src/connectionState.ts

@@ -3,6 +3,9 @@
  * Licensed under the MIT License.
  */
 
+/**
+ * @internal
+ */
 export enum ConnectionState {
 	/**
 	 * The container is not connected to the ordering service

package/src/connectionStateHandler.ts

@@ -312,12 +312,25 @@ class ConnectionStateCatchup extends ConnectionStateHandlerPassThrough {
 class ConnectionStateHandler implements IConnectionStateHandler {
 	private _connectionState = ConnectionState.Disconnected;
 	private _pendingClientId: string | undefined;
+
+	/**
+	 * Tracks that we observe the "leave" op within the timeout for our previous clientId (see comment on ConnectionStateHandler class)
+	 * ! This ensures we do not switch to a new clientId until we process all potential messages from old clientId
+	 * ! i.e. We will always see the "leave" op for a client after we have seen all the ops it has sent
+	 * ! This check helps prevent the same op from being resubmitted by the PendingStateManager upon reconnecting
+	 */
 	private readonly prevClientLeftTimer: Timer;
+
+	/**
+	 * Tracks that we observe our own "join" op within the timeout after receiving a "connected" event from the DeltaManager
+	 */
 	private readonly joinOpTimer: Timer;
+
 	private protocol?: IProtocolHandler;
 	private connection?: IConnectionDetailsInternal;
 	private _clientId?: string;
 
+	/** Track how long we waited to see "leave" op for previous clientId */
 	private waitEvent: PerformanceEvent | undefined;
 
 	public get connectionState(): ConnectionState {
@@ -453,9 +466,9 @@ class ConnectionStateHandler implements IConnectionStateHandler {
 			0x2e2 /* "Must only wait for leave message when clientId in quorum" */,
 		);
 
-		// Move to connected state only if we are in Connecting state, we have seen our join op
-		// and there is no timer running which means we are not waiting for previous client to leave
-		// or timeout has occurred while doing so.
+		// Move to connected state only if:
+		// 1. We have seen our own "join" op (i.e. for this.pendingClientId)
+		// 2. There is no "leave" timer running, meaning this is our first connection or the previous client has left (via this.prevClientLeftTimer)
 		if (
 			this.pendingClientId !== this.clientId &&
 			this.hasMember(this.pendingClientId) &&

package/src/container.ts

@@ -237,6 +237,7 @@ export interface IContainerCreateProps {
  * but it maybe still behind.
  *
  * @throws an error beginning with `"Container closed"` if the container is closed before it catches up.
+ * @internal
  */
 export async function waitContainerToCatchUp(container: IContainer) {
 	// Make sure we stop waiting if container is closed.
@@ -497,6 +498,7 @@ export class Container
 	private readonly subLogger: ITelemetryLoggerExt;
 	private readonly detachedBlobStorage: IDetachedBlobStorage | undefined;
 	private readonly protocolHandlerBuilder: ProtocolHandlerBuilder;
+	private readonly client: IClient;
 
 	private readonly mc: MonitoringContext;
 
@@ -814,6 +816,14 @@ export class Container
 			});
 		};
 
+		this._containerId = uuid();
+
+		this.client = Container.setupClient(
+			this._containerId,
+			this.options,
+			this.clientDetailsOverride,
+		);
+
 		// Create logger for data stores to use
 		const type = this.client.details.type;
 		const interactive = this.client.details.capabilities.interactive;
@@ -821,7 +831,6 @@ export class Container
 			type !== undefined && type !== "" ? `/${type}` : ""
 		}`;
 
-		this._containerId = uuid();
 		// Need to use the property getter for docId because for detached flow we don't have the docId initially.
 		// We assign the id later so property getter is used.
 		this.subLogger = createChildLogger({
@@ -1116,7 +1125,6 @@ export class Container
 		// runtime matches pending ops to successful ones by clientId and client seq num, so we need to close the
 		// container at the same time we get pending state, otherwise this container could reconnect and resubmit with
 		// a new clientId and a future container using stale pending state without the new clientId would resubmit them
-		this.disconnectInternal({ text: "closeAndGetPendingLocalState" }); // TODO https://dev.azure.com/fluidframework/internal/_workitems/edit/5127
 		const pendingState = await this.getPendingLocalStateCore({
 			notifyImminentClosure: true,
 			stopBlobAttachingSignal,
@@ -1996,10 +2004,15 @@ export class Container
 		return pkg as IFluidCodeDetails;
 	}
 
-	private get client(): IClient {
+	private static setupClient(
+		containerId: string,
+		options?: ILoaderOptions,
+		clientDetailsOverride?: IClientDetails,
+	): IClient {
+		const loaderOptionsClient = structuredClone(options?.client);
 		const client: IClient =
-			this.options?.client !== undefined
-				? (this.options.client as IClient)
+			loaderOptionsClient !== undefined
+				? (loaderOptionsClient as IClient)
 				: {
 						details: {
 							capabilities: { interactive: true },
@@ -2010,21 +2023,22 @@ export class Container
 						user: { id: "" },
 				  };
 
-		if (this.clientDetailsOverride !== undefined) {
+		if (clientDetailsOverride !== undefined) {
 			client.details = {
 				...client.details,
-				...this.clientDetailsOverride,
+				...clientDetailsOverride,
 				capabilities: {
 					...client.details.capabilities,
-					...this.clientDetailsOverride.capabilities,
+					...clientDetailsOverride?.capabilities,
 				},
 			};
 		}
 		client.details.environment = [
 			client.details.environment,
 			` loaderVersion:${pkgVersion}`,
-			` containerId:${this._containerId}`,
+			` containerId:${containerId}`,
 		].join(";");
+
 		return client;
 	}
 
@@ -2530,7 +2544,7 @@ export class Container
 
 /**
  * IContainer interface that includes experimental features still under development.
- * @alpha
+ * @internal
  */
 export interface IContainerExperimental extends IContainer {
 	/**
@@ -2538,16 +2552,12 @@ export interface IContainerExperimental extends IContainer {
 	 * submission and potential document corruption. The blob returned MUST be deleted if and when this
 	 * container emits a "connected" event.
 	 * @returns serialized blob that can be passed to Loader.resolve()
-	 * @alpha misuse of this API can result in duplicate op submission and potential document corruption
-	 * {@link https://github.com/microsoft/FluidFramework/blob/main/packages/loader/container-loader/closeAndGetPendingLocalState.md}
 	 */
 	getPendingLocalState?(): Promise<string>;
 
 	/**
 	 * Closes the container and returns serialized local state intended to be
 	 * given to a newly loaded container.
-	 * @alpha
-	 * {@link https://github.com/microsoft/FluidFramework/blob/main/packages/loader/container-loader/closeAndGetPendingLocalState.md}
 	 */
 	closeAndGetPendingLocalState?(stopBlobAttachingSignal?: AbortSignal): Promise<string>;
 }

package/src/deltaManager.ts

@@ -9,6 +9,7 @@ import {
 	IEventProvider,
 	ITelemetryProperties,
 	ITelemetryErrorEvent,
+	type ITelemetryBaseEvent,
 } from "@fluidframework/core-interfaces";
 import {
 	ICriticalContainerError,
@@ -22,12 +23,12 @@ import {
 	DataProcessingError,
 	extractSafePropertiesFromMessage,
 	normalizeError,
-	logIfFalse,
 	safeRaiseEvent,
 	isFluidError,
 	ITelemetryLoggerExt,
 	DataCorruptionError,
 	UsageError,
+	type ITelemetryGenericEventExt,
 } from "@fluidframework/telemetry-utils";
 import {
 	IDocumentDeltaStorageService,
@@ -114,6 +115,29 @@ function isClientMessage(message: ISequencedDocumentMessage | IDocumentMessage):
 	}
 }
 
+/**
+ * Like assert, but logs only if the condition is false, rather than throwing
+ * @param condition - The condition to attest too
+ * @param logger - The logger to log with
+ * @param event - The string or event to log
+ * @returns The outcome of the condition
+ */
+function logIfFalse(
+	condition: boolean,
+	logger: ITelemetryLoggerExt,
+	event: string | ITelemetryGenericEventExt,
+): condition is true {
+	if (condition) {
+		return true;
+	}
+	const newEvent: ITelemetryBaseEvent =
+		typeof event === "string"
+			? { eventName: event, category: "error" }
+			: { category: "error", ...event };
+	logger.send(newEvent);
+	return false;
+}
+
 /**
  * Manages the flow of both inbound and outbound messages. This class ensures that shared objects receive delta
  * messages in order regardless of possible network conditions or timings causing out of order delivery.

package/src/loader.ts

@@ -6,7 +6,6 @@
 import { v4 as uuid } from "uuid";
 import {
 	ITelemetryLoggerExt,
-	IConfigProviderBase,
 	mixinMonitoringContext,
 	MonitoringContext,
 	PerformanceEvent,
@@ -22,6 +21,7 @@ import {
 	IRequest,
 	IRequestHeader,
 	IResponse,
+	IConfigProviderBase,
 } from "@fluidframework/core-interfaces";
 import {
 	IContainer,
@@ -113,6 +113,9 @@ export class RelativeLoader implements ILoader {
 	}
 }
 
+/**
+ * @alpha
+ */
 export interface ILoaderOptions extends ILoaderOptions1 {
 	summarizeProtocolTree?: boolean;
 }
@@ -122,6 +125,7 @@ export interface ILoaderOptions extends ILoaderOptions1 {
  * {@link @fluidframework/container-definitions#IFluidModuleWithDetails}
  * to have all the code loading modules in one package. #8193
  * Encapsulates a module entry point with corresponding code details.
+ * @alpha
  */
 export interface IFluidModuleWithDetails {
 	/** Fluid code module that implements the runtime factory needed to instantiate the container runtime. */
@@ -139,6 +143,7 @@ export interface IFluidModuleWithDetails {
  * to have code loading modules in one package. #8193
  * Fluid code loader resolves a code module matching the document schema, i.e. code details, such as
  * a package name and package version range.
+ * @alpha
  */
 export interface ICodeDetailsLoader extends Partial<IProvideFluidCodeDetailsComparer> {
 	/**
@@ -152,6 +157,7 @@ export interface ICodeDetailsLoader extends Partial<IProvideFluidCodeDetailsComp
 
 /**
  * Services and properties necessary for creating a loader
+ * @alpha
  */
 export interface ILoaderProps {
 	/**
@@ -208,6 +214,7 @@ export interface ILoaderProps {
 
 /**
  * Services and properties used by and exposed by the loader
+ * @alpha
  */
 export interface ILoaderServices {
 	/**
@@ -260,6 +267,7 @@ export interface ILoaderServices {
 /**
  * Subset of IDocumentStorageService which only supports createBlob() and readBlob(). This is used to support
  * blobs in detached containers.
+ * @alpha
  */
 export type IDetachedBlobStorage = Pick<IDocumentStorageService, "createBlob" | "readBlob"> & {
 	size: number;
@@ -274,6 +282,7 @@ export type IDetachedBlobStorage = Pick<IDocumentStorageService, "createBlob" |
  * @param container - a resolved container
  * @returns component on the container
  * @deprecated Will be removed in future major release. Migrate all usage of IFluidRouter to the "entryPoint" pattern. Refer to Removing-IFluidRouter.md
+ * @internal
  */
 export async function requestResolvedObjectFromContainer(
 	container: IContainer,
@@ -298,6 +307,7 @@ export async function requestResolvedObjectFromContainer(
 
 /**
  * Manages Fluid resource loading
+ * @alpha
  */
 export class Loader implements IHostLoader {
 	public readonly services: ILoaderServices;

package/src/location-redirection-utilities/resolveWithLocationRedirection.ts

@@ -15,6 +15,7 @@ import { createChildLogger } from "@fluidframework/telemetry-utils";
  * Checks if the error is location redirection error.
  * @param error - error whose type is to be determined.
  * @returns `true` is the error is location redirection error, otherwise `false`.
+ * @internal
  */
 export function isLocationRedirectionError(error: any): error is ILocationRedirectionError {
 	return (
@@ -31,6 +32,7 @@ export function isLocationRedirectionError(error: any): error is ILocationRedire
  * @param urlResolver - resolver used to resolve the url.
  * @param logger - logger to send events.
  * @returns Response from the API call.
+ * @internal
  */
 export async function resolveWithLocationRedirectionHandling<T>(
 	api: (request: IRequest) => Promise<T>,

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/container-loader";
-export const pkgVersion = "2.0.0-internal.7.3.0";
+export const pkgVersion = "2.0.0-internal.7.4.0";

package/src/protocol.ts

@@ -28,6 +28,7 @@ export enum SignalType {
 
 /**
  * Function to be used for creating a protocol handler.
+ * @alpha
  */
 export type ProtocolHandlerBuilder = (
 	attributes: IDocumentAttributes,
@@ -35,6 +36,9 @@ export type ProtocolHandlerBuilder = (
 	sendProposal: (key: string, value: any) => number,
 ) => IProtocolHandler;
 
+/**
+ * @alpha
+ */
 export interface IProtocolHandler extends IBaseProtocolHandler {
 	readonly audience: IAudienceOwner;
 	processSignal(message: ISignalMessage);

package/src/utils.ts

@@ -27,6 +27,7 @@ export interface ISnapshotTreeWithBlobContents extends ISnapshotTree {
  * Interface to represent the parsed parts of IResolvedUrl.url to help
  * in getting info about different parts of the url.
  * May not be compatible or relevant for any Url Resolver
+ * @internal
  */
 export interface IParsedUrl {
 	/**
@@ -56,6 +57,7 @@ export interface IParsedUrl {
  * with urls of type: protocol://<string>/.../..?<querystring>
  * @param url - This is the IResolvedUrl.url part of the resolved url.
  * @returns The IParsedUrl representing the input URL, or undefined if the format was not supported
+ * @internal
  */
 export function tryParseCompatibleResolvedUrl(url: string): IParsedUrl | undefined {
 	const parsed = parse(url, true);