koffi 2.14.0 → 2.15.0

package/CHANGELOG.md

@@ -5,8 +5,34 @@
 
 ## Koffi 2
 
+### Koffi 2.15
+
+#### Koffi 2.15.0
+
+*Released on 2025-12-21*
+
+- Fix parsing error with some parameter types that could lead to weird crashes (regression introduced in Koffi 2.14)
+- Fix rare data race in Koffi memory allocation/release
+- Increase default and maximum length of async call queue
+- Decrease default stack and heap size used for async calls
+- Add API to poll sockets with Node libuv event loop ([@mkicherer](https://github.com/mkicherer))
+- Fix erroneous UTF-32 range checks when decoding UTF-32 buffers ([@VastBlast](https://github.com/VastBlast))
+- Fix possible overflow when encoding malformed UTF-16 to UTF-32
+- Throw error when using negative offset in encode and decode functions ([@VastBlast](https://github.com/VastBlast))
+- Use proper Unicode replacement char in UTF-32 routines
+
+> [!NOTE]
+> The socket polling/libuv integration API is not yet documented and might change in subsequent releases. You've been warned!
+
 ### Koffi 2.14
 
+#### Koffi 2.14.1
+
+*Released on 2025-09-13*
+
+- Recompile Linux (musl) ARM64 prebuild with Alpine 3.20 (instead of Alpine edge)
+- Clean up redundant code paths for handling string arguments
+
 #### Koffi 2.14.0
 
 *Released on 2025-08-17*
@@ -980,7 +1006,6 @@ This entry documents changes since version 1.1.0.
 
 The following features and improvements are planned, not necessarily in that order:
 
-- Port Koffi to Loong64 ISA and ABI
 - Port Koffi to PowerPC (POWER9+) ISA and ABI
 - Optimize passing of structs and arrays (with auto-generated JS)
 - Automate Windows/AArch64 (qemu) and macOS/AArch64 (how? ... thanks Apple) tests

package/README.md

@@ -4,7 +4,7 @@ Koffi is a fast and easy-to-use C FFI module for Node.js, featuring:
 
 * Low-overhead and fast performance (see [benchmarks](https://koffi.dev/benchmarks))
 * Support for primitive and aggregate data types (structs and fixed-size arrays), both by reference (pointer) and by value
-* Javascript functions can be used as C callbacks (since 1.2.0)
+* Javascript functions can be used as C callbacks
 * Well-tested code base for popular OS/architecture combinations
 
 The following combinations of OS and architectures __are officially supported and tested__ at the moment:

package/doc/assets.ini

@@ -1,4 +1,5 @@
 EsbuildPath = ../../vendor/esbuild/native/node_modules/@esbuild
+EsbuildRoot = ../..
 
 [favicon.png]
 Type = Copy
@@ -11,7 +12,7 @@ Ignore = favicon.png *.js *.css
 
 [static/site.min.js]
 Type = Bundle
-Source = ../../src/web/flat/static.js
+Source = ../../lib/web/flat/static.js
 
 [static/highlight.min.js]
 Type = Bundle

package/doc/build.sh

@@ -0,0 +1,9 @@
+#!/bin/bash -e
+
+cd "$(dirname $0)"
+
+../../bootstrap.sh
+../../felix -pFast hodler
+
+mkdir -p ../../bin/Web/koffi.dev
+../../bin/Fast/hodler . -O ../../bin/Web/koffi.dev --gzip

package/doc/pages/404.md

@@ -0,0 +1,17 @@
+*The page you requested does not exist...*
+
+<div class="error">Error 404</div>
+
+<style>
+    main {
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        justify-content: center;
+    }
+    .error {
+        margin: 0.8em;
+        font-size: 4em;
+        font-weight: bold;
+    }
+</style>

package/doc/pages/index.md

@@ -1,16 +1,51 @@
-# Koffi
+# Overview
 
 Koffi is a **fast and easy-to-use C FFI module for Node.js**, featuring:
 
 * Low-overhead and fast performance (see [benchmarks](benchmarks))
 * Support for primitive and aggregate data types (structs and fixed-size arrays), both by reference (pointer) and by value
-* Javascript functions can be used as C callbacks (since 1.2.0)
-* Well-tested code base for [popular OS/architecture combinations](platforms)
+* Javascript functions can be used as C callbacks
+* Well-tested code base for popular OS/architecture combinations
 
-Koffi requires a recent [Node.js](https://nodejs.org/) version with N-API version 8 support, see [this page](platforms) for more information.
+If you like this project, consider supporting me:
+
+<p style="display: flex; gap: 2em; justify-content: center;">
+     <a href="https://buymeacoffee.com/koromix" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-orange.png" alt="Buy Me A Coffee" height="41" width="174" style="border-radius: 12px;"></a>
+</p>
+
+Koffi requires [Node.js](https://nodejs.org/) version 16 or later. Use [NVM](https://github.com/nvm-sh/nvm) to install more recent Node versions on older Linux distributions.
+
+The following combinations of OS and architectures __are officially supported and tested__ at the moment:
+
+ISA / OS           | Windows | Linux (glibc) | Linux (musl) | macOS | FreeBSD | OpenBSD
+------------------ | ------- | ------------- | ------------ | ----- | ------- | -------
+x86 (IA32) [^2]    | ✅       | ✅             | 🟨            | ⬜️    | ✅       | ✅
+x86_64 (AMD64)     | ✅       | ✅             | ✅            | ✅    | ✅       | ✅
+ARM32 LE [^3]      | ⬜️       | ✅             | 🟨            | ⬜️    | 🟨       | 🟨
+ARM64 (AArch64) LE | ✅       | ✅             | ✅            | ✅    | ✅       | 🟨
+RISC-V 64 [^4]     | ⬜️       | ✅             | 🟨            | ⬜️    | 🟨       | 🟨
+LoongArch64        | ⬜️       | ✅             | 🟨            | ⬜️    | 🟨       | 🟨
+
+<div class="legend">✅ Yes | 🟨 Probably | ⬜️ Not applicable</div>
+
+[^2]: The following call conventions are supported for forward calls: cdecl, stdcall, MS fastcall, thiscall. Only cdecl and stdcall can be used for C to JS callbacks.
+[^3]: The prebuilt binary uses the hard float ABI and expects a VFP coprocessor. Build from source to use Koffi with a different ABI (softfp, soft).
+[^4]: The prebuilt binary uses the LP64D (double-precision float) ABI. The LP64 ABI is supported in theory if you build Koffi from source (untested), the LP64F ABI is not supported.
+
+For all fully supported platforms (green check marks), a prebuilt binary is included in the NPM package which means you can install Koffi without a C++ compiler.
+
+# Source code
 
 The source code is available here: https://github.com/Koromix/rygel/ (in the *src/koffi* subdirectory).
 
+> [!NOTE]
+> Most of my projects live in a single repository (or monorepo), which have two killer features for me:
+>
+> - Cross-project refactoring
+> - Simplified dependency management
+>
+> You can find a more detailed rationale here: https://danluu.com/monorepo/
+
 New releases are frequent, look at the [changelog](changelog) for more information.
 
 # License
@@ -18,3 +53,7 @@ New releases are frequent, look at the [changelog](changelog) for more informati
 This program is free software: you can redistribute it and/or modify it under the terms of the **MIT License**.
 
 Find more information here: https://choosealicense.com/licenses/mit/
+
+<style>
+     table td:not(:first-child) { text-align: center; }
+</style>

package/doc/pages/misc.md

@@ -112,21 +112,26 @@ let config = koffi.config();
 console.log(config);
 ```
 
-The same is true for asynchronous calls. When an asynchronous call is made, Koffi will allocate new blocks unless there is an unused (resident) set of blocks still available. Once the asynchronous call is finished, these blocks are freed if there are more than `resident_async_pools` sets of blocks left around.
+The same is true for asynchronous calls. When an asynchronous call is made, Koffi will allocate new blocks unless there is an unused (resident) set of blocks still available. Once the asynchronous call is finished, these blocks are freed if there are more than `resident_async_pools` sets of blocks left around. By default, the preallocated stack and heap blocks are much smaller than for synchronous calls (see [default settings](#default-settings)).
 
-There cannot be more than `max_async_calls` running at the same time.
+> [!CAUTION]
+> The **memory usage can blow up easily** if you increase the size of async memory blocks and many async calls are running or queued at the same time !
+>
+> For example, with 4096 running/queued async calls, a stack size of 256 kiB and a heap size of 512 kiB, the memory usage will reach approximately _4096 * (256 + 512) kiB ≈ 3 GiB_ just for Koffi, even though most of it will be freed once the number of queued calls goes down.
+
+Async calls run on worker threads, the number of which depends on the number of cores in your machine. Additional async calls are queued, up to `max_async_calls` can run and be queued at the same time. If you try to make an async call once the queue if full, an exception will be thrown.
 
 ## Default settings
 
-Setting              | Default | Description
--------------------- | ------- | -----------------------------------------------
-sync_stack_size      | 1 MiB   | Stack size for synchronous calls
-sync_heap_size       | 2 MiB   | Heap size for synchronous calls
-async_stack_size     | 256 kiB | Stack size for asynchronous calls
-async_heap_size      | 512 kiB | Heap size for asynchronous calls
-resident_async_pools | 2       | Number of resident pools for asynchronous calls
-max_async_calls      | 64      | Maximum number of ongoing asynchronous calls
-max_type_size        | 64 MiB  | Maximum size of Koffi types (for arrays and structs)
+Setting              | Default | Maximum | Description
+-------------------- | ------- | ------- | ----------------------------------------------------
+sync_stack_size      | 1 MiB   | 16 MiB  | Stack size for synchronous calls
+sync_heap_size       | 2 MiB   | 16 MiB  | Heap size for synchronous calls
+async_stack_size     | 128 kiB | 16 MiB  | Stack size for asynchronous calls
+async_heap_size      | 128 kiB | 16 MiB  | Heap size for asynchronous calls
+resident_async_pools | 4       | 16      | Number of resident pools for asynchronous calls
+max_async_calls      | 256     | 4096    | Maximum number of queued asynchronous calls
+max_type_size        | 64 MiB  | 512 MiB | Maximum size of Koffi types (for arrays and structs)
 
 # Usage statistics
 

package/doc/pages/platforms.md

@@ -14,25 +14,14 @@ Use [NVM](https://github.com/nvm-sh/nvm) to install more recent Node versions on
 
 The following combinations of OS and architectures __are officially supported and tested__ at the moment:
 
-ISA / OS           | Windows | Linux (glibc) | Linux (musl)
------------------- | ------- | ------------- | ------------
-x86 (IA32) [^1]    | ✅      | ✅            | 🟨
-x86_64 (AMD64)     | ✅      | ✅            | ✅
-ARM32 LE [^2]      | ⬜️      | ✅            | 🟨
-ARM64 (AArch64) LE | ✅      | ✅            | ✅
-RISC-V 64 [^3]     | ⬜️      | ✅            | 🟨
-LoongArch64        | ⬜️      | ✅            | 🟨
-
-<div class="legend">✅ Yes | 🟨 Probably | ⬜️ Not applicable</div>
-
-ISA / OS           | macOS | FreeBSD     | OpenBSD
------------------- | ----- | ----------- | --------
-x86 (IA32) [^1]    | ⬜️    | ✅          | ✅
-x86_64 (AMD64)     | ✅    | ✅          | ✅
-ARM32 LE [^2]      | ⬜️    | 🟨          | 🟨
-ARM64 (AArch64) LE | ✅    | ✅          | 🟨
-RISC-V 64 [^3]     | ⬜️    | 🟨          | 🟨
-LoongArch64        | ⬜️    | 🟨          | 🟨
+ISA / OS           | Windows     | Linux (glibc) | Linux (musl) | macOS       | FreeBSD     | OpenBSD
+------------------ | ----------- | ------------- | ------------ | ----------- | ----------- | --------
+x86 (IA32) [^1]    | ✅ Yes      | ✅ Yes        | 🟨 Probably  | ⬜️ *N/A*    | ✅ Yes      | ✅ Yes
+x86_64 (AMD64)     | ✅ Yes      | ✅ Yes        | ✅ Yes       | ✅ Yes      | ✅ Yes      | ✅ Yes
+ARM32 LE [^2]      | ⬜️ *N/A*    | ✅ Yes        | 🟨 Probably  | ⬜️ *N/A*    | 🟨 Probably | 🟨 Probably
+ARM64 (AArch64) LE | ✅ Yes      | ✅ Yes        | ✅ Yes       | ✅ Yes      | ✅ Yes      | 🟨 Probably
+RISC-V 64 [^3]     | ⬜️ *N/A*    | ✅ Yes        | 🟨 Probably  | ⬜️ *N/A*    | 🟨 Probably | 🟨 Probably
+LoongArch64        | ⬜️ *N/A*    | ✅ Yes        | 🟨 Probably  | ⬜️ *N/A*    | 🟨 Probably | 🟨 Probably
 
 <div class="legend">✅ Yes | 🟨 Probably | ⬜️ Not applicable</div>
 

package/doc/pages.ini

@@ -2,13 +2,6 @@
 Title = Koffi
 Menu = Overview
 Description = Koffi presentation and features
-ToC = Off
-Template = templates/page.html
-
-[pages/platforms.md]
-Title = Requirements | Koffi
-Menu = Documentation / Requirements
-Description = Supported systemd and architectures
 Template = templates/page.html
 
 [pages/start.md]
@@ -87,3 +80,7 @@ Title = Changelog | Koffi
 Menu = Changelog
 Description = List of Koffi versions
 Template = templates/page.html
+
+[pages/404.md]
+Title = Page not found
+Template = templates/page.html

package/doc/static/highlight.js

@@ -1,17 +1,5 @@
-// Copyright (C) 2025  Niels Martignène <niels.martignene@protonmail.com>
-//
-// This program is free software: you can redistribute it and/or modify
-// it under the terms of the GNU General Public License as published by
-// the Free Software Foundation, either version 3 of the License, or
-// (at your option) any later version.
-//
-// This program is distributed in the hope that it will be useful,
-// but WITHOUT ANY WARRANTY; without even the implied warranty of
-// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-// GNU General Public License for more details.
-//
-// You should have received a copy of the GNU General Public License
-// along with this program.  If not, see <https://www.gnu.org/licenses/>.
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2025 Niels Martignène <niels.martignene@protonmail.com>
 
 import * as hljs from '../../../vendor/highlight.js/highlight.js';
 

package/doc/static/koffi.css

@@ -1,19 +1,7 @@
-/* Copyright (C) 2025  Niels Martignène <niels.martignene@protonmail.com>
+/* SPDX-License-Identifier: MIT */
+/* SPDX-FileCopyrightText: 2025 Niels Martignène <niels.martignene@protonmail.com> */
 
-   This program is free software: you can redistribute it and/or modify
-   it under the terms of the GNU General Public License as published by
-   the Free Software Foundation, either version 3 of the License, or
-   (at your option) any later version.
-
-   This program is distributed in the hope that it will be useful,
-   but WITHOUT ANY WARRANTY; without even the implied warranty of
-   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-   GNU General Public License for more details.
-
-   You should have received a copy of the GNU General Public License
-   along with this program.  If not, see <https://www.gnu.org/licenses/>. */
-
-@import url('../../../src/web/flat/flat.css');
+@import url('../../../lib/web/flat/flat.css');
 @import url('../../../vendor/highlight.js/styles/base16/tomorrow.css');
 
 html {

package/doc/static/print.css

@@ -1,17 +1,5 @@
-/* Copyright (C) 2025  Niels Martignène <niels.martignene@protonmail.com>
-
-   This program is free software: you can redistribute it and/or modify
-   it under the terms of the GNU General Public License as published by
-   the Free Software Foundation, either version 3 of the License, or
-   (at your option) any later version.
-
-   This program is distributed in the hope that it will be useful,
-   but WITHOUT ANY WARRANTY; without even the implied warranty of
-   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-   GNU General Public License for more details.
-
-   You should have received a copy of the GNU General Public License
-   along with this program.  If not, see <https://www.gnu.org/licenses/>. */
+/* SPDX-License-Identifier: MIT */
+/* SPDX-FileCopyrightText: 2025 Niels Martignène <niels.martignene@protonmail.com> */
 
 @media print {
     .schema { width: 90%; }

package/index.d.ts

@@ -1,23 +1,5 @@
-// Copyright (C) 2025  Niels Martignène <niels.martignene@protonmail.com>
-//
-// Permission is hereby granted, free of charge, to any person obtaining a copy of
-// this software and associated documentation files (the “Software”), to deal in
-// the Software without restriction, including without limitation the rights to use,
-// copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
-// Software, and to permit persons to whom the Software is furnished to do so,
-// subject to the following conditions:
-//
-// The above copyright notice and this permission notice shall be included in all
-// copies or substantial portions of the Software.
-//
-// THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
-// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
-// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
-// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
-// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-// OTHER DEALINGS IN THE SOFTWARE.
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: 2025 Niels Martignène <niels.martignene@protonmail.com>
 
 type LoadOptions = {
     lazy?: boolean,
@@ -277,7 +259,30 @@ type PrimitiveTypes =
     | 'wchar_t';
 export const types: Record<PrimitiveTypes, IKoffiCType>;
 
-// Internal stuff, don't use!
-export const node: {
-    env: { __brand: 'IKoffiNodeEnv' }
-};
+export interface IKoffiPollOptions {
+    readable?: boolean;
+    writable?: boolean;
+    disconnect?: boolean;
+}
+
+export interface IKoffiPollEvents {
+    readable: boolean;
+    writable: boolean;
+    disconnect: boolean;
+}
+
+export namespace node {
+    export const env: { __brand: 'IKoffiNodeEnv' };
+
+    export class PollHandle {
+        start(opts: IKoffiPollOptions, callback: (ev: IKoffiPollEvents) => void): void;
+        start(callback: (ev: IKoffiPollEvents) => void): void;
+        stop(): void;
+        close(): void;
+        unref(): void;
+        ref(): void;
+    }
+
+    export function poll(fd: number, opts: IKoffiPollOptions, callback: (ev: IKoffiPollEvents) => void): PollHandle;
+    export function poll(fd: number, callback: (ev: IKoffiPollEvents) => void): PollHandle;
+}

package/index.js

@@ -4,9 +4,9 @@ var __commonJS = (cb, mod3) => function __require() {
   return mod3 || (0, cb[__getOwnPropNames(cb)[0]])((mod3 = { exports: {} }).exports, mod3), mod3.exports;
 };
 
-// ../../../bin/Koffi/package/src/cnoke/src/tools.js
+// bin/Koffi/package/src/cnoke/src/tools.js
 var require_tools = __commonJS({
-  "../../../bin/Koffi/package/src/cnoke/src/tools.js"(exports2, module2) {
+  "bin/Koffi/package/src/cnoke/src/tools.js"(exports2, module2) {
     "use strict";
     var crypto = require("crypto");
     var fs2 = require("fs");
@@ -397,12 +397,12 @@ var require_tools = __commonJS({
   }
 });
 
-// ../../../bin/Koffi/package/src/koffi/package.json
+// bin/Koffi/package/src/koffi/package.json
 var require_package = __commonJS({
-  "../../../bin/Koffi/package/src/koffi/package.json"(exports2, module2) {
+  "bin/Koffi/package/src/koffi/package.json"(exports2, module2) {
     module2.exports = {
       name: "koffi",
-      version: "2.14.0",
+      version: "2.15.0",
       description: "Fast and simple C FFI (foreign function interface) for Node.js",
       keywords: [
         "foreign",
@@ -438,14 +438,15 @@ var require_package = __commonJS({
         node: 16,
         napi: 8,
         require: "./index.js"
-      }
+      },
+      funding: "https://buymeacoffee.com/koromix"
     };
   }
 });
 
-// ../../../bin/Koffi/package/src/koffi/src/init.js
+// bin/Koffi/package/src/koffi/src/init.js
 var require_init = __commonJS({
-  "../../../bin/Koffi/package/src/koffi/src/init.js"(exports, module) {
+  "bin/Koffi/package/src/koffi/src/init.js"(exports, module) {
     var fs = require("fs");
     var path = require("path");
     var util = require("util");
@@ -528,7 +529,7 @@ var require_init = __commonJS({
   }
 });
 
-// ../../../bin/Koffi/package/src/koffi/index.js
+// bin/Koffi/package/src/koffi/index.js
 var { detect: detect2, init: init2 } = require_init();
 var triplet2 = detect2();
 var native2 = null;

package/indirect.js

@@ -4,9 +4,9 @@ var __commonJS = (cb, mod3) => function __require() {
   return mod3 || (0, cb[__getOwnPropNames(cb)[0]])((mod3 = { exports: {} }).exports, mod3), mod3.exports;
 };
 
-// ../../../bin/Koffi/package/src/cnoke/src/tools.js
+// bin/Koffi/package/src/cnoke/src/tools.js
 var require_tools = __commonJS({
-  "../../../bin/Koffi/package/src/cnoke/src/tools.js"(exports2, module2) {
+  "bin/Koffi/package/src/cnoke/src/tools.js"(exports2, module2) {
     "use strict";
     var crypto = require("crypto");
     var fs2 = require("fs");
@@ -397,12 +397,12 @@ var require_tools = __commonJS({
   }
 });
 
-// ../../../bin/Koffi/package/src/koffi/package.json
+// bin/Koffi/package/src/koffi/package.json
 var require_package = __commonJS({
-  "../../../bin/Koffi/package/src/koffi/package.json"(exports2, module2) {
+  "bin/Koffi/package/src/koffi/package.json"(exports2, module2) {
     module2.exports = {
       name: "koffi",
-      version: "2.14.0",
+      version: "2.15.0",
       description: "Fast and simple C FFI (foreign function interface) for Node.js",
       keywords: [
         "foreign",
@@ -438,14 +438,15 @@ var require_package = __commonJS({
         node: 16,
         napi: 8,
         require: "./index.js"
-      }
+      },
+      funding: "https://buymeacoffee.com/koromix"
     };
   }
 });
 
-// ../../../bin/Koffi/package/src/koffi/src/init.js
+// bin/Koffi/package/src/koffi/src/init.js
 var require_init = __commonJS({
-  "../../../bin/Koffi/package/src/koffi/src/init.js"(exports, module) {
+  "bin/Koffi/package/src/koffi/src/init.js"(exports, module) {
     var fs = require("fs");
     var path = require("path");
     var util = require("util");
@@ -528,7 +529,7 @@ var require_init = __commonJS({
   }
 });
 
-// ../../../bin/Koffi/package/src/koffi/indirect.js
+// bin/Koffi/package/src/koffi/indirect.js
 var { detect: detect2, init: init2 } = require_init();
 var triplet2 = detect2();
 var mod2 = init2(triplet2, null);