@fluidframework/runtime-definitions 2.0.0-dev-rc.1.0.0.232845 → 2.0.0-dev-rc.2.0.0.246488

package/.eslintrc.cjs

@@ -7,6 +7,6 @@ module.exports = {
 	parserOptions: {
 		project: ["./tsconfig.json", "./src/test/tsconfig.json"],
 	},
-	extends: ["@fluidframework/eslint-config-fluid/minimal", "prettier"],
+	extends: ["@fluidframework/eslint-config-fluid/minimal-deprecated", "prettier"],
 	plugins: ["deprecation"],
 };

package/CHANGELOG.md

@@ -1,5 +1,80 @@
 # @fluidframework/runtime-definitions
 
+## 2.0.0-rc.2.0.0
+
+### Minor Changes
+
+-   runtime-definitions: ITelemetryContext: Functions `get` and `serialize` are now deprecated ([#19409](https://github.com/microsoft/FluidFramework/issues/19409)) [42696564dd](https://github.com/microsoft/FluidFramework/commits/42696564ddbacfe200d653bdf7a1db18fc253bfb)
+
+    ITelemetryContext is to be used only for instrumentation, not for attempting to read the values already set by other code.
+    This is important because this _public_ interface may soon use FF's _should-be internal_ logging instrumentation types,
+    which we reserve the right to expand (to support richer instrumentation).
+    In that case, we would not be able to do so in a minor release if they're used as an "out" type
+    like the return type for `get`.
+
+    There is no replacement given in terms of immediate programmatic access to this data.
+    The expected use pattern is something like this:
+
+    -   Some code creates a concrete implementation of `ITelemetryContext` and passes it around
+    -   Callers use the "write" functions on the interface to build up the context
+    -   The originator uses a function like `serialize` (on the concrete impl, not exposed on the interface any longer)
+        and passes the result to a logger
+    -   The data is inspected along with other logs in whatever telemetry pipeline is used by the application (or Debug Tools, etc)
+
+-   container-runtime: New feature: ID compression for DataStores & DDSs ([#19859](https://github.com/microsoft/FluidFramework/issues/19859)) [51f0d3db73](https://github.com/microsoft/FluidFramework/commits/51f0d3db737800e1c30ea5e3952d38ff30ffc7da)
+
+    ### Key changes
+
+    1. A new API IContainerRuntimeBase.generateDocumentUniqueId() is exposed. This API will opportunistically generate IDs in short format (non-negative numbers). If it can't achieve that, it will return UUID strings. 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 data in container is likely candidate to start leveraging this API.
+    2. Data store internal IDs (IDs that are auto generated by FF system) will opportunistically be generated in shorter form. Data stores created in detached container will always have short IDs, data stores created in attached container will opportunistically be short (by using newly added IContainerRuntimeBase.generateDocumentUniqueId() capability)
+    3. Similar DDS names will be opportunistically short (same considerations for detached DDS vs. attached DDS)
+
+    ### Implementation details
+
+    1. Container level ID Compressor can now be enabled with delay. With such setting, only new IContainerRuntimeBase.generateDocumentUniqueId() is exposed (ID Compressor is not exposed in such case, as leveraging any of its other capabilities requires future container sessions to load ID Compressor on container load, for correctness reasons). Once Container establishes connection and any changes are made in container, newly added API will start generating more compact IDs (in most cases).
+
+    ### Breaking changes
+
+    1. DDS names can no longer start with "\_" symbol - this is reserved for FF needs. I've validated that's not an issue for AzureClient (it only creates root object by name, everything else is referred by handle). Our main internal partners almost never use named DDSs (I can find only 4 instances in Loop).
+
+    ### Backward compatibility considerations
+
+    1. Data store internal IDs could collide with earlier used names data stores. Earlier versions of FF framework (before DataStore aliasing feature was added) allowed customers to supply IDs for data stores. And thus, files created with earlier versions of framework could have data store IDs that will be similar to names FF will use for newly created data stores ("A", ... "Z", "a"..."z", "AA", etc.). While such collision is possible, it's very unlikely (almost impossible) if user-provided names were at least 4-5 characters long.
+    2. If application runs to these problems, or wants to reduce risks, consider disabling ID compressor via IContainerRuntimeOptions.enableRuntimeIdCompressor = "off".
+
+    ### Minor changes
+
+    1. IContainerRuntime.createDetachedRootDataStore() is removed. Please use IContainerRuntime.createDetachedDataStore and IDataStore.trySetAlias() instead
+    2. IContainerRuntimeOptions.enableRuntimeIdCompressor has been changes from boolean to tri-state.
+
+-   driver-definitions: repositoryUrl removed from IDocumentStorageService ([#19522](https://github.com/microsoft/FluidFramework/issues/19522)) [90eb3c9d33](https://github.com/microsoft/FluidFramework/commits/90eb3c9d33d80e24caa1393a50f414c5602f6aa3)
+
+    The `repositoryUrl` member of `IDocumentStorageService` was unused and always equal to the empty string. It has been removed.
+
+-   runtime-definitions: FlushMode.Immediate is deprecated ([#19963](https://github.com/microsoft/FluidFramework/issues/19963)) [861500c1e2](https://github.com/microsoft/FluidFramework/commits/861500c1e2bdd3394308bd87007231d70b698be0)
+
+    `FlushMode.Immediate` is deprecated and will be removed in the next major version. It should not be used. Use
+    `FlushMode.TurnBased` instead, which is the default. See
+    <https://github.com/microsoft/FluidFramework/tree/main/packages/runtime/container-runtime/src/opLifecycle#how-batching-works>
+    for more information
+
+-   container-definitions: ILoaderOptions no longer accepts arbitrary key/value pairs ([#19306](https://github.com/microsoft/FluidFramework/issues/19306)) [741926e225](https://github.com/microsoft/FluidFramework/commits/741926e2253a161504ecc6a6451d8f15d7ac4ed6)
+
+    ILoaderOptions has been narrowed to the specific set of supported loader options, and may no longer be used to pass arbitrary key/value pairs through to the runtime.
+
+-   runtime-definitions: Deprecated ID compressor related types have been removed. ([#19031](https://github.com/microsoft/FluidFramework/issues/19031)) [de92ef0ac5](https://github.com/microsoft/FluidFramework/commits/de92ef0ac551ad89b00564c78c0091f8ecc33639)
+
+    This change should be a no-op for consumers, as these types were almost certainly unused and are also available in the
+    standalone package id-compressor (see <https://github.com/microsoft/FluidFramework/pull/18749>).
+
+-   container-definitions: Added containerMetadata prop on IContainer interface ([#19142](https://github.com/microsoft/FluidFramework/issues/19142)) [d0d77f3516](https://github.com/microsoft/FluidFramework/commits/d0d77f3516d67f3c9faedb47b20dbd4e309c3bc2)
+
+    Added `containerMetadata` prop on IContainer interface.
+
+-   runtime-definitions: Moved ISignalEnvelope interface to core-interfaces ([#19142](https://github.com/microsoft/FluidFramework/issues/19142)) [d0d77f3516](https://github.com/microsoft/FluidFramework/commits/d0d77f3516d67f3c9faedb47b20dbd4e309c3bc2)
+
+    The `ISignalEnvelope` interface has been moved to the @fluidframework/core-interfaces package.
+
 ## 2.0.0-rc.1.0.0
 
 ### Minor Changes

package/api-extractor-cjs.json

@@ -0,0 +1,8 @@
+{
+	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+	"extends": "../../../common/build/build-common/api-extractor-base.cjs.primary.json",
+	// CJS is actually secondary; so, no report.
+	"apiReport": {
+		"enabled": false
+	}
+}

package/api-extractor-lint.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-lint.json"
+	"extends": "../../../common/build/build-common/api-extractor-lint.esm.primary.json"
 }

package/api-extractor.json

@@ -1,4 +1,4 @@
 {
 	"$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-	"extends": "../../../common/build/build-common/api-extractor-base.json"
+	"extends": "../../../common/build/build-common/api-extractor-base.esm.primary.json"
 }

package/api-report/runtime-definitions.api.md

@@ -4,32 +4,31 @@
 
 ```ts
 
-import { AttachState } from '@fluidframework/container-definitions';
-import { FluidObject } from '@fluidframework/core-interfaces';
-import { IAudience } from '@fluidframework/container-definitions';
-import { IClientDetails } from '@fluidframework/protocol-definitions';
-import { IDeltaManager } from '@fluidframework/container-definitions';
-import { IDisposable } from '@fluidframework/core-interfaces';
-import { IDocumentMessage } from '@fluidframework/protocol-definitions';
-import { IDocumentStorageService } from '@fluidframework/driver-definitions';
-import { IEvent } from '@fluidframework/core-interfaces';
-import { IEventProvider } from '@fluidframework/core-interfaces';
-import { IFluidHandle } from '@fluidframework/core-interfaces';
-import { IIdCompressor } from '@fluidframework/id-compressor';
-import { ILoaderOptions } from '@fluidframework/container-definitions';
-import { IProvideFluidHandleContext } from '@fluidframework/core-interfaces';
-import { IQuorumClients } from '@fluidframework/protocol-definitions';
-import { IRequest } from '@fluidframework/core-interfaces';
-import { IResponse } from '@fluidframework/core-interfaces';
-import { ISequencedDocumentMessage } from '@fluidframework/protocol-definitions';
-import { ISignalMessage } from '@fluidframework/protocol-definitions';
-import { ISnapshotTree } from '@fluidframework/protocol-definitions';
-import { ISummaryTree } from '@fluidframework/protocol-definitions';
-import { ITelemetryBaseLogger } from '@fluidframework/core-interfaces';
-import { ITree } from '@fluidframework/protocol-definitions';
+import type { AttachState } from '@fluidframework/container-definitions';
+import type { FluidObject } from '@fluidframework/core-interfaces';
+import type { IAudience } from '@fluidframework/container-definitions';
+import type { IClientDetails } from '@fluidframework/protocol-definitions';
+import type { IDeltaManager } from '@fluidframework/container-definitions';
+import type { IDisposable } from '@fluidframework/core-interfaces';
+import type { IDocumentMessage } from '@fluidframework/protocol-definitions';
+import type { IDocumentStorageService } from '@fluidframework/driver-definitions';
+import type { IEvent } from '@fluidframework/core-interfaces';
+import type { IEventProvider } from '@fluidframework/core-interfaces';
+import type { IFluidHandle } from '@fluidframework/core-interfaces';
+import type { IIdCompressor } from '@fluidframework/id-compressor';
+import type { IProvideFluidHandleContext } from '@fluidframework/core-interfaces';
+import type { IQuorumClients } from '@fluidframework/protocol-definitions';
+import type { IRequest } from '@fluidframework/core-interfaces';
+import type { IResponse } from '@fluidframework/core-interfaces';
+import type { ISequencedDocumentMessage } from '@fluidframework/protocol-definitions';
+import type { ISignalMessage } from '@fluidframework/protocol-definitions';
+import type { ISnapshotTree } from '@fluidframework/protocol-definitions';
+import type { ISummaryTree } from '@fluidframework/protocol-definitions';
+import type { ITelemetryBaseLogger } from '@fluidframework/core-interfaces';
+import type { ITree } from '@fluidframework/protocol-definitions';
 import type { IUser } from '@fluidframework/protocol-definitions';
-import { SummaryTree } from '@fluidframework/protocol-definitions';
-import { TelemetryEventPropertyType } from '@fluidframework/core-interfaces';
+import type { SummaryTree } from '@fluidframework/protocol-definitions';
+import type { TelemetryBaseEventPropertyType } from '@fluidframework/core-interfaces';
 
 // @alpha
 export type AliasResult = "Success" | "Conflict" | "AlreadyAliased";
@@ -86,6 +85,7 @@ export type FluidDataStoreRegistryEntry = Readonly<Partial<IProvideFluidDataStor
 
 // @alpha
 export enum FlushMode {
+    // @deprecated
     Immediate = 0,
     TurnBased = 1
 }
@@ -98,6 +98,9 @@ export enum FlushModeExperimental {
 // @internal
 export const gcBlobPrefix = "__gc";
 
+// @internal
+export const gcDataBlobKey = ".gcdata";
+
 // @internal
 export const gcDeletedBlobKey = "__deletedNodes";
 
@@ -118,17 +121,24 @@ export interface IAttachMessage {
 export interface IContainerRuntimeBase extends IEventProvider<IContainerRuntimeBaseEvents> {
     // (undocumented)
     readonly clientDetails: IClientDetails;
-    createDataStore(pkg: string | string[], groupId?: string): Promise<IDataStore>;
+    createDataStore(pkg: Readonly<string | string[]>, loadingGroupId?: string): Promise<IDataStore>;
     // @deprecated (undocumented)
-    _createDataStoreWithProps(pkg: string | string[], props?: any, id?: string): Promise<IDataStore>;
-    createDetachedDataStore(pkg: Readonly<string[]>, groupId?: string): IFluidDataStoreContextDetached;
+    _createDataStoreWithProps(pkg: Readonly<string | string[]>, props?: any, id?: string): Promise<IDataStore>;
+    createDetachedDataStore(pkg: Readonly<string[]>, loadingGroupId?: string): IFluidDataStoreContextDetached;
+    // (undocumented)
+    readonly disposed: boolean;
+    generateDocumentUniqueId(): number | string;
     getAbsoluteUrl(relativeUrl: string): Promise<string | undefined>;
     getAudience(): IAudience;
     getQuorum(): IQuorumClients;
+    getSnapshotForLoadingGroupId(loadingGroupIds: string[], pathParts: string[]): Promise<{
+        snapshotTree: ISnapshotTree;
+        sequenceNumber: number;
+    }>;
     // (undocumented)
     readonly logger: ITelemetryBaseLogger;
     orderSequentially(callback: () => void): void;
-    submitSignal(type: string, content: any): void;
+    submitSignal(type: string, content: any, targetClientId?: string): void;
     // (undocumented)
     uploadBlob(blob: ArrayBufferLike, signal?: AbortSignal): Promise<IFluidHandle<ArrayBufferLike>>;
 }
@@ -143,6 +153,8 @@ export interface IContainerRuntimeBaseEvents extends IEvent {
     (event: "batchEnd", listener: (error: any, op: ISequencedDocumentMessage) => void): any;
     // (undocumented)
     (event: "signal", listener: (message: IInboundSignalMessage, local: boolean) => void): any;
+    // (undocumented)
+    (event: "dispose", listener: () => void): any;
 }
 
 // @alpha
@@ -168,36 +180,72 @@ export interface IExperimentalIncrementalSummaryContext {
 export interface IFluidDataStoreChannel extends IDisposable {
     // (undocumented)
     applyStashedOp(content: any): Promise<unknown>;
-    // @deprecated
-    attachGraph(): void;
-    readonly attachState: AttachState;
     readonly entryPoint: IFluidHandle<FluidObject>;
+    getAttachGCData?(telemetryContext?: ITelemetryContext): IGarbageCollectionData;
     getAttachSummary(telemetryContext?: ITelemetryContext): ISummaryTreeWithStats;
     getGCData(fullGC?: boolean): Promise<IGarbageCollectionData>;
-    // (undocumented)
-    readonly id: string;
     makeVisibleAndAttachGraph(): void;
-    process(message: ISequencedDocumentMessage, local: boolean, localOpMetadata: unknown): void;
-    processSignal(message: any, local: boolean): void;
+    process(message: ISequencedDocumentMessage, local: boolean, localOpMetadata: unknown, addedOutboundReference?: (fromNodePath: string, toNodePath: string) => void): void;
+    processSignal(message: IInboundSignalMessage, local: boolean): void;
     // (undocumented)
     request(request: IRequest): Promise<IResponse>;
     reSubmit(type: string, content: any, localOpMetadata: unknown): any;
     rollback?(type: string, content: any, localOpMetadata: unknown): void;
+    // (undocumented)
+    setAttachState(attachState: AttachState.Attaching | AttachState.Attached): void;
     setConnectionState(connected: boolean, clientId?: string): any;
     summarize(fullTree?: boolean, trackState?: boolean, telemetryContext?: ITelemetryContext): Promise<ISummaryTreeWithStats>;
     updateUsedRoutes(usedRoutes: string[]): void;
+}
+
+// @alpha
+export interface IFluidDataStoreContext extends IFluidParentContext {
+    addedGCOutboundRoute?(fromPath: string, toPath: string): void;
     // (undocumented)
-    readonly visibilityState: VisibilityState;
+    readonly baseSnapshot: ISnapshotTree | undefined;
+    // @deprecated (undocumented)
+    readonly createProps?: any;
+    // @deprecated (undocumented)
+    getBaseGCDetails(): Promise<IGarbageCollectionDetailsBase>;
+    // (undocumented)
+    readonly id: string;
+    readonly isLocalDataStore: boolean;
+    readonly packagePath: readonly string[];
+}
+
+// @alpha (undocumented)
+export interface IFluidDataStoreContextDetached extends IFluidDataStoreContext {
+    attachRuntime(factory: IProvideFluidDataStoreFactory, dataStoreRuntime: IFluidDataStoreChannel): Promise<IDataStore>;
+}
+
+// @alpha (undocumented)
+export const IFluidDataStoreFactory: keyof IProvideFluidDataStoreFactory;
+
+// @alpha
+export interface IFluidDataStoreFactory extends IProvideFluidDataStoreFactory {
+    instantiateDataStore(context: IFluidDataStoreContext, existing: boolean): Promise<IFluidDataStoreChannel>;
+    type: string;
 }
 
+// @alpha (undocumented)
+export const IFluidDataStoreRegistry: keyof IProvideFluidDataStoreRegistry;
+
 // @alpha
-export interface IFluidDataStoreContext extends IEventProvider<IFluidDataStoreContextEvents>, Partial<IProvideFluidDataStoreRegistry>, IProvideFluidHandleContext {
+export interface IFluidDataStoreRegistry extends IProvideFluidDataStoreRegistry {
+    // (undocumented)
+    get(name: string): Promise<FluidDataStoreRegistryEntry | undefined>;
+}
+
+// @alpha
+export interface IFluidParentContext extends IProvideFluidHandleContext, Partial<IProvideFluidDataStoreRegistry> {
     // @deprecated (undocumented)
-    addedGCOutboundReference?(srcHandle: IFluidHandle, outboundHandle: IFluidHandle): void;
+    addedGCOutboundReference?(srcHandle: {
+        absolutePath: string;
+    }, outboundHandle: {
+        absolutePath: string;
+    }): void;
     readonly attachState: AttachState;
     // (undocumented)
-    readonly baseSnapshot: ISnapshotTree | undefined;
-    // (undocumented)
     readonly clientDetails: IClientDetails;
     // (undocumented)
     readonly clientId: string | undefined;
@@ -205,33 +253,30 @@ export interface IFluidDataStoreContext extends IEventProvider<IFluidDataStoreCo
     readonly connected: boolean;
     // (undocumented)
     readonly containerRuntime: IContainerRuntimeBase;
-    // @deprecated (undocumented)
-    readonly createProps?: any;
+    // (undocumented)
+    deleteChildSummarizerNode(id: string): void;
     // (undocumented)
     readonly deltaManager: IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>;
     ensureNoDataModelChanges<T>(callback: () => T): T;
+    // (undocumented)
+    readonly gcThrowOnTombstoneUsage: boolean;
+    // (undocumented)
+    readonly gcTombstoneEnforcementAllowed: boolean;
     getAbsoluteUrl(relativeUrl: string): Promise<string | undefined>;
     getAudience(): IAudience;
-    // @deprecated (undocumented)
-    getBaseGCDetails(): Promise<IGarbageCollectionDetailsBase>;
     // (undocumented)
     getCreateChildSummarizerNodeFn(
     id: string,
     createParam: CreateChildSummarizerNodeParam): CreateChildSummarizerNodeFn;
     getQuorum(): IQuorumClients;
     // (undocumented)
-    readonly groupId?: string;
-    // (undocumented)
-    readonly id: string;
-    // (undocumented)
     readonly idCompressor?: IIdCompressor;
-    readonly isLocalDataStore: boolean;
+    readonly loadingGroupId?: string;
     // (undocumented)
     readonly logger: ITelemetryBaseLogger;
     makeLocallyVisible(): void;
     // (undocumented)
-    readonly options: ILoaderOptions;
-    readonly packagePath: readonly string[];
+    readonly options: Record<string | number, any>;
     readonly scope: FluidObject;
     setChannelDirty(address: string): void;
     // (undocumented)
@@ -242,35 +287,6 @@ export interface IFluidDataStoreContext extends IEventProvider<IFluidDataStoreCo
     uploadBlob(blob: ArrayBufferLike, signal?: AbortSignal): Promise<IFluidHandle<ArrayBufferLike>>;
 }
 
-// @alpha (undocumented)
-export interface IFluidDataStoreContextDetached extends IFluidDataStoreContext {
-    attachRuntime(factory: IProvideFluidDataStoreFactory, dataStoreRuntime: IFluidDataStoreChannel): Promise<void>;
-}
-
-// @alpha (undocumented)
-export interface IFluidDataStoreContextEvents extends IEvent {
-    // (undocumented)
-    (event: "attaching" | "attached", listener: () => void): any;
-}
-
-// @alpha (undocumented)
-export const IFluidDataStoreFactory: keyof IProvideFluidDataStoreFactory;
-
-// @alpha
-export interface IFluidDataStoreFactory extends IProvideFluidDataStoreFactory {
-    instantiateDataStore(context: IFluidDataStoreContext, existing: boolean): Promise<IFluidDataStoreChannel>;
-    type: string;
-}
-
-// @alpha (undocumented)
-export const IFluidDataStoreRegistry: keyof IProvideFluidDataStoreRegistry;
-
-// @alpha
-export interface IFluidDataStoreRegistry extends IProvideFluidDataStoreRegistry {
-    // (undocumented)
-    get(name: string): Promise<FluidDataStoreRegistryEntry | undefined>;
-}
-
 // @public
 export interface IGarbageCollectionData {
     gcNodes: {
@@ -399,10 +415,12 @@ export interface ISummaryTreeWithStats {
 
 // @public
 export interface ITelemetryContext {
-    get(prefix: string, property: string): TelemetryEventPropertyType;
+    // @deprecated
+    get(prefix: string, property: string): TelemetryBaseEventPropertyType;
+    // @deprecated
     serialize(): string;
-    set(prefix: string, property: string, value: TelemetryEventPropertyType): void;
-    setMultiple(prefix: string, property: string, values: Record<string, TelemetryEventPropertyType>): void;
+    set(prefix: string, property: string, value: TelemetryBaseEventPropertyType): void;
+    setMultiple(prefix: string, property: string, values: Record<string, TelemetryBaseEventPropertyType>): void;
 }
 
 // @alpha