@fluid-experimental/tree 0.59.4002 → 1.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluid-experimental/tree",
-  "version": "0.59.4002",
+  "version": "1.0.2",
   "description": "Distributed tree",
   "homepage": "https://fluidframework.com",
   "repository": {
@@ -38,13 +38,13 @@
   "dependencies": {
     "@fluidframework/common-definitions": "^0.20.1",
     "@fluidframework/common-utils": "^0.32.1",
-    "@fluidframework/container-definitions": "^0.48.2000",
-    "@fluidframework/core-interfaces": "^0.43.1000",
-    "@fluidframework/datastore-definitions": "^0.59.4002",
+    "@fluidframework/container-definitions": "^1.0.2",
+    "@fluidframework/core-interfaces": "^1.0.2",
+    "@fluidframework/datastore-definitions": "^1.0.2",
     "@fluidframework/protocol-definitions": "^0.1028.2000",
-    "@fluidframework/runtime-definitions": "^0.59.4002",
-    "@fluidframework/shared-object-base": "^0.59.4002",
-    "@fluidframework/telemetry-utils": "^0.59.4002",
+    "@fluidframework/runtime-definitions": "^1.0.2",
+    "@fluidframework/shared-object-base": "^1.0.2",
+    "@fluidframework/telemetry-utils": "^1.0.2",
     "buffer": "^6.0.3",
     "denque": "^1.5.1",
     "lru-cache": "^6.0.0",
@@ -52,43 +52,30 @@
     "uuid": "^8.3.1"
   },
   "devDependencies": {
-    "@fluid-internal/stochastic-test-utils": "^0.59.4002",
-    "@fluid-tools/benchmark": "^0.41.67945",
+    "@fluid-internal/stochastic-test-utils": "^1.0.2",
+    "@fluid-tools/benchmark": "^0.40.0",
     "@fluidframework/build-common": "^0.23.0",
-    "@fluidframework/container-loader": "^0.59.4002",
-    "@fluidframework/container-runtime": "^0.59.4002",
+    "@fluidframework/container-loader": "^1.0.2",
+    "@fluidframework/container-runtime": "^1.0.2",
     "@fluidframework/eslint-config-fluid": "^0.28.2000",
-    "@fluidframework/mocha-test-setup": "^0.59.4002",
-    "@fluidframework/runtime-utils": "^0.59.4002",
-    "@fluidframework/test-driver-definitions": "^0.59.4002",
-    "@fluidframework/test-drivers": "^0.59.4002",
-    "@fluidframework/test-runtime-utils": "^0.59.4002",
-    "@fluidframework/test-utils": "^0.59.4002",
-    "@fluidframework/undo-redo": "^0.59.4002",
+    "@fluidframework/mocha-test-setup": "^1.0.2",
+    "@fluidframework/runtime-utils": "^1.0.2",
+    "@fluidframework/test-driver-definitions": "^1.0.2",
+    "@fluidframework/test-drivers": "^1.0.2",
+    "@fluidframework/test-runtime-utils": "^1.0.2",
+    "@fluidframework/test-utils": "^1.0.2",
+    "@fluidframework/undo-redo": "^1.0.2",
     "@microsoft/api-extractor": "^7.22.2",
     "@rushstack/eslint-config": "^2.5.1",
     "@types/lru-cache": "^5.1.0",
     "@types/mocha": "^9.1.1",
     "@types/random-js": "^1.0.31",
-    "@typescript-eslint/eslint-plugin": "~5.9.0",
-    "@typescript-eslint/parser": "~5.9.0",
     "chai": "^4.2.0",
     "concurrently": "^6.2.0",
     "cross-env": "^7.0.2",
     "easy-table": "^1.1.1",
     "env-cmd": "^10.1.0",
     "eslint": "~8.6.0",
-    "eslint-plugin-editorconfig": "~3.2.0",
-    "eslint-plugin-eslint-comments": "~3.2.0",
-    "eslint-plugin-import": "~2.25.4",
-    "eslint-plugin-jest": "~26.1.3",
-    "eslint-plugin-jsdoc": "~39.3.0",
-    "eslint-plugin-mocha": "~10.0.3",
-    "eslint-plugin-promise": "~6.0.0",
-    "eslint-plugin-react": "~7.28.0",
-    "eslint-plugin-tsdoc": "~0.2.14",
-    "eslint-plugin-unicorn": "~40.0.0",
-    "eslint-plugin-unused-imports": "~2.0.0",
     "mocha": "^10.0.0",
     "nyc": "^15.0.0",
     "prettier": "^2.3.1",

package/src/SharedTree.ts

@@ -27,7 +27,15 @@ import { ChildLogger, ITelemetryLoggerPropertyBags, PerformanceEvent } from '@fl
 import { ISummaryTreeWithStats } from '@fluidframework/runtime-definitions';
 import { assert, assertNotUndefined, fail, copyPropertyIfDefined, noop } from './Common';
 import { EditHandle, EditLog, getNumberOfHandlesFromEditLogSummary, OrderedEditSet } from './EditLog';
-import { EditId, NodeId, StableNodeId, DetachedSequenceId, OpSpaceNodeId, isDetachedSequenceId } from './Identifiers';
+import {
+	EditId,
+	NodeId,
+	StableNodeId,
+	DetachedSequenceId,
+	OpSpaceNodeId,
+	isDetachedSequenceId,
+	AttributionId,
+} from './Identifiers';
 import { initialTree } from './InitialTree';
 import {
 	CachingLogViewer,
@@ -88,6 +96,75 @@ import { TransactionInternal } from './TransactionInternal';
 import { IdCompressor, createSessionId } from './id-compressor';
 import { convertEditIds } from './IdConversion';
 import { MutableStringInterner } from './StringInterner';
+import { nilUuid } from './UuidUtilities';
+
+/**
+ * The write format and associated options used to construct a `SharedTree`
+ * @public
+ */
+export type SharedTreeArgs<WF extends WriteFormat = WriteFormat> = [writeFormat: WF, options?: SharedTreeOptions<WF>];
+
+/**
+ * The type of shared tree options for a given write format
+ * @public
+ */
+export type SharedTreeOptions<
+	WF extends WriteFormat,
+	HistoryCompatibility extends 'Forwards' | 'None' = 'Forwards'
+> = Omit<
+	WF extends WriteFormat.v0_0_2
+		? SharedTreeOptions_0_0_2
+		: WF extends WriteFormat.v0_1_1
+		? SharedTreeOptions_0_1_1
+		: never,
+	HistoryCompatibility extends 'Forwards' ? 'summarizeHistory' : never
+>;
+
+/**
+ * Configuration options for a SharedTree with write format 0.0.2
+ * @public
+ */
+export interface SharedTreeOptions_0_0_2 {
+	/**
+	 * Determines if the history is included in summaries.
+	 *
+	 * Warning: enabling history summarization incurs a permanent cost in the document. It is not possible to disable history summarization
+	 * later once it has been enabled, and thus the history cannot be safely deleted.
+	 *
+	 * On 0.1.1 documents, due to current code limitations, this parameter is only impactful for newly created documents.
+	 * `SharedTree`s which load existing documents will summarize history if and only if the loaded summary included history.
+	 *
+	 * The technical limitations here relate to clients with mixed versions collaborating.
+	 * In the future we may allow modification of whether or not a particular document saves history, but only via a consensus mechanism.
+	 * See the skipped test in SharedTreeFuzzTests.ts for more details on this issue.
+	 * See docs/Breaking-Change-Migration for more details on the consensus scheme.
+	 */
+	summarizeHistory?: boolean;
+}
+
+/**
+ * Configuration options for a SharedTree with write format 0.1.1
+ * @public
+ */
+export interface SharedTreeOptions_0_1_1 {
+	/**
+	 * Determines if the history is included in summaries and if edit chunks are uploaded when they are full.
+	 *
+	 * Warning: enabling history summarization incurs a permanent cost in the document. It is not possible to disable history summarization
+	 * later once it has been enabled, and thus the history cannot be safely deleted.
+	 *
+	 * On 0.1.1 documents, due to current code limitations, this parameter is only impactful for newly created documents.
+	 * `SharedTree`s which load existing documents will summarize history if and only if the loaded summary included history.
+	 *
+	 * The technical limitations here relate to clients with mixed versions collaborating.
+	 * In the future we may allow modification of whether or not a particular document saves history, but only via a consensus mechanism.
+	 * See the skipped test in SharedTreeFuzzTests.ts for more details on this issue.
+	 * See docs/Breaking-Change-Migration for more details on the consensus scheme.
+	 */
+	summarizeHistory?: false | { uploadEditChunks: boolean };
+	/** a UUID that identifies the user of this tree; all node IDs generated by this tree will be associated with this UUID */
+	attributionId?: AttributionId;
+}
 
 /**
  * Factory for SharedTree.
@@ -109,20 +186,20 @@ export class SharedTreeFactory implements IChannelFactory {
 		packageVersion: '0.1',
 	};
 
+	private readonly args: SharedTreeArgs;
+
 	/**
 	 * Get a factory for SharedTree to register with the data store.
 	 * @param writeFormat - Determines the format version the SharedTree will write ops and summaries in. See [the write format
 	 * documentation](../docs/Write-Format.md) for more information.
-	 * @param summarizeHistory - Determines if the history is included in summaries and if edit chunks are uploaded when they are full.
-	 * See the [breaking change migration documentation](docs/Breaking-Change-Migration) for more details on this scheme.
-	 * @param expensiveValidation - Enables expensive asserts on SharedTree.
+	 * @param options - Configuration options for this tree
 	 * @returns A factory that creates `SharedTree`s and loads them from storage.
 	 */
-	constructor(
-		private readonly writeFormat: WriteFormat,
-		private readonly summarizeHistory: false | { uploadEditChunks: boolean } = false,
-		private expensiveValidation = false
-	) {}
+	constructor(...args: SharedTreeArgs<WriteFormat.v0_0_2>);
+	constructor(...args: SharedTreeArgs<WriteFormat.v0_1_1>);
+	constructor(...args: SharedTreeArgs) {
+		this.args = args;
+	}
 
 	/**
 	 * {@inheritDoc @fluidframework/shared-object-base#ISharedObjectFactory."type"}
@@ -157,22 +234,22 @@ export class SharedTreeFactory implements IChannelFactory {
 	 * @param runtime - data store runtime that owns the new SharedTree
 	 * @param id - optional name for the SharedTree
 	 */
-	public create(runtime: IFluidDataStoreRuntime, id: string, expensiveValidation: boolean = false): SharedTree {
-		this.expensiveValidation = expensiveValidation;
+	public create(runtime: IFluidDataStoreRuntime, id: string): SharedTree {
 		const sharedTree = this.createSharedTree(runtime, id);
 		sharedTree.initializeLocal();
 		return sharedTree;
 	}
 
 	private createSharedTree(runtime: IFluidDataStoreRuntime, id: string): SharedTree {
-		const sharedTree = new SharedTree(
-			runtime,
-			id,
-			this.writeFormat,
-			this.summarizeHistory,
-			this.expensiveValidation
-		);
-		return sharedTree;
+		const [writeFormat] = this.args;
+		switch (writeFormat) {
+			case WriteFormat.v0_0_2:
+				return new SharedTree(runtime, id, ...(this.args as SharedTreeArgs<WriteFormat.v0_0_2>));
+			case WriteFormat.v0_1_1:
+				return new SharedTree(runtime, id, ...(this.args as SharedTreeArgs<WriteFormat.v0_1_1>));
+			default:
+				fail('Unknown write format');
+		}
 	}
 }
 
@@ -281,35 +358,56 @@ export class SharedTree extends SharedObject<ISharedTreeEvents> implements NodeI
 
 	/**
 	 * Get a factory for SharedTree to register with the data store.
-	 * @param summarizeHistory - Determines if the history is included in summaries and if edit chunks are uploaded when they are full.
-	 *
-	 * On 0.1.1 documents, due to current code limitations, this parameter is only impactful for newly created documents.
-	 * `SharedTree`s which load existing documents will summarize history if and only if the loaded summary included history.
-	 *
-	 * The technical limitations here relate to clients with mixed versions collaborating.
-	 * In the future we may allow modification of whether or not a particular document saves history, but only via a consensus mechanism.
-	 * See the skipped test in SharedTreeFuzzTests.ts for more details on this issue.
-	 * See docs/Breaking-Change-Migration for more details on the consensus scheme.
 	 * @param writeFormat - Determines the format version the SharedTree will write ops and summaries in.
 	 * This format may be updated to a newer (supported) version at runtime if a collaborating shared-tree
 	 * that was initialized with a newer write version connects to the session. Care must be taken when changing this value,
 	 * as a staged rollout must of occurred such that all collaborating clients must have the code to read at least the version
 	 * written.
 	 * See [the write format documentation](../docs/Write-Format.md) for more information.
+	 * @param options - Configuration options for this tree
 	 * @returns A factory that creates `SharedTree`s and loads them from storage.
 	 */
-	public static getFactory(
-		writeFormat: WriteFormat,
-		summarizeHistory: false | { uploadEditChunks: boolean } = false
-	): SharedTreeFactory {
+	public static getFactory(...args: SharedTreeArgs<WriteFormat.v0_0_2>): SharedTreeFactory;
+
+	public static getFactory(...args: SharedTreeArgs<WriteFormat.v0_1_1>): SharedTreeFactory;
+
+	public static getFactory(...args: SharedTreeArgs): SharedTreeFactory {
+		const [writeFormat] = args;
 		// 	On 0.1.1 documents, due to current code limitations, all clients MUST agree on the value of `summarizeHistory`.
 		//  Note that this means staged rollout changing this value should not be attempted.
 		//  It is possible to update shared-tree to correctly handle such a staged rollout, but that hasn't been implemented.
 		//  See the skipped test in SharedTreeFuzzTests.ts for more details on this issue.
-		return new SharedTreeFactory(writeFormat, summarizeHistory);
+		switch (writeFormat) {
+			case WriteFormat.v0_0_2:
+				return new SharedTreeFactory(...(args as SharedTreeArgs<WriteFormat.v0_0_2>));
+			case WriteFormat.v0_1_1:
+				return new SharedTreeFactory(...(args as SharedTreeArgs<WriteFormat.v0_1_1>));
+			default:
+				fail('Unknown write format');
+		}
 	}
 
-	private idCompressor: IdCompressor = new IdCompressor(createSessionId(), reservedIdCount);
+	/**
+	 * The UUID used for attribution of nodes created by this SharedTree. All shared trees with a write format of 0.1.1 or
+	 * greater have a unique attribution ID which may be configured in the constructor. All other shared trees (i.e. those
+	 * with a write format of 0.0.2) use the nil UUID as their attribution ID.
+	 * @public
+	 */
+	public get attributionId(): AttributionId {
+		switch (this.writeFormat) {
+			case WriteFormat.v0_0_2:
+				return nilUuid;
+			default: {
+				const { attributionId } = this.idCompressor;
+				if (attributionId === ghostSessionId) {
+					return nilUuid;
+				}
+				return attributionId;
+			}
+		}
+	}
+
+	private idCompressor: IdCompressor;
 	private readonly idNormalizer: NodeIdNormalizer<OpSpaceNodeId> & { tree: SharedTree } = {
 		tree: this,
 		get localSessionId() {
@@ -375,25 +473,46 @@ export class SharedTree extends SharedObject<ISharedTreeEvents> implements NodeI
 	private summarizeHistory: boolean;
 	private uploadEditChunks: boolean;
 
+	private getHistoryPolicy(options: SharedTreeOptions<WriteFormat, 'Forwards' | 'None'>): {
+		summarizeHistory: boolean;
+		uploadEditChunks: boolean;
+	} {
+		const noCompatOptions = options as SharedTreeOptions<WriteFormat, 'None'>;
+		if (typeof noCompatOptions.summarizeHistory === 'object') {
+			return {
+				summarizeHistory: true,
+				uploadEditChunks: noCompatOptions.summarizeHistory.uploadEditChunks,
+			};
+		} else {
+			return {
+				summarizeHistory: noCompatOptions.summarizeHistory ?? false,
+				uploadEditChunks: false,
+			};
+		}
+	}
+
 	/**
-	 * Create a new SharedTreeFactory.
+	 * Create a new SharedTree.
 	 * @param runtime - The runtime the SharedTree will be associated with
 	 * @param id - Unique ID for the SharedTree
 	 * @param writeFormat - Determines the format version the SharedTree will write ops and summaries in. See [the write format
 	 * documentation](../docs/Write-Format.md) for more information.
-	 * @param summarizeHistory - Determines if the history is included in summaries and if edit chunks are uploaded when they are full.
-	 * @param expensiveValidation - Enable expensive asserts.
+	 * @param options - Configuration options for this tree
 	 */
+	public constructor(runtime: IFluidDataStoreRuntime, id: string, ...args: SharedTreeArgs<WriteFormat.v0_0_2>);
+
+	public constructor(runtime: IFluidDataStoreRuntime, id: string, ...args: SharedTreeArgs<WriteFormat.v0_1_1>);
+
 	public constructor(
 		runtime: IFluidDataStoreRuntime,
 		id: string,
 		private writeFormat: WriteFormat,
-		summarizeHistory: false | { uploadEditChunks: boolean } = false,
-		private readonly expensiveValidation = false
+		options: SharedTreeOptions<typeof writeFormat> = {}
 	) {
-		super(id, runtime, SharedTreeFactory.Attributes);
-		this.summarizeHistory = summarizeHistory === false ? false : true;
-		this.uploadEditChunks = summarizeHistory === false ? false : summarizeHistory.uploadEditChunks;
+		super(id, runtime, SharedTreeFactory.Attributes, 'fluid_sharedTree_');
+		const historyPolicy = this.getHistoryPolicy(options);
+		this.summarizeHistory = historyPolicy.summarizeHistory;
+		this.uploadEditChunks = historyPolicy.uploadEditChunks;
 
 		// This code is somewhat duplicated from OldestClientObserver because it currently depends on the container runtime
 		// which SharedTree does not have access to.
@@ -412,13 +531,15 @@ export class SharedTree extends SharedObject<ISharedTreeEvents> implements NodeI
 			sharedTreeTelemetryProperties
 		);
 
+		const attributionId = (options as SharedTreeOptions<WriteFormat.v0_1_1>).attributionId;
+		this.idCompressor = new IdCompressor(createSessionId(), reservedIdCount, attributionId);
 		const { editLog, cachingLogViewer } = this.initializeNewEditLogFromSummary(
 			{
 				editChunks: [],
 				editIds: [],
 			},
 			undefined,
-			this.idCompressor, // TODO: Attribution info
+			this.idCompressor,
 			this.processEditResult,
 			this.processSequencedEditResult,
 			WriteFormat.v0_1_1
@@ -429,6 +550,11 @@ export class SharedTree extends SharedObject<ISharedTreeEvents> implements NodeI
 		this.encoder_0_1_1 = new SharedTreeEncoder_0_1_1(this.summarizeHistory);
 	}
 
+	/**
+	 * The write format version currently used by this `SharedTree`. This is always initialized to the write format
+	 * passed to the tree's constructor, but it may automatically upgrade over time (e.g. when connected to another
+	 * SharedTree with a higher write format, or when loading a summary with a higher write format).
+	 */
 	public getWriteFormat(): WriteFormat {
 		return this.writeFormat;
 	}
@@ -555,6 +681,26 @@ export class SharedTree extends SharedObject<ISharedTreeEvents> implements NodeI
 		return this.idCompressor.tryRecompress(id) as NodeId | undefined;
 	}
 
+	/**
+	 * Returns the attribution ID associated with the SharedTree that generated the given node ID. This is generally only useful for clients
+	 * with a write format of 0.1.1 or greater since older clients cannot be given an attribution ID and will always use the default
+	 * `attributionId` of the tree.
+	 * @public
+	 */
+	public attributeNodeId(id: NodeId): AttributionId {
+		switch (this.writeFormat) {
+			case WriteFormat.v0_0_2:
+				return nilUuid;
+			default: {
+				const attributionId = this.idCompressor.attributeId(id);
+				if (attributionId === ghostSessionId) {
+					return nilUuid;
+				}
+				return attributionId;
+			}
+		}
+	}
+
 	/**
 	 * @returns the edit history of the tree.
 	 * @public
@@ -744,7 +890,10 @@ export class SharedTree extends SharedObject<ISharedTreeEvents> implements NodeI
 		let convertedSummary: SummaryContents;
 		switch (loadedSummaryVersion) {
 			case WriteFormat.v0_0_2:
-				convertedSummary = this.encoder_0_0_2.decodeSummary(summary as SharedTreeSummary_0_0_2);
+				convertedSummary = this.encoder_0_0_2.decodeSummary(
+					summary as SharedTreeSummary_0_0_2,
+					this.attributionId
+				);
 				break;
 			case WriteFormat.v0_1_1: {
 				const typedSummary = summary as SharedTreeSummary;
@@ -756,7 +905,7 @@ export class SharedTree extends SharedObject<ISharedTreeEvents> implements NodeI
 					this.encoder_0_1_1 = new SharedTreeEncoder_0_1_1(this.summarizeHistory);
 				}
 
-				convertedSummary = this.encoder_0_1_1.decodeSummary(summary as SharedTreeSummary); // TODO:#461: pass attribution info
+				convertedSummary = this.encoder_0_1_1.decodeSummary(summary as SharedTreeSummary, this.attributionId);
 				break;
 			}
 			default:
@@ -1115,7 +1264,7 @@ export class SharedTree extends SharedObject<ISharedTreeEvents> implements NodeI
 		this.interner = new MutableStringInterner([initialTree.definition]);
 		const oldIdCompressor = this.idCompressor;
 		// Create the IdCompressor that will be used after the upgrade
-		const newIdCompressor = new IdCompressor(createSessionId(), reservedIdCount); // TODO: attribution info
+		const newIdCompressor = new IdCompressor(createSessionId(), reservedIdCount, this.attributionId);
 		const newContext = getNodeIdContext(newIdCompressor);
 		// Generate all local IDs in the new compressor that were in the old compressor and preserve their UUIDs.
 		// This will allow the client to continue to use local IDs that were allocated pre-upgrade
@@ -1130,7 +1279,7 @@ export class SharedTree extends SharedObject<ISharedTreeEvents> implements NodeI
 			}
 		};
 		// Construct a temporary "ghost" compressor which is used to generate final IDs that will be consistent across all upgrading clients
-		const ghostIdCompressor = new IdCompressor(ghostSessionId, reservedIdCount); // TODO: attribution info
+		const ghostIdCompressor = new IdCompressor(ghostSessionId, reservedIdCount);
 		const ghostContext = getNodeIdContext(ghostIdCompressor);
 		if (this.summarizeHistory) {
 			// All clients have the full history, and can therefore all "generate" the same final IDs for every ID in the history

package/src/SharedTreeEncoder.ts

@@ -159,7 +159,7 @@ export class SharedTreeEncoder_0_1_1 {
 			idCompressor: serializedIdCompressor,
 			version,
 		}: SharedTreeSummary,
-		attributionId?: AttributionId
+		attributionId: AttributionId
 	): SummaryContents {
 		assert(version === WriteFormat.v0_1_1, `Invalid summary version to decode: ${version}, expected: 0.1.1`);
 		assert(typeof editHistory === 'object', '0.1.1 summary encountered with non-object edit history.');

package/src/index.ts

@@ -91,6 +91,10 @@ export {
 	TraitLocationInternal,
 } from './persisted-types';
 export {
+	SharedTreeArgs,
+	SharedTreeOptions,
+	SharedTreeOptions_0_0_2,
+	SharedTreeOptions_0_1_1,
 	SharedTreeFactory,
 	SharedTree,
 	EditCommittedHandler,