@fluidframework/tree 2.61.0 → 2.62.0

package/src/shared-tree-core/{editManagerFormat.ts → editManagerFormatCommons.ts}

@@ -13,6 +13,7 @@ import {
 	SessionIdSchema,
 } from "../core/index.js";
 import { type Brand, brandedNumberType } from "../util/index.js";
+import type { EncodedBranchId } from "./branch.js";
 
 /**
  * Contains a single change to the `SharedTree` and associated metadata.
@@ -67,7 +68,7 @@ export type SequenceId = Static<typeof SequenceId>;
  */
 export interface SequencedCommit<TChangeset> extends Commit<TChangeset>, SequenceId {}
 
-const SequencedCommit = <ChangeSchema extends TSchema>(tChange: ChangeSchema) =>
+export const SequencedCommit = <ChangeSchema extends TSchema>(tChange: ChangeSchema) =>
 	Type.Composite([CommitBase(tChange), SequenceId], noAdditionalProps);
 
 /**
@@ -86,7 +87,7 @@ export interface EncodedSummarySessionBranch<TChangeset> {
 	readonly commits: Commit<TChangeset>[];
 }
 
-const SummarySessionBranch = <ChangeSchema extends TSchema>(tChange: ChangeSchema) =>
+export const SummarySessionBranch = <ChangeSchema extends TSchema>(tChange: ChangeSchema) =>
 	Type.Object(
 		{
 			base: RevisionTagSchema,
@@ -95,23 +96,26 @@ const SummarySessionBranch = <ChangeSchema extends TSchema>(tChange: ChangeSchem
 		noAdditionalProps,
 	);
 
-export interface EncodedEditManager<TChangeset> {
+export interface EncodedSharedBranch<TChangeset> {
+	readonly id?: EncodedBranchId;
+	readonly name?: string;
+	readonly author?: string;
+	readonly session?: SessionId;
+	readonly base?: EncodedRevisionTag;
 	readonly trunk: readonly Readonly<SequencedCommit<TChangeset>>[];
-	readonly branches: readonly [SessionId, Readonly<EncodedSummarySessionBranch<TChangeset>>][];
-	readonly version: 1 | 2 | 3 | 4;
+	readonly peers: readonly [SessionId, Readonly<EncodedSummarySessionBranch<TChangeset>>][];
 }
 
-export const EncodedEditManager = <ChangeSchema extends TSchema>(tChange: ChangeSchema) =>
+export const EncodedSharedBranch = <ChangeSchema extends TSchema>(tChange: ChangeSchema) =>
 	Type.Object(
 		{
-			version: Type.Union([
-				Type.Literal(1),
-				Type.Literal(2),
-				Type.Literal(3),
-				Type.Literal(4),
-			]),
+			id: Type.Optional(Type.Number()),
+			name: Type.Optional(Type.String()),
+			session: Type.Optional(SessionIdSchema),
+			author: Type.Optional(Type.String()),
+			base: Type.Optional(RevisionTagSchema),
 			trunk: Type.Array(SequencedCommit(tChange)),
-			branches: Type.Array(Type.Tuple([SessionIdSchema, SummarySessionBranch(tChange)])),
+			peers: Type.Array(Type.Tuple([SessionIdSchema, SummarySessionBranch(tChange)])),
 		},
 		noAdditionalProps,
 	);

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

@@ -0,0 +1,42 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { SessionId } from "@fluidframework/id-compressor";
+import { type ObjectOptions, type TSchema, Type } from "@sinclair/typebox";
+
+import { SessionIdSchema } from "../core/index.js";
+import {
+	type EncodedSummarySessionBranch,
+	SequencedCommit,
+	SummarySessionBranch,
+} from "./editManagerFormatCommons.js";
+
+const noAdditionalProps: ObjectOptions = { additionalProperties: false };
+
+// Many of the return types in this module are intentionally derived, rather than explicitly specified.
+/* eslint-disable @typescript-eslint/explicit-function-return-type */
+
+export interface EncodedEditManager<TChangeset> {
+	readonly trunk: readonly Readonly<SequencedCommit<TChangeset>>[];
+	readonly branches: readonly [SessionId, Readonly<EncodedSummarySessionBranch<TChangeset>>][];
+	readonly version: 1 | 2 | 3 | 4;
+}
+
+export const EncodedEditManager = <ChangeSchema extends TSchema>(tChange: ChangeSchema) =>
+	Type.Object(
+		{
+			version: Type.Union([
+				Type.Literal(1),
+				Type.Literal(2),
+				Type.Literal(3),
+				Type.Literal(4),
+			]),
+			trunk: Type.Array(SequencedCommit(tChange)),
+			branches: Type.Array(Type.Tuple([SessionIdSchema, SummarySessionBranch(tChange)])),
+		},
+		noAdditionalProps,
+	);
+
+/* eslint-enable @typescript-eslint/explicit-function-return-type */

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

@@ -0,0 +1,35 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { type ObjectOptions, type TSchema, Type } from "@sinclair/typebox";
+import type { SessionId } from "@fluidframework/id-compressor";
+
+import { EncodedSharedBranch } from "./editManagerFormatCommons.js";
+import { SessionIdSchema } from "../core/index.js";
+
+const noAdditionalProps: ObjectOptions = { additionalProperties: false };
+
+// Many of the return types in this module are intentionally derived, rather than explicitly specified.
+/* eslint-disable @typescript-eslint/explicit-function-return-type */
+
+export interface EncodedEditManager<TChangeset> {
+	readonly version: 5;
+	readonly originator: SessionId;
+	readonly main: EncodedSharedBranch<TChangeset>;
+	readonly branches?: readonly EncodedSharedBranch<TChangeset>[];
+}
+
+export const EncodedEditManager = <ChangeSchema extends TSchema>(tChange: ChangeSchema) =>
+	Type.Object(
+		{
+			version: Type.Union([Type.Literal(5)]),
+			originator: SessionIdSchema,
+			main: EncodedSharedBranch(tChange),
+			branches: Type.Optional(Type.Array(EncodedSharedBranch(tChange))),
+		},
+		noAdditionalProps,
+	);
+
+/* eslint-enable @typescript-eslint/explicit-function-return-type */

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

@@ -8,6 +8,7 @@ export {
 	SharedTreeBranch,
 	type SharedTreeBranchChange,
 	type SharedTreeBranchEvents,
+	type BranchId,
 } from "./branch.js";
 
 export {
@@ -44,6 +45,7 @@ export {
 	EditManager,
 	minimumPossibleSequenceNumber,
 	type SummaryData,
+	type SharedBranchSummaryData,
 } from "./editManager.js";
 export type {
 	Commit,
@@ -51,4 +53,4 @@ export type {
 	SequencedCommit,
 	SummarySessionBranch,
 	EncodedCommit,
-} from "./editManagerFormat.js";
+} from "./editManagerFormatCommons.js";

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

@@ -0,0 +1,104 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { type TAnySchema, Type } from "@sinclair/typebox";
+import { assert } from "@fluidframework/core-utils/internal";
+
+import { type ICodecOptions, type IJsonCodec, withSchemaValidation } from "../codec/index.js";
+import type {
+	ChangeEncodingContext,
+	ChangeFamilyCodec,
+	EncodedRevisionTag,
+	RevisionTag,
+} from "../core/index.js";
+import type { JsonCompatibleReadOnly } from "../util/index.js";
+
+import { Message } from "./messageFormatV1ToV4.js";
+import type { DecodedMessage } from "./messageTypes.js";
+import type { MessageEncodingContext } from "./messageCodecs.js";
+
+export function makeV1ToV4CodecWithVersion<TChangeset>(
+	changeCodec: ChangeFamilyCodec<TChangeset>,
+	revisionTagCodec: IJsonCodec<
+		RevisionTag,
+		EncodedRevisionTag,
+		EncodedRevisionTag,
+		ChangeEncodingContext
+	>,
+	options: ICodecOptions,
+	version: 1 | 2 | 3 | 4,
+): IJsonCodec<
+	DecodedMessage<TChangeset>,
+	JsonCompatibleReadOnly,
+	JsonCompatibleReadOnly,
+	MessageEncodingContext
+> {
+	return withSchemaValidation<
+		DecodedMessage<TChangeset>,
+		TAnySchema,
+		JsonCompatibleReadOnly,
+		JsonCompatibleReadOnly,
+		MessageEncodingContext
+	>(
+		Message(changeCodec.encodedSchema ?? Type.Any()),
+		{
+			encode: (decoded: DecodedMessage<TChangeset>, context: MessageEncodingContext) => {
+				assert(decoded.type === "commit", 0xc68 /* Only commit messages are supported */);
+				assert(
+					decoded.branchId === "main",
+					0xc69 /* Only commit messages to main are supported */,
+				);
+				const { commit, sessionId: originatorId } = decoded;
+				const message: Message = {
+					revision: revisionTagCodec.encode(commit.revision, {
+						originatorId,
+						idCompressor: context.idCompressor,
+						revision: undefined,
+					}),
+					originatorId,
+					changeset: changeCodec.encode(commit.change, {
+						originatorId,
+						schema: context.schema,
+						idCompressor: context.idCompressor,
+						revision: commit.revision,
+					}),
+					version,
+				};
+				return message as unknown as JsonCompatibleReadOnly;
+			},
+			decode: (
+				encoded: JsonCompatibleReadOnly,
+				context: MessageEncodingContext,
+			): DecodedMessage<TChangeset> => {
+				const {
+					revision: encodedRevision,
+					originatorId,
+					changeset,
+				} = encoded as unknown as Message;
+
+				const revision = revisionTagCodec.decode(encodedRevision, {
+					originatorId,
+					revision: undefined,
+					idCompressor: context.idCompressor,
+				});
+
+				return {
+					branchId: "main",
+					type: "commit",
+					commit: {
+						revision,
+						change: changeCodec.decode(changeset, {
+							originatorId,
+							revision,
+							idCompressor: context.idCompressor,
+						}),
+					},
+					sessionId: originatorId,
+				};
+			},
+		},
+		options.jsonValidator,
+	);
+}

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

@@ -0,0 +1,131 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { type TAnySchema, Type } from "@sinclair/typebox";
+
+import { type ICodecOptions, type IJsonCodec, withSchemaValidation } from "../codec/index.js";
+import type {
+	ChangeEncodingContext,
+	ChangeFamilyCodec,
+	EncodedRevisionTag,
+	RevisionTag,
+} from "../core/index.js";
+import type { JsonCompatibleReadOnly } from "../util/index.js";
+
+import { Message } from "./messageFormatV5.js";
+import type { DecodedMessage } from "./messageTypes.js";
+import { assert, unreachableCase } from "@fluidframework/core-utils/internal";
+import type { MessageEncodingContext } from "./messageCodecs.js";
+import { decodeBranchId, encodeBranchId } from "./branchIdCodec.js";
+
+export function makeV5CodecWithVersion<TChangeset>(
+	changeCodec: ChangeFamilyCodec<TChangeset>,
+	revisionTagCodec: IJsonCodec<
+		RevisionTag,
+		EncodedRevisionTag,
+		EncodedRevisionTag,
+		ChangeEncodingContext
+	>,
+	options: ICodecOptions,
+	version: 5,
+): IJsonCodec<
+	DecodedMessage<TChangeset>,
+	JsonCompatibleReadOnly,
+	JsonCompatibleReadOnly,
+	MessageEncodingContext
+> {
+	return withSchemaValidation<
+		DecodedMessage<TChangeset>,
+		TAnySchema,
+		JsonCompatibleReadOnly,
+		JsonCompatibleReadOnly,
+		MessageEncodingContext
+	>(
+		Message(changeCodec.encodedSchema ?? Type.Any()),
+		{
+			encode: (
+				message: DecodedMessage<TChangeset>,
+				context: MessageEncodingContext,
+			): JsonCompatibleReadOnly => {
+				const type = message.type;
+				switch (type) {
+					case "commit": {
+						const changeContext: ChangeEncodingContext = {
+							originatorId: message.sessionId,
+							schema: context.schema,
+							idCompressor: context.idCompressor,
+							revision: message.commit.revision,
+						};
+
+						return {
+							revision: revisionTagCodec.encode(message.commit.revision, {
+								originatorId: message.sessionId,
+								idCompressor: context.idCompressor,
+								revision: undefined,
+							}),
+							originatorId: message.sessionId,
+							changeset: changeCodec.encode(message.commit.change, changeContext),
+							branchId: encodeBranchId(context.idCompressor, message.branchId),
+							version,
+						} satisfies Message & JsonCompatibleReadOnly;
+					}
+					case "branch": {
+						return {
+							originatorId: message.sessionId,
+							branchId: encodeBranchId(context.idCompressor, message.branchId),
+							version,
+						} satisfies Message & JsonCompatibleReadOnly;
+					}
+					default:
+						unreachableCase(type);
+				}
+			},
+			decode: (
+				encoded: JsonCompatibleReadOnly,
+				context: MessageEncodingContext,
+			): DecodedMessage<TChangeset> => {
+				const {
+					revision: encodedRevision,
+					originatorId,
+					changeset,
+					branchId: encodedBranchId,
+				} = encoded as unknown as Message;
+
+				const changeContext = {
+					originatorId,
+					revision: undefined,
+					idCompressor: context.idCompressor,
+				};
+
+				const branchId = decodeBranchId(context.idCompressor, encodedBranchId, changeContext);
+
+				if (changeset === undefined) {
+					return { type: "branch", sessionId: originatorId, branchId };
+				}
+
+				assert(
+					encodedRevision !== undefined,
+					0xc6a /* Commit messages must have a revision */,
+				);
+				const revision = revisionTagCodec.decode(encodedRevision, changeContext);
+
+				return {
+					type: "commit",
+					commit: {
+						revision,
+						change: changeCodec.decode(changeset, {
+							originatorId,
+							revision,
+							idCompressor: context.idCompressor,
+						}),
+					},
+					branchId,
+					sessionId: originatorId,
+				};
+			},
+		},
+		options.jsonValidator,
+	);
+}

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

@@ -3,28 +3,25 @@
  * Licensed under the MIT License.
  */
 
-import { type TAnySchema, Type } from "@sinclair/typebox";
-
 import {
 	type ICodecFamily,
 	type ICodecOptions,
 	type IJsonCodec,
 	makeCodecFamily,
 	makeVersionDispatchingCodec,
-	withSchemaValidation,
 } from "../codec/index.js";
 import type {
 	ChangeEncodingContext,
-	ChangeFamilyCodec,
 	EncodedRevisionTag,
 	RevisionTag,
 	SchemaAndPolicy,
 } from "../core/index.js";
 import type { JsonCompatibleReadOnly } from "../util/index.js";
 
-import { Message } from "./messageFormat.js";
 import type { DecodedMessage } from "./messageTypes.js";
 import type { IIdCompressor } from "@fluidframework/id-compressor";
+import { makeV1ToV4CodecWithVersion } from "./messageCodecV1ToV4.js";
+import { makeV5CodecWithVersion } from "./messageCodecV5.js";
 
 export interface MessageEncodingContext {
 	idCompressor: IIdCompressor;
@@ -64,7 +61,7 @@ export function makeMessageCodecs<TChangeset>(
 	>,
 	options: ICodecOptions,
 ): ICodecFamily<DecodedMessage<TChangeset>, MessageEncodingContext> {
-	const v1Codec = makeV1CodecWithVersion(
+	const v1Codec = makeV1ToV4CodecWithVersion(
 		changeCodecs.resolve(1).json,
 		revisionTagCodec,
 		options,
@@ -74,84 +71,18 @@ export function makeMessageCodecs<TChangeset>(
 		// Back-compat: messages weren't always written with an explicit version field.
 		[undefined, v1Codec],
 		[1, v1Codec],
-		[2, makeV1CodecWithVersion(changeCodecs.resolve(2).json, revisionTagCodec, options, 2)],
-		[3, makeV1CodecWithVersion(changeCodecs.resolve(3).json, revisionTagCodec, options, 3)],
-		[4, makeV1CodecWithVersion(changeCodecs.resolve(4).json, revisionTagCodec, options, 4)],
+		[
+			2,
+			makeV1ToV4CodecWithVersion(changeCodecs.resolve(2).json, revisionTagCodec, options, 2),
+		],
+		[
+			3,
+			makeV1ToV4CodecWithVersion(changeCodecs.resolve(3).json, revisionTagCodec, options, 3),
+		],
+		[
+			4,
+			makeV1ToV4CodecWithVersion(changeCodecs.resolve(4).json, revisionTagCodec, options, 4),
+		],
+		[5, makeV5CodecWithVersion(changeCodecs.resolve(4).json, revisionTagCodec, options, 5)],
 	]);
 }
-
-function makeV1CodecWithVersion<TChangeset>(
-	changeCodec: ChangeFamilyCodec<TChangeset>,
-	revisionTagCodec: IJsonCodec<
-		RevisionTag,
-		EncodedRevisionTag,
-		EncodedRevisionTag,
-		ChangeEncodingContext
-	>,
-	options: ICodecOptions,
-	version: 1 | 2 | 3 | 4,
-): IJsonCodec<
-	DecodedMessage<TChangeset>,
-	JsonCompatibleReadOnly,
-	JsonCompatibleReadOnly,
-	MessageEncodingContext
-> {
-	return withSchemaValidation<
-		DecodedMessage<TChangeset>,
-		TAnySchema,
-		JsonCompatibleReadOnly,
-		JsonCompatibleReadOnly,
-		MessageEncodingContext
-	>(
-		Message(changeCodec.encodedSchema ?? Type.Any()),
-		{
-			encode: (
-				{ commit, sessionId: originatorId }: DecodedMessage<TChangeset>,
-				context: MessageEncodingContext,
-			) => {
-				const message: Message = {
-					revision: revisionTagCodec.encode(commit.revision, {
-						originatorId,
-						idCompressor: context.idCompressor,
-						revision: undefined,
-					}),
-					originatorId,
-					changeset: changeCodec.encode(commit.change, {
-						originatorId,
-						schema: context.schema,
-						idCompressor: context.idCompressor,
-						revision: commit.revision,
-					}),
-					version,
-				};
-				return message as unknown as JsonCompatibleReadOnly;
-			},
-			decode: (encoded: JsonCompatibleReadOnly, context: MessageEncodingContext) => {
-				const {
-					revision: encodedRevision,
-					originatorId,
-					changeset,
-				} = encoded as unknown as Message;
-
-				const revision = revisionTagCodec.decode(encodedRevision, {
-					originatorId,
-					revision: undefined,
-					idCompressor: context.idCompressor,
-				});
-
-				return {
-					commit: {
-						revision,
-						change: changeCodec.decode(changeset, {
-							originatorId,
-							revision,
-							idCompressor: context.idCompressor,
-						}),
-					},
-					sessionId: originatorId,
-				};
-			},
-		},
-		options.jsonValidator,
-	);
-}

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

@@ -0,0 +1,50 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type { SessionId } from "@fluidframework/id-compressor";
+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";
+
+/**
+ * The format of messages that SharedTree sends and receives.
+ */
+export interface Message {
+	/**
+	 * The revision tag for the change in this message
+	 */
+	readonly revision?: EncodedRevisionTag;
+	/**
+	 * The stable ID that identifies the originator of the message.
+	 */
+	readonly originatorId: SessionId;
+	/**
+	 * The changeset to be applied.
+	 */
+	readonly changeset?: JsonCompatibleReadOnly;
+
+	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.
+	 */
+	readonly version?: number;
+}
+
+// Return type is intentionally derived.
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+export const Message = <ChangeSchema extends TSchema>(tChange: ChangeSchema) =>
+	Type.Object({
+		revision: Type.Optional(RevisionTagSchema),
+		originatorId: SessionIdSchema,
+		changeset: Type.Optional(tChange),
+		branchId: Type.Optional(Type.Number()),
+		version: Type.Optional(Type.Number()),
+	});

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

@@ -6,8 +6,21 @@
 import type { SessionId } from "@fluidframework/id-compressor";
 
 import type { GraphCommit } from "../core/index.js";
+import type { BranchId } from "./branch.js";
 
-export interface DecodedMessage<TChange> {
-	commit: GraphCommit<TChange>;
+export type DecodedMessage<TChange> = CommitMessage<TChange> | BranchMessage;
+
+export interface MessageBase {
 	sessionId: SessionId;
 }
+
+export interface CommitMessage<TChange> extends MessageBase {
+	type: "commit";
+	commit: GraphCommit<TChange>;
+	branchId: BranchId;
+}
+
+export interface BranchMessage extends MessageBase {
+	type: "branch";
+	branchId: BranchId;
+}

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

@@ -7,7 +7,7 @@ import { assert } from "@fluidframework/core-utils/internal";
 
 import { brand } from "../util/index.js";
 
-import type { SequenceId } from "./editManagerFormat.js";
+import type { SequenceId } from "./editManagerFormatCommons.js";
 
 /**
  * Compares two sequenceIds. Returns a negative number if a \< b, a positive number if a \> b, and 0 if a === b.