@fluidframework/runtime-definitions 2.0.0-dev-rc.1.0.0.228517 → 2.0.0-dev-rc.2.0.0.245554

package/src/dataStoreContext.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import {
+import type {
 	IEvent,
 	IEventProvider,
 	ITelemetryBaseLogger,
@@ -14,32 +14,30 @@ import {
 	IResponse,
 	FluidObject,
 } from "@fluidframework/core-interfaces";
-import {
-	IAudience,
-	IDeltaManager,
-	AttachState,
-	ILoaderOptions,
-} from "@fluidframework/container-definitions";
-import { IDocumentStorageService } from "@fluidframework/driver-definitions";
-import {
+import type { IAudience, IDeltaManager, AttachState } from "@fluidframework/container-definitions";
+import type { IDocumentStorageService } from "@fluidframework/driver-definitions";
+import type {
 	IClientDetails,
 	IDocumentMessage,
 	IQuorumClients,
 	ISequencedDocumentMessage,
 	ISnapshotTree,
 } from "@fluidframework/protocol-definitions";
-import { IIdCompressor } from "@fluidframework/id-compressor";
-import { IProvideFluidDataStoreFactory } from "./dataStoreFactory";
-import { IProvideFluidDataStoreRegistry } from "./dataStoreRegistry";
-import { IGarbageCollectionData, IGarbageCollectionDetailsBase } from "./garbageCollection";
-import { IInboundSignalMessage } from "./protocol";
-import {
+import type { IIdCompressor } from "@fluidframework/id-compressor";
+import type { IProvideFluidDataStoreFactory } from "./dataStoreFactory.js";
+import type { IProvideFluidDataStoreRegistry } from "./dataStoreRegistry.js";
+import type {
+	IGarbageCollectionData,
+	IGarbageCollectionDetailsBase,
+} from "./garbageCollectionDefinitions.js";
+import type { IInboundSignalMessage } from "./protocol.js";
+import type {
 	CreateChildSummarizerNodeParam,
 	ISummarizerNodeWithGC,
 	ISummaryTreeWithStats,
 	ITelemetryContext,
 	SummarizeInternalFn,
-} from "./summary";
+} from "./summary.js";
 
 /**
  * Runtime flush mode handling
@@ -48,6 +46,9 @@ import {
 export enum FlushMode {
 	/**
 	 * In Immediate flush mode the runtime will immediately send all operations to the driver layer.
+	 *
+	 * @deprecated This option will be removed in the next major version and should not be used. Use {@link FlushMode.TurnBased} instead, which is the default.
+	 * See https://github.com/microsoft/FluidFramework/tree/main/packages/runtime/container-runtime/src/opLifecycle#how-batching-works
 	 */
 	Immediate,
 
@@ -120,6 +121,7 @@ export interface IContainerRuntimeBaseEvents extends IEvent {
 	(event: "op", listener: (op: ISequencedDocumentMessage, runtimeMessage?: boolean) => void);
 	(event: "batchEnd", listener: (error: any, op: ISequencedDocumentMessage) => void);
 	(event: "signal", listener: (message: IInboundSignalMessage, local: boolean) => void);
+	(event: "dispose", listener: () => void);
 }
 
 /**
@@ -167,10 +169,13 @@ export interface IDataStore {
 export interface IContainerRuntimeBase extends IEventProvider<IContainerRuntimeBaseEvents> {
 	readonly logger: ITelemetryBaseLogger;
 	readonly clientDetails: IClientDetails;
+	readonly disposed: boolean;
 
 	/**
 	 * Invokes the given callback and guarantees that all operations generated within the callback will be ordered
-	 * sequentially. Total size of all messages must be less than maxOpSize.
+	 * sequentially.
+	 *
+	 * If the callback throws an error, the container will close and the error will be logged.
 	 */
 	orderSequentially(callback: () => void): void;
 
@@ -178,14 +183,15 @@ export interface IContainerRuntimeBase extends IEventProvider<IContainerRuntimeB
 	 * Submits a container runtime level signal to be sent to other clients.
 	 * @param type - Type of the signal.
 	 * @param content - Content of the signal.
+	 * @param targetClientId - When specified, the signal is only sent to the provided client id.
 	 */
-	submitSignal(type: string, content: any): void;
+	submitSignal(type: string, content: any, targetClientId?: string): void;
 
 	/**
 	 * @deprecated 0.16 Issue #1537, #3631
 	 */
 	_createDataStoreWithProps(
-		pkg: string | string[],
+		pkg: Readonly<string | string[]>,
 		props?: any,
 		id?: string,
 	): Promise<IDataStore>;
@@ -197,14 +203,24 @@ export interface IContainerRuntimeBase extends IEventProvider<IContainerRuntimeB
 	 * already attached DDS (or non-attached DDS that will eventually get attached to storage) will result in this
 	 * store being attached to storage.
 	 * @param pkg - Package name of the data store factory
+	 * @param loadingGroupId - This represents the group of the datastore within a container or its snapshot.
+	 * When not specified the datastore will belong to a `default` group. Read more about it in this
+	 * {@link https://github.com/microsoft/FluidFramework/blob/main/packages/runtime/container-runtime/README.md | README}
 	 */
-	createDataStore(pkg: string | string[]): Promise<IDataStore>;
+	createDataStore(pkg: Readonly<string | string[]>, loadingGroupId?: string): Promise<IDataStore>;
 
 	/**
 	 * Creates detached data store context. Only after context.attachRuntime() is called,
 	 * data store initialization is considered complete.
+	 * @param pkg - Package name of the data store factory
+	 * @param loadingGroupId - This represents the group of the datastore within a container or its snapshot.
+	 * When not specified the datastore will belong to a `default` group. Read more about it in this
+	 * {@link https://github.com/microsoft/FluidFramework/blob/main/packages/runtime/container-runtime/README.md | README}.
 	 */
-	createDetachedDataStore(pkg: Readonly<string[]>): IFluidDataStoreContextDetached;
+	createDetachedDataStore(
+		pkg: Readonly<string[]>,
+		loadingGroupId?: string,
+	): IFluidDataStoreContextDetached;
 
 	/**
 	 * Get an absolute url for a provided container-relative request.
@@ -224,6 +240,30 @@ export interface IContainerRuntimeBase extends IEventProvider<IContainerRuntimeB
 	 * Returns the current audience.
 	 */
 	getAudience(): IAudience;
+
+	/**
+	 * Generates a new ID that is guaranteed to be unique across all sessions for this container.
+	 * It could be in compact form (non-negative integer, oppotunistic), but it could also be UUID string.
+	 * UUIDs generated will have low entropy in groups and will compress well.
+	 * It can be leveraged anywhere in container where container unique IDs are required, i.e. any place
+	 * that uses uuid() and stores result in container is likely candidate to start leveraging this API.
+	 * If you always want to convert to string, instead of doing String(generateDocumentUniqueId()), consider
+	 * doing encodeCompactIdToString(generateDocumentUniqueId()).
+	 *
+	 * For more details, please see IIdCompressor.generateDocumentUniqueId()
+	 */
+	generateDocumentUniqueId(): number | string;
+
+	/**
+	 * Api to fetch the snapshot from the service for a loadingGroupIds.
+	 * @param loadingGroupIds - LoadingGroupId for which the snapshot is asked for.
+	 * @param pathParts - Parts of the path, which we want to extract from the snapshot tree.
+	 * @returns - snapshotTree and the sequence number of the snapshot.
+	 */
+	getSnapshotForLoadingGroupId(
+		loadingGroupIds: string[],
+		pathParts: string[],
+	): Promise<{ snapshotTree: ISnapshotTree; sequenceNumber: number }>;
 }
 
 /**
@@ -234,21 +274,6 @@ export interface IContainerRuntimeBase extends IEventProvider<IContainerRuntimeB
  * @alpha
  */
 export interface IFluidDataStoreChannel extends IDisposable {
-	readonly id: string;
-
-	/**
-	 * Indicates the attachment state of the channel to a host service.
-	 */
-	readonly attachState: AttachState;
-
-	readonly visibilityState: VisibilityState;
-
-	/**
-	 * Runs through the graph and attaches the bound handles. Then binds this runtime to the container.
-	 * @deprecated This will be removed in favor of {@link IFluidDataStoreChannel.makeVisibleAndAttachGraph}.
-	 */
-	attachGraph(): void;
-
 	/**
 	 * Makes the data store channel visible in the container. Also, runs through its graph and attaches all
 	 * bound handles that represent its dependencies in the container's graph.
@@ -256,19 +281,29 @@ export interface IFluidDataStoreChannel extends IDisposable {
 	makeVisibleAndAttachGraph(): void;
 
 	/**
-	 * Retrieves the summary used as part of the initial summary message
+	 * Synchronously retrieves the summary used as part of the initial summary message
 	 */
 	getAttachSummary(telemetryContext?: ITelemetryContext): ISummaryTreeWithStats;
 
+	/**
+	 * Synchronously retrieves GC Data (representing the outbound routes present) for the initial state of the DataStore
+	 */
+	getAttachGCData?(telemetryContext?: ITelemetryContext): IGarbageCollectionData;
+
 	/**
 	 * Processes the op.
 	 */
-	process(message: ISequencedDocumentMessage, local: boolean, localOpMetadata: unknown): void;
+	process(
+		message: ISequencedDocumentMessage,
+		local: boolean,
+		localOpMetadata: unknown,
+		addedOutboundReference?: (fromNodePath: string, toNodePath: string) => void,
+	): void;
 
 	/**
 	 * Processes the signal.
 	 */
-	processSignal(message: any, local: boolean): void;
+	processSignal(message: IInboundSignalMessage, local: boolean): void;
 
 	/**
 	 * Generates a summary for the channel.
@@ -329,6 +364,8 @@ export interface IFluidDataStoreChannel extends IDisposable {
 	readonly entryPoint: IFluidHandle<FluidObject>;
 
 	request(request: IRequest): Promise<IResponse>;
+
+	setAttachState(attachState: AttachState.Attaching | AttachState.Attached): void;
 }
 
 /**
@@ -344,44 +381,29 @@ export type CreateChildSummarizerNodeFn = (
 ) => ISummarizerNodeWithGC;
 
 /**
+ * Represents the context for the data store like objects. It is used by the data store runtime to
+ * get information and call functionality to its parent.
+ *
+ * This layout is temporary, as {@link IFluidParentContext} and {@link IFluidDataStoreContext} will converge.
+ *
  * @alpha
  */
-export interface IFluidDataStoreContextEvents extends IEvent {
-	(event: "attaching" | "attached", listener: () => void);
-}
-
-/**
- * Represents the context for the data store. It is used by the data store runtime to
- * get information and call functionality to the container.
- * @alpha
- */
-export interface IFluidDataStoreContext
-	extends IEventProvider<IFluidDataStoreContextEvents>,
-		Partial<IProvideFluidDataStoreRegistry>,
-		IProvideFluidHandleContext {
-	readonly id: string;
-	/**
-	 * A data store created by a client, is a local data store for that client. Also, when a detached container loads
-	 * from a snapshot, all the data stores are treated as local data stores because at that stage the container
-	 * still doesn't exists in storage and so the data store couldn't have been created by any other client.
-	 * Value of this never changes even after the data store is attached.
-	 * As implementer of data store runtime, you can use this property to check that this data store belongs to this
-	 * client and hence implement any scenario based on that.
-	 */
-	readonly isLocalDataStore: boolean;
-	/**
-	 * The package path of the data store as per the package factory.
-	 */
-	readonly packagePath: readonly string[];
-	readonly options: ILoaderOptions;
+export interface IFluidParentContext
+	extends IProvideFluidHandleContext,
+		Partial<IProvideFluidDataStoreRegistry> {
+	readonly options: Record<string | number, any>;
 	readonly clientId: string | undefined;
 	readonly connected: boolean;
 	readonly deltaManager: IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>;
 	readonly storage: IDocumentStorageService;
-	readonly baseSnapshot: ISnapshotTree | undefined;
 	readonly logger: ITelemetryBaseLogger;
 	readonly clientDetails: IClientDetails;
 	readonly idCompressor?: IIdCompressor;
+	/**
+	 * Represents the loading group to which the data store belongs to. Please refer to this readme for more context.
+	 * {@link https://github.com/microsoft/FluidFramework/blob/main/packages/runtime/container-runtime/README.md | README}
+	 */
+	readonly loadingGroupId?: string;
 	/**
 	 * Indicates the attachment state of the data store to a host service.
 	 */
@@ -389,16 +411,14 @@ export interface IFluidDataStoreContext
 
 	readonly containerRuntime: IContainerRuntimeBase;
 
-	/**
-	 * @deprecated 0.16 Issue #1635, #3631
-	 */
-	readonly createProps?: any;
-
 	/**
 	 * Ambient services provided with the context
 	 */
 	readonly scope: FluidObject;
 
+	readonly gcThrowOnTombstoneUsage: boolean;
+	readonly gcTombstoneEnforcementAllowed: boolean;
+
 	/**
 	 * Returns the current quorum.
 	 */
@@ -443,12 +463,6 @@ export interface IFluidDataStoreContext
 	 */
 	makeLocallyVisible(): void;
 
-	/**
-	 * Call by IFluidDataStoreChannel, indicates that a channel is dirty and needs to be part of the summary.
-	 * @param address - The address of the channel that is dirty.
-	 */
-	setChannelDirty(address: string): void;
-
 	/**
 	 * Get an absolute url to the container based on the provided relativeUrl.
 	 * Returns undefined if the container or data store isn't attached to storage.
@@ -470,8 +484,60 @@ export interface IFluidDataStoreContext
 		createParam: CreateChildSummarizerNodeParam,
 	): CreateChildSummarizerNodeFn;
 
+	deleteChildSummarizerNode?(id: string): void;
+
 	uploadBlob(blob: ArrayBufferLike, signal?: AbortSignal): Promise<IFluidHandle<ArrayBufferLike>>;
 
+	/**
+	 * @deprecated There is no replacement for this, its functionality is no longer needed at this layer.
+	 * It will be removed in a future release, sometime after 2.0.0-internal.8.0.0
+	 *
+	 * Similar capability is exposed with from/to string paths instead of handles via @see addedGCOutboundRoute
+	 *
+	 * Called when a new outbound reference is added to another node. This is used by garbage collection to identify
+	 * all references added in the system.
+	 * @param srcHandle - The handle of the node that added the reference.
+	 * @param outboundHandle - The handle of the outbound node that is referenced.
+	 */
+	addedGCOutboundReference?(
+		srcHandle: { absolutePath: string },
+		outboundHandle: { absolutePath: string },
+	): void;
+
+	/**
+	 * Called by IFluidDataStoreChannel, indicates that a channel is dirty and needs to be part of the summary.
+	 * @param address - The address of the channel that is dirty.
+	 */
+	setChannelDirty(address: string): void;
+}
+
+/**
+ * Represents the context for the data store. It is used by the data store runtime to
+ * get information and call functionality to the container.
+ * @alpha
+ */
+export interface IFluidDataStoreContext extends IFluidParentContext {
+	readonly id: string;
+	/**
+	 * A data store created by a client, is a local data store for that client. Also, when a detached container loads
+	 * from a snapshot, all the data stores are treated as local data stores because at that stage the container
+	 * still doesn't exists in storage and so the data store couldn't have been created by any other client.
+	 * Value of this never changes even after the data store is attached.
+	 * As implementer of data store runtime, you can use this property to check that this data store belongs to this
+	 * client and hence implement any scenario based on that.
+	 */
+	readonly isLocalDataStore: boolean;
+	/**
+	 * The package path of the data store as per the package factory.
+	 */
+	readonly packagePath: readonly string[];
+	readonly baseSnapshot: ISnapshotTree | undefined;
+
+	/**
+	 * @deprecated 0.16 Issue #1635, #3631
+	 */
+	readonly createProps?: any;
+
 	/**
 	 * @deprecated The functionality to get base GC details has been moved to summarizer node.
 	 *
@@ -481,15 +547,15 @@ export interface IFluidDataStoreContext
 	getBaseGCDetails(): Promise<IGarbageCollectionDetailsBase>;
 
 	/**
-	 * @deprecated There is no replacement for this, its functionality is no longer needed at this layer.
-	 * It will be removed in a future release, sometime after 2.0.0-internal.8.0.0
+	 * (Same as @see addedGCOutboundReference, but with string paths instead of handles)
 	 *
 	 * Called when a new outbound reference is added to another node. This is used by garbage collection to identify
 	 * all references added in the system.
-	 * @param srcHandle - The handle of the node that added the reference.
-	 * @param outboundHandle - The handle of the outbound node that is referenced.
+	 *
+	 * @param fromPath - The absolute path of the node that added the reference.
+	 * @param toPath - The absolute path of the outbound node that is referenced.
 	 */
-	addedGCOutboundReference?(srcHandle: IFluidHandle, outboundHandle: IFluidHandle): void;
+	addedGCOutboundRoute?(fromPath: string, toPath: string): void;
 }
 
 /**
@@ -502,5 +568,5 @@ export interface IFluidDataStoreContextDetached extends IFluidDataStoreContext {
 	attachRuntime(
 		factory: IProvideFluidDataStoreFactory,
 		dataStoreRuntime: IFluidDataStoreChannel,
-	): Promise<void>;
+	): Promise<IDataStore>;
 }

package/src/dataStoreFactory.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { IFluidDataStoreContext, IFluidDataStoreChannel } from "./dataStoreContext";
+import type { IFluidDataStoreContext, IFluidDataStoreChannel } from "./dataStoreContext.js";
 
 /**
  * @alpha

package/src/dataStoreRegistry.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { IProvideFluidDataStoreFactory } from "./dataStoreFactory";
+import type { IProvideFluidDataStoreFactory } from "./dataStoreFactory.js";
 
 /**
  * A single registry entry that may be used to create data stores

package/src/{garbageCollection.ts → garbageCollectionDefinitions.ts}

@@ -10,7 +10,7 @@
  */
 export const gcTreeKey = "gc";
 /**
- * They prefix for GC blobs in the GC tree in summary.
+ * The prefix for GC blobs in the GC tree in summary.
  *
  * @internal
  */
@@ -27,6 +27,12 @@ export const gcTombstoneBlobKey = "__tombstones";
  * @internal
  */
 export const gcDeletedBlobKey = "__deletedNodes";
+/**
+ * The key for the GC Data blob in attach summaries.
+ *
+ * @internal
+ */
+export const gcDataBlobKey = ".gcdata";
 
 /**
  * Garbage collection data returned by nodes in a Container.

package/src/index.ts

@@ -3,55 +3,54 @@
  * Licensed under the MIT License.
  */
 
-export {
+export type {
 	AttributionInfo,
 	AttributionKey,
 	DetachedAttributionKey,
 	LocalAttributionKey,
 	OpAttributionKey,
-} from "./attribution";
-export {
+} from "./attribution.js";
+export type {
 	AliasResult,
 	CreateChildSummarizerNodeFn,
-	FlushMode,
-	FlushModeExperimental,
 	IContainerRuntimeBase,
 	IContainerRuntimeBaseEvents,
 	IDataStore,
 	IFluidDataStoreChannel,
 	IFluidDataStoreContext,
+	IFluidParentContext,
 	IFluidDataStoreContextDetached,
-	IFluidDataStoreContextEvents,
-	VisibilityState,
-} from "./dataStoreContext";
-export { IFluidDataStoreFactory, IProvideFluidDataStoreFactory } from "./dataStoreFactory";
-export {
+} from "./dataStoreContext.js";
+export { FlushMode, FlushModeExperimental, VisibilityState } from "./dataStoreContext.js";
+export type { IProvideFluidDataStoreFactory } from "./dataStoreFactory.js";
+export { IFluidDataStoreFactory } from "./dataStoreFactory.js";
+export type {
 	FluidDataStoreRegistryEntry,
-	IFluidDataStoreRegistry,
 	IProvideFluidDataStoreRegistry,
 	NamedFluidDataStoreRegistryEntries,
 	NamedFluidDataStoreRegistryEntry,
-} from "./dataStoreRegistry";
+} from "./dataStoreRegistry.js";
+export { IFluidDataStoreRegistry } from "./dataStoreRegistry.js";
+export type {
+	IGarbageCollectionData,
+	IGarbageCollectionDetailsBase,
+} from "./garbageCollectionDefinitions.js";
 export {
 	gcBlobPrefix,
+	gcDataBlobKey,
 	gcDeletedBlobKey,
 	gcTombstoneBlobKey,
 	gcTreeKey,
-	IGarbageCollectionData,
-	IGarbageCollectionDetailsBase,
-} from "./garbageCollection";
-export {
+} from "./garbageCollectionDefinitions.js";
+export type {
 	IAttachMessage,
 	IEnvelope,
 	IInboundSignalMessage,
 	InboundAttachMessage,
 	ISignalEnvelope,
-} from "./protocol";
-export {
-	blobCountPropertyName,
-	channelsTreeName,
+} from "./protocol.js";
+export type {
 	CreateChildSummarizerNodeParam,
-	CreateSummarizerNodeSource,
 	IExperimentalIncrementalSummaryContext,
 	ISummarizeInternalResult,
 	ISummarizeResult,
@@ -63,54 +62,10 @@ export {
 	ISummaryTreeWithStats,
 	ITelemetryContext,
 	SummarizeInternalFn,
-	totalBlobSizePropertyName,
-} from "./summary";
-
-// Re-exports for backwards compatibility.
-// Will be removed in the future.
+} from "./summary.js";
 export {
-	/**
-	 * @deprecated Import from `@fluidframework/id-compressor` instead.
-	 */
-	IdCompressor,
-	/**
-	 * @deprecated Import from `@fluidframework/id-compressor` instead.
-	 */
-	IIdCompressor,
-	/**
-	 * @deprecated Import from `@fluidframework/id-compressor` instead.
-	 */
-	IIdCompressorCore,
-	/**
-	 * @deprecated Import from `@fluidframework/id-compressor` instead.
-	 */
-	IdCreationRange,
-	/**
-	 * @deprecated Import from `@fluidframework/id-compressor` instead.
-	 */
-	OpSpaceCompressedId,
-	/**
-	 * @deprecated Import from `@fluidframework/id-compressor` instead.
-	 */
-	SerializedIdCompressor,
-	/**
-	 * @deprecated Import from `@fluidframework/id-compressor` instead.
-	 */
-	SerializedIdCompressorWithNoSession,
-	/**
-	 * @deprecated Import from `@fluidframework/id-compressor` instead.
-	 */
-	SerializedIdCompressorWithOngoingSession,
-	/**
-	 * @deprecated Import from `@fluidframework/id-compressor` instead.
-	 */
-	SessionId,
-	/**
-	 * @deprecated Import from `@fluidframework/id-compressor` instead.
-	 */
-	SessionSpaceCompressedId,
-	/**
-	 * @deprecated Import from `@fluidframework/id-compressor` instead.
-	 */
-	StableId,
-} from "@fluidframework/id-compressor";
+	blobCountPropertyName,
+	channelsTreeName,
+	CreateSummarizerNodeSource,
+	totalBlobSizePropertyName,
+} from "./summary.js";

package/src/protocol.ts

@@ -3,7 +3,7 @@
  * Licensed under the MIT License.
  */
 
-import { ISignalMessage, ITree } from "@fluidframework/protocol-definitions";
+import type { ISignalMessage, ITree } from "@fluidframework/protocol-definitions";
 
 /**
  * An envelope wraps the contents with the intended target
@@ -23,6 +23,7 @@ export interface IEnvelope {
 
 /**
  * @internal
+ * @deprecated - This interface is now moved to `@fluidframework/container-definitions` package. Please import from that package.
  */
 export interface ISignalEnvelope {
 	/**