wgsl-analyzer-web 0.12.0-next.0

package/src/host.ts

@@ -0,0 +1,82 @@
+/**
+ * Hosts the emscripten module: boots it, seeds the workspace, and carries the
+ * message stream.
+ */
+
+import type { ModuleFactory } from "./emscripten.js";
+import { seedWorkspace, writeFile } from "./fs.js";
+import type { WorkspaceFiles } from "./protocol.js";
+
+export interface HostOptions {
+	/** Absolute path of the workspace inside the in-memory filesystem. */
+	readonly root: string;
+	/** Files to seed, keyed by path relative to {@link HostOptions.root}. */
+	readonly files: WorkspaceFiles;
+	/** argv for `main()`. Empty selects the default `lsp-server` subcommand. */
+	readonly args: readonly string[];
+	/** Receives each parsed JSON-RPC message from the server. */
+	readonly onMessage: (message: unknown) => void;
+	/** Receives the server's stderr, line by line. */
+	readonly onStderr: (line: string) => void;
+	/** Called if `main()` returns. */
+	readonly onExit: (code: number) => void;
+}
+
+/** A running server. Once it has exited, every method does nothing. */
+export interface Host {
+	/** Sends one JSON-RPC message to the server. */
+	send(message: unknown): void;
+	/** Creates or replaces a workspace file, given its path relative to the root. */
+	writeFile(relativePath: string, contents: string | Uint8Array): void;
+	/** Removes a workspace file, if present. */
+	deleteFile(relativePath: string): void;
+}
+
+/** Boots the server and resolves once `main()` has been started. */
+export async function startHost(factory: ModuleFactory, options: HostOptions): Promise<Host> {
+	const { root } = options;
+	const resolve = (relativePath: string): string => `${root}/${relativePath.replace(/^\/+/, "")}`;
+
+	// Messages for the server, which pulls them one at a time. It never closes.
+	const inbox = new TransformStream<string, string>();
+	const reader = inbox.readable.getReader();
+	const writer = inbox.writable.getWriter();
+
+	// With `-sEXIT_RUNTIME`, calling into the module after `main()` returns is an
+	// error, and the page can still send messages after that.
+	let exited = false;
+	const module = await factory({
+		noInitialRun: true,
+		printErr: options.onStderr,
+		onExit: (code) => {
+			exited = true;
+			// Messages are delivered from microtasks too, so those sent before exiting come first.
+			queueMicrotask(() => options.onExit(code));
+		},
+		lspNextMessage: () => reader.read().then(({ value }) => value as string),
+		lspOnMessage: (body) => options.onMessage(JSON.parse(body)),
+	});
+
+	// Needs to run after WasmFS was iniialized.
+	seedWorkspace(module.FS, root, options.files);
+	module.FS.chdir(root);
+	// WasmFS's `chdir` does not go through `FS.handleError`, so a failure is
+	// otherwise silent.
+	if (module.FS.cwd() !== root) throw new Error(`cannot change directory to ${root}`);
+
+	// Returns immediately: -sPROXY_TO_PTHREAD runs main() on a pthread.
+	module.callMain(options.args);
+
+	return {
+		send: (message) => {
+			if (!exited) void writer.write(JSON.stringify(message));
+		},
+		writeFile: (relativePath, contents) => {
+			if (!exited) writeFile(module.FS, resolve(relativePath), contents);
+		},
+		deleteFile: (relativePath) => {
+			const path = resolve(relativePath);
+			if (!exited && module.FS.analyzePath(path).exists) module.FS.unlink(path);
+		},
+	};
+}

package/src/index.ts

@@ -0,0 +1,166 @@
+/**
+ * wgsl-analyzer as a language server in a Web Worker.
+ *
+ * The server is the `wgsl-analyzer` binary compiled to
+ * `wasm32-unknown-emscripten`, running its ordinary `main_loop` over a transport.
+ * This module hosts it and exposes the message stream.
+ *
+ * The page must be cross-origin isolated. The build uses shared memory, so
+ * without `Cross-Origin-Opener-Policy: same-origin` and
+ * `Cross-Origin-Embedder-Policy: require-corp` nothing will start.
+ */
+
+import type { HostMessage, WorkerMessage, WorkspaceFiles } from "./protocol.js";
+
+export type { WorkspaceFiles } from "./protocol.js";
+
+export interface StartOptions {
+	/**
+	 * Directory serving `worker.js`, `wgsl_analyzer.js` and `wgsl_analyzer.wasm`.
+	 * They must sit side by side. Defaults to `"/wgsl-analyzer/"`.
+	 */
+	readonly baseUrl?: string | URL;
+	/** Absolute path of the workspace in the in-memory filesystem. Defaults to `"/workspace"`. */
+	readonly root?: string;
+	/** Files to seed, keyed by path relative to {@link StartOptions.root}. */
+	readonly files: WorkspaceFiles;
+	/** argv for `main()`. Empty selects the default `lsp-server` subcommand. */
+	readonly args?: readonly string[];
+	/** Receives the server's stderr, line by line. */
+	readonly onStderr?: (line: string) => void;
+	/** Called if `main()` returns. */
+	readonly onExit?: (code: number) => void;
+}
+
+export interface Disposable {
+	dispose(): void;
+}
+
+/** A running wgsl-analyzer language server. */
+export class WgslAnalyzerServer {
+	readonly #worker: Worker;
+	readonly #listeners = new Set<(message: unknown) => void>();
+	readonly #root: string;
+	#disposed = false;
+
+	private constructor(worker: Worker, root: string) {
+		this.#worker = worker;
+		this.#root = root;
+	}
+
+	/** The workspace root as a URI, suitable for `initialize`. */
+	get rootUri(): string {
+		return `file://${this.#root}`;
+	}
+
+	/** Builds the URI of a workspace file, given its path relative to the root. */
+	uriOf(relativePath: string): string {
+		return `file://${this.#root}/${relativePath.replace(/^\/+/, "")}`;
+	}
+
+	/** Boots the server and resolves once it is ready to accept messages. */
+	static async start(options: StartOptions): Promise<WgslAnalyzerServer> {
+		const base = new URL(String(options.baseUrl ?? "/wgsl-analyzer/"), globalThis.location.href);
+		const root = options.root ?? "/workspace";
+
+		const worker = new Worker(new URL("worker.js", base), { type: "module" });
+		const server = new WgslAnalyzerServer(worker, root);
+
+		await new Promise<void>((resolve, reject) => {
+			const onFirstMessage = (event: MessageEvent<WorkerMessage>): void => {
+				const message = event.data;
+				if (message.type === "ready") {
+					worker.removeEventListener("message", onFirstMessage);
+					resolve();
+				} else if (message.type === "error") {
+					worker.removeEventListener("message", onFirstMessage);
+					reject(new Error(`${message.message}\n${message.stack ?? ""}`));
+				}
+			};
+			worker.addEventListener("message", onFirstMessage);
+			worker.addEventListener(
+				"error",
+				(event) => reject(new Error(`worker failed to load: ${event.message}`)),
+				{ once: true },
+			);
+
+			const boot: HostMessage = {
+				type: "boot",
+				root,
+				files: options.files,
+				args: options.args ?? [],
+			};
+			worker.postMessage(boot);
+		});
+
+		worker.addEventListener("message", (event: MessageEvent<WorkerMessage>) => {
+			const message = event.data;
+			switch (message.type) {
+				case "lsp":
+					for (const listener of server.#listeners) listener(message.message);
+					break;
+				case "stderr":
+					options.onStderr?.(message.line);
+					break;
+				case "exit":
+					options.onExit?.(message.code);
+					break;
+				case "error":
+					options.onStderr?.(`[worker] ${message.message}`);
+					break;
+				default:
+					break;
+			}
+		});
+
+		return server;
+	}
+
+	/** Sends one JSON-RPC message to the server. */
+	sendMessage(message: unknown): void {
+		if (this.#disposed) throw new Error("server has been disposed");
+		const envelope: HostMessage = { type: "lsp", message };
+		this.#worker.postMessage(envelope);
+	}
+
+	/** Subscribes to messages coming back from the server. */
+	onMessage(listener: (message: unknown) => void): Disposable {
+		this.#listeners.add(listener);
+		return {
+			dispose: () => {
+				this.#listeners.delete(listener);
+			},
+		};
+	}
+
+	/**
+	 * Creates or replaces a file in the in-memory filesystem.
+	 *
+	 * The server does not watch the filesystem, so follow this with a
+	 * `workspace/didChangeWatchedFiles` notification for the file. Edits to an
+	 * open document go through `textDocument/didChange` instead.
+	 */
+	writeFile(relativePath: string, contents: string | Uint8Array): void {
+		const message: HostMessage = { type: "writeFile", path: relativePath, contents };
+		this.#worker.postMessage(message);
+	}
+
+	/** Removes a file from the in-memory filesystem. See {@link WgslAnalyzerServer.writeFile}. */
+	deleteFile(relativePath: string): void {
+		const message: HostMessage = { type: "deleteFile", path: relativePath };
+		this.#worker.postMessage(message);
+	}
+
+	/** Stops the server and tears down the worker. */
+	dispose(): void {
+		if (this.#disposed) return;
+		this.#disposed = true;
+		this.#listeners.clear();
+
+		// `exit` ends the server's main loop, if the server reads it before the
+		// worker is terminated on the next macrotask.
+		const exit: HostMessage = { type: "lsp", message: { jsonrpc: "2.0", method: "exit" } };
+		this.#worker.postMessage(exit);
+		setTimeout(() => this.#worker.terminate(), 0);
+	}
+}

package/src/protocol.ts

@@ -0,0 +1,27 @@
+/**
+ * Control messages exchanged between the page and the worker hosting the
+ * emscripten module.
+ */
+
+/** Contents of a workspace, keyed by path relative to its root in the in-memory filesystem. */
+export type WorkspaceFiles = Record<string, string | Uint8Array>;
+
+/** Page to worker. */
+export type HostMessage =
+	| {
+			readonly type: "boot";
+			readonly root: string;
+			readonly files: WorkspaceFiles;
+			readonly args: readonly string[];
+	  }
+	| { readonly type: "lsp"; readonly message: unknown }
+	| { readonly type: "writeFile"; readonly path: string; readonly contents: string | Uint8Array }
+	| { readonly type: "deleteFile"; readonly path: string };
+
+/** Worker to page. */
+export type WorkerMessage =
+	| { readonly type: "ready" }
+	| { readonly type: "lsp"; readonly message: unknown }
+	| { readonly type: "stderr"; readonly line: string }
+	| { readonly type: "exit"; readonly code: number }
+	| { readonly type: "error"; readonly message: string; readonly stack?: string | undefined };

package/src/wgsl_analyzer.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Stands in for the emscripten glue.
+ *
+ * The real `wgsl_analyzer.js` is produced by `cargo xtask dist-web` and only
+ * exists in `dist/`, next to the bundled worker that imports it at runtime. This
+ * declaration lets the worker typecheck without it being present in `src/`.
+ */
+
+import type { ModuleFactory } from "./emscripten.js";
+
+declare const createWgslAnalyzer: ModuleFactory;
+export default createWgslAnalyzer;

package/src/worker.ts

@@ -0,0 +1,60 @@
+/**
+ * Worker entry point: relays between the page and the {@link Host}.
+ *
+ * This file is bundled to `dist/worker.js` and must be served next to
+ * `wgsl_analyzer.js`. The dynamic import below resolves relative to it, and the
+ * glue spawns its pthread pool with
+ * `new Worker(new URL("wgsl_analyzer.js", import.meta.url))`.
+ */
+
+import { type Host, startHost } from "./host.js";
+import type { HostMessage, WorkerMessage } from "./protocol.js";
+
+const post = (message: WorkerMessage): void => {
+	self.postMessage(message);
+};
+
+let host: Host | null = null;
+
+self.onmessage = (event: MessageEvent<HostMessage>): void => {
+	const message = event.data;
+	switch (message.type) {
+		case "boot":
+			boot(message).catch((error: unknown) => {
+				post({
+					type: "error",
+					message: String(error),
+					stack: error instanceof Error ? error.stack : undefined,
+				});
+			});
+			break;
+		case "lsp":
+			host?.send(message.message);
+			break;
+		case "writeFile":
+			host?.writeFile(message.path, message.contents);
+			break;
+		case "deleteFile":
+			host?.deleteFile(message.path);
+			break;
+		default:
+			break;
+	}
+};
+
+async function boot(message: Extract<HostMessage, { type: "boot" }>): Promise<void> {
+	// Left external by the bundler so it resolves next to dist/worker.js at
+	// runtime rather than being inlined.
+	const { default: createWgslAnalyzer } = await import("./wgsl_analyzer.js");
+
+	host = await startHost(createWgslAnalyzer, {
+		root: message.root,
+		files: message.files,
+		args: message.args,
+		onMessage: (lsp) => post({ type: "lsp", message: lsp }),
+		onStderr: (line) => post({ type: "stderr", line }),
+		onExit: (code) => post({ type: "exit", code }),
+	});
+
+	post({ type: "ready" });
+}