@fluidframework/sequence 2.0.0-dev.5.3.2.178189 → 2.0.0-dev.6.4.0.191457

package/src/sequence.ts

@@ -2,8 +2,9 @@
  * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
  * Licensed under the MIT License.
  */
-import { Deferred, bufferToString, assert } from "@fluidframework/common-utils";
-import { ChildLogger } from "@fluidframework/telemetry-utils";
+import { assert, Deferred } from "@fluidframework/core-utils";
+import { bufferToString } from "@fluid-internal/client-utils";
+import { LoggingError, createChildLogger } from "@fluidframework/telemetry-utils";
 import { ISequencedDocumentMessage, MessageType } from "@fluidframework/protocol-definitions";
 import {
 	IChannelAttributes,
@@ -13,6 +14,7 @@ import {
 import {
 	Client,
 	createAnnotateRangeOp,
+	// eslint-disable-next-line import/no-deprecated
 	createGroupOp,
 	createInsertOp,
 	createRemoveRangeOp,
@@ -46,15 +48,14 @@ import {
 	ISharedObjectEvents,
 	SummarySerializer,
 } from "@fluidframework/shared-object-base";
-import { IEventThisPlaceHolder } from "@fluidframework/common-definitions";
+import { IEventThisPlaceHolder } from "@fluidframework/core-interfaces";
 import { ISummaryTreeWithStats, ITelemetryContext } from "@fluidframework/runtime-definitions";
-
 import { DefaultMap, IMapOperation } from "./defaultMap";
 import { IMapMessageLocalMetadata, IValueChanged } from "./defaultMapInterfaces";
+import { SequenceInterval } from "./intervals";
 import {
 	IIntervalCollection,
 	IntervalCollection,
-	SequenceInterval,
 	SequenceIntervalCollectionValueType,
 } from "./intervalCollection";
 import { SequenceDeltaEvent, SequenceMaintenanceEvent } from "./sequenceDeltaEvent";
@@ -119,6 +120,21 @@ export abstract class SharedSegmentSequence<T extends ISegment>
 		return this.loadedDeferred.promise;
 	}
 
+	/**
+	 * This is a safeguard to avoid problematic reentrancy of local ops. This type of scenario occurs if the user of SharedString subscribes
+	 * to the `sequenceDelta` event and uses the callback for a local op to submit further local ops.
+	 * Historically (before 2.0.0-internal.6.1.0), doing so would result in eventual consistency issues or a corrupted document.
+	 * These issues were fixed in #16815 which makes such reentrancy no different from applying the ops in order but not from within the change events,
+	 * but there is still little test coverage for reentrant scenarios.
+	 * Additionally, applications submitting ops from inside change events need to take extreme care that their data models also support reentrancy.
+	 * Since this is likely not the case, by default SharedString throws when encountering reentrant ops.
+	 *
+	 * An application using SharedString which explicitly wants to opt in to allowing reentrancy anyway can set `sharedStringPreventReentrancy`
+	 * on the data store options to `false`.
+	 * @internal
+	 */
+	protected guardReentrancy: <TRet>(callback: () => TRet) => TRet;
+
 	private static createOpsFromDelta(event: SequenceDeltaEvent): IMergeTreeDeltaOp[] {
 		const ops: IMergeTreeDeltaOp[] = [];
 		for (const r of event.ranges) {
@@ -194,22 +210,38 @@ export abstract class SharedSegmentSequence<T extends ISegment>
 	) {
 		super(id, dataStoreRuntime, attributes, "fluid_sequence_");
 
+		this.guardReentrancy =
+			dataStoreRuntime.options.sharedStringPreventReentrancy ?? true
+				? ensureNoReentrancy
+				: createReentrancyDetector((depth) => {
+						if (totalReentrancyLogs > 0) {
+							totalReentrancyLogs--;
+							this.logger.sendTelemetryEvent(
+								{ eventName: "LocalOpReentry", depth },
+								new LoggingError(reentrancyErrorMessage),
+							);
+						}
+				  });
+
 		this.loadedDeferred.promise.catch((error) => {
 			this.logger.sendErrorEvent({ eventName: "SequenceLoadFailed" }, error);
 		});
 
 		this.client = new Client(
 			segmentFromSpec,
-			ChildLogger.create(this.logger, "SharedSegmentSequence.MergeTreeClient"),
+			createChildLogger({
+				logger: this.logger,
+				namespace: "SharedSegmentSequence.MergeTreeClient",
+			}),
 			dataStoreRuntime.options,
 		);
 
-		this.client.on("delta", (opArgs, deltaArgs) => {
-			this.emit(
-				"sequenceDelta",
-				new SequenceDeltaEvent(opArgs, deltaArgs, this.client),
-				this,
-			);
+		this.client.prependListener("delta", (opArgs, deltaArgs) => {
+			const event = new SequenceDeltaEvent(opArgs, deltaArgs, this.client);
+			if (opArgs.stashed !== true && event.isLocal) {
+				this.submitSequenceMessage(opArgs.op);
+			}
+			this.emit("sequenceDelta", event, this);
 		});
 
 		this.client.on("maintenance", (args, opArgs) => {
@@ -230,14 +262,14 @@ export abstract class SharedSegmentSequence<T extends ISegment>
 	 * @param end - The exclusive end of the range to remove
 	 */
 	public removeRange(start: number, end: number): IMergeTreeRemoveMsg {
-		const removeOp = this.client.removeRangeLocal(start, end);
-		this.submitSequenceMessage(removeOp);
-		return removeOp;
+		return this.guardReentrancy(() => this.client.removeRangeLocal(start, end));
 	}
 
+	/**
+	 * @deprecated - The ability to create group ops will be removed in an upcoming release, as group ops are redundant with the native batching capabilities of the runtime
+	 */
 	public groupOperation(groupOp: IMergeTreeGroupMsg) {
-		this.client.localTransaction(groupOp);
-		this.submitSequenceMessage(groupOp);
+		this.guardReentrancy(() => this.client.localTransaction(groupOp));
 	}
 
 	/**
@@ -283,10 +315,7 @@ export abstract class SharedSegmentSequence<T extends ISegment>
 		props: PropertySet,
 		combiningOp?: ICombiningOp,
 	) {
-		const annotateOp = this.client.annotateRangeLocal(start, end, props, combiningOp);
-		if (annotateOp) {
-			this.submitSequenceMessage(annotateOp);
-		}
+		this.guardReentrancy(() => this.client.annotateRangeLocal(start, end, props, combiningOp));
 	}
 
 	public getPropertiesAtPosition(pos: number) {
@@ -361,6 +390,9 @@ export abstract class SharedSegmentSequence<T extends ISegment>
 		);
 	}
 
+	/**
+	 * @deprecated - This method will no longer be public in an upcoming release as it is not safe to use outside of this class
+	 */
 	public submitSequenceMessage(message: IMergeTreeOp) {
 		if (!this.isAttached()) {
 			return;
@@ -412,12 +444,15 @@ export abstract class SharedSegmentSequence<T extends ISegment>
 		this.client.walkSegments(handler, start, end, accum as TClientData, splitRange);
 	}
 
+	/**
+	 * @deprecated - this functionality is no longer supported and will be removed
+	 */
 	public getStackContext(startPos: number, rangeLabels: string[]): RangeStackMap {
 		return this.client.getStackContext(startPos, rangeLabels);
 	}
 
 	/**
-	 * @returns - The most recent sequence number which has been acked by the server and processed by this
+	 * @returns The most recent sequence number which has been acked by the server and processed by this
 	 * SharedSegmentSequence.
 	 */
 	public getCurrentSeq() {
@@ -430,10 +465,7 @@ export abstract class SharedSegmentSequence<T extends ISegment>
 	 * @param segment - The segment to insert
 	 */
 	public insertAtReferencePosition(pos: ReferencePosition, segment: T) {
-		const insertOp = this.client.insertAtReferencePositionLocal(pos, segment);
-		if (insertOp) {
-			this.submitSequenceMessage(insertOp);
-		}
+		this.guardReentrancy(() => this.client.insertAtReferencePositionLocal(pos, segment));
 	}
 	/**
 	 * Inserts a segment
@@ -442,10 +474,7 @@ export abstract class SharedSegmentSequence<T extends ISegment>
 	 */
 	public insertFromSpec(pos: number, spec: IJSONSegment) {
 		const segment = this.segmentFromSpec(spec);
-		const insertOp = this.client.insertSegmentLocal(pos, segment);
-		if (insertOp) {
-			this.submitSequenceMessage(insertOp);
-		}
+		this.guardReentrancy(() => this.client.insertSegmentLocal(pos, segment));
 	}
 
 	/**
@@ -460,6 +489,7 @@ export abstract class SharedSegmentSequence<T extends ISegment>
 	 * @returns An iterable object that enumerates the IntervalCollection labels.
 	 *
 	 * @example
+	 *
 	 * ```typescript
 	 * const iter = this.getIntervalCollectionKeys();
 	 * for (key of iter)
@@ -520,11 +550,7 @@ export abstract class SharedSegmentSequence<T extends ISegment>
 		const insert = this.client.insertSegmentLocal(insertIndex, segment);
 		if (insert) {
 			if (start < end) {
-				const remove = this.client.removeRangeLocal(start, end);
-				const op = remove ? createGroupOp(insert, remove) : insert;
-				this.submitSequenceMessage(op);
-			} else {
-				this.submitSequenceMessage(insert);
+				this.client.removeRangeLocal(start, end);
 			}
 		}
 	}
@@ -729,6 +755,7 @@ export abstract class SharedSegmentSequence<T extends ISegment>
 				stashMessage = {
 					...message,
 					referenceSequenceNumber: stashMessage.sequenceNumber - 1,
+					// eslint-disable-next-line import/no-deprecated
 					contents: ops.length !== 1 ? createGroupOp(...ops) : ops[0],
 				};
 			}
@@ -810,3 +837,41 @@ export abstract class SharedSegmentSequence<T extends ISegment>
 		}
 	}
 }
+
+function createReentrancyDetector(
+	onReentrancy: (depth: number) => void,
+): <T>(callback: () => T) => T {
+	let depth = 0;
+	function detectReentrancy<T>(callback: () => T): T {
+		if (depth > 0) {
+			onReentrancy(depth);
+		}
+		depth++;
+		try {
+			return callback();
+		} finally {
+			depth--;
+		}
+	}
+
+	return detectReentrancy;
+}
+
+/**
+ * Apps which generate reentrant behavior may do so at a high frequency.
+ * Logging even per-SharedSegmentSequence instance might be too noisy, and having a few logs from a session
+ * is likely enough.
+ */
+let totalReentrancyLogs = 3;
+
+/**
+ * Resets the reentrancy log counter. Test-only API.
+ */
+export function resetReentrancyLogCounter() {
+	totalReentrancyLogs = 3;
+}
+
+const reentrancyErrorMessage = "Reentrancy detected in sequence local ops";
+const ensureNoReentrancy = createReentrancyDetector(() => {
+	throw new LoggingError(reentrancyErrorMessage);
+});

package/src/sequenceDeltaEvent.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/common-utils";
+import { assert } from "@fluidframework/core-utils";
 import {
 	Client,
 	IMergeTreeDeltaCallbackArgs,
@@ -147,25 +147,33 @@ export interface ISequenceDeltaRange<
 > {
 	/**
 	 * The type of operation that changed this range.
-	 * @remarks - Consuming code should typically compare this to the enum values defined in
+	 *
+	 * @remarks Consuming code should typically compare this to the enum values defined in
 	 * `MergeTreeDeltaOperationTypes`.
 	 */
 	operation: TOperation;
+
 	/**
 	 * The index of the start of the range.
 	 */
 	position: number;
+
 	/**
 	 * The segment that corresponds to the range.
 	 */
 	segment: ISegment;
+
 	/**
 	 * Deltas object which contains all modified properties with their previous values.
 	 * Since `undefined` doesn't survive a round-trip through JSON serialization, the old value being absent
 	 * is instead encoded with `null`.
-	 * @remarks - This object is motivated by undo/redo scenarios, and provides a convenient "inverse op" to apply to
+	 *
+	 * @remarks This object is motivated by undo/redo scenarios, and provides a convenient "inverse op" to apply to
 	 * undo a property change.
-	 * @example - If a segment initially had properties `{ foo: "1", bar: 2 }` and it was annotated with
+	 *
+	 * @example
+	 *
+	 * If a segment initially had properties `{ foo: "1", bar: 2 }` and it was annotated with
 	 * `{ foo: 3, baz: 5 }`, the corresponding event would have a `propertyDeltas` of `{ foo: "1", baz: null }`.
 	 */
 	propertyDeltas: PropertySet;

package/src/sharedIntervalCollection.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { bufferToString } from "@fluidframework/common-utils";
+import { bufferToString } from "@fluid-internal/client-utils";
 import {
 	IChannelAttributes,
 	IFluidDataStoreRuntime,
@@ -18,12 +18,11 @@ import {
 	IFluidSerializer,
 	SharedObject,
 } from "@fluidframework/shared-object-base";
+import { Interval, ISerializableInterval } from "./intervals";
 import {
-	Interval,
 	IntervalCollection,
 	IIntervalCollection,
 	IntervalCollectionValueType,
-	ISerializableInterval,
 } from "./intervalCollection";
 import { DefaultMap, IMapOperation } from "./defaultMap";
 import { pkgVersion } from "./packageVersion";

package/src/sharedSequence.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { assert } from "@fluidframework/common-utils";
+import { assert } from "@fluidframework/core-utils";
 import { BaseSegment, IJSONSegment, ISegment, PropertySet } from "@fluidframework/merge-tree";
 import {
 	IChannelAttributes,
@@ -14,10 +14,16 @@ import { SharedSegmentSequence } from "./sequence";
 
 const MaxRun = 128;
 
+/**
+ * @deprecated - IJSONRunSegment will be removed in a upcoming release. It has been moved to the fluid-experimental/sequence-deprecated package
+ */
 export interface IJSONRunSegment<T> extends IJSONSegment {
 	items: Serializable<T>[];
 }
 
+/**
+ * @deprecated - SubSequence will be removed in a upcoming release. It has been moved to the fluid-experimental/sequence-deprecated package
+ */
 export class SubSequence<T> extends BaseSegment {
 	public static readonly typeString: string = "SubSequence";
 	public static is(segment: ISegment): segment is SubSequence<any> {
@@ -98,6 +104,9 @@ export class SubSequence<T> extends BaseSegment {
 	}
 }
 
+/**
+ * @deprecated - SharedSequence will be removed in a upcoming release. It has been moved to the fluid-experimental/sequence-deprecated package
+ */
 export class SharedSequence<T> extends SharedSegmentSequence<SubSequence<T>> {
 	constructor(
 		document: IFluidDataStoreRuntime,
@@ -118,10 +127,7 @@ export class SharedSequence<T> extends SharedSegmentSequence<SubSequence<T>> {
 		if (props) {
 			segment.addProperties(props);
 		}
-		const insertOp = this.client.insertSegmentLocal(pos, segment);
-		if (insertOp) {
-			this.submitSequenceMessage(insertOp);
-		}
+		this.client.insertSegmentLocal(pos, segment);
 	}
 
 	/**

package/src/sharedString.ts

@@ -118,10 +118,7 @@ export class SharedString
 		}
 
 		const pos = this.posFromRelativePos(relativePos1);
-		const insertOp = this.client.insertSegmentLocal(pos, segment);
-		if (insertOp) {
-			this.submitSequenceMessage(insertOp);
-		}
+		this.guardReentrancy(() => this.client.insertSegmentLocal(pos, segment));
 	}
 
 	/**
@@ -137,11 +134,7 @@ export class SharedString
 			segment.addProperties(props);
 		}
 
-		const insertOp = this.client.insertSegmentLocal(pos, segment);
-		if (insertOp) {
-			this.submitSequenceMessage(insertOp);
-		}
-		return insertOp;
+		return this.guardReentrancy(() => this.client.insertSegmentLocal(pos, segment));
 	}
 
 	/**
@@ -157,10 +150,7 @@ export class SharedString
 		}
 
 		const pos = this.posFromRelativePos(relativePos1);
-		const insertOp = this.client.insertSegmentLocal(pos, segment);
-		if (insertOp) {
-			this.submitSequenceMessage(insertOp);
-		}
+		this.guardReentrancy(() => this.client.insertSegmentLocal(pos, segment));
 	}
 
 	/**
@@ -172,10 +162,7 @@ export class SharedString
 			segment.addProperties(props);
 		}
 
-		const insertOp = this.client.insertSegmentLocal(pos, segment);
-		if (insertOp) {
-			this.submitSequenceMessage(insertOp);
-		}
+		this.guardReentrancy(() => this.client.insertSegmentLocal(pos, segment));
 	}
 
 	/**
@@ -210,10 +197,9 @@ export class SharedString
 		props: PropertySet,
 		callback: (m: Marker) => void,
 	) {
-		const annotateOp = this.client.annotateMarkerNotifyConsensus(marker, props, callback);
-		if (annotateOp) {
-			this.submitSequenceMessage(annotateOp);
-		}
+		this.guardReentrancy(() =>
+			this.client.annotateMarkerNotifyConsensus(marker, props, callback),
+		);
 	}
 
 	/**
@@ -223,10 +209,7 @@ export class SharedString
 	 * @param combiningOp - Optional. Specifies how to combine values for the property, such as "incr" for increment.
 	 */
 	public annotateMarker(marker: Marker, props: PropertySet, combiningOp?: ICombiningOp) {
-		const annotateOp = this.client.annotateMarker(marker, props, combiningOp);
-		if (annotateOp) {
-			this.submitSequenceMessage(annotateOp);
-		}
+		this.guardReentrancy(() => this.client.annotateMarker(marker, props, combiningOp));
 	}
 
 	/**