# How enabling cross-origin isolation silently broke our multi-threaded WASM image compressor

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.

The setup

We 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.

For the multi-threaded code paths we rely on shared memory + atomics, which in the browser requires crossOriginIsolated. So we served the document with:

Cross-Origin-Embedder-Policy: require-corp
Cross-Origin-Opener-Policy: same-origin

That gives us crossOriginIsolated === true, unlocks SharedArrayBuffer, and lets the *‑threaded WASM builds actually spawn workers.

The build uses a nightly toolchain (nightly-2025-06-01 + -Z build-std) with:

RUSTFLAGS="--cfg=... +atomics,+bulk-memory --shared-memory --import-memory"

and a custom rayon handle pool (with_turbo_pool) instead of build_global, so we control worker lifecycle and can abort/self-heal.

The incident

After flipping COEP to require-corp in production, every format started crashing with the same message:

compression worker crashed

Not one codec — JPG, PNG, WebP, AVIF, all of them. It was a P0: the core feature was dead for every user.

What 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.

Root cause

The *‑threaded WASM packages spin up nested rayon workers to parallelize the codec. Under COI + COEP require-corp, those nested workers get blocked by Cross-Origin-Resource-Policy / 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.

The trap: we had gated the ‑threaded build on crossOriginIsolated:

// ❌ the bug: environment detection == feature enable
if (crossOriginIsolated) {
  loadThreadedPackage();   // boots nested rayon workers → blocked by COEP
}

So 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.

(This matches the fix commits 569731d "默认压缩路径禁用 *-threaded 线程包" and 73e9377 "COI 下 module worker 被 COEP 拦死".)

The fix

Three changes, all in the loader — not the codec:

1. Decouple "COI is available" from "use threads."

We no longer load *‑threaded just because crossOriginIsolated is true. It loads only on an explicit opt-in — our "Turbo" toggle (v2.compressAccel):

// ✅ capability != automatic enable
const wantsTurbo = settings.compressAccel === true; // user/plan explicit
if (wantsTurbo && crossOriginIsolated) {
  loadThreadedPackage();
}
// default path stays single-threaded and COEP-safe

2. Keep the single-threaded path as the default and make it robust.

The 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.

3. Self-heal on worker crash.

pool.ts now catches a dead worker and retries on the safe path, and aborts Turbo multi-core rather than bubbling a hard crash:

worker.oncrash = () => {
  retryOnSingleThread();   // f8c86d5: 自愈重试覆盖 JPG/PNG/WEBP
  disableTurbo();          // fall back, don't hard-fail
};

Commits 2177a9f (AVIF worker abort self-heal + rebuild pkg-avif) and f8c86d5 (self-heal retry covering core paths) closed the remaining formats.

A second, subtler trap: AVIF / rav1e

rav1e 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 当前是走全局池还是注入句柄，以代码为准]

Lessons (the part worth stealing)

1. COI is a double-edged sword. crossOriginIsolated unlocks speed and tightens loading policy. Anything that spawns workers/sub-resources must satisfy COEP + CORP or it silently dies.
2. Never let environment detection auto-enable a feature. if (crossOriginIsolated) enableThreads couples two unrelated decisions. Gate on intent, verify the environment.
3. Test under real COI. crossOriginIsolated is false on localhost and most staging setups. If your threaded path only runs when isolated, you will not exercise it until production. Stand up a COEP-serving preview.
4. Self-heal, don't hard-crash. A worker that can die should degrade to the safe path, not take the whole feature down.
5. Capability probe, not assumption. We now probe for the threaded package and fall back if it fails to boot, instead of assuming presence (cc605f5).

Repro checklist for your own WASM app

• [ ] Serve COEP: require-corp + COOP: same-origin on a real preview, not localhost.
• [ ] Confirm every worker script response also carries Cross-Origin-Resource-Policy: same-origin (or cross-origin if truly cross-origin).
• [ ] Separate "is COI available" from "should I use threads."
• [ ] Add a crash→single-thread fallback in the worker pool.
• [ ] Log which package actually booted, so a COEP block is visible, not silent.

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 569731d, 73e9377, 2177a9f, f8c86d5. Happy to compare notes if you've fought the same COI/COEP war.