koffi 2.16.0 → 2.16.1

package/CHANGELOG.md

@@ -7,6 +7,13 @@
 
 ### Koffi 2.16
 
+#### Koffi 2.16.1
+
+*Released on 2026-04-17*
+
+- Fix possible stack check crash when relaying callbacks on Windows
+- Improve exception handling inside callbacks
+
 #### Koffi 2.16.0
 
 *Released on 2026-04-14*
@@ -14,7 +21,7 @@
 - Support buffers and typed arrays in `koffi.address()`
 - Put x86 SEH record at the top of stack frame
 - Optimize Koffi binaries produced by GCC (with `-fno-semantic-interposition`)
-- Fix nonsensical addresses in Koffi call dumps (when using DUMP_CALLS=1 environement variable)
+- Fix nonsensical addresses in Koffi call dumps (when using DUMP_CALLS=1 environment variable)
 
 - Reduce Koffi package size even more:
   * Replace table of callback trampoline pointers with simple offset computation

package/index.js

@@ -398,7 +398,7 @@ var require_package = __commonJS({
   "../../bin/Koffi/package/src/koffi/package.json"(exports2, module2) {
     module2.exports = {
       name: "koffi",
-      version: "2.16.0",
+      version: "2.16.1",
       description: "Fast and simple C FFI (foreign function interface) for Node.js",
       keywords: [
         "foreign",

package/indirect.js

@@ -398,7 +398,7 @@ var require_package = __commonJS({
   "../../bin/Koffi/package/src/koffi/package.json"(exports2, module2) {
     module2.exports = {
       name: "koffi",
-      version: "2.16.0",
+      version: "2.16.1",
       description: "Fast and simple C FFI (foreign function interface) for Node.js",
       keywords: [
         "foreign",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "koffi",
-    "version": "2.16.0",
+    "version": "2.16.1",
     "description": "Fast and simple C FFI (foreign function interface) for Node.js",
     "keywords": [
         "foreign",

package/src/koffi/src/abi_arm32.cc

@@ -544,15 +544,12 @@ Napi::Value CallData::Complete(const FunctionInfo *func)
 
 void CallData::Relay(Size idx, uint8_t *sp)
 {
+    const TrampolineInfo &trampoline = shared.trampolines[idx];
+
     uint8_t *own_sp = sp;
     uint8_t *caller_sp = sp + 128;
     BackRegisters *out_reg = (BackRegisters *)(sp + 80);
 
-    if (env.IsExceptionPending()) [[unlikely]]
-        return;
-
-    const TrampolineInfo &trampoline = shared.trampolines[idx];
-
     const FunctionInfo *proto = trampoline.proto;
     Napi::Function func = trampoline.func.Value();
 
@@ -565,11 +562,6 @@ void CallData::Relay(Size idx, uint8_t *sp)
 
     K_DEFER_N(err_guard) { memset(out_reg, 0, K_SIZE(*out_reg)); };
 
-    if (trampoline.generation >= 0 && trampoline.generation != (int32_t)mem->generation) [[unlikely]] {
-        ThrowError<Napi::Error>(env, "Cannot use non-registered callback beyond FFI call");
-        return;
-    }
-
     LocalArray<napi_value, MaxParameters + 1> arguments;
 
     arguments.Append(!trampoline.recv.IsEmpty() ? trampoline.recv.Value() : env.Undefined());

package/src/koffi/src/abi_arm64.cc

@@ -693,33 +693,12 @@ Napi::Value CallData::Complete(const FunctionInfo *func)
 
 void CallData::Relay(Size idx, uint8_t *sp)
 {
+    const TrampolineInfo &trampoline = shared.trampolines[idx];
+
     uint8_t *own_sp = sp;
     uint8_t *caller_sp = sp + 208;
     BackRegisters *out_reg = (BackRegisters *)(sp + 136);
 
-    if (env.IsExceptionPending()) [[unlikely]]
-        return;
-
-#if defined(_WIN32)
-    TEB *teb = GetTEB();
-
-    // Restore previous stack limits at the end
-    K_DEFER_C(base = teb->StackBase,
-               limit = teb->StackLimit,
-               dealloc = teb->DeallocationStack) {
-        teb->StackBase = base;
-        teb->StackLimit = limit;
-        teb->DeallocationStack = dealloc;
-    };
-
-    // Adjust stack limits so SEH works correctly
-    teb->StackBase = instance->main_stack_max;
-    teb->StackLimit = instance->main_stack_min;
-    teb->DeallocationStack = instance->main_stack_min;
-#endif
-
-    const TrampolineInfo &trampoline = shared.trampolines[idx];
-
     const FunctionInfo *proto = trampoline.proto;
     Napi::Function func = trampoline.func.Value();
 
@@ -731,11 +710,6 @@ void CallData::Relay(Size idx, uint8_t *sp)
 
     K_DEFER_N(err_guard) { memset(out_reg, 0, K_SIZE(*out_reg)); };
 
-    if (trampoline.generation >= 0 && trampoline.generation != (int32_t)mem->generation) [[unlikely]] {
-        ThrowError<Napi::Error>(env, "Cannot use non-registered callback beyond FFI call");
-        return;
-    }
-
     LocalArray<napi_value, MaxParameters + 1> arguments;
 
     arguments.Append(!trampoline.recv.IsEmpty() ? trampoline.recv.Value() : env.Undefined());

package/src/koffi/src/abi_loong64_asm.S

@@ -141,7 +141,7 @@ ForwardCallXDD:
 .macro trampoline id
     li.d $t0, \id
     b RelayTrampoline
-    .align 4
+    .balign 16
 .endm
 
 RelayTrampoline:
@@ -197,7 +197,7 @@ SwitchAndRelay:
     addi.d $sp, $sp, 16
     jr $ra
 
-.align 4
+.balign 16
 #include "gnu.inc"
 
 TrampolineEnd:

package/src/koffi/src/abi_riscv64.cc

@@ -485,15 +485,12 @@ Napi::Value CallData::Complete(const FunctionInfo *func)
 
 void CallData::Relay(Size idx, uint8_t *sp)
 {
+    const TrampolineInfo &trampoline = shared.trampolines[idx];
+
     uint8_t *own_sp = sp;
     uint8_t *caller_sp = sp + 168;
     BackRegisters *out_reg = (BackRegisters *)(sp + 128);
 
-    if (env.IsExceptionPending()) [[unlikely]]
-        return;
-
-    const TrampolineInfo &trampoline = shared.trampolines[idx];
-
     const FunctionInfo *proto = trampoline.proto;
     Napi::Function func = trampoline.func.Value();
 
@@ -506,11 +503,6 @@ void CallData::Relay(Size idx, uint8_t *sp)
 
     K_DEFER_N(err_guard) { memset(out_reg, 0, K_SIZE(*out_reg)); };
 
-    if (trampoline.generation >= 0 && trampoline.generation != (int32_t)mem->generation) [[unlikely]] {
-        ThrowError<Napi::Error>(env, "Cannot use non-registered callback beyond FFI call");
-        return;
-    }
-
     LocalArray<napi_value, MaxParameters + 1> arguments;
 
     arguments.Append(!trampoline.recv.IsEmpty() ? trampoline.recv.Value() : env.Undefined());

package/src/koffi/src/abi_riscv64_asm.S

@@ -141,7 +141,7 @@ ForwardCallXDD:
 .macro trampoline id
     li t0, \id
     j RelayTrampoline
-    .align 4
+    .balign 16
 .endm
 
 RelayTrampoline:
@@ -196,7 +196,7 @@ SwitchAndRelay:
     addi sp, sp, 16
     ret
 
-.align 4
+.balign 16
 #include "gnu.inc"
 
 TrampolineEnd:

package/src/koffi/src/abi_x64_sysv.cc

@@ -521,15 +521,12 @@ Napi::Value CallData::Complete(const FunctionInfo *func)
 
 void CallData::Relay(Size idx, uint8_t *sp)
 {
+    const TrampolineInfo &trampoline = shared.trampolines[idx];
+
     uint8_t *own_sp = sp;
     uint8_t *caller_sp = sp + 160;
     BackRegisters *out_reg = (BackRegisters *)(sp + 112);
 
-    if (env.IsExceptionPending()) [[unlikely]]
-        return;
-
-    const TrampolineInfo &trampoline = shared.trampolines[idx];
-
     const FunctionInfo *proto = trampoline.proto;
     Napi::Function func = trampoline.func.Value();
 
@@ -542,11 +539,6 @@ void CallData::Relay(Size idx, uint8_t *sp)
 
     K_DEFER_N(err_guard) { memset(out_reg, 0, K_SIZE(*out_reg)); };
 
-    if (trampoline.generation >= 0 && trampoline.generation != (int32_t)mem->generation) [[unlikely]] {
-        ThrowError<Napi::Error>(env, "Cannot use non-registered callback beyond FFI call");
-        return;
-    }
-
     LocalArray<napi_value, MaxParameters + 1> arguments;
 
     arguments.Append(!trampoline.recv.IsEmpty() ? trampoline.recv.Value() : env.Undefined());

package/src/koffi/src/abi_x64_win.cc

@@ -327,31 +327,12 @@ Napi::Value CallData::Complete(const FunctionInfo *func)
 
 void CallData::Relay(Size idx, uint8_t *sp)
 {
+    const TrampolineInfo &trampoline = shared.trampolines[idx];
+
     uint8_t *own_sp = sp;
     uint8_t *caller_sp = sp + 128;
     BackRegisters *out_reg = (BackRegisters *)(sp + 64);
 
-    if (env.IsExceptionPending()) [[unlikely]]
-        return;
-
-    TEB *teb = GetTEB();
-
-    // Restore previous stack limits at the end
-    K_DEFER_C(base = teb->StackBase,
-               limit = teb->StackLimit,
-               dealloc = teb->DeallocationStack) {
-        teb->StackBase = base;
-        teb->StackLimit = limit;
-        teb->DeallocationStack = dealloc;
-    };
-
-    // Adjust stack limits so SEH works correctly
-    teb->StackBase = instance->main_stack_max;
-    teb->StackLimit = instance->main_stack_min;
-    teb->DeallocationStack = instance->main_stack_min;
-
-    const TrampolineInfo &trampoline = shared.trampolines[idx];
-
     const FunctionInfo *proto = trampoline.proto;
     Napi::Function func = trampoline.func.Value();
 
@@ -363,11 +344,6 @@ void CallData::Relay(Size idx, uint8_t *sp)
 
     K_DEFER_N(err_guard) { memset(out_reg, 0, K_SIZE(*out_reg)); };
 
-    if (trampoline.generation >= 0 && trampoline.generation != (int32_t)mem->generation) [[unlikely]] {
-        ThrowError<Napi::Error>(env, "Cannot use non-registered callback beyond FFI call");
-        return;
-    }
-
     LocalArray<napi_value, MaxParameters + 1> arguments;
 
     arguments.Append(!trampoline.recv.IsEmpty() ? trampoline.recv.Value() : env.Undefined());

package/src/koffi/src/abi_x64_win_asm.S

@@ -152,12 +152,12 @@ SwitchAndRelay:
     pop %rbp
     ret
 
-.align 4
+.balign 16
 FindTrampolineStart:
     leaq 16(%rip), %rax
     andq $0xFFFFFFFFFFFFFFF0, %rax
     ret
-.align 4
+.balign 16
 
 #include "gnu.inc"
 

package/src/koffi/src/abi_x86.cc

@@ -441,32 +441,11 @@ Napi::Value CallData::Complete(const FunctionInfo *func)
 
 void CallData::Relay(Size idx, uint8_t *sp)
 {
+    const TrampolineInfo &trampoline = shared.trampolines[idx];
+
     uint8_t *caller_sp = sp + 48;
     BackRegisters *out_reg = (BackRegisters *)(sp + 16);
 
-    if (env.IsExceptionPending()) [[unlikely]]
-        return;
-
-#if defined(_WIN32)
-    TEB *teb = GetTEB();
-
-    // Restore previous stack limits at the end
-    K_DEFER_C(base = teb->StackBase,
-               limit = teb->StackLimit,
-               dealloc = teb->DeallocationStack) {
-        teb->StackBase = base;
-        teb->StackLimit = limit;
-        teb->DeallocationStack = dealloc;
-    };
-
-    // Adjust stack limits so SEH works correctly
-    teb->StackBase = instance->main_stack_max;
-    teb->StackLimit = instance->main_stack_min;
-    teb->DeallocationStack = instance->main_stack_min;
-#endif
-
-    const TrampolineInfo &trampoline = shared.trampolines[idx];
-
     const FunctionInfo *proto = trampoline.proto;
     Napi::Function func = trampoline.func.Value();
 
@@ -492,11 +471,6 @@ void CallData::Relay(Size idx, uint8_t *sp)
         out_reg->ret_pop = pop;
     };
 
-    if (trampoline.generation >= 0 && trampoline.generation != (int32_t)mem->generation) [[unlikely]] {
-        ThrowError<Napi::Error>(env, "Cannot use non-registered callback beyond FFI call");
-        return;
-    }
-
     LocalArray<napi_value, MaxParameters + 1> arguments;
 
     arguments.Append(!trampoline.recv.IsEmpty() ? trampoline.recv.Value() : env.Undefined());

package/src/koffi/src/abi_x86_asm.S

@@ -109,6 +109,8 @@ RelayTrampoline:
     .cfi_def_cfa esp, 48
     movl %eax, 0(%esp)
     movl %esp, 4(%esp)
+    movl $0, 32(%esp)
+    movl $0, 36(%esp)
     call GetEIP
     addl $_GLOBAL_OFFSET_TABLE_, %eax
     call *RelayCallback@GOT(%eax)
@@ -172,13 +174,13 @@ SwitchAndRelay:
     ret
     .cfi_endproc
 
-.align 4
+.balign 16
 FindTrampolineStart:
     call GetEIP
     addl $16, %eax
     andl $0xFFFFFFF0, %eax
     ret
-.align 4
+.balign 16
 
 #include "gnu.inc"
 

package/src/koffi/src/abi_x86_asm.asm

@@ -101,6 +101,8 @@ RelayTrampoline proc
     sub esp, 44
     mov dword ptr [esp+0], eax
     mov dword ptr [esp+4], esp
+    mov dword ptr [esp+32], 0
+    mov dword ptr [esp+36], 0
     call RelayCallback
     mov edx, dword ptr [esp+44]
     mov ecx, dword ptr [esp+36]

package/src/koffi/src/call.cc

@@ -31,7 +31,6 @@ CallData::CallData(Napi::Env env, InstanceData *instance, InstanceMemory *mem)
     : env(env), instance(instance),
       mem(mem), old_stack_mem(mem->stack), old_heap_mem(mem->heap)
 {
-    mem->generation += !mem->depth;
     mem->depth++;
 
     K_ASSERT(AlignUp(mem->stack.ptr, 16) == mem->stack.ptr);
@@ -64,9 +63,9 @@ void CallData::Dispose()
             K_ASSERT(trampoline->instance == instance);
             K_ASSERT(!trampoline->func.IsEmpty());
 
-            trampoline->instance = nullptr;
             trampoline->func.Reset();
             trampoline->recv.Reset();
+            trampoline->used = false;
 
             shared.available.Append(idx);
         }
@@ -1142,7 +1141,7 @@ void *CallData::ReserveTrampoline(const FunctionInfo *proto, Napi::Function func
     trampoline->proto = proto;
     trampoline->func.Reset(func, 1);
     trampoline->recv.Reset();
-    trampoline->generation = (int32_t)mem->generation;
+    trampoline->used = true;
 
     void *ptr = GetTrampoline(idx);
 

package/src/koffi/src/ffi.cc

@@ -1728,10 +1728,6 @@ extern "C" void RelayCallback(Size idx, uint8_t *sp)
         return;
     }
 
-    // Avoid triggering the "use callback beyond FFI" check
-    K_DEFER_C(generation = trampoline->generation) { trampoline->generation = generation; };
-    trampoline->generation = -1;
-
     if (std::this_thread::get_id() == instance->main_thread_id) {
         CallData call(env, instance, mem);
 
@@ -1745,6 +1741,35 @@ extern "C" void RelayCallback(Size idx, uint8_t *sp)
 
 extern "C" void RelayDirect(CallData *call, Size idx, uint8_t *sp)
 {
+    TrampolineInfo *trampoline = &shared.trampolines[idx];
+    Napi::Env env = trampoline->func.Env();
+
+#if defined(_WIN32)
+    TEB *teb = GetTEB();
+    InstanceData *instance = trampoline->instance;
+
+    // Restore previous stack limits at the end
+    K_DEFER_C(base = teb->StackBase,
+              limit = teb->StackLimit,
+              dealloc = teb->DeallocationStack) {
+        teb->StackBase = base;
+        teb->StackLimit = limit;
+        teb->DeallocationStack = dealloc;
+    };
+
+    // Adjust stack limits so SEH works correctly
+    teb->StackBase = instance->main_stack_max;
+    teb->StackLimit = instance->main_stack_min;
+    teb->DeallocationStack = instance->main_stack_min;
+#endif
+
+    if (env.IsExceptionPending()) [[unlikely]]
+        return;
+    if (!trampoline->used) [[unlikely]] {
+        ThrowError<Napi::Error>(env, "Cannot use non-registered callback beyond FFI call");
+        return;
+    }
+
     Napi::HandleScope scope(call->env);
     call->Relay(idx, sp);
 }
@@ -2020,7 +2045,7 @@ static Napi::Value RegisterCallback(const Napi::CallbackInfo &info)
     } else {
         trampoline->recv.Reset();
     }
-    trampoline->generation = -1;
+    trampoline->used = true;
 
     void *ptr = GetTrampoline(idx);
 
@@ -2072,6 +2097,7 @@ static Napi::Value UnregisterCallback(const Napi::CallbackInfo &info)
 
         trampoline->func.Reset();
         trampoline->recv.Reset();
+        trampoline->used = false;
 
         shared.available.Append(idx);
     }
@@ -2665,6 +2691,7 @@ InstanceData::~InstanceData()
                 trampoline->instance = nullptr;
                 trampoline->func.Reset();
                 trampoline->recv.Reset();
+                trampoline->used = false;
             }
         }
     }

package/src/koffi/src/ffi.hh

@@ -249,8 +249,6 @@ struct InstanceMemory {
     Span<uint8_t> stack0;
     Span<uint8_t> heap;
 
-    uint16_t generation; // Can wrap without risk
-
     bool busy;
     bool temporary;
     int depth;
@@ -322,7 +320,7 @@ struct TrampolineInfo {
     Napi::FunctionReference func;
     Napi::Reference<Napi::Value> recv;
 
-    int32_t generation;
+    bool used;
 };
 
 struct SharedData {