coakka-logger-node 1.2.1

package/dist/native.js

@@ -0,0 +1,363 @@
+import koffi from "../vendor/koffi/index.js";
+export const COAKKA_LOGGER_CORE_ABI_VERSION = 10;
+export const CoakkaLoggerStatus = {
+    OK: 0,
+    INVALID_ARGUMENT: 1,
+    BAD_STATE: 2,
+    QUEUE_FULL: 3,
+    RECORD_TOO_LARGE: 4,
+    TIMED_OUT: 5,
+    BUFFER_TOO_SMALL: 6,
+    INTERNAL_ERROR: 7,
+};
+export const CoakkaLoggerLevel = {
+    TRACE: 0,
+    DEBUG: 1,
+    INFO: 2,
+    WARN: 3,
+    ERROR: 4,
+    FATAL: 5,
+};
+export const CoakkaLoggerSinkMode = {
+    MANUAL_DRAIN: 0,
+    FILE: 1,
+    CONSOLE: 2,
+    MULTI: 3,
+};
+export const CoakkaLoggerSinkTarget = {
+    NONE: 0,
+    FILE: 1 << 0,
+    CONSOLE: 1 << 1,
+};
+export const CoakkaLoggerPressureState = {
+    NORMAL: 0,
+    QUOTA_PRESSURE: 1,
+    DROP_LOW_PRIORITY: 2,
+    EMERGENCY_ONLY: 3,
+};
+export const CoakkaLoggerLevelMask = {
+    TRACE: 1 << CoakkaLoggerLevel.TRACE,
+    DEBUG: 1 << CoakkaLoggerLevel.DEBUG,
+    INFO: 1 << CoakkaLoggerLevel.INFO,
+    WARN: 1 << CoakkaLoggerLevel.WARN,
+    ERROR: 1 << CoakkaLoggerLevel.ERROR,
+    FATAL: 1 << CoakkaLoggerLevel.FATAL,
+    ALL: (1 << 6) - 1,
+};
+const LoggerCoreInfoStruct = koffi.struct("coakka_logger_core_info_t", {
+    struct_size: koffi.types.size_t,
+    abi_version: "uint32_t",
+    runtime_version: "str",
+    git_commit: "str",
+    docs_hint: "str",
+});
+const LoggerCoreConfigStruct = koffi.struct("coakka_logger_core_config_t", {
+    struct_size: koffi.types.size_t,
+    system_name: "str",
+    queue_capacity: "uint32_t",
+    min_level: "int",
+    sink_mode: "int",
+    output_path: "str",
+    max_file_size_bytes: "uint64_t",
+    max_total_size_bytes: "uint64_t",
+    pressure_state: "int",
+    max_archived_files: "uint32_t",
+    category_capacity: "uint32_t",
+    message_capacity: "uint32_t",
+    emergency_output_path: "str",
+    emergency_file_size_bytes: "uint64_t",
+    category_override_capacity: "uint32_t",
+    sink_targets: "uint32_t",
+    console_fd: "int32_t",
+    console_stdout_fd: "int32_t",
+    console_stderr_fd: "int32_t",
+    console_stdout_level_mask: "uint32_t",
+    console_stderr_level_mask: "uint32_t",
+    file_output_path: "str",
+    file_max_size_bytes: "uint64_t",
+    file_total_size_limit_bytes: "uint64_t",
+    file_max_archived_files: "uint32_t",
+    file_emergency_output_path: "str",
+    file_emergency_size_bytes: "uint64_t",
+});
+const LoggerCoreConfigViewStruct = koffi.struct("coakka_logger_core_config_view_t", {
+    struct_size: koffi.types.size_t,
+    system_name: "str",
+    state: "int",
+    queue_capacity: "uint32_t",
+    min_level: "int",
+    sink_mode: "int",
+    output_path: "str",
+    max_file_size_bytes: "uint64_t",
+    max_total_size_bytes: "uint64_t",
+    pressure_state: "int",
+    max_archived_files: "uint32_t",
+    category_capacity: "uint32_t",
+    message_capacity: "uint32_t",
+    emergency_output_path: "str",
+    emergency_file_size_bytes: "uint64_t",
+    category_override_capacity: "uint32_t",
+    sink_targets: "uint32_t",
+    console_fd: "int32_t",
+    console_stdout_fd: "int32_t",
+    console_stderr_fd: "int32_t",
+    console_stdout_level_mask: "uint32_t",
+    console_stderr_level_mask: "uint32_t",
+    file_output_path: "str",
+    file_max_size_bytes: "uint64_t",
+    file_total_size_limit_bytes: "uint64_t",
+    file_max_archived_files: "uint32_t",
+    file_emergency_output_path: "str",
+    file_emergency_size_bytes: "uint64_t",
+});
+const LoggerCoreStatsStruct = koffi.struct("coakka_logger_core_stats_t", {
+    struct_size: koffi.types.size_t,
+    state: "int",
+    queue_capacity: "uint32_t",
+    queue_depth: "uint32_t",
+    queue_high_watermark: "uint32_t",
+    next_sequence: "uint64_t",
+    emitted_count: "uint64_t",
+    delivered_count: "uint64_t",
+    dropped_count: "uint64_t",
+    dropped_below_level_count: "uint64_t",
+    sink_write_count: "uint64_t",
+    sink_bytes_written: "uint64_t",
+    sink_write_failure_count: "uint64_t",
+    sink_current_file_size_bytes: "uint64_t",
+    sink_total_size_bytes: "uint64_t",
+    pressure_state: "int",
+    sink_roll_count: "uint64_t",
+    sink_deleted_archive_count: "uint64_t",
+    dropped_pressure_count: "uint64_t",
+    emergency_active: "uint32_t",
+    emergency_last_reason: "int",
+    emergency_enter_count: "uint64_t",
+    emergency_recovered_count: "uint64_t",
+    emergency_bytes_written: "uint64_t",
+    emergency_write_failure_count: "uint64_t",
+    emergency_overwrite_count: "uint64_t",
+    emergency_last_recovered_reason: "int",
+    emergency_last_recovered_duration_ms: "uint64_t",
+    emergency_last_recovered_dropped_total: "uint64_t",
+    emergency_last_recovered_dropped_pressure: "uint64_t",
+    emergency_last_recovered_deleted_archives: "uint64_t",
+    reload_count: "uint64_t",
+    category_override_count: "uint32_t",
+    sink_reopen_failure_count: "uint64_t",
+    sink_roll_failure_count: "uint64_t",
+    sink_append_failure_count: "uint64_t",
+    sink_cleanup_failure_count: "uint64_t",
+    file_write_count: "uint64_t",
+    file_bytes_written: "uint64_t",
+    file_write_failure_count: "uint64_t",
+    file_current_size_bytes: "uint64_t",
+    file_total_size_bytes: "uint64_t",
+    file_roll_count: "uint64_t",
+    file_deleted_archive_count: "uint64_t",
+    file_reopen_failure_count: "uint64_t",
+    file_roll_failure_count: "uint64_t",
+    file_append_failure_count: "uint64_t",
+    file_cleanup_failure_count: "uint64_t",
+    console_write_count: "uint64_t",
+    console_bytes_written: "uint64_t",
+    console_write_failure_count: "uint64_t",
+});
+const LoggerCoreRecordBufferStruct = koffi.struct("coakka_logger_core_record_buffer_t", {
+    struct_size: koffi.types.size_t,
+    sequence: "uint64_t",
+    wall_time_unix_ms: "uint64_t",
+    monotonic_time_ns: "uint64_t",
+    level: "int",
+    category: "char *",
+    category_capacity: koffi.types.size_t,
+    category_length: koffi.types.size_t,
+    message: "char *",
+    message_capacity: koffi.types.size_t,
+    message_length: koffi.types.size_t,
+});
+koffi.opaque("coakka_logger_core_handle_t");
+function decodeText(value) {
+    return value ?? "";
+}
+export class LoggerStatusError extends Error {
+    operation;
+    status;
+    statusName;
+    constructor(operation, status, statusName) {
+        super(`${operation} failed: ${statusName} (${status})`);
+        this.operation = operation;
+        this.status = status;
+        this.statusName = statusName;
+    }
+}
+export class NativeLoggerBindings {
+    loggerLibPath;
+    lib;
+    getAbiVersionFn;
+    getInfoFn;
+    createFn;
+    startFn;
+    stopFn;
+    destroyFn;
+    getConfigFn;
+    getStatsFn;
+    isEnabledFn;
+    isEnabledForCategoryFn;
+    logFn;
+    readNextFn;
+    statusNameFn;
+    levelNameFn;
+    stateNameFn;
+    constructor(loggerLibPath) {
+        this.loggerLibPath = loggerLibPath;
+        this.lib = koffi.load(loggerLibPath);
+        this.getAbiVersionFn = this.lib.func("uint32_t coakka_logger_core_get_abi_version(void)");
+        this.getInfoFn = this.lib.func("int coakka_logger_core_get_info(_Inout_ coakka_logger_core_info_t *out_info)");
+        this.createFn = this.lib.func("int coakka_logger_core_create(const coakka_logger_core_config_t *config, _Out_ coakka_logger_core_handle_t **out_handle)");
+        this.startFn = this.lib.func("int coakka_logger_core_start(coakka_logger_core_handle_t *handle)");
+        this.stopFn = this.lib.func("int coakka_logger_core_stop(coakka_logger_core_handle_t *handle)");
+        this.destroyFn = this.lib.func("void coakka_logger_core_destroy(coakka_logger_core_handle_t *handle)");
+        this.getConfigFn = this.lib.func("int coakka_logger_core_get_config(coakka_logger_core_handle_t *handle, _Inout_ coakka_logger_core_config_view_t *out_view)");
+        this.getStatsFn = this.lib.func("int coakka_logger_core_get_stats(coakka_logger_core_handle_t *handle, _Inout_ coakka_logger_core_stats_t *out_stats)");
+        this.isEnabledFn = this.lib.func("int coakka_logger_core_is_enabled(coakka_logger_core_handle_t *handle, int level)");
+        this.isEnabledForCategoryFn = this.lib.func("int coakka_logger_core_is_enabled_for_category(coakka_logger_core_handle_t *handle, const char *category, int level)");
+        this.logFn = this.lib.func("int coakka_logger_core_log(coakka_logger_core_handle_t *handle, int level, const char *category, const char *message, _Out_ uint64_t *out_sequence)");
+        this.readNextFn = this.lib.func("int coakka_logger_core_read_next(coakka_logger_core_handle_t *handle, uint32_t timeout_ms, _Inout_ coakka_logger_core_record_buffer_t *out_record)");
+        this.statusNameFn = this.lib.func("const char *coakka_logger_status_name(int status)");
+        this.levelNameFn = this.lib.func("const char *coakka_logger_level_name(int level)");
+        this.stateNameFn = this.lib.func("const char *coakka_logger_state_name(int state)");
+    }
+    getAbiVersion() {
+        return this.getAbiVersionFn();
+    }
+    readInfo() {
+        const info = { struct_size: koffi.sizeof(LoggerCoreInfoStruct) };
+        this.requireOk(this.getInfoFn(info), "logger_core_get_info");
+        return {
+            abiVersion: Number(info.abi_version),
+            runtimeVersion: decodeText(info.runtime_version),
+            gitCommit: decodeText(info.git_commit),
+            docsHint: decodeText(info.docs_hint),
+        };
+    }
+    create(config) {
+        const outHandle = [null];
+        const nativeConfig = {
+            struct_size: koffi.sizeof(LoggerCoreConfigStruct),
+            system_name: config.systemName,
+            queue_capacity: config.queueCapacity,
+            min_level: config.minLevel,
+            sink_mode: CoakkaLoggerSinkMode.MANUAL_DRAIN,
+            output_path: null,
+            max_file_size_bytes: 0,
+            max_total_size_bytes: 0,
+            pressure_state: CoakkaLoggerPressureState.NORMAL,
+            max_archived_files: 0,
+            category_capacity: config.categoryCapacity,
+            message_capacity: config.messageCapacity,
+            emergency_output_path: null,
+            emergency_file_size_bytes: 0,
+            category_override_capacity: 32,
+            sink_targets: CoakkaLoggerSinkTarget.NONE,
+            console_fd: -1,
+            console_stdout_fd: -1,
+            console_stderr_fd: -1,
+            console_stdout_level_mask: CoakkaLoggerLevelMask.TRACE | CoakkaLoggerLevelMask.DEBUG | CoakkaLoggerLevelMask.INFO,
+            console_stderr_level_mask: CoakkaLoggerLevelMask.WARN | CoakkaLoggerLevelMask.ERROR | CoakkaLoggerLevelMask.FATAL,
+            file_output_path: null,
+            file_max_size_bytes: 0,
+            file_total_size_limit_bytes: 0,
+            file_max_archived_files: 0,
+            file_emergency_output_path: null,
+            file_emergency_size_bytes: 0,
+        };
+        this.requireOk(this.createFn(nativeConfig, outHandle), "logger_core_create");
+        const handle = outHandle[0];
+        if (handle == null) {
+            throw new Error("logger_core_create returned null handle");
+        }
+        return handle;
+    }
+    start(handle) {
+        this.requireOk(this.startFn(handle), "logger_core_start");
+    }
+    stop(handle) {
+        this.requireOk(this.stopFn(handle), "logger_core_stop");
+    }
+    destroy(handle) {
+        this.destroyFn(handle);
+    }
+    config(handle) {
+        const view = { struct_size: koffi.sizeof(LoggerCoreConfigViewStruct) };
+        this.requireOk(this.getConfigFn(handle, view), "logger_core_get_config");
+        const state = Number(view.state);
+        return {
+            systemName: decodeText(view.system_name),
+            state,
+            stateName: decodeText(this.stateNameFn(state)),
+            queueCapacity: Number(view.queue_capacity),
+            categoryCapacity: Number(view.category_capacity),
+            messageCapacity: Number(view.message_capacity),
+        };
+    }
+    stats(handle) {
+        const stats = { struct_size: koffi.sizeof(LoggerCoreStatsStruct) };
+        this.requireOk(this.getStatsFn(handle, stats), "logger_core_get_stats");
+        const state = Number(stats.state);
+        return {
+            state,
+            stateName: decodeText(this.stateNameFn(state)),
+            queueCapacity: Number(stats.queue_capacity),
+            queueDepth: Number(stats.queue_depth),
+            queueHighWatermark: Number(stats.queue_high_watermark),
+            nextSequence: Number(stats.next_sequence),
+            emittedCount: Number(stats.emitted_count),
+            deliveredCount: Number(stats.delivered_count),
+            droppedCount: Number(stats.dropped_count),
+        };
+    }
+    isEnabled(handle, level) {
+        return this.isEnabledFn(handle, level) !== 0;
+    }
+    isEnabledForCategory(handle, category, level) {
+        return this.isEnabledForCategoryFn(handle, category, level) !== 0;
+    }
+    log(handle, level, category, message) {
+        const outSequence = [0];
+        this.requireOk(this.logFn(handle, level, category, message, outSequence), "logger_core_log");
+        return Number(outSequence[0]);
+    }
+    readNext(handle, timeoutMs, categoryCapacity, messageCapacity) {
+        const category = Buffer.alloc(Math.max(1, categoryCapacity));
+        const message = Buffer.alloc(Math.max(1, messageCapacity));
+        const record = {
+            struct_size: koffi.sizeof(LoggerCoreRecordBufferStruct),
+            category,
+            category_capacity: category.byteLength,
+            message,
+            message_capacity: message.byteLength,
+        };
+        const status = this.readNextFn(handle, timeoutMs, record);
+        if (status === CoakkaLoggerStatus.TIMED_OUT) {
+            return null;
+        }
+        this.requireOk(status, "logger_core_read_next");
+        const level = Number(record.level);
+        return {
+            sequence: Number(record.sequence),
+            wallTimeUnixMs: Number(record.wall_time_unix_ms),
+            monotonicTimeNs: Number(record.monotonic_time_ns),
+            level,
+            levelName: decodeText(this.levelNameFn(level)),
+            category: category.toString("utf8", 0, Number(record.category_length)),
+            message: message.toString("utf8", 0, Number(record.message_length)),
+        };
+    }
+    requireOk(status, operation) {
+        if (status === CoakkaLoggerStatus.OK) {
+            return;
+        }
+        throw new LoggerStatusError(operation, status, decodeText(this.statusNameFn(status)));
+    }
+}

package/dist/packaging.d.ts

@@ -0,0 +1,4 @@
+export declare const LOGGER_NODE_VERSION = "1.2.1";
+export declare const LOGGER_NATIVE_CORE_VERSION = "1.2.1";
+export declare const LOGGER_NATIVE_GIT_COMMIT = "f50756ebff0d";
+export declare const LOGGER_NATIVE_PACKAGE_VERSION = "1.2.1+f50756ebff0d";

package/dist/packaging.js

@@ -0,0 +1,4 @@
+export const LOGGER_NODE_VERSION = "1.2.1";
+export const LOGGER_NATIVE_CORE_VERSION = "1.2.1";
+export const LOGGER_NATIVE_GIT_COMMIT = "f50756ebff0d";
+export const LOGGER_NATIVE_PACKAGE_VERSION = "1.2.1+f50756ebff0d";

package/native/.gitkeep

@@ -0,0 +1 @@
+

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "coakka-logger-node",
+  "version": "1.2.1",
+  "description": "Node.js connector package for the CoAkka native logger core",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "native",
+    "vendor",
+    "CONSUMING.md",
+    "LICENSE.md",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "npm run stage:native && tsc -p tsconfig.json && node scripts/vendor-koffi.mjs",
+    "stage:native": "node scripts/stage-logger-natives.mjs",
+    "test": "tsx --test test/**/*.test.ts",
+    "verify": "npm run build && npm test",
+    "pack:release": "npm run build && npm pack",
+    "smoke:packaged": "bash scripts/smoke-packaged-package.sh"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "koffi": "^2.16.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.8.3"
+  }
+}

package/vendor/koffi/LICENSE.txt

@@ -0,0 +1,22 @@
+MIT License
+
+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.