quickjs-emscripten-sync 1.9.0 → 1.10.0

package/src/marshal/function.ts

@@ -12,24 +12,45 @@ export default function marshalFunction(
   unmarshal: (handle: QuickJSHandle) => unknown,
   preMarshal: (target: unknown, handle: QuickJSHandle) => QuickJSHandle | undefined,
   preApply?: (target: (...args: any[]) => any, thisArg: unknown, args: unknown[]) => any,
+  disposeTransient: (handle: QuickJSHandle) => void = () => {},
+  prepareReturn: (handle: QuickJSHandle) => QuickJSHandle = h => h,
 ): QuickJSHandle | undefined {
   if (typeof target !== "function") return;
 
   const raw = ctx
     .newFunction(target.name, function (...argHandles) {
-      const that = unmarshal(this);
+      // A plain call (`fn()`) passes the VM global object as `this`. Unmarshalling
+      // it would eagerly deep-copy the entire global graph (hundreds of handles)
+      // on the first call, for a `this` host functions almost never use — and
+      // leaking globalThis to the host is undesirable. So global `this` is passed
+      // to the host function as `undefined`, which differs from plain JS where a
+      // non-strict function sees `this === globalThis` (see README Limitations).
+      // Real method calls still get their receiver unmarshalled.
+      const that = ctx.sameValue(this, ctx.global) ? undefined : unmarshal(this);
       const args = argHandles.map(a => unmarshal(a));
 
       if (isES2015Class(target) && isObject(that)) {
         // Class constructors cannot be invoked without new expression, and new.target is not changed
         const result = new target(...args);
         Object.entries(result).forEach(([key, value]) => {
-          ctx.setProp(this, key, marshal(value));
+          const valueHandle = marshal(value);
+          ctx.setProp(this, key, valueHandle);
+          // setProp dup'd the value into `this`; drop ours if it was transient.
+          disposeTransient(valueHandle);
         });
         return this;
       }
 
-      return marshal(preApply ? preApply(target as (...args: any[]) => any, that, args) : (target as (...args: any[]) => any).apply(that, args));
+      // The VM disposes whatever we return here. `prepareReturn` dups the
+      // handle when the VMMap retains it, so the map keeps a live copy and
+      // identity (`x === fn()` across calls) survives instead of going stale.
+      return prepareReturn(
+        marshal(
+          preApply
+            ? preApply(target as (...args: any[]) => any, that, args)
+            : (target as (...args: any[]) => any).apply(that, args),
+        ),
+      );
     })
     .consume(handle2 =>
       // fucntions created by vm.newFunction are not callable as a class constrcutor
@@ -47,7 +68,7 @@ export default function marshalFunction(
     );
 
   const handle = preMarshal(target, raw) ?? raw;
-  marshalProperties(ctx, target, raw, marshal);
+  marshalProperties(ctx, target, raw, marshal, disposeTransient);
 
   return handle;
 }

package/src/marshal/index.ts

@@ -16,12 +16,23 @@ export type Options = {
   marshalByReference?: (target: unknown) => boolean;
   registerHostRef?: (target: unknown, handle: QuickJSHandle) => QuickJSHandle;
   find: (target: unknown) => QuickJSHandle | undefined;
+  // Track a handle that nobody else owns (json copies, BigInt) so it can be
+  // disposed once consumed.
+  registerTransient?: (handle: QuickJSHandle) => void;
+  // Dispose a handle previously registered as transient, right after a parent
+  // consumer has copied it into the parent value. A no-op for owned handles.
+  disposeTransient?: (handle: QuickJSHandle) => void;
   pre: (
     target: unknown,
     handle: QuickJSHandle | QuickJSDeferredPromise,
     mode: true | "json" | undefined,
   ) => QuickJSHandle | undefined;
   preApply?: (target: (...args: any[]) => any, thisArg: unknown, args: unknown[]) => any;
+  // Adjust ownership of a handle that is about to be handed to the VM as a host
+  // function's return value. The VM disposes whatever it receives, so a handle
+  // the VMMap retains (for identity, while sync is on) must be dup'd here or its
+  // map entry goes stale. Defaults to identity (no-op).
+  prepareReturn?: (handle: QuickJSHandle) => QuickJSHandle;
   custom?: Iterable<(obj: unknown, ctx: QuickJSContext) => QuickJSHandle | undefined>;
 };
 
@@ -31,6 +42,10 @@ export function marshal(target: unknown, options: Options): QuickJSHandle {
   {
     const primitive = marshalPrimitive(ctx, target);
     if (primitive) {
+      // BigInt handles are heap-allocated and, unlike strings and numbers, are
+      // not reclaimed unless explicitly disposed. Track them as transient so a
+      // nested one is freed by its parent consumer (or on dispose as a fallback).
+      if (typeof target === "bigint") options.registerTransient?.(primitive);
       return primitive;
     }
   }
@@ -59,12 +74,22 @@ export function marshal(target: unknown, options: Options): QuickJSHandle {
   }
 
   const marshal2 = (t: unknown) => marshal(t, options);
+  const disposeTransient = options.disposeTransient;
   return (
     marshalCustom(ctx, target, pre2, [...defaultCustom, ...(options.custom ?? [])]) ??
     marshalPromise(ctx, target, marshal2, pre2) ??
-    marshalFunction(ctx, target, marshal2, unmarshal, pre2, options.preApply) ??
-    marshalMapSet(ctx, target, marshal2, pre2) ??
-    marshalObject(ctx, target, marshal2, pre2) ??
+    marshalFunction(
+      ctx,
+      target,
+      marshal2,
+      unmarshal,
+      pre2,
+      options.preApply,
+      disposeTransient,
+      options.prepareReturn,
+    ) ??
+    marshalMapSet(ctx, target, marshal2, pre2, disposeTransient) ??
+    marshalObject(ctx, target, marshal2, pre2, disposeTransient) ??
     ctx.undefined
   );
 }

package/src/marshal/mapset.ts

@@ -7,12 +7,18 @@ export default function marshalMapSet(
   target: unknown,
   marshal: (target: unknown) => QuickJSHandle,
   preMarshal: (target: unknown, handle: QuickJSHandle) => QuickJSHandle | undefined,
+  disposeTransient: (handle: QuickJSHandle) => void = () => {},
 ): QuickJSHandle | undefined {
   if (target instanceof Map) {
     const raw = call(ctx, "() => new Map()");
     const handle = preMarshal(target, raw) ?? raw;
     for (const [k, v] of target) {
-      call(ctx, "(m, k, v) => m.set(k, v)", undefined, raw, marshal(k), marshal(v)).dispose();
+      const kh = marshal(k);
+      const vh = marshal(v);
+      call(ctx, "(m, k, v) => m.set(k, v)", undefined, raw, kh, vh).dispose();
+      // set() has taken its own references; drop ours if they were transient.
+      disposeTransient(kh);
+      disposeTransient(vh);
     }
     return handle;
   }
@@ -21,7 +27,10 @@ export default function marshalMapSet(
     const raw = call(ctx, "() => new Set()");
     const handle = preMarshal(target, raw) ?? raw;
     for (const v of target) {
-      call(ctx, "(s, v) => s.add(v)", undefined, raw, marshal(v)).dispose();
+      const vh = marshal(v);
+      call(ctx, "(s, v) => s.add(v)", undefined, raw, vh).dispose();
+      // add() has taken its own reference; drop ours if it was transient.
+      disposeTransient(vh);
     }
     return handle;
   }

package/src/marshal/object.ts

@@ -9,6 +9,7 @@ export default function marshalObject(
   target: unknown,
   marshal: (target: unknown) => QuickJSHandle,
   preMarshal: (target: unknown, handle: QuickJSHandle) => QuickJSHandle | undefined,
+  disposeTransient: (handle: QuickJSHandle) => void = () => {},
 ): QuickJSHandle | undefined {
   if (typeof target !== "object" || target === null) return;
 
@@ -23,9 +24,11 @@ export default function marshalObject(
       : undefined;
   if (prototypeHandle) {
     call(ctx, "Object.setPrototypeOf", undefined, handle, prototypeHandle).dispose();
+    // setPrototypeOf has taken its own reference; drop ours if it was transient.
+    disposeTransient(prototypeHandle);
   }
 
-  marshalProperties(ctx, target, raw, marshal);
+  marshalProperties(ctx, target, raw, marshal, disposeTransient);
 
   return handle;
 }

package/src/marshal/properties.ts

@@ -7,13 +7,21 @@ export default function marshalProperties(
   target: object | ((...args: any[]) => any),
   handle: QuickJSHandle,
   marshal: (target: unknown) => QuickJSHandle,
+  disposeTransient: (handle: QuickJSHandle) => void = () => {},
 ): void {
   const descs = ctx.newObject();
+  // Property values may be transient (json copies / BigInt) with no owner; once
+  // `Object.defineProperties` has copied them into `handle` the standalone
+  // handles are redundant and disposed below. Owned handles are left untouched.
+  const transient: QuickJSHandle[] = [];
   const cb = (key: string | number | symbol, desc: PropertyDescriptor) => {
     const keyHandle = marshal(key);
     const valueHandle = typeof desc.value === "undefined" ? undefined : marshal(desc.value);
     const getHandle = typeof desc.get === "undefined" ? undefined : marshal(desc.get);
     const setHandle = typeof desc.set === "undefined" ? undefined : marshal(desc.set);
+    if (valueHandle) transient.push(valueHandle);
+    if (getHandle) transient.push(getHandle);
+    if (setHandle) transient.push(setHandle);
 
     ctx.newObject().consume(descObj => {
       Object.entries(desc).forEach(([k, v]) => {
@@ -41,6 +49,9 @@ export default function marshalProperties(
     Object.getOwnPropertySymbols(desc).forEach(k => cb(k, (desc as any)[k]));
 
     call(ctx, `Object.defineProperties`, undefined, handle, descs).dispose();
+    // Safe only after defineProperties has dup'd the values into `handle`; `descs`
+    // still holds its own references until its own dispose() in the finally.
+    for (const h of transient) disposeTransient(h);
   } finally {
     descs.dispose();
   }

package/src/remarshalleak.test.ts

@@ -0,0 +1,50 @@
+import variant from "@jitl/quickjs-wasmfile-debug-sync";
+import { newQuickJSWASMModuleFromVariant } from "quickjs-emscripten";
+import { describe, expect, it } from "vitest";
+
+import { Arena } from ".";
+
+// Marshalling the same host object into the VM more than once used to leak a
+// handle: the first registration stores both a wrapped (proxy) handle and its
+// unwrapped sibling. Once the VM frees the proxy, the map entry goes stale, and
+// the lazy eviction in VMMap.get dropped the entry without disposing the
+// still-alive sibling. The debug-sync runtime aborts on dispose if any GC
+// object handle leaked, so reaching ctx.dispose() without an abort proves the
+// sibling is now released.
+async function withArena(fn: (arena: Arena) => void) {
+  const mod = await newQuickJSWASMModuleFromVariant(variant as any);
+  const ctx = mod.newContext();
+  const arena = new Arena(ctx, { isMarshalable: true });
+  fn(arena);
+  arena.dispose();
+  expect(() => ctx.dispose()).not.toThrow();
+}
+
+describe("re-marshal handle leak", () => {
+  // Calling an exposed function from inside the VM marshals the whole global
+  // graph on each call, which is slow under the debug-sync runtime + coverage,
+  // so these get a generous timeout (cf. the "many newFunction" edge test).
+  it(
+    "does not leak when a host function returns the same object twice",
+    async () => {
+      await withArena(arena => {
+        const shared = { k: 1 };
+        arena.expose({ get: () => shared });
+        arena.evalCode(`get(); get();`);
+      });
+    },
+    90000,
+  );
+
+  it(
+    "does not leak when the same object is compared across two calls",
+    async () => {
+      await withArena(arena => {
+        const shared = { k: 1 };
+        arena.expose({ get: () => shared });
+        arena.evalCode(`get() === get();`);
+      });
+    },
+    90000,
+  );
+});

package/src/vmmap.ts

@@ -121,7 +121,11 @@ export default class VMMap {
 
     if (!handle) return;
     if (!handle.alive) {
-      this.delete(key);
+      // The primary handle was freed by the VM, so this entry is stale. Dispose
+      // its sibling handle while evicting it: otherwise the sibling (e.g. the
+      // unwrapped handle registered alongside a proxy) is orphaned and leaks
+      // when the same value is marshalled again.
+      this.delete(key, true);
       return;
     }
 

package/src/vmutil.ts

@@ -119,7 +119,9 @@ export function isHandleObject(ctx: QuickJSContext, h: QuickJSHandle): boolean {
 export function json(ctx: QuickJSContext, target: any): QuickJSHandle {
   const json = JSON.stringify(target);
   if (!json) return ctx.undefined;
-  return call(ctx, `JSON.parse`, undefined, ctx.newString(json));
+  // `call` does not dispose its arguments, so the intermediate string handle
+  // must be consumed here or it leaks on every json marshal.
+  return ctx.newString(json).consume(s => call(ctx, `JSON.parse`, undefined, s));
 }
 
 /**