koffi 2.14.1 → 2.15.0

package/CHANGELOG.md

@@ -5,6 +5,25 @@
 
 ## 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

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

@@ -7,7 +7,7 @@ Koffi is a **fast and easy-to-use C FFI module for Node.js**, featuring:
 * Javascript functions can be used as C callbacks
 * Well-tested code base for popular OS/architecture combinations
 
-I work on this project on my spare time, if you like this project, consider supporting me:
+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>

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.ini

@@ -80,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.1",
+      version: "2.15.0",
       description: "Fast and simple C FFI (foreign function interface) for Node.js",
       keywords: [
         "foreign",
@@ -444,9 +444,9 @@ var require_package = __commonJS({
   }
 });
 
-// ../../../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");
@@ -529,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.1",
+      version: "2.15.0",
       description: "Fast and simple C FFI (foreign function interface) for Node.js",
       keywords: [
         "foreign",
@@ -444,9 +444,9 @@ var require_package = __commonJS({
   }
 });
 
-// ../../../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");
@@ -529,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);