WebAssembly Threads: Localhost Works, Production Fails on SharedArrayBuffer

WebAssembly modules compiled with Emscripten's -pthread flag, or any module that uses the WebAssembly Threads proposal alongside SharedArrayBuffer, rely on browser-enforced Spectre mitigations. These mitigations manifest as requirements for Cross-Origin-Opener-Policy and Cross-Origin-Embedder-Policy headers on the top-level document. On localhost, browsers typically skip these checks, allowing instantiation without extra response headers. In production, however, the same-origin policy and header enforcement apply, causing instantiation to fail with an OperationError or the message "SharedArrayBuffer not available".

Confirmed facts from the model-knowledge research brief: the use of SharedArrayBuffer triggers browser Spectre mitigations; localhost deployments bypass COOP/COEP checks; production environments require Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp (or credentialless); server-side runtimes such as Node.js, Wasmtime, and Wasmer do not enforce these browser policies; CDN or reverse-proxy layers can strip or override these headers, making network-edge verification necessary.

The practical verification step is to inspect the response headers of the top-level document. Using a scoped command such as curl -I https://your-domain.com will reveal whether Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp (or credentialless) are present. If headers are missing or altered by a CDN, adding them at the origin server or configuring the edge to preserve them resolves the instantiation error.

Regarding the open questions: a header-free fallback for environments that cannot set COOP/COEP (e.g., embedded iframes, restricted hosting) is possible only by disabling threads or avoiding SharedArrayBuffer entirely, which changes the module's capabilities. COEP: credentialless may offer broader compatibility than require-corp across some older browser versions, but require-corp is more reliably supported for cross-origin resource isolation. Additionally, a WebAssembly module can detect the missing isolation at load time and gracefully degrade by falling back to a single-threaded execution path, though this depends on the application's thread usage patterns.

To determine whether a header-free fallback or a specific COEP mode is appropriate for your setup, what is the target browser version range and hosting platform? This detail changes the recommended degradation path.