Skip to content

Fluid Framework v2.0.0-rc.5.0.0 (major)
Compare
Choose a tag to compare
@tylerbutler tylerbutler released this 19 Jun 23:22
· 1198 commits to main since this release
client_v2.0.0-rc.5.0.0
7e4ee06
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Learn about vigilant mode.

New Features

tree: Added support for optional schema validation on newly inserted content in SharedTree

When defining how to view a SharedTree, an application can now specify that new content inserted into the tree should be subject to schema validation at the time it is inserted, so if it's not valid according to the stored schema in the tree an error is thrown immediately.

This can be accomplished by passing an ITreeConfigurationOptions argument with enableSchemaValidation set to true when creating a TreeConfiguration to use with the SharedTree.

Since this feature requires additional compute when inserting new content into the tree, it is not enabled by default.

fluid-framework: Type Erase ISharedObjectKind

A new type, SharedObjectKind is added as a type erased version of ISharedObjectKind and DataObjectClass.

This type fills the role of both ISharedObjectKind and DataObjectClass in the @public "declarative API" exposed in the fluid-framework package.

This allows several types referenced by ISharedObjectKind to be made @alpha as they should only need to be used by legacy code and users of the unstable/alpha/legacy "encapsulated API".

Access to these now less public types should not be required for users of the @public "declarative API" exposed in the fluid-framework package, but can still be accessed for those who need them under the /legacy import paths. The full list of such types is:

  • SharedTree as exported from @fluidframwork/tree: It is still exported as @public from fluid-framework as SharedObjectKind.
  • ISharedObjectKind: See new SharedObjectKind type for use in @public APIs. ISharedObject
  • IChannel
  • IChannelAttributes
  • IChannelFactory
  • IExperimentalIncrementalSummaryContext
  • IGarbageCollectionData
  • ISummaryStats
  • ISummaryTreeWithStats
  • ITelemetryContext
  • IDeltaManagerErased
  • IFluidDataStoreRuntimeEvents
  • IFluidHandleContext
  • IProvideFluidHandleContext

Removed APIs:

  • DataObjectClass: Usages replaced with SharedObjectKind.
  • LoadableObjectClass: Replaced with SharedObjectKind.
  • LoadableObjectClassRecord: Replaced with Record<string, SharedObjectKind>.

tree: A new tree status has been added for SharedTree nodes.

TreeStatus.New indicates that a SharedTree node has been constructed but not yet inserted into the tree. Constraints passed to the runTransaction API are now marked as readonly.

Breaking Changes

odsp-client: Move odsp-client out of experimental

The scope of the odsp-client package is changed from @fluid-experimental/odsp-client to @fluidframework/odsp-client.

fluid-framework: Remove some types from @public that are not needed

Mark the following APIs @alpha instead of @public:

  • IBranchOrigin
  • ISequencedDocumentMessage
  • ISignalMessage
  • ISignalMessageBase
  • ITrace

fluid-framework: Remove several types from @public scope

The following types have been moved from @public to @alpha:

  • IFluidSerializer
  • ISharedObjectEvents
  • IChannelServices
  • IChannelStorageService
  • IDeltaConnection
  • IDeltaHandler

These should not be needed by users of the declarative API, which is what @public is targeting.

tree: Event types have been renamed

  • ISubscribable is renamed to Listenable.
  • IsEvent type helper is renamed to IsListener.
  • Events is renamed to Listeners.

tree: Breaking change: Removed the "afterBatch" event from Treeview

This event is no longer necessary. In the past, it provided a means for waiting for a batch of changes to finish applying to the tree before taking some action. However, the tree change events exposed via Tree.on wait for a batch to complete before firing, so the "afterBatch" event provides no additional guarantees. Listeners of this event who wish to respond to changes to the tree view can use "rootChanged" instead.

tree: Move several types into InternalTypes

The stable public API surface for Tree has been reduced.
Several types have been moved into InternalTypes, indicating that they are not fully stable nor intended to be referenced by users of Tree.

  • NodeBuilderData
  • FieldHasDefault
  • TreeNodeSchemaNonClass
  • TreeArrayNodeBase
  • ScopedSchemaName
  • DefaultProvider
  • typeNameSymbol
  • InsertableObjectFromSchemaRecord
  • ObjectFromSchemaRecord
  • FieldHasDefaultUnsafe
  • ObjectFromSchemaRecordUnsafe
  • TreeObjectNodeUnsafe
  • TreeFieldFromImplicitFieldUnsafe
  • TreeNodeFromImplicitAllowedTypesUnsafe
  • InsertableTreeNodeFromImplicitAllowedTypesUnsafe
  • TreeArrayNodeUnsafe
  • TreeMapNodeUnsafe
  • InsertableObjectFromSchemaRecordUnsafe
  • InsertableTreeFieldFromImplicitFieldUnsafe
  • InsertableTypedNodeUnsafe
  • NodeBuilderDataUnsafe
  • NodeFromSchemaUnsafe
  • FlexList
  • TreeApi

Additionally a few more types which could not be moved due to technically limitations have been documented that they should be treated similarly.

  • TreeNodeApi
  • TreeNodeSchemaCore
  • All *Unsafe type (use for construction of recursive schema).
  • WithType
  • AllowedTypes
  • FieldSchemaUnsafe

Also to reduce confusion type was renamed to typeNameSymbol, and is now only type exported. Tree.is should be used to get type information from TreeNodes instead.

ITree.schematize removal

ITree.schematize (and its argument TreeConfiguration) has been removed. Instead, call ITree.viewWith and provide it a TreeViewConfiguration. Unlike schematize, viewWith does not implicitly initialize the document. As such, it doesn't take an initialTree property. Instead, applications should initialize their trees in document creation codepaths using the added TreeView.initialize API.

Old

As an example, something like the following code may have been used before for both the document create and document load codepaths:

// -- fluid-framework API for statically defined objects in container schema --
const tree = container.initialObjects.myTree;
const view = tree.schematize(
  new TreeConfiguration(Point, () => new Point({ x: 0, y: 0 })),
);

// -- fluid-framework API for dynamically created objects --
const tree = await container.create(SharedTree);
const view = tree.schematize(
  new TreeConfiguration(Point, () => new Point({ x: 0, y: 0 })),
);

When using the encapsulated API, creating a tree looks a bit different but the call to schematize is the same:

// -- encapsulated API --
const tree = SharedTree.create(runtime, "foo");
const view = tree.schematize(
  new TreeConfiguration(Point, () => new Point({ x: 0, y: 0 })),
);

New

After migrating this code away from schematize and onto viewWith, it would look like this on the create codepath:

const treeConfig = new TreeViewConfiguration({ schema: Point });

// The following line reflects the first-party API (e.g. @fluidframework/aqueduct). If using the third-party API, obtaining
// a SharedTree is unaffected by this changeset.
const tree = SharedTree.create(runtime, "foo");
const view = tree.viewWith(treeConfig);
view.initialize(new Point({ x: 0, y: 0 }));

and this on the load codepath:

// 'tree' would typically be obtained by retrieving it from a well-known location, e.g. within a `DataObject`'s
// root directory or in `IFluidContainer.initialObjects`
const view = tree.viewWith(treeConfig);

Besides only making the initial tree required to specify in places that actually perform document initialization, this is beneficial for mutation semantics: tree.viewWith never modifies the state of the underlying tree. This means applications are free to attempt to view a document using multiple schemas (e.g. legacy versions of their document format) without worrying about altering the document state.

If existing code used schematize in a context where it wasn't known whether the document needed to be initialized, you can leverage TreeView.compatibility like so:

const view = tree.viewWith(config);
if (view.compatibility.canInitialize) {
  view.initialize(initialTree);
}

core-interfaces, tree: Unify IDisposable interfaces

Public APIs in @fluidframework/tree now use IDisposable from @fluidframework/core-interfaces replacing disposeSymbol with "dispose".

IDisposable in @fluidframework/core-interfaces is now @sealed indicating that third parties should not implement it to reserve the ability for Fluid Framework to extend it to include Symbol.dispose as a future non-breaking change.

telemetry-utils: Breaking Change: Update MockLogger's events property is no longer externally mutable

If you depended on this mutability to implement some behavior, you should create your own mock logger implementation.

If you depended on this mutability to work around the logger's self-clearing behavior after running a match check, you can now override this behavior via the clearEventsAfterCheck parameter.

telemetry-utils: Deprecate MockLogger for external use.

No replacement API is given. This type was never intended for use outside of the fluid-framework repository.
If you were depending on this class for testing purposes, we recommend creating your own mock logger implementation,
or copy and adapt the code from fluid-framework as needed.

Notable Updates

Update to TypeScript 5.4

Update package implementations to use TypeScript 5.4.5.

Update to ES 2022

Update tsconfig to target ES 2022.

azure-client, tinylicious-client: compatibilityMode parameter added to createContainer and getContainer on AzureClient and TinyliciousClient

To support migration from 1.x to 2.0, a compatibility mode parameter has been added to these methods on AzureClient and TinyliciousClient. When set to "1", this allows interop between the 2.0 clients and 1.x clients. When set to "2", interop with 1.x clients is disallowed but new 2.0 features may be used.

tree: Adjusted Listenable multi-event subscription policy.

Listenable.on() no longer supports the same listener function object being registered twice for the same event. The deregister function returned by Listenable.on() may now be called multiple times with no effect.

tinylicious-client: Types are now beta

TinyliciousClient and related types have been promoted to @beta.

tree: object node fields with statically known default values are now optional

Makes object node fields with statically known default values (i.e., optional and identifier fields) optional when creating trees, where they were previously required.

Example:

class Foo extends schemaFactory.object("Foo", {
  name: schemaFactory.string,
  id: schemaFactory.identifier,
  nickname: schemaFactory.optional(schemaFactory.string),
}) {}

// Before
const foo = new Foo({
  name: "Bar",
  id: undefined, // Had to explicitly specify `undefined` to opt into default behavior
  nickname: undefined, // Had to explicitly specify `undefined` for optional field
});

// After
const foo = new Foo({
  name: "Bar",
  // Can omit `id` and `nickname` fields, as both have statically known defaults!
});

tree: Fix AfterBatch event

TreeViewEvents.afterBatch is now triggered when appropriate instead of never firing.

tree: Implement compatibility-based schema evolution API

This change adjusts some top-level APIs for using SharedTree to better accommodate applications that need to change their schema. These changes enable forwards compatibility with future work to relax SharedTree's restrictions around view schema and stored schema compatibility. That future work will enable more flexible policies around how applications can update their documents' schemas over time.

Application authors are encouraged to develop a compatibility policy which they are comfortable with using the guidance in the "Schema Evolvability" section of @fluidframework/tree's readme.

To make the details of schema compatibilities that SharedTree supports more clear, TreeView.error has been functionally replaced with the compatibility property. Users desiring the previous strict behavior should use view.compatibility.isEquivalent at appropriate places in application logic.

Deprecations

container-loader: IDetachedBlobStorage is deprecated and replaced with a default in memory store for detached blobs

IDetachedBlobStorage will be removed in a future release without a replacement.

When applications load a container without specifying ILoaderServices.detachedBlobStorage, an implementation which stores the blobs in memory will be injected by Fluid.

IDetachedBlobStorage as well as application-defined implementations of it are deprecated and support will be removed for them in a future update. Applications are recommended to stop providing this property on ILoaderServices.

Further Updates

sequence: Stop ISharedString extending SharedObject

ISharedString no longer extends SharedSegmentSequence and instead extends the new ISharedSegmentSequence, which may be missing some APIs.

Attempt to migrate off the missing APIs, but if that is not practical, request they be added to ISharedSegmentSequence and cast to SharedSegmentSequence as a workaround temporally.

runtime-definitions: Remove deprecated 'get' and 'serialize' members on the ITelemetryContext interface

The ITelemetryContext interface was not intended to allow getting properties that had been added to it, so it is now "write-only". Internal usage within FluidFramework should use the new ITelemetryContextExt.

Separate schemaChanged event on TreeView

The previous rootChanged event was called whenever the root was invalidated, which happens on changes to the document schema as well as changes to the root field (i.e. usage of TreeView.root's setter on a local client, or acking such a change made by a remote client).

There was no distinct schemaChanged event, meaning that any time the root changed, clients would have needed to check the error state on TreeView to see if the document's underlying schema had been changed.

Now, the latter case of the document's underlying schema changing has been split off into a schemaChanged event, which will fire before rootChanged. This should allow applications to run slightly less compatibility logic to routine changes to the root field.

tree: Fix bug where reading tree during events could cause issues

Reading the tree inside of NodeChange and TreeChange events could corrupt internal memory structures leading to invalid data in subsequence reads as well as internal errors being thrown. This bug has been fixed.

fluid-framework: Cleanup fluid-framework legacy exports

Cleanup fluid-framework legacy exports to remove no longer required types.

data-objects: Fix using Signaler in ContainerSchema

Signaler now implements SharedObjectKind<ISignaler>, allowing its use in ContainerSchema which was broken when ContainerSchema was made more strict. Additionally fewer encapsulated APIs are exposed on Signaler and the instance type must now be ISignaler (instead of Signaler), which has been extended to have an "error" event which was previously missing.

runtime-definitions: Make IInboundSignalMessage alpha and readonly

Users of IInboundSignalMessage will need to import it from the /legacy scope and should not mutate it. Only users of existing @alpha APIs like IFluidDataStoreRuntime should be able to use this type, so it should not introduce new /legacy usage.

Updated server dependencies

The following Fluid server dependencies have been updated to the latest version, 5.0.0. See the full changelog.

  • @fluidframework/gitresources
  • @fluidframework/server-kafka-orderer
  • @fluidframework/server-lambdas
  • @fluidframework/server-lambdas-driver
  • @fluidframework/server-local-server
  • @fluidframework/server-memory-orderer
  • @fluidframework/protocol-base
  • @fluidframework/server-routerlicious
  • @fluidframework/server-routerlicious-base
  • @fluidframework/server-services
  • @fluidframework/server-services-client
  • @fluidframework/server-services-core
  • @fluidframework/server-services-ordering-kafkanode
  • @fluidframework/server-services-ordering-rdkafka
  • @fluidframework/server-services-ordering-zookeeper
  • @fluidframework/server-services-shared
  • @fluidframework/server-services-telemetry
  • @fluidframework/server-services-utils
  • @fluidframework/server-test-utils
  • tinylicious
Assets 2
Loading