API Review: Shared WebView2 Cluster Environment

[Navdeep-ss]

This pull request introduces the specification for a Shared WebView2 Cluster Environment, a first-class, explicit way for a set of cooperating host applications to opt into one shared WebView2 environment (a "cluster") and agree on the shared options up front. Today apps can share a browser process only implicitly by passing the same user data folder; this API makes the sharing intent explicit, keyed on a well-known ClusterName, with a clear options-match contract and a way to read a cluster's options before joining.

New APIs:

• CreateOrJoinCoreWebView2ClusterEnvironment(options, handler) — Symmetric create-or-join. The first host to establish a cluster for a given ClusterName fixes the cluster's options (first-creator-wins). A later host with matching options attaches to the running cluster; a host with different options receives COREWEBVIEW2_CLUSTER_ENVIRONMENT_STATUS_OPTIONS_MISMATCH.
• GetCoreWebView2ClusterEnvironmentOptions(clusterName, options) — Synchronously reads a running cluster's options without launching the shared browser process, so a host can decide before joining.

New Interfaces and Enums:

• ICoreWebView2ClusterEnvironmentOptions — the shared options (ClusterName, AdditionalBrowserArguments, Language, AllowSingleSignOnUsingOSPrimaryAccount, EnableTrackingPrevention, AreBrowserExtensionsEnabled, PerHostProfileIsolation, ReleaseChannels, ChannelSearchKind, CustomSchemeRegistrations).
• ICoreWebView2ClusterEnvironmentCreateResult — Status plus Environment (non-null only when the status is Succeeded).
• ICoreWebView2CreateOrJoinClusterEnvironmentCompletedHandler — completion handler for the create-or-join operation.
• COREWEBVIEW2_CLUSTER_ENVIRONMENT_STATUS — Succeeded, OptionsMismatch.

Details covered in the spec:

• User-data-folder derivation from ClusterName, lifetime and liveness model, options-matching semantics, trust/identity/session model, host-dependent option resolution, the loader-override contract, and user-data-folder deletion guidance.
• C++ and .NET/WinRT code samples for the create-or-join flow and for deleting a cluster's user data folder, plus the .NET/WinRT projection.

[FrankC-msft]

Are CustomSchemeRegistrations usually order-dependent? If not, this seems like an extra (arbitrary?) bar for coordination between apps seeking to form a cluster.

Or, if this is an existing restriction of CoreWebView2Environment ::CreateWithOptionsAsync , then appeal to consistency.

[david-risney]

Agreed that it does feel arbitrary, however practically it shouldn't be an issue: either the apps have coordinated well ahead of time and have the exact same list or they use the Get...Options method to get the exact correct list.

Please update API public docs to note that this is intended for well coordinated apps to share WebView2 and not intended for loosely coupled apps to share WebView2.

[FrankC-msft]

Does wv2 use the WinRT API preference to use return values for execution failures? Windows' WinRT APIs throw for "catastrophic errors" and "usage errors".

This appears to be throwing for execution failures, where I would expect to see a CoreWebView2ClusterEnvironmentCreateResult with .Environment == null

[FrankC-msft]

This also appears in the WinRT sample above. We appear to be requiring a try/catch to handle 0x80070032, which for OS WinRT APIs should not be required in a minimal correct usage of the API.

[david-risney]

Please see above discussion about non-exceptional status codes.

[FrankC-msft]

It seems easier for apps to accidently collide on a cluster name than would have been plausible to accidently try using an in-use userDataFolder. Do we think this is still low likelihood because clustering will be such a niche case compared to default environment creation?

[david-risney]

Please update docs to provide recommended pattern for clustername including examples:

To ensure a unique cluster name consider including your company name or a GUID, for example: Contoso.Something, or {GUID}.Something (please fix this)

[FrankC-msft]

may be out of scope of today's API addition. Is there any thinking about how someone in a Cluster can tell who else has joined?

To add something like that in v2, I think we'd add to CoreWebView2ClusterEnvironmentCreateResult so that apps joining a cluster could get some kind of queryable object or event source for info about it.

[david-risney]

Discussion: we don't know what this may look like in the future and we have room on the result or elsewhere if necessary.

[oldnewthing]

If two processes both create a cluster named "X" against different runtimes, how do they both reside in the same %LOCALAPPDATA%\Microsoft\WebView2Clusters\X directory yet remain distinct?

[david-risney]

Please update docs to note that different runtime means you can't join the cluster versus a different non-matching cluster name gives you a different cluster.

[oldnewthing]

But the attacker can just enumerate the directories under %LOCALAPPDATA%\Microsoft\WebView2Clusters to discover all cluster names.

I think we shouldn't promise that there's a way to keep untrusted code out. We can say "To make it less likely" to say that you can make it harder, but you can't stop it entirely.

[david-risney]

Please update docs to note that there is no security boundary here. Choosing a better name doesn't provide meaningly security benefits. Probably just remove final sentence.

[oldnewthing]

If two hosts both create a cluster named "X", how do they both reside in the same %LOCALAPPDATA%\Microsoft\WebView2Clusters\X directory yet remain distinct?

[david-risney]

This is specifically about Edge browser profiles not cluster names.

Please update docs to make this clearer by explicitly calling out that these are profiles within clusters.

[oldnewthing]

This code assumes that no new status values will be added in the future. Is that a safe assumption? Or should it have a

default:
     // unknown failure, don't use clusters.
    UsePrivateEnvironment();
    break;

[david-risney]

Please fix - use recommended above

[oldnewthing]

Misleading comment. Can also get here if the Status is something other than Succeeded or OptionsMismatch.

[david-risney]

Please fix. Similar to the switch with missing default above.

Please consider making the C++ & C# sample code more closely match and use matching switch or if/else

[oldnewthing]

C++ and C# are inconsistent here. If the cluster cannot be found, C++ fails the operation with ERROR_NOT_FOUND, but C# succeeds the operation and returns null.

Should align the behaviors.

[david-risney]

Please fix sample code and make sure it matches between SOK/null in C++ & C#. Slight pref for C#

Please examine exceptions from CreateCoreWebView2Environment and the new CreateOrJoin..ClusterEnv and see what errors makes sense to make into non-exceptional status results. And ensure its consistent between C++ & C#.

[oldnewthing]

Shouldn't step 0 be "use the version API to see if clusters are supported"?

[david-risney]

Please fix

[oldnewthing]

Does this mean that apps that use this feature cannot be MSIX? Because you can't run custom code at MSIX uninstall.

[david-risney]

Please consider how to resolve this or block appcontainers from using this feature (not great option because MSIX is the preferred deployment mechanism)

[oldnewthing]

Who initializes this variable m_clusterEnvironment?

I think there is a missing step: 1.5: Get the environment that we want to clean up. To do that, we need to create the environment (or join it). This will start the shared browser process, but that's apparently unavoidable. There's no way to get an environment for a non-running cluster.

GetCoreWebView2ClusterEnvironmentOptions(L"contoso.cluster", &options);
CreateOrJoinCoreWebView2ClusterEnvironment(options, Callback([](HRESULT errorCode, auto result) {
    // blah blah retry or whatever
    if (SUCCEEDED(errorCode) && result->Status == Succeeded) {
      // continue with step 2
    }
});

[david-risney]

Please fix:

1. Make the sample code show how to obtain the cluster given that many cases uninstall is totally separate process from app getting uninstalled. Or consider addiotnal uninstall sample standalone v clean on exit.
2. Do we want to make this easier? Perhaps ties into above issue resolution.

[oldnewthing]

This sample hangs because our own process is keeping the cluster environment from exiting!

Mussing step 4: Exit our environment and hope the others will exit soon too.

The only way to exit our environment appears to be to create a webview2 and then close the webview2.

m_clusterEnvironment.as<ICoreWebView2Environment3>()->CreateCoreWebview2Controller(m_mainWindow, [](HRESULT errorCode, auto controller) {
  if (SUCCEEDED(errorCode)) { controller->Close(); /* exit our webview and hope that the others will follow suit */
}
);

[david-risney]

The sample is for clean on exit not standalone uninstall. See above.

But also please examine code and make sure its correct.