Repository files navigation

Champion(s): Luca Casonato, Guy Bedford

Author(s): Luca Casonato, Guy Bedford, Nicolo Ribaudo

Stage: 3

Stage 3 reviewers: Daniel Ehrenberg, Kris Kowal

Upstream PR:tc39/ecma262#3492

For both JavaScript and WebAssembly, there is a need to be able to more closelycustomize the loading, linking, and execution of modules beyond the standardhost execution model.

For JavaScript, creating userland loaders would require a module source typein order to share the host parsing, execution, security, and caching semantics.

For WebAssembly, imports and exports for WebAssembly modules often require custominspection and wrapping in order to be set up correctly, which typically requiresmanual fetch and instantiation work that is not provided for in the current hostESM integration proposal.

Supporting syntactical module source imports as a new import phase creates aprimitive that can extend the static, security and tooling benefits of modulesfrom the ESM integration to these dynamic instantiation use cases.

This proposal allows ES modules to import a reified representation of thecompiled source of a module when the host provides such a representation:

importsourcexfrom"<specifier>";

Thesource module source loading phase name is added to the beginning of theImportStatement.

Only the above form is supported - named exports and unbound declarations arenot supported.

Just as with static and dynamic imports, there is a need for static and dynamic accessto sources, to be able to support both those sources that are required to be instantiatedfrom source text during initialization of an application, and those that are optionally orlazily created at runtime.

The dynamic form uses aimport.<phase> import call:

constx=awaitimport.source("<specifier>");

By making the phase part of the explicit syntax, it is possible to statically distinguish betweena full dynamic import and one that is only for a source (where dependencies don't need to beprocessed).

Optionalimport attributes may still be specified with the second argument in awith key,just like for dynamic import, and without conflict due to the design of phased evaluation.

Module source imports can be seen to be one type of evaluation phase.

If theasset references proposal advances in future this could be seenas another type of phase representing an earlier phase of the loading process.

importassetxfrom"<specifier>";awaitimport.asset("<specifier>");

Only thesource import source phase is specified by this proposal.

The object provided by the module source phase must be an object withAbstractModuleSource.prototype in its prototype chain, defined by this specificationto be a minimal shared base prototype for a compiled modular resource.

In addition it defines the@@toStringTag getter returning the constructor name stringcorresponding to the name of the specific module source subclass, with a stronginternal slot check.

For JavaScript modules, the module source phase is then specified to returnaModuleSource object, representing an ECMAScript Module Source, whereModuleSource.prototype.[[Proto]] is%AbstractModuleSource%.prototype.

Future proposals may then add support forbindings lookup methods,the [ModuleSource constructor][module soruce] andinstantiation support.

New properties may be added to the base%AbstractModuleSource%.prototype, or sharedwith ECMAScript module sources viaModuleSource.prototype additions.

For WebAssembly modules, the existingWebAssembly.Module.prototype object is to beupdated to have a[[Proto]] of%AbstractModuleSource%.prototype in theWebAssembly JS integration API.

This allows workflows, as explained in the motivation, like the following:

importsourceFooModulefrom"./foo.wasm";FooModuleinstanceofWebAssembly.Module;// true// For example, to run a WASI execution with an API like Node.js WASI:import{WASI}from'wasi';constwasi=newWASI({ args, env, preopens});constfooInstance=awaitWebAssembly.instantiate(FooModule,{wasi_snapshot_preview1:wasi.wasiImport});wasi.start(fooInstance);

The static analysis benefits of not needing a customfetch andWebAssembly.compileStreaming apply not only to code analysis and securitybut also for bundlers.

In turn this enablesWasm components to be able to importWebAssembly.Module objects themselves in future.

Any other host-defined module types may define their own host module sources. If a given module does not define a source representation for it's source, importing it with a "source" phase target fails with aReferenceError at link time.

Host-defined module sources must include%AbstractModuleSource%.prototype in their prototype chain and support the[[ModuleSourceRecord]] internal slot containing the@@toStringTag brand check and underlying source host data.

The native ES module loader is able to implement security policies, includingsupport forContent Security Policies in browsers. This property does not just impact platforms using CSP, but also other platforms with systems to restrict permissions, such as Deno. These policies are based on protecting which URLs are supported for the compilation and execution of scripts or modules.

Extending the static security benefits of the host module system to custom loaders is a security benefit of this proposal. For Wasm, it would enable source-specific CSP policies for dynamic Wasm instantiation.

Because[[ModuleSourceObject]] is keyed on the base module record, it will alwaysbe unique to the module being imported from.

Q: How does this relate to import attributes?

A: Import attributes are properties of the module request, while source importsrepresent phases of that specific request / key in the module map, without affectingthe idempotency of the module load. Both can be used together for a resource to indicate alternative phasing for the given module resource and attributes.

Q: How does this relate to module expressions and compartments?

A: The module object that is provided has been carefully specified here to becompatible with the linking model of module expressions and compartments.

Q: Why not just useconst module = await WebAssembly.compileStreaming(fetch(new URL("./module.wasm", import.meta.url)));?

A: There are multiple benefits: firstly if the module is staticallyreferenced in the module graph, it is easier to statically analyze (by bundlersfor example). Secondly when using CSP,script-src: unsafe-eval would not beneeded. See the security improvements section for more details.