ffi: support function calls from pointers

Add getFunctionFromPointer() to create callables from native addresses
with explicit signatures.

Reuse function preparation without populating named symbol caches.
Keep the associated library alive and invalidate pointer callables
when it is closed.

Add coverage for conversions, vtables, permissions and garbage
collection, and document pointer lifetime requirements.

Assisted-by: GitHub Copilot
Signed-off-by: Damiano Mazzella <damianomazzella@gmail.com>

Author: dmazzella

doc/api/ffi.md

@@ -433,6 +433,64 @@ console.log(add(20, 22));
 console.log(add.pointer);
 ```
 
+### `library.getFunctionFromPointer(pointer, signature)`
+
+* `pointer` {bigint}
+* `signature` {Object}
+* Returns: {Function}
+
+Creates a callable JavaScript wrapper for a native function address. The pointer
+must be a nonzero, non-negative `bigint` that fits the platform's pointer width.
+It can come from a resolved symbol, a native function's return value, or a
+function pointer stored in native memory, such as a vtable slot.
+
+```cjs
+const { DynamicLibrary, suffix } = require('node:ffi');
+
+const lib = new DynamicLibrary(`./mylib.${suffix}`);
+try {
+  const address = lib.getSymbol('add_i32');
+  const add = lib.getFunctionFromPointer(address, {
+    arguments: ['int32', 'int32'],
+    return: 'int32',
+  });
+  console.log(add(20, 22));
+  console.log(add.pointer === address);
+} finally {
+  lib.close();
+}
+```
+
+Argument and return conversions follow the same rules as `getFunction()`.
+This method supports fixed signatures using the platform's default calling
+convention. Explicit calling convention selection and structures passed or
+returned by value are not supported.
+
+Each call creates a distinct wrapper. Multiple signatures can be associated
+with the same address, but the caller is responsible for their correctness.
+These wrappers do not appear in `library.functions`, `library.getFunctions()`,
+`library.symbols`, or `library.getSymbols()` unless a symbol was separately
+resolved by name. They use the generic libffi call path rather than Fast API
+or SharedBuffer invokers.
+
+The wrapper keeps the associated library alive. Calling it after
+`library.close()` throws `ERR_FFI_LIBRARY_CLOSED`. FFI permission is required
+when creating the wrapper, including after permission has been revoked on an
+already-open library.
+
+**The associated library does not establish ownership or validity of the
+address.** Node.js cannot determine whether the pointer refers to executable
+code, matches the signature, or is still valid. Passing a data pointer, using
+an incorrect signature, or calling code that has been unloaded can crash the
+process or corrupt memory.
+
+The caller must keep the actual code and any native object used by the call
+alive. For example, associating a COM vtable method with `ole32.dll` does not
+retain the COM object or the module implementing that method. The caller must
+manage its native references and lifetime. A wrapper for a callback pointer
+also becomes unsafe if that callback is unregistered, even if the associated
+library remains open.
+
 ### `library.getFunctions([definitions])`
 
 * `definitions` {Object}

lib/ffi.js

@@ -152,6 +152,7 @@ ObjectDefineProperty(DynamicLibrary.prototype, 'constructor', {
 });
 
 const rawGetFunction = DynamicLibrary.prototype.getFunction;
+const rawGetFunctionFromPointer = DynamicLibrary.prototype.getFunctionFromPointer;
 const rawGetFunctions = DynamicLibrary.prototype.getFunctions;
 const rawClose = DynamicLibrary.prototype.close;
 
@@ -180,6 +181,11 @@ DynamicLibrary.prototype.getFunction = function getFunction(name, signature) {
   return wrapFFIFunction(raw, this);
 };
 
+DynamicLibrary.prototype.getFunctionFromPointer = function getFunctionFromPointer(pointer, signature) {
+  const raw = FunctionPrototypeCall(rawGetFunctionFromPointer, this, pointer, signature);
+  return wrapFFIFunction(raw, this);
+};
+
 DynamicLibrary.prototype.getFunctions = function getFunctions(definitions) {
   const raw = definitions === undefined ?
     FunctionPrototypeCall(rawGetFunctions, this) :

src/node_ffi.cc

@@ -90,6 +90,14 @@ void DynamicLibrary::MemoryInfo(MemoryTracker* tracker) const {
           sizeof(decltype(function_wrappers_)::value_type),
       "std::unordered_map<std::string, v8::Global<v8::Function>>");
 
+  tracker->TrackFieldWithSize(
+      "pointer_functions",
+      pointer_functions_ == nullptr
+          ? 0
+          : sizeof(std::unordered_set<FFIFunction*>) +
+                pointer_functions_->size() * sizeof(FFIFunction*),
+      "std::unordered_set<FFIFunction*>");
+
   // FFIFunctionInfo instances and their sb_backing ArrayBuffers are
   // owned by V8 function wrappers and reachable only via weak references,
   // so they are deliberately not counted here.
@@ -101,6 +109,14 @@ void DynamicLibrary::Close() {
     fn->ptr = nullptr;
   }
 
+  if (pointer_functions_ != nullptr) {
+    for (FFIFunction* fn : *pointer_functions_) {
+      fn->closed = true;
+      fn->ptr = nullptr;
+    }
+    pointer_functions_->clear();
+  }
+
   // Closing the library invalidates all registered callbacks. Node.js does not
   // track or revoke callback pointers that have already been handed to native
   // code. If native code calls a callback pointer after `close()` or
@@ -142,7 +158,10 @@ Maybe<void*> DynamicLibrary::ResolveSymbol(Environment* env,
 }
 
 Maybe<DynamicLibrary::PreparedFunction> DynamicLibrary::PrepareFunction(
-    Environment* env, const std::string& name, Local<Object> signature) {
+    Environment* env,
+    const std::string& name,
+    Local<Object> signature,
+    void* ptr) {
   std::shared_ptr<FFIFunction> fn;
   FunctionSignature parsed;
 
@@ -151,22 +170,22 @@ Maybe<DynamicLibrary::PreparedFunction> DynamicLibrary::PrepareFunction(
   }
   // Look up the cache only after parsing: the signature's getters run user
   // code that may close the library, which clears `functions_`.
-  auto existing = functions_.find(name);
+  const bool from_pointer = ptr != nullptr;
+  auto existing = from_pointer ? functions_.end() : functions_.find(name);
   auto [return_type, args, return_type_name, arg_type_names] =
       std::move(parsed);
 
   bool should_cache_symbol = false;
   bool should_cache_function = false;
 
   if (existing == functions_.end()) {
-    void* ptr;
-
-    if (!ResolveSymbol(env, name).To(&ptr)) {
-      return {};
+    if (!from_pointer) {
+      if (!ResolveSymbol(env, name).To(&ptr)) {
+        return {};
+      }
+      should_cache_symbol = symbols_.find(name) == symbols_.end();
     }
 
-    should_cache_symbol = symbols_.find(name) == symbols_.end();
-
     fn = std::make_shared<FFIFunction>();
     fn->ptr = ptr;
     fn->args = std::move(args);
@@ -205,7 +224,7 @@ Maybe<DynamicLibrary::PreparedFunction> DynamicLibrary::PrepareFunction(
     }
 #endif
 
-    should_cache_function = true;
+    should_cache_function = !from_pointer;
   } else {
     fn = existing->second;
 
@@ -267,7 +286,6 @@ MaybeLocal<Function> DynamicLibrary::CreateFunction(
     const std::string& name,
     const std::shared_ptr<FFIFunction>& fn) {
   Isolate* isolate = env->isolate();
-  Local<Context> context = env->context();
 
   // Creating a callable emits a trampoline, allocates an FFIFunctionInfo, and
   // on the SharedBuffer path allocates an ArrayBuffer, so reuse the one already
@@ -282,17 +300,38 @@ MaybeLocal<Function> DynamicLibrary::CreateFunction(
     function_wrappers_.erase(cached);
   }
 
+  Local<Function> ret;
+  if (!BuildFunction(env, name, fn, true).ToLocal(&ret)) {
+    return {};
+  }
+  function_wrappers_.emplace(name, Global<Function>(isolate, ret))
+      .first->second.SetWeak();
+  return ret;
+}
+
+MaybeLocal<Function> DynamicLibrary::BuildFunction(
+    Environment* env,
+    const std::string& name,
+    const std::shared_ptr<FFIFunction>& fn,
+    bool optimize) {
+  Isolate* isolate = env->isolate();
+  Local<Context> context = env->context();
   auto info = FFIFunctionInfo::Create(env, fn, this);
+  if (!info) {
+    return {};
+  }
 
   DCHECK_EQ(fn->args.size(), fn->arg_type_names.size());
 
   // Try the generated Fast API path first. If metadata creation rejects the
   // signature, fall back to SharedBuffer for supported scalar shapes, then to
   // the generic libffi invoker.
-  std::shared_ptr<FFIFunction> fast_fn = CloneWithRawPointerArgNames(fn);
-  info->fast_metadata = CreateFastFFIMetadata(*fast_fn, &fn->closed, isolate);
+  if (optimize) {
+    std::shared_ptr<FFIFunction> fast_fn = CloneWithRawPointerArgNames(fn);
+    info->fast_metadata = CreateFastFFIMetadata(*fast_fn, &fn->closed, isolate);
+  }
   bool use_fast_api = info->fast_metadata != nullptr;
-  bool use_sb = !use_fast_api && IsSBEligibleSignature(*fn);
+  bool use_sb = optimize && !use_fast_api && IsSBEligibleSignature(*fn);
   bool has_ptr_args = use_sb && SignatureHasPointerArgs(*fn);
   // Signatures that need JS-side conversion or validation use a wrapper, as
   // do all fast signatures on platforms without a native library guard.
@@ -485,14 +524,6 @@ MaybeLocal<Function> DynamicLibrary::CreateFunction(
     }
   }
 
-  // A strong handle would root the callable, which holds the library object
-  // through FFIFunctionInfo, so neither could ever be collected. Weaken the
-  // stored handle instead, so the cache lasts exactly as long as user code
-  // keeps a reference. SetWeak() runs after the move into the map because
-  // moving a handle relocates the underlying slot.
-  function_wrappers_.emplace(name, Global<Function>(isolate, ret))
-      .first->second.SetWeak();
-
   return ret;
 }
 
@@ -607,6 +638,7 @@ void DynamicLibrary::InvokeFunction(const FunctionCallbackInfo<Value>& args) {
   std::vector<uint64_t> values(expected_args, 0);
   std::vector<void*> ffi_args(expected_args, nullptr);
   std::vector<std::string> strings;
+  strings.reserve(expected_args);
 
   for (unsigned int i = 0; i < expected_args; i++) {
     FFIArgumentCategory res;
@@ -861,6 +893,68 @@ void DynamicLibrary::GetFunction(const FunctionCallbackInfo<Value>& args) {
   args.GetReturnValue().Set(ret);
 }
 
+void DynamicLibrary::GetFunctionFromPointer(
+    const FunctionCallbackInfo<Value>& args) {
+  Environment* env = Environment::GetCurrent(args);
+  THROW_IF_INSUFFICIENT_PERMISSIONS(env, permission::PermissionScope::kFFI, "");
+
+  if (args.Length() < 1 || !args[0]->IsBigInt()) {
+    THROW_ERR_INVALID_ARG_TYPE(env, "Function pointer must be a bigint");
+    return;
+  }
+  bool lossless;
+  uint64_t address = args[0].As<BigInt>()->Uint64Value(&lossless);
+  if (!lossless || address == 0 ||
+      address > static_cast<uint64_t>(
+                    std::numeric_limits<uintptr_t>::max())) {
+    THROW_ERR_INVALID_ARG_VALUE(env, "Invalid function pointer");
+    return;
+  }
+  if (args.Length() < 2 || !args[1]->IsObject() || args[1]->IsArray()) {
+    THROW_ERR_INVALID_ARG_TYPE(env, "Function signature must be an object");
+    return;
+  }
+
+  DynamicLibrary* lib = Unwrap<DynamicLibrary>(args.This());
+  if (lib->is_closed()) {
+    THROW_ERR_FFI_LIBRARY_CLOSED(env);
+    return;
+  }
+  Local<Object> signature = args[1].As<Object>();
+  PreparedFunction prepared;
+  void* ptr = reinterpret_cast<void*>(static_cast<uintptr_t>(address));
+  if (!lib->PrepareFunction(env, "<pointer>", signature, ptr).To(&prepared)) {
+    return;
+  }
+  THROW_IF_INSUFFICIENT_PERMISSIONS(env, permission::PermissionScope::kFFI, "");
+  if (lib->is_closed()) {
+    THROW_ERR_FFI_LIBRARY_CLOSED(env);
+    return;
+  }
+
+  auto fn = std::move(prepared.fn);
+  if (lib->pointer_functions_ == nullptr) {
+    lib->pointer_functions_ =
+        std::make_shared<std::unordered_set<FFIFunction*>>();
+  }
+  fn->pointer_registry = lib->pointer_functions_;
+  fn->closed = true;
+  lib->pointer_functions_->insert(fn.get());
+  Local<Function> ret;
+  if (!lib->BuildFunction(env, "<pointer>", fn, false).ToLocal(&ret)) {
+    lib->pointer_functions_->erase(fn.get());
+    fn->ptr = nullptr;
+    return;
+  }
+  THROW_IF_INSUFFICIENT_PERMISSIONS(env, permission::PermissionScope::kFFI, "");
+  if (lib->is_closed()) {
+    THROW_ERR_FFI_LIBRARY_CLOSED(env);
+    return;
+  }
+  fn->closed = false;
+  args.GetReturnValue().Set(ret);
+}
+
 void DynamicLibrary::GetFunctions(const FunctionCallbackInfo<Value>& args) {
   Environment* env = Environment::GetCurrent(args);
   Isolate* isolate = env->isolate();
@@ -1324,6 +1418,10 @@ Local<FunctionTemplate> DynamicLibrary::GetConstructorTemplate(
     SetProtoMethod(isolate, tmpl, "close", DynamicLibrary::Close);
     SetProtoDispose(isolate, tmpl, DynamicLibrary::Close);
     SetProtoMethod(isolate, tmpl, "getFunction", DynamicLibrary::GetFunction);
+    SetProtoMethod(isolate,
+             tmpl,
+             "getFunctionFromPointer",
+             DynamicLibrary::GetFunctionFromPointer);
     SetProtoMethod(isolate, tmpl, "getFunctions", DynamicLibrary::GetFunctions);
     SetProtoMethod(isolate, tmpl, "getSymbol", DynamicLibrary::GetSymbol);
     SetProtoMethod(isolate, tmpl, "getSymbols", DynamicLibrary::GetSymbols);

src/node_ffi.h

@@ -12,6 +12,7 @@
 #include <string>
 #include <thread>
 #include <unordered_map>
+#include <unordered_set>
 #include <vector>
 
 // libffi only accelerates reusable call plans on x86-64 System V. Other
@@ -29,12 +30,18 @@ struct FFIFunction;
 
 struct FFIFunction {
   FFIFunction() = default;
+  ~FFIFunction() {
+    if (auto registry = pointer_registry.lock()) {
+      registry->erase(this);
+    }
+  }
   FFIFunction(const FFIFunction&) = delete;
   FFIFunction& operator=(const FFIFunction&) = delete;
   FFIFunction(FFIFunction&&) = delete;
   FFIFunction& operator=(FFIFunction&&) = delete;
 
   bool closed = false;
+  std::weak_ptr<std::unordered_set<FFIFunction*>> pointer_registry;
 
   void* ptr = nullptr;
   ffi_cif cif = {};
@@ -133,6 +140,8 @@ class DynamicLibrary : public BaseObject {
 
   static void GetPath(const v8::FunctionCallbackInfo<v8::Value>& args);
   static void GetFunction(const v8::FunctionCallbackInfo<v8::Value>& args);
+  static void GetFunctionFromPointer(
+      const v8::FunctionCallbackInfo<v8::Value>& args);
   static void GetFunctions(const v8::FunctionCallbackInfo<v8::Value>& args);
   static void GetSymbol(const v8::FunctionCallbackInfo<v8::Value>& args);
   static void GetSymbols(const v8::FunctionCallbackInfo<v8::Value>& args);
@@ -156,11 +165,17 @@ class DynamicLibrary : public BaseObject {
   };
   v8::Maybe<PreparedFunction> PrepareFunction(Environment* env,
                                               const std::string& name,
-                                              v8::Local<v8::Object> signature);
+                                              v8::Local<v8::Object> signature,
+                                              void* ptr = nullptr);
   v8::MaybeLocal<v8::Function> CreateFunction(
       Environment* env,
       const std::string& name,
       const std::shared_ptr<FFIFunction>& fn);
+  v8::MaybeLocal<v8::Function> BuildFunction(
+      Environment* env,
+      const std::string& name,
+      const std::shared_ptr<FFIFunction>& fn,
+      bool optimize);
   static void CleanupFunctionInfo(
       const v8::WeakCallbackInfo<FFIFunctionInfo>& data);
   bool is_closed() const;
@@ -175,6 +190,7 @@ class DynamicLibrary : public BaseObject {
   // which keeps the map from rooting the library through the wrapper's
   // FFIFunctionInfo.
   std::unordered_map<std::string, v8::Global<v8::Function>> function_wrappers_;
+  std::shared_ptr<std::unordered_set<FFIFunction*>> pointer_functions_;
   std::unordered_map<void*, std::unique_ptr<FFICallback>> callbacks_;
 };