Unify Blazor WebAssembly JS interop implementation

[SteveSandersonMS]

Summary

This is a prerequisite for completing the JS object reference work.

Rather than rely on specific combinations of parameters and invocation semantics being hardcoded in the dotnet.wasm runtime, we should replace the underlying transport with a simpler, more flexible mechanism. This will give us the ability to extend it for JS object reference, and any other enhancements we want in the future, without needing more runtime changes.

Motivation

Today, Blazor WebAssembly JS interop is achieved via two InternalCall methods, whose JavaScript implementations are hardcoded inside the runtime here and here. These two JS methods declare specific combinations of parameters for sync vs async calls and also know about marshalled vs unmarshalled calls.

Having this logic in the runtime limits flexibility for us when working in the aspnetcore repo. For example, as part of the JS object reference work, we'll need to add another parameter such as targetObjectId, but:

• It's inconvenient to thread this extra param through lots of layers, including working across repos
• In the case of unmarshalled interop, it's not clear we even can add another parameter. Historically, the Emscripten internal calls were limited to a maximum of 5 params, and mono_wasm_invoke_js_unmarshalled already uses 5 (not sure if the param count limit has been raised since). We could work around this in the marshalled case by repurposing argsJson to hold arbitrary framework-controlled metadata with the true args embedded inside it, but there's no such flexibility for unmarshalled interop.

Rather than fighting this every time we want to extend JS interop, I propose a different and simpler way of transporting the interop calls, which unifies the sync/async cases and the marshalled/unmarshalled cases, plus lets us pass through arbitrary unlimited metadata which can be changed purely within the aspnetcore repo without needing runtime changes. To enable this, I've already made and merged a PR in the runtime repo. What's left is for us to wire this up to Blazor.

Goals

• Be able to add an extra param for JS object reference in all interop forms (sync/async/unmarshalled)
• Be free to make other arbitrary changes to what info we provide, and what are the semantics of the calls, in the future without needing runtime changes. Example: to add another flag saying the return value should not be JSON serialized.
• Exactly retain the semantics of sync/async/unmarshalled interop calls (e.g., parameter formats, async completion flow, error handling), plus no meaningful extra overhead on unmarshalled calls.
• Don't change any public APIs. This is an internal implementation change only.

Non-goals

• Retaining back-compat with any code relying on the private InternalCall methods (e.g., through private reflection).

Scenarios

This should work with all the flavors of JS interop: sync, async, unmarshalled.

Risks

• We might accidentally change some very subtle detail about the semantics of the calls. TBH I think we won't because this should be a pretty mechanical change.

Interactions with other features

Although JS interop is used extensively throughout Blazor and by user code, since we intend to retain the existing semantics exactly, there should be no impact on any other feature.

This does not affect or touch JS interop in Blazor Server in any way at all.

[SteveSandersonMS]

Implementation suggestion

Once the runtime PR flows all the way into the aspnetcore repo, we will be able to declare a new InternalCall method in here. For example:

[MethodImpl(MethodImplOptions.InternalCall)]
public static extern TRes InvokeJS<T0, T1, T2, TRes>(out string exception, ref JSCallInfo callInfo, [AllowNull] T0 arg0, [AllowNull] T1 arg1, [AllowNull] T2 arg2);

Note that it must be called InvokeJS in order to match up to the runtime declaration. The JSCallInfo type is a new concept and is how we can pass arbitrary metadata with the call. We have to pass it by ref so that the JS-side code gets a pointer to the stack variable and can read it with no copying or allocations. The type may look similar to the following:

[StructLayout(LayoutKind.Explicit, Pack = 4)]
internal struct JSCallInfo
{
    [FieldOffset(0)] public string FunctionIdentifier;
    [FieldOffset(4)] public JSCallResultType ResultType;

    // If MarshalledCallArgsJson is nonnull, this signals that the
    // args are being passed with JSON serialization. In this case
    // the call's arg0/arg1/arg2 parameters must be ignored.
    [FieldOffset(8)] public string MarshalledCallArgsJson;

    // If MarshalledCallAsyncHandle is nonzero and this is a JSON-marshalled
    // call, indicates that this begins an async invocation and provides the
    // call handle. For unmarshalled calls, this value will be ignored.
    [FieldOffset(12)] public long MarshalledCallAsyncHandle;

    // In the future, we can also add this for JS object reference calls:
    // [FieldOffset(20)] public long TargetInstanceId;
}

internal enum JSCallResultType : int
{
    /// <summary>
    /// Signals that the call should use the default result type handling.
    /// For JSON-marshalled calls, this means serializing it as JSON. For
    /// unmarshalled calls, this means returning the result directly
    /// (relying on it being a valid pointer or value).
    /// </summary>
    Default = 0,

    // In the future, we may add other result types, e.g.:
    // JSObjectReference = 1,
    // Void = 2, (signals that the JS code should discard any result and not try to JSON-serialize it)
}

Given these declarations, the implementations of WebAssemblyJSRuntime.cs's InvokeJS, BeginInvokeJS, and InvokeUnmarshalled can all be changed to call InternalCalls.InvokeJS instead of the older internal calls they used before. They can each construct a JSCallInfo describing the call they want to make, and pass it by ref to InternalCalls.InvokeJS.

The runtime will then attempt to pass through this call to our JS function Blazor._internal.invokeJSFromDotNet, which does not yet exist. We should define this new JS function and have it read the metadata out of the callInfo struct using the existing helper functions for unmarshalled reading of .NET structs in JS, similar to how we read RenderTreeFrame structs in JS. For example, like this:

// readStringField is exported by `MonoPlatform.ts`
const functionIdentifier = readStringField(callInfo, 0); // 0 is the `FieldOffset` for this field on the struct

// Or if you wanted the async handle:
const asyncHandle = readUint64Field(callInfo, 12); // It's actually an int64 not uint64, but it will never be negative so this produces the correct result

From there, Blazor._internal.invokeJSFromDotNet can pass this call through to:

• DotNet.jsCallDispatcher.invokeJSFromDotNet for marshalled sync calls
• DotNet.jsCallDispatcher.beginInvokeJSFromDotNet for marshalled async calls
• Directly to the referenced function for unmarshalled calls. To locate the referenced function, call DotNet.jsCallDispatcher.findJSFunction, passing the function identifier as a JavaScript string.

This should deal with retaining all the existing call semantics, including error handling. Note that you don't have to catch any exceptions inside Blazor._internal.invokeJSFromDotNet, because synchronous error handling is still dealt with inside the runtime.

Now, I think this all works great in theory, but of course I haven't tried it out... :)

Why we need T0 arg0, T1 arg1, T2 arg2

I know it would be tempting to think we could drop those parameters and include them in JSCallInfo. But we can't, at least not as far as I know!

The reason is that, as far as I know, having these as parameters on the InternalCall is the only way to retain the existing (and desired) semantics for how reference and value types are treated in unmarshalled calls:

• For reference types, the JS code receives a pointer to the instance on the heap
• For value types, the JS code receives data from inside the value as a number. For example, int values come through as JavaScript numbers, bool values come through as some numeric representation like 0 or 1, etc.
• In no scenario do we box anything

We can't make JSCallInfo into a generic type (because generic types can't have LayoutKind.Explicit since the field sizes would be unknown), and we can't add object-typed fields onto JSCallInfo because then value types would get boxed.

We could instead do some wildly evil tricks to find the memory address of the arguments (e.g., a pointer to the stack entry containing an int) and pass that, so JSCallInfo would have extra fields like IntPtr Arg0 or even void* Arg0 if we did unsafe. But that's extremely abnormal for .NET code, plus even going through calls on Marshal.* to get addresses is overhead we don't want for unmarshalled calls. It might be possible via __makeref but this is undocumented and I don't think we want to rely on it.

[SteveSandersonMS]

Further note about adding more parameters in the future, e.g., for JS object reference

If JSCallInfo also had a TargetInstanceId field, we'd probably want to pass it through to DotNet.jsCallDispatcher's invokeJSFromDotNet/beginInvokeJSFromDotNet functions. So we'd need to extend Microsoft.JSInterop.ts to know about and use this extra parameter.

Similarly for unmarshalled calls we'd want to do some extra stuff where we find the targeted instance and pass it to DotNet.jsCallDispatcher.findJSFunction, as well as using it as the this parameter when doing a call/apply on the function instance.