@fluidframework/tree 2.74.0-365691 → 2.74.0

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

@@ -3,12 +3,12 @@
  * Licensed under the MIT License.
  */
 
-import type { Brand } from "../util/index.js";
+import { strictEnum, type Values } from "../util/index.js";
 
 /**
  * The format version for the message.
  */
-export const MessageFormatVersion = {
+export const MessageFormatVersion = strictEnum("MessageFormatVersion", {
 	/**
 	 * NOTE: this is written as `undefined` rather than `0` in the wire format.
 	 * Introduced and retired prior to 2.0.
@@ -27,32 +27,39 @@ export const MessageFormatVersion = {
 	v2: 2,
 	/**
 	 * Introduced prior to 2.0 and used beyond.
-	 * Reading capability is currently maintained for backwards compatibility, but it could be removed in the future.
-	 * Writing capability needs to be maintained.
+	 * Reading capability must be maintained for backwards compatibility.
+	 * Writing capability needs to be maintained so long as {@link lowestMinVersionForCollab} is less than 2.2.0.
 	 */
 	v3: 3,
 	/**
-	 * Was inadvertently released in 2.43.0 (through usages of configuredSharedTree) and remains available.
+	 * Introduced in 2.2.0.
+	 * Was inadvertently made usable for writing in 2.43.0 (through configuredSharedTree) and remains available.
 	 * Reading capability must be maintained for backwards compatibility.
-	 * Writing capability needs to be maintained.
-	 * @privateRemarks TODO: stop writing this version.
+	 * Writing capability could be dropped in favor of {@link MessageFormatVersion.v3},
+	 * but doing so would make the pattern of writable versions more complex and gain little
+	 * because most of the logic for this format is shared with {@link MessageFormatVersion.v3}.
 	 */
 	v4: 4,
+	/**
+	 * This version number was used internally for testing shared branches.
+	 * This format was never made stable.
+	 * This version number is kept here solely to avoid reusing the number: it is not supported for either reading or writing.
+	 * @deprecated Use {@link MessageFormatVersion.vSharedBranches} for testing shared branches.
+	 */
+	v5: 5,
 	/**
 	 * Not yet released.
 	 * Only used for testing shared branches.
 	 */
-	v5: 5,
-} as const;
-export type MessageFormatVersion = Brand<
-	(typeof MessageFormatVersion)[keyof typeof MessageFormatVersion],
-	"MessageFormatVersion"
->;
+	vSharedBranches: "shared-branches|v0.1",
+});
+export type MessageFormatVersion = Values<typeof MessageFormatVersion>;
+
 export const supportedMessageFormatVersions: ReadonlySet<MessageFormatVersion> = new Set([
 	MessageFormatVersion.v3,
 	MessageFormatVersion.v4,
-	MessageFormatVersion.v5,
-] as MessageFormatVersion[]);
+	MessageFormatVersion.vSharedBranches,
+]);
 export const messageFormatVersions: ReadonlySet<MessageFormatVersion> = new Set(
-	Object.values(MessageFormatVersion) as MessageFormatVersion[],
+	Object.values(MessageFormatVersion),
 );

package/src/shared-tree-core/{messageFormatV5.ts → messageFormatVSharedBranches.ts}

@@ -9,6 +9,7 @@ import { type TSchema, Type } from "@sinclair/typebox";
 import { type EncodedRevisionTag, RevisionTagSchema, SessionIdSchema } from "../core/index.js";
 import type { JsonCompatibleReadOnly } from "../util/index.js";
 import type { EncodedBranchId } from "./branch.js";
+import { MessageFormatVersion } from "./messageFormat.js";
 
 /**
  * The format of messages that SharedTree sends and receives.
@@ -30,12 +31,9 @@ export interface Message {
 	readonly branchId?: EncodedBranchId;
 
 	/**
-	 * The version of the message. This controls how the message is encoded.
-	 *
-	 * This was not set historically and was added before making any breaking changes to the format.
-	 * For that reason, absence of a 'version' field is synonymous with version 1.
+	 * The version of the message format.
 	 */
-	readonly version?: number;
+	readonly version: typeof MessageFormatVersion.vSharedBranches;
 }
 
 // Return type is intentionally derived.
@@ -46,5 +44,5 @@ export const Message = <ChangeSchema extends TSchema>(tChange: ChangeSchema) =>
 		originatorId: SessionIdSchema,
 		changeset: Type.Optional(tChange),
 		branchId: Type.Optional(Type.Number()),
-		version: Type.Optional(Type.Number()),
+		version: Type.Literal(MessageFormatVersion.vSharedBranches),
 	});

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

@@ -62,9 +62,16 @@ import {
 import type { DecodedMessage } from "./messageTypes.js";
 import type { ResubmitMachine } from "./resubmitMachine.js";
 import type { MessageFormatVersion } from "./messageFormat.js";
-
-// TODO: Organize this to be adjacent to persisted types.
-const summarizablesTreeKey = "indexes";
+import {
+	minVersionToSharedTreeSummaryFormatVersion,
+	summarizablesTreeKey,
+	supportedSharedTreeSummaryFormatVersions,
+	type SharedTreeSummaryFormatVersion,
+	type Summarizable,
+	type SummaryElementParser,
+	type SummaryElementStringifier,
+} from "./summaryTypes.js";
+import { VersionedSummarizer } from "./versionedSummarizer.js";
 
 export interface ClonableSchemaAndPolicy extends SchemaAndPolicy {
 	schema: TreeStoredSchemaRepository;
@@ -80,7 +87,8 @@ export interface SharedTreeCoreOptionsInternal
  */
 @breakingClass
 export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
-	implements WithBreakable
+	extends VersionedSummarizer<SharedTreeSummaryFormatVersion>
+	implements WithBreakable, Summarizable
 {
 	private readonly editManager: EditManager<TEditor, TChange, ChangeFamily<TEditor, TChange>>;
 	private readonly summarizables: readonly [EditManagerSummarizer<TChange>, ...Summarizable[]];
@@ -139,6 +147,13 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 		enricher?: ChangeEnricherReadonlyCheckout<TChange>,
 		public readonly getEditor: () => TEditor = () => this.getLocalBranch().editor,
 	) {
+		super(
+			summarizablesTreeKey,
+			minVersionToSharedTreeSummaryFormatVersion(options.minVersionForCollab),
+			supportedSharedTreeSummaryFormatVersions,
+			true /* supportPreVersioningFormat */,
+		);
+
 		this.schemaAndPolicy = {
 			schema,
 			policy: schemaPolicy,
@@ -178,6 +193,7 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 				this.editManager,
 				editManagerCodec,
 				this.idCompressor,
+				options.minVersionForCollab,
 				this.schemaAndPolicy,
 			),
 			...summarizables,
@@ -203,14 +219,16 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 
 	// TODO: SharedObject's merging of the two summary methods into summarizeCore is not what we want here:
 	// We might want to not subclass it, or override/reimplement most of its functionality.
-	@throwIfBroken
-	public summarizeCore(
-		serializer: IFluidSerializer,
-		telemetryContext?: ITelemetryContext,
-		incrementalSummaryContext?: IExperimentalIncrementalSummaryContext,
-		fullTree?: boolean,
-	): ISummaryTreeWithStats {
-		const builder = new SummaryTreeBuilder();
+	protected summarizeInternal(props: {
+		stringify: SummaryElementStringifier;
+		fullTree?: boolean;
+		trackState?: boolean;
+		telemetryContext?: ITelemetryContext;
+		incrementalSummaryContext?: IExperimentalIncrementalSummaryContext;
+		builder: SummaryTreeBuilder;
+	}): void {
+		const { stringify, fullTree, telemetryContext, incrementalSummaryContext, builder } =
+			props;
 		const summarizableBuilder = new SummaryTreeBuilder();
 		// Merge the summaries of all summarizables together under a single ISummaryTree
 		for (const s of this.summarizables) {
@@ -226,28 +244,24 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 			summarizableBuilder.addWithStats(
 				s.key,
 				s.summarize({
-					stringify: (contents: unknown) =>
-						serializer.stringify(contents, this.sharedObject.handle),
+					stringify,
 					fullTree,
 					telemetryContext,
 					incrementalSummaryContext: childIncrementalSummaryContext,
 				}),
 			);
 		}
-
 		builder.addWithStats(summarizablesTreeKey, summarizableBuilder.getSummaryTree());
-		return builder.getSummaryTree();
 	}
 
-	public async loadCore(services: IChannelStorageService): Promise<void> {
-		assert(
-			this.getLocalBranch().getHead() === this.editManager.getTrunkHead("main"),
-			0xaaa /* All local changes should be applied to the trunk before loading from summary */,
-		);
+	protected async loadInternal(
+		services: IChannelStorageService,
+		parse: SummaryElementParser,
+	): Promise<void> {
 		const [editManagerSummarizer, ...summarizables] = this.summarizables;
-		const loadEditManager = this.loadSummarizable(editManagerSummarizer, services);
+		const loadEditManager = this.loadSummarizable(editManagerSummarizer, services, parse);
 		const loadSummarizables = summarizables.map(async (s) =>
-			this.loadSummarizable(s, services),
+			this.loadSummarizable(s, services, parse),
 		);
 
 		if (this.detachedRevision !== undefined) {
@@ -268,6 +282,30 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 		}
 	}
 
+	@throwIfBroken
+	public summarizeCore(
+		serializer: IFluidSerializer,
+		telemetryContext?: ITelemetryContext,
+		incrementalSummaryContext?: IExperimentalIncrementalSummaryContext,
+		fullTree?: boolean,
+	): ISummaryTreeWithStats {
+		return this.summarize({
+			stringify: (contents: unknown) =>
+				serializer.stringify(contents, this.sharedObject.handle),
+			fullTree,
+			telemetryContext,
+			incrementalSummaryContext,
+		});
+	}
+
+	public async loadCore(services: IChannelStorageService): Promise<void> {
+		assert(
+			this.getLocalBranch().getHead() === this.editManager.getTrunkHead("main"),
+			0xaaa /* All local changes should be applied to the trunk before loading from summary */,
+		);
+		await super.load(services, (contents) => this.serializer.parse(contents));
+	}
+
 	private registerSharedBranch(branchId: BranchId): void {
 		this.editManager.getLocalBranch(branchId).events.on("beforeChange", (change) => {
 			if (change.type === "append") {
@@ -286,10 +324,11 @@ export class SharedTreeCore<TEditor extends ChangeFamilyEditor, TChange>
 	private async loadSummarizable(
 		summarizable: Summarizable,
 		services: IChannelStorageService,
+		parse: SummaryElementParser,
 	): Promise<void> {
 		return summarizable.load(
 			scopeStorageService(services, summarizablesTreeKey, summarizable.key),
-			(contents) => this.serializer.parse(contents),
+			parse,
 		);
 	}
 
@@ -646,57 +685,6 @@ function isClonableSchemaPolicy(
 	return schemaAndPolicy.schema !== undefined && schemaAndPolicy.policy !== undefined;
 }
 
-/**
- * Specifies the behavior of a component that puts data in a summary.
- */
-export interface Summarizable {
-	/**
-	 * Field name in summary json under which this element stores its data.
-	 */
-	readonly key: string;
-
-	/**
-	 * {@inheritDoc @fluidframework/datastore-definitions#(IChannel:interface).summarize}
-	 * @param stringify - Serializes the contents of the component (including {@link (IFluidHandle:interface)}s) for storage.
-	 * @param fullTree - A flag indicating whether the attempt should generate a full
-	 * summary tree without any handles for unchanged subtrees. It should only be set to true when generating
-	 * a summary from the entire container. The default value is false.
-	 * @param trackState - An optimization for tracking state of objects across summaries. If the state
-	 * of an object did not change since last successful summary, an
-	 * {@link @fluidframework/protocol-definitions#ISummaryHandle} can be used
-	 * instead of re-summarizing it. If this is `false`, the expectation is that you should never
-	 * send an `ISummaryHandle`, since you are not expected to track state. The default value is true.
-	 * @param telemetryContext - See {@link @fluidframework/runtime-definitions#ITelemetryContext}.
-	 * @param incrementalSummaryContext - See {@link @fluidframework/runtime-definitions#IExperimentalIncrementalSummaryContext}.
-	 */
-	summarize(props: {
-		stringify: SummaryElementStringifier;
-		fullTree?: boolean;
-		trackState?: boolean;
-		telemetryContext?: ITelemetryContext;
-		incrementalSummaryContext?: IExperimentalIncrementalSummaryContext;
-	}): ISummaryTreeWithStats;
-
-	/**
-	 * Allows the component to perform custom loading. The storage service is scoped to this component and therefore
-	 * paths in this component will not collide with those in other components, even if they are the same string.
-	 * @param service - Storage used by the component
-	 * @param parse - Parses serialized data from storage into runtime objects for the component
-	 */
-	load(service: IChannelStorageService, parse: SummaryElementParser): Promise<void>;
-}
-
-/**
- * Serializes the given contents into a string acceptable for storing in summaries, i.e. all
- * Fluid handles have been replaced appropriately by an IFluidSerializer
- */
-export type SummaryElementStringifier = (contents: unknown) => string;
-
-/**
- * Parses a serialized/summarized string into an object, rehydrating any Fluid handles as necessary
- */
-export type SummaryElementParser = (contents: string) => unknown;
-
 /**
  * Compose an {@link IChannelStorageService} which prefixes all paths before forwarding them to the original service
  */

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

@@ -0,0 +1,122 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { IChannelStorageService } from "@fluidframework/datastore-definitions/internal";
+import type {
+	IExperimentalIncrementalSummaryContext,
+	ISummaryTreeWithStats,
+	ITelemetryContext,
+	MinimumVersionForCollab,
+} from "@fluidframework/runtime-definitions/internal";
+
+// TODO: Organize this to be adjacent to persisted types.
+/**
+ * The storage key for the subtree containing all summarizable indexes in the SharedTree summary.
+ */
+export const summarizablesTreeKey = "indexes";
+
+/**
+ * The storage key for the blob containing metadata for the summarizable's summary.
+ */
+export const summarizablesMetadataKey = ".metadata";
+
+/**
+ * Specifies the behavior of a component that puts data in a summary.
+ */
+export interface Summarizable {
+	/**
+	 * Field name in summary json under which this element stores its data.
+	 */
+	readonly key: string;
+
+	/**
+	 * {@inheritDoc @fluidframework/datastore-definitions#(IChannel:interface).summarize}
+	 * @param stringify - Serializes the contents of the component (including {@link (IFluidHandle:interface)}s) for storage.
+	 * @param fullTree - A flag indicating whether the attempt should generate a full
+	 * summary tree without any handles for unchanged subtrees. It should only be set to true when generating
+	 * a summary from the entire container. The default value is false.
+	 * @param trackState - An optimization for tracking state of objects across summaries. If the state
+	 * of an object did not change since last successful summary, an
+	 * {@link @fluidframework/protocol-definitions#ISummaryHandle} can be used
+	 * instead of re-summarizing it. If this is `false`, the expectation is that you should never
+	 * send an `ISummaryHandle`, since you are not expected to track state. The default value is true.
+	 * @param telemetryContext - See {@link @fluidframework/runtime-definitions#ITelemetryContext}.
+	 * @param incrementalSummaryContext - See {@link @fluidframework/runtime-definitions#IExperimentalIncrementalSummaryContext}.
+	 */
+	summarize(props: {
+		stringify: SummaryElementStringifier;
+		fullTree?: boolean;
+		trackState?: boolean;
+		telemetryContext?: ITelemetryContext;
+		incrementalSummaryContext?: IExperimentalIncrementalSummaryContext;
+	}): ISummaryTreeWithStats;
+
+	/**
+	 * Allows the component to perform custom loading. The storage service is scoped to this component and therefore
+	 * paths in this component will not collide with those in other components, even if they are the same string.
+	 * @param service - Storage used by the component
+	 * @param parse - Parses serialized data from storage into runtime objects for the component
+	 */
+	load(service: IChannelStorageService, parse: SummaryElementParser): Promise<void>;
+}
+
+/**
+ * Serializes the given contents into a string acceptable for storing in summaries, i.e. all
+ * Fluid handles have been replaced appropriately by an IFluidSerializer
+ */
+export type SummaryElementStringifier = (contents: unknown) => string;
+
+/**
+ * Parses a serialized/summarized string into an object, rehydrating any Fluid handles as necessary
+ */
+export type SummaryElementParser = (contents: string) => unknown;
+
+/**
+ * The type for the metadata in the summarizable's summary.
+ * The metadata is stored under the {@link summarizablesMetadataKey} key in the summary.
+ * @remarks
+ * This is common metadata used by all summarizables. If a summarizable needs to add more metadata,
+ * it should define its own metadata type that extends this type.
+ */
+// Using type definition instead of interface to make this compatible with JsonCompatible.
+// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+export type SharedTreeSummarizableMetadata = {
+	/** The version of the SharedTree summary. */
+	readonly version: number;
+};
+
+/**
+ * The versions for the SharedTree summary format.
+ */
+export const enum SharedTreeSummaryFormatVersion {
+	/**
+	 * This version represents summary format before summary versioning was introduced.
+	 */
+	v1 = 1,
+	/**
+	 * This version adds metadata to the summary. This is backward compatible with version 1.
+	 */
+	v2 = 2,
+	/**
+	 * The latest version of the SharedTree summary. Must be updated when a new version is added.
+	 */
+	vLatest = v2,
+}
+
+export const supportedSharedTreeSummaryFormatVersions =
+	new Set<SharedTreeSummaryFormatVersion>([
+		SharedTreeSummaryFormatVersion.v1,
+		SharedTreeSummaryFormatVersion.v2,
+	]);
+
+/**
+ * Returns the summary version to use as per the given minimum version for collab.
+ */
+export function minVersionToSharedTreeSummaryFormatVersion(
+	version: MinimumVersionForCollab,
+): SharedTreeSummaryFormatVersion {
+	// Currently, version 2 is written which adds metadata blob to the summary.
+	return SharedTreeSummaryFormatVersion.v2;
+}

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

@@ -0,0 +1,114 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { assert } from "@fluidframework/core-utils/internal";
+import type { IChannelStorageService } from "@fluidframework/datastore-definitions/internal";
+import type {
+	IExperimentalIncrementalSummaryContext,
+	ISummaryTreeWithStats,
+	ITelemetryContext,
+} from "@fluidframework/runtime-definitions/internal";
+import { SummaryTreeBuilder } from "@fluidframework/runtime-utils/internal";
+import { UsageError } from "@fluidframework/telemetry-utils/internal";
+import {
+	summarizablesMetadataKey,
+	type SharedTreeSummarizableMetadata,
+	type Summarizable,
+	type SummaryElementParser,
+	type SummaryElementStringifier,
+} from "./summaryTypes.js";
+import { readAndParseSnapshotBlob } from "../util/index.js";
+
+/**
+ * Utility for implementing {@link Summarizable}s classes with versioning.
+ * It handles versioning of summaries - writing version metadata to summaries
+ * and checking version compatibility when loading.
+ */
+export abstract class VersionedSummarizer<TVersion extends number> implements Summarizable {
+	public constructor(
+		/** {@link Summarizable.key} */
+		public readonly key: string,
+		/** The format version of the summary to write in the summary metadata. */
+		private readonly writeVersion: TVersion,
+		/** The set of supported versions that a summary can have for this summarizer to load it. */
+		private readonly supportedVersions: ReadonlySet<TVersion>,
+		/**
+		 * Whether to support loading summaries before versioning was added, i.e., summaries without metadata blob.
+		 * @remarks
+		 * This version may not be supported if the support for the version before metadata blob was dropped.
+		 * In that case, this will not be present in `supportedVersions` and an error will be thrown during load.
+		 */
+		private readonly supportPreVersioningFormat: boolean,
+	) {
+		assert(
+			this.supportedVersions.has(this.writeVersion),
+			0xca6 /* Unsupported write version requested. */,
+			() => `Write version ${this.writeVersion} requested but not supported with key ${key}.`,
+		);
+	}
+
+	/**
+	 * The summarize function that derived classes must implement. They should use the passed summary tree builder to
+	 * add their summary data.
+	 */
+	protected abstract summarizeInternal(props: {
+		stringify: SummaryElementStringifier;
+		fullTree?: boolean;
+		trackState?: boolean;
+		telemetryContext?: ITelemetryContext;
+		incrementalSummaryContext?: IExperimentalIncrementalSummaryContext;
+		builder: SummaryTreeBuilder;
+	}): void;
+
+	/**
+	 * The load function that derived classes must implement to load their summary data.
+	 */
+	protected abstract loadInternal(
+		services: IChannelStorageService,
+		parse: SummaryElementParser,
+		/**
+		 * The format version of the summary being loaded, or undefined if this is pre-versioning format,
+		 * i.e., the summary has no version metadata.
+		 */
+		version: TVersion | undefined,
+	): Promise<void>;
+
+	public summarize(props: {
+		stringify: SummaryElementStringifier;
+		fullTree?: boolean;
+		trackState?: boolean;
+		telemetryContext?: ITelemetryContext;
+		incrementalSummaryContext?: IExperimentalIncrementalSummaryContext;
+	}): ISummaryTreeWithStats {
+		const builder = new SummaryTreeBuilder();
+		const metadata: SharedTreeSummarizableMetadata = {
+			version: this.writeVersion,
+		};
+		builder.addBlob(summarizablesMetadataKey, props.stringify(metadata));
+		this.summarizeInternal({ ...props, builder });
+		return builder.getSummaryTree();
+	}
+
+	public async load(
+		services: IChannelStorageService,
+		parse: SummaryElementParser,
+	): Promise<void> {
+		let version: TVersion | undefined;
+		if (await services.contains(summarizablesMetadataKey)) {
+			const metadata = await readAndParseSnapshotBlob<SharedTreeSummarizableMetadata>(
+				summarizablesMetadataKey,
+				services,
+				(contents) => parse(contents),
+			);
+			version = metadata.version as TVersion;
+			if (!this.supportedVersions.has(version)) {
+				throw new UsageError(`Cannot read version ${version} of shared tree summary.`);
+			}
+		} else if (!this.supportPreVersioningFormat) {
+			throw new UsageError(`Cannot read summary without versioning for shared tree summary.`);
+		}
+		await this.loadInternal(services, parse, version);
+	}
+}