napi_create_external_buffer - what should happen when length is zero, but with a valid pointer?

[btsimonh]

Hi all,

I'm trying to understand a difference between node 16/18/20 and node 22.
Specifically, node-ffi-napi uses 0 length buffers to represent function pointers in it's tests.

16/18/20 fail these tests, where napi_create_external_buffer(env, ptr, 0, NULL, NULL, &val) fills val with a null pointer, when ptr is valid.
22 passes the tests, and val contains a valid pointer to ptr, and a length of zero.
I assume this used to pass in node version up to 12 at least...

If I instead call with napi_create_external_buffer(env, ptr, 8, NULL, NULL, &val), tests pass on node 20 (not tried 16 & 18 yet), and the buffer returned has a valid pointer, but has a length of 8.

I'm finding it very difficult to locate a change in the NodeJS sources.

The ACTUAL code in the tests is

template<typename T>
inline Value WrapPointer(Env env, T* ptr, size_t length = 8) {
  if (ptr == nullptr)
    length = 0;
  return Buffer<char>::New(env,
                           reinterpret_cast<char*>(ptr),
                           length,
                           [](Env,char*){});
}

but I modified it to use napi_create_external_buffer directly to check one level down, and behaviour is the same in both cases.

So; what is the expected behaviour when passing a valid pointer, and 0 in the length parameter?
In terms of making the tests work for 16/18/20, should I just pass 8 as the length, and can anyone think of a reason this may be bad?

br,
Simon

[Pleo2]

I would not use a zero-length external Buffer as an opaque pointer carrier.

The Node-API contract defines length as the number of bytes in the input/new Buffer and data as its backing storage. With length == 0, there are no addressable bytes. The API does not promise that retrieving the data pointer from an empty Buffer preserves the exact non-null pointer supplied by the addon, so relying on that identity is not portable across Node/V8 versions.

Passing 8 only makes the Buffer contract truthful if ptr points to at least 8 bytes of live, readable storage that JavaScript is allowed to expose. A function address is not such a byte buffer. Presenting the first 8 bytes at a function address as Buffer storage risks invalid memory access, exposes executable memory, assumes a pointer width, and mixes data-pointer and function-pointer representations that C++ does not make universally interchangeable.

For an opaque native handle, use napi_create_external / napi_get_value_external (or Napi::External<T>). For a function pointer, the portable pattern is to allocate a holder object and externalize a pointer to that object:

using Callback = void (*)(void);
struct CallbackHolder { Callback fn; };

// Allocate CallbackHolder, pass CallbackHolder* to napi_create_external,
// and delete it from the napi_finalize callback.

Native code can retrieve the holder and call holder->fn; JavaScript never treats the function address as bytes. If the FFI library specifically requires a Buffer ABI, allocate real owned storage of sizeof(Callback), copy the pointer representation into that storage, and attach a finalizer. Do not point the Buffer at the function body, and do not hard-code 8.

The observed Node 16/18/20 versus 22 difference should therefore be treated as an implementation detail in handling empty backing stores, not as a stable capability to test for.

Node-API documents the two intended contracts here:

• External values: https://nodejs.org/api/n-api.html#napi_create_external
• External Buffers: https://nodejs.org/api/n-api.html#napi_create_external_buffer