{"slug": "how-enabling-cross-origin-isolation-silently-broke-our-multi-threaded-wasm-image", "title": "How enabling cross-origin isolation silently broke our multi-threaded WASM image compressor", "summary": "A developer's browser-side image compressor, built with Rust compiled to WASM and WebGPU, crashed for every format after enabling cross-origin isolation in production. The root cause was that the threaded WASM package, which spawns nested rayon workers, was automatically loaded when crossOriginIsolated was true, but those workers were blocked by the Cross-Origin-Embedder-Policy (COEP) require-corp header. The fix decoupled the threaded package from COI availability, defaulted to a single-threaded path, and added self-healing on worker crashes.", "body_md": "*A production postmortem. We shipped browser-side image compression (Rust → WASM + WebGPU), turned on cross-origin isolation for speed, and watched every format crash with compression worker crashed. Here's the root cause and the fix.*\n\nWe built an image compressor that runs **100% in the browser** — Rust compiled to WASM for the codec work, WebGPU for the heavy ML passes (background removal, denoise, watermark). No upload, so users' pixels never leave the device. Privacy is the whole selling point.\n\nFor the multi-threaded code paths we rely on **shared memory + atomics**, which in the browser requires `crossOriginIsolated`\n\n. So we served the document with:\n\n```\nCross-Origin-Embedder-Policy: require-corp\nCross-Origin-Opener-Policy: same-origin\n```\n\nThat gives us `crossOriginIsolated === true`\n\n, unlocks `SharedArrayBuffer`\n\n, and lets the `*‑threaded`\n\nWASM builds actually spawn workers.\n\nThe build uses a nightly toolchain (`nightly-2025-06-01`\n\n+ `-Z build-std`\n\n) with:\n\n```\nRUSTFLAGS=\"--cfg=... +atomics,+bulk-memory --shared-memory --import-memory\"\n```\n\nand a **custom rayon handle pool** (`with_turbo_pool`\n\n) instead of `build_global`\n\n, so we control worker lifecycle and can abort/self-heal.\n\nAfter flipping COEP to `require-corp`\n\nin production, **every format started crashing** with the same message:\n\n```\ncompression worker crashed\n```\n\nNot one codec — JPG, PNG, WebP, AVIF, all of them. It was a P0: the core feature was dead for every user.\n\nWhat made it nasty: it only reproduced under **real cross-origin isolation**. Local dev without COEP was fine. Staging without the header was fine. So the bug hid until it hit production traffic.\n\nThe `*‑threaded`\n\nWASM packages spin up **nested rayon workers** to parallelize the codec. Under COI + COEP `require-corp`\n\n, those nested workers get blocked by `Cross-Origin-Resource-Policy`\n\n/ COEP — the spawned worker script is treated as a cross-origin response without the right CORP header, so the browser refuses it. No worker → the rayon pool never initializes → the compression call throws `compression worker crashed`\n\n.\n\nThe trap: we had gated the *‑threaded* build on `crossOriginIsolated`\n\n:\n\n```\n// ❌ the bug: environment detection == feature enable\nif (crossOriginIsolated) {\n  loadThreadedPackage();   // boots nested rayon workers → blocked by COEP\n}\n```\n\nSo **enabling COI auto-enabled the broken path**. COI was supposed to be the enabler, but it also activated the exact code that COEP then killed. A perfect deadlock between two headers we set ourselves.\n\n(This matches the fix commits `569731d`\n\n\"默认压缩路径禁用 *-threaded 线程包\" and `73e9377`\n\n\"COI 下 module worker 被 COEP 拦死\".)\n\nThree changes, all in the loader — not the codec:\n\n**1. Decouple \"COI is available\" from \"use threads.\"**\n\nWe no longer load `*‑threaded`\n\njust because `crossOriginIsolated`\n\nis true. It loads **only on an explicit opt-in** — our \"Turbo\" toggle (`v2.compressAccel`\n\n):\n\n``` js\n// ✅ capability != automatic enable\nconst wantsTurbo = settings.compressAccel === true; // user/plan explicit\nif (wantsTurbo && crossOriginIsolated) {\n  loadThreadedPackage();\n}\n// default path stays single-threaded and COEP-safe\n```\n\n**2. Keep the single-threaded path as the default and make it robust.**\n\nThe non-threaded wasm (e.g. ORT 1.17 legacy, which ships a real single-thread build) works fine under COEP. Defaulting to it means COI no longer breaks the common case.\n\n**3. Self-heal on worker crash.**\n\n`pool.ts`\n\nnow catches a dead worker and retries on the safe path, and **aborts Turbo multi-core** rather than bubbling a hard crash:\n\n``` js\nworker.oncrash = () => {\n  retryOnSingleThread();   // f8c86d5: 自愈重试覆盖 JPG/PNG/WEBP\n  disableTurbo();          // fall back, don't hard-fail\n};\n```\n\nCommits `2177a9f`\n\n(AVIF worker abort self-heal + rebuild `pkg-avif`\n\n) and `f8c86d5`\n\n(self-heal retry covering core paths) closed the remaining formats.\n\nrav1e parallelizes via rayon too, but its pool **doesn't read our custom env pool** — it builds its own. Under COI that meant AVIF either ignored our thread budget or hit the same COEP wall. The takeaway: don't assume one rayon pool config applies across codecs. Each WASM crate may own its threading model. `[需你核对：rav1e 当前是走全局池还是注入句柄，以代码为准]`\n\n`crossOriginIsolated`\n\nunlocks speed `if (crossOriginIsolated) enableThreads`\n\ncouples two unrelated decisions. Gate on intent, verify the environment.`crossOriginIsolated`\n\nis false on `localhost`\n\nand most staging setups. If your threaded path only runs when isolated, you will not exercise it until production. Stand up a COEP-serving preview.`cc605f5`\n\n).`COEP: require-corp`\n\n+ `COOP: same-origin`\n\non a real preview, not localhost.`Cross-Origin-Resource-Policy: same-origin`\n\n(or `cross-origin`\n\nif truly cross-origin).This compressor — and the Turbo path described above — runs in ** zipo.pics**. The full internal postmortem lives in our repo; the architectural facts above are from the fix commits\n\n`569731d`\n\n, `73e9377`\n\n, `2177a9f`\n\n, `f8c86d5`\n\n. Happy to compare notes if you've fought the same COI/COEP war.", "url": "https://wpnews.pro/news/how-enabling-cross-origin-isolation-silently-broke-our-multi-threaded-wasm-image", "canonical_source": "https://dev.to/richang/-how-enabling-cross-origin-isolation-silently-broke-our-multi-threaded-wasm-image-compressor-3a0p", "published_at": "2026-09-04 09:39:01+00:00", "updated_at": "2026-09-04 09:53:54.187678+00:00", "lang": "en", "topics": ["developer-tools"], "entities": ["WASM", "WebGPU", "rayon", "COEP", "COI"], "alternates": {"html": "https://wpnews.pro/news/how-enabling-cross-origin-isolation-silently-broke-our-multi-threaded-wasm-image", "markdown": "https://wpnews.pro/news/how-enabling-cross-origin-isolation-silently-broke-our-multi-threaded-wasm-image.md", "text": "https://wpnews.pro/news/how-enabling-cross-origin-isolation-silently-broke-our-multi-threaded-wasm-image.txt", "jsonld": "https://wpnews.pro/news/how-enabling-cross-origin-isolation-silently-broke-our-multi-threaded-wasm-image.jsonld"}}