use brotli

Author: Tsche

README.md

@@ -245,6 +245,14 @@ WebAssembly threads, service workers, and cross-origin isolation require a secur
 
 If assets are hosted on another origin, that origin must allow CORS and send `Cross-Origin-Resource-Policy: cross-origin` or an equivalent policy accepted by the embedding page.
 
+Production builds retain every uncompressed runtime file and also create Brotli
+sidecars for everything under `wasm/` and for other JavaScript files of at least
+128 KiB. Configure the web server to serve `file.br` for a request to `file` when
+the client advertises `Accept-Encoding: br`, with the original content type,
+`Content-Encoding: br`, and `Vary: Accept-Encoding`. Vite preview does this
+automatically. The uncompressed files remain the source of truth and the fallback
+for hosts that do not support precompressed sidecars.
+
 ## Build and test
 
 Installing dependencies downloads the latest verified prebuilt clangd artifacts

public/_headers

@@ -4,3 +4,18 @@
 
 /wasm/*.wasm
   Content-Type: application/wasm
+
+/assets/*.js.br
+  Content-Encoding: br
+  Content-Type: text/javascript
+  Vary: Accept-Encoding
+
+/wasm/*.js.br
+  Content-Encoding: br
+  Content-Type: text/javascript
+  Vary: Accept-Encoding
+
+/wasm/*.wasm.br
+  Content-Encoding: br
+  Content-Type: application/wasm
+  Vary: Accept-Encoding

public/coi-serviceworker.js

@@ -5,14 +5,21 @@ self.addEventListener("activate", (event) => {
 });
 self.addEventListener("fetch", (event) => {
   if (new URL(event.request.url).origin !== self.location.origin) return;
-  if (
-    event.request.cache === "only-if-cached" &&
-    event.request.mode !== "same-origin"
-  )
-    return;
+  // COOP and COEP are document policies. Same-origin subresources already
+  // satisfy COEP, so leaving them alone also avoids reload-time cancellation
+  // noise for stylesheets and modules.
+  if (event.request.mode !== "navigate") return;
   event.respondWith(
     (async () => {
-      const response = await fetch(event.request);
+      let response;
+      try {
+        response = await fetch(event.request);
+      } catch (_) {
+        // A navigation/reload can cancel in-flight subresource requests. Resolve
+        // respondWith instead of turning that ordinary cancellation into an
+        // unhandled service-worker rejection in the browser console.
+        return Response.error();
+      }
       if (response.status === 0) return response;
       const headers = new Headers(response.headers);
       headers.set("Cross-Origin-Embedder-Policy", "require-corp");

scripts/build-package.mjs

@@ -46,3 +46,12 @@ await run(
   ],
   { label: "copy-runtime-assets" },
 );
+
+await run(
+  process.execPath,
+  [
+    path.join(projectRoot, "scripts", "compress-runtime-assets.mjs"),
+    `--outdir=${outdir}`,
+  ],
+  { label: "compress-runtime-assets" },
+);

scripts/clangd/build.sh

@@ -146,7 +146,7 @@ wasi_include="$CLANGD_BUILD_ROOT/wasi-sysroot-$WASI_SDK_VERSION/include"
 cp -R "build/lib/clang/$LLVM_MAJOR/include/." "$wasi_include/"
 
 ## Re-link the production build with the sysroot embedded.
-configure_clangd "-pthread -s ENVIRONMENT=worker -s NO_INVOKE_RUN -s EXIT_RUNTIME -s INITIAL_MEMORY=256MB -s ALLOW_MEMORY_GROWTH -s MAXIMUM_MEMORY=2GB -s STACK_SIZE=256kB -s EXPORTED_RUNTIME_METHODS=FS,callMain -s MODULARIZE -s EXPORT_ES6 -s WASM_BIGINT -s ASSERTIONS -s ASYNCIFY -s PTHREAD_POOL_SIZE='Math.max(navigator.hardwareConcurrency, 8)' --embed-file=$wasi_include@/usr/include"
+configure_clangd "-pthread -s ENVIRONMENT=worker -s NO_INVOKE_RUN -s EXIT_RUNTIME -s INITIAL_MEMORY=256MB -s ALLOW_MEMORY_GROWTH -s MAXIMUM_MEMORY=2GB -s STACK_SIZE=256kB -s EXPORTED_RUNTIME_METHODS=FS,callMain -s MODULARIZE -s EXPORT_ES6 -s WASM_BIGINT -s ASSERTIONS -s ASYNCIFY -s PTHREAD_POOL_SIZE='Math.max(navigator.hardwareConcurrency, 4)' --embed-file=$wasi_include@/usr/include"
 cmake --build build --target clangd
 
 mkdir -p "$clangd_wasm_dir"

scripts/compress-runtime-assets.mjs

@@ -0,0 +1,49 @@
+import { brotliCompress } from "node:zlib";
+import { promisify } from "node:util";
+import { readdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { constants as zlibConstants } from "node:zlib";
+import { parseArguments, projectChild } from "./lib/project.mjs";
+
+const compress = promisify(brotliCompress);
+const minimumJavaScriptSize = 128 * 1024;
+const { options } = parseArguments();
+const outdir = options.get("outdir") ?? "dist";
+const outputDirectory = projectChild(outdir, "output directory");
+
+async function visit(directory) {
+  const entries = await readdir(directory, { withFileTypes: true });
+  await Promise.all(
+    entries.map(async (entry) => {
+      const filename = path.join(directory, entry.name);
+      if (entry.isDirectory()) return visit(filename);
+      if (!entry.isFile() || filename.endsWith(".br")) return;
+
+      const isWasm = filename.endsWith(".wasm");
+      const isJavaScript = filename.endsWith(".js");
+      if (!isWasm && !isJavaScript) return;
+
+      const contents = await readFile(filename);
+      const relativePath = path.relative(outputDirectory, filename);
+      const isWasmRuntime = relativePath.split(path.sep)[0] === "wasm";
+      if (
+        isJavaScript &&
+        !isWasmRuntime &&
+        contents.length < minimumJavaScriptSize
+      )
+        return;
+
+      const compressed = await compress(contents, {
+        params: {
+          [zlibConstants.BROTLI_PARAM_QUALITY]: 11,
+          [zlibConstants.BROTLI_PARAM_MODE]: isWasm
+            ? zlibConstants.BROTLI_MODE_GENERIC
+            : zlibConstants.BROTLI_MODE_TEXT,
+        },
+      });
+      await writeFile(`${filename}.br`, compressed);
+    }),
+  );
+}
+
+await visit(outputDirectory);

src/clangd/worker.ts

@@ -34,14 +34,38 @@ self.addEventListener("message", (event) => {
   else pendingWorkspaceFiles.push(files);
 });
 
-async function download(url: URL): Promise<Uint8Array> {
+function unsignedLeb128(value: number): number[] {
+  const bytes = [];
+  do {
+    let byte = value & 0x7f;
+    value >>>= 7;
+    if (value) byte |= 0x80;
+    bytes.push(byte);
+  } while (value);
+  return bytes;
+}
+
+function emptySourceMapSection(): Uint8Array {
+  const encoder = new TextEncoder();
+  const name = encoder.encode("sourceMappingURL");
+  const url = encoder.encode(
+    'data:application/json,{"version":3,"sources":[],"names":[],"mappings":""}',
+  );
+  const contents = new Uint8Array([
+    ...unsignedLeb128(name.length),
+    ...name,
+    ...unsignedLeb128(url.length),
+    ...url,
+  ]);
+  return new Uint8Array([0, ...unsignedLeb128(contents.length), ...contents]);
+}
+
+async function download(url: URL, suffix?: Uint8Array): Promise<Uint8Array> {
   const response = await fetch(url);
   if (!response.ok || !response.body) {
     throw new Error(`Unable to download clangd.wasm (${response.status})`);
   }
 
-  const headerSize =
-    Number(response.headers.get("content-length")) || undefined;
   const chunks: Uint8Array[] = [];
   let loaded = 0;
   const reader = response.body.getReader();
@@ -51,16 +75,17 @@ async function download(url: URL): Promise<Uint8Array> {
     if (value) {
       chunks.push(value);
       loaded += value.length;
-      self.postMessage({ type: "progress", loaded, total: headerSize });
+      self.postMessage({ type: "progress", loaded });
     }
   }
 
-  const bytes = new Uint8Array(loaded);
+  const bytes = new Uint8Array(loaded + (suffix?.length ?? 0));
   let offset = 0;
   for (const chunk of chunks) {
     bytes.set(chunk, offset);
     offset += chunk.length;
   }
+  if (suffix) bytes.set(suffix, loaded);
   return bytes;
 }
 
@@ -76,7 +101,10 @@ async function start(): Promise<void> {
   const modulePromise = import(/* @vite-ignore */ clangdJsUrl.href) as Promise<{
     default: ClangdFactory;
   }>;
-  const wasmBinary = await download(clangdWasmUrl);
+  // Firefox asks every instantiated Wasm module for a source-map URL. Give it
+  // a valid, empty map instead of letting DevTools try to resolve `null` against
+  // the synthetic URL assigned to an ArrayBuffer-instantiated module.
+  const wasmBinary = await download(clangdWasmUrl, emptySourceMapSection());
   self.postMessage({ type: "starting" });
 
   const { default: Clangd } = await modulePromise;

vite.config.ts

@@ -1,12 +1,66 @@
 import { defineConfig } from "vite";
 import importMetaUrlPlugin from "@codingame/esbuild-import-meta-url-plugin";
+import { existsSync } from "node:fs";
+import path from "node:path";
 
 const crossOriginIsolationHeaders = {
   "Cross-Origin-Embedder-Policy": "require-corp",
   "Cross-Origin-Opener-Policy": "same-origin",
 };
 
+const contentTypes = new Map([
+  [".js", "text/javascript"],
+  [".wasm", "application/wasm"],
+]);
+
+function precompressedPreview() {
+  return {
+    name: "precompressed-preview",
+    configurePreviewServer(server) {
+      server.middlewares.use((request, response, next) => {
+        if (
+          !request.url ||
+          !/\bbr\b/.test(request.headers["accept-encoding"] ?? "")
+        ) {
+          return next();
+        }
+
+        const pathname = decodeURIComponent(
+          new URL(request.url, "http://localhost").pathname,
+        );
+        const extension = path.extname(pathname);
+        const contentType = contentTypes.get(extension);
+        if (!contentType) return next();
+
+        const relativePath = pathname.replace(/^\/+/, "");
+        const candidate = path.resolve(
+          server.config.root,
+          server.config.build.outDir,
+          `${relativePath}.br`,
+        );
+        const outputRoot = path.resolve(
+          server.config.root,
+          server.config.build.outDir,
+        );
+        if (
+          !candidate.startsWith(`${outputRoot}${path.sep}`) ||
+          !existsSync(candidate)
+        ) {
+          return next();
+        }
+
+        request.url = `${pathname}.br`;
+        response.setHeader("Content-Encoding", "br");
+        response.setHeader("Content-Type", contentType);
+        response.setHeader("Vary", "Accept-Encoding");
+        next();
+      });
+    },
+  };
+}
+
 export default defineConfig({
+  plugins: [precompressedPreview()],
   base: "./",
   define: {
     __CLANGD_WASM_BASE__: JSON.stringify(process.env.CLANGD_WASM_BASE ?? ""),