feat: put each JDK module but java.base in its own image file (#75)

Author: Project516

AGENTS.md

@@ -32,7 +32,7 @@ Node, which is how the tests run.
   IndexedDB and one VM per about:blank iframe. Keep these working.
 - The release form is an npm package of the built files only
   (`java-web.js`, `java-web-worker.js`, `node.js` (the Node entry), `cli.js` (the
-  `java-web` command), `boot.pack`, `jdk/image.jar`,
+  `java-web` command), `boot.pack`, the `jdk/*.jar` image files,
   `jdk/javac.pack`, and OpenJDK's notices in `jdk/legal/`), versioned, with
   nothing built at install. A GitHub Actions workflow triggered by a release
   publishes it to npm; never publish by hand.

README.md

@@ -10,10 +10,9 @@ and its page API matches CheerpJ's, so existing pages can switch.
 pnpm add @project516/java-web
 ```
 
-Serve `node_modules/@project516/java-web/dist/` as static files (on GitHub
-Pages, deploy from Actions: a `gh-pages` branch cannot hold the 120 MB
-`jdk/image.jar`; on a project site, `/app/` is `user.github.io`, so files are
-under `/app/<repo>/`), then:
+Serve `node_modules/@project516/java-web/dist/` as static files (on a GitHub
+Pages project site, `/app/` is the site root `user.github.io`, so the page's
+files are under `/app/<repo>/`), then:
 
 ```html
 <script src="java-web.js"></script>

docs/browser.md

@@ -5,15 +5,19 @@ The npm package holds the built files: `java-web.js`, `java-web-worker.js`,
 and load `java-web.js` with a classic `<script>` tag. It finds the other files
 next to itself, or where `cheerpjInit({ runtime: "/path/to/dist/" })` says.
 
-- The server should answer range requests for `jdk/image.jar`, the whole JDK
-  image, so a page reads only the classes it needs. `boot.pack` holds what a
-  typical start reads, and `jdk/javac.pack` what javac adds. A host that
-  compresses ranged responses still works, at the cost of one full download of
-  `jdk/image.jar` (about 120 MB).
-- `jdk/image.jar` is over GitHub's 100 MB limit for a file in a git
-  repository, so a site published by pushing a `gh-pages` branch cannot hold
-  it. GitHub Pages deployed from Actions (`actions/upload-pages-artifact`)
-  serves it, Range requests included.
+- The server should answer range requests for the `jdk/*.jar` files, the JDK
+  image, so a page reads only the classes it needs. `jdk/image.jar` holds
+  `java.base` and the files around the classes, each other module is in
+  `jdk/<module>.jar`, and `jdk/ct.sym.jar` holds what `javac --release` reads.
+  `boot.pack` holds what a typical start reads, and `jdk/javac.pack` what javac
+  adds. A host that compresses ranged responses still works, at the cost of one
+  full download of each image file a page reads.
+- A host can leave out the `jdk/<module>.jar` of a module its pages never
+  load, and `jdk/ct.sym.jar` when nothing compiles with `--release`. A class of
+  a left-out module does not load (`NoClassDefFoundError`), and the console
+  names the missing file. Without `localeData` nothing reads
+  `jdk/jdk.localedata.jar` (26 MB); javac reads `jdk.compiler`,
+  `java.compiler` and `jdk.zipfs`.
 - The JIT compiles hot Java methods with `new Function`, so a page with a
   Content Security Policy needs `'unsafe-eval'` in `script-src`. Without it,
   Java still runs, only interpreted.

docs/development.md

@@ -8,7 +8,8 @@ included, builds the same image, with the Linux class library whose natives
 java-web implements. The host JDK is the HotSpot reference the tests run, linked
 at `build/hotspot`. The build links the selected modules into `build/jdk/lib/modules`;
 `lib/packages.txt` indexes packages for the boot class loader. `pnpm build`
-puts it, with the files around it, in `dist/jdk/image.jar`, read by byte range.
+puts it, with the files around it, in `dist/jdk/image.jar` and, for each module
+but `java.base`, `dist/jdk/<module>.jar`, all read by byte range.
 It packs the byte ranges a typical start reads into `boot.pack`, and those javac
 adds into `jdk/javac.pack`. Without `localeData`, the VM leaves `jdk.localedata`
 out with `jdk.module.limitmods`, as `--limit-modules` does.

scripts/build-web.ts

@@ -173,14 +173,56 @@ const rangeEntries = (ranges: Map<string, [number, number][]>, src: Recorder) =>
   [...ranges].flatMap(([p, spans]) => spans.map(([s, e]): [string, Uint8Array] => [`@${s}:${p}`, src.readRange(p, s, e - s)!]));
 const inJavacPack = new Set(javacFiles);
 
-// Every java.home file goes in one file, jdk/image.jar, read in ranges:
-// lib/modules (the jimage with every class) and the conf/ and lib/ files
-// around it. The index says where each file is, so the worker can stat and
-// list offline.
+// A jimage's resources as runs of one module's, [module, start, end) in image
+// order. Empty resources and module-info.class are left out: jlink puts the
+// latter with the index, and javac reads them all.
+function moduleRuns(image: Uint8Array): [string, number, number][] {
+  const v = new DataView(image.buffer, image.byteOffset, image.byteLength);
+  const count = v.getUint32(16, true);
+  const locations = 28 + count * 8, strings = locations + v.getUint32(20, true);
+  const resources = strings + v.getUint32(24, true);
+  const str = (off: number) => {
+    let s = "";
+    for (let i = strings + off; image[i]; i++) s += String.fromCharCode(image[i]);
+    return s;
+  };
+  const found: [string, number, number][] = [];
+  for (let i = 0; i < count; i++) {
+    let p = locations + v.getUint32(28 + count * 4 + i * 4, true);
+    const attrs = Array<number>(8).fill(0);
+    while (image[p] > 7) {
+      const b = image[p++];
+      let value = 0;
+      for (let n = (b & 7) + 1; n > 0; n--) value = value * 256 + image[p++];
+      attrs[b >> 3] = value;
+    }
+    const size = attrs[6] || attrs[7];
+    if (size && !(!attrs[2] && str(attrs[3]) === "module-info")) found.push([str(attrs[1]), resources + attrs[5], resources + attrs[5] + size]);
+  }
+  const runs: [string, number, number][] = [];
+  for (const [module, start, end] of found.sort((a, b) => a[1] - b[1])) {
+    const last = runs[runs.length - 1];
+    if (last?.[0] === module) last[2] = Math.max(last[2], end);
+    else runs.push([module, start, end]);
+  }
+  return runs;
+}
+
+// The java.home files go in jdk/image.jar, read in ranges, with the index
+// saying where each is, so the worker can stat and list offline. Parts a page
+// may never read go in their own files, which a host can leave out: each
+// module of lib/modules but java.base in jdk/<module>.jar, and lib/ct.sym
+// (javac --release) in jdk/ct.sym.jar.
+const linked = new Set(/^MODULES="(.*)"$/m.exec(readFileSync(join(jdk, "release"), "utf8"))![1].split(" "));
+const imageSizes = new Map<string, number>();
+// appends data to jdk/<name>.jar, returning where it starts there
+const put = (name: string, data: Uint8Array) => {
+  const at = imageSizes.get(name) ?? 0;
+  (at ? appendFileSync : writeFileSync)(join(dist, "jdk", `${name}.jar`), data);
+  imageSizes.set(name, at + data.length);
+  return at;
+};
 const lines: string[] = [];
-const imageFile = join(dist, "jdk", "image.jar");
-writeFileSync(imageFile, "");
-let imageSize = 0;
 const walk = (dir: string) => {
   for (const name of readdirSync(dir).sort()) {
     const p = join(dir, name);
@@ -190,10 +232,25 @@ const walk = (dir: string) => {
     if (st.isDirectory()) {
       lines.push(`d ${rel}`);
       walk(p);
+    } else if (rel === "/lib/modules") {
+      const data = readFileSync(p);
+      const parts: [number, string][] = [];
+      let pos = 0;
+      for (const [module, start, end] of moduleRuns(data)) {
+        if (module === "java.base" || !linked.has(module)) continue;
+        if (parts.some(([, m]) => m === module)) throw new Error(`lib/modules has ${module} in more than one place`);
+        if (start > pos) parts.push([pos, "image"]);
+        parts.push([start, module]);
+        pos = end;
+      }
+      if (pos < data.length) parts.push([pos, "image"]);
+      parts.forEach(([start, image], i) => {
+        const at = put(image, data.subarray(start, i + 1 < parts.length ? parts[i + 1][0] : data.length));
+        lines.push(start ? `p ${rel} ${start} ${image}:${at}` : `f ${rel} ${st.size} ${image}:${at}`);
+      });
     } else {
-      lines.push(`f ${rel} ${st.size} image:${imageSize}${inJavacPack.has(rel) ? " javac" : ""}`);
-      appendFileSync(imageFile, readFileSync(p));
-      imageSize += st.size;
+      const image = rel === "/lib/ct.sym" ? "ct.sym" : "image";
+      lines.push(`f ${rel} ${st.size} ${image}:${put(image, readFileSync(p))}${inJavacPack.has(rel) ? " javac" : ""}`);
     }
   }
 };
@@ -249,4 +306,6 @@ const javacPack = writePack(join(dist, "jdk", "javac.pack"), [
   ...javacFiles.map((p): [string, Uint8Array] => [p, javacRecorder.read(p)!]),
   ...rangeEntries(javacRanges, javacRecorder),
 ]);
-console.log(`dist/ ready: boot.pack ${boot}, jdk/javac.pack ${javacPack}, jdk/image.jar ${(imageSize / 2 ** 20).toFixed(0)} MB`);
+const mb = (n: number) => `${(n / 2 ** 20).toFixed(0)} MB`;
+const others = [...imageSizes].filter(([n]) => n !== "image").reduce((n, [, size]) => n + size, 0);
+console.log(`dist/ ready: boot.pack ${boot}, jdk/javac.pack ${javacPack}, jdk/image.jar ${mb(imageSizes.get("image")!)}, ${imageSizes.size - 1} more images ${mb(others)}`);

src/browser/http.ts

@@ -12,6 +12,9 @@ export interface Pack {
   lazy: Map<string, string>;
   // path -> the image file holding it and its offset there
   offsets: Map<string, { image: string; at: number }>;
+  // path -> where the bytes from each start on are, for a file split across
+  // image files, sorted by start; offsets has the first part
+  parts: Map<string, { start: number; image: string; at: number }[]>;
   // path -> parts of a file read in ranges (the JDK image), as [offset, bytes]
   // sorted by offset
   ranges: Map<string, [number, Uint8Array][]>;
@@ -25,8 +28,10 @@ const utf8 = new TextDecoder();
 // Pack layout: repeated [u16 path length][path][u32 size][bytes]. In the boot
 // pack, "/index.prefix" holds prefix-coded "d path" and "f path size
 // [image:offset] [pack]" lines. A file with an offset is read in ranges from
-// <image>.jar; a named pack is <name>.pack next to it and is
-// fetched whole the first time one of its files is read. An entry named
+// <image>.jar, and a "p path start image:offset" line after it says the
+// file's bytes from start on are in another image. A named pack is
+// <name>.pack next to it and is fetched whole the first time one of its files
+// is read. An entry named
 // "@<offset>:<path>" holds part of a file read in ranges, and one named
 // "@lazy:<pack>:<path>" lists, as u32 start and end pairs, the parts of it
 // that pack holds. Images are .jar
@@ -44,7 +49,7 @@ export function parsePack(buf: ArrayBuffer): Pack {
     files.set(path, u8.subarray(p + 4, p + 4 + size));
     p += 4 + size;
   }
-  const pack: Pack = { files, index: null, lazy: new Map(), offsets: new Map(), ranges: new Map(), lazyRanges: new Map() };
+  const pack: Pack = { files, index: null, lazy: new Map(), offsets: new Map(), parts: new Map(), ranges: new Map(), lazyRanges: new Map() };
   for (const [p, data] of files) {
     if (p[0] !== "@") continue;
     files.delete(p);
@@ -169,10 +174,34 @@ export function addIndex(pack: Pack, text: string, prefix = false) {
         b = c;
       }
       pack.lazy.set(path, line.slice(b + 1));
+    } else if (line[0] === "p") {
+      const b = line.indexOf(" ", a + 1), colon = line.lastIndexOf(":");
+      const name = line.slice(b + 1, colon);
+      let image = images.get(name);
+      if (image === undefined) images.set(name, (image = `/${name}.jar`));
+      let parts = pack.parts.get(path);
+      if (!parts) pack.parts.set(path, (parts = []));
+      parts.push({ start: +line.slice(a + 1, b), image, at: +line.slice(colon + 1) });
     }
   }
 }
 
+// Where byte off of a file read in ranges is: the image file, the offset
+// there, and how many bytes from off on that part of the file holds.
+export function imagePart(pack: Pack, path: string, off: number): { image: string; at: number; len: number } | undefined {
+  const first = pack.offsets.get(path);
+  if (!first) return undefined;
+  let { image, at } = first, start = 0, end = pack.index!.get(path)!;
+  for (const p of pack.parts.get(path) ?? []) {
+    if (p.start > off) {
+      end = p.start;
+      break;
+    }
+    ({ image, at, start } = p);
+  }
+  return { image, at: at + off - start, len: end - off };
+}
+
 const BLOCK = 64 << 10;
 
 function encodePath(path: string): string {
@@ -204,8 +233,10 @@ export class HttpBackend implements Backend {
   private fetchedPacks = new Set<string>();
   // 64 KB blocks of files read in parts, by path
   private blocks = new Map<string, Map<number, Uint8Array>>();
+  // files read in ranges that the server does not have
+  private missing = new Set<string>();
 
-  constructor(base: string, pack: Pack = { files: new Map(), index: null, lazy: new Map(), offsets: new Map(), ranges: new Map(), lazyRanges: new Map() }) {
+  constructor(base: string, pack: Pack = { files: new Map(), index: null, lazy: new Map(), offsets: new Map(), parts: new Map(), ranges: new Map(), lazyRanges: new Map() }) {
     this.base = base.endsWith("/") ? base.slice(0, -1) : base;
     this.pack = pack;
   }
@@ -290,8 +321,18 @@ export class HttpBackend implements Backend {
       return this.readRange(path, off, len);
     }
     // has() parses the path's module first; image files themselves are not indexed
-    const at = this.pack.index?.has(path) ? this.pack.offsets.get(path) : undefined;
-    if (at !== undefined) return this.readRange(at.image, at.at + off, len);
+    const at = this.pack.index?.has(path) ? imagePart(this.pack, path, off) : undefined;
+    if (at !== undefined) {
+      if (len <= at.len || at.len <= 0) return this.readRange(at.image, at.at, len);
+      const head = this.readRange(at.image, at.at, at.len);
+      const rest = head && this.readRange(path, off + at.len, len - at.len);
+      if (!head || !rest) return null;
+      const out = new Uint8Array(len);
+      out.set(head);
+      out.set(rest, head.length);
+      return out;
+    }
+    if (this.missing.has(path)) return null;
     let blocks = this.blocks.get(path);
     if (!blocks) this.blocks.set(path, (blocks = new Map()));
     const first = Math.floor(off / BLOCK), last = Math.floor((off + len - 1) / BLOCK);
@@ -315,6 +356,10 @@ export class HttpBackend implements Backend {
         this.blocks.delete(path);
         return data.subarray(off, off + len);
       }
+      if (xhr.status === 404) {
+        this.missing.add(path);
+        console.warn(`java-web: ${this.base}${path} is missing, so the classes in it do not load`);
+      }
       if (xhr.status !== 206) return null;
       if (!rangeOk(xhr, b * BLOCK, data.length)) return this.readWhole(path, off, len);
       for (let i = b; i <= end; i++) blocks.set(i, data.subarray((i - b) * BLOCK, (i - b + 1) * BLOCK));
@@ -332,11 +377,13 @@ export class HttpBackend implements Backend {
   }
 
   // When ranges of a file come back wrong, reads all of it once: a whole
-  // response decodes correctly even from a host that compresses it.
+  // response decodes correctly even from a host that compresses it. A range
+  // that fails to decode throws as a network error does, so a failed read
+  // here is taken as the network's, and later reads try again.
   private readWhole(path: string, off: number, len: number): Uint8Array | null {
-    console.warn(`java-web: range reads of ${this.base}${path} came back compressed or wrong, so it is read whole. Serve it without compression (as .jar files are on GitHub Pages).`);
     const xhr = this.request("GET", path);
     if (!xhr) return null;
+    console.warn(`java-web: range reads of ${this.base}${path} came back compressed or wrong, so it is read whole. Serve it without compression (as .jar files are on GitHub Pages).`);
     const data = new Uint8Array(xhr.response as ArrayBuffer);
     this.cache.set(path, data);
     this.blocks.delete(path);

src/image.ts

@@ -1,10 +1,10 @@
 // The JDK image as `pnpm build` packages it in dist/, read from disk under
 // Node: boot.pack holds the index and the files and image ranges a typical
-// start reads, and the rest is read at its offset in jdk/image.jar.
+// start reads, and the rest is read at its offset in the jdk/*.jar images.
 
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { listIndex, packedRange, parsePack } from "./browser/http.ts";
+import { imagePart, listIndex, packedRange, parsePack } from "./browser/http.ts";
 import type { Pack } from "./browser/http.ts";
 import type { Backend, Stat } from "./fs.ts";
 
@@ -20,6 +20,9 @@ export function imageFd(file: string): number {
   return fd;
 }
 
+// image files a read failed in, warned about once
+const unreadable = new Set<string>();
+
 export class ImageBackend implements Backend {
   readonly writable = false;
   // this VM's descriptor of each image file
@@ -55,23 +58,28 @@ export class ImageBackend implements Backend {
     if (packed) return packed.subarray(off, off + len);
     const part = packedRange(this.pack, p, off, len);
     if (part) return part;
-    const at = this.pack.offsets.get(p);
-    if (!at) return null;
+    if (!this.pack.offsets.has(p)) return null;
     const out = new Uint8Array(len);
-    let n = 0;
+    let n = 0, image = "";
     try {
-      let fd = this.fds.get(at.image);
-      if (fd === undefined) this.fds.set(at.image, (fd = imageFd(path.join(this.dir, "jdk", at.image))));
       while (n < len) {
-        const got = fs.readSync(fd, out, n, len - n, at.at + off + n);
+        const at = imagePart(this.pack, p, off + n)!;
+        image = at.image;
+        let fd = this.fds.get(image);
+        if (fd === undefined) this.fds.set(image, (fd = imageFd(path.join(this.dir, "jdk", image))));
+        const got = fs.readSync(fd, out, n, Math.min(len - n, at.len), at.at);
         if (got === 0) break;
         n += got;
       }
-    } catch {
-      return null;
+    } catch {}
+    if (n === len) return out;
+    // a missing, short or unreadable image reads as missing rather than cut off
+    const file = path.join(this.dir, "jdk", image);
+    if (!unreadable.has(file)) {
+      unreadable.add(file);
+      console.warn(`java-web: cannot read ${file}, so the classes in it do not load`);
     }
-    // a short or unreadable image is damaged; the file reads as missing rather than cut off
-    return n === len ? out : null;
+    return null;
   }
 
   list(p: string): string[] | null {

src/jimage.ts

@@ -63,7 +63,9 @@ export class JImage {
     if (actual !== full) return null;
     if (attrs[6]) throw new Error("compressed jimage resource");
     const data = this.fs.readRange(this.path, this.index.length + attrs[5], attrs[7]);
-    if (!data || data.length !== attrs[7]) throw new Error(`cannot read image resource: ${full}`);
+    // a host may leave out the image file of a module its pages never load
+    if (!data) return null;
+    if (data.length !== attrs[7]) throw new Error(`cannot read image resource: ${full}`);
     return data;
   }
 }