OdspClient: Support more extensive app scenarios (Designer app)

[vladsud]

Scenario/ success criteria

The goal of it is to enable more scenarios for OdspClient, in particular - enable scenarios that Designer app needs, and scenarios that they will likely need in nearest future (based on our experience with another Odsp app - Loop).

1. Leverage our declarative model (mostly this is about SharedTree).
2. Successfully implement the following scenarios (in priority order):
   1. Store FF content in alternate partitions. Designer will follow SPO Pages design and store FF data not in main partition of a file, but in alternate partition of SharePoint file. This difference is mostly transparent for FF layers (as SharePoint redirects all calls to such partition, based on file extension), but creation flow differs - instead of file name, we need to pass itemId of existing file.
   2. Support CLP (i.e. clp-compliant apps need to pass extra header).
   3. Expose ODSP driver policies and capabilities, including provide ability for the app to use caching layer.
   4. Enable sharing flow and working with sharing links, including single roundtrip scenarios
   5. Properly expose types & signatures of the APIs: IFluidContainer.attach() should have proper type and reflect the input parameter type (broken today).

Reframing in Fluid language

The problem is - how do we expose rich set of scenarios that ODSP driver supports, in a way that is

1. Easily discoverable
2. Self documenting
3. And ideally - can be leveraged using our declarative API model (i.e. using OdspClient), with an eye toward learning and taking this knowledge / direction to encapsulated model as well.

Sharing workflow & Design choices

We provide a set of URI resolvers that make it easier for the application to work with SharePoint canonical and sharing links. Canonical links are not controlled by the application, and thus there some value in providing common tools to deal with that. Sharing links are a bit more nuanced, as applications could (depending on scenarios) add their own payloads (nav parameter) and construction of such payload could be app specific. It's not possible to work efficiently with sharing links without having file identity information that is usually encoded in such nav parameter.

On top of that dealing with URIs and URI resolves is extremely hard - the protocol / types are not in clear sight, it's extremely hard to learn what functionality exists or functionality app has to use.

As such, I chose to build and expose IOdspCreateRequest & IOdspOpenRequest (see here) interfaces that describe all the functionality that ODSP driver exposes and provide adapters to convert them to existing flows (based on IOdspResolvedUrl used across the driver). This way clients could

• encode & decode URIs on their own, fully controlling their format
• have type-safe interaction with FF
• know all the functionality available or required from the app.

This does not eliminate us providing stock implementations for various common flows, like parsing or generating canonical links.

Compatibility considerations

This prototype explores what it takes to make existing OdspClient flows to support scenarios outlined above. It goes without saying that it will be breaking change if we go that route (and we will need to introduce these breaks ASAP), and the only issue is - how breaking.

That said, we could also abandon OdspClient as is and create OdspClient2. Or push Designer (and any new app that is in similar need) toward using loader + odsp driver. That said, even if we go loader + odsp driver, it's not wasted effort, as it's really hard to figure out contracts in the system hiding behind IRequest opaque interface. Part of this work is discovery and figuring out what typical app needs, and thus having right inputs into decision tree.

The other aspect to consider - these changes impact AzureClient. There are options here, but if we absolutely do not want to change any type touching AzureClient, we likely need a bigger fork (I've tried to preserve as much of shared types here as possible between AFR and ODSP flows).

Where to start with review

1. packages/drivers/odsp-driver-definitions/src/resolvedUrl.ts - newly created ODSP interfaces
2. packages/framework/fluid-static/src/fluidContainer.ts - common code between various clients, parametrization of various interfaces to properly support customized flows.
3. packages/service-clients/odsp-client/src/interfaces.ts has most of the changes (types) for OdspClient flow.
4. packages/service-clients/odsp-client/src/odspClient.ts demonstrates actual flows (encoding / decoding sharing links, etc.)

Open questions / Questionable flows

1. It's a bit weird to provide driveId & siteURI when container open flow is based on sharing link and thus does not use this info - it gets identity of the file from sharing link. Maybe we move it out into stand-alone API (to create container from sharing link)?
2. I downgraded some OdspClient types from @ beta to @ alpha, as I have to take dependency on a bunch of @ alpha types. We can upgrade them all to beta

What is not done

1. Test everything
   • sharing flow
   • alt partition flow
2. There are a number of eslint-disable-next-line import/no-internal-modules rules to import from @fluidframework/odsp-client/internal - need to add proper projects into exception list.

[changeset-bot[bot]]

⚠️ No Changeset found

Latest commit: af752a7136ff5dc06e4335f315f9ec3ebaac5581

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[msfluid-bot]

⯅ @fluid-example/bundle-size-tests: +1.41 KB

Metric Name	Baseline Size	Compare Size	Size Diff
aqueduct.js	457.41 KB	457.44 KB	⯅ +35 Bytes
azureClient.js	554.57 KB	554.63 KB	⯅ +55 Bytes
connectionState.js	680 Bytes	680 Bytes	■ No change
containerRuntime.js	258.08 KB	258.09 KB	⯅ +14 Bytes
fluidFramework.js	408.36 KB	408.37 KB	⯅ +14 Bytes
loader.js	134.04 KB	134.05 KB	⯅ +14 Bytes
map.js	42.13 KB	42.14 KB	⯅ +7 Bytes
matrix.js	146.42 KB	146.42 KB	⯅ +7 Bytes
odspClient.js	522.72 KB	523.93 KB	⯅ +1.21 KB
odspDriver.js	97.55 KB	97.57 KB	⯅ +21 Bytes
odspPrefetchSnapshot.js	42.61 KB	42.62 KB	⯅ +14 Bytes
sharedString.js	163.14 KB	163.15 KB	⯅ +7 Bytes
sharedTree.js	398.87 KB	398.88 KB	⯅ +7 Bytes
Total Size	3.3 MB	3.3 MB	⯅ +1.41 KB

---

Baseline commit: 7f0fbf7742c6af479613eef25ea6951efb443bdf

Generated by :no_entry_sign: dangerJS against b49ecac3bbe70362c9e1102cb5a00c148e841561

[github-actions[bot]]

🔗 Found some broken links! 💔

Run a link check locally to find them. See https://github.com/microsoft/FluidFramework/wiki/Checking-for-broken-links-in-the-documentation for more information.

linkcheck output

> [email protected] ci:linkcheck /home/runner/work/FluidFramework/FluidFramework/docs
> start-server-and-test ci:start 1313 linkcheck:full

1: starting server using command "npm run ci:start"
and when url "[ 'http://127.0.0.1:1313' ]" is responding with HTTP status code 200
running tests using command "npm run linkcheck:full"


> [email protected] ci:start
> http-server ./public --port 1313 --silent


> [email protected] linkcheck:full
> npm run linkcheck:fast -- --external


> [email protected] linkcheck:fast
> linkcheck http://localhost:1313 --skip-file skipped-urls.txt --external

Crawling...

Access to these URLs denied by robots.txt, so we couldn't check them:
- https://aka.ms/fluid/devtool
- https://aka.ms/fluid/devtool/chrome
- https://aka.ms/fluid/devtool/edge
- https://aka.ms/fluid/release_blog
- https://aka.ms/fluid/samples
- https://go.microsoft.com/fwlink/?linkid=2259814

http://localhost:1313/docs/api/v1/azure-client/azurefunctiontokenprovider-class/
- (2855:134) 'https://..' => https://github.com/microsoft/FluidFramework/issues/13693 (HTTP 429)
- (2855:134) 'https://..' => https://github.com/microsoft/FluidFramework/issues/13693 (HTTP 429)

http://localhost:1313/docs/api/v1/container-runtime-definitions/idatastorewithbindtocontext_deprecated-interface/
- (2855:30) 'https://..' => https://github.com/microsoft/FluidFramework/issues/9127 (HTTP 429)
- (2855:30) 'https://..' => https://github.com/microsoft/FluidFramework/issues/9127 (HTTP 429)

http://localhost:1313/docs/api/v1/sequence/sharednumbersequence-class/
- (2855:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3008:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3072:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3134:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3147:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (2855:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3008:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3072:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3134:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3147:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)

http://localhost:1313/docs/api/v1/sequence/sharednumbersequencefactory-class/
- (2854:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3042:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3053:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3064:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3074:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3085:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3136:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3210:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (2854:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3042:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3053:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3064:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3074:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3085:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3136:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3210:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)

http://localhost:1313/docs/api/v1/sequence/sharedobjectsequence-class/
- (2855:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3030:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3094:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3178:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3191:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (2855:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3030:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3094:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3178:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3191:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)

http://localhost:1313/docs/api/v1/sequence/sharedobjectsequencefactory-class/
- (2854:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3042:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3053:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3064:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3074:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3085:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3136:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3210:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (2854:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3042:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3053:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3064:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3074:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3085:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3136:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)
- (3210:145) 'https://..' => https://github.com/microsoft/FluidFramework/issues/8526 (HTTP 429)

http://localhost:1313/docs/data-structures/sequences/
- (3330:77) 'this git..' => https://github.com/microsoft/FluidFramework/issues/8518 (HTTP 429)


Stats:
  377845 links
    2990 destination URLs
       8 URLs ignored
       0 warnings
       4 errors

 ELIFECYCLE  Command failed with exit code 1.

[microsoft-github-policy-service[bot]]

This PR has been automatically marked as stale because it has had no activity for 60 days. It will be closed if no further activity occurs within 8 days of this comment. Thank you for your contributions to Fluid Framework!