Conn has a memory leak

[awake23]

Environment

node24

Reproduction

none

Describe the bug

While investigating a memory leak related to Conn, I found that ImportClient appears to strongly retain Conn, preventing it from being garbage collected in Node.js.

During testing, explicitly breaking the reference from ImportClient back to Conn allows both Conn and higher-level objects to be released:

Object.values(conn.imports).forEach(v => {
  delete v.rc._client.conn;
});

After this, heap snapshots no longer show Conn or related objects.

This suggests that there is a strong reference cycle involving:

Conn -> imports -> RefCount -> ImportClient -> Conn

I’m not deeply familiar with the intended lifecycle semantics of this library, but this reference chain seems to make it difficult (or impossible) for Conn to be GC’d under normal shutdown, even after closing the transport.

I hope this observation helps narrow down the issue.
Please let me know if a minimal reproduction or heap snapshot would be useful.

Additional context

No response

Logs

[awake23]

Issue: FinalizationRegistry callback closure strongly retains RefCount, extending its lifetime unintentionally

In the Ref constructor, the following logic is used:

constructor(
  public rc: RefCount,
  finalize: Finalize,
) {
  const closeState = { closed: false };
  this.closeState = closeState;
  finalize(this, () => {
    if (!closeState.closed) {
      closeState.closed = true;
      rc.decref();
    }
  });
}

finalize(this, ...) ultimately registers the callback via FinalizationRegistry.register(target, heldValue).

Core problem

• FinalizationRegistry strongly retains the heldValue
• In the current implementation, the heldValue is a closure
• That closure strongly captures rc: RefCount

This creates the following reference chain:

global FinalizationRegistry
  → registry record
    → finalizer callback (closure)
      → RefCount (rc)

Observed impact

• As long as the registry record exists, RefCount is strongly retained and cannot be garbage-collected
• Even after the Ref (target) becomes unreachable, finalization and record cleanup are not guaranteed to run promptly
• Heap snapshots show RefCount being retained via FinalizationRegistry → finalizer callback

In practice, this causes RefCount’s lifetime to be closer to the registry’s lifetime (global singleton) rather than the logical lifetime of the Ref.

Root cause

By specification:

• target is weakly referenced
• heldValue is strongly referenced
• The lifetime of heldValue depends on the registry record, not on the target

Therefore, capturing resource-management objects (such as RefCount) in a finalizer is unsafe.

Suggested improvements

• Avoid strongly referencing RefCount in the finalizer

• Consider:

  • Using WeakRef<RefCount> as the heldValue
  • Restricting finalizers to diagnostics only (logging / leak detection)
  • Explicitly calling unregister() when close() is invoked

Otherwise, this design can lead to real memory retention issues in long-running processes.

[vicb]

Note that RPC in this package is experimental and probably has many other shortcomings