coakka-logger-node 1.2.1

package/CONSUMING.md

@@ -0,0 +1,35 @@
+# Consuming `coakka-logger-node`
+
+The Node.js logger package is a binary tarball that embeds the native logger
+core. Applications normally do not need to pass a native library path.
+
+```ts
+import { CoakkaLoggerLevel, Logger } from "coakka-logger-node";
+
+const logger = Logger.start({ minLevel: CoakkaLoggerLevel.INFO });
+try {
+  logger.info("orders", "accepted");
+  const record = logger.awaitNext(1000);
+} finally {
+  logger.close();
+}
+```
+
+For local development or diagnostics, an explicit native library path can be
+provided:
+
+```ts
+Logger.start({}, "/abs/path/to/libcoakka_logger_core.dylib");
+```
+
+The environment override is:
+
+```sh
+COAKKA_LOGGER_LIB=/abs/path/to/libcoakka_logger_core.so
+```
+
+Current embedded native package:
+
+- native core version: `1.2.1`
+- native package version: `1.2.1+f50756ebff0d`
+- platforms: `macos-aarch64`, `linux-aarch64`, `linux-x86_64`

package/LICENSE.md

@@ -0,0 +1,115 @@
+# CoAkka Public Artifact Preview License 1.0
+
+Effective: 2026-07-19
+
+This repository is the public binary artifact surface for CoAkka. It contains
+headers, native libraries, connector packages, Maven artifacts, checksums, and
+artifact metadata. It is not a source-build repository.
+
+Unless a specific release artifact includes different license terms, the
+artifacts in this repository are made available under the following preview
+terms.
+
+This is not an OSI-approved open source license. The separate
+`coakka-samples` repository may use a permissive open source license for sample
+code and documentation; that sample license does not change the terms for the
+artifacts distributed from this repository.
+
+## Definitions
+
+`Artifacts` means the CoAkka binaries, headers, libraries, connector packages,
+Maven artifacts, container-bundle files, checksums, manifests, and release
+metadata distributed from this repository or from an official release page for
+this repository.
+
+`Production` means any environment that serves live end-user traffic, live
+customer data, live operational data, revenue-generating workloads, or
+customer-facing workloads outside development, test, CI, sample execution, or
+proof-of-concept evaluation.
+
+`Official sample images` means container images published by the CoAkka
+project or repository owner, including the current
+`docker.io/gabrielgun1983/*` sample image namespace and any future images
+published under an official CoAkka container namespace, that bundle unmodified
+artifacts solely to run official CoAkka samples.
+
+## Allowed Use
+
+You may download, copy, and use the artifacts from this repository to:
+
+- evaluate CoAkka locally
+- run the official public samples
+- build proof-of-concept integrations
+- run development and test environments for applications that integrate with
+  CoAkka
+- run CI jobs, automated tests, and integration verification for
+  non-production applications or evaluations
+- run company evaluations, proofs of concept, and integration tests,
+  including evaluations inside commercial organizations
+- redistribute unmodified CoAkka artifacts inside local development, test, or
+  sample environments, provided this notice and the included checksums or
+  manifests remain available
+- pull, cache internally, and run official sample images for local development,
+  CI, test, sample execution, proof-of-concept integration, and evaluation
+
+## Reserved Uses
+
+The following uses require a separate written license:
+
+- selling, hosting, or offering CoAkka artifacts as a managed runtime service
+- running CoAkka artifacts in production systems
+- bundling CoAkka artifacts into a product distributed to customers
+- redistributing CoAkka artifacts as part of a paid product, support package,
+  appliance, cloud image, or hosted service
+- offering a product or service that presents modified CoAkka artifacts as
+  official CoAkka artifacts
+- removing or obscuring copyright, license, checksum, or provenance notices
+- reverse engineering artifacts except where that restriction is prohibited by
+  applicable law
+- using the CoAkka name, package names, artifact names, image names, or other
+  project identifiers in a way that implies endorsement of an unofficial fork,
+  hosted service, or product
+
+## Official Samples
+
+Official sample images may bundle unmodified artifacts solely so users can run
+official CoAkka samples without installing the artifacts manually.
+
+This sample-image permission does not grant third parties the right to create,
+publish, sell, host, or distribute derivative images for production, customer
+distribution, hosted services, paid support packages, appliances, or cloud
+marketplace offerings.
+
+## Production Use
+
+These preview terms are intended for developer evaluation, sample execution,
+non-production proof-of-concept work, CI, and integration testing. Production
+use, hosted service use, customer distribution, and paid redistribution require
+explicit release terms or a separate written agreement.
+
+For production, hosted service, customer distribution, paid redistribution, or
+other commercial rights, contact the project through `SUPPORT.md`.
+
+## No Warranty
+
+The artifacts are provided as-is, without warranties or conditions of any kind,
+to the maximum extent permitted by applicable law.
+
+## Limitation Of Liability
+
+To the maximum extent permitted by applicable law, the project contributors and
+artifact publishers are not liable for any direct, indirect, incidental,
+special, consequential, exemplary, or other damages arising from use of the
+artifacts.
+
+## No Patent Or Trademark Grant
+
+These preview terms do not grant patent rights, trademark rights, or rights to
+use the CoAkka name beyond the limited artifact and sample uses allowed above.
+Trademark use is governed by `TRADEMARKS.md`.
+
+## Legal Notice
+
+This file is not legal advice. If your intended use depends on legal
+interpretation of these terms, consult your own counsel or request a separate
+written agreement.

package/README.md

@@ -0,0 +1,45 @@
+# CoAkka Logger Node
+
+`logger/node/` is the Node.js host connector lane for the standalone CoAkka
+native logger core.
+
+It mirrors the Python logger lane:
+
+- load `libcoakka_logger_core` through `koffi`
+- keep Node-side formatting above the native core
+- let the native logger own queueing, pressure policy, sinks, and lifecycle
+- package staged native libraries into the npm tarball for macOS aarch64,
+  Linux aarch64, and Linux x86_64
+
+## Build
+
+```sh
+npm --prefix logger/node run build
+```
+
+The script stages native libraries from:
+
+```text
+logger/staging/native/1.2.1+f50756ebff0d/
+```
+
+## Smoke
+
+```sh
+npm --prefix logger/node test
+npm --prefix logger/node run smoke:packaged
+```
+
+## Example
+
+```ts
+import { Logger } from "coakka-logger-node";
+
+const logger = Logger.start();
+try {
+  logger.info("app", "started");
+  const record = logger.awaitNext(1000);
+} finally {
+  logger.close();
+}
+```

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { LOGGER_NATIVE_CORE_VERSION, LOGGER_NATIVE_GIT_COMMIT, LOGGER_NATIVE_PACKAGE_VERSION, LOGGER_NODE_VERSION, } from "./packaging.js";
+export { Logger, type LoggerSpec, } from "./logger.js";
+export { COAKKA_LOGGER_CORE_ABI_VERSION, CoakkaLoggerLevel, CoakkaLoggerLevelMask, CoakkaLoggerPressureState, CoakkaLoggerSinkMode, CoakkaLoggerSinkTarget, CoakkaLoggerStatus, LoggerStatusError, type LoggerConfigSnapshot, type LoggerInfoSnapshot, type LoggerRecordSnapshot, type LoggerStatsSnapshot, } from "./native.js";
+export { LoggerLibraryResolver, } from "./native-loader.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { LOGGER_NATIVE_CORE_VERSION, LOGGER_NATIVE_GIT_COMMIT, LOGGER_NATIVE_PACKAGE_VERSION, LOGGER_NODE_VERSION, } from "./packaging.js";
+export { Logger, } from "./logger.js";
+export { COAKKA_LOGGER_CORE_ABI_VERSION, CoakkaLoggerLevel, CoakkaLoggerLevelMask, CoakkaLoggerPressureState, CoakkaLoggerSinkMode, CoakkaLoggerSinkTarget, CoakkaLoggerStatus, LoggerStatusError, } from "./native.js";
+export { LoggerLibraryResolver, } from "./native-loader.js";

package/dist/logger.d.ts

@@ -0,0 +1,35 @@
+import { type LoggerConfigSnapshot, type LoggerInfoSnapshot, type LoggerRecordSnapshot, type LoggerStatsSnapshot } from "./native.js";
+export interface LoggerSpec {
+    systemName?: string;
+    queueCapacity?: number;
+    categoryCapacity?: number;
+    messageCapacity?: number;
+    minLevel?: number;
+}
+export declare class Logger {
+    private readonly bindings;
+    private readonly handle;
+    private readonly spec;
+    static start(spec?: LoggerSpec, loggerLibPath?: string): Logger;
+    static readInfo(loggerLibPath?: string): LoggerInfoSnapshot;
+    private stopped;
+    private closed;
+    private constructor();
+    config(): LoggerConfigSnapshot;
+    stats(): LoggerStatsSnapshot;
+    isEnabled(level: number): boolean;
+    isEnabledForCategory(category: string, level: number): boolean;
+    log(level: number, category: string, message: string): number | null;
+    trace(category: string, message: string): number | null;
+    debug(category: string, message: string): number | null;
+    info(category: string, message: string): number | null;
+    warn(category: string, message: string): number | null;
+    error(category: string, message: string): number | null;
+    fatal(category: string, message: string): number | null;
+    poll(): LoggerRecordSnapshot | null;
+    awaitNext(timeoutMs?: number): LoggerRecordSnapshot | null;
+    stop(): void;
+    close(): void;
+    [Symbol.dispose](): void;
+    private requireOpen;
+}

package/dist/logger.js

@@ -0,0 +1,121 @@
+import { COAKKA_LOGGER_CORE_ABI_VERSION, CoakkaLoggerLevel, NativeLoggerBindings, } from "./native.js";
+import { LoggerLibraryResolver } from "./native-loader.js";
+export class Logger {
+    bindings;
+    handle;
+    spec;
+    static start(spec = {}, loggerLibPath) {
+        const resolvedSpec = resolveSpec(spec);
+        const bindings = new NativeLoggerBindings(LoggerLibraryResolver.resolve(loggerLibPath));
+        const abiVersion = bindings.getAbiVersion();
+        if (abiVersion !== COAKKA_LOGGER_CORE_ABI_VERSION) {
+            throw new Error(`unexpected logger ABI version: expected ${COAKKA_LOGGER_CORE_ABI_VERSION}, got ${abiVersion}`);
+        }
+        const handle = bindings.create(resolvedSpec);
+        try {
+            bindings.start(handle);
+        }
+        catch (error) {
+            bindings.destroy(handle);
+            throw error;
+        }
+        return new Logger(bindings, handle, resolvedSpec);
+    }
+    static readInfo(loggerLibPath) {
+        return new NativeLoggerBindings(LoggerLibraryResolver.resolve(loggerLibPath)).readInfo();
+    }
+    stopped = false;
+    closed = false;
+    constructor(bindings, handle, spec) {
+        this.bindings = bindings;
+        this.handle = handle;
+        this.spec = spec;
+    }
+    config() {
+        this.requireOpen();
+        return this.bindings.config(this.handle);
+    }
+    stats() {
+        this.requireOpen();
+        return this.bindings.stats(this.handle);
+    }
+    isEnabled(level) {
+        this.requireOpen();
+        return this.bindings.isEnabled(this.handle, level);
+    }
+    isEnabledForCategory(category, level) {
+        this.requireOpen();
+        return this.bindings.isEnabledForCategory(this.handle, category, level);
+    }
+    log(level, category, message) {
+        if (!this.isEnabledForCategory(category, level)) {
+            return null;
+        }
+        this.requireOpen();
+        return this.bindings.log(this.handle, level, category, message);
+    }
+    trace(category, message) {
+        return this.log(CoakkaLoggerLevel.TRACE, category, message);
+    }
+    debug(category, message) {
+        return this.log(CoakkaLoggerLevel.DEBUG, category, message);
+    }
+    info(category, message) {
+        return this.log(CoakkaLoggerLevel.INFO, category, message);
+    }
+    warn(category, message) {
+        return this.log(CoakkaLoggerLevel.WARN, category, message);
+    }
+    error(category, message) {
+        return this.log(CoakkaLoggerLevel.ERROR, category, message);
+    }
+    fatal(category, message) {
+        return this.log(CoakkaLoggerLevel.FATAL, category, message);
+    }
+    poll() {
+        return this.awaitNext(0);
+    }
+    awaitNext(timeoutMs = 1000) {
+        this.requireOpen();
+        return this.bindings.readNext(this.handle, timeoutMs, this.spec.categoryCapacity, this.spec.messageCapacity);
+    }
+    stop() {
+        if (this.closed || this.stopped) {
+            return;
+        }
+        this.bindings.stop(this.handle);
+        this.stopped = true;
+    }
+    close() {
+        if (this.closed) {
+            return;
+        }
+        if (!this.stopped) {
+            try {
+                this.bindings.stop(this.handle);
+            }
+            finally {
+                this.stopped = true;
+            }
+        }
+        this.bindings.destroy(this.handle);
+        this.closed = true;
+    }
+    [Symbol.dispose]() {
+        this.close();
+    }
+    requireOpen() {
+        if (this.closed) {
+            throw new Error("logger is closed");
+        }
+    }
+}
+function resolveSpec(spec) {
+    return {
+        systemName: spec.systemName ?? "nodeLogger",
+        queueCapacity: spec.queueCapacity ?? 256,
+        categoryCapacity: spec.categoryCapacity ?? 64,
+        messageCapacity: spec.messageCapacity ?? 512,
+        minLevel: spec.minLevel ?? CoakkaLoggerLevel.TRACE,
+    };
+}

package/dist/native-loader.d.ts

@@ -0,0 +1,11 @@
+export declare class LoggerLibraryResolver {
+    static readonly envVar = "COAKKA_LOGGER_LIB";
+    static resolve(explicitPath?: string): string;
+    static platformId(osName?: NodeJS.Platform, archName?: NodeJS.Architecture): string;
+    static normalizeOs(osName: string): string;
+    static normalizeArch(archName: string): string;
+    static resourceFileNamesForCurrentPlatform(osName?: NodeJS.Platform): string[];
+    private static resolveEmbedded;
+    private static searchCandidates;
+    private static requireExisting;
+}

package/dist/native-loader.js

@@ -0,0 +1,94 @@
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { LOGGER_NATIVE_PACKAGE_VERSION } from "./packaging.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export class LoggerLibraryResolver {
+    static envVar = "COAKKA_LOGGER_LIB";
+    static resolve(explicitPath) {
+        if (explicitPath != null && explicitPath.trim() !== "") {
+            return this.requireExisting(resolve(explicitPath), "explicit loggerLibPath");
+        }
+        const configuredPath = process.env[this.envVar]?.trim();
+        if (configuredPath != null && configuredPath !== "") {
+            return this.requireExisting(resolve(configuredPath), `$${this.envVar}`);
+        }
+        const embedded = this.resolveEmbedded();
+        if (embedded != null) {
+            return embedded;
+        }
+        for (const candidate of this.searchCandidates()) {
+            if (existsSync(candidate)) {
+                return candidate;
+            }
+        }
+        throw new Error("native logger library was not found. " +
+            `Set ${this.envVar}, pass loggerLibPath explicitly, or package one of ` +
+            `${this.resourceFileNamesForCurrentPlatform().join(", ")} under logger/node/native/${this.platformId()}/.`);
+    }
+    static platformId(osName = process.platform, archName = process.arch) {
+        return `${this.normalizeOs(osName)}-${this.normalizeArch(archName)}`;
+    }
+    static normalizeOs(osName) {
+        const normalized = osName.toLowerCase();
+        if (normalized === "darwin" || normalized.includes("mac")) {
+            return "macos";
+        }
+        if (normalized === "linux" || normalized.includes("linux")) {
+            return "linux";
+        }
+        if (normalized === "win32" || normalized.includes("windows")) {
+            return "windows";
+        }
+        throw new Error(`unsupported os.name=${osName}; supported platforms are macOS, Linux, and Windows`);
+    }
+    static normalizeArch(archName) {
+        const normalized = archName.toLowerCase();
+        if (normalized === "arm64" || normalized === "aarch64") {
+            return "aarch64";
+        }
+        if (normalized === "x64" || normalized === "x86_64" || normalized === "amd64") {
+            return "x86_64";
+        }
+        throw new Error(`unsupported os.arch=${archName}; supported architectures are aarch64 and x86_64`);
+    }
+    static resourceFileNamesForCurrentPlatform(osName = process.platform) {
+        const versionedBase = `libcoakka_logger_core-${LOGGER_NATIVE_PACKAGE_VERSION}`;
+        switch (this.normalizeOs(osName)) {
+            case "macos":
+                return [`${versionedBase}.dylib`, "libcoakka_logger_core.dylib", "libcoakka_logger_core.so"];
+            case "linux":
+                return [`${versionedBase}.so`, "libcoakka_logger_core.so"];
+            case "windows":
+                return [`${versionedBase}.dll`, "libcoakka_logger_core.dll"];
+            default:
+                throw new Error("unsupported platform");
+        }
+    }
+    static resolveEmbedded() {
+        const platformId = this.platformId();
+        for (const fileName of this.resourceFileNamesForCurrentPlatform()) {
+            const resourcePath = resolve(__dirname, "..", "native", platformId, fileName);
+            if (existsSync(resourcePath)) {
+                const tempDir = mkdtempSync(resolve(tmpdir(), "coakka-logger-node-"));
+                process.once("exit", () => rmSync(tempDir, { recursive: true, force: true }));
+                const targetPath = resolve(tempDir, fileName);
+                writeFileSync(targetPath, readFileSync(resourcePath));
+                return targetPath;
+            }
+        }
+        return null;
+    }
+    static searchCandidates() {
+        const cwd = process.cwd();
+        const roots = [resolve(cwd, "lib"), resolve(cwd, "logger", "node", "lib")];
+        return roots.flatMap((root) => this.resourceFileNamesForCurrentPlatform().map((name) => resolve(root, name)));
+    }
+    static requireExisting(path, source) {
+        if (!existsSync(path)) {
+            throw new Error(`${source} does not exist: ${path}`);
+        }
+        return path;
+    }
+}

package/dist/native.d.ts

@@ -0,0 +1,125 @@
+export declare const COAKKA_LOGGER_CORE_ABI_VERSION = 10;
+export declare const CoakkaLoggerStatus: {
+    readonly OK: 0;
+    readonly INVALID_ARGUMENT: 1;
+    readonly BAD_STATE: 2;
+    readonly QUEUE_FULL: 3;
+    readonly RECORD_TOO_LARGE: 4;
+    readonly TIMED_OUT: 5;
+    readonly BUFFER_TOO_SMALL: 6;
+    readonly INTERNAL_ERROR: 7;
+};
+export declare const CoakkaLoggerLevel: {
+    readonly TRACE: 0;
+    readonly DEBUG: 1;
+    readonly INFO: 2;
+    readonly WARN: 3;
+    readonly ERROR: 4;
+    readonly FATAL: 5;
+};
+export declare const CoakkaLoggerSinkMode: {
+    readonly MANUAL_DRAIN: 0;
+    readonly FILE: 1;
+    readonly CONSOLE: 2;
+    readonly MULTI: 3;
+};
+export declare const CoakkaLoggerSinkTarget: {
+    readonly NONE: 0;
+    readonly FILE: number;
+    readonly CONSOLE: number;
+};
+export declare const CoakkaLoggerPressureState: {
+    readonly NORMAL: 0;
+    readonly QUOTA_PRESSURE: 1;
+    readonly DROP_LOW_PRIORITY: 2;
+    readonly EMERGENCY_ONLY: 3;
+};
+export declare const CoakkaLoggerLevelMask: {
+    readonly TRACE: number;
+    readonly DEBUG: number;
+    readonly INFO: number;
+    readonly WARN: number;
+    readonly ERROR: number;
+    readonly FATAL: number;
+    readonly ALL: number;
+};
+export interface LoggerInfoSnapshot {
+    abiVersion: number;
+    runtimeVersion: string;
+    gitCommit: string;
+    docsHint: string;
+}
+export interface LoggerConfigSnapshot {
+    systemName: string;
+    state: number;
+    stateName: string;
+    queueCapacity: number;
+    categoryCapacity: number;
+    messageCapacity: number;
+}
+export interface LoggerStatsSnapshot {
+    state: number;
+    stateName: string;
+    queueCapacity: number;
+    queueDepth: number;
+    queueHighWatermark: number;
+    nextSequence: number;
+    emittedCount: number;
+    deliveredCount: number;
+    droppedCount: number;
+}
+export interface LoggerRecordSnapshot {
+    sequence: number;
+    wallTimeUnixMs: number;
+    monotonicTimeNs: number;
+    level: number;
+    levelName: string;
+    category: string;
+    message: string;
+}
+export interface NativeLoggerConfig {
+    systemName: string;
+    queueCapacity: number;
+    categoryCapacity: number;
+    messageCapacity: number;
+    minLevel: number;
+}
+export declare class LoggerStatusError extends Error {
+    readonly operation: string;
+    readonly status: number;
+    readonly statusName: string;
+    constructor(operation: string, status: number, statusName: string);
+}
+export declare class NativeLoggerBindings {
+    readonly loggerLibPath: string;
+    private readonly lib;
+    private readonly getAbiVersionFn;
+    private readonly getInfoFn;
+    private readonly createFn;
+    private readonly startFn;
+    private readonly stopFn;
+    private readonly destroyFn;
+    private readonly getConfigFn;
+    private readonly getStatsFn;
+    private readonly isEnabledFn;
+    private readonly isEnabledForCategoryFn;
+    private readonly logFn;
+    private readonly readNextFn;
+    private readonly statusNameFn;
+    private readonly levelNameFn;
+    private readonly stateNameFn;
+    constructor(loggerLibPath: string);
+    getAbiVersion(): number;
+    readInfo(): LoggerInfoSnapshot;
+    create(config: NativeLoggerConfig): unknown;
+    start(handle: unknown): void;
+    stop(handle: unknown): void;
+    destroy(handle: unknown): void;
+    config(handle: unknown): LoggerConfigSnapshot;
+    stats(handle: unknown): LoggerStatsSnapshot;
+    isEnabled(handle: unknown, level: number): boolean;
+    isEnabledForCategory(handle: unknown, category: string, level: number): boolean;
+    log(handle: unknown, level: number, category: string, message: string): number;
+    readNext(handle: unknown, timeoutMs: number, categoryCapacity: number, messageCapacity: number): LoggerRecordSnapshot | null;
+    requireOk(status: number, operation: string): void;
+}