@fluidframework/tree 2.61.0 → 2.62.0

package/src/shared-tree/treeCheckout.ts

@@ -11,7 +11,7 @@ import {
 	UsageError,
 	type ITelemetryLoggerExt,
 } from "@fluidframework/telemetry-utils/internal";
-import { FluidClientVersion, noopValidator } from "../codec/index.js";
+import { FluidClientVersion, FormatValidatorNoOp } from "../codec/index.js";
 import {
 	type Anchor,
 	type AnchorLocator,
@@ -47,6 +47,7 @@ import {
 	type TreeNodeSchemaIdentifier,
 	type TreeNodeStoredSchema,
 	LeafNodeStoredSchema,
+	diffHistories,
 } from "../core/index.js";
 import {
 	type FieldBatchCodec,
@@ -296,7 +297,7 @@ export function createTreeCheckout(
 	const schema = args?.schema ?? new TreeStoredSchemaRepository();
 	const forest = args?.forest ?? buildForest(breaker, schema);
 	const defaultCodecOptions = {
-		jsonValidator: noopValidator,
+		jsonValidator: FormatValidatorNoOp,
 		oldestCompatibleClient: FluidClientVersion.v2_0,
 	};
 	const defaultFieldBatchVersion = 1;
@@ -310,6 +311,9 @@ export function createTreeCheckout(
 			args?.chunkCompressionStrategy,
 			idCompressor,
 		);
+
+	// TODO: If a branch is passed in, is it supposed to be local main?
+	// Otherwise shouldn't we set `isSharedBranch` to false?
 	const branch =
 		args?.branch ??
 		new SharedTreeBranch(
@@ -323,7 +327,7 @@ export function createTreeCheckout(
 
 	return new TreeCheckout(
 		branch,
-		false,
+		true,
 		changeFamily,
 		schema,
 		forest,
@@ -366,7 +370,7 @@ export interface RevertMetrics {
 export class TreeCheckout implements ITreeCheckoutFork {
 	public disposed = false;
 
-	private readonly editLock: EditLock;
+	private editLock: EditLock;
 
 	private readonly views = new Set<TreeView<ImplicitFieldSchema>>();
 
@@ -396,15 +400,15 @@ export class TreeCheckout implements ITreeCheckoutFork {
 
 	public constructor(
 		branch: SharedTreeBranch<SharedTreeEditBuilder, SharedTreeChange>,
-		/** True if and only if this checkout is for a forked branch and not the "main branch" of the tree. */
-		public readonly isBranch: boolean,
+		/** True if and only if this checkout is for a branch which is persisted and shared with other clients. */
+		public readonly isSharedBranch: boolean,
 		private readonly changeFamily: ChangeFamily<SharedTreeEditBuilder, SharedTreeChange>,
 		public readonly storedSchema: TreeStoredSchemaRepository,
 		public readonly forest: IEditableForest,
 		private readonly mintRevisionTag: () => RevisionTag,
 		private readonly revisionTagCodec: RevisionTagCodec,
 		private readonly idCompressor: IIdCompressor,
-		private removedRoots: DetachedFieldIndex = makeDetachedFieldIndex(
+		public removedRoots: DetachedFieldIndex = makeDetachedFieldIndex(
 			"repair",
 			revisionTagCodec,
 			idCompressor,
@@ -412,9 +416,29 @@ export class TreeCheckout implements ITreeCheckoutFork {
 		/** Optional logger for telemetry. */
 		private readonly logger?: ITelemetryLoggerExt,
 		public readonly breaker: Breakable = new Breakable("TreeCheckout"),
-		private readonly disposeForksAfterTransaction = true,
+		public readonly disposeForksAfterTransaction = true,
 	) {
-		this.#transaction = new SquashingTransactionStack(
+		this.#transaction = this.createTransactionStack(branch);
+		this.editLock = new EditLock(this.#transaction.activeBranchEditor);
+		this.registerForBranchEvents();
+	}
+
+	private registerForBranchEvents(): void {
+		this.#transaction.branch.events.on("afterChange", this.onAfterBranchChange);
+		this.#transaction.activeBranchEvents.on("afterChange", this.onAfterChange);
+		this.#transaction.activeBranchEvents.on("ancestryTrimmed", this.onAncestryTrimmed);
+	}
+
+	private unregisterFromBranchEvents(): void {
+		this.#transaction.branch.events.off("afterChange", this.onAfterBranchChange);
+		this.#transaction.activeBranchEvents.off("afterChange", this.onAfterChange);
+		this.#transaction.activeBranchEvents.off("ancestryTrimmed", this.onAncestryTrimmed);
+	}
+
+	private createTransactionStack(
+		branch: SharedTreeBranch<SharedTreeEditBuilder, SharedTreeChange>,
+	): SquashingTransactionStack<SharedTreeEditBuilder, SharedTreeChange> {
+		return new SquashingTransactionStack(
 			branch,
 			(commits) => {
 				const revision = this.mintRevisionTag();
@@ -450,58 +474,6 @@ export class TreeCheckout implements ITreeCheckoutFork {
 				};
 			},
 		);
-
-		this.editLock = new EditLock(this.#transaction.activeBranchEditor);
-
-		branch.events.on("afterChange", (event) => {
-			// The following logic allows revertibles to be generated for the change.
-			// Currently only appends (including merges and transaction commits) are supported.
-			if (event.type === "append") {
-				// TODO:#20949: When the SharedTree is detached, these commits will already have been garbage collected.
-				//       Figure out a way to generate revertibles before the commits are garbage collected.
-				for (const commit of event.newCommits) {
-					const kind = event.type === "append" ? event.kind : CommitKind.Default;
-					const { change, revision } = commit;
-
-					const getRevertible = hasSchemaChange(change)
-						? undefined
-						: (onRevertibleDisposed?: (revertible: RevertibleAlpha) => void) => {
-								if (!withinEventContext) {
-									throw new UsageError(
-										"Cannot get a revertible outside of the context of a changed event.",
-									);
-								}
-								if (this.revertibleCommitBranches.get(revision) !== undefined) {
-									throw new UsageError(
-										"Cannot generate the same revertible more than once. Note that this can happen when multiple changed event listeners are registered.",
-									);
-								}
-								const revertible = this.createRevertible(
-									revision,
-									kind,
-									this,
-									onRevertibleDisposed,
-								);
-								this.revertibleCommitBranches.set(
-									revision,
-									this.#transaction.activeBranch.fork(commit),
-								);
-								this.revertibles.add(revertible);
-								return revertible;
-							};
-
-					let withinEventContext = true;
-					this.#events.emit("changed", { isLocal: true, kind }, getRevertible);
-					withinEventContext = false;
-				}
-			} else if (this.isRemoteChangeEvent(event)) {
-				// TODO: figure out how to plumb through commit kind info for remote changes
-				this.#events.emit("changed", { isLocal: false, kind: CommitKind.Default });
-			}
-		});
-
-		this.#transaction.activeBranchEvents.on("afterChange", this.onAfterChange);
-		this.#transaction.activeBranchEvents.on("ancestryTrimmed", this.onAncestryTrimmed);
 	}
 
 	public exportVerbose(): VerboseTree | undefined {
@@ -522,6 +494,55 @@ export class TreeCheckout implements ITreeCheckoutFork {
 		}
 	}
 
+	private readonly onAfterBranchChange = (
+		event: SharedTreeBranchChange<SharedTreeChange>,
+	): void => {
+		// The following logic allows revertibles to be generated for the change.
+		// Currently only appends (including merges and transaction commits) are supported.
+		if (event.type === "append") {
+			// TODO:#20949: When the SharedTree is detached, these commits will already have been garbage collected.
+			//       Figure out a way to generate revertibles before the commits are garbage collected.
+			for (const commit of event.newCommits) {
+				const kind = event.type === "append" ? event.kind : CommitKind.Default;
+				const { change, revision } = commit;
+
+				const getRevertible = hasSchemaChange(change)
+					? undefined
+					: (onRevertibleDisposed?: (revertible: RevertibleAlpha) => void) => {
+							if (!withinEventContext) {
+								throw new UsageError(
+									"Cannot get a revertible outside of the context of a changed event.",
+								);
+							}
+							if (this.revertibleCommitBranches.get(revision) !== undefined) {
+								throw new UsageError(
+									"Cannot generate the same revertible more than once. Note that this can happen when multiple changed event listeners are registered.",
+								);
+							}
+							const revertible = this.createRevertible(
+								revision,
+								kind,
+								this,
+								onRevertibleDisposed,
+							);
+							this.revertibleCommitBranches.set(
+								revision,
+								this.#transaction.activeBranch.fork(commit),
+							);
+							this.revertibles.add(revertible);
+							return revertible;
+						};
+
+				let withinEventContext = true;
+				this.#events.emit("changed", { isLocal: true, kind }, getRevertible);
+				withinEventContext = false;
+			}
+		} else if (this.isRemoteChangeEvent(event)) {
+			// TODO: figure out how to plumb through commit kind info for remote changes
+			this.#events.emit("changed", { isLocal: false, kind: CommitKind.Default });
+		}
+	};
+
 	private readonly onAfterChange = (event: SharedTreeBranchChange<SharedTreeChange>): void => {
 		this.editLock.lock();
 		this.#events.emit("beforeBatch", event);
@@ -531,34 +552,7 @@ export class TreeCheckout implements ITreeCheckoutFork {
 					? this.#transaction.activeBranch.getHead().revision
 					: event.change.revision;
 
-			// Conflicts due to schema will be empty and thus are not applied.
-			for (const change of event.change.change.changes) {
-				if (change.type === "data") {
-					const delta = intoDelta(tagChange(change.innerChange, revision));
-					this.withCombinedVisitor((visitor) => {
-						visitDelta(delta, visitor, this.removedRoots, revision);
-					});
-				} else if (change.type === "schema") {
-					// Schema changes from a current to a new schema are expected to be backwards compatible.
-					// This guarantees that all data in the forest (which is valid before the schema change)
-					// is also valid under the new schema.
-					// Note however, that such schema changes may in some cases be rolled back:
-					// Case 1: A transaction with a schema change may be aborted.
-					// The transaction may have made some data changes that would render some trees invalid
-					// under the old schema, but these changes will also be rolled back, thereby putting the forest
-					// back in the state before the transaction, which is valid under the original (reinstated) schema.
-					// Case 2: A branch with a schema change may be rebased such that the schema change (because
-					// of a constraint) is no longer applied.
-					// Such a branch may contain data changes that would render some trees invalid under the
-					// original schema. These data changes may not necessarily be rolled back.
-					// They will however be rebased over the rollback of the schema change. This rebasing will
-					// ensure that these data changes are muted if they would render some trees invalid under the
-					// original (reinstated) schema.
-					this.storedSchema.apply(change.innerChange.schema.new);
-				} else {
-					fail(0xad1 /* Unknown Shared Tree change type. */);
-				}
-			}
+			this.applyChange(event.change.change, revision);
 		}
 		this.#events.emit("afterBatch");
 		this.editLock.unlock();
@@ -567,6 +561,38 @@ export class TreeCheckout implements ITreeCheckoutFork {
 		}
 	};
 
+	// Revision is the revision of the commit, if any, which caused this change.
+	private applyChange(change: SharedTreeChange, revision?: RevisionTag): void {
+		// Conflicts due to schema will be empty and thus are not applied.
+		for (const innerChange of change.changes) {
+			if (innerChange.type === "data") {
+				const delta = intoDelta(tagChange(innerChange.innerChange, revision));
+				this.withCombinedVisitor((visitor) => {
+					visitDelta(delta, visitor, this.removedRoots, revision);
+				});
+			} else if (innerChange.type === "schema") {
+				// Schema changes from a current to a new schema are expected to be backwards compatible.
+				// This guarantees that all data in the forest (which is valid before the schema change)
+				// is also valid under the new schema.
+				// Note however, that such schema changes may in some cases be rolled back:
+				// Case 1: A transaction with a schema change may be aborted.
+				// The transaction may have made some data changes that would render some trees invalid
+				// under the old schema, but these changes will also be rolled back, thereby putting the forest
+				// back in the state before the transaction, which is valid under the original (reinstated) schema.
+				// Case 2: A branch with a schema change may be rebased such that the schema change (because
+				// of a constraint) is no longer applied.
+				// Such a branch may contain data changes that would render some trees invalid under the
+				// original schema. These data changes may not necessarily be rolled back.
+				// They will however be rebased over the rollback of the schema change. This rebasing will
+				// ensure that these data changes are muted if they would render some trees invalid under the
+				// original (reinstated) schema.
+				this.storedSchema.apply(innerChange.innerChange.schema.new);
+			} else {
+				fail(0xad1 /* Unknown Shared Tree change type. */);
+			}
+		}
+	}
+
 	private readonly onAncestryTrimmed = (revisions: RevisionTag[]): void => {
 		// When the branch is trimmed, we can garbage collect any repair data whose latest relevant revision is one of the
 		// trimmed revisions.
@@ -730,7 +756,7 @@ export class TreeCheckout implements ITreeCheckoutFork {
 	 * To avoid updating observers of the view state with intermediate results during a transaction,
 	 * use {@link ITreeCheckout#branch} and {@link ISharedTreeFork#merge}.
 	 */
-	readonly #transaction: SquashingTransactionStack<SharedTreeEditBuilder, SharedTreeChange>;
+	#transaction: SquashingTransactionStack<SharedTreeEditBuilder, SharedTreeChange>;
 
 	public branch(): TreeCheckout {
 		this.checkNotDisposed(
@@ -743,7 +769,7 @@ export class TreeCheckout implements ITreeCheckoutFork {
 		const forest = this.forest.clone(storedSchema, anchors);
 		const checkout = new TreeCheckout(
 			branch,
-			true,
+			false,
 			this.changeFamily,
 			storedSchema,
 			forest,
@@ -759,6 +785,32 @@ export class TreeCheckout implements ITreeCheckoutFork {
 		return checkout;
 	}
 
+	public switchBranch(
+		branch: SharedTreeBranch<SharedTreeEditBuilder, SharedTreeChange>,
+	): void {
+		// TODO: Dispose old branch, if necessary
+		assert(
+			!this.#transaction.isInProgress(),
+			0xc55 /* Cannot switch branches during a transaction */,
+		);
+		const diff = diffHistories(
+			this.changeFamily.rebaser,
+			this.#transaction.branch.getHead(),
+			branch.getHead(),
+			this.mintRevisionTag,
+		);
+
+		this.unregisterFromBranchEvents();
+
+		this.#transaction = this.createTransactionStack(branch);
+		this.editLock = new EditLock(this.#transaction.activeBranchEditor);
+		this.registerForBranchEvents();
+
+		// TODO: Rework eventing
+		this.applyChange(diff);
+		this.#events.emit("afterBatch");
+	}
+
 	public rebase(checkout: TreeCheckout): void {
 		this.checkNotDisposed(
 			"The target of the branch rebase has been disposed and cannot be rebased.",
@@ -772,8 +824,8 @@ export class TreeCheckout implements ITreeCheckoutFork {
 			0x9af /* A view cannot be rebased while it has a pending transaction */,
 		);
 		assert(
-			checkout.isBranch,
-			0xa5d /* The main branch cannot be rebased onto another branch. */,
+			!checkout.isSharedBranch,
+			0xa5d /* Shared branches cannot be rebased onto another branch. */,
 		);
 
 		checkout.#transaction.activeBranch.rebaseOnto(this.#transaction.activeBranch);
@@ -804,8 +856,8 @@ export class TreeCheckout implements ITreeCheckoutFork {
 			checkout.transaction.commit();
 		}
 		this.#transaction.activeBranch.merge(checkout.#transaction.activeBranch);
-		if (disposeMerged && checkout.isBranch) {
-			// Dispose the merged checkout unless it is the main branch.
+		if (disposeMerged && !checkout.isSharedBranch) {
+			// Dispose the merged checkout unless it is a shared branch.
 			checkout[disposeSymbol]();
 		}
 	}
@@ -961,10 +1013,10 @@ export class TreeCheckout implements ITreeCheckoutFork {
 	 */
 	private isRemoteChangeEvent(event: SharedTreeBranchChange<SharedTreeChange>): boolean {
 		return (
-			// Remote changes are only ever applied to the main branch
-			!this.isBranch &&
-			// Remote changes are applied to the main branch by rebasing it onto the trunk.
-			// No other rebases are allowed on the main branch, so we can use this to detect remote changes.
+			// Remote changes are only ever applied to shared branches
+			this.isSharedBranch &&
+			// Remote changes are applied to the branch by rebasing it onto the trunk.
+			// No other rebases are allowed on shared branches, so we can use this to detect remote changes.
 			event.type === "rebase"
 		);
 	}
@@ -1020,7 +1072,7 @@ class EditLock {
 	 * Edits the tree by calling the methods of the editor passed into the {@link EditLock} constructor.
 	 * @remarks Edits will throw an error if the lock is currently locked.
 	 */
-	public editor: ISharedTreeEditor;
+	public readonly editor: ISharedTreeEditor;
 	private locked = false;
 
 	/**

package/src/shared-tree-core/branch.ts

@@ -24,6 +24,13 @@ import {
 	type RebaseStatsWithDuration,
 } from "../core/index.js";
 import { hasSome, defineLazyCachedProperty } from "../util/index.js";
+import type {
+	OpSpaceCompressedId,
+	SessionSpaceCompressedId,
+} from "@fluidframework/id-compressor";
+
+export type BranchId = SessionSpaceCompressedId | "main";
+export type EncodedBranchId = OpSpaceCompressedId;
 
 /**
  * Describes a change to a `SharedTreeBranch`. Each of the following event types provides a `change` which contains the net change to the branch (or is undefined if there was no net change):

package/src/shared-tree-core/branchIdCodec.ts

@@ -0,0 +1,28 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type {
+	IIdCompressor,
+	OpSpaceCompressedId,
+	SessionId,
+} from "@fluidframework/id-compressor";
+import type { BranchId } from "./branch.js";
+
+export function encodeBranchId(
+	idCompressor: IIdCompressor,
+	branchId: BranchId,
+): OpSpaceCompressedId | undefined {
+	return branchId === "main" ? undefined : idCompressor.normalizeToOpSpace(branchId);
+}
+
+export function decodeBranchId(
+	idCompressor: IIdCompressor,
+	encoded: OpSpaceCompressedId | undefined,
+	context: { readonly originatorId: SessionId },
+): BranchId {
+	return encoded === undefined
+		? "main"
+		: idCompressor.normalizeToSessionSpace(encoded, context.originatorId);
+}