(tree) Add versioning to shared tree's summary

packages/dds/tree/src/feature-libraries/detachedFieldIndexSummarizer.ts

@@ -4,34 +4,100 @@
  */
 
 import { bufferToString } from "@fluid-internal/client-utils";
+import { assert } from "@fluidframework/core-utils/internal";
 import type { IChannelStorageService } from "@fluidframework/datastore-definitions/internal";
 import type {
 	IExperimentalIncrementalSummaryContext,
 	ISummaryTreeWithStats,
 	ITelemetryContext,
+	MinimumVersionForCollab,
 } from "@fluidframework/runtime-definitions/internal";
-import { createSingleBlobSummary } from "@fluidframework/shared-object-base/internal";
+import { SummaryTreeBuilder } from "@fluidframework/runtime-utils/internal";
 
 import type { DetachedFieldIndex } from "../core/index.js";
 import type {
 	Summarizable,
 	SummaryElementParser,
 	SummaryElementStringifier,
 } from "../shared-tree-core/index.js";
-import type { JsonCompatibleReadOnly } from "../util/index.js";
+import {
+	brand,
+	readAndParseSnapshotBlob,
+	type Brand,
+	type JsonCompatibleReadOnly,
+} from "../util/index.js";
+import { FluidClientVersion } from "../codec/index.js";
 
 /**
  * The storage key for the blob in the summary containing schema data
  */
 const detachedFieldIndexBlobKey = "DetachedFieldIndexBlob";
 
+/**
+ * The storage key for the blob containing metadata for the detached field index's summary.
+ */
+export const detachedFieldIndexMetadataKey = ".metadata";
+
+/**
+ * The versions for the detached field index summary.
+ */
+export const DetachedFieldIndexSummaryVersion = {
+	/**
+	 * Version 0 represents summaries before versioning was added. This version is not written.
+	 * It is only used to avoid undefined checks.
+	 */
+	v0: 0,
+	/**
+	 * Version 1 adds metadata to the detached field index summary.
+	 */
+	v1: 1,
+	/**
+	 * The latest version of the detached field index summary. Must be updated when a new version is added.
+	 */
+	vLatest: 1,
+} as const;
+export type DetachedFieldIndexSummaryVersion = Brand<
+	(typeof DetachedFieldIndexSummaryVersion)[keyof typeof DetachedFieldIndexSummaryVersion],
+	"DetachedFieldIndexSummaryVersion"
+>;
+
+/**
+ * The type for the metadata in the detached field index's summary.
+ * Using type definition instead of interface to make this compatible with JsonCompatible.
+ */
+// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+export type DetachedFieldIndexSummaryMetadata = {
+	/** The version of the detached field index summary. */
+	readonly version: DetachedFieldIndexSummaryVersion;
+};
+
+/**
+ * Returns the summary version to use as per the given minimum version for collab.
+ */
+function minVersionToDetachedFieldIndexSummaryVersion(
+	version: MinimumVersionForCollab,
+): DetachedFieldIndexSummaryVersion {
+	return version < FluidClientVersion.v2_73
+		? brand(DetachedFieldIndexSummaryVersion.v0)
+		: brand(DetachedFieldIndexSummaryVersion.v1);
+}
+
 /**
  * Provides methods for summarizing and loading a tree index.
  */
 export class DetachedFieldIndexSummarizer implements Summarizable {
 	public readonly key = "DetachedFieldIndex";
 
-	public constructor(private readonly detachedFieldIndex: DetachedFieldIndex) {}
+	// The summary version to write in the metadata for the detached field index summary.
+	private readonly summaryWriteVersion: DetachedFieldIndexSummaryVersion;
+
+	public constructor(
+		private readonly detachedFieldIndex: DetachedFieldIndex,
+		minVersionForCollab: MinimumVersionForCollab,
+	) {
+		this.summaryWriteVersion =
+			minVersionToDetachedFieldIndexSummaryVersion(minVersionForCollab);
+	}
 
 	public summarize(props: {
 		stringify: SummaryElementStringifier;
@@ -41,13 +107,35 @@ export class DetachedFieldIndexSummarizer implements Summarizable {
 		incrementalSummaryContext?: IExperimentalIncrementalSummaryContext;
 	}): ISummaryTreeWithStats {
 		const data = this.detachedFieldIndex.encode();
-		return createSingleBlobSummary(detachedFieldIndexBlobKey, props.stringify(data));
+		const builder = new SummaryTreeBuilder();
+		builder.addBlob(detachedFieldIndexBlobKey, props.stringify(data));
+
+		if (this.summaryWriteVersion >= DetachedFieldIndexSummaryVersion.v1) {
+			const metadata: DetachedFieldIndexSummaryMetadata = {
+				version: this.summaryWriteVersion,
+			};
+			builder.addBlob(detachedFieldIndexMetadataKey, JSON.stringify(metadata));
+		}
+
+		return builder.getSummaryTree();
 	}
 
 	public async load(
 		services: IChannelStorageService,
 		parse: SummaryElementParser,
 	): Promise<void> {
+		if (await services.contains(detachedFieldIndexMetadataKey)) {
+			const metadata = await readAndParseSnapshotBlob<DetachedFieldIndexSummaryMetadata>(
+				detachedFieldIndexMetadataKey,
+				services,
+				parse,
+			);
+			assert(
+				metadata.version === DetachedFieldIndexSummaryVersion.v1,
+				"Unsupported detached field index summary",
+			);
+		}
+
 		if (await services.contains(detachedFieldIndexBlobKey)) {
 			const detachedFieldIndexBuffer = await services.readBlob(detachedFieldIndexBlobKey);
 			const treeBufferString = bufferToString(detachedFieldIndexBuffer, "utf8");

packages/dds/tree/src/feature-libraries/forest-summary/forestSummarizer.ts

@@ -3,7 +3,6 @@
  * Licensed under the MIT License.
  */
 
-import { bufferToString } from "@fluid-internal/client-utils";
 import { assert } from "@fluidframework/core-utils/internal";
 import type { IChannelStorageService } from "@fluidframework/datastore-definitions/internal";
 import type { IIdCompressor } from "@fluidframework/id-compressor";
@@ -32,7 +31,7 @@ import type {
 	SummaryElementParser,
 	SummaryElementStringifier,
 } from "../../shared-tree-core/index.js";
-import { idAllocatorFromMaxId, type JsonCompatible } from "../../util/index.js";
+import { idAllocatorFromMaxId, readAndParseSnapshotBlob } from "../../util/index.js";
 // eslint-disable-next-line import-x/no-internal-modules
 import { chunkFieldSingle, defaultChunkPolicy } from "../chunked-forest/chunkTree.js";
 import {
@@ -46,17 +45,16 @@ import { type ForestCodec, makeForestSummarizerCodec } from "./codec.js";
 import {
 	ForestIncrementalSummaryBehavior,
 	ForestIncrementalSummaryBuilder,
-	forestSummaryContentKey,
 } from "./incrementalSummaryBuilder.js";
 import { TreeCompressionStrategyExtended } from "../treeCompressionUtils.js";
-import type { IFluidHandle } from "@fluidframework/core-interfaces";
-
-/**
- * The key for the tree that contains the overall forest's summary tree.
- * This tree is added by the parent of the forest summarizer.
- * See {@link ForestIncrementalSummaryBuilder} for details on the summary structure.
- */
-export const forestSummaryKey = "Forest";
+import {
+	forestSummaryContentKey,
+	forestSummaryKey,
+	forestSummaryMetadataKey,
+	ForestSummaryVersion,
+	minVersionToForestSummaryVersion,
+	type ForestSummaryMetadata,
+} from "./summaryTypes.js";
 
 /**
  * Provides methods for summarizing and loading a forest.
@@ -89,6 +87,7 @@ export class ForestSummarizer implements Summarizable {
 			(cursor: ITreeCursorSynchronous) => this.forest.chunkField(cursor),
 			shouldEncodeIncrementally,
 			initialSequenceNumber,
+			minVersionToForestSummaryVersion(options.minVersionForCollab),
 		);
 	}
 
@@ -164,24 +163,30 @@ export class ForestSummarizer implements Summarizable {
 			0xc21 /* Forest summary content missing in snapshot */,
 		);
 
-		const readAndParseBlob = async <T extends JsonCompatible<IFluidHandle>>(
-			id: string,
-		): Promise<T> => {
-			const treeBuffer = await services.readBlob(id);
-			const treeBufferString = bufferToString(treeBuffer, "utf8");
-			return parse(treeBufferString) as T;
-		};
+		if (await services.contains(forestSummaryMetadataKey)) {
+			const metadata = await readAndParseSnapshotBlob<ForestSummaryMetadata>(
+				forestSummaryMetadataKey,
+				services,
+				parse,
+			);
+			assert(metadata.version === ForestSummaryVersion.v1, "Unsupported forest summary");
+		}
 
 		// Load the incremental summary builder so that it can download any incremental chunks in the
 		// snapshot.
-		await this.incrementalSummaryBuilder.load(services, readAndParseBlob);
+		await this.incrementalSummaryBuilder.load(services, async (id: string) =>
+			readAndParseSnapshotBlob(id, services, parse),
+		);
 
 		// TODO: this code is parsing data without an optional validator, this should be defined in a typebox schema as part of the
 		// forest summary format.
-		const fields = this.codec.decode(await readAndParseBlob(forestSummaryContentKey), {
-			...this.encoderContext,
-			incrementalEncoderDecoder: this.incrementalSummaryBuilder,
-		});
+		const fields = this.codec.decode(
+			await readAndParseSnapshotBlob(forestSummaryContentKey, services, parse),
+			{
+				...this.encoderContext,
+				incrementalEncoderDecoder: this.incrementalSummaryBuilder,
+			},
+		);
 		const allocator = idAllocatorFromMaxId();
 		const fieldChanges: [FieldKey, DeltaFieldChanges][] = [];
 		const build: DeltaDetachedNodeBuild[] = [];

packages/dds/tree/src/feature-libraries/forest-summary/incrementalSummaryBuilder.ts

@@ -30,21 +30,13 @@ import type { ISnapshotTree } from "@fluidframework/driver-definitions/internal"
 import { LoggingError } from "@fluidframework/telemetry-utils/internal";
 import type { IFluidHandle } from "@fluidframework/core-interfaces";
 import type { SummaryElementStringifier } from "../../shared-tree-core/index.js";
-
-/**
- * The key for the blob under ForestSummarizer's root.
- * This blob contains the ForestCodec's output.
- * See {@link ForestIncrementalSummaryBuilder} for details on the summary structure.
- */
-export const forestSummaryContentKey = "ForestTree";
-
-/**
- * The contents of an incremental chunk is under a summary tree node with its {@link ChunkReferenceId} as the key.
- * The inline portion of the chunk content is encoded with the forest codec is stored in a blob with this key.
- * The rest of the chunk contents  is stored in the summary tree under the summary tree node.
- * See the summary format in {@link ForestIncrementalSummaryBuilder} for more details.
- */
-const chunkContentsBlobKey = "contents";
+import {
+	chunkContentsBlobKey,
+	forestSummaryContentKey,
+	forestSummaryMetadataKey,
+	ForestSummaryVersion,
+	type ForestSummaryMetadata,
+} from "./summaryTypes.js";
 
 /**
  * State that tells whether a summary is currently being tracked.
@@ -291,6 +283,8 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 		private readonly getChunkAtCursor: (cursor: ITreeCursorSynchronous) => TreeChunk[],
 		public readonly shouldEncodeIncrementally: IncrementalEncodingPolicy,
 		private readonly initialSequenceNumber: number,
+		// The summary version to write in the metadata for the detached field index summary.
+		private readonly summaryWriteVersion: ForestSummaryVersion,
 	) {}
 
 	/**
@@ -462,6 +456,15 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 		return chunkReferenceIds;
 	}
 
+	private maybeAddMetadataToSummary(summaryBuilder: SummaryTreeBuilder): void {
+		if (this.summaryWriteVersion >= ForestSummaryVersion.v1) {
+			const metadata: ForestSummaryMetadata = {
+				version: this.summaryWriteVersion,
+			};
+			summaryBuilder.addBlob(forestSummaryMetadataKey, JSON.stringify(metadata));
+		}
+	}
+
 	/**
 	 * Must be called after summary generation is complete to finish tracking the summary.
 	 * It clears any tracking state and deletes the tracking properties for summaries that are older than the
@@ -479,10 +482,12 @@ export class ForestIncrementalSummaryBuilder implements IncrementalEncoderDecode
 		if (!this.enableIncrementalSummary || incrementalSummaryContext === undefined) {
 			const summaryBuilder = new SummaryTreeBuilder();
 			summaryBuilder.addBlob(forestSummaryContentKey, forestSummaryContent);
+			this.maybeAddMetadataToSummary(summaryBuilder);
 			return summaryBuilder.getSummaryTree();
 		}
 
 		validateTrackingSummary(this.forestSummaryState, this.trackedSummaryProperties);
+		this.maybeAddMetadataToSummary(this.trackedSummaryProperties.parentSummaryBuilder);
 
 		this.trackedSummaryProperties.parentSummaryBuilder.addBlob(
 			forestSummaryContentKey,

packages/dds/tree/src/feature-libraries/forest-summary/index.ts

@@ -3,6 +3,7 @@
  * Licensed under the MIT License.
  */
 
-export { forestSummaryKey, ForestSummarizer } from "./forestSummarizer.js";
+export { ForestSummarizer } from "./forestSummarizer.js";
 export { getCodecTreeForForestFormat } from "./codec.js";
 export { ForestFormatVersion } from "./format.js";
+export { forestSummaryKey } from "./summaryTypes.js";

packages/dds/tree/src/feature-libraries/forest-summary/summaryTypes.ts

@@ -0,0 +1,79 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { MinimumVersionForCollab } from "@fluidframework/runtime-definitions/internal";
+import { FluidClientVersion } from "../../codec/index.js";
+import { brand, type Brand } from "../../util/index.js";
+
+/**
+ * The key for the tree that contains the overall forest's summary tree.
+ * This tree is added by the parent of the forest summarizer.
+ * See {@link ForestIncrementalSummaryBuilder} for details on the summary structure.
+ */
+export const forestSummaryKey = "Forest";
+
+/**
+ * The key for the blob under ForestSummarizer's root.
+ * This blob contains the ForestCodec's output.
+ * See {@link ForestIncrementalSummaryBuilder} for details on the summary structure.
+ */
+export const forestSummaryContentKey = "ForestTree";
+
+/**
+ * The storage key for the blob containing metadata for the forest's summary.
+ */
+export const forestSummaryMetadataKey = ".metadata";
+
+/**
+ * The contents of an incremental chunk is under a summary tree node with its {@link ChunkReferenceId} as the key.
+ * The inline portion of the chunk content is encoded with the forest codec is stored in a blob with this key.
+ * The rest of the chunk contents  is stored in the summary tree under the summary tree node.
+ * See the summary format in {@link ForestIncrementalSummaryBuilder} for more details.
+ */
+export const chunkContentsBlobKey = "contents";
+
+/**
+ * The versions for the forest summary.
+ */
+export const ForestSummaryVersion = {
+	/**
+	 * Version 0 represents summaries before versioning was added. This version is not written.
+	 * It is only used to avoid undefined checks.
+	 */
+	v0: 0,
+	/**
+	 * Version 1 adds metadata to the forest summary.
+	 */
+	v1: 1,
+	/**
+	 * The latest version of the forest summary. Must be updated when a new version is added.
+	 */
+	vLatest: 1,
+} as const;
+export type ForestSummaryVersion = Brand<
+	(typeof ForestSummaryVersion)[keyof typeof ForestSummaryVersion],
+	"ForestSummaryVersion"
+>;
+
+/**
+ * The type for the metadata in forest's summary.
+ * Using type definition instead of interface to make this compatible with JsonCompatible.
+ */
+// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+export type ForestSummaryMetadata = {
+	/** The version of the forest summary. */
+	readonly version: ForestSummaryVersion;
+};
+
+/**
+ * Returns the summary version to use as per the given minimum version for collab.
+ */
+export function minVersionToForestSummaryVersion(
+	version: MinimumVersionForCollab,
+): ForestSummaryVersion {
+	return version < FluidClientVersion.v2_73
+		? brand(ForestSummaryVersion.v0)
+		: brand(ForestSummaryVersion.v1);
+}