From 42b323cdbf129c897cf9bb51c1f1b9de5642ef8a Mon Sep 17 00:00:00 2001 From: Jason Hartman Date: Mon, 16 Sep 2024 11:47:41 -0700 Subject: [PATCH] build(client): publish experimental presence (#22499) + Note current Notifications limitation + Connect docs to readme with more details --- .changeset/moody-rats-cover.md | 16 ++++++++++++++++ feeds/internal-build.txt | 1 + feeds/internal-test.txt | 1 + feeds/public.txt | 1 + fluidBuild.config.cjs | 2 ++ packages/framework/presence/README.md | 11 +++++++++++ packages/framework/presence/package.json | 1 - packages/framework/presence/src/index.ts | 3 +++ 8 files changed, 35 insertions(+), 1 deletion(-) create mode 100644 .changeset/moody-rats-cover.md diff --git a/.changeset/moody-rats-cover.md b/.changeset/moody-rats-cover.md new file mode 100644 index 000000000000..df5999cd6fcb --- /dev/null +++ b/.changeset/moody-rats-cover.md @@ -0,0 +1,16 @@ +--- +"@fluid-experimental/presence": major +--- +--- +"section": feature +--- + +Experimental Presence package added + +**[@fluid-experimental/presence](https://github.com/microsoft/FluidFramework/tree/main/packages/framework/presence#readme)** is now available for investigation. The new package is meant to support presence of collaborators connected to the same container. Use this library to quickly share simple, non-persisted data among all clients or send/receive fire and forget notifications. + +API documentation for **@fluid-experimental/presence** is available at . + +There are some limitations; see the README.md of installed package for most relevant notes. + +We're just getting started. Please give it a go and share feedback. diff --git a/feeds/internal-build.txt b/feeds/internal-build.txt index 3379e378f4fb..fef09083b7a3 100644 --- a/feeds/internal-build.txt +++ b/feeds/internal-build.txt @@ -27,6 +27,7 @@ @fluidframework/undo-redo @fluidframework/synthesize @fluidframework/request-handler +@fluid-experimental/presence @fluid-experimental/oldest-client-observer @fluidframework/fluid-static fluid-framework diff --git a/feeds/internal-test.txt b/feeds/internal-test.txt index c14df41656e9..3b3a8bbb5506 100644 --- a/feeds/internal-test.txt +++ b/feeds/internal-test.txt @@ -33,6 +33,7 @@ @fluidframework/undo-redo @fluidframework/synthesize @fluidframework/request-handler +@fluid-experimental/presence @fluid-experimental/oldest-client-observer @fluidframework/fluid-static fluid-framework diff --git a/feeds/public.txt b/feeds/public.txt index 2692b97d0dca..15fcc91fa048 100644 --- a/feeds/public.txt +++ b/feeds/public.txt @@ -26,6 +26,7 @@ @fluidframework/undo-redo @fluidframework/synthesize @fluidframework/request-handler +@fluid-experimental/presence @fluid-experimental/oldest-client-observer @fluidframework/fluid-static fluid-framework diff --git a/fluidBuild.config.cjs b/fluidBuild.config.cjs index 821dd7d7fc39..c90e80312ea9 100644 --- a/fluidBuild.config.cjs +++ b/fluidBuild.config.cjs @@ -328,6 +328,8 @@ module.exports = { "^examples/data-objects/table-document/", // AB#8147: ./test/EditLog export should be ./internal/... or tagged for support "^experimental/dds/tree/", + // comments in api-extractor JSON files fail parsing - PR #22498 to fix + "^packages/framework/presence/", // Packages with APIs that don't need strict API linting "^build-tools/", diff --git a/packages/framework/presence/README.md b/packages/framework/presence/README.md index d9b1e80a9fd6..2950f4918636 100644 --- a/packages/framework/presence/README.md +++ b/packages/framework/presence/README.md @@ -61,6 +61,10 @@ const presence = await acquirePresenceViaDataObject(container.initialObjects.pre ## Limitations +### States Reliability + +The current implementation relies on Fluid Framework's Signal infrastructure instead of Ops. This has advantages, but comes with some risk of unreliable messaging. The most common known case of unreliable signals occurs during reconnection periods and current implementation attempts to account for that. Be aware that all clients are not guaranteed to arrive at eventual consistency. Please [file a new issue](https://github.com/microsoft/FluidFramework/issues/new?assignees=&labels=bug&projects=&template=bug_report.md&title=Presence:%20States:%20) if one is not found under [Presence States issues](https://github.com/microsoft/FluidFramework/issues?q=is%3Aissue+%22Presence%3A+States%3A%22). + ### Compatibility and Versioning Current API does not provide a mechanism to validate that state and notification data received within session from other clients matches the types declared. The schema of workspace address, states and notifications names, and their types will only be consistent when all clients connected to the session are using the same types for a unique value/notification path (workspace address + name within workspace). In other words, don't mix versions or make sure to change identifiers when changing types in a non-compatible way. @@ -82,6 +86,13 @@ presence.getStates("app:v1states", { myState2: Latest({x: true})}); would be compatible with both of the prior schemas as "myState2" is a different name. Though in this situation none of the different clients would be able to observe each other. +### Notifications + +Notifications API is mostly unimplemented. All messages are always broadcast even if `unicast` API is used and all are emitted as `unattendedNotification` event rather than the appropriate custom event. + +Notifications are fundamentally unreliable at this time as there are no built-in acknowledgements nor retained state. To prevent most common loss of notifications, always check for connection before sending. + + ### Experimental diff --git a/packages/framework/presence/package.json b/packages/framework/presence/package.json index 4f8a929207e6..e6dd6ff87c9f 100644 --- a/packages/framework/presence/package.json +++ b/packages/framework/presence/package.json @@ -1,7 +1,6 @@ { "name": "@fluid-experimental/presence", "version": "2.3.0", - "private": true, "description": "A component for lightweight data sharing within a single session", "homepage": "https://fluidframework.com", "repository": { diff --git a/packages/framework/presence/src/index.ts b/packages/framework/presence/src/index.ts index d68a4fa545a9..e5ca80920656 100644 --- a/packages/framework/presence/src/index.ts +++ b/packages/framework/presence/src/index.ts @@ -5,6 +5,9 @@ /** * Experimental package for client presence within a connected session. + * + * See {@link https://github.com/microsoft/FluidFramework/tree/main/packages/framework/presence#readme | README.md } for an overview of the package. + * * @packageDocumentation */