@fluidframework/fluid-static 2.50.0-345060 → 2.51.0-347100

package/src/treeRootDataObject.ts

@@ -0,0 +1,249 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import {
+	BaseContainerRuntimeFactory,
+	TreeDataObject,
+	TreeDataObjectFactory,
+} from "@fluidframework/aqueduct/internal";
+import type { IDataObjectProps } from "@fluidframework/aqueduct/internal";
+import type { IRuntimeFactory } from "@fluidframework/container-definitions/internal";
+import {
+	FluidDataStoreRegistry,
+	type IContainerRuntimeOptions,
+	type MinimumVersionForCollab,
+} from "@fluidframework/container-runtime/internal";
+import type {
+	IContainerRuntime,
+	IContainerRuntimeInternal,
+} from "@fluidframework/container-runtime-definitions/internal";
+import type {
+	FluidObject,
+	IFluidHandle,
+	IFluidLoadable,
+} from "@fluidframework/core-interfaces";
+import { assert } from "@fluidframework/core-utils/internal";
+import type { IChannelFactory } from "@fluidframework/datastore-definitions/internal";
+import type { IFluidDataStoreRegistry } from "@fluidframework/runtime-definitions/internal";
+import type { SharedObjectKind } from "@fluidframework/shared-object-base/internal";
+
+import { compatibilityModeRuntimeOptions } from "./compatibilityConfiguration.js";
+import type {
+	CompatibilityMode,
+	IRootDataObject,
+	IStaticEntryPoint,
+	LoadableObjectKind,
+	LoadableObjectRecord,
+	TreeContainerSchema,
+} from "./types.js";
+import {
+	compatibilityModeToMinVersionForCollab,
+	createDataObject,
+	createSharedObject,
+	isDataObjectKind,
+	isSharedObjectKind,
+	makeFluidObject,
+	parseDataObjectsFromSharedObjects,
+} from "./utils.js";
+
+/**
+ * This module contains types and factories for creating tree-based root data objects.
+ * They exist as an alternative to the APIs in `rootDataObject.ts`.
+ *
+ * These APIs are currently shaped to parallel `RootDataObject`, but this is not intended as the long-term design.
+ * The current shape is a short-term solution to allow for easier migration from the old APIs.
+ */
+
+/**
+ * The entry-point/root collaborative object of the {@link IFluidContainer | Fluid Container}.
+ *
+ * @remarks
+ * Abstracts the dynamic code required to build a Fluid Container into a static representation for end customers.
+ */
+class TreeRootDataObject extends TreeDataObject implements IRootDataObject {
+	public constructor(props: IDataObjectProps) {
+		super(props);
+	}
+
+	public get TreeRootDataObject(): TreeRootDataObject {
+		return this;
+	}
+
+	// TODO: longer term, it would be better to not have to fit into the `initialObjects` model for tree-based containers.
+	// But in the short term, fitting into this model makes migration easier.
+	public get initialObjects(): LoadableObjectRecord {
+		return {
+			tree: this.tree,
+		};
+	}
+
+	public async create<T>(objectClass: SharedObjectKind<T>): Promise<T> {
+		const internal = objectClass as unknown as LoadableObjectKind<T & IFluidLoadable>;
+		if (isDataObjectKind(internal)) {
+			return createDataObject(internal, this.context);
+		} else if (isSharedObjectKind(internal)) {
+			return createSharedObject(internal, this.runtime);
+		}
+		throw new Error("Could not create new Fluid object because an unknown object was passed");
+	}
+
+	public async uploadBlob(blob: ArrayBufferLike): Promise<IFluidHandle<ArrayBufferLike>> {
+		return this.runtime.uploadBlob(blob);
+	}
+}
+
+const treeRootDataStoreId = "treeRootDOId";
+
+/**
+ * Type of the {@link TreeRootDataObject}.
+ * @remarks Used in the PureDataObjectFactory to create the root data object.
+ */
+const treeRootDataObjectType = "treeRootDO";
+
+async function provideEntryPoint(
+	containerRuntime: IContainerRuntime,
+): Promise<IStaticEntryPoint> {
+	const entryPoint = await containerRuntime.getAliasedDataStoreEntryPoint(treeRootDataStoreId);
+	if (entryPoint === undefined) {
+		throw new Error(`default dataStore [${treeRootDataStoreId}] must exist`);
+	}
+	const treeRootDataObject = ((await entryPoint.get()) as FluidObject<TreeRootDataObject>)
+		.TreeRootDataObject;
+	assert(treeRootDataObject !== undefined, "entryPoint must be of type TreeRootDataObject");
+	return makeFluidObject<IStaticEntryPoint>(
+		{
+			rootDataObject: treeRootDataObject,
+			extensionStore: containerRuntime as IContainerRuntimeInternal,
+		},
+		"IStaticEntryPoint",
+	);
+}
+
+/**
+ * Factory for Container Runtime instances that provide a {@link IStaticEntryPoint}
+ * (containing single {@link IRootDataObject}) as their entry point.
+ */
+class TreeContainerRuntimeFactory extends BaseContainerRuntimeFactory {
+	// TODO: use for runtime factory.
+	readonly #treeRootDataObjectFactory: TreeDataObjectFactory<TreeRootDataObject>;
+
+	public constructor(
+		compatibilityMode: CompatibilityMode,
+		treeRootDataObjectFactory: TreeDataObjectFactory<TreeRootDataObject>,
+		overrides?: Partial<{
+			runtimeOptions: Partial<IContainerRuntimeOptions>;
+			minVersionForCollab: MinimumVersionForCollab;
+		}>,
+	) {
+		super({
+			registryEntries: [treeRootDataObjectFactory.registryEntry],
+			runtimeOptions: {
+				...compatibilityModeRuntimeOptions[compatibilityMode],
+				...overrides?.runtimeOptions,
+			},
+			provideEntryPoint,
+			minVersionForCollab:
+				overrides?.minVersionForCollab ??
+				compatibilityModeToMinVersionForCollab[compatibilityMode],
+		});
+		this.#treeRootDataObjectFactory = treeRootDataObjectFactory;
+	}
+
+	protected async containerInitializingFirstTime(runtime: IContainerRuntime): Promise<void> {
+		// The first time we create the container we create the RootDataObject
+		await this.#treeRootDataObjectFactory.createRootInstance(treeRootDataStoreId, runtime);
+	}
+}
+
+/**
+ * Factory that creates instances of a tree-based root data object.
+ */
+class TreeRootDataObjectFactory extends TreeDataObjectFactory<TreeRootDataObject> {
+	public constructor(
+		sharedObjects: readonly IChannelFactory[] = [],
+		private readonly dataStoreRegistry: IFluidDataStoreRegistry,
+	) {
+		type Ctor = new (props: IDataObjectProps) => TreeRootDataObject;
+		const ctor: Ctor = function (_props) {
+			// eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+			return new TreeRootDataObject({
+				..._props,
+				// Add any additional injected properties here
+			});
+		} as unknown as Ctor;
+
+		// Note: we're not specifying registry entries to the base class, so it won't create a registry itself,
+		// and instead we override the necessary methods in this class to use the registry received in the constructor.
+		super({
+			type: treeRootDataObjectType,
+			ctor,
+			sharedObjects,
+		});
+	}
+
+	public get IFluidDataStoreRegistry(): IFluidDataStoreRegistry {
+		return this.dataStoreRegistry;
+	}
+}
+
+/**
+ * Creates an {@link @fluidframework/aqueduct#IRuntimeFactory} which constructs containers
+ * with an entry point containing single tree-based root data object.
+ *
+ * @remarks
+ * The entry point is opaque to caller.
+ * The root data object's registry and shared objects are configured based on the provided
+ * SharedTree and optionally data store registry.
+ *
+ * @legacy @alpha
+ */
+export function createTreeContainerRuntimeFactory(props: {
+	/**
+	 * The schema for the container.
+	 */
+	readonly schema: TreeContainerSchema;
+
+	/**
+	 * See {@link CompatibilityMode} and compatibilityModeRuntimeOptions for more details.
+	 */
+	readonly compatibilityMode: CompatibilityMode;
+	/**
+	 * Optional registry of data stores to pass to the DataObject factory.
+	 * If not provided, one will be created based on the schema.
+	 */
+	readonly rootDataStoreRegistry?: IFluidDataStoreRegistry;
+	/**
+	 * Optional overrides for the container runtime options.
+	 * If not provided, only the default options for the given compatibilityMode will be used.
+	 */
+	readonly runtimeOptionOverrides?: Partial<IContainerRuntimeOptions>;
+	/**
+	 * Optional override for minimum version for collab.
+	 * If not provided, the default for the given compatibilityMode will be used.
+	 * @remarks
+	 * This is useful when runtime options are overridden and change the minimum version for collab.
+	 */
+	readonly minVersionForCollabOverride?: MinimumVersionForCollab;
+}): IRuntimeFactory {
+	const {
+		compatibilityMode,
+		minVersionForCollabOverride,
+		rootDataStoreRegistry,
+		runtimeOptionOverrides,
+		schema,
+	} = props;
+
+	const [registryEntries, sharedObjects] = parseDataObjectsFromSharedObjects(schema);
+	const registry = rootDataStoreRegistry ?? new FluidDataStoreRegistry(registryEntries);
+
+	return new TreeContainerRuntimeFactory(
+		compatibilityMode,
+		new TreeRootDataObjectFactory(sharedObjects, registry),
+		{
+			runtimeOptions: runtimeOptionOverrides,
+			minVersionForCollab: minVersionForCollabOverride,
+		},
+	);
+}

package/src/types.ts

@@ -11,8 +11,11 @@ import type {
 	IFluidHandle,
 	IFluidLoadable,
 } from "@fluidframework/core-interfaces";
-import type { SharedObjectKind } from "@fluidframework/shared-object-base";
-import type { ISharedObjectKind } from "@fluidframework/shared-object-base/internal";
+import type {
+	ISharedObjectKind,
+	SharedObjectKind,
+} from "@fluidframework/shared-object-base/internal";
+import type { ITree } from "@fluidframework/tree";
 
 /**
  * Determines the set of runtime options that Fluid Framework will use when running.
@@ -100,15 +103,28 @@ export interface ContainerSchema {
 }
 
 /**
- * Holds the collection of objects that the container was initially created with, as well as provides the ability
- * to dynamically create further objects during usage.
+ * Declares the Fluid objects that will be available in the {@link IFluidContainer | Container}.
+ *
+ * @remarks
+ *
+ * It includes both the kind of `SharedTree` that will be initially available upon `Container` creation, as well
+ * as the types of objects that may be dynamically created throughout the lifetime of the `Container`.
+ *
+ * @legacy @alpha
  */
-export interface IRootDataObject {
-	/**
-	 * Provides a record of the initial objects defined on creation.
-	 */
-	readonly initialObjects: LoadableObjectRecord;
+export interface TreeContainerSchema extends ContainerSchema {
+	// TODO: longer term, it would be better to not have to fit into the `initialObjects` model for tree-based containers.
+	// But in the short term, fitting into this model makes migration easier.
+	readonly initialObjects: {
+		readonly tree: SharedObjectKind<ITree>;
+	};
+}
 
+/**
+ * Holds the collection of objects that the container was initially created with.
+ * Additionally provides the ability to dynamically create further objects during usage.
+ */
+export interface IRootDataObject {
 	/**
 	 * Dynamically creates a new detached collaborative object (DDS/DataObject).
 	 *
@@ -127,6 +143,11 @@ export interface IRootDataObject {
 	 * @remarks This method is used to expose uploadBlob to the IFluidContainer level. UploadBlob will upload data to server side (as of now, ODSP only). There is no downloadBlob provided as it is not needed(blob lifetime managed by server).
 	 */
 	uploadBlob(blob: ArrayBufferLike): Promise<IFluidHandle<ArrayBufferLike>>;
+
+	/**
+	 * Provides a record of the initial objects defined on creation.
+	 */
+	readonly initialObjects: LoadableObjectRecord;
 }
 
 interface IProvideStaticEntryPoint {

package/src/utils.ts

@@ -4,13 +4,27 @@
  */
 
 import type { DataObjectKind } from "@fluidframework/aqueduct/internal";
-import type { IFluidLoadable } from "@fluidframework/core-interfaces";
-import type { IChannelFactory } from "@fluidframework/datastore-definitions/internal";
-import type { NamedFluidDataStoreRegistryEntry } from "@fluidframework/runtime-definitions/internal";
+import type { MinimumVersionForCollab } from "@fluidframework/container-runtime/internal";
+import type { FluidObjectKeys, IFluidLoadable } from "@fluidframework/core-interfaces";
+import { oob } from "@fluidframework/core-utils/internal";
+import type {
+	IChannelFactory,
+	IFluidDataStoreRuntime,
+} from "@fluidframework/datastore-definitions/internal";
+import type {
+	IFluidDataStoreContext,
+	NamedFluidDataStoreRegistryEntry,
+} from "@fluidframework/runtime-definitions/internal";
 import type { ISharedObjectKind } from "@fluidframework/shared-object-base/internal";
 import { UsageError } from "@fluidframework/telemetry-utils/internal";
+import { SharedTreeFactoryType } from "@fluidframework/tree/internal";
 
-import type { ContainerSchema, LoadableObjectKind } from "./types.js";
+import type {
+	CompatibilityMode,
+	ContainerSchema,
+	LoadableObjectKind,
+	TreeContainerSchema,
+} from "./types.js";
 
 /**
  * Runtime check to determine if an object is a {@link DataObjectKind}.
@@ -94,3 +108,75 @@ export const parseDataObjectsFromSharedObjects = (
 
 	return [[...registryEntries], [...sharedObjects]];
 };
+
+/**
+ * Creates a new data object of the specified type.
+ */
+export async function createDataObject<T extends IFluidLoadable>(
+	dataObjectClass: DataObjectKind<T>,
+	context: IFluidDataStoreContext,
+): Promise<T> {
+	const factory = dataObjectClass.factory;
+	const packagePath = [...context.packagePath, factory.type];
+	const dataStore = await context.containerRuntime.createDataStore(packagePath);
+	const entryPoint = await dataStore.entryPoint.get();
+	return entryPoint as T;
+}
+
+/**
+ * Creates a new shared object of the specified type.
+ */
+export function createSharedObject<T extends IFluidLoadable>(
+	sharedObjectClass: ISharedObjectKind<T>,
+	runtime: IFluidDataStoreRuntime,
+): T {
+	const factory = sharedObjectClass.getFactory();
+	const obj = runtime.createChannel(undefined, factory.type);
+	return obj as unknown as T;
+}
+
+/**
+ * Creates a Fluid object that has a property with the key `providerKey` that points to itself.
+ * @remarks This is useful for creating objects that need to reference themselves, such as DataObjects.
+ */
+export function makeFluidObject<
+	T extends object,
+	K extends FluidObjectKeys<T> = FluidObjectKeys<T>,
+>(object: Omit<T, K>, providerKey: K): T {
+	return Object.defineProperty(object, providerKey, { value: object }) as T;
+}
+
+/**
+ * Maps CompatibilityMode to a semver valid string that can be passed to the container runtime.
+ */
+export const compatibilityModeToMinVersionForCollab = {
+	"1": "1.0.0",
+	"2": "2.0.0",
+} as const satisfies Record<CompatibilityMode, MinimumVersionForCollab>;
+
+/**
+ * Determines if the provided schema is a valid tree-based container schema.
+ * @internal
+ */
+export function isTreeContainerSchema(schema: ContainerSchema): schema is TreeContainerSchema {
+	const schemaEntries = Object.entries(schema.initialObjects);
+	if (schemaEntries.length !== 1) {
+		return false;
+	}
+
+	const entry = schemaEntries[0] ?? oob();
+	const key = entry[0];
+	if (key !== "tree") {
+		return false;
+	}
+
+	const objectKind = entry[1] as unknown as LoadableObjectKind;
+	if (
+		isSharedObjectKind(objectKind) &&
+		objectKind.getFactory().type === SharedTreeFactoryType
+	) {
+		return true;
+	}
+
+	return false;
+}