Skip to content

BREAKING.md

Latest commit

 

History

History
2069 lines (1492 loc) · 128 KB

BREAKING.md

File metadata and controls

2069 lines (1492 loc) · 128 KB
Raw

Adding breaking change notes

Notes on breaking and otherwise interesting changes go here. They will be reviewed and published along with each release. Published changelogs may be found on the docs site at fluidframework.com.

Writing a change note

There are a few steps you can take to write a good change note and avoid needing to followup for clarification.

  • Provide a concise title. It should make clear what the topic of the change is.
  • Ensure the affected packages are named or clearly identifiable within the body.
  • Provide guidance on how the change should be consumed if applicable, such as by specifying replacement APIs.
  • Consider providing code examples as part of guidance for non-trivial changes.

0.58 Breaking changes

Move IntervalType from merge-tree to sequence package

Move the type from the merge-tree package where it isn't used to the sequence package where it is used

- import { IntervalType } from "@fluidframework/merge-tree";
+ import { IntervalType } from "@fluidframework/sequence";

Remove logger property from IContainerContext

The logger property in IContainerContext became an optional parameter in release 0.56. This property has now been removed. The taggedLogger property is now set as a required parameter in IContainerContext interface.

Set raiseContainerWarning property as optional parameter on IContainerContext

raiseContainerWarning is set as an optional parameter on IContainerContext interface and would be removed from IContainerContext interface and ContainerContext class in the next release. Please see [#Remove-raiseContainerWarning-property] for more details.

Consolidate fluidErrorCode and message on FF Errors

Errors raised by the Fluid Framework will no longer contain the property fluidErrorCode. This was present in many error constructors, and exposed in the type IFluidErrorBase, but has now been removed. Previously, the fluidErrorCode value (a pascaleCased term) was often used as the error message itself. Now all error messages can be expected to be easily-read sentences, sometimes followed by a colon and an inner error message when applicable.

0.57 Breaking changes

IFluidConfiguration removed

The IFluidConfiguration interface and related properties were deprecated in 0.55, and have now been removed. This includes the configuration member of IContainerContext and ContainerContext.

Driver error constructors' signatures have changed

All error classes defined in @fluidframework/driver-utils now require the props parameter in their constructors, and props must include the property driverVersion: string | undefined (via type DriverErrorTelemetryProps). Same for helper functions that return new error objects.

Additionally, createGenericNetworkError's signature was refactored to combine canRetry and retryAfterMs into a single required parameter retryInfo.

IFluidObject removed from IFluidDataStoreContext scope

IFluidObject is deprecated and being replaced with FluidObject. IFluidObject is now removed from IFluidDataStoreContext's scope:

- readonly scope: IFluidObject & FluidObject;
+ readonly scope: FluidObject;

Additionally, the following deprecated fields have been removed from IFluidObject:

  • IFluidDataStoreFactory
  • IFluidDataStoreRegistry

Use FluidObject instead.

Containers isDirty flag behavior has changed

Container is now considered dirty if it's not attached or it is attached but has pending ops. Check https://fluidframework.com/docs/build/containers/#isdirty for further details.

Removed PureDataObject.requestFluidObject_UNSAFE

The requestFluidObject_UNSAFE is removed from the PureDataObject. If you still need to fallback on URIs, use handleFromLegacyUri. We are making this change to encourage retreiving shared objects via handles only.

Modified PureDataObject.getFluidObjectFromDirectory

Going forward, getFluidObjectFromDirectory will not return FluidObject if you have have used to store uri string for a given key. If you still need to fallback on URIs, use handleFromLegacyUri. Also, getFluidObjectFromDirectory now expects callback that is only returning IFluidHandle or undefined. Returnig uri/id (string) is not supported as we want to encourage retreiving shared objects via handles only.

Remove IFluidObject from Aqueduct

IFluidObject is deprecated. In this release we have removed all IFluidObject from the aqueduct package. This impacts the following public apis:

  • getDefaultObjectFromContainer
  • getObjectWithIdFromContainer
  • getObjectFromContainer
  • PureDataObject.getFluidObjectFromDirectory
  • ContainerServiceRegistryEntries
  • SingletonContainerServiceFactory.getService

In general the impact of these changes should be transparent. If you see compile errors related to Fluid object provider types with the above apis, you should transition those usages to FluidObject which is the replacement for the deprecated IFluidObject.

Removing snapshot API from IRuntime

Snapshot API has been removed from IRuntime. Replay tools and snapshot tests are now using summarize API.

Remove Unused IFluidObject Augmentations

The following deprecated provider properties are no longer exposed off of IFluidObject

  • IFluidMountableView
  • IAgentScheduler
  • IContainerRuntime
  • ISummarizer

The interfaces that correspond to the above properties continue to exist, and can use directly, or with the IFluidObject replacement FluidObject

Duplicate extractLogSafeErrorProperties removed

The helper function extractLogSafeErrorProperties existed in both telemetry-utils and common-utils packages. The copy in common-utils was out of date and unused in this repo, and has now been removed.

Code proposal rejection removed

Rejection functionality has been removed from Quorum. As a result, the "codeDetailsProposed" event on IContainer now provides an ISequencedProposal rather than an IPendingProposal.

ContainerRuntime.createDataStore return type changed

ContainerRuntime.createDataStore will now return an an IDataStore instead of an IFluidRouter. This change does not break the interface contract, as the former inherits the latter, however the concrete object will be a DataStore instance, which does not inherit IFluidDataStoreChannel as before.

Root datastore creation may throw an exception in case of name conflicts

When creating root datastores using ContainerRuntime.createRootDataStore or ContainerRuntime._createDataStoreWithProps, in case of a name conflict (when attempting to create a root datastore with a name which already exists in the document), an exception of type GenericError may be thrown from the function.

0.56 Breaking changes

MessageType.Save and code that handled it was removed

The Save operation type was deprecated and has now been removed. This removes MessageType.Save from protocol-definitions, save;${string}: ${string} from SummarizeReason in the container-runtime package, and MessageFactory.createSave() from and server-test-utils.

Removed IOdspResolvedUrl.sharingLinkToRedeem

The sharingLinkToRedeem property is removed from the IOdspResolvedUrl interface. The property can be accesed from IOdspResolvedUrl.shareLinkInfo instead.

Removed url from ICreateBlobResponse

The unused url property of ICreateBlobResponse in @fluidframework/protocol-definitions has been removed

readonly removed from IDeltaManager, DeltaManager, and DeltaManagerProxy

The readonly property was deprecated and has now been removed from IDeltaManager from container-definitions. Additionally, readonly has been removed from the implementations in DeltaManager and DeltaManagerProxy from container-loader. To replace its functionality, use readOnlyInfo.readonly instead.

Synthesize Decoupled from IFluidObject and Deprecations Removed

DependencyContainer now takes a generic argument, as it is no longer directly couple to IFluidObject. The ideal pattern here would be directly pass the provider or FluidObject interfaces you will register. As a short term solution you could also pass IFluidObject, but IFluidObject is deprecated, so will need to be removed if used here. Examples:

// the old way
const dc = new DependencyContainer();
dc.register(IFluidHTMLView, MockLoadable());

// FluidObject option
const dc = new DependencyContainer<FluidObject<IFluidHTMLView>>();
dc.register(IFluidHTMLView, MockLoadable());

// Provider option
const dc = new DependencyContainer<IProvideFluidHTMLView>();
dc.register(IFluidHTMLView, MockLoadable());

// Short term IFluidObject option
const dc = new DependencyContainer<IFluidObject>();
dc.register(IFluidHTMLView, MockLoadable());

The following members have been removed from IFluidDependencySynthesizer:

  • registeredTypes - unused and no longer supported. has can replace most possible usages
  • register - create new DependencyContainer and add existing as parent
  • unregister - create new DependencyContainer and add existing as parent
  • getProvider - use has and synthesize to check or get provider respectively

The following types have been removed or changed. These changes should only affect direct usages which should be rare. Existing synthesizer api usage is backwards compatible:

  • FluidObjectKey - removed as IFluidObject is deprecated
  • NonNullableFluidObject - removed as IFluidObject is deprecated. use typescripts NonNullable instead
  • AsyncRequiredFluidObjectProvider - Takes FluidObject types rather than keys
  • AsyncOptionalFluidObjectProvider - Takes FluidObject types rather than keys
  • AsyncFluidObjectProvider - Takes FluidObject types rather than keys
  • FluidObjectProvider - Takes FluidObject types rather than keys
  • ProviderEntry - no longer used
  • DependencyContainerRegistry - no longer used

codeDetails removed from Container

In release 0.53, the codeDetails member was removed from IContainer. It is now also removed from Container. To inspect the code details of a container, instead use the getSpecifiedCodeDetails() and getLoadedCodeDetails() methods.

wait() methods removed from map and directory

The wait() methods on ISharedMap and IDirectory were deprecated in 0.55 and have now been removed. See the deprecation notice for migration advice if you currently use these APIs.

Removed containerPath from DriverPreCheckInfo

The containerPath property of DriverPreCheckInfo was deprecated and has now been removed. To replace its functionality, use Loader.request().

Removed SharedObject.is

The is method is removed from SharedObject. This was being used to detect SharedObjects stored inside other SharedObjects (and then binding them), which should not be happening anymore. Instead, use handles to SharedObjects.

Removed IContainerContext.id and ContainerContext.id

The id property of IContainerContext was deprecated and now removed. The id property of ContainerContext was deprecated and now removed. id should not be exposed at runtime level anymore. Instead, get from container's resolvedURL if necessary.

Remove raiseContainerWarning property

The raiseContainerWarning property is removed from the following interfaces in release 0.56:

  • IContainerRuntime
  • IFluidDataStoreContext
  • IFluidDataStoreRuntime

This property was also deprecated in IContainerContext and will be removed in a future release. Application developers should generate their own telemetry/logging events.

Set logger property as optional parameter in IContainerContext

The logger property from IContainerContext is now optional. It will be removed completely in a future release. Use taggedLogger instead. Loggers passed to ContainerContext will need to support tagged events.

0.55 Breaking changes

container-loader interfaces return IQuorumClients rather than IQuorum

The getQuorum() method on IContainer and the quorum member of IContainerContext return an IQuorumClients rather than an IQuorum. See the prior breaking change notice announcing this change for recommendations on migration.

SharedObject summary and GC API changes

SharedObject.snapshotCore is renamed to summarizeCore and returns ISummaryTreeWithStats. Use SummaryTreeBuilder to create a summary instead of ITree.

SharedObject.getGCDataCore is renamed to processGCDataCore and a SummarySerializer is passed as a parameter. The method should run the serializer over the handles as before and does not need to return anything. The caller will extract the GC data from the serializer.

IChannel.summarize split into sync and async

IChannel now has two summarization methods instead of a single synchronous summarize. getAttachSummary is synchronous to prevent channel modifications during summarization, summarize is asynchronous.

IFluidSerializer moved to shared-object-base

IFluidSerializer has moved packages from core-interfaces to shared-object-base. replaceHandles method is renamed to encode. decode method is now required. IFluidSerializer in core-interfaces is now deprecated and will be removed in a future release.

Removed IFluidSerializer from IFluidDataStoreRuntime

IFluidSerializer in IFluidDataStoreRuntime was deprecated in version 0.53 and is now removed.

IFluidConfiguration deprecated and IFluidConfiguration member removed from ContainerRuntime

The IFluidConfiguration interface from @fluidframework/core-interfaces has been deprecated and will be removed in an upcoming release. This will include removal of the configuration member of the IContainerContext from @fluidframework/container-definitions and ContainerContext from @fluidframework/container-loader at that time. To inspect whether the document is in readonly state, you should instead query container.readOnlyInfo.readonly.

The IFluidConfiguration member of ContainerRuntime from @fluidframework/container-runtime has also been removed.

wait() methods deprecated on map and directory

The wait() methods on ISharedMap and IDirectory have been deprecated and will be removed in an upcoming release. To wait for a change to a key, you can replicate this functionality with a helper function that listens to the change events.

const directoryWait = async <T = any>(directory: IDirectory, key: string): Promise<T> => {
    const maybeValue = directory.get<T>(key);
    if (maybeValue !== undefined) {
        return maybeValue;
    }

    return new Promise((resolve) => {
        const handler = (changed: IValueChanged) => {
            if (changed.key === key) {
                directory.off("containedValueChanged", handler);
                const value = directory.get<T>(changed.key);
                if (value === undefined) {
                    throw new Error("Unexpected containedValueChanged result");
                }
                resolve(value);
            }
        };
        directory.on("containedValueChanged", handler);
    });
};

const foo = await directoryWait<Foo>(this.root, fooKey);

const mapWait = async <T = any>(map: ISharedMap, key: string): Promise<T> => {
    const maybeValue = map.get<T>(key);
    if (maybeValue !== undefined) {
        return maybeValue;
    }

    return new Promise((resolve) => {
        const handler = (changed: IValueChanged) => {
            if (changed.key === key) {
                map.off("valueChanged", handler);
                const value = map.get<T>(changed.key);
                if (value === undefined) {
                    throw new Error("Unexpected valueChanged result");
                }
                resolve(value);
            }
        };
        map.on("valueChanged", handler);
    });
};

const bar = await mapWait<Bar>(someSharedMap, barKey);

As-written above, these promises will silently remain pending forever if the key is never set (similar to current wait() functionality). For production use, consider adding timeouts, telemetry, or other failure flow support to detect and handle failure cases appropriately.

Remove Legacy Data Object and Factories

In order to ease migration to the new Aqueduct Data Object and Data Object Factory generic arguments we added legacy versions of those classes in version 0.53.

In this release we remove those legacy classes: LegacyDataObject, LegacyPureDataObject, LegacyDataObjectFactory, and LegacyPureDataObjectFactory

It is recommend you migrate to the new generic arguments before consuming this release. Details are here: 0.53: Generic Argument Changes to DataObjects and Factories

Removed innerRequestHandler

innerRequestHandler is removed from @fluidframework/request-handlers package, and its usage is removed from BaseContainerRuntimeFactory and ContainerRuntimeFactoryWithDefaultDataStore. If you are using these container runtime factories, attempting to access internal data stores via request() will result in 404 responses.

If you rely on request() access to internal root data stores, you can add rootDataStoreRequestHandler to your list of request handlers on the runtime factory.

It is not recommended to provide request() access to non-root data stores, but if you currently rely on this functionality you can add a custom request handler that calls runtime.IFluidHandleContext.resolveHandle(request) just like innerRequestHandler used to do.

Aqueduct and IFluidDependencySynthesizer changes

The type DependencyContainerRegistry is now deprecated and no longer used. In it's place the DependencyContainer class should be used instead.

The following classes in Aqueduct have been changed to no longer take DependencyContainerRegistry and to use DependencyContainer instead: BaseContainerRuntimeFactory, and ContainerRuntimeFactoryWithDefaultDataStore

In both cases, the third parameter to the constructor has been changed from providerEntries: DependencyContainerRegistry = [] to dependencyContainer?: IFluidDependencySynthesizer. If you were previously passing an emptry array, [] you should now pass undefined. If you were passing in something besides an empty array, you will instead create new DependencyContainer and register your types, and then pass that, rather than the type directly:

+const dependencyContainer = new DependencyContainer();
+dependencyContainer.register(IFluidUserInformation,async (dc) => userInfoFactory(dc));

 export const fluidExport = new ContainerRuntimeFactoryWithDefaultDataStore(
     Pond.getFactory(),
     new Map([
         Pond.getFactory().registryEntry,
     ]),
-    [
-        {
-            type: IFluidUserInformation,
-            provider: async (dc) => userInfoFactory(dc),
-        },
-    ]);
+    dependencyContainer);

0.54 Breaking changes

Removed readAndParseFromBlobs from driver-utils

The readAndParseFromBlobs function from driver-utils was deprecated in 0.44, and has now been removed from the driver-utils package.

Loader now returns IContainer instead of Container

The following public API functions on Loader, from "@fluidframework/container-loader" package, now return IContainer:

  • createDetachedContainer
  • rehydrateDetachedContainerFromSnapshot
  • resolve

All of the required functionality from a Container instance should be available on IContainer. If the function or property you require is not available, please file an issue on GitHub describing which function and what you are planning on using it for. They can still be used by casting the returned object to Container, i.e. const container = await loader.resolve(request) as Container;, however, this should be avoided whenever possible and the IContainer API should be used instead.

getQuorum() returns IQuorumClients from within the container

The getQuorum() method on IContainerRuntimeBase, IFluidDataStoreContext, and IFluidDataStoreRuntime now returns an IQuorumClients rather than an IQuorum. IQuorumClients retains the ability to inspect the clients connected to the collaboration session, but removes the ability to access the quorum proposals. It is not recommended to access the quorum proposals directly.

A future change will similarly convert calls to getQuorum() on IContainer and IContainerContext to return an IQuorumClients. If you need to access the code details on the IContainer, you should use the getSpecifiedCodeDetails() API instead. If you are currently accessing the code details on the IContainerContext, a temporary getSpecifiedCodeDetails() method is exposed there as well to aid in migration. However, accessing the code details from the container context is not recommended and this migratory API will be removed in an upcoming release. It is instead recommended to only inspect code details in the code loader while loading code, or on IContainer as part of code upgrade scenarios (i.e. when calling IContainer's proposeCodeDetails()). Other uses are not supported.

SharedNumberSequence and SharedObjectSequence deprecated

The SharedNumberSequence and SharedObjectSequence have been deprecated and are not recommended for use. To discuss future plans to support scenarios involving sequences of objects, please see Github issue 8526.

Additionally, useSyncedArray() from @fluid-experimental/react has been removed, as it depended on the SharedObjectArray.

IContainer interface updated to complete 0.53 changes

The breaking changes introduced in IContainer interface updated to expose actively used Container public APIs have now been completed in 0.54. The following additions to the IContainer interface are no longer optional but rather mandatory:

  • connectionState
  • connected
  • audience
  • readOnlyInfo

The following "alpha" APIs are still optional:

  • setAutoReconnect() (alpha)
  • resume() (alpha)
  • clientId (alpha)
  • forceReadonly() (alpha)

The deprecated codeDetails API, which was marked as optional on the last release, has now been removed.

0.53 Breaking changes

IContainer interface updated to expose actively used Container public APIs

In order to have the IContainer interface be the active developer surface that is used when interacting with a Container instance, it has been updated to expose the APIs that are necessary for currently used behavior. The motivation here is to move away from using the Container class when only its type is required, and to use the IContainer interface instead.

The following values have been added (NOTE: some of these are marked with an @alpha tag and may be replaced in the future with a breaking change as the IContainer interface is finalized):

  • connectionState
  • connected
  • setAutoReconnect() (alpha)
  • resume() (alpha)
  • audience
  • clientId (alpha)
  • readOnlyInfo
  • forceReadonly() (alpha)

Additionally, codeDetails which was already deprecated before is now marked as optional and ready for removal after the next release.

Remove getLegacyInterval() and delete() from sequence dds

getLegacyInterval() was only being used by the deprecated IntervalCollection.delete(). The alternative to IntervalCollection.delete() is IntervalCollection.removeIntervalById().

readOnly and readOnlyPermissions removed from Container

The readOnly and readOnlyPermissions properties from Container in container-loader was deprecated in 0.35, and has now been removed. To replace its functionality, use readOnlyInfo by accessing readOnlyInfo.readonly and readOnlyInfo.permissions respectively.

Generic Argument Changes to DataObjects and Factories

DataObject and PureDataObject used to take 3 generic type parameters. This has been collasped to a single generic argument. This new format takes the same types, but allows for easier exclusion or inclusion of specific types, while also being more readable.

In general the existing data object generic parameters map to the new generic parameter as follow: DataObject<O,S,E> maps to DataObject<{OptionalProviders: O, InitialState: S, Events: E}>

We would frequently see default values for generic paramaters, in order to set a following parameter. This is no longer necessary. If you see a generic parameter with a type of {}, undefined, object, unknown, any, IEvent, or IFluidObject is not needed, and can now be excluded.

Here are some examples:

  • DataObject<{}, any, IEvent> becomes DataObject
  • DataObject<IFluidUserInformation> becomes DataObject<{OptionalProviders: IFluidUserInformation}>
  • DataObject<{}, RootDataObjectProps> becomes DataObject<{InitialState: RootDataObjectProps}>
  • DataObject<object, undefined, IClickerEvents> becomes DataObject<{Events: IClickerEvents}>

Very similar changes have been made to DataObjectFactory and PureDataObjectFactory. Rather than 4 generic arguments it is reduced to 2. The first is still the same, and is the DataObject, the second is the same type the DataObject itself takes. However, this detail should not be important, as will this change has come improved type inference, so it should no longer be necessary to set any generic arguments on the factory.

here are some examples:

  • new DataObjectFactory<SpacesStorage, undefined, undefined, IEvent> becomes new DataObjectFactory
  • DataObjectFactory<MockComponentFooProvider, object, undefined> becomes DataObjectFactory<MockComponentFooProvider>

Above I've used DataObject, and DataObjectFactory however the same changes apply to PureDataObject and PureDataObjectFactory.

To ease transition we've also added LegacyDataObject, LegacyPureDataObject, LegacyDataObjectFactory, and LegacyPureDataObjectFactory. These types have the same generic parameters as the types before this change, and can be used as a drop in replacement, but please move away from these types asap, as they will be removed in a following release.

Remove loader property from MockFluidDataStoreContext class

The loader property from MockFluidDataStoreContext class was deprecated in release 0.37 and is now removed. Refer the following deprecation warning: Loader in data stores deprecated

maxMessageSize removed from IConnectionDetails and IDocumentDeltaConnection

The maxMessageSize property from IConnectionDetails and IDocumentDeltaConnection was deprecated in 0.51, and has now been removed from the container-definitions and driver-definitions packages respectively. To replace its functionality, use serviceConfiguration.maxMessageSize.

Remove IntervalCollection.getView() from sequence dds

The IntervalCollection.getView() was removed. If you were calling this API, you should instead refer to the IntervalCollection itself directly in places where you were using the view.

Moved ICodeDetailsLoader and IFluidModuleWithDetails interface to @fluidframework/container-definitions

The ICodeDetailsLoader and IFluidModuleWithDetails interface are deprecated in @fluidframework/container-loader and moved to @fluidframework/container-definitions. The ICodeDetailsLoader interface should be imported from @fluidframework/container-definition package. The ICodeDetailsLoader and IFluidModuleWithDetails from @fluidframework/container-loader will be removed from @fluidframework/container-loader in further releases.

Removed errorMessage property from ISummaryNack interface

The errorMessage property from the ISummaryNack interface was deprecated in 0.43, and has now been removed from the protocol-definitions package. To replace its functionality, use the message property.

ISequencedDocumentMessage arg removed from SharedMap and SharedDirectory events

The ISequencedDocumentMessage argument in events emitted from SharedMap and SharedDirectory (the "valueChanged" and "clear" events) has been removed. It is not recommended to access the protocol layer directly. Note that if you were leveraging the this argument of these events, you will need to update your event listeners due to the arity change.

Moved @fluidframework/core-interface#fluidPackage.ts to @fluidframework/container-definition#fluidPackage.ts

Moved the following interfaces and const from @fluidframework/core-interface to @fluidframework/container-definitions:

  • IFluidPackageEnvironment
  • IFluidPackage
  • isFluidPackage
  • IFluidCodeDetailsConfig
  • IFluidCodeDetailsConfig
  • IFluidCodeDetails
  • IFluidCodeDetailsComparer
  • IProvideFluidCodeDetailsComparer
  • IFluidCodeDetailsComparer

They are deprecated from @fluidframework/core-interface and would be removed in future release. Please import them from @fluidframework/container-definitions.

Deprecated IFluidSerializer in IFluidDataStoreRuntime

IFluidSerializer should only be used by DDSs to serialize data and they should use the one created by SharedObject.

Errors thrown to DDS event handlers

Before this release, exceptions thrown from DDS event handlers resulted in Fluid Framework reporting non-error telemetry event and moving forward as if nothing happened. Starting with this release, such exceptions will result in critical error, i.e. container will be closed with such error and hosting app will be notified via Container's "closed" event. This will either happen immediately (if exception was thrown while processing remote op), or on later usage (if exception was thrown on local change). DDS will go into "broken" state and will keep throwing error on amy attempt to make local changes. This process is supposed to be a catch-call case for cases where listeners did not do due diligence or have no better way to handle their errors. If possible, it's recommended for DDS event listeners to not throw exceptions, but rather handle them appropriately without involving DDS itself. The purpose of this change to ensure that data model stays always synchronized with data projection that event listeners are building. If event listener is not able to fully / correctly process change event, that likely means data synchronization is broken and it's not safe to continue (and potentially, corrupt document).

0.52 Breaking changes

chaincodePackage removed from Container

The chaincodePackage property on Container was deprecated in 0.28, and has now been removed. Two new APIs have been added to replace its functionality, getSpecifiedCodeDetails() and getLoadedCodeDetails(). Use getSpecifiedCodeDetails() to get the code details currently specified for the Container, or getLoadedCodeDetails() to get the code details that were used to load the Container.

OdspDocumentInfo type replaced with OdspFluidDataStoreLocator interface

The OdspDocumentInfo type is removed from odsp-driver package. It is removed from packages\drivers\odsp-driver\src\contractsPublic.ts and replaced with OdspFluidDataStoreLocator interface as parameter in OdspDriverUrlResolverForShareLink.createDocumentUrl(). If there are any instances of OdspDocumentInfo type used, it can be simply replaced with OdspFluidDataStoreLocator interface.

Replace createCreateNewRequest function with createOdspCreateContainerRequest function

The createCreateNewRequest() is removed and replaced with createOdspCreateContainerRequest() in the odsp-driver package. If any instances of createCreateNewRequest() are used, replace them with createOdspCreateContainerRequest() by importing it from @fluidframework/odsp-driver package.

Deprecate IFluidObject and introduce FluidObject

This release deprecates the interface IFluidObject and introduces the utility type FluidObject. The primary reason for this change is that the module augmentation used by IFluidObject creates excessive type coupling where a small breaking change in any type exposed off IFluidObject can lead to type error in all usages of IFluidObject. On investigation we also found that the uber type IFluidObject wasn't genenerally necessary, as consumers generally only used a small number of specific types that they knew in advance.

Given these points, we've introduced FluidObject. FluidObject is a utility type that is used in both its generic and non-generic forms.

The non-generic FluidObject is returned or taken in cases where the specific functionally isn't known, or is different based on scenario. You'll see this usage for things like scope and the request pattern.

The non-generic FluidObject is a hint that the generic form of FluidObject should be used to inspect it. For example

    const provider: FluidObject<IFluidHTMLView> = requestFluidObject(container, "/");
    if(provider.IFluidHTMLView !== undefined){
        provider.IFluidHTMLView.render(div)
    }

If you want to inspect for multiple interfaces via FluidObject, you can use an intersection:

    const provider: FluidObject<IFluidHTMLView & IFluidMountableView> = requestFluidObject(container, "/");

Please begin reducing the usage of IFluidObject and moving to FluidObject. If you find any cases that FluidObject doesn't support please file an issue.

0.51 Breaking changes

maxMessageSize property has been deprecated from IConnectionDetails and IDocumentDeltaConnection

maxMessageSize is redundant and will be removed soon. Please use the serviceConfiguration.maxMessageSize property instead.

_createDataStoreWithProps and IFluidDataStoreChannel

ContainerRuntime._createDataStoreWithProps() is made consistent with the rest of API (same API on IContainerRuntimeBase interface, all other create methods to create data store) and returns now only IFluidRouter. IFluidDataStoreChannel is internal communication mechanism between ContainerRuntime and data stores and should be used only for this purpose, by data store authors. It is not a public interface that should be exposed by data stores. While casting IFluidRouter objects returned by various data store creation APIs to IFluidDataStoreChannel would continue to work in this release, this is not supported and will be taken away in next releases due to upcoming work in GC & named component creation space.

Deprecated Loader._create is removed

Removing API Loader._create from @fluidframework/container-loader, which was an interim replacement of the Loader constructor API change in version 0.28. Use the Loader constructor with the ILoaderProps instead.

Stop exporting internal class CollabWindowTracker

CollabWindowTracker is an internal implementation for @fluidframework/container-loader and should never been exported.

base-host package removed

The @fluidframework/base-host package has been removed. See the quick-start guide for recommended hosting practices.

If you were using the UpgradeManager utility from this package, external access to Quorum proposals is planned to be deprecated and so this is no longer recommended. To upgrade code, instead use the Container API proposeCodeDetails.

Registers removed from sequence and merge-tree

The @fluidframework/sequence and @fluidframework/merge-tree packages provided cut/copy/paste functionalities that built on a register concept. These functionalities were never fully implemented and have been removed.

Token fetch errors have proper errorType

If the tokenFetcher provided by the host thrown an error, this error will be propagated through the code with errorType "fetchTokenError". Previously, the errorType was either empty, or recently and incorrectly, "dataProcessingError".

0.50 Breaking changes

OpProcessingController removed

OpProcessingController has been deprecated for very long time. It's being removed in this release. Please use LoaderContainerTracker instead (see microsoft#7784 as an example of changes required) If you can't make this transition, you can always copy implementation of LoaderContainerTracker to your repo and maintain it. That said, it has bugs and tests using it are easily broken but subtle changes in reconnection logic, as evident from PRs #7753, #7393)

Expose isDirty flag in the FluidContainer

The isDirty flag is exposed onto the FluidContainer. The property is already exposed on the Container and it is just piped up to the FluidContainer.

get-container API changed

The signature of methods getTinyliciousContainer and getFRSContainer exported from the get-container package has been changed to accomodate the new container create flow. Both methods now return a tuple of the container instance and container ID associated with it. The documentId parameter is ignored when a new container is requested. Client applications need to use the ID returned by the API. The get-container API is widely used in multiple sample applications across the repository. All samples were refactored to reflect the change in the API. External samples consuming these methods should be updated accordingly.

SharedCell serialization

SharedCell serialization format has changed. Values stored from previous versions will be broken.

Expose saved and dirty events in FluidContainer

The saved and dirty container events are exposed onto the FluidContainer. The events are emitted on the Container already.

Deprecated bindToContext in IFluidDataStoreChannel

bindToContext in IFluidDataStoreChannel has been deprecated. This should not be used to explicitly bind data stores. Root data stores will automatically be bound to container. Non-root data stores will be bound when their handles are stored in an already bound DDS.

0.49 Breaking changes

Deprecated dirty document events and property removed from ContainerRuntime

The isDocumentDirty() method, "dirtyDocument" and "savedDocument" events that were deprecated in 0.35 have now been removed. For more information on replacements, see DirtyDocument events and property.

DeltaManager removed from fluid-framework export

The DeltaManager class, the IConnectionArgs interface, the IDeltaManagerInternalEvents interface, and the ReconnectedMode enum have been removed from @fluidframework/container-loader package exports. Instead of DeltaManager, IDeltaManager should be used where appropriate.

resumeInternal made private

The protected function resumeInternal under the class Container has been made private.

url removed from ICreateBlobResponse

The unused url property of ICreateBlobResponse in @fluidframework/protocol-definitions has been removed

encoding type change

The encoding property of IBlob in @fluidframework/protocol-definitions has changed type from string to "utf-8" | "base64" to match the only supported values.

0.48 Breaking changes

client-api package removed

The @fluid-internal/client-api package was deprecated in 0.20 and has now been removed. Usage of this package should be replaced with direct usage of the Loader, FluidDataStoreRuntime, ContainerRuntime, and other supported functionality.

SignalManager removed from fluid-framework export

The SignalManager and Signaler classes have been removed from the @fluid-framework/fluid-static and fluid-framework package exports and moved to the @fluid-experimental/data-objects package. This is because of its experimental state and the intentional omission of experimental features from fluid-framework. Users should instead import the classes from the @fluid-experimental/data-objects package.

MockLogger removed from @fluidframework/test-runtime-utils

MockLogger is only used internally, so it's removed from @fluidframework/test-runtime-utils.

0.47 Breaking changes

Property removed from IFluidDataStoreContext

  • the existing property from IFluidDataStoreContext (and FluidDataStoreContext) has been removed.

Changes to IFluidDataStoreFactory

  • The existing parameter from the instantiateDataStore function is now mandatory to differentiate creating vs loading.

FlushMode enum values renamed

FlushMode enum values from @fluidframework/runtime-definitions have ben renamed as following:

  • FlushMode.Manual to FlushMode.TurnBased
  • FlushMode.Automatic to FlushMode.Immediate

name removed from ContainerSchema

The name property on the ContainerSchema was used for multi-container scenarios but has not materialized to be a useful schema property. The feedback has been negative to neutral so it is being removed before it becomes formalized. Support for multi-container scenarios, if any is required, will be addressed as a future change.

Anonymous return types for container calls in client packages

createContainer and getContainer in @fluidframework/azure-client and @fluidframework/tinylicious-client will no longer return typed objects but instead will return an anonymous type. This provide the flexibility that comes with tuple deconstruction with the strong typing of property names.

// `@fluidframework/azure-client`
createContainer(containerSchema: ContainerSchema): Promise<{
    container: FluidContainer;
    services: AzureContainerServices;
}>;
getContainer(id: string, containerSchema: ContainerSchema): Promise<{
    container: FluidContainer;
    services: AzureContainerServices;
}>;

// `@fluidframework/tinylicious-client`
createContainer(containerSchema: ContainerSchema): Promise<{
    container: FluidContainer;
    services: TinyliciousContainerServices;
}>;
getContainer(id: string, containerSchema: ContainerSchema): Promise<{
    container: FluidContainer;
    services: TinyliciousContainerServices;
}>;

createContainer and getContainer response objects properties renamed

For all *-client packages createContainer and getContainer would return an object with fluidContainer and containerServices. These have been renamed to the following for brevity.

  • fluidContainer => container
  • containerServices => services
// old
const { fluidContainer, containerServices } = client.getContainer(...);

// new
const { container, services } = client.getContainer(...);

tinylicious and azure clients createContainer now detached

Creating a new container now requires and explicit attach step. All changes made in between container creation, and attaching, will be persisted as part of creation and guaranteed to always be available to users. This allows developers to initialize initialObjects with state before the container is connected to the service. It also enables draft creation modes.

// old
const { fluidContainer } = client.createContainer(...);

// new
const { container } = client.createContainer(...);
const id = container.attach();

container id is returned from new attach() and not exposed on the container

Because we now have an explicit attach flow, the container id is part of that flow as well. The id is returned from the attach() call.

// old
const { fluidContainer } = client.createContainer(...);
const containerId = fluidContainer.id;

// new
const { container } = client.createContainer(...);
const containerId = container.attach();

AzureClient initialization as a singular config

AzureClient now takes a singular config instead of multiple parameters. This enables easier scaling of config properties as we introduce new functionality.

// old
const connectionConfig = {...};
const logger = new MyLogger();
const client = new AzureClient(connectionConfig, logger);

// new
const config = {
    connection: {...},
    logger: new MyLogger(...)
}
const client = new AzureClient(config);

0.46 Breaking changes

@fluid-experimental/fluid-framework package name changed

The @fluid-experimental/fluid-framework package has been renamed to now be fluid-framework. The scope has been removed.

FrsClient has been renamed to AzureClient and moved out of experimental state

The @fluid-experimental/frs-client package for connecting with the Azure Fluid Relay service has been renamed to now be @fluidframework/azure-client. This also comes with the following name changes for the exported classes and interfaces from the package:

  • FrsClient -> AzureClient
  • FrsAudience -> AzureAudience
  • IFrsAudience -> IAzureAudience
  • FrsMember -> AzureMember
  • FrsConnectionConfig -> AzureConnectionConfig
  • FrsContainerConfig -> AzureContainerConfig
  • FrsResources -> AzureResources
  • FrsAzFunctionTokenProvider -> AzureFunctionTokenProvider
  • FrsUrlResolver -> AzureUrlResolver

documentId removed from IFluidDataStoreRuntime and IFluidDataStoreContext

  • documentId property is removed from IFluidDataStoreRuntime and IFluidDataStoreContext. It is a document level concept and is no longer exposed from data store level.

@fluid-experimental/tinylicious-client package name changed

The @fluid-experimental/tinylicious-client package has been renamed to now be @fluidframework/tinylicious-client.

@fluid-experimental/fluid-static package name changed

The @fluid-experimental/fluid-static package has been renamed to now be @fluidframework/fluid-static.

TinyliciousClient and AzureClient container API changed

Tinylicious and Azure client API changed to comply with the new container creation flow. From now on, the new container ID will be generated by the framework. In addition to that, the AzureContainerConfig parameter's got decommissioned and the logger's moved to the client's constructor.

// Create a client using connection settings and an optional logger
const client = new AzureClient(connectionConfig, logger);
// Create a new container
const { fluidContainer, containerServices } = await client.createContainer(containerSchema);
// Retrieve the new container ID
const containerId = fluidContainer.id;
// Access the existing container
const { fluidContainer, containerServices }= await client.getContainer(containerId, containerSchema);

0.45 Breaking changes

Changes to local testing in insecure environments and associated bundle size increase

Previously the @fluidframework/common-utils package exposed a setInsecureContextHashFn function so users could set an override when testing locally in insecure environments because the crypto.subtle library is not available. This is now done automatically as a fallback and the function is removed. The fallback exists as a dynamic import of our equivalent Node platform implementation, and will show as a chunk named "FluidFramework-HashFallback" and be up to ~25KB parsed in size. It will not be served when running normally in a modern browser.

Property removed from IFluidDataStoreRuntime

  • the existing property from IFluidDataStoreRuntime (and FluidDataStoreRuntime) has been removed. There is no need for this property in the class, as the flag can be supplied as a parameter to FluidDataStoreRuntime.load or to the constructor of FluidDataStoreRuntime. The IFluidDataStoreFactory.instantiateDataStore function has an existing parameter which can be supplied to the FluidDataStoreRuntime when the latter is created.

Changes to client-api Document

  • The existing property from the Document class in @fluid-internal/client-api has been removed. It can be assumed that the property would have always been true.

Changes to PureDataObject

  • The initializeInternal and the finishInitialization functions have a mandatory existing parameter to differentiate creating vs loading.

Changes to DataObject

  • The initializeInternal function has a mandatory existing parameter to differentiate creating vs loading.

Changes to PureDataObjectFactory

  • The createDataObject in PureDataObjectFactory has a mandatory existing parameter to differentiate creating vs loading.

webpack-fluid-loader package name changed

The webpack-fluid-loader utility was previously available from a package named @fluidframework/webpack-fluid-loader. However, since it is a tool and should not be used in production, it is now available under the tools scope @fluid-tools/webpack-fluid-loader.

Loggers without tag support now deprecated in ContainerContext

The logger property of ContainerContext has been marked deprecated. Loggers passed to ContainerContext will need to support tagged events.

Creating new containers with Container.load is no longer supported

getHashedDocumentId is now async

@fluidframework/odsp-driver's getHashedDocumentId function is now async to take advantage of shared hashing functionality. It drops its dependency on the sha.js package as a result, which contributed ~37KB to the parsed size of the odsp-driver bundle.

0.44 Breaking changes

Property removed from the ContainerRuntime class

  • the existing property from ContainerRuntime has been removed. Inspecting this property in order to decide whether or not to perform initialization operations should be replaced with extending the RuntimeFactoryHelper abstract class from @fluidframework/runtime-utils and overriding instantiateFirstTime and instantiateFromExisting. Alternatively, any class implementing IRuntimeFactory can supply an existing parameter to the instantiateRuntime method.

attach() should only be called once

Container.attach() will now throw if called more than once. Once called, it is responsible for retrying on retriable errors or closing the container on non-retriable errors.

Loader access in data stores is removed

Following the deprecation warning Loader in data stores deprecated, the associated APIs have now been removed. In addition to the original deprecation notes, users will automatically have an ILoader available on the container scope object as the ILoader property if the container was created through a Loader.

0.43 Breaking changes

TinyliciousClient and FrsClient are no longer static

TinyliciousClient and FrsClient global static properties are removed. Instead, object instantiation is now required.

Property removed from the Container class

Routerlicious Driver DeltaStorageService constructor changed

DeltaStorageService from @fluidframework/routerlicious-driver now takes a RestWrapper as the second constructor parameter, rather than a TokenProvider.

addGlobalAgentSchedulerAndLeaderElection removed

In 0.38, the IContainerRuntimeOptions option addGlobalAgentSchedulerAndLeaderElection was added (on by default), which could be explicitly disabled to remove the built-in AgentScheduler and leader election functionality. This flag was turned off by default in 0.40. In 0.43 the flag (and the functionality it enabled) has been removed.

See AgentScheduler-related deprecations for more information on this deprecation and back-compat support, as well as recommendations on how to migrate away from the built-in.

Creating new containers with Container.load has been deprecated

  • Container.load with inexistent files will fail instead of creating a new container. Going forward, please use Container.createDetached for this scenario.
  • To enable the legacy scenario, set the createOnLoad flag to true inside IContainerLoadOptions. Loader.request and Loader.resolve will enable the legacy scenario if the IClientDetails.environment property inside IRequest.headers contains the string enable-legacy-create-on-load (see LegacyCreateOnLoadEnvironmentKey from @fluidframework/container-loader).

Changes to client-api

  • The load function from document.ts will fail the container does not exist. Going forward, please use the create function to handle this scenario.

0.42 Breaking changes

0.42 package renames

We have renamed some packages to better reflect their status. See the npm package scopes page in the wiki for more information about the npm scopes.

  • @fluidframework/react-inputs is renamed to @fluid-experimental/react-inputs
  • @fluidframework/react is renamed to @fluid-experimental/react

IContainerRuntimeEvents changes

  • fluidDataStoreInstantiated has been removed from the interface and will no longer be emitted by the ContainerRuntime.

IContainerRuntime property removed

  • the existing property from IContainerRuntime has been removed.

Removed IParsedUrl interface, parseUrl, getSnapshotTreeFromSerializedContainer and convertProtocolAndAppSummaryToSnapshotTree api from export

These interface and apis are not supposed to be used outside the package. So stop exposing them.

0.41 Breaking changes

0.41 package renames

We have renamed some packages to better reflect their status. See the npm package scopes page in the wiki for more information about the npm scopes.

  • @fluidframework/last-edited-experimental is renamed to @fluid-experimental/last-edited

LoaderHeader.version could not be null

LoaderHeader.version in ILoader can not be null as we always load from existing snapshot in container.load();

Leadership API surface removed

In 0.38, the leadership API surface was deprecated, and in 0.40 it was turned off by default. In 0.41 it has now been removed. If you still require leadership functionality, you can use a TaskSubscription in combination with an AgentScheduler.

See AgentScheduler-related deprecations for more information on how to use TaskSubscription to migrate away from leadership election.

IContainerContext and Container storage API return type changed

IContainerContext and Container now will always have storage even in Detached mode, so its return type has changed and undefined is removed.

0.40 Breaking changes

AgentScheduler removed by default

In 0.38, the IContainerRuntimeOptions option addGlobalAgentSchedulerAndLeaderElection was added (on by default), which could be explicitly disabled to remove the built-in AgentScheduler and leader election functionality. This flag has now been turned off by default. If you still depend on this functionality, you can re-enable it by setting the flag to true, though this option will be removed in a future release.

See AgentScheduler-related deprecations for more information on this deprecation and back-compat support, as well as recommendations on how to migrate away from the built-in.

ITelemetryProperties may be tagged for privacy purposes

Telemetry properties on logs can (but are not yet required to) now be tagged. This is not a breaking change in 0.40, but users are strongly encouraged to add support for tags (see UPCOMING.md for more details).

[edit]

This actually was a breaking change in 0.40, in that the type of the event parameter of ITelemetryBaseLogger.send changed to a more inclusive type which needs to be accounted for in implementations. However, in releases 0.40 through 0.44, no tagged events are sent to any ITelemetryBaseLogger by the Fluid Framework. We are preparing to do so soon, and will include an entry in BREAKING.md when we do.

IContainerRuntimeDirtyable removed

The IContainerRuntimeDirtyable interface and isMessageDirtyable() method were deprecated in release 0.38. They have now been removed in 0.40. Please refer to the breaking change notice in 0.38 for instructions on migrating away from use of this interface.

Most RouterliciousDocumentServiceFactory params removed

The RouterliciousDocumentServiceFactory constructor no longer accepts the following params: useDocumentService2, disableCache, historianApi, gitCache, and credentials. Please open an issue if these flags/params were important to your project so that they can be re-incorporated into the upcoming IRouterliciousDriverPolicies param.

0.39 Breaking changes

connect event removed from Container

The "connect" event would previously fire on the Container after connect_document_success was received from the server (which likely happens before the client's own join message is processed). This event does not represent a safe-to-use state, and has been removed. To detect when the Container is fully connected, the "connected" event should be used instead.

LoaderHeader.pause

LoaderHeader.pause has been removed. instead of

[LoaderHeader.pause]: true

use

[LoaderHeader.loadMode]: { deltaConnection: "none" }

ODSP driver definitions

A lot of definitions have been moved from @fluidframework/odsp-driver to @fluidframework/odsp-driver-definitions. This change is required in preparation for driver to be dynamically loaded by host. This new package contains all the dependencies of ODSP driver factory (like HostStoragePolicy, IPersistedCache, TokenFetcher) as well as outputs (OdspErrorType). @fluidframework/odsp-driver will continue to have defintions for non-factory functionality (like URI resolver, helper functionality to deal with sharing links, URI parsing, etc.)

ITelemetryLogger Remove redundant methods

Remove deprecated shipAssert debugAssert logException logGenericError in favor of sendErrorEvent as they provide the same behavior and semantics as sendErrorEventand in general are relatively unused. These methods were deprecated in 0.36.

fileOverwrittenInStorage

Please use DriverErrorType.fileOverwrittenInStorage instead of OdspErrorType.epochVersionMismatch

absolutePath use in IFluidHandle is deprecated

Rather than retrieving the absolute path, ostensibly to be stored, one should instead store the handle itself. To load, first retrieve the handle and then call get on it to get the actual object. Note that it is assumed that the container is responsible both for mapping an external URI to an internal object and for requesting resolved objects with any remaining tail of the external URI. For example, if a container has some map that maps /a --> <some handle>, then a request like request(/a/b/c) should flow like request(/a/b/c) --> <some handle> --> <object> --> request(/b/c).

0.38 Breaking changes

IPersistedCache changes

IPersistedCache implementation no longer needs to implement updateUsage() method (removed form interface). Same goes for sequence number / maxOpCount arguments. put() changed from fire-and-forget to promise, with intention of returning write errors back to caller. Driver could use this information to stop recording any data about given file if driver needs to follow all-or-nothing strategy in regards to info about a file. Please note that format of data stored by driver changed. It will ignore cache entries recorded by previous versions of driver.

ODSP Driver Type Unification

This change reuses existing contracts to reduce redundancy improve consistency.

The breaking portion of this change does rename some parameters to some helper functions, but the change are purely mechanical. In most cases you will likely find you are pulling properties off an object individually to pass them as params, whereas now you can just pass the object itself.

// before:
createOdspUrl(
    siteUrl,
    driveId,
    fileId,
    "/",
    containerPackageName,
);
fetchJoinSession(
    driveId,
    itemId,
    siteUrl,
    ...
)
getFileLink(
    getToken,
    something.driveId,
    something.itemId,
    something.siteUrl,
    ...
)

// After:
createOdspUrl({
    siteUrl,
    driveId,
    itemId: fileId,
    dataStorePath: "/",
    containerPackageName,
});

fetchJoinSession(
    {driveId, itemId, siteUrl},
    ...
);

getFileLink(
    getToken,
    something,
    ...
)

ODSP Driver url resolver for share link parameter consolidation

OdspDriverUrlResolverForShareLink constructor signature has been changed to simplify instance creation in case resolver is not supposed to generate share link. Instead of separately specifying constructor parameters that are used to fetch share link there will be single parameter in shape of object that consolidates all properties that are necessary to get share link.

// before:
new OdspDriverUrlResolverForShareLink(
    tokenFetcher,
    identityType,
    logger,
    appName,
);

// After:
new OdspDriverUrlResolverForShareLink(
    { tokenFetcher, identityType },
    logger,
    appName,
);

AgentScheduler-related deprecations

AgentScheduler is currently a built-in part of ContainerRuntime, but will be removed in an upcoming release. Correspondingly, the API surface of ContainerRuntime that relates to or relies on the AgentScheduler is deprecated.

Leadership deprecation

A .leader property and "leader"/"notleader" events are currently exposed on the ContainerRuntime, FluidDataStoreContext, and FluidDataStoreRuntime. These are deprecated and will be removed in an upcoming release.

A TaskSubscription has been added to the @fluidframework/agent-scheduler package which can be used in conjunction with an AgentScheduler to get equivalent API surface:

const leadershipTaskSubscription = new TaskSubscription(agentScheduler, "leader");
if (leadershipTaskSubscription.haveTask()) {
    // client is the leader
}
leadershipTaskSubscription.on("gotTask", () => {
    // client just became leader
});
leadershipTaskSubscription.on("lostTask", () => {
    // client is no longer leader
});

The AgentScheduler can be one of your choosing, or the built-in AgentScheduler can be retrieved for this purpose using ContainerRuntime.getRootDataStore() (however, as noted above this will be removed in an upcoming release):

const agentScheduler = await requestFluidObject<IAgentScheduler>(
    await containerRuntime.getRootDataStore("_scheduler"),
    "",
);

IContainerRuntimeDirtyable deprecation

The IContainerRuntimeDirtyable interface provides the isMessageDirtyable() method, for use with last-edited functionality. This is only used to differentiate messages for the built-in AgentScheduler. With the deprecation of the AgentScheduler, this interface and method are no longer necessary and so are deprecated and will be removed in an upcoming release. From the ContainerRuntime's perspective all messages are considered dirtyable with this change.

If you continue to use the built-in AgentScheduler and want to replicate this filtering in your last-edited behavior, you can use the following in your shouldDiscardMessage() check:

import { ContainerMessageType } from "@fluidframework/container-runtime";
import { IEnvelope, InboundAttachMessage } from "@fluidframework/runtime-definitions";

// In shouldDiscardMessage()...
if (type === ContainerMessageType.Attach) {
    const attachMessage = contents as InboundAttachMessage;
    if (attachMessage.id === "_scheduler") {
        return true;
    }
} else if (type === ContainerMessageType.FluidDataStoreOp) {
    const envelope = contents as IEnvelope;
    if (envelope.address === "_scheduler") {
        return true;
    }
}
// Otherwise, proceed with other discard logic...

Deprecation of AgentScheduler in the container registry and instantiation of the _scheduler

Finally, the automatic addition to the registry and creation of the AgentScheduler with ID _scheduler is deprecated and will also be removed in an upcoming release. To prepare for this, you can proactively opt-out of the built-in by turning off the IContainerRuntimeOptions option addGlobalAgentSchedulerAndLeaderElection in your calls to Container.load or in the constructor of your BaseContainerRuntimeFactory or ContainerRuntimeFactoryWithDefaultDataStore.

For backwards compat with documents created prior to this change, you'll need to ensure the AgentSchedulerFactory.registryEntry is present in the container registry. You can add it explicitly in your calls to Container.load or in the constructor of your BaseContainerRuntimeFactory or ContainerRuntimeFactoryWithDefaultDataStore. The examples below show how to opt-out of the built-in while maintaining backward-compat with documents that were created with a built-in AgentScheduler.

const runtime = await ContainerRuntime.load(
    context,
    [
        // Any other registry entries...
        AgentSchedulerFactory.registryEntry,
    ],
    requestHandler,
    // Opt-out of adding the AgentScheduler
    { addGlobalAgentSchedulerAndLeaderElection: false },
    scope);
const SomeContainerRuntimeFactory = new ContainerRuntimeFactoryWithDefaultDataStore(
    DefaultFactory,
    new Map([
        // Any other registry entries...
        AgentSchedulerFactory.registryEntry,
    ]),
    providerEntries,
    requestHandlers,
    // Opt-out of adding the AgentScheduler
    { addGlobalAgentSchedulerAndLeaderElection: false },
);

If you use AgentScheduler functionality, it is recommended to instantiate this as a normal (non-root) data store (probably on your root data object). But if you are not yet ready to migrate away from the root data store, you can instantiate it yourself on new containers (you should do this while the container is still detached):

if (!context.existing) {
    await runtime.createRootDataStore(AgentSchedulerFactory.type, "_scheduler");
}

The option will be turned off by default in an upcoming release before being turned off permanently, so it is recommended to make these updates proactively.

Removed containerUrl from IContainerLoadOptions and IContainerConfig

Removed containerUrl from IContainerLoadOptions and IContainerConfig. This is no longer needed to route request.

0.37 Breaking changes

OpProcessingController marked for deprecation

OpProcessingController is marked for deprecation and we be removed in 0.38. LoaderContainerTracker is the replacement with better tracking. The API differs from OpProcessingController in the following ways:

  • Loader is added for tracking and any Container created/loaded will be automatically tracked
  • The op control APIs accept Container instead of DeltaManager

Loader in data stores deprecated

The loader property on the IContainerRuntime, IFluidDataStoreRuntime, and IFluidDataStoreContext interfaces is now deprecated and will be removed in an upcoming release. Data store objects will no longer have access to an ILoader by default. To replicate the same behavior, existing users can make the ILoader used to create a Container available on the scope property of these interfaces instead by setting the provideScopeLoader ILoaderOptions flag when creating the loader.

const loader = new Loader({
    urlResolver,
    documentServiceFactory,
    codeLoader,
    options: { provideScopeLoader: true },
});
const loader: ILoader | undefined = this.context.scope.ILoader;

TelemetryLogger Properties Format

The TelemetryLogger's properties format has been updated to support error only properties. This includes: ChildLogger, MultiSinkLogger,DebugLogger. The previous format was just a property bag: ChildLogger.create(logger, undefined, { someProperty: uuid() }); Whereas now it has nested property bags for error categories including all and error: ChildLogger.create(logger, undefined, {all:{ someProperty: uuid() }});

IContainerRuntimeOptions Format Change

The runtime options passed into ContainerRuntime have been subdivided into nested objects, because all of them fall under two categories currently:

  • summaryOptions - contains all summary/summarizer related options
    • generateSummaries
    • initialSummarizerDelayMs
    • summaryConfigOverrides
    • disableIsolatedChannels
  • gcOptions - contains all Garbage Collection related options
    • disableGC
    • gcAllowed (new)
    • runFullGC

For a few versions we will keep supporting the old format, but the typings have already been updated.

AgentScheduler moves and renames

IAgentScheduler and IProvideAgentScheduler have been moved to the @fluidframework/agent-scheduler package, and taskSchedulerId has been renamed to agentSchedulerId.

0.36 Breaking changes

Some ILoader APIs moved to IHostLoader

The createDetachedContainer and rehydrateDetachedContainerFromSnapshot APIs are removed from the ILoader interface, and have been moved to the new IHostLoader interface. The Loader class now implements IHostLoader instead, and consumers who need these methods should operate on an IHostLoader instead of an ILoader, such as by creating a Loader.

TaskManager removed

The TaskManager has been removed, as well as methods to access it (e.g. the .taskManager member on DataObject). The AgentScheduler should be used instead for the time being and can be accessed via a request on the ContainerRuntime (e.g. await this.context.containerRuntime.request({ url: "/_scheduler" })), though we expect this will also be deprecated and removed in a future release when an alternative is made available (see #4413).

ContainerRuntime registerTasks removed

The registerTasks method has been removed from ContainerRuntime. The AgentScheduler should be used instead for task scheduling.

getRootDataStore

IContainerRuntime.getRootDataStore() used to have a backdoor allowing accessing any store, including non-root stores. This back door is removed - you can only access root data stores using this API.

Share link generation no longer exposed externally

Share link generation implementation has been refactored to remove options for generating share links of various kinds. Method for generating share link is no longer exported. ShareLinkTokenFetchOptions has been removed and OdspDriverUrlResolverForShareLink constructor has been changed to accept tokenFetcher parameter which will pass OdspResourceTokenFetchOptions instead of ShareLin kTokenFetchOptions.

ITelemetryLogger redundant method deprecation

Deprecate shipAssert debugAssert logException logGenericError in favor of sendErrorEvent as they provide the same behavior and semantics as sendErrorEventand in general are relatively unused.

0.35 Breaking changes

Removed-some-api-implementations-from-odsp-driver

Removed authorizedFetchWithRetry, AuthorizedRequestTokenPolicy, AuthorizedFetchProps, asyncWithCache, asyncWithRetry, fetchWithRetry implementation from odspdriver.

get-tinylicious-container and get-session-storage-container moved

The functionality from the packages @fluidframework/get-tinylicious-container and @fluidframework/get-session-storage-container has been moved to the package @fluid-experimental/get-container.

Moved parseAuthErrorClaims from @fluidframework/odsp-driver to @fluidframework/odsp-doclib-utils

Moved parseAuthErrorClaims from @fluidframework/odsp-driver to @fluidframework/odsp-doclib-utils

Refactored token fetcher types in odsp-driver

Streamlined interfaces and types used to facilitate access tokens needed by odsp-driver to call ODSP implementation of Fluid services. Added support for passing siteUrl when fetching token that is used to establish co-authoring session for Fluid content stored in ODSP file which is hosted in external tenant. This token is used by ODSP ordering service implementation (aka ODSP Push service).

DeltaManager readonly and readOnlyPermissions properties deprecated

DeltaManager.readonly/Container.readonly and DeltaManager.readOnlyPermissions/Container.readOnlyPermissions have been deprecated. Please use DeltaManager.readOnlyInfo/Container.readOnlyInfo instead, which exposes the same information.

DirtyDocument events and property

The following 3 names have been deprecated - please use new names: "dirtyDocument" event -> "dirty" event "savedDocument" event -> "saved" event isDocumentDirty property -> isDirty property

Removed createDocumentService and createDocumentService2 from r11s driver

Removed the deprecated methods createDocumentService and createDocumentService2. Please use DocumentServiceFactory.createDocumentService instead.

0.34 Breaking changes

Aqueduct writeBlob() and BlobHandle implementation removed

writeBlob() and BlobHandle have been removed from aqueduct. Please use FluidDataStoreRuntime.uploadBlob() or ContainerRuntime.uploadBlob() instead.

Connected events raised on registration

Connected / disconnected listeners are called on registration. Please see Connectivity events section of Loader readme.md for more details

0.33 Breaking changes

Normalizing enum ContainerErrorType

In an effort to clarify error categorization, a name and value in this enumeration were changed.

Map and Directory typing changes from enabling strictNullCheck

Typescript compile options strictNullCheck is enabled for the @fluidframework/map package. Some of the API signature is updated to include possibility of undefined and null, which can cause new typescript compile error when upgrading. Existing code may need to update to handle the possiblity of undefined or `null.

MergeTree ReferencePosition getTileLabels getRangeLabels changes

This includes LocalReference and Marker. getTileLabels and getRangeLabels methods will return undefined instead of creating an empty if the properties for tile labels and range labels is not set.

Containers from Loader.request() are now cached by default

Some loader request header options that previously prevented caching (pause: true and reconnect: false) no longer do. Callers must now explicitly spcify cache: false in the request header to prevent caching of the returned container. Containers are evicted from the cache in their closed event, and closed containers that are requested are not cached.

0.32 Breaking changes

Node version updated to 12.17

Due to changes in server packages and introduction of AsyncLocalStorage module which requires Node version 12.17 or above, you will need to update Node version to 12.17 or above.

getAttachSnapshot removed from IFluidDataStoreChannel

getAttachSnapshot() has been removed from IFluidDataStoreChannel. It is replaced by getAttachSummary().

resolveDataStore replaced

The resolveDataStore method manually exported by the ODSP resolver has been replaced with checkUrl() from the same package.

0.30 Breaking Changes

Branching removed

The branching feature has been removed. This includes all related members, methods, etc. such as parentBranch, branchId, branch(), etc.

removeAllEntriesForDocId api name and signature change

removeAllEntriesForDocId api renamed to removeEntries. Now it takes IFileEntry as argument instead of just docId.

snapshot removed from IChannel and ISharedObject

snapshot has been removed from IChannel and ISharedObject. It is replaced by summarize which should be used to get a summary of the channel / shared object.

0.29 Breaking Changes

OdspDriverUrlResolver2 renamed to OdspDriverUrlResolverForShareLink

OdspDriverUrlResolver2 renamed to OdspDriverUrlResolverForShareLink

removeAllEntriesForDocId api in host storage changed

removeAllEntriesForDocId api in host storage is now an async api.

IContainerRuntimeBase.IProvideFluidDataStoreRegistry

IProvideFluidDataStoreRegistry implementation moved from IContainerRuntimeBase to IContainerRuntime. Data stores and objects should not have access to global state in container. IProvideFluidDataStoreRegistry is removed from IFluidDataStoreChannel - it has not been implemented there for a while (it moved to context).

_createDataStoreWithProps returns IFluidRouter

IContainerRuntimeBase._createDataStoreWithProps returns IFluidRouter instead of IFluidDataStoreChannel. This is done to be consistent with other APIs create data stores, and ensure we do not return internal interfaces. This likely to expose areas where IFluidDataStoreChannel.bindToContext() was called manually on data store. Such usage should be re-evaluate - lifetime management should be left up to runtime, storage of any handle form data store in attached DDS will result in automatic attachment of data store (and all of its objects) to container. If absolutely needed, and only for staging, casting can be done to implement old behavior.

FluidDataStoreRuntime.registerRequestHandler deprecated

Please use mixinRequestHandler() as a way to create custom data store runtime factory/object and append request handling to existing implementation.

snapshot removed from IFluidDataStoreRuntime

snapshot has been removed from IFluidDataStoreRuntime.

getAttachSnapshot deprecated in IFluidDataStoreChannel

getAttachSnapshot() has been deprecated in IFluidDataStoreChannel. It is replaced by getAttachSummary().

0.28 Breaking Changes

FileName should contain extension for ODSP driver create new path

Now the ODSP driver expects file extension in the file name while creating a new detached container.

ODSP Driver IPersistedCache-Changes

Added api removeAllEntriesForDocId which allows removal of all entries for a given document id. Also the schema for entries stored inside odsp IPersistedCache has changed. It now stores/expect values as IPersistedCacheValueWithEpoch. So host needs to clear its cached entries in this version.

IFluidPackage Changes

  • Moving IFluidPackage and IFluidCodeDetails from "@fluidframework/container-definitions" to '@fluidframework/core-interfaces'
  • Remove npm specific IPackage interface
  • Simplify the IFluidPackage by removing browser and npm specific properties
  • Add new interface IFluidBrowserPackage, and isFluidBrowserPackage which defines browser specific properties
  • Added resolveFluidPackageEnvironment helper for resolving a package environment

DataObject changes

DataObject are now always created when Data Store is created. Full initialization for existing objects (in file) continues to happen to be on demand, i.e. when request() is processed. Full DataObject initialization does happen for newly created (detached) DataObjects. The impact of that change is that all changed objects would get loaded by summarizer container, but would not get initialized. Before this change, summarizer would not be loading any DataObjects. This change

  1. Ensures that initial summary generated for when data store attaches to container has fully initialized object, with all DDSs created. Before this change this initial snapshot was empty in most cases.
  2. Allows DataObjects to modify FluidDataStoreRuntime behavior before it gets registered and used by the rest of the system, including setting various hooks.

But it also puts more constraints on DataObject - its constructor should be light and not do any expensive work (all such work should be done in corresponding initialize methods), or access any data store runtime functionality that requires fully initialized runtime (like loading DDSs will not work in this state)

RequestParser

RequestParser's ctor is made protected. Please replace this code

    const a = new RequestParser(request);

with this one:

    const a = RequestParser.create(request);

IFluidLodable.url is removed

url property is removed. If you need a path to an object (in a container), you can use IFluidLoadable.handle.absolutePath instead.

Loader Constructor Changes

The loader constructor has changed to now take a props object, rather than a series of paramaters. This should make it easier to construct loaders as the optional services can be easily excluded.

Before:

const loader = new Loader(
    urlResolver,
    documentServiceFactory,
    codeLoader,
    { blockUpdateMarkers: true },
    {},
    new Map()
);

After:

const loader = new Loader({
    urlResolver,
    documentServiceFactory,
    codeLoader,
});

if for some reason this change causes you problems, we've added a deprecated Loader._create method that has the same parameters as the previous constructor which can be used in the interim.

Moving DriverHeader and merge with CreateNewHeader

Compile time only API breaking change between runtime and driver. Only impacts driver implementer. No back-compat or mix version impact.

DriverHeader is a driver concept, so move from core-interface to driver-definitions. CreateNewHeader is also a kind of driver header, merged it into DriverHeader.

ODSP status codes moved modules from odsp-driver to odsp-doclib-utils

Error/status codes like offlineFetchFailureStatusCode which used to be imported like import { offlineFetchFailureStatusCode } from '@fluidframework/@odsp-driver'; have been moved to odspErrorUtils.ts in odsp-doclib-utils.

0.27 Breaking Changes

Local Web Host Removed

Local Web host is removed. Users who are using the local web host can use examples/utils/get-session-storage-container which provides the same functionality with the detached container flow.

0.25 Breaking Changes

External Component Loader and IComponentDefaultFactoryName removed

The @fluidframework/external-component-loader package has been removed from the repo. In addition to this, the IFluidExportDefaultFactoryName and the corresponding IProvideFluidExportDefaultFactoryName interfaces have also been dropped.

MockFluidDataStoreRuntime api rename

Runtime Test Utils's MockFluidDataStoreRuntime now has "requestDataStore" instead of "requestComponent"

Local Web Host API change

The renderDefaultComponent function has been updated to be renderDefaultFluidObject

Container runtime event changes

Container runtime now emits the event "fluidDataStoreInstantiated" instead of "componentInstantiated"

Component is removed from telemetry event names

The following telemetry event names have been updated to drop references to the term component:

ComponentRuntimeDisposeError -> ChannelDisposeError ComponentContextDisposeError -> FluidDataStoreContextDisposeError SignalComponentNotFound -> SignalFluidDataStoreNotFound

IComponentContextLegacy is removed

Deprecated in 0.18, removed.

IContainerRuntimeBase._createDataStoreWithProps is removed

Note: This change has been reverted for 0.25 and will be pushed to a later release.

IContainerRuntimeBase._createDataStoreWithProps() has been removed. Please use IContainerRuntimeBase.createDataStore() (returns IFluidRouter). If you need to pass props to data store, either use request() route to pass initial props directly, or to query Fluid object to interact with it (pass props / call methods to configure object).

_createDataStore APIs are removed

IFluidDataStoreContext._createDataStore() & IContainerRuntimeBase._createDataStore() are removed Please switch to using one of the following APIs:

  1. IContainerRuntime.createRootDataStore() - data store created that way is automatically bound to container. It will immediately be visible to remote clients (when/if container is attached). Such data stores are never garbage collected. Note that this API is on IContainerRuntime interface, which is not directly accessible to data stores. The intention is that only container owners are creating roots.
  2. IContainerRuntimeBase.createDataStore() - creates data store that is not bound to container. In order for this store to be bound to container (and thus be observable on remote clients), ensure that handle to it (or any of its objects / DDS) is stored into any other DDS that is already bound to container. In other words, newly created data store has to be reachable (there has to be a path) from some root data store in container. If, in future, such data store becomes unreachable from one of the roots, it will be garbage collected (implementation pending).

createDataStoreWithRealizationFn() APIs are removed

Removed from IFluidDataStoreContext & IContainerRuntime. Consider using (Pure)DataObject(Factory) for your objects - they support passing initial args. Otherwise consider implementing similar flow of exposing interface from your Fluid object that is used to initialize object after creation.

getDataStore() APIs is removed

IContainerRuntime.getDataStore() is removed. Only IContainerRuntime.getRootDataStore() is available to retrieve root data stores. For couple versions we will allow retrieving non-root data stores using this API, but this functionality is temporary and will be removed soon. You can use handleFromLegacyUri() for creating handles from container-internal URIs (i.e., in format /${dataStoreId}) and resolving those containers to get to non-root data stores. Please note that this functionality is strictly added for legacy files! In future, not using handles to refer to content (and storing handles in DDSes) will result in such data stores not being reachable from roots, and thus garbage collected (deleted) from file.

Package Renames

As a follow up to the changes in 0.24 we are updating a number of package names

  • @fluidframework/component-core-interfaces is renamed to @fluidframework/core-interfaces
  • @fluidframework/component-runtime-definitions is renamed to @fluidframework/datastore-definitions
  • @fluidframework/component-runtime is renamed to @fluidframework/datastore
  • @fluidframework/webpack-component-loader is renamed to @fluidframework/webpack-fluid-loader

IComponent and IComponent Interfaces Removed

In 0.24 IComponent and IComponent interfaces were deprecated, they are being removed in this build. Please move to IFluidObject and IFluidObject interfaces.

odsp-utils Changes

To support additional authentication scenarios, the signature and/or name of a few auth-related functions was modified.

LastEditedTrackerComponent renamed

It is renamed to LastEditedTrackerDataObject

ComponentProvider renamed to FluidObjectProvider

In the package @fluidframework/synthesize, these types are renamed:

ComponentKey -> FluidObjectKey ComponentSymbolProvider -> FluidObjectProvider AsyncRequiredcomponentProvider -> AsyncRequiredFluidObjectProvider AsyncOptionalComponentProvider -> AsyncOptionalFluidObjectProvider AsyncComponentProvider -> AsyncFluidObjectProvider NonNullableComponent -> NonNullableFluidObject

0.24 Breaking Changes

This release only contains renames. There are no functional changes in this release. You should ensure you have integrated and validated up to release 0.23 before integrating this release.

This is a followup to the forward compat added in release 0.22: Forward Compat For Loader IComponent Interfaces

You should ensure all container and components hosts are running at least 0.22 before integrating this release.

The below json describes all the renames done in this release. If you have a large typescript code base, we have automation that may help. Please contact us if that is the case.

All renames are 1-1, and global case senstive and whole word find replace for all should be safe. For IComponent Interfaces, both the type and property name were re-named.

{
    "dataStore": {
        "types": {
            "IComponentRuntimeChannel": "IFluidDataStoreChannel",
            "IComponentAttributes": "IFluidDataStoretAttributes",

            "IComponentContext": "IFluidDataStoreContext",
            "ComponentContext": "FluidDataStoreContext",
            "LocalComponentContext": "LocalFluidDataStoreContext",
            "RemotedComponentContext": "RemotedFluidDataStoreContext ",

            "IComponentRuntime": "IFluidDataStoreRuntime",
            "ComponentRuntime": "FluidDataStoreRuntime",
            "MockComponentRuntime": "MockFluidDataStoreRuntime"
        },
        "methods": {
            "createComponent": "_createDataStore",
            "createComponentContext": "createDataStoreContext",
            "createComponentWithProps": "createDataStoreWithProps",
            "_createComponentWithProps": "_createDataStoreWithProps",
            "createComponentWithRealizationFn": "createDataStoreWithRealizationFn",
            "getComponentRuntime": "getDataStore",
            "notifyComponentInstantiated": "notifyDataStoreInstantiated"
        }
    },

    "aquaduct": {
        "IComponentInterfaces": {
            "IProvideComponentDefaultFactoryName": "IProvideFluidExportDefaultFactoryName",
            "IComponentDefaultFactoryName": "IFluidExportDefaultFactoryName"
        },
        "types": {
            "SharedComponentFactory": "PureDataObjectFactory",
            "SharedComponent": "PureDataObject",

            "PrimedComponentFactory": "DataObjectFactory",
            "PrimedComponent": "DataObject",

            "ContainerRuntimeFactoryWithDefaultComponent": "ContainerRuntimeFactoryWithDefaultDataStore",

            "defaultComponentRuntimeRequestHandler": "defaultRouteRequestHandler"
        },
        "methods": {
            "getComponent": "requestFluidObject",
            "asComponent": "asFluidObject",
            "createAndAttachComponent": "createAndAttachDataStore",
            "getComponentFromDirectory": "getFluidObjectFromDirectory",
            "getComponent_UNSAFE": "requestFluidObject_UNSAFE",
            "componentInitializingFirstTime": "initializingFirstTime",
            "componentInitializingFromExisting": "initializingFromExisting",
            "componentHasInitialized": "hasInitialized"
        }
    },

    "fluidObject": {
        "IComponentInterfaces": {
            "IProvideComponentRouter": "IProvideFluidRouter",
            "IComponentRouter": "IFluidRouter",

            "IProvideComponentLoadable": "IProvideFluidLoadable",
            "IComponentLoadable": "IFluidLoadable",

            "IProvideComponentHandle": "IProvideFluidHandle",
            "IComponentHandle": "IFluidHandle",

            "IProvideComponentHandleContext": "IProvideFluidHandleContext",
            "IComponentHandleContext": "IFluidHandleContext",

            "IProvideComponentSerializer": "IProvideFluidSerializer",
            "IComponentSerializer": "IFluidSerializer",

            "IProvideComponentRunnable": "IProvideFluidRunnable",
            "IComponentRunnable": "IFluidRunnable",

            "IProvideComponentConfiguration": "IProvideFluidConfiguration",
            "IComponentConfiguration": "IFluidConfiguration",

            "IProvideComponentHTMLView": "IProvideFluidHTMLView",
            "IComponentHTMLView": "IFluidHTMLView",
            "IComponentHTMLOptions": "IFluidHTMLOptions",

            "IProvideComponentMountableView": "IProvideFluidMountableView",
            "IComponentMountableViewClass": "IFluidMountableViewClass",
            "IComponentMountableView": "IFluidMountableView",

            "IProvideComponentLastEditedTracker": "IProvideFluidLastEditedTracker",
            "IComponentLastEditedTracker": "IFluidLastEditedTracker",

            "IProvideComponentRegistry": "IProvideFluidDataStoreRegistry",
            "IComponentRegistry": "IFluidDataStoreRegistry",

            "IProvideComponentFactory": "IProvideFluidDataStoreFactory",
            "IComponentFactory": "IFluidDataStoreFactory",

            "IProvideComponentCollection": "IProvideFluidObjectCollection",
            "IComponentCollection": "IFluidObjectCollection",

            "IProvideComponentDependencySynthesizer": "IProvideFluidDependencySynthesizer",
            "IComponentDependencySynthesizer": "IFluidDependencySynthesizer",

            "IProvideComponentTokenProvider": "IProvideFluidTokenProvider",
            "IComponentTokenProvider": "IFluidTokenProvider"
        },
        "types": {
            "IComponent": "IFluidObject",
            "fluid/component": "fluid/object",

            "SharedObjectComponentHandle": "SharedObjectHandle",
            "RemoteComponentHandle": "RemoteFluidObjectHandle",
            "ComponentHandle": "FluidObjectHandle",
            "ComponentSerializer": "FluidSerializer",

            "ComponentHandleContext": "FluidHandleContext",

            "ComponentRegistryEntry": "FluidDataStoreRegistryEntry",
            "NamedComponentRegistryEntry": "NamedFluidDataStoreRegistryEntry",
            "NamedComponentRegistryEntries": "NamedFluidDataStoreRegistryEntries",
            "ComponentRegistry": "FluidDataStoreRegistry",
            "ContainerRuntimeComponentRegistry": "ContainerRuntimeDataStoreRegistry"
        },
        "methods": {
            "instantiateComponent": "instantiateDataStore"
        }
    }
}

0.23 Breaking Changes

Removed collaborating event on IComponentRuntime

Component Runtime no longer fires the collaborating event on attaching. Now it fires attaching event.

ISharedObjectFactory

ISharedObjectFactory renamed to IChannelFactory and moved from @fluidframework/shared-object-base to @fluidframework/datastore-definitions

LocalSessionStorageDbFactory moved to @fluidframework/local-driver

Previously, LocalSessionStorageDbFactory was part of the @fluidframework/webpack-component-loader package. It has been moved to the @fluidframework/local-driver package.

0.22 Breaking Changes

Deprecated path from IComponentHandleContext

Deprecated the path field from the interface IComponentHandleContext. This means that IComponentHandle will not have this going forward as well.

Added an absolutePath field to IComponentHandleContext which is the absolute path to reach it from the container runtime.

Dynamically loaded components

Components that were compiled against Fluid Framework <= 0.19.x releases will fail to load. A bunch of APIs has been deprecated in 0.20 & 0.21 and back compat support is being removed in 0.22. Some of the key APIs are:

  • IComponentRuntime.attach
  • ContainerContext.isAttached
  • ContainerContext.isLocal Such components needs to be compiled against >= 0.21 runtime and can be used in container that is built using >= 0.21 runtime as well.

ContainerRuntime.load Request Handler Changes

ContainerRuntime.load no longer accepts an array of RuntimeRequestHandlers. It has been changed to a single function parameter with a compatible signature: requestHandler?: (request: IRequest, runtime: IContainerRuntime) => Promise<IResponse>

To continue to use RuntimeRequestHandlers you can used the RuntimeRequestHandlerBuilder in the package @fluidframework/request-handler

example:

const builder = new RuntimeRequestHandlerBuilder();
builder.pushHandler(...this.requestHandlers);
builder.pushHandler(defaultRouteRequestHandler("defaultComponent"));
builder.pushHandler(innerRequestHandler());

const runtime = await ContainerRuntime.load(
    context,
    this.registryEntries,
    async (req, rt) => builder.handleRequest(req, rt),
    undefined,
    scope
);

Additionally the class RequestParser has been moved to the @fluidframework/runtime-utils package

This will allow consumers of our ContainerRuntime to substitute other routing frameworks more easily.

IComponentHTMLVisual removed

The IComponentHTMLVisual interface was deprecated in 0.21, and is now removed in 0.22. To support multiview scenarios, consider split view/model patterns like those demonstrated in the multiview sample.

IComponentReactViewable deprecated

The IComponentReactViewable interface is deprecated and will be removed in an upcoming release. For multiview scenarios, instead use a pattern like the one demonstrated in the sample in /components/experimental/multiview. This sample demonstrates how to create multiple views for a component.

Forward Compat For Loader IComponent Interfaces

As part of the Fluid Data Library (FDL) and Fluid Component Library (FCL) split we will be renaming a significant number of out interfaces. Some of these interfaces are used across the loader -> runtime boundary. For these interfaces we have introduced the newly renamed interfaces in this release. This will allow Host's to implment forward compatbitiy for these interfaces, so they are not broken when the implementations themselves are renamed.

  • IComponentLastEditedTracker will become IFluidLastEditedTracker
  • IComponentHTMLView will become IFluidHTMLView
  • IComponentMountableViewClass will become IFluidMountableViewClass
  • IComponentLoadable will become IFluidLoadable
  • IComponentRunnable will become IFluidRunnable
  • IComponentConfiguration will become IFluidConfiguration
  • IComponentRouter will become IFluidRouter
  • IComponentHandleContext will become IFluidHandleContext
  • IComponentHandle will become IFluidHandle
  • IComponentSerializer will become IFluidSerializer
  • IComponentTokenProvider will become IFluidTokenProvider

IComponent will also become IFluidObject, and the mime type for for requests will change from fluid/component to fluid/object

To ensure forward compatability when accessing the above interfaces outside the context of a container e.g. from the host, you should use the nullish coalesing operator (??).

For example

        if (response.status !== 200 ||
            !(
                response.mimeType === "fluid/component" ||
                response.mimeType === "fluid/object"
            )) {
            return undefined;
        }

        const fluidObject = response.value as IComponent & IFluidObject;
        return fluidObject.IComponentHTMLView ?? fluidObject.IFluidHTMLView.

Add Undefined to getAbsoluteUrl return type

getAbsoluteUrl on the container runtime and component context now returns string | undefined. undefined will be returned if the container or component is not attached. You can determine if a component is attached and get its url with the below snippit:

import { waitForAttach } from "@fluidframework/aqueduct";


protected async hasInitialized() {
        waitForAttach(this.runtime)
            .then(async () => {
                const url = await this.context.getAbsoluteUrl(this.url);
                this._absoluteUrl = url;
                this.emit("stateChanged");
            })
            .catch(console.error);
}

Renamed TestDeltaStorageService, TestDocumentDeltaConnection, TestDocumentService, TestDocumentServiceFactory and TestResolver

Renamed the following in "@fluidframework/local-driver" since these are used beyond testing:

  • TestDeltaStorageService -> LocalDeltaStorageService
  • TestDocumentDeltaConnection -> LocalDocumentDeltaConnection
  • TestDocumentService -> LocalDocumentService
  • TestDocumentServiceFactory -> LocalDocumentServiceFactory
  • TestResolver -> LocalResolver

DocumentDeltaEventManager has been renamed and moved to "@fluidframework/test-utils"

DocumentDeltaEventManager has moved to "@fluidframework/test-utils" and renamed to OpProcessingController.

The registerDocuments method has been renamed to addDeltaManagers and should be called with a list of delta managers. Similarly, all the other methods have been updated to be called with delta managers.

So, the usage has now changed to pass in the deltaManager from the object that was passed earlier. For example:

// Old usage
containerDeltaEventManager = new DocumentDeltaEventManager(
    deltaConnectionServer
);
containerDeltaEventManager.registerDocuments(
    component1.runtime,
    component2.runtime
);

// New usage
opProcessingController = new OpProcessingController(deltaConnectionServer);
opProcessingController.addDeltaManagers(
    component1.runtime.deltaManager,
    component2.runtime.deltaManager
);

isAttached replaced with attachState property

isAttached is replaced with attachState property on IContainerContext, IContainerRuntime and IComponentContext. isAttached returned true when the entity was either attaching or attached to the storage. So if attachState is AttachState.Attaching or AttachState.Attached then isAttached would have returned true. Attaching is introduced in regards to Detached container where there is a time where state is neither AttachState.Detached nor AttachState.Attached.

0.21 Breaking Changes

Removed @fluidframework/local-test-utils

Removed this package so classes like TestHost are no longer supported. Please contact us if there were dependencies on this or if any assistance in required to get rid of it.

IComponentHTMLVisual deprecated

The IComponentHTMLVisual interface is deprecated and will be removed in an upcoming release. For multiview scenarios, instead use a pattern like the one demonstrated in the sample in /components/experimental/multiview. This sample demonstrates how to create multiple views for a component.

createValueType removed from SharedMap and SharedDirectory

The createValueType() method on SharedMap and SharedDirectory was deprecated in 0.20, and is now removed in 0.21. If Counter functionality is required, the @fluidframework/counter DDS can be used for counter functionality.

isLocal api removed

isLocal api is removed from the repo. It is now replaced with isAttached which tells that the entity is attached or getting attached to storage. So its meaning is opposite to isLocal.

register/attach api renames on handles, components and dds

Register on dds and attach on data store runtime is renamed to bindToContext(). attach on handles is renamed to attachGraph().

Error handling changes

ErrorType enum has been broken into 3 distinct enums / layers:

  1. ContainerErrorType - errors & warnings raised at loader level
  2. OdspErrorType and R11sErrorType - errors raised by ODSP and R11S drivers.
  3. Runtime errors, like "summarizingError", "dataCorruptionError". This class of errors it not pre-determined and depends on type of container loaded.

ICriticalContainerError.errorType is now a string, not enum, as loader has no visibility into full set of errors that can be potentially raised. Hosting application may package different drivers and open different types of containers, thus making errors list raised at container level dynamic.

Sequence snapshot format change

Due to a change in the sequence's snapshot format clients running a version less than 0.19 will not be able to load snapshots generated in 0.21. This will affect all sequence types includes shared string, and sparse matrix. If you need to support pre-0.19 clients please contact us for mitigations.

0.20 Breaking Changes

Value types deprecated on SharedMap and SharedDirectory

The Counter value type and createValueType() method on SharedMap and SharedDirectory are now deprecated and will be removed in an upcoming release. Instead, the @fluidframework/counter DDS can be used for counter functionality.

rename @fluidframework/aqueduct-react to @fluidframework/react-inputs

aqueduct-react is actually just a react library and renamed it to reflect such.

0.19 Breaking Changes

Package rename

Package with the prefix "@microsoft/fluid-" is renamed to "@fluidframework/" to take advanage a separate namespace for Fluid Framework SDK packages.

Container Error Event

"error" event is gone. All critical errors are raised on "closed" event via optiona error object. "warning" event is added to expose warnings. Currently it contains summarizer errors and throttling errors.

IUrlResolver change from requestUrl to getAbsoluteUrl

As we continue to refine our API around detached containers, and component urls, we've renamed IUrlResolver from requestUrl to getAbsoluteUrl

0.18 Breaking Changes

App Id removed as a parameter to OdspDocumentServiceFactory

@microsoft/fluid-odsp-driver no longer requires consumers to pass in an app id as an input. Consumers should simply remove this parameter from the OdspDocumentServiceFactory/OdspDocumentServiceFactoryWithCodeSplit constructor.

ConsensusRegisterCollection now supports storing handles

ConsensusRegisterCollection will properly serialize/deserialize handles added as values.

Summarizing errors on parent container

The parent container of the summarizing container will now raise "error" events related to summarization problems. These will be of type ISummarizingError and will have a description indicating either a problem creating the summarizing container, a problem generating a summary, or a nack or ack wait timeout from the server.

OdspDocumentServiceFactory no longer requires a logger

The logger will be passed in on createDocumentService or createContainer, no need to pass in one on construction of OdspDocumentServiceFactory.

0.17 and earlier Breaking Changes

For older versions' breaking changes, go here