Add support for linked modules

[lukaslihotzki]

Like imported modules, linked modules can be added by any crate with the wasm_bindgen::link_to! macro and the existing module, raw_module or inline_js attributes. In contrast to imported modules, no imports are added to the JS shim generated by wasm-bindgen. Instead, the macro expands to an expression of type String that contains a link. This link may be relative and is suitable for creating workers or worklets, or dynamic imports.
Internally, the macro invocation wasm_bindgen::link_to!(module = "/src/task/worker.js") expands to code like (simplified):

{
	pub static _GENERATED: [u8; …] = …; // Program in custom section
	extern "C" {
		fn __wbindgen_link_9fdd114fc6bc2308() -> String; // link function
	}
	__wbindgen_link_9fdd114fc6bc2308()
}

This link function is implemented in the JS shim:

    imports.wbg.__wbindgen_link_9fdd114fc6bc2308 = function(arg0) {
        const ret = new URL('snippets/wasm-bindgen-futures-b12f15e5e844bdeb/src/task/worker.js', import.meta.url).toString();
        …
    };

The main reason for this approach is that it works both without bundlers and with bundlers (like webpack >= 5) that detect the new URL(…, import.meta.url) syntax, bundle and minify the linked file, and change the link. Depending on the target, the correct alternative for import.meta.url is used.

This is a useful part of #3034. In contrast to #3034, importing the JS shim is not supported, so this PR can only be used for pure JS workers or worklets (not considering workarounds).

Fixes #2335 (Just create a script element or dynamically import your linked module before using JS classes from Rust)

[alexcrichton]

Apologies but I personally do not have the time to adequately review new major features like this. Others may be able to but I will be unable to provide review or issue support for this if it lands.

[hamza1311]

Requesting my own review so I don't forget. This is something I've experimented with and can be very useful when it comes to lazy loading modules

[lukaslihotzki]

I needed to rebase because of #3073. Because the link_to! macro is new, strict attribute checking can be enabled without breaking change.

[hamza1311]

The implementation looks fine to me. It's worth noting that I'm not too familiar with this part of the code base so I could've missed something important.

A couple of things are missing here. Can you add tests and documentation for this feature?
It's not really possible to update the book¹ so adding rustdoc comments (including an example) to the macro would be fine.

Footnotes

1. I tried reaching out to @fitzgen for push access to the repo(s) but couldn't get a hold of them. If anyone else seeing this can grant me access, that would be great. ↩

[lukaslihotzki]

Other bundlers are a valid concern. Luckily, it can be solved at bindgen time, because the generated JS import code can choose to return a data URI. It took me some time though to figure out embedding the content in AuxImport::LinkTo is a lot nicer than trying to pass WasmBindgenAux to the import code generator. Compared to compile time approaches, this prevents a dependency to set the feature unexpectedly. Also, this guarantees a consistent link-or-embed behavior and allows to display explanatory text if links are needed. Alternatively, links could be allowed automatically if embedding is impossible (maybe displaying a hint).

@Liamolucko, I'm sorry for the delay. Do you accept this approach? If so, I'll have to add tests with embedding probably. Is there anything else missing (I don't think so)?

[Liamolucko]

Good idea to put it behind a flag! I think that works out well; by default, everything 'just works', and then if you want the stricter CSP and/or lazy loading, you can manually configure your bundler to make things work and turn on the flag.

[Liamolucko]

Looks good. I just have some nitpicks about the phrasing of the docs.

[lukaslihotzki]

@Liamolucko, I have overlooked the other suggestion. It is committed now.

[Liamolucko]

Thank you for all of your work on this!