wowdump 0.3.9 → 0.3.11

package/dist/{reader → memory}/broker.js

@@ -1,5 +1,6 @@
 import { createInterface } from "node:readline";
 import { stdin, stdout } from "node:process";
+import { dumpNative } from "./dump.js";
 export const DEFAULT_IDLE_TIMEOUT_MS = 20 * 60 * 1000;
 export const DEFAULT_RIGHTS = Object.freeze([
     "PROCESS_QUERY_INFORMATION",
@@ -16,25 +17,25 @@ const MAX_QUERY_REGIONS = 100_000;
 function hexAddress(value) {
     const normalized = value.trim();
     if (!/^0x[0-9a-f]+$/i.test(normalized)) {
-        throw new ReaderProtocolError("INVALID_ADDRESS", "address must be a hexadecimal 0x-prefixed string");
+        throw new MemoryProtocolError("INVALID_ADDRESS", "address must be a hexadecimal 0x-prefixed string");
     }
     const address = BigInt(normalized);
     if (address < 0n || address > 0xffffffffffffffffn) {
-        throw new ReaderProtocolError("INVALID_ADDRESS", "address is outside the 64-bit range");
+        throw new MemoryProtocolError("INVALID_ADDRESS", "address is outside the 64-bit range");
     }
     return address;
 }
 function boundedSize(value, name, maximum = 16 * 1024 * 1024) {
     const size = Number(value);
     if (!Number.isSafeInteger(size) || size <= 0 || size > maximum) {
-        throw new ReaderProtocolError("INVALID_SIZE", `${name} must be an integer between 1 and ${maximum}`);
+        throw new MemoryProtocolError("INVALID_SIZE", `${name} must be an integer between 1 and ${maximum}`);
     }
     return size;
 }
 function boundedPid(value) {
     const pid = Number(value);
     if (!Number.isSafeInteger(pid) || pid <= 0 || pid > 0x7fffffff) {
-        throw new ReaderProtocolError("INVALID_PID", "pid must be a positive Windows process id");
+        throw new MemoryProtocolError("INVALID_PID", "pid must be a positive Windows process id");
     }
     return pid;
 }
@@ -43,7 +44,7 @@ function boundedCount(value, name, maximum, fallback) {
         return fallback;
     const count = Number(value);
     if (!Number.isSafeInteger(count) || count < 1 || count > maximum) {
-        throw new ReaderProtocolError("INVALID_COUNT", `${name} must be an integer between 1 and ${maximum}`);
+        throw new MemoryProtocolError("INVALID_COUNT", `${name} must be an integer between 1 and ${maximum}`);
     }
     return count;
 }
@@ -52,20 +53,20 @@ function toHex(bytes) {
 }
 function bytesFromResult(result) {
     if (!result || !(result.bytes instanceof Uint8Array)) {
-        throw new ReaderProtocolError("NATIVE_RESULT", "native reader returned no byte buffer");
+        throw new MemoryProtocolError("NATIVE_RESULT", "native memory returned no byte buffer");
     }
     const bytesRead = result.bytesRead === undefined ? result.bytes.byteLength : Number(result.bytesRead);
     if (!Number.isSafeInteger(bytesRead) || bytesRead < 0 || bytesRead > result.bytes.byteLength) {
-        throw new ReaderProtocolError("NATIVE_RESULT", "native reader returned an invalid bytesRead value");
+        throw new MemoryProtocolError("NATIVE_RESULT", "native memory returned an invalid bytesRead value");
     }
     return { bytes: result.bytes.subarray(0, bytesRead), bytesRead };
 }
-export class ReaderProtocolError extends Error {
+export class MemoryProtocolError extends Error {
     code;
     details;
     constructor(code, message, details) {
         super(message);
-        this.name = "ReaderProtocolError";
+        this.name = "MemoryProtocolError";
         this.code = code;
         this.details = details;
     }
@@ -74,9 +75,9 @@ export class ReaderProtocolError extends Error {
  * Placeholder backend used until the platform adapter is installed.  Keeping
  * this explicit makes an unavailable native layer observable to the caller.
  */
-export class UnavailableNativeReader {
+export class UnavailableNativeMemory {
     diagnostic() {
-        throw new ReaderProtocolError("NATIVE_BACKEND_UNAVAILABLE", "Windows native reader backend is not installed", {
+        throw new MemoryProtocolError("NATIVE_BACKEND_UNAVAILABLE", "Windows native memory backend is not installed", {
             platform: process.platform,
             requestedRights: [...DEFAULT_RIGHTS],
             elevation: this.elevationStatus()
@@ -97,23 +98,22 @@ export class UnavailableNativeReader {
         };
     }
 }
-export class ReaderBroker {
+export class MemoryBroker {
     idleTimeoutMs;
     backend;
     now;
     onShutdown;
-    runDebug;
     handles = new Map();
     watches = new Map();
     idleTimer;
     watchCounter = 0;
     stopped = false;
+    activeRequests = 0;
     constructor(options = {}) {
-        this.backend = options.backend ?? new UnavailableNativeReader();
+        this.backend = options.backend ?? new UnavailableNativeMemory();
         this.idleTimeoutMs = Math.max(1, Math.floor(options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS));
         this.now = options.now ?? Date.now;
         this.onShutdown = options.onShutdown;
-        this.runDebug = options.runDebug;
         this.armIdleTimer();
     }
     get isStopped() {
@@ -130,17 +130,24 @@ export class ReaderBroker {
         const command = typeof request?.command === "string" ? request.command : "unknown";
         const base = { id: request?.id, ok: true, command, timestamp: this.now() };
         if (this.stopped) {
-            return { ...base, ok: false, error: { code: "BROKER_STOPPED", message: "reader broker is stopped" } };
+            return { ...base, ok: false, error: { code: "BROKER_STOPPED", message: "memory broker is stopped" } };
         }
+        this.activeRequests += 1;
+        if (this.idleTimer)
+            clearTimeout(this.idleTimer);
         try {
             const result = await this.dispatch(request);
             this.armIdleTimer();
-            return { ...base, ...result, ok: true };
+            return { ...base, ...result, ok: result.ok !== false };
         }
         catch (error) {
             this.armIdleTimer();
             return { ...base, ok: false, error: serializeError(error, this.backend) };
         }
+        finally {
+            this.activeRequests -= 1;
+            this.armIdleTimer();
+        }
     }
     async shutdown(reason = "request") {
         if (this.stopped)
@@ -160,7 +167,7 @@ export class ReaderBroker {
         await Promise.resolve(this.onShutdown?.(reason)).catch(() => undefined);
     }
     armIdleTimer() {
-        if (this.stopped)
+        if (this.stopped || this.activeRequests > 0)
             return;
         if (this.idleTimer)
             clearTimeout(this.idleTimer);
@@ -174,16 +181,16 @@ export class ReaderBroker {
         switch (request.command) {
             case "status":
                 return {
+                    engine: "native-memory",
+                    capabilities: ["read", "regions", "modules", "dump", "watch"],
                     pid: process.pid,
                     idleTimeoutMs: this.idleTimeoutMs,
                     activeHandles: this.handles.size,
                     activeWatches: this.activeWatchCount,
                     elevation: await Promise.resolve(this.backend.elevationStatus?.() ?? { state: "unknown" })
                 };
-            case "debug":
-                if (!this.runDebug)
-                    throw new ReaderProtocolError("CDB_NOT_CONFIGURED", "elevated CDB runner is not configured");
-                return this.runDebug(request);
+            case "dump":
+                return dumpNative(request, this.backend);
             case "modules":
                 return this.modules(request);
             case "regions":
@@ -204,7 +211,7 @@ export class ReaderBroker {
                 await this.shutdown("request");
                 return { stopped: true };
             default:
-                throw new ReaderProtocolError("UNKNOWN_COMMAND", `unsupported reader command: ${String(request?.command)}`);
+                throw new MemoryProtocolError("UNKNOWN_COMMAND", `unsupported memory command: ${String(request?.command)}`);
         }
     }
     async getHandle(pid, requested) {
@@ -212,7 +219,7 @@ export class ReaderBroker {
         if (existing && (!requested || requested === existing.id))
             return existing;
         if (requested && existing?.id !== requested) {
-            throw new ReaderProtocolError("HANDLE_MISMATCH", `handle ${requested} is not open for pid ${pid}`);
+            throw new MemoryProtocolError("HANDLE_MISMATCH", `handle ${requested} is not open for pid ${pid}`);
         }
         const handle = await this.backend.openProcess(pid, DEFAULT_RIGHTS);
         this.handles.set(pid, handle);
@@ -270,13 +277,13 @@ export class ReaderBroker {
     async modules(request) {
         const pid = boundedPid(request.pid);
         if (!this.backend.enumerateModules) {
-            throw new ReaderProtocolError("MODULE_ENUM_UNAVAILABLE", "native module enumeration is not installed");
+            throw new MemoryProtocolError("MODULE_ENUM_UNAVAILABLE", "native module enumeration is not installed");
         }
         return { pid, modules: await this.backend.enumerateModules(pid) };
     }
     async regions(request) {
         if (!this.backend.virtualQueryEx) {
-            throw new ReaderProtocolError("VIRTUAL_QUERY_UNAVAILABLE", "native VirtualQueryEx backend is not installed");
+            throw new MemoryProtocolError("VIRTUAL_QUERY_UNAVAILABLE", "native VirtualQueryEx backend is not installed");
         }
         const pid = boundedPid(request.pid);
         const requestedStart = hexAddress(request.start ?? `0x${DEFAULT_QUERY_START.toString(16)}`);
@@ -284,7 +291,7 @@ export class ReaderBroker {
         const requestedEnd = hexAddress(request.end ?? `0x${DEFAULT_QUERY_END.toString(16)}`);
         const end = requestedEnd > MAX_USER_QUERY_ADDRESS ? MAX_USER_QUERY_ADDRESS : requestedEnd;
         if (end < start)
-            throw new ReaderProtocolError("INVALID_RANGE", "end must be greater than or equal to start");
+            throw new MemoryProtocolError("INVALID_RANGE", "end must be greater than or equal to start");
         const maxRegions = boundedCount(request.maxRegions, "maxRegions", MAX_QUERY_REGIONS, 4096);
         const includeFree = request.includeFree === true;
         const handle = await this.getHandle(pid, request.handle);
@@ -299,13 +306,13 @@ export class ReaderBroker {
                 regionSize = BigInt(String(raw.regionSize ?? "0"));
             }
             catch {
-                throw new ReaderProtocolError("NATIVE_RESULT", "VirtualQueryEx returned an invalid region size");
+                throw new MemoryProtocolError("NATIVE_RESULT", "VirtualQueryEx returned an invalid region size");
             }
             if (regionSize <= 0n)
-                throw new ReaderProtocolError("NATIVE_RESULT", "VirtualQueryEx returned a non-positive region size");
+                throw new MemoryProtocolError("NATIVE_RESULT", "VirtualQueryEx returned a non-positive region size");
             const next = baseAddress + regionSize;
             if (next <= cursor)
-                throw new ReaderProtocolError("NATIVE_RESULT", "VirtualQueryEx did not advance the query address");
+                throw new MemoryProtocolError("NATIVE_RESULT", "VirtualQueryEx did not advance the query address");
             const state = Number(raw.state);
             if (includeFree || state === MEM_COMMIT) {
                 regions.push({
@@ -359,7 +366,7 @@ export class ReaderBroker {
     }
     async watchPoll(request) {
         if (!request.watchId || typeof request.watchId !== "string")
-            throw new ReaderProtocolError("INVALID_WATCH", "watchId is required");
+            throw new MemoryProtocolError("INVALID_WATCH", "watchId is required");
         const watch = this.watches.get(request.watchId);
         if (!watch || watch.stopped)
             return { watchId: request.watchId, stopped: true, events: [] };
@@ -400,12 +407,12 @@ export class ReaderBroker {
         }
         catch (error) {
             watch.stopped = true;
-            return { watchId: watch.id, stopped: true, reason: "reader_error", events: [{ type: "reader_error", watchId: watch.id, pid: watch.pid, sequence: watch.sequence + 1, timestamp: this.now(), error: serializeError(error, this.backend) }] };
+            return { watchId: watch.id, stopped: true, reason: "memory_error", events: [{ type: "memory_error", watchId: watch.id, pid: watch.pid, sequence: watch.sequence + 1, timestamp: this.now(), error: serializeError(error, this.backend) }] };
         }
     }
     async watchStop(request) {
         if (!request.watchId || typeof request.watchId !== "string")
-            throw new ReaderProtocolError("INVALID_WATCH", "watchId is required");
+            throw new MemoryProtocolError("INVALID_WATCH", "watchId is required");
         const watch = this.watches.get(request.watchId);
         if (!watch)
             return { watchId: request.watchId, stopped: false };
@@ -423,21 +430,21 @@ function equalBytes(left, right) {
     return true;
 }
 function serializeError(error, backend) {
-    if (error instanceof ReaderProtocolError) {
+    if (error instanceof MemoryProtocolError) {
         return { code: error.code, message: error.message, ...(error.details ? { details: error.details } : {}) };
     }
     const message = error instanceof Error ? error.message : String(error);
     const typed = error;
     return {
-        code: typeof typed.code === "string" ? typed.code : "READER_ERROR",
+        code: typeof typed.code === "string" ? typed.code : "MEMORY_ERROR",
         message,
         ...(typed.details && typeof typed.details === "object" ? { details: typed.details } : {}),
         elevation: backend.elevationStatus ? backend.elevationStatus() : { state: "unknown" }
     };
 }
 /** Start a JSONL broker process over stdio. */
-export function serveReaderBroker(options = {}) {
-    const broker = new ReaderBroker({ ...options, attachStdio: false });
+export function serveMemoryBroker(options = {}) {
+    const broker = new MemoryBroker({ ...options, attachStdio: false });
     if (options.attachStdio !== false) {
         const input = options.input ?? stdin;
         const output = options.output ?? stdout;
@@ -475,7 +482,7 @@ export function serveReaderBroker(options = {}) {
     return broker;
 }
 /** Small typed client used by the CLI; transport owns process/UAC reuse. */
-export class ReaderClient {
+export class MemoryClient {
     transport;
     requestTimeoutMs;
     counter = 0;
@@ -488,7 +495,7 @@ export class ReaderClient {
         const line = await withTimeout(this.transport.request(JSON.stringify({ ...request, id })), this.requestTimeoutMs);
         const response = JSON.parse(line);
         if (!response || typeof response !== "object" || typeof response.ok !== "boolean") {
-            throw new ReaderProtocolError("INVALID_RESPONSE", "reader broker returned an invalid JSONL response");
+            throw new MemoryProtocolError("INVALID_RESPONSE", "memory broker returned an invalid JSONL response");
         }
         return response;
     }
@@ -498,8 +505,8 @@ export class ReaderClient {
 }
 function withTimeout(promise, timeoutMs) {
     return new Promise((resolve, reject) => {
-        const timer = setTimeout(() => reject(new ReaderProtocolError("REQUEST_TIMEOUT", `reader request timed out after ${timeoutMs}ms`)), timeoutMs);
-        timer.unref?.();
+        const timer = setTimeout(() => reject(new MemoryProtocolError("REQUEST_TIMEOUT", `memory request timed out after ${timeoutMs}ms`)), timeoutMs);
+        // An in-flight request must settle even when the transport has no active handles.
         promise.then(value => { clearTimeout(timer); resolve(value); }, error => { clearTimeout(timer); reject(error); });
     });
 }
@@ -509,7 +516,7 @@ export function createElevatedLaunchSpec(file, args = []) {
     return Object.freeze({ file, args: [...args], verb: "runas", windowsHide: false });
 }
 /** Reuse one broker client and invoke the launcher only after the first miss. */
-export class ReaderBrokerPool {
+export class MemoryBrokerPool {
     client;
     launching;
     launcher;
@@ -541,10 +548,10 @@ export class ReaderBrokerPool {
             return this.client;
         if (!this.launching) {
             this.launching = this.launcher.launch(this.launchSpec).then(result => {
-                this.client = new ReaderClient({ transport: result.transport, requestTimeoutMs: this.requestTimeoutMs });
+                this.client = new MemoryClient({ transport: result.transport, requestTimeoutMs: this.requestTimeoutMs });
                 return this.client;
             }).catch(error => {
-                throw new ReaderProtocolError("ELEVATION_FAILED", error instanceof Error ? error.message : String(error), {
+                throw new MemoryProtocolError("ELEVATION_FAILED", error instanceof Error ? error.message : String(error), {
                     verb: this.launchSpec.verb,
                     requestedRights: [...DEFAULT_RIGHTS],
                     elevation: "launch rejected or cancelled"

package/dist/memory/client.js

@@ -0,0 +1 @@
+export { MemoryClient, MemoryBrokerPool, MemoryProtocolError, createElevatedLaunchSpec } from "./broker.js";

package/dist/memory/dump.js

@@ -0,0 +1,142 @@
+import { createHash } from "node:crypto";
+import { mkdir, open, rm, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { readPeLayout } from "../analysis/pe.js";
+import { sha256File } from "../core/build-store.js";
+function fail(code, message) { throw Object.assign(new Error(message), { code }); }
+function bounded(n, max) {
+    if (!Number.isSafeInteger(n) || n < 1 || n > max)
+        fail("DUMP_ARGUMENT_INVALID", "invalid dump limit");
+    return n;
+}
+/** Only the broker touches bytes. IPC carries paths and bounded summaries. */
+export async function dumpNative(request, backend) {
+    const chunkBytes = bounded(request.chunkBytes ?? 65536, 1024 * 1024);
+    bounded(request.maxSectionBytes, 512 * 1024 * 1024);
+    bounded(request.maxTotalBytes, 768 * 1024 * 1024);
+    bounded(request.timeoutMs, 15 * 60 * 1000);
+    bounded(request.pid, 0x7fffffff);
+    if (!/^[A-Za-z0-9@._-]+$/.test(request.buildKey) || !/^[a-f0-9]{64}$/i.test(request.executableSha256))
+        fail("DUMP_ARGUMENT_INVALID", "invalid build identity");
+    if (!backend.virtualQueryEx || !backend.enumerateModules)
+        fail("NATIVE_BACKEND_UNAVAILABLE", "module enumeration and page query are required");
+    const module = (await backend.enumerateModules(request.pid)).find(m => /^Wow\.exe$/i.test(m.name));
+    if (!module?.path)
+        fail("MODULE_NOT_FOUND", "Wow.exe not found");
+    if (await sha256File(module.path) !== request.executableSha256)
+        fail("BUILD_MISMATCH", "target executable hash differs from build");
+    const layout = await readPeLayout(module.path);
+    if (module.size !== undefined && module.size !== layout.moduleSize)
+        fail("BUILD_MISMATCH", "module size differs from PE");
+    if (!Array.isArray(request.sections) || request.sections.length < 1 || request.sections.length > 64 || new Set(request.sections).size !== request.sections.length)
+        fail("DUMP_ARGUMENT_INVALID", "invalid section selection");
+    const selected = request.sections.map(name => {
+        const s = layout.sections.find(s => s.name.toLowerCase() === name.toLowerCase());
+        if (!s || !/^\.[A-Za-z0-9_-]+$/.test(s.name))
+            fail("SECTION_NOT_FOUND", `unknown section ${name}`);
+        return s;
+    });
+    let total = 0;
+    for (const s of selected) {
+        const size = s.virtualSize || s.rawSize;
+        if (size > request.maxSectionBytes || (total += size) > request.maxTotalBytes)
+            fail("DUMP_LIMIT_EXCEEDED", "raise explicit limits or select fewer sections");
+        if (BigInt(s.rva) + BigInt(size) > BigInt(layout.moduleSize))
+            fail("PE_INVALID", "section exceeds image");
+    }
+    const directory = resolve(request.outputDir);
+    // Non-recursive exclusive directory creation prevents overwriting prior evidence.
+    await mkdir(resolve(directory, ".."), { recursive: true });
+    await mkdir(directory);
+    const startedAt = new Date().toISOString();
+    const deadline = Date.now() + request.timeoutMs;
+    const sections = [];
+    let completedBytes = 0;
+    let handle;
+    try {
+        handle = await backend.openProcess(request.pid, ["PROCESS_QUERY_INFORMATION", "PROCESS_VM_READ"]);
+        for (const section of selected) {
+            const size = section.virtualSize || section.rawSize;
+            const base = BigInt(module.base) + BigInt(section.rva);
+            const file = join(directory, `${section.name}.bin`);
+            const output = await open(file, "wx");
+            const hash = createHash("sha256");
+            const gaps = [];
+            let offset = 0, readSize = 0;
+            try {
+                while (offset < size) {
+                    if (Date.now() >= deadline)
+                        fail("DUMP_TIMEOUT", "native dump timed out");
+                    if (backend.isProcessAlive && !await backend.isProcessAlive(request.pid))
+                        fail("TARGET_EXITED", "target exited during dump");
+                    const address = base + BigInt(offset);
+                    let count = Math.min(chunkBytes, size - offset), bytes = Buffer.alloc(0), reason = "unreadable-page";
+                    try {
+                        const page = await backend.virtualQueryEx(handle, address);
+                        const end = BigInt(String(page.baseAddress)) + BigInt(String(page.regionSize));
+                        if (end <= address)
+                            fail("PAGE_INVALID", "page query made no progress");
+                        count = Number(BigInt(count) < end - address ? BigInt(count) : end - address);
+                        const protection = Number(page.protect);
+                        if (Number(page.state) === 0x1000 && !(protection & 0x100) && [2, 4, 8, 0x20, 0x40, 0x80].includes(protection & 0xff)) {
+                            const read = await backend.readProcessMemory(handle, address, count);
+                            const n = read.bytesRead ?? read.bytes.length;
+                            if (!Number.isSafeInteger(n) || n < 0 || n > count || n > read.bytes.length)
+                                fail("NATIVE_RESULT", "invalid read length");
+                            bytes = Buffer.from(read.bytes.subarray(0, n));
+                            reason = "short-read";
+                        }
+                    }
+                    catch (error) {
+                        if (error.code === "NATIVE_RESULT")
+                            throw error;
+                        count = Math.min(count, 4096 - Number(address % 4096n));
+                        reason = error instanceof Error ? error.message.slice(0, 160) : "read-failed";
+                    }
+                    const block = Buffer.alloc(count);
+                    bytes.copy(block);
+                    readSize += bytes.length;
+                    if (bytes.length < count) {
+                        const gap = { offset: offset + bytes.length, size: count - bytes.length, reason };
+                        const previous = gaps.at(-1);
+                        if (previous && previous.reason === reason && previous.offset + previous.size === gap.offset)
+                            previous.size += gap.size;
+                        else
+                            gaps.push(gap);
+                        if (gaps.length > 65536)
+                            fail("DUMP_GAP_LIMIT", "too many unreadable ranges");
+                    }
+                    let written = 0;
+                    while (written < count) {
+                        const r = await output.write(block, written, count - written, offset + written);
+                        if (!r.bytesWritten)
+                            fail("DUMP_WRITE_FAILED", "zero byte write");
+                        written += r.bytesWritten;
+                    }
+                    hash.update(block);
+                    offset += count;
+                    completedBytes += count;
+                    await writeFile(join(directory, "progress.json"), JSON.stringify({ completedBytes, totalBytes: total, section: section.name, offset }));
+                }
+            }
+            finally {
+                await output.close();
+            }
+            sections.push({ ...section, runtimeAddress: `0x${base.toString(16)}`, file, bytes: size, readSize, shortRead: readSize !== size, gaps, sha256: hash.digest("hex") });
+        }
+        if (Date.now() >= deadline)
+            fail("DUMP_TIMEOUT", "native dump timed out");
+        const complete = sections.every(s => !s.shortRead);
+        const manifest = { schema: "wowdump.runtime-dump.v4", engine: "native-memory", buildKey: request.buildKey, executableSha256: request.executableSha256, pid: request.pid, moduleBase: module.base, preferredImageBase: layout.imageBase, moduleSize: layout.moduleSize, startedAt, generatedAt: new Date().toISOString(), atomic: false, complete, zeroFilledGaps: true, sections, totalBytes: total };
+        const manifestFile = join(directory, "manifest.json");
+        await writeFile(manifestFile, JSON.stringify(manifest, null, 2));
+        return { ok: complete, kind: "dump", manifestFile, outputDirectory: directory, complete, totalBytes: total, sections: sections.map(s => ({ name: s.name, bytes: s.bytes, readSize: s.readSize, sha256: s.sha256, shortRead: s.shortRead })), ...(!complete ? { error: { code: "DUMP_INCOMPLETE", message: "manifest records unreadable ranges" } } : {}) };
+    }
+    catch (error) {
+        await rm(directory, { recursive: true, force: true });
+        throw error;
+    }
+    finally {
+        await handle?.close();
+    }
+}

package/dist/{reader → memory}/launcher.js

@@ -3,7 +3,7 @@ import { createConnection } from "node:net";
 import { mkdir, open, readFile, rm } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import koffi from "koffi";
-import { ReaderProtocolError } from "./broker.js";
+import { MemoryProtocolError } from "./broker.js";
 function quoteWindowsArgument(value) {
     if (value.length > 0 && !/[\s"]/u.test(value))
         return value;
@@ -95,7 +95,7 @@ function requestPipe(metadata, request, timeoutMs) {
                 resolveResult(value);
         };
         const timer = setTimeout(() => {
-            const error = new Error(`reader broker request timed out after ${timeoutMs}ms`);
+            const error = new Error(`memory broker request timed out after ${timeoutMs}ms`);
             error.code = "BROKER_REQUEST_TIMEOUT";
             finish(error);
         }, timeoutMs);
@@ -115,7 +115,7 @@ function requestPipe(metadata, request, timeoutMs) {
         });
         socket.once("error", error => finish(error));
         socket.once("end", () => { if (!settled)
-            finish(new Error("reader broker closed without a response")); });
+            finish(new Error("memory broker closed without a response")); });
     });
 }
 async function pause(milliseconds) {
@@ -125,12 +125,12 @@ export class WindowsBrokerManager {
     metadataFile;
     options;
     constructor(options) {
-        this.options = { ...options, home: resolve(options.home), readerEntry: resolve(options.readerEntry) };
-        this.metadataFile = join(this.options.home, "runtime", "reader-broker.json");
+        this.options = { ...options, home: resolve(options.home), memoryEntry: resolve(options.memoryEntry) };
+        this.metadataFile = join(this.options.home, "runtime", "memory-broker.json");
     }
     async request(invocation) {
         const request = invocationRequest(invocation);
-        const requestTimeout = invocation.command === "debug"
+        const requestTimeout = invocation.command === "dump"
             ? Math.max(this.options.requestTimeoutMs ?? 30_000, Math.min(15 * 60_000, Number(invocation.payload.durationMs ?? invocation.payload.timeoutMs ?? 120_000) + 10_000))
             : this.options.requestTimeoutMs ?? 30_000;
         const existing = await this.readMetadata();
@@ -140,7 +140,7 @@ export class WindowsBrokerManager {
             }
             catch (error) {
                 const code = error.code;
-                // A long-running debugger request is not evidence that the broker died.
+                // A long-running dump request is not evidence that the broker died.
                 // Keep its metadata so the next command reuses the elevated process.
                 if (code === "BROKER_REQUEST_TIMEOUT")
                     throw error;
@@ -153,7 +153,7 @@ export class WindowsBrokerManager {
     async readMetadata() {
         try {
             const value = JSON.parse(await readFile(this.metadataFile, "utf8"));
-            return value?.schema === "wowdump.reader-broker.v1"
+            return value?.schema === "wowdump.memory-broker.v1"
                 && value.host === "127.0.0.1"
                 && Number.isSafeInteger(value.port)
                 && value.port > 0
@@ -166,6 +166,32 @@ export class WindowsBrokerManager {
             return undefined;
         }
     }
+    async retireLegacyBroker() {
+        const file = join(this.options.home, "runtime", "reader-broker.json");
+        let metadata;
+        try {
+            metadata = JSON.parse(await readFile(file, "utf8"));
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return;
+            throw error;
+        }
+        if (metadata.schema !== "wowdump.reader-broker.v1" || metadata.host !== "127.0.0.1" ||
+            !Number.isSafeInteger(metadata.port) || metadata.port < 1 || metadata.port > 65535 || typeof metadata.token !== "string") {
+            throw new MemoryProtocolError("LEGACY_BROKER_INVALID", "legacy broker metadata is invalid");
+        }
+        try {
+            const result = await requestPipe(metadata, { command: "shutdown" }, 3000);
+            if (!result?.ok)
+                throw new MemoryProtocolError("LEGACY_BROKER_BUSY", "legacy broker did not accept shutdown");
+        }
+        catch (error) {
+            if (error.code !== "ECONNREFUSED")
+                throw error;
+        }
+        await rm(file, { force: true });
+    }
     async launchBroker() {
         await mkdir(dirname(this.metadataFile), { recursive: true });
         const lockFile = `${this.metadataFile}.lock`;
@@ -187,19 +213,20 @@ export class WindowsBrokerManager {
             return this.launchBroker();
         }
         const token = randomBytes(32).toString("hex");
-        const args = [this.options.readerEntry, "--listen", "127.0.0.1", "--port", "0", "--token", token, "--metadata", this.metadataFile];
+        const args = [this.options.memoryEntry, "--listen", "127.0.0.1", "--port", "0", "--token", token, "--metadata", this.metadataFile];
         const launch = this.options.launch ?? shellExecuteRunAs;
         try {
+            await this.retireLegacyBroker();
             try {
-                launch(this.options.nodeExecutable ?? process.execPath, args, dirname(this.options.readerEntry));
+                launch(this.options.nodeExecutable ?? process.execPath, args, dirname(this.options.memoryEntry));
             }
             catch (error) {
                 const native = error;
-                throw new ReaderProtocolError("ELEVATION_FAILED", native.message, {
+                throw new MemoryProtocolError("ELEVATION_FAILED", native.message, {
                     verb: "runas",
                     win32: native.win32 ?? null,
                     requestedRights: ["PROCESS_QUERY_INFORMATION", "PROCESS_VM_READ"],
-                    readerEntry: this.options.readerEntry
+                    memoryEntry: this.options.memoryEntry
                 });
             }
             const deadline = Date.now() + (this.options.launchTimeoutMs ?? 30_000);
@@ -209,7 +236,7 @@ export class WindowsBrokerManager {
                     return metadata;
                 await pause(100);
             }
-            throw new Error(`elevated reader broker did not become ready within ${this.options.launchTimeoutMs ?? 30_000}ms`);
+            throw new Error(`elevated memory broker did not become ready within ${this.options.launchTimeoutMs ?? 30_000}ms`);
         }
         finally {
             await lock.close().catch(() => undefined);

package/dist/{reader → memory}/main.js

@@ -2,9 +2,8 @@
 import { createServer } from "node:net";
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
-import { serveReaderBroker } from "./broker.js";
-import { executeCdbDebug } from "../debug/cdb.js";
-import { createWindowsNativeReader } from "./windows.js";
+import { serveMemoryBroker } from "./broker.js";
+import { createWindowsNativeMemory } from "./windows.js";
 function argument(name) {
     const index = process.argv.indexOf(name);
     return index >= 0 ? process.argv[index + 1] : undefined;
@@ -14,24 +13,10 @@ const port = Number(argument("--port") ?? "0");
 const token = argument("--token");
 const metadata = argument("--metadata");
 let server;
-const backend = process.env.WOWDUMP_USE_FAKE_READER === "1" ? undefined : createWindowsNativeReader();
-const broker = serveReaderBroker({
+const backend = process.env.WOWDUMP_USE_FAKE_MEMORY === "1" ? undefined : createWindowsNativeMemory();
+const broker = serveMemoryBroker({
     attachStdio: !listen,
     backend,
-    runDebug: async (request) => {
-        const debugRequest = request;
-        if (!backend)
-            return executeCdbDebug(debugRequest);
-        const handle = await backend.openProcess(request.pid, ["PROCESS_QUERY_INFORMATION"]);
-        try {
-            return await executeCdbDebug(debugRequest, address => backend.virtualQueryEx
-                ? backend.virtualQueryEx(handle, address)
-                : Promise.reject(new Error("VirtualQueryEx is not installed")));
-        }
-        finally {
-            await Promise.resolve(handle.close()).catch(() => undefined);
-        }
-    },
     onShutdown: async () => {
         server?.close();
         if (metadata)
@@ -56,7 +41,7 @@ if (listen) {
                     try {
                         const envelope = JSON.parse(line);
                         if (envelope.token !== token || !envelope.request) {
-                            socket.write(`${JSON.stringify({ ok: false, command: "auth", timestamp: Date.now(), error: { code: "AUTH_FAILED", message: "invalid reader broker token" } })}\n`);
+                            socket.write(`${JSON.stringify({ ok: false, command: "auth", timestamp: Date.now(), error: { code: "AUTH_FAILED", message: "invalid memory broker token" } })}\n`);
                             return;
                         }
                         socket.write(`${JSON.stringify(await broker.handle(envelope.request))}\n`);
@@ -72,8 +57,8 @@ if (listen) {
         await mkdir(dirname(metadata), { recursive: true });
         const address = server?.address();
         if (!address || typeof address === "string")
-            throw new Error("reader broker did not acquire a TCP endpoint");
-        await writeFile(metadata, `${JSON.stringify({ schema: "wowdump.reader-broker.v1", host: listen, port: address.port, token, pid: process.pid })}\n`, { encoding: "utf8", mode: 0o600 });
+            throw new Error("memory broker did not acquire a TCP endpoint");
+        await writeFile(metadata, `${JSON.stringify({ schema: "wowdump.memory-broker.v1", host: listen, port: address.port, token, pid: process.pid })}\n`, { encoding: "utf8", mode: 0o600 });
     });
 }
 const shutdown = () => {