@fluidframework/merge-tree 2.23.0 → 2.30.0

package/src/perspective.ts

@@ -3,70 +3,87 @@
  * Licensed under the MIT License.
  */
 
-import { UnassignedSequenceNumber } from "./constants.js";
+import { LocalClientId, UnassignedSequenceNumber } from "./constants.js";
 import { type MergeTree } from "./mergeTree.js";
 import { LeafAction, backwardExcursion, forwardExcursion } from "./mergeTreeNodeWalk.js";
 import { seqLTE, type ISegmentLeaf } from "./mergeTreeNodes.js";
-import {
-	isInserted,
-	isMoved,
-	isRemoved,
-	type IInsertionInfo,
-	type IMoveInfo,
-	type IRemovalInfo,
-	type SegmentWithInfo,
-} from "./segmentInfos.js";
+import { isInserted, toMoveInfo, toRemovalInfo } from "./segmentInfos.js";
+import * as opstampUtils from "./stamps.js";
+import type { OperationStamp, InsertOperationStamp, RemoveOperationStamp } from "./stamps.js";
 
 /**
- * Provides a view of a MergeTree from the perspective of a specific client at a specific sequence number.
+ * A perspective which includes some subset of operations known to the local client.
+ *
+ * This helps the local client reason about the state of other clients when they issued an operation.
  */
 export interface Perspective {
-	nextSegment(segment: ISegmentLeaf, forward?: boolean): ISegmentLeaf;
-	previousSegment(segment: ISegmentLeaf): ISegmentLeaf;
-}
+	/**
+	 * The sequence number last seen from this perspective. Same concept as `ISequencedDocumentMessage.referenceSequenceNumber`.
+	 * @privateRemarks
+	 * This currently allows inter-operation between MergeTree methods and the partial lengths implementation, which still depends
+	 * on the (refSeq, clientId, localSeq?) representation of perspectives.
+	 */
+	readonly refSeq: number;
 
-/**
- * Represents a point in time inside the collaboration window.
- */
-export interface SeqTime {
-	refSeq: number;
-	localSeq?: number;
-}
+	/**
+	 * The client id for this perspective.
+	 * @privateRemarks
+	 * This currently allows inter-operation between MergeTree methods and the partial lengths implementation, which still depends
+	 * on the (refSeq, clientId, localSeq?) representation of perspectives.
+	 */
+	readonly clientId: number;
 
-/**
- * Implementation of {@link Perspective}.
- * @privateRemarks
- * TODO:AB#29765: This class does not support non-local-client perspectives, but should.
- */
-export class PerspectiveImpl implements Perspective {
 	/**
-	 * @param _mergeTree - The {@link MergeTree} to view.
-	 * @param _seqTime - The latest sequence number and local sequence number to consider.
+	 * When this is a local perspective, the local sequence number last seen from this perspective.
+	 *
+	 * Perspectives with defined `localSeq` values are useful in reconnection flows, where the local client may need to resend some
+	 * of its ops after rederiving their new equivalents.
+	 * @privateRemarks
+	 * This currently allows inter-operation between MergeTree methods and the partial lengths implementation, which still depends
+	 * on the (refSeq, clientId, localSeq?) representation of perspectives.
 	 */
-	public constructor(
-		private readonly _mergeTree: MergeTree,
-		private readonly _seqTime: SeqTime,
-	) {}
+	readonly localSeq?: number;
+
+	/**
+	 * @returns Whether the segment is present (visible) from this perspective
+	 */
+	isSegmentPresent(segment: ISegmentLeaf): boolean;
+
+	/**
+	 * @returns Whether this perspective has seen the given operation.
+	 */
+	hasOccurred(stamp: RemoveOperationStamp | InsertOperationStamp): boolean;
+
+	nextSegment(mergeTree: MergeTree, segment: ISegmentLeaf, forward?: boolean): ISegmentLeaf;
+	previousSegment(mergeTree: MergeTree, segment: ISegmentLeaf): ISegmentLeaf;
+}
+
+abstract class PerspectiveBase {
+	abstract hasOccurred(stamp: RemoveOperationStamp | InsertOperationStamp): boolean;
 
 	/**
 	 * Returns the immediately adjacent segment in the specified direction from this perspective.
 	 * There may actually be multiple segments between the given segment and the returned segment,
-	 * but they were either inserted after this perspective, or have been removed or moved before this perspective.
+	 * but they were either inserted after this perspective, or have been removed before this perspective.
 	 *
 	 * @param segment - The segment to start from.
 	 * @param forward - The direction to search.
 	 * @returns the next segment in the specified direction, or the start or end of the tree if there is no next segment.
 	 */
-	public nextSegment(segment: ISegmentLeaf, forward: boolean = true): ISegmentLeaf {
+	public nextSegment(
+		mergeTree: MergeTree,
+		segment: ISegmentLeaf,
+		forward: boolean = true,
+	): ISegmentLeaf {
 		let next: ISegmentLeaf | undefined;
 		const action = (seg: ISegmentLeaf): boolean | undefined => {
-			if (isSegmentPresent(seg, this._seqTime)) {
+			if (this.isSegmentPresent(seg)) {
 				next = seg;
 				return LeafAction.Exit;
 			}
 		};
 		(forward ? forwardExcursion : backwardExcursion)(segment, action);
-		return next ?? (forward ? this._mergeTree.endOfTree : this._mergeTree.startOfTree);
+		return next ?? (forward ? mergeTree.endOfTree : mergeTree.startOfTree);
 	}
 
 	/**
@@ -75,99 +92,158 @@ export class PerspectiveImpl implements Perspective {
 	 * @returns the previous segment, or the start of the tree if there is no previous segment.
 	 * @remarks This is a convenient equivalent to calling `nextSegment(segment, false)`.
 	 */
-	public previousSegment(segment: ISegmentLeaf): ISegmentLeaf {
-		return this.nextSegment(segment, false);
+	public previousSegment(mergeTree: MergeTree, segment: ISegmentLeaf): ISegmentLeaf {
+		return this.nextSegment(mergeTree, segment, false);
+	}
+
+	public isSegmentPresent(seg: ISegmentLeaf): boolean {
+		const insert: InsertOperationStamp = {
+			type: "insert",
+			clientId: seg.clientId,
+			seq: seg.seq,
+			localSeq: seg.localSeq,
+		};
+		if (isInserted(seg) && !this.hasOccurred(insert)) {
+			return false;
+		}
+
+		const removes: RemoveOperationStamp[] = [];
+		const removalInfo = toRemovalInfo(seg);
+		if (removalInfo !== undefined) {
+			removes.push(
+				...removalInfo.removedClientIds.map((clientId) =>
+					(clientId === LocalClientId || clientId === 0) &&
+					removalInfo.localRemovedSeq !== undefined
+						? ({
+								type: "setRemove",
+								seq: UnassignedSequenceNumber,
+								clientId,
+								localSeq: removalInfo.localRemovedSeq,
+							} as const)
+						: // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+							({ type: "setRemove", seq: removalInfo.removedSeq, clientId } as const),
+				),
+			);
+		}
+
+		const moveInfo = toMoveInfo(seg);
+		if (moveInfo !== undefined) {
+			removes.push(
+				...moveInfo.movedClientIds.map((clientId, index) =>
+					(clientId === LocalClientId || clientId === 0) &&
+					moveInfo.localMovedSeq !== undefined
+						? ({
+								type: "sliceRemove",
+								seq: UnassignedSequenceNumber,
+								clientId,
+								localSeq: moveInfo.localMovedSeq,
+							} as const)
+						: // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+							({ type: "setRemove", seq: moveInfo.movedSeqs[index]!, clientId } as const),
+				),
+			);
+		}
+
+		if (removes.some((remove) => this.hasOccurred(remove))) {
+			return false;
+		}
+
+		return true;
 	}
 }
 
 /**
- * Determines if the given segment was removed before the given perspective.
- * @param seg - The segment to check.
- * @param seq - The latest sequence number to consider.
- * @param localSeq - The latest local sequence number to consider.
- * @returns true iff this segment was removed in the given perspective.
- * @privateRemarks
- * TODO:AB#29765: This function does not support non-local-client perspectives, but should.
+ * A perspective which includes edits at or before some reference sequence number alongside all edits from some particular client.
+ *
+ * @remarks
+ * This works for both the local client as well as remote clients since refSeq-based checks disallow unacked edits, but the clientId check
+ * catches unacked edits from the local client.
  */
-export function wasRemovedBefore(
-	seg: SegmentWithInfo<IInsertionInfo & IRemovalInfo>,
-	{ refSeq, localSeq }: SeqTime,
-): boolean {
-	if (
-		seg.removedSeq === UnassignedSequenceNumber &&
-		localSeq !== undefined &&
-		seg.localRemovedSeq !== undefined
+export class PriorPerspective extends PerspectiveBase implements Perspective {
+	public constructor(
+		public readonly refSeq: number,
+		public readonly clientId: number,
 	) {
-		return seg.localRemovedSeq <= localSeq;
+		super();
+	}
+
+	public hasOccurred(stamp: OperationStamp): boolean {
+		const predatesViaRefSeq = seqLTE(stamp.seq, this.refSeq);
+		const predatesViaSameClient = stamp.clientId === this.clientId;
+		return predatesViaRefSeq || predatesViaSameClient;
 	}
-	return seg.removedSeq !== undefined && seqLTE(seg.removedSeq, refSeq);
 }
 
 /**
- * Determines if the given segment was moved before the given perspective.
- * @param seg - The segment to check.
- * @param refSeq - The latest sequence number to consider.
- * @param localSeq - The latest local sequence number to consider.
- * @returns true iff this segment was moved (aka obliterated) in the given perspective.
- * @privateRemarks
- * TODO:AB#29765: This function does not support non-local-client perspectives, but should.
+ * A perspective which includes edits which were either:
+ * - acked and at or before some reference sequence number
+ * - unacked, but at or before some local sequence number
+ *
+ * This is a useful perspective when the local client is in the process of reconnecting, since it must
+ * rederive positions for unacked ops while only considering a portion of its own edits as having been applied.
  */
-export function wasMovedBefore(
-	seg: SegmentWithInfo<IInsertionInfo & IMoveInfo>,
-	{ refSeq, localSeq }: SeqTime,
-): boolean {
-	if (
-		seg.movedSeq === UnassignedSequenceNumber &&
-		localSeq !== undefined &&
-		seg.localMovedSeq !== undefined
+export class LocalReconnectingPerspective extends PerspectiveBase implements Perspective {
+	public constructor(
+		public readonly refSeq: number,
+		public readonly clientId: number,
+		public readonly localSeq: number,
 	) {
-		return seg.localMovedSeq <= localSeq;
+		super();
+	}
+
+	public hasOccurred(stamp: OperationStamp): boolean {
+		const predatesViaRefSeq = seqLTE(stamp.seq, this.refSeq);
+		const predatesViaLocalSeq =
+			stamp.localSeq !== undefined && stamp.localSeq <= this.localSeq;
+		return predatesViaRefSeq || predatesViaLocalSeq;
 	}
-	return seg.movedSeq !== undefined && seqLTE(seg.movedSeq, refSeq);
 }
 
 /**
- * See {@link wasRemovedBefore} and {@link wasMovedBefore}.
- * @privateRemarks
- * TODO:AB#29765: This function does not support non-local-client perspectives, but should.
+ * A perspective which includes all known edits.
+ *
+ * This is the perspective that the application sees.
+ * @remarks
+ * This can be represented using {@link PriorPerspective} with a refSeq of `Number.MAX_SAFE_INTEGER`, but having an explicit
+ * variant of this perspective renders extra refSeq checks unnecessary and is a bit easier to read.
  */
-export function wasRemovedOrMovedBefore(seg: ISegmentLeaf, seqTime: SeqTime): boolean {
-	return (
-		isInserted(seg) &&
-		((isRemoved(seg) && wasRemovedBefore(seg, seqTime)) ||
-			(isMoved(seg) && wasMovedBefore(seg, seqTime)))
-	);
+export class LocalDefaultPerspective extends PerspectiveBase implements Perspective {
+	public readonly refSeq = Number.MAX_SAFE_INTEGER;
+
+	public constructor(public readonly clientId: number) {
+		super();
+	}
+
+	public hasOccurred(_stamp: OperationStamp): boolean {
+		return true;
+	}
 }
 
 /**
- * Determines if the given segment is present in the given perspective.
- * @param seg - The segment to check.
- * @param seqTime - The latest sequence number and local sequence number to consider.
- * @returns true iff this segment was inserted before the given perspective,
- * and it was not removed or moved in the given perspective.
- * @privateRemarks
- * TODO:AB#29765: This function does not support non-local-client perspectives, but should.
+ * A perspective dictating whether segments are 'visible' to a remote obliterate operation.
+ *
+ * NOTE: Beware that partial lengths doesn't support this perspective, in the sense that consulting partial lengths' for the length of a block
+ * can give different results than summing the lengths of present segments in that block.
+ * This ends up not affecting the current obliterate implementation (which has some special casing in the mapRange calls it uses),
+ * but use with caution.
  */
-export function isSegmentPresent(seg: ISegmentLeaf, seqTime: SeqTime): boolean {
-	const { refSeq, localSeq } = seqTime;
-	// If seg.seq is undefined, then this segment has existed since minSeq.
-	// It may have been moved or removed since.
-	if (isInserted(seg)) {
-		if (seg.seq !== UnassignedSequenceNumber) {
-			if (!seqLTE(seg.seq, refSeq)) {
-				return false;
-			}
-		} else if (
-			seg.localSeq !== undefined && // seg.seq === UnassignedSequenceNumber
-			// If the current perspective does not include local sequence numbers,
-			// then this segment does not exist yet.
-			(localSeq === undefined || seg.localSeq > localSeq)
-		) {
+export class RemoteObliteratePerspective extends PerspectiveBase implements Perspective {
+	public readonly refSeq = Number.MAX_SAFE_INTEGER;
+
+	constructor(public readonly clientId: number) {
+		super();
+	}
+
+	public hasOccurred(stamp: InsertOperationStamp | RemoveOperationStamp): boolean {
+		// Local-only removals are not visible to an obliterate operation, since this means the local removal was concurrent
+		// to a remote obliterate and we may need to mark the segment appropriately to reflect this overlapping remove.
+		// Every other type of operation is visible: obliterates do not affect segments that have already been removed and acked,
+		// and they always affect segments within their range that have not been removed, even if those segments were inserted
+		// after the obliterate's refSeq.
+		if (stamp.type !== "insert" && opstampUtils.isLocal(stamp)) {
 			return false;
 		}
+
+		return true;
 	}
-	if (wasRemovedOrMovedBefore(seg, seqTime)) {
-		return false;
-	}
-	return true;
 }

package/src/stamps.ts

@@ -0,0 +1,164 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { UnassignedSequenceNumber } from "./constants.js";
+
+/**
+ * A stamp that identifies provenance of an operation performed on the MergeTree.
+ *
+ * Stamps identify a point in time (`seq`/`localSeq`) as well as the source (`clientId`) for the operation.
+ * This provides enough information to linearize all known applied operations: acked operations happen before
+ * local+unacked ones, with acked operations ordered by their sequence numbers and local+unacked operations
+ * ordered by their localSeq.
+ *
+ * By including `clientId`, it also provides enough information to resolve whether segments are visible
+ * from alternative perspectives: a remote client will have seen all of its own previous operations as well as
+ * those at or below the op's reference sequence number.
+ *
+ * @remarks - As the `readonly` identifies suggest, these stamps should be treated as immutable.
+ * New operations applied to a merge-tree should create new stamps rather than modify existing ones (e.g. when
+ * a change's ack happens).
+ * @internal
+ */
+export interface OperationStamp {
+	/**
+	 * The sequence number at which this operation was applied.
+	 */
+	readonly seq: number;
+
+	/**
+	 * Short clientId for the client that performed this operation.
+	 */
+	readonly clientId: number;
+
+	/**
+	 * Local seq at which this operation was applied.
+	 * This is defined if and only if the operation is pending an ack, i.e. `seq` is UnassignedSequenceNumber.
+	 *
+	 * @privateRemarks
+	 * See {@link CollaborationWindow.localSeq} for more information on the semantics of localSeq.
+	 */
+	readonly localSeq?: number;
+}
+
+/**
+ * {@link OperationStamp} for an 'insert' operation.
+ */
+export interface InsertOperationStamp extends OperationStamp {
+	readonly type: "insert";
+}
+
+/**
+ * {@link OperationStamp} for a 'set remove' operation. This aligns with the `markRangeRemoved` API in MergeTree.
+ *
+ * @remarks The terminology here comes from the fact that the removal should affect only the *set* of nodes that were
+ * specified at the time the local client issued the remove, and not any nodes that were inserted concurrently.
+ *
+ * Not using "remove" and "obliterate" here allows us to unambiguously use the term "remove" elsewhere in code to mean
+ * "removed from the tree, either by MergeTree.obliterateRange or MergeTree.removeRange". This is convenient as the vast majority
+ * of merge-tree code only cares about segment visibility and not the specific operation that caused a segment to be removed.
+ */
+export interface SetRemoveOperationStamp extends OperationStamp {
+	readonly type: "setRemove";
+}
+
+/**
+ * {@link OperationStamp} for a 'set remove' operation. This aligns with the `obliterateRange` API in MergeTree.
+ *
+ * @remarks The terminology here comes from the fact that the removal should affect the *slice* of nodes between the
+ * start and end point specified by the local client, which includes any nodes that were inserted concurrently.
+ *
+ * Not using "remove" and "obliterate" here allows us to unambiguously use the term "remove" elsewhere in code to mean
+ * "removed from the tree, either by MergeTree.obliterateRange or MergeTree.removeRange". This is convenient as the vast majority
+ * of merge-tree code only cares about segment visibility and not the specific operation that caused a segment to be removed.
+ */
+export interface SliceRemoveOperationStamp extends OperationStamp {
+	readonly type: "sliceRemove";
+}
+
+export type RemoveOperationStamp = SetRemoveOperationStamp | SliceRemoveOperationStamp;
+
+export function lessThan(a: OperationStamp, b: OperationStamp): boolean {
+	if (a.seq === UnassignedSequenceNumber) {
+		// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+		return b.seq === UnassignedSequenceNumber && a.localSeq! < b.localSeq!;
+	}
+
+	if (b.seq === UnassignedSequenceNumber) {
+		return true;
+	}
+
+	return a.seq < b.seq;
+}
+
+export function gte(a: OperationStamp, b: OperationStamp): boolean {
+	return !lessThan(a, b);
+}
+
+export function greaterThan(a: OperationStamp, b: OperationStamp): boolean {
+	if (a.seq === UnassignedSequenceNumber) {
+		// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+		return b.seq !== UnassignedSequenceNumber || a.localSeq! > b.localSeq!;
+	}
+
+	if (b.seq === UnassignedSequenceNumber) {
+		return false;
+	}
+
+	return a.seq > b.seq;
+}
+
+export function lte(a: OperationStamp, b: OperationStamp): boolean {
+	return !greaterThan(a, b);
+}
+
+export function equal(a: OperationStamp, b: OperationStamp): boolean {
+	return a.seq === b.seq && a.clientId === b.clientId && a.localSeq === b.localSeq;
+}
+
+export function isLocal(a: OperationStamp): boolean {
+	return a.seq === UnassignedSequenceNumber;
+}
+
+export function isAcked(a: OperationStamp): boolean {
+	return a.seq !== UnassignedSequenceNumber;
+}
+
+/**
+ * Inserts a stamp into a sorted list of stamps in the correct (sorted) position.
+ *
+ * Beware that this uses Array.splice, thus requires asymptotics considerations.
+ * If inserting a variable number of timestamp, consider just pushing them and sorting the list
+ * after using {@link compare} instead.
+ */
+export function spliceIntoList(list: OperationStamp[], stamp: OperationStamp): void {
+	if (isLocal(stamp) || list.length === 0) {
+		list.push(stamp);
+	} else {
+		for (let i = list.length - 1; i >= 0; i--) {
+			if (greaterThan(stamp, list[i])) {
+				list.splice(i + 1, 0, stamp);
+				return;
+			}
+		}
+
+		// Less than all stamps in the list: put it at the beginning.
+		list.unshift(stamp);
+	}
+}
+
+export function hasAnyAckedOperation(list: OperationStamp[]): boolean {
+	return list.some((ts) => isAcked(ts));
+}
+
+export function compare(a: OperationStamp, b: OperationStamp): number {
+	if (greaterThan(a, b)) {
+		return 1;
+	} else if (lessThan(a, b)) {
+		return -1;
+	} else {
+		return 0;
+	}
+}