{"pin":{"key":"spec/main","sha":"d7b37e4170d8315f2f1283aed4e8076591a9a333","spec":"web-api","version":"main"},"sections":[{"id":"intro","anchors":["intro"],"title":"Introduction","level":2,"path":"web-api","prose":"This document builds off of the WebAssembly specification WEBASSEMBLY and the WebAssembly JavaScript embedding WASMJS.\nIt describes the integration of WebAssembly into the broader Web platform, for example with\nadditional APIs that are implemented by Web user agents but are outside the scope of JavaScript ECMASCRIPT itself.","crossrefs":[],"formal_refs":[],"url":"https://webassembly.github.io/spec/web-api/#intro"},{"id":"streaming-modules","anchors":["streaming-modules"],"title":"Streaming Module Compilation and Instantiation","level":2,"path":"web-api","prose":"The compileStreaming(source, options) method, when invoked, returns the result of compiling a potential WebAssembly response with source using options.\n\nThe instantiateStreaming(source, importObject, options) method, when invoked, performs the following steps:\n\n 1. Let promiseOfModule be the result of compiling a potential WebAssembly response with source using options.\n 1. Return the result of instantiating the promise of a module promiseOfModule with imports importObject.\n\nTo compile a potential WebAssembly response with a promise of a Response source and WebAssemblyCompileOptions options, perform the following steps:\n\nNote: This algorithm accepts a Response object, or a\n promise for one, and compiles and instantiates the resulting bytes of the response. This compilation\n can be performed in the background and in a streaming manner. If the Response is not\n CORS-same-origin, does not represent an ok status, or does not match the\n ` application/wasm MIME type, the returned promise will be rejected with a TypeError; if\n compilation or instantiation fails, the returned promise will be rejected with a\n CompileError or other relevant error type, depending on the cause of failure.\n\n 1. Let returnValue be a new promise.\n 1. React to source:\n If source was fulfilled with value unwrappedSource:\n 1. Let response be unwrappedSource's Response/response.\n 1. Let mimeType be the result of header list/getting Content-Type from response's response/header list.\n 1. If mimeType is null, reject returnValue with a TypeError and abort these substeps.\n 1. Remove all HTTP tab or space byte from the start and end of mimeType.\n 1. If mimeType is not a byte-case-insensitive match for application/wasm , reject returnValue with a TypeError and abort these substeps.\n\n Note: extra parameters are not allowed, including the empty application/wasm; `.\n\n 1. If response is not CORS-same-origin, reject returnValue with a TypeError and abort these substeps.\n 1. If response's response/status is not an ok status, reject returnValue with a TypeError and abort these substeps.\n 1. Consume response's body as an ArrayBuffer, and let bodyPromise be the result.\n\n Note: Although it is specified here that the response is consumed entirely before compilation proceeds, that is purely for ease of specification; implementations are likely to instead perform processing in a streaming fashion. The difference is unobservable, and thus the simpler model is specified. \n\n 1. React to bodyPromise:\n If bodyPromise was fulfilled with value bodyArrayBuffer:\n 1. Let stableBytes be a copy of the bytes held by the buffer bodyArrayBuffer.\n 1. Asynchronously compile the WebAssembly module stableBytes using the networking task source and options and resolve returnValue with the result.\n If bodyPromise was rejected with reason reason:\n 1. Reject returnValue with reason.\n If source was rejected with reason reason:\n 1. Reject returnValue with reason.\n 1. Return returnValue.","crossrefs":["compile a potential WebAssembly response","instantiate a promise of a module","CORS-same-origin","ok status","a new promise","React","Response/response","header list/getting","response/header list","HTTP tab or space byte","byte-case-insensitive","reject","response/status","Consume body","get a copy of the buffer source","Asynchronously compile a WebAssembly module","networking task source","resolve","Reject","Response","WebAssemblyCompileOptions","TypeError","CompileError","ArrayBuffer"],"formal_refs":[],"url":"https://webassembly.github.io/spec/web-api/#streaming-modules"},{"id":"serialization","anchors":["serialization"],"title":"Serialization","level":2,"path":"web-api","prose":"Web user agents must augment the Module interface with the [Serializable] extended attribute.\n\nThe serialization steps, given value, serialized, and forStorage, are:\n\n 1. If forStorage is true, throw a \"DataCloneError\" DOMException.\n\n 1. Set serialized.\\[[Bytes]] to the sub-serialization of value.\\[[Bytes]].\n\n 1. Set serialized.\\[[AgentCluster]] to the current Realm's corresponding agent cluster.\n\nThe deserialization steps, given serialized, value, and targetRealm are:\n\n 1. Let bytes be the sub-deserialization of serialized.\\[[Bytes]].\n\n 1. Set value.\\[[Bytes]] to bytes.\n\n 1. If targetRealm's corresponding agent cluster is not serialized.\\[[AgentCluster]], then throw a \"DataCloneError\" DOMException.\n\n 1. Compile a WebAssembly module from bytes and set value.\\[[Module]] to the result.\n\nEngines should attempt to share/reuse internal compiled code when performing\na structured serialization, although in corner cases like CPU upgrade or browser\nupdate, this might not be possible and full recompilation may be necessary.\n\nNote: The semantics of a structured serialization is as-if the binary source, from which the\nModule was compiled, is serialized, then deserialized, and recompiled into the target realm.\nGiven the above engine optimizations, structured serialization provides developers\nexplicit control over both compiled-code caching and cross-window/worker code\nsharing.","crossrefs":["serialization steps","sub-serialization","current Realm","agent cluster","deserialization steps","sub-deserialization","Compile a WebAssembly module","Module","DOMException"],"formal_refs":[],"url":"https://webassembly.github.io/spec/web-api/#serialization"},{"id":"conventions","anchors":["conventions"],"title":"Developer-Facing Display Conventions","level":2,"path":"web-api","prose":"This section is non-normative.\n\nBrowsers, JavaScript engines, and offline tools have common ways of referring to\nJavaScript artifacts and language constructs. For example, locations in\nJavaScript source code are printed in stack traces or error messages, and are\nrepresented naturally as decimal-format lines and columns in text files. Names\nof functions and variables are taken directly from the sources. Therefore (for\nexample) even though the exact format of implementation-dependent stack trace\nstrings does not always match, the locations are easily understandable and the\nsame across browsers.\n\nTo achieve the same goal of a common representation for WebAssembly constructs, the\nfollowing conventions are adopted.\n\nA WebAssembly location is a reference to a particular instruction in the binary, and may be\ndisplayed by a browser or engine in similar contexts as JavaScript source locations.\nIt has the following format:\n\n${url}:wasm-function[${funcIndex}]:${pcOffset}\n\nWhere\n ${url} is the URL associated with the module, if applicable (see notes).\n ${funcIndex} is the function index relative to the module.\n ${pcOffset} is the offset in the module binary of the first byte of the instruction, printed in hexadecimal with lower-case digits, with a leading 0x prefix.\n\nNotes:\n The URL field may be interpreted differently depending on the\n context. When the response-based\n instantiation API is used in a\n browser, the associated URL should be used; or when the\n ArrayBuffer-based instantiation\n API is used, the browser should represent\n the location of the API call. This kind of instantiation is analogous to\n executing JavaScript using eval; therefore if the browser has an existing\n method to represent the location of the eval call it can use a similar\n one for WebAssembly.instantiate. For example if the browser uses\n foo.js line 10 > eval or eval at bar (foo.js:10:3) for eval, it could\n use foo.js line 10 > WebAssembly.instantiate or\n WebAssembly.instantiate at bar (foo.js:10:3), respectively.\n Offline tools may use a filename instead.\n Using hexadecimal for module offsets matches common conventions in native tools\n such as objdump (where addresses are printed in hex) and makes them visually\n distinct from JavaScript line numbers. Other numbers are represented in decimal.\n\nWhile the \"name\" property of an Exported Function instance\nis specified by the [[WASMJS|JS API]], synthesized function names are also\ndisplayed in other contexts like call stacks in debuggers and string representations\nof stack traces.\nIf a WebAssembly module contains a name section,\nthese names should be used to synthesize a function name as follows:\n If a function name subsection is present, the displayed name should be ${module_name}.${function_name} or ${function_name}, depending on whether the module name is present.\n Otherwise, the output can be context-dependent:\n If the function name is shown alongside its location in a stack trace, then just the module name (if present) or an empty string can be used (because the function index is already in the location).\n * Otherwise, ${module_name}.wasm-function[${funcIndex}] or wasm-function[${funcIndex}] should be used to convey the function index.\n\nNote that this document does not specify the full format of strings such as\nstack frame representations; this allows engines to continue using their\nexisting formats for JavaScript (which existing code may already be depending\non) while still printing WebAssembly frames in a format consistent with\nJavaScript.","crossrefs":["function index","instantiate","Exported Function","name section","ArrayBuffer"],"formal_refs":[],"url":"https://webassembly.github.io/spec/web-api/#conventions"},{"id":"mediaType","anchors":["mediaType"],"title":"Media-type Registration","level":2,"path":"web-api","prose":"The media type application/wasm has been registered with the IANA media type database IANA-MEDIA-TYPES,\nwith the following registration template:\n\napplication/wasm\n\nType Name:\n application\nSubtype Name:\n wasm\nRequired Parameters:\n None\nOptional Parameters:\n None\nEncoding Considerations:\n binary\nSecurity Considerations:\n \n WebAssembly is a standard, a safe, portable, low-level code format. The\n security considerations associated with executing WebAssembly code are\n described in https://www.w3.org/TR/wasm-core/#security-considerations.\n The WebAssembly format includes no integrity or privacy protection. If\n such protection is needed it must be provided externally, e.g., through\n the use of HTTPS.\n \nInteroperability Considerations:\n See WebAssembly Core Conformance\n https://www.w3.org/TR/wasm-core/#conformance\nPublished specification:\n https://www.w3.org/TR/wasm-core-1/\n https://www.w3.org/TR/wasm-js-api-1/\n https://www.w3.org/TR/wasm-web-api-1/\nApplication Usage:\n The application/wasm media type is intended for use as the type used to\n describe WebAssembly files when sent over HTTP to be executed by browsers,\n which is a common scenario. Additionally, the type is used by several\n WebAssembly runtimes that take advantage of the safety and portability\n while targeting efficient execution and compact representation.\nFragment Identifier Considerations:\n None\nRestrictions on usage:\n None\nProvisional Registrations:\n N/A\nAdditional information:\n\n Deprecated alias names for this type:\n None\n Magic number(s):\n 0x00 0x61 0x73 0x6D\n File extension(s):\n .wasm\n Macintosh file type code(s):\n None\n Object Identifier(s) or OID(s):\n None\n\nIntended usage:\n Common\nOther Information & Comments:\n Common\nContact Person:\n\n Contact Name:\n Eric Prud'hommeaux\n Contact Email Address:\n eric@w3.org\n Author/Change Controller:\n W3C","crossrefs":[],"formal_refs":[],"url":"https://webassembly.github.io/spec/web-api/#mediaType"},{"id":"security-considerations","anchors":["security-considerations"],"title":"Security and Privacy Considerations","level":2,"path":"web-api","prose":"This section is non-normative.\nWebAssembly provides no access to the surrounding environment other than via the JavaScript API described in the [[WASMJS|JS API]] specification.\nTherefore, WebAssembly cannot collect or expose any information (personal, sensitive or otherwise) to Web sites or other parties beyond what can be collected, exposed or processed with JavaScript.\nWebAssembly memory has the same lifetime as the objects in the surrounding JavaScript environment and is not persisted or serialized (other than by copying it out to JavaScript and using existing serialization APIs).\nNo access is provided to the underlying platform or hardware, or to other devices, or to the user agent’s native UI.\n\nWebAssembly is an additional program execution mechanism, and can be executed wherever JavaScript can be executed.\nTherefore the threat model is essentially the same as for JavaScript code, and has similar considerations for delivery (e.g. WebAssembly code should be protected in transit from active and passive network attackers)\nand policy (e.g. some loading mechanisms or execution are restricted via mechanisms such as the same-origin policy or Content Security Policy).","crossrefs":[],"formal_refs":[],"url":"https://webassembly.github.io/spec/web-api/#security-considerations"},{"id":"change-history","anchors":["change-history"],"title":"Change History","level":2,"path":"web-api","prose":"This section is non-normative.\n\nSince the original release 1.0 of the WebAssembly specification, a number of proposals for extensions have been integrated.\nThe following sections provide an overview of what has changed.","crossrefs":[],"formal_refs":[],"url":"https://webassembly.github.io/spec/web-api/#change-history"},{"id":"release-20","anchors":["release-20"],"title":"Release 2.0","level":3,"path":"web-api","prose":"","crossrefs":[],"formal_refs":[],"url":"https://webassembly.github.io/spec/web-api/#release-20"},{"id":"changes-registration","anchors":["changes-registration"],"title":"Media-type Registraton Completed","level":4,"path":"web-api","prose":"The registration for the application/wasm media type has been successfully completed.","crossrefs":[],"formal_refs":[],"url":"https://webassembly.github.io/spec/web-api/#changes-registration"}]}