[browser] detect SIMD and EH support (#89387)

Co-authored-by: Ankit Jain <[email protected]>

Author: pavelsavara

eng/testing/performance/performance-setup.sh

@@ -403,7 +403,7 @@ if [[ -n "$wasm_bundle_directory" ]]; then
     wasm_bundle_directory_path=$payload_directory
     mv $wasm_bundle_directory/* $wasm_bundle_directory_path
     find $wasm_bundle_directory_path -type d
-    wasm_args="--expose_wasm"
+    wasm_args="--experimental-wasm-eh --expose_wasm"
     if [ "$javascript_engine" == "v8" ]; then
         # for es6 module support
         wasm_args="$wasm_args --module"

src/mono/sample/wasm/Directory.Build.targets

@@ -55,10 +55,10 @@
     <Exec WorkingDirectory="bin/$(Configuration)/AppBundle" Command="v8 --expose_wasm --module $(_WasmMainJSFileName) -- $(DOTNET_MONO_LOG_LEVEL) --run $(_SampleAssembly) $(Args)" IgnoreExitCode="true" />
   </Target>
   <Target Name="RunSampleWithNode" DependsOnTargets="BuildSampleInTree;_ComputeMainJSFileName">
-    <Exec WorkingDirectory="bin/$(Configuration)/AppBundle" Command="node --expose_wasm $(_WasmMainJSFileName) -- $(DOTNET_MONO_LOG_LEVEL) --run $(_SampleAssembly) $(Args)" IgnoreExitCode="true" />
+    <Exec WorkingDirectory="bin/$(Configuration)/AppBundle" Command="node --experimental-wasm-eh --expose_wasm $(_WasmMainJSFileName) -- $(DOTNET_MONO_LOG_LEVEL) --run $(_SampleAssembly) $(Args)" IgnoreExitCode="true" />
   </Target>
   <Target Name="DebugSampleWithNode" DependsOnTargets="BuildSampleInTree;_ComputeMainJSFileName">
-    <Exec WorkingDirectory="bin/$(Configuration)/AppBundle" Command="node --expose_wasm $(_WasmMainJSFileName) -- $(DOTNET_MONO_LOG_LEVEL) --run $(_SampleAssembly) $(Args) --inspect=9222" IgnoreExitCode="true" />
+    <Exec WorkingDirectory="bin/$(Configuration)/AppBundle" Command="node --experimental-wasm-eh --expose_wasm $(_WasmMainJSFileName) -- $(DOTNET_MONO_LOG_LEVEL) --run $(_SampleAssembly) $(Args) --inspect=9222" IgnoreExitCode="true" />
   </Target>
   <Target Name="CheckServe">
     <Exec Command="dotnet tool install -g dotnet-serve" IgnoreExitCode="true" />

src/mono/sample/wasm/wasm.mk

@@ -45,7 +45,7 @@ run-console:
 	cd bin/$(CONFIG)/AppBundle && $(V8_PATH) --stack-trace-limit=1000 --single-threaded --expose_wasm --module $(MAIN_JS) -- $(ARGS)
 
 run-console-node:
-	cd bin/$(CONFIG)/AppBundle && node --stack-trace-limit=1000 --single-threaded --expose_wasm $(MAIN_JS) $(ARGS)
+	cd bin/$(CONFIG)/AppBundle && node --stack-trace-limit=1000 --single-threaded --experimental-wasm-eh --expose_wasm $(MAIN_JS) $(ARGS)
 
 debug-console-node:
-	cd bin/$(CONFIG)/AppBundle && node --inspect=9222 --stack-trace-limit=1000 --single-threaded --expose_wasm $(MAIN_JS) $(ARGS)
+	cd bin/$(CONFIG)/AppBundle && node --inspect=9222 --stack-trace-limit=1000 --single-threaded --experimental-wasm-eh --expose_wasm $(MAIN_JS) $(ARGS)

src/mono/wasm/build/WasmApp.Native.targets

@@ -275,6 +275,10 @@
       <EmscriptenEnvVars Include="EM_FROZEN_CACHE=True" />
       <EmscriptenEnvVars Include="DISABLE_LEGACY_JS_INTEROP=1" Condition="'$(WasmEnableLegacyJsInterop)' == 'false'" />
       <EmscriptenEnvVars Include="DISABLE_LEGACY_JS_INTEROP=0" Condition="'$(WasmEnableLegacyJsInterop)' != 'false'" />
+      <EmscriptenEnvVars Include="WASM_ENABLE_SIMD=1" Condition="'$(WasmEnableSIMD)' != 'false'" />
+      <EmscriptenEnvVars Include="WASM_ENABLE_SIMD=0" Condition="'$(WasmEnableSIMD)' == 'false'" />
+      <EmscriptenEnvVars Include="WASM_ENABLE_EH=1" Condition="'$(WasmEnableExceptionHandling)' != 'false'" />
+      <EmscriptenEnvVars Include="WASM_ENABLE_EH=0" Condition="'$(WasmEnableExceptionHandling)' == 'false'" />
       <EmscriptenEnvVars Include="ENABLE_AOT_PROFILER=$([System.Convert]::ToInt32($(WasmProfilers.Contains('aot'))))" />
       <EmscriptenEnvVars Include="ENABLE_BROWSER_PROFILER=$([System.Convert]::ToInt32($(WasmProfilers.Contains('browser'))))" />
     </ItemGroup>

src/mono/wasm/features.md

@@ -0,0 +1,37 @@
+# Browser or JS engine features
+
+dotnet for wasm can be compiled with various MSBuild flags which enable the use of browser features. If you need to target an older version of the browser, then you may need to disable some of the dotnet features or optimizations.
+
+For full set of MSBuild properties [see top of](src\mono\wasm\build\WasmApp.targets)
+For set of [browser WASM features see](https://webassembly.org/roadmap/)
+
+# Multi-threading
+Is enabled by `<WasmEnableThreads>true</WasmEnableThreads>`.
+It requires HTTP headers similar to `Cross-Origin-Embedder-Policy:require-corp` and `Cross-Origin-Opener-Policy:same-origin`.
+See also https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer#security_requirements
+
+# SIMD - Single instruction, multiple data
+Is performance optimization enabled by default. It requires recent version of browser.
+You can disable it by `<WasmEnableSIMD>false</WasmEnableSIMD><WasmBuildNative>true</WasmBuildNative>`.
+[See also](https://github.com/WebAssembly/simd/blob/master/proposals/simd/SIMD.md)
+
+# EH - Exception handling
+Is performance optimization enabled by default. It requires recent version of browser.
+You can disable it by `<WasmEnableExceptionHandling>false</WasmEnableExceptionHandling><WasmBuildNative>true</WasmBuildNative>`.
+[See also](https://github.com/WebAssembly/exception-handling/blob/master/proposals/exception-handling/Exceptions.md)
+
+# BigInt
+Is required if the application uses Int64 marshaling in JS interop.
+[See also](https://github.com/WebAssembly/JS-BigInt-integration)
+
+# fetch browser API
+Is required if the application uses [HttpClient](https://learn.microsoft.com/en-us/dotnet/api/system.net.http.httpclient)
+NodeJS needs to install `node-fetch` and `node-abort-controller` npm packages.
+
+# WebSocket browser API
+Is required if the application uses [WebSocketClient](https://learn.microsoft.com/en-us/dotnet/api/system.net.websockets.clientwebsocket)
+NodeJS needs to install `ws` npm package.
+
+# Shell environments - NodeJS & V8
+We pass most of the unit tests with NodeJS v 14 but it's not fully supported target platform. We would like to hear about community use-cases.
+We also use v8 engine version 11 or higher to run some of the tests. The engine is lacking many APIs and features.

src/mono/wasm/runtime/es6/dotnet.es6.lib.js

@@ -7,6 +7,8 @@
 
 // because we can't pass custom define symbols to acorn optimizer, we use environment variables to pass other build options
 const DISABLE_LEGACY_JS_INTEROP = process.env.DISABLE_LEGACY_JS_INTEROP === "1";
+const WASM_ENABLE_SIMD = process.env.WASM_ENABLE_SIMD === "1";
+const WASM_ENABLE_EH = process.env.WASM_ENABLE_EH === "1";
 const ENABLE_BROWSER_PROFILER = process.env.ENABLE_BROWSER_PROFILER === "1";
 const ENABLE_AOT_PROFILER = process.env.ENABLE_AOT_PROFILER === "1";
 
@@ -62,6 +64,8 @@ function setup(linkerSetup) {
 const postset = `
     DOTNET.setup({ `+
     `linkerDisableLegacyJsInterop: ${DISABLE_LEGACY_JS_INTEROP ? "true" : "false"},` +
+    `linkerWasmEnableSIMD: ${WASM_ENABLE_SIMD ? "true" : "false"},` +
+    `linkerWasmEnableEH: ${WASM_ENABLE_EH ? "true" : "false"},` +
     `linkerEnableAotProfiler: ${ENABLE_AOT_PROFILER ? "true" : "false"}, ` +
     `linkerEnableBrowserProfiler: ${ENABLE_BROWSER_PROFILER ? "true" : "false"}` +
     `});

src/mono/wasm/runtime/globals.ts

@@ -24,13 +24,17 @@ export let runtimeHelpers: RuntimeHelpers = null as any;
 export let loaderHelpers: LoaderHelpers = null as any;
 // this is when we link with workload tools. The consts:wasmEnableLegacyJsInterop is when we compile with rollup.
 export let linkerDisableLegacyJsInterop = false;
+export let linkerWasmEnableSIMD = true;
+export let linkerWasmEnableEH = true;
 export let linkerEnableAotProfiler = false;
 export let linkerEnableBrowserProfiler = false;
 export let _runtimeModuleLoaded = false; // please keep it in place also as rollup guard
 
 export function passEmscriptenInternals(internals: EmscriptenInternals): void {
     ENVIRONMENT_IS_PTHREAD = internals.isPThread;
     linkerDisableLegacyJsInterop = internals.linkerDisableLegacyJsInterop;
+    linkerWasmEnableSIMD = internals.linkerWasmEnableSIMD;
+    linkerWasmEnableEH = internals.linkerWasmEnableEH;
     linkerEnableAotProfiler = internals.linkerEnableAotProfiler;
     linkerEnableBrowserProfiler = internals.linkerEnableBrowserProfiler;
     runtimeHelpers.quit = internals.quit_;

src/mono/wasm/runtime/http.ts

@@ -10,8 +10,8 @@ import type { VoidPtr } from "./types/emscripten";
 function verifyEnvironment() {
     if (typeof globalThis.fetch !== "function" || typeof globalThis.AbortController !== "function") {
         const message = ENVIRONMENT_IS_NODE
-            ? "Please install `node-fetch` and `node-abort-controller` npm packages to enable HTTP client support."
-            : "This browser doesn't support fetch API. Please use a modern browser.";
+            ? "Please install `node-fetch` and `node-abort-controller` npm packages to enable HTTP client support. See also https://aka.ms/dotnet-wasm-features"
+            : "This browser doesn't support fetch API. Please use a modern browser. See also https://aka.ms/dotnet-wasm-features";
         throw new Error(message);
     }
 }

src/mono/wasm/runtime/loader/globals.ts

@@ -1,6 +1,8 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
+import { exceptions, simd } from "wasm-feature-detect";
+
 import type { AssetEntryInternal, GlobalObjects, LoaderHelpers, RuntimeHelpers } from "../types/internal";
 import type { MonoConfig, RuntimeAPI } from "../types";
 import { assert_runtime_running, is_exited, is_runtime_running, mono_exit } from "./exit";
@@ -94,6 +96,10 @@ export function setLoaderGlobals(
         hasDebuggingEnabled,
         invokeLibraryInitializers,
 
+        // from wasm-feature-detect npm package
+        exceptions,
+        simd,
+
     } as Partial<LoaderHelpers>);
 }
 

src/mono/wasm/runtime/loader/polyfills.ts

@@ -19,19 +19,25 @@ const URLPolyfill = class URL {
 };
 
 export function verifyEnvironment() {
-    mono_assert(ENVIRONMENT_IS_SHELL || typeof globalThis.URL === "function", "This browser/engine doesn't support URL API. Please use a modern version.");
-    mono_assert(typeof globalThis.BigInt64Array === "function", "This browser/engine doesn't support BigInt64Array API. Please use a modern version.");
+    mono_assert(ENVIRONMENT_IS_SHELL || typeof globalThis.URL === "function", "This browser/engine doesn't support URL API. Please use a modern version. See also https://aka.ms/dotnet-wasm-features");
+    mono_assert(typeof globalThis.BigInt64Array === "function", "This browser/engine doesn't support BigInt64Array API. Please use a modern version. See also https://aka.ms/dotnet-wasm-features");
     if (MonoWasmThreads) {
-        mono_assert(!ENVIRONMENT_IS_SHELL && !ENVIRONMENT_IS_NODE, "This build of dotnet is multi-threaded, it doesn't support shell environments like V8 or NodeJS.");
-        mono_assert(globalThis.SharedArrayBuffer !== undefined, "SharedArrayBuffer is not enabled on this page. Please use a modern browser and set Cross-Origin-Opener-Policy and Cross-Origin-Embedder-Policy http headers. See also https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer#security_requirements");
-        mono_assert(typeof globalThis.EventTarget === "function", "This browser/engine doesn't support EventTarget API. Please use a modern version.");
+        mono_assert(!ENVIRONMENT_IS_SHELL && !ENVIRONMENT_IS_NODE, "This build of dotnet is multi-threaded, it doesn't support shell environments like V8 or NodeJS. See also https://aka.ms/dotnet-wasm-features");
+        mono_assert(globalThis.SharedArrayBuffer !== undefined, "SharedArrayBuffer is not enabled on this page. Please use a modern browser and set Cross-Origin-Opener-Policy and Cross-Origin-Embedder-Policy http headers. See also https://aka.ms/dotnet-wasm-features");
+        mono_assert(typeof globalThis.EventTarget === "function", "This browser/engine doesn't support EventTarget API. Please use a modern version. See also https://aka.ms/dotnet-wasm-features");
     }
-
-    // TODO detect other (WASM) features that are required for the runtime
-    // See https://github.com/dotnet/runtime/issues/84574
 }
 
 export async function detect_features_and_polyfill(module: DotnetModuleInternal): Promise<void> {
+    if (ENVIRONMENT_IS_NODE) {
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore:
+        const process = await import(/* webpackIgnore: true */"process");
+        const minNodeVersion = 14;
+        if (process.versions.node.split(".")[0] < minNodeVersion) {
+            throw new Error(`NodeJS at '${process.execPath}' has too low version '${process.versions.node}', please use at least ${minNodeVersion}. See also https://aka.ms/dotnet-wasm-features`);
+        }
+    }
 
     const scriptUrlQuery =/* webpackIgnore: true */import.meta.url;
     const queryIndex = scriptUrlQuery.indexOf("?");