@fluidframework/runtime-utils 2.113.0-411909 → 2.114.0

package/src/serviceClientUtils.ts

@@ -0,0 +1,236 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import type {
+	ICodeDetailsLoader,
+	IContainerContext,
+	IFluidCodeDetails,
+	IFluidCodeDetailsComparer,
+	IFluidModuleWithDetails,
+	IRuntime,
+	IRuntimeFactory,
+} from "@fluidframework/container-definitions/internal";
+import type { FluidObject } from "@fluidframework/core-interfaces";
+import { assert } from "@fluidframework/core-utils/internal";
+import {
+	createBasicRegistryKey,
+	type DataStoreKey,
+	type DataStoreKind,
+	type DataStoreRegistry,
+	type FluidContainerAttached,
+	type FluidContainerWithService,
+	type Registry,
+	lookupInRegistry,
+	type ServiceClient,
+} from "@fluidframework/driver-definitions/internal";
+import type {
+	FluidDataStoreRegistryEntry,
+	IContainerRuntimeBase,
+	IFluidDataStoreRegistry,
+	MinimumVersionForCollab,
+} from "@fluidframework/runtime-definitions/internal";
+
+import { DataStoreKindImplementation } from "./serviceClientBase.js";
+
+/**
+ * The constant ID used for the root data store alias in service containers.
+ * @internal
+ */
+export const rootDataStoreId = "root";
+
+/**
+ * Converts a `DataStoreRegistry` to the `IFluidDataStoreRegistry` interface expected by the container runtime.
+ * @remarks
+ * This does not leverage the ability for `IFluidDataStoreRegistry.get` to return undefined.
+ * Note that all use-cases of `IFluidDataStoreRegistry.get` returning undefined currently end up as a fatal error.
+ * Therefore it should be fine for the error to instead be thrown by the registry function, which is what this function does.
+ * @internal
+ */
+export function convertRegistry<T>(registry: DataStoreRegistry<T>): IFluidDataStoreRegistry {
+	return {
+		async get(name: string): Promise<FluidDataStoreRegistryEntry | undefined> {
+			const dataStoreKind = await lookupInRegistry(registry, createBasicRegistryKey(name));
+			DataStoreKindImplementation.narrowGeneric(dataStoreKind);
+			return dataStoreKind;
+		},
+		get IFluidDataStoreRegistry(): IFluidDataStoreRegistry {
+			return this;
+		},
+	};
+}
+
+/**
+ * Normalizes a `DataStoreKind` or registry function into a registry function.
+ * @internal
+ */
+export function normalizeRegistry<T>(
+	input: DataStoreKind<T> | Registry<Promise<DataStoreKind<T>>>,
+): Registry<Promise<DataStoreKind<T>>> {
+	if (DataStoreKindImplementation.guard(input)) {
+		return async () => input;
+	}
+	assert(typeof input === "function", 0xd17 /* Registry must be a function */);
+	return input;
+}
+
+/**
+ * Parameters passed to a {@link ContainerRuntimeLoader}.
+ * @internal
+ */
+export interface ContainerRuntimeLoaderParams {
+	context: IContainerContext;
+	registry: IFluidDataStoreRegistry;
+	provideEntryPoint: (runtime: IContainerRuntimeBase) => Promise<FluidObject>;
+	existing: boolean;
+	minVersionForCollab: MinimumVersionForCollab;
+	/**
+	 * The type string of the root data store to create. Only set when `existing` is false.
+	 */
+	newContainerRootType: string | undefined;
+}
+
+/**
+ * A service-specific callback that creates or loads the container runtime.
+ *
+ * @remarks
+ * Receives the runtime parameters assembled by {@link makeCodeLoader} and is responsible for
+ * calling the concrete runtime factory (e.g. `ContainerRuntime.loadRuntime2`) and, when
+ * `existing` is `false`, initializing the root data store before returning.
+ *
+ * @internal
+ */
+export type ContainerRuntimeLoader = (
+	parameters: ContainerRuntimeLoaderParams,
+) => Promise<IRuntime>;
+
+/**
+ * Creates an `ICodeDetailsLoader` that wires up the container runtime via the supplied
+ * `loadRuntime` callback.
+ *
+ * @remarks
+ * The `loadRuntime` callback is responsible for invoking the concrete runtime factory and,
+ * when `parameters.existing` is `false` and `parameters.newContainerRootType` is set, creating and
+ * aliasing the root data store.
+ *
+ * This loader never does any code loading, and always assumes it is compatible.
+ * TODO: We should reevaluate this before promoting ServiceClient APIs to beta.
+ *
+ * @internal
+ */
+export function makeCodeLoader<T>(
+	registry: DataStoreRegistry<T>,
+	minVersionForCollab: MinimumVersionForCollab,
+	loadRuntime: ContainerRuntimeLoader,
+	root?: DataStoreKind<T>,
+): ICodeDetailsLoader {
+	const fluidExport: IRuntimeFactory & IFluidCodeDetailsComparer = {
+		async instantiateRuntime(
+			context: IContainerContext,
+			existing: boolean,
+		): Promise<IRuntime> {
+			const provideEntryPoint = async (
+				entryPointRuntime: IContainerRuntimeBase,
+			): Promise<T & FluidObject> => {
+				const data = await entryPointRuntime.getAliasedDataStoreEntryPoint(rootDataStoreId);
+				if (data === undefined) {
+					throw new Error("Root data store missing!");
+				}
+				const rootDataStore = await data.get();
+				return rootDataStore as T & FluidObject;
+			};
+
+			return loadRuntime({
+				context,
+				registry: convertRegistry(registry),
+				provideEntryPoint,
+				existing,
+				minVersionForCollab,
+				newContainerRootType: root?.type,
+			});
+		},
+
+		async satisfies(
+			candidate: IFluidCodeDetails,
+			constraint: IFluidCodeDetails,
+		): Promise<boolean> {
+			return true;
+		},
+
+		async compare(a: IFluidCodeDetails, b: IFluidCodeDetails): Promise<number | undefined> {
+			return 0;
+		},
+
+		get IRuntimeFactory(): IRuntimeFactory {
+			return fluidExport;
+		},
+
+		get IFluidCodeDetailsComparer(): IFluidCodeDetailsComparer {
+			return fluidExport;
+		},
+	};
+
+	return {
+		load: async (details: IFluidCodeDetails): Promise<IFluidModuleWithDetails> => {
+			return { module: { fluidExport }, details };
+		},
+	};
+}
+
+/**
+ * Minimal interface for the static container factory methods used by {@link ServiceClientImplementation}.
+ * @internal
+ */
+export interface ServiceContainerStatics<TOptions> {
+	createDetached<T>(
+		registry: DataStoreRegistry<T>,
+		options: TOptions,
+		root: DataStoreKind<T>,
+	): Promise<FluidContainerWithService<T>>;
+
+	load<T>(
+		registry: DataStoreRegistry<T>,
+		options: TOptions,
+		id: string,
+	): Promise<FluidContainerAttached<T>>;
+}
+
+/**
+ * Creates a {@link @fluidframework/driver-definitions#ServiceClient} that delegates container
+ * creation and loading to the supplied container class statics.
+ * @internal
+ */
+export class ServiceClientImplementation<TOptions> implements ServiceClient {
+	public constructor(
+		private readonly options: TOptions,
+		private readonly statics: ServiceContainerStatics<TOptions>,
+	) {}
+
+	public createContainer<T>(root: DataStoreKind<T>): Promise<FluidContainerWithService<T>>;
+
+	public createContainer<T>(
+		root: DataStoreKey<T>,
+		registry: Registry<Promise<DataStoreKind>>,
+	): Promise<FluidContainerWithService<T>>;
+
+	public async createContainer<T>(
+		root: DataStoreKey<T> | DataStoreKind<T>,
+		registry?: Registry<Promise<DataStoreKind<T>>>,
+	): Promise<FluidContainerWithService<T>> {
+		if (registry === undefined) {
+			DataStoreKindImplementation.narrowGeneric(root);
+			return this.statics.createDetached(normalizeRegistry(root), this.options, root);
+		} else {
+			const result = await lookupInRegistry(registry, root);
+			return this.statics.createDetached(registry, this.options, result);
+		}
+	}
+
+	public async loadContainer<T>(
+		id: string,
+		root: DataStoreKind<T> | Registry<Promise<DataStoreKind<T>>>,
+	): Promise<FluidContainerAttached<T>> {
+		return this.statics.load(normalizeRegistry(root), this.options, id);
+	}
+}