@fluidframework/tree 2.21.0 → 2.23.0-323641

package/src/shared-tree/sharedTree.ts

@@ -4,16 +4,34 @@
  */
 
 import { assert } from "@fluidframework/core-utils/internal";
-import type { ErasedType, IFluidHandle } from "@fluidframework/core-interfaces/internal";
+import type {
+	ErasedType,
+	IFluidHandle,
+	IFluidLoadable,
+} from "@fluidframework/core-interfaces/internal";
 import type {
 	IChannelAttributes,
-	IChannelFactory,
 	IFluidDataStoreRuntime,
-	IChannelServices,
 	IChannelStorageService,
+	IChannel,
 } from "@fluidframework/datastore-definitions/internal";
-import type { ISharedObject } from "@fluidframework/shared-object-base/internal";
-import { UsageError } from "@fluidframework/telemetry-utils/internal";
+import {
+	SharedObject,
+	type IFluidSerializer,
+	type ISharedObject,
+} from "@fluidframework/shared-object-base/internal";
+import {
+	UsageError,
+	type ITelemetryLoggerExt,
+} from "@fluidframework/telemetry-utils/internal";
+import type { IIdCompressor } from "@fluidframework/id-compressor";
+import type {
+	ITelemetryContext,
+	IExperimentalIncrementalSummaryContext,
+	ISummaryTreeWithStats,
+	IRuntimeMessageCollection,
+} from "@fluidframework/runtime-definitions/internal";
+import type { ISequencedDocumentMessage } from "@fluidframework/driver-definitions/internal";
 
 import { type ICodecOptions, noopValidator } from "../codec/index.js";
 import {
@@ -74,6 +92,7 @@ import {
 	FieldKind,
 	type CustomTreeNode,
 	type CustomTreeValue,
+	type ITreeAlpha,
 } from "../simple-tree/index.js";
 
 import { SchematizingSimpleTreeView } from "./schematizingTreeView.js";
@@ -82,12 +101,16 @@ import { SharedTreeChangeFamily } from "./sharedTreeChangeFamily.js";
 import type { SharedTreeChange } from "./sharedTreeChangeTypes.js";
 import type { SharedTreeEditBuilder } from "./sharedTreeEditBuilder.js";
 import { type TreeCheckout, type BranchableTree, createTreeCheckout } from "./treeCheckout.js";
-import { breakingClass, fail, throwIfBroken } from "../util/index.js";
-import type { IIdCompressor } from "@fluidframework/id-compressor";
-import { SharedTreeAttributes, SharedTreeFactoryType } from "./publicContracts.js";
+import {
+	Breakable,
+	breakingClass,
+	fail,
+	throwIfBroken,
+	type WithBreakable,
+} from "../util/index.js";
 
 /**
- * Copy of data from an {@link ISharedTree} at some point in time.
+ * Copy of data from an {@link ITreePrivate} at some point in time.
  * @remarks
  * This is unrelated to Fluids concept of "snapshots".
  */
@@ -111,30 +134,26 @@ export interface SharedTreeContentSnapshot {
 }
 
 /**
- * {@link ITree} extended with some non-public APIs.
+ * Information about a Fluid channel.
+ * @privateRemarks
+ * This is distinct from {@link IChannel} as it omits the APIs used by the runtime to manage the channel and instead only has things which are useful (and safe) to expose to users of the channel.
  * @internal
  */
-export interface ITreeInternal extends ISharedObject, ITree {
-	/**
-	 * Exports root in the same format as {@link TreeAlpha.(exportVerbose:1)} using stored keys.
-	 * @privateRemarks
-	 * TODO:
-	 * This should probably get promoted to a public API on ITree eventually.
-	 */
-	exportVerbose(): VerboseTree | undefined;
+export type IChannelView = Pick<IChannel, "id" | "attributes" | "isAttached">;
 
-	/**
-	 * Exports the SimpleTreeSchema that is stored in the tree, using stored keys for object fields.
-	 * @remarks
-	 * To get the schema using property keys, use {@link getSimpleSchema} on the view schema.
-	 */
-	exportSimpleSchema(): SimpleTreeSchema;
-}
+/**
+ * {@link ITree} extended with some non-public APIs.
+ * @internal
+ */
+export interface ITreeInternal extends IChannelView, ITreeAlpha {}
 
 /**
  * {@link ITreeInternal} extended with some non-exported APIs.
+ * @remarks
+ * This allows access to the tree content using the internal data model used at the storage and "flex" layers,
+ * and should only be needed for testing and debugging this package's internals.
  */
-export interface ISharedTree extends ISharedObject, ITreeInternal {
+export interface ITreePrivate extends ITreeInternal {
 	/**
 	 * Provides a copy of the current content of the tree.
 	 * This can be useful for inspecting the tree when no suitable view schema is available.
@@ -145,6 +164,13 @@ export interface ISharedTree extends ISharedObject, ITreeInternal {
 	contentSnapshot(): SharedTreeContentSnapshot;
 }
 
+/**
+ * {@link ITreePrivate} extended with ISharedObject.
+ * @remarks
+ * This is used when integration testing this package with the Fluid runtime as it exposes the APIs the runtime consumes to manipulate the tree.
+ */
+export interface ISharedTree extends ISharedObject, ITreePrivate {}
+
 /**
  * Has an entry for each codec which writes an explicit version into its data.
  *
@@ -188,20 +214,20 @@ function getCodecVersions(formatVersion: number): ExplicitCodecVersions {
 }
 
 /**
- * Shared tree, configured with a good set of indexes and field kinds which will maintain compatibility over time.
- *
- * TODO: detail compatibility requirements.
+ * Shared object wrapping {@link SharedTreeKernel}.
  */
-@breakingClass
-export class SharedTree
-	extends SharedTreeCore<SharedTreeEditBuilder, SharedTreeChange>
-	implements ISharedTree
-{
-	public readonly checkout: TreeCheckout;
+export class SharedTree extends SharedObject implements ISharedTree, WithBreakable {
+	public readonly breaker: Breakable = new Breakable("Shared Tree");
+
+	public get checkout(): TreeCheckout {
+		return this.kernel.checkout;
+	}
 	public get storedSchema(): TreeStoredSchemaRepository {
 		return this.checkout.storedSchema;
 	}
 
+	private readonly kernel: SharedTreeKernel;
+
 	public constructor(
 		id: string,
 		runtime: IFluidDataStoreRuntime,
@@ -209,23 +235,136 @@ export class SharedTree
 		optionsParam: SharedTreeOptionsInternal,
 		telemetryContextPrefix: string = "fluid_sharedTree_",
 	) {
+		super(id, runtime, attributes, telemetryContextPrefix);
 		if (runtime.idCompressor === undefined) {
 			throw new UsageError("IdCompressor must be enabled to use SharedTree");
 		}
+		this.kernel = new SharedTreeKernel(
+			this.breaker,
+			this,
+			this.serializer,
+			(content, localOpMetadata) => this.submitLocalMessage(content, localOpMetadata),
+			() => this.deltaManager.lastSequenceNumber,
+			this.logger,
+			runtime.idCompressor,
+			optionsParam,
+		);
+	}
+
+	public get editor(): SharedTreeEditBuilder {
+		return this.kernel.getEditor();
+	}
+
+	public summarizeCore(
+		serializer: IFluidSerializer,
+		telemetryContext?: ITelemetryContext,
+		incrementalSummaryContext?: IExperimentalIncrementalSummaryContext,
+	): ISummaryTreeWithStats {
+		return this.kernel.summarizeCore(serializer, telemetryContext, incrementalSummaryContext);
+	}
+
+	protected processCore(
+		message: ISequencedDocumentMessage,
+		local: boolean,
+		localOpMetadata: unknown,
+	): void {
+		this.kernel.processCore(message, local, localOpMetadata);
+	}
+
+	protected override processMessagesCore(messagesCollection: IRuntimeMessageCollection): void {
+		this.kernel.processMessagesCore(messagesCollection);
+	}
+
+	protected onDisconnect(): void {}
+
+	public exportVerbose(): VerboseTree | undefined {
+		return this.kernel.exportVerbose();
+	}
+
+	public exportSimpleSchema(): SimpleTreeSchema {
+		return this.kernel.exportSimpleSchema();
+	}
+
+	public contentSnapshot(): SharedTreeContentSnapshot {
+		return this.kernel.contentSnapshot();
+	}
+
+	// For the new TreeViewAlpha API
+	public viewWith<TRoot extends ImplicitFieldSchema | UnsafeUnknownSchema>(
+		config: TreeViewConfiguration<ReadSchema<TRoot>>,
+	): SchematizingSimpleTreeView<TRoot> & TreeView<ReadSchema<TRoot>>;
+
+	// For the old TreeView API
+	public viewWith<TRoot extends ImplicitFieldSchema>(
+		config: TreeViewConfiguration<TRoot>,
+	): SchematizingSimpleTreeView<TRoot> & TreeView<TRoot>;
+
+	public viewWith<TRoot extends ImplicitFieldSchema | UnsafeUnknownSchema>(
+		config: TreeViewConfiguration<ReadSchema<TRoot>>,
+	): SchematizingSimpleTreeView<TRoot> & TreeView<ReadSchema<TRoot>> {
+		return this.kernel.viewWith(config);
+	}
+
+	protected override async loadCore(services: IChannelStorageService): Promise<void> {
+		await this.kernel.loadCore(services);
+	}
+
+	protected override didAttach(): void {
+		this.kernel.didAttach();
+	}
+
+	protected override applyStashedOp(
+		...args: Parameters<
+			SharedTreeCore<SharedTreeEditBuilder, SharedTreeChange>["applyStashedOp"]
+		>
+	): void {
+		this.kernel.applyStashedOp(...args);
+	}
+
+	protected override reSubmitCore(
+		...args: Parameters<
+			SharedTreeCore<SharedTreeEditBuilder, SharedTreeChange>["reSubmitCore"]
+		>
+	): void {
+		this.kernel.reSubmitCore(...args);
+	}
+}
+
+/**
+ * SharedTreeCore, configured with a good set of indexes and field kinds which will maintain compatibility over time.
+ *
+ * TODO: detail compatibility requirements.
+ */
+@breakingClass
+class SharedTreeKernel extends SharedTreeCore<SharedTreeEditBuilder, SharedTreeChange> {
+	public readonly checkout: TreeCheckout;
+	public get storedSchema(): TreeStoredSchemaRepository {
+		return this.checkout.storedSchema;
+	}
 
+	public constructor(
+		breaker: Breakable,
+		sharedObject: IChannelView & IFluidLoadable,
+		serializer: IFluidSerializer,
+		submitLocalMessage: (content: unknown, localOpMetadata?: unknown) => void,
+		lastSequenceNumber: () => number | undefined,
+		logger: ITelemetryLoggerExt | undefined,
+		idCompressor: IIdCompressor,
+		optionsParam: SharedTreeOptionsInternal,
+	) {
 		const options = { ...defaultSharedTreeOptions, ...optionsParam };
 		const codecVersions = getCodecVersions(options.formatVersion);
 		const schema = new TreeStoredSchemaRepository();
-		const forest = buildConfiguredForest(options.forest, schema, runtime.idCompressor);
-		const revisionTagCodec = new RevisionTagCodec(runtime.idCompressor);
+		const forest = buildConfiguredForest(options.forest, schema, idCompressor);
+		const revisionTagCodec = new RevisionTagCodec(idCompressor);
 		const removedRoots = makeDetachedFieldIndex(
 			"repair",
 			revisionTagCodec,
-			runtime.idCompressor,
+			idCompressor,
 			options,
 		);
-		const schemaSummarizer = new SchemaSummarizer(runtime, schema, options, {
-			getCurrentSeq: () => this.deltaManager.lastSequenceNumber,
+		const schemaSummarizer = new SchemaSummarizer(schema, options, {
+			getCurrentSeq: lastSequenceNumber,
 		});
 		const fieldBatchCodec = makeFieldBatchCodec(options, codecVersions.fieldBatch);
 
@@ -235,8 +374,8 @@ export class SharedTree
 				policy: defaultSchemaPolicy,
 			},
 			encodeType: options.treeEncodeType,
-			originatorId: runtime.idCompressor.localSessionId,
-			idCompressor: runtime.idCompressor,
+			originatorId: idCompressor.localSessionId,
+			idCompressor,
 		};
 		const forestSummarizer = new ForestSummarizer(
 			forest,
@@ -244,7 +383,7 @@ export class SharedTree
 			fieldBatchCodec,
 			encoderContext,
 			options,
-			runtime.idCompressor,
+			idCompressor,
 		);
 		const removedRootsSummarizer = new DetachedFieldIndexSummarizer(removedRoots);
 		const innerChangeFamily = new SharedTreeChangeFamily(
@@ -252,7 +391,7 @@ export class SharedTree
 			fieldBatchCodec,
 			options,
 			options.treeEncodeType,
-			runtime.idCompressor,
+			idCompressor,
 		);
 		const changeFamily = makeMitigatedChangeFamily(
 			innerChangeFamily,
@@ -278,14 +417,16 @@ export class SharedTree
 		);
 		const changeEnricher = new SharedTreeReadonlyChangeEnricher(forest, schema, removedRoots);
 		super(
+			breaker,
+			sharedObject,
+			serializer,
+			submitLocalMessage,
+			logger,
 			[schemaSummarizer, forestSummarizer, removedRootsSummarizer],
 			changeFamily,
 			options,
 			codecVersions,
-			id,
-			runtime,
-			attributes,
-			telemetryContextPrefix,
+			idCompressor,
 			schema,
 			defaultSchemaPolicy,
 			new DefaultResubmitMachine(
@@ -296,44 +437,39 @@ export class SharedTree
 			changeEnricher,
 		);
 		const localBranch = this.getLocalBranch();
-		this.checkout = createTreeCheckout(
-			runtime.idCompressor,
-			this.mintRevisionTag,
-			revisionTagCodec,
-			{
-				branch: localBranch,
-				changeFamily,
-				schema,
-				forest,
-				fieldBatchCodec,
-				removedRoots,
-				chunkCompressionStrategy: options.treeEncodeType,
-				logger: this.logger,
-				breaker: this.breaker,
-				disposeForksAfterTransaction: options.disposeForksAfterTransaction,
-			},
-		);
+		this.checkout = createTreeCheckout(idCompressor, this.mintRevisionTag, revisionTagCodec, {
+			branch: localBranch,
+			changeFamily,
+			schema,
+			forest,
+			fieldBatchCodec,
+			removedRoots,
+			chunkCompressionStrategy: options.treeEncodeType,
+			logger,
+			breaker: this.breaker,
+			disposeForksAfterTransaction: options.disposeForksAfterTransaction,
+		});
 
 		this.checkout.transaction.events.on("started", () => {
-			if (this.isAttached()) {
+			if (sharedObject.isAttached()) {
 				// It is currently forbidden to attach during a transaction, so transaction state changes can be ignored until after attaching.
 				this.commitEnricher.startTransaction();
 			}
 		});
 		this.checkout.transaction.events.on("aborting", () => {
-			if (this.isAttached()) {
+			if (sharedObject.isAttached()) {
 				// It is currently forbidden to attach during a transaction, so transaction state changes can be ignored until after attaching.
 				this.commitEnricher.abortTransaction();
 			}
 		});
 		this.checkout.transaction.events.on("committing", () => {
-			if (this.isAttached()) {
+			if (sharedObject.isAttached()) {
 				// It is currently forbidden to attach during a transaction, so transaction state changes can be ignored until after attaching.
 				this.commitEnricher.commitTransaction();
 			}
 		});
 		this.checkout.events.on("beforeBatch", (event) => {
-			if (event.type === "append" && this.isAttached()) {
+			if (event.type === "append" && sharedObject.isAttached()) {
 				if (this.checkout.transaction.isInProgress()) {
 					this.commitEnricher.addTransactionCommits(event.newCommits);
 				}
@@ -402,12 +538,12 @@ export class SharedTree
 			TreeView<ReadSchema<TRoot>>;
 	}
 
-	protected override async loadCore(services: IChannelStorageService): Promise<void> {
+	public override async loadCore(services: IChannelStorageService): Promise<void> {
 		await super.loadCore(services);
 		this.checkout.load();
 	}
 
-	protected override didAttach(): void {
+	public override didAttach(): void {
 		if (this.checkout.transaction.isInProgress()) {
 			// Attaching during a transaction is not currently supported.
 			// At least part of of the system is known to not handle this case correctly - commit enrichment - and there may be others.
@@ -418,7 +554,7 @@ export class SharedTree
 		super.didAttach();
 	}
 
-	protected override applyStashedOp(
+	public override applyStashedOp(
 		...args: Parameters<
 			SharedTreeCore<SharedTreeEditBuilder, SharedTreeChange>["applyStashedOp"]
 		>
@@ -642,34 +778,6 @@ export const defaultSharedTreeOptions: Required<SharedTreeOptionsInternal> = {
 	disposeForksAfterTransaction: true,
 };
 
-/**
- * A channel factory that creates {@link ISharedTree}s.
- */
-export class SharedTreeFactory implements IChannelFactory<ISharedTree> {
-	public readonly type: string = SharedTreeFactoryType;
-
-	public readonly attributes: IChannelAttributes = SharedTreeAttributes;
-
-	public constructor(private readonly options: SharedTreeOptionsInternal = {}) {}
-
-	public async load(
-		runtime: IFluidDataStoreRuntime,
-		id: string,
-		services: IChannelServices,
-		channelAttributes: Readonly<IChannelAttributes>,
-	): Promise<SharedTree> {
-		const tree = new SharedTree(id, runtime, channelAttributes, this.options);
-		await tree.load(services);
-		return tree;
-	}
-
-	public create(runtime: IFluidDataStoreRuntime, id: string): SharedTree {
-		const tree = new SharedTree(id, runtime, this.attributes, this.options);
-		tree.initializeLocal();
-		return tree;
-	}
-}
-
 function verboseFromCursor(
 	reader: ITreeCursor,
 	schema: ReadonlyMap<TreeNodeSchemaIdentifier, TreeNodeStoredSchema>,

package/src/shared-tree/treeApi.ts

@@ -14,12 +14,13 @@ import {
 	type TreeView,
 	getOrCreateInnerNode,
 	treeNodeApi,
+	rollback,
+	type TransactionConstraint,
 } from "../simple-tree/index.js";
 
 import { SchematizingSimpleTreeView } from "./schematizingTreeView.js";
 import type { ITreeCheckout } from "./treeCheckout.js";
 import { getCheckoutFlexTreeView } from "./checkoutFlexTreeView.js";
-import { rollback, type TransactionConstraint } from "./transactionTypes.js";
 
 /**
  * A function which runs a transaction in a SharedTree.
@@ -394,6 +395,7 @@ function createRunTransaction(): RunTransaction {
  * Run the given transaction.
  * @remarks
  * This API is not publicly exported but is exported outside of this module so that test code may unit test the `Tree.runTransaction` function directly without being restricted to its public API overloads.
+ * @deprecated This API catches exceptions then tries to modify the tree before rethrowing: this is not robust. Use {@link TreeViewAlpha.runTransaction} instead which does not try to edit content in the error case.
  */
 export function runTransaction<
 	TNode extends TreeNode,
@@ -427,6 +429,10 @@ export function runTransaction<
 	}
 }
 
+/**
+ * Run the given transaction.
+ * @deprecated This API catches exceptions then tries to modify the tree before rethrowing: this is not robust. Use {@link TreeViewAlpha.runTransaction} instead which does not try to editing content in the error case.
+ */
 function runTransactionInCheckout<TResult>(
 	checkout: ITreeCheckout,
 	transaction: () => TResult | typeof rollback,
@@ -450,11 +456,14 @@ function runTransactionInCheckout<TResult>(
 				unreachableCase(constraint.type);
 		}
 	}
+
 	let result: ReturnType<typeof transaction>;
 	try {
 		result = transaction();
 	} catch (error) {
 		// If the transaction has an unhandled error, abort and rollback the transaction but continue to propagate the error.
+		// This might try and modify the tree or trigger events while things are in an inconsistent state.
+		// It is up to the user of runTransaction to ensure that does not cause problems (and they have no robust way to do that, which is why its deprecated).
 		checkout.transaction.abort();
 		throw error;
 	}

package/src/shared-tree/treeCheckout.ts

@@ -60,7 +60,13 @@ import {
 	type SharedTreeBranchChange,
 	type Transactor,
 } from "../shared-tree-core/index.js";
-import { Breakable, disposeSymbol, fail, getOrCreate } from "../util/index.js";
+import {
+	Breakable,
+	disposeSymbol,
+	fail,
+	getOrCreate,
+	type WithBreakable,
+} from "../util/index.js";
 
 import { SharedTreeChangeFamily, hasSchemaChange } from "./sharedTreeChangeFamily.js";
 import type { SharedTreeChange } from "./sharedTreeChangeTypes.js";
@@ -182,7 +188,7 @@ export interface TreeBranchFork extends BranchableTree, IDisposable {
  * API for interacting with a {@link SharedTreeBranch}.
  * Implementations of this interface must implement the {@link branchKey} property.
  */
-export interface ITreeCheckout extends AnchorLocator, ViewableTree {
+export interface ITreeCheckout extends AnchorLocator, ViewableTree, WithBreakable {
 	/**
 	 * Read and Write access for schema stored in the document.
 	 *
@@ -391,7 +397,7 @@ export class TreeCheckout implements ITreeCheckoutFork {
 		),
 		/** Optional logger for telemetry. */
 		private readonly logger?: ITelemetryLoggerExt,
-		private readonly breaker: Breakable = new Breakable("TreeCheckout"),
+		public readonly breaker: Breakable = new Breakable("TreeCheckout"),
 		private readonly disposeForksAfterTransaction = true,
 	) {
 		this.#transaction = new SquashingTransactionStack(
@@ -549,15 +555,13 @@ export class TreeCheckout implements ITreeCheckoutFork {
 
 	private withCombinedVisitor(fn: (visitor: DeltaVisitor) => void): void {
 		const anchorVisitor = this.forest.anchors.acquireVisitor();
-		const combinedVisitor = combineVisitors(
-			[this.forest.acquireVisitor(), anchorVisitor],
-			[anchorVisitor],
-		);
+		const combinedVisitor = combineVisitors([this.forest.acquireVisitor(), anchorVisitor]);
 		fn(combinedVisitor);
 		combinedVisitor.free();
 	}
 
 	private checkNotDisposed(usageError?: string): void {
+		this.breaker.use();
 		if (this.disposed) {
 			if (usageError !== undefined) {
 				throw new UsageError(usageError);
@@ -659,7 +663,6 @@ export class TreeCheckout implements ITreeCheckoutFork {
 			this,
 			config,
 			createNodeKeyManager(this.idCompressor),
-			this.breaker,
 			() => {
 				this.views.delete(view);
 			},