coakka-v2-connector-node 1.3.1

package/dist/runtime-ffi.d.ts

@@ -0,0 +1,105 @@
+export declare const COAKKA_OK = 0;
+export declare const COAKKA_ABI_VERSION = 1;
+export declare const HOST_HANDLES_ENABLE_MONITOR: number;
+export declare const HOST_HANDLES_SEPARATE_DELIVERED_REQUEST_LANE: number;
+export interface RuntimeInfoSnapshot {
+    abiVersion: number;
+    featureFlags: number;
+    runtimeVersion: string;
+    gitCommit: string;
+    southboundBackend: string;
+    allocatorBackend: string;
+    docsHint: string;
+}
+export interface RuntimeConfigSnapshot {
+    systemName: string;
+    nodeId: string;
+    runtimeState: number;
+    snapshotPresent: boolean;
+    appliedGeneration: number;
+    routeCount: number;
+    southboundBindHost: string;
+    southboundBindPort: number;
+    effectiveIngressOverloadMode: number;
+    effectiveLocalDeliveryOverloadMode: number;
+    effectiveRemoteOutboundOverloadMode: number;
+    effectiveRemoteOutboundReplyReserveSlots: number;
+}
+export interface RuntimeHealthSnapshot {
+    runtimeState: number;
+    flags: number;
+    appliedGeneration: number;
+}
+export interface RuntimeStatsSnapshot {
+    appliedGeneration: number;
+    routeCount: number;
+    runtimeState: number;
+    queueRejectedCount: number;
+    routeMissCount: number;
+    deadletterCount: number;
+    deliveryFailedCount: number;
+    controlRejectedCount: number;
+    monitorEventEmittedCount: number;
+    monitorEventDroppedCount: number;
+    monitorEventEmittedLifetimeCount: number;
+    monitorEventDroppedLifetimeCount: number;
+    localWorkQueueCapacity: number;
+    localWorkQueueDepth: number;
+    localWorkQueueHighWatermark: number;
+    deliveredRequestOutboundDirectWriteCount: number;
+    responseOutboundDirectWriteCount: number;
+    deadletterOutboundDirectWriteCount: number;
+    remoteOutboundQueueCapacity: number;
+    remoteOutboundQueueDepth: number;
+    remoteOutboundQueueHighWatermark: number;
+    remoteOutboundQueueRejectedCount: number;
+    remoteOutboundExpiredDropCount: number;
+    remoteOutboundReplyReserveSlots: number;
+    remoteOutboundReplyReservationRejectCount: number;
+    remoteOutboundOneWayDropCount: number;
+}
+export interface HostHandlesSnapshot {
+    flags: number;
+    requestWriteFd: number;
+    responseReadFd: number;
+    deadletterReadFd: number;
+    controlWriteFd: number;
+    monitorReadFd: number;
+    deliveredRequestReadFd: number;
+}
+export interface NativeRuntimeConfig {
+    systemName: string;
+    nodeId: string;
+    strictNoDrop: boolean;
+    queueCapacity: number;
+}
+export declare class NativeRuntimeBindings {
+    readonly runtimeLibPath: string;
+    private readonly lib;
+    private readonly getAbiVersionFn;
+    private readonly getInfoFn;
+    private readonly createRuntimeFn;
+    private readonly destroyRuntimeFn;
+    private readonly getHostHandlesFn;
+    private readonly startRuntimeFn;
+    private readonly stopRuntimeFn;
+    private readonly getHealthFn;
+    private readonly getStatsFn;
+    private readonly getConfigFn;
+    private readonly submitEnvelopeFn;
+    private readonly applyControlEnvelopeFn;
+    constructor(runtimeLibPath: string);
+    getAbiVersion(): number;
+    readRuntimeInfo(): RuntimeInfoSnapshot;
+    createRuntime(config: NativeRuntimeConfig): unknown;
+    destroyRuntime(runtime: unknown): void;
+    getHostHandles(runtime: unknown, flags: number): HostHandlesSnapshot;
+    startRuntime(runtime: unknown): void;
+    stopRuntime(runtime: unknown): void;
+    getHealth(runtime: unknown): RuntimeHealthSnapshot;
+    getStats(runtime: unknown): RuntimeStatsSnapshot;
+    getConfig(runtime: unknown): RuntimeConfigSnapshot;
+    submitEnvelope(runtime: unknown, bytes: Uint8Array): void;
+    applyControlEnvelope(runtime: unknown, bytes: Uint8Array): void;
+    requireOk(rc: number, what: string): void;
+}

package/dist/runtime-ffi.js

@@ -0,0 +1,282 @@
+import koffi from "../vendor/koffi/index.js";
+export const COAKKA_OK = 0;
+export const COAKKA_ABI_VERSION = 1;
+export const HOST_HANDLES_ENABLE_MONITOR = 1 << 0;
+export const HOST_HANDLES_SEPARATE_DELIVERED_REQUEST_LANE = 1 << 1;
+const RuntimeConfigStruct = koffi.struct("coakka_v2_runtime_config_t", {
+    system_name: "str",
+    node_id: "str",
+    strict_no_drop: "int",
+    queue_capacity: "int",
+});
+const RuntimeInfoStruct = koffi.struct("coakka_v2_runtime_info_t", {
+    struct_size: koffi.types.size_t,
+    abi_version: "uint32_t",
+    feature_flags: "uint32_t",
+    runtime_version: "str",
+    git_commit: "str",
+    southbound_backend: "str",
+    allocator_backend: "str",
+    docs_hint: "str",
+});
+const RuntimeConfigViewStruct = koffi.struct("coakka_v2_runtime_config_view_t", {
+    struct_size: koffi.types.size_t,
+    system_name: "str",
+    node_id: "str",
+    strict_no_drop: "int",
+    queue_capacity: "int",
+    request_max_frame_size: koffi.types.size_t,
+    local_dispatch_batch_limit: koffi.types.size_t,
+    runtime_state: "int",
+    snapshot_present: "uint32_t",
+    applied_generation: "uint64_t",
+    route_count: koffi.types.size_t,
+    southbound_bind_host: "str",
+    southbound_bind_port: "uint16_t",
+    configured_ingress_overload_mode: "uint32_t",
+    configured_local_delivery_overload_mode: "uint32_t",
+    configured_remote_outbound_overload_mode: "uint32_t",
+    configured_remote_outbound_reply_reserve_slots: koffi.types.size_t,
+    effective_ingress_overload_mode: "uint32_t",
+    effective_local_delivery_overload_mode: "uint32_t",
+    effective_remote_outbound_overload_mode: "uint32_t",
+    effective_remote_outbound_reply_reserve_slots: koffi.types.size_t,
+});
+const HostHandlesStruct = koffi.struct("coakka_v2_host_handles_t", {
+    struct_size: koffi.types.size_t,
+    flags: "uint32_t",
+    request_write_fd: "int",
+    response_read_fd: "int",
+    deadletter_read_fd: "int",
+    control_write_fd: "int",
+    monitor_read_fd: "int",
+    delivered_request_read_fd: "int",
+});
+const RuntimeHealthStruct = koffi.struct("coakka_v2_runtime_health_t", {
+    struct_size: koffi.types.size_t,
+    runtime_state: "int",
+    flags: "uint32_t",
+    applied_generation: "uint64_t",
+});
+const RuntimeStatsStruct = koffi.struct("coakka_v2_runtime_stats_t", {
+    struct_size: koffi.types.size_t,
+    applied_generation: "uint64_t",
+    route_count: koffi.types.size_t,
+    runtime_state: "int",
+    ingress_queue_capacity: koffi.types.size_t,
+    ingress_queue_depth: koffi.types.size_t,
+    ingress_queue_high_watermark: koffi.types.size_t,
+    queue_rejected_count: "uint64_t",
+    route_miss_count: "uint64_t",
+    deadletter_count: "uint64_t",
+    delivery_failed_count: "uint64_t",
+    remote_transport_failed_count: "uint64_t",
+    southbound_submit_attempt_count: "uint64_t",
+    southbound_probe_connect_success_count: "uint64_t",
+    southbound_probe_connect_failure_count: "uint64_t",
+    request_max_frame_size: koffi.types.size_t,
+    local_dispatch_batch_limit: koffi.types.size_t,
+    delivered_request_outbound_queue_capacity: koffi.types.size_t,
+    delivered_request_outbound_queue_depth: koffi.types.size_t,
+    delivered_request_outbound_queue_high_watermark: koffi.types.size_t,
+    delivered_request_outbound_enqueue_block_count: "uint64_t",
+    response_outbound_queue_capacity: koffi.types.size_t,
+    response_outbound_queue_depth: koffi.types.size_t,
+    response_outbound_queue_high_watermark: koffi.types.size_t,
+    response_outbound_enqueue_block_count: "uint64_t",
+    deadletter_outbound_queue_capacity: koffi.types.size_t,
+    deadletter_outbound_queue_depth: koffi.types.size_t,
+    deadletter_outbound_queue_high_watermark: koffi.types.size_t,
+    deadletter_outbound_enqueue_block_count: "uint64_t",
+    remote_reply_timeout_count: "uint64_t",
+    late_remote_reply_drop_count: "uint64_t",
+    remote_outbound_queue_capacity: koffi.types.size_t,
+    remote_outbound_queue_depth: koffi.types.size_t,
+    remote_outbound_queue_high_watermark: koffi.types.size_t,
+    remote_outbound_queue_rejected_count: "uint64_t",
+    remote_outbound_expired_drop_count: "uint64_t",
+    endpoint_unavailable_count: "uint64_t",
+    remote_response_forwarded_count: "uint64_t",
+    remote_deadletter_forwarded_count: "uint64_t",
+    drained_route_count: koffi.types.size_t,
+    control_rejected_count: "uint64_t",
+    control_invalid_count: "uint64_t",
+    control_stale_generation_count: "uint64_t",
+    control_bad_state_count: "uint64_t",
+    control_io_count: "uint64_t",
+    remote_outbound_reply_reserve_slots: koffi.types.size_t,
+    remote_outbound_reply_reservation_reject_count: "uint64_t",
+    ingress_overload_mode: "uint32_t",
+    local_delivery_overload_mode: "uint32_t",
+    remote_outbound_overload_mode: "uint32_t",
+    monitor_event_emitted_count: "uint64_t",
+    monitor_event_dropped_count: "uint64_t",
+    monitor_event_emitted_lifetime_count: "uint64_t",
+    monitor_event_dropped_lifetime_count: "uint64_t",
+    local_work_queue_capacity: koffi.types.size_t,
+    local_work_queue_depth: koffi.types.size_t,
+    local_work_queue_high_watermark: koffi.types.size_t,
+    delivered_request_outbound_direct_write_count: "uint64_t",
+    response_outbound_direct_write_count: "uint64_t",
+    deadletter_outbound_direct_write_count: "uint64_t",
+    remote_outbound_one_way_drop_count: "uint64_t",
+});
+koffi.opaque("coakka_v2_runtime_t");
+function decodeText(value) {
+    return value ?? "";
+}
+export class NativeRuntimeBindings {
+    runtimeLibPath;
+    lib;
+    getAbiVersionFn;
+    getInfoFn;
+    createRuntimeFn;
+    destroyRuntimeFn;
+    getHostHandlesFn;
+    startRuntimeFn;
+    stopRuntimeFn;
+    getHealthFn;
+    getStatsFn;
+    getConfigFn;
+    submitEnvelopeFn;
+    applyControlEnvelopeFn;
+    constructor(runtimeLibPath) {
+        this.runtimeLibPath = runtimeLibPath;
+        this.lib = koffi.load(runtimeLibPath);
+        this.getAbiVersionFn = this.lib.func("uint32_t coakka_v2_runtime_get_abi_version(void)");
+        this.getInfoFn = this.lib.func("int coakka_v2_runtime_get_info(_Out_ coakka_v2_runtime_info_t *out_info)");
+        this.createRuntimeFn = this.lib.func("coakka_v2_runtime_t *coakka_v2_runtime_create(const coakka_v2_runtime_config_t *cfg)");
+        this.destroyRuntimeFn = this.lib.func("void coakka_v2_runtime_destroy(coakka_v2_runtime_t *rt)");
+        this.getHostHandlesFn = this.lib.func("int coakka_v2_runtime_get_host_handles(coakka_v2_runtime_t *rt, _Inout_ coakka_v2_host_handles_t *out_handles)");
+        this.startRuntimeFn = this.lib.func("int coakka_v2_runtime_start(coakka_v2_runtime_t *rt)");
+        this.stopRuntimeFn = this.lib.func("int coakka_v2_runtime_stop(coakka_v2_runtime_t *rt)");
+        this.getHealthFn = this.lib.func("int coakka_v2_runtime_get_health(coakka_v2_runtime_t *rt, _Out_ coakka_v2_runtime_health_t *out_health)");
+        this.getStatsFn = this.lib.func("int coakka_v2_runtime_get_stats(coakka_v2_runtime_t *rt, _Out_ coakka_v2_runtime_stats_t *out_stats)");
+        this.getConfigFn = this.lib.func("int coakka_v2_runtime_get_config(coakka_v2_runtime_t *rt, _Out_ coakka_v2_runtime_config_view_t *out_config)");
+        this.submitEnvelopeFn = this.lib.func("int coakka_v2_runtime_submit_envelope(coakka_v2_runtime_t *rt, const uint8_t *buf, size_t len)");
+        this.applyControlEnvelopeFn = this.lib.func("int coakka_v2_runtime_apply_control_envelope(coakka_v2_runtime_t *rt, const uint8_t *buf, size_t len)");
+    }
+    getAbiVersion() {
+        return this.getAbiVersionFn();
+    }
+    readRuntimeInfo() {
+        const info = { struct_size: koffi.sizeof(RuntimeInfoStruct) };
+        this.requireOk(this.getInfoFn(info), "runtime_get_info");
+        return {
+            abiVersion: Number(info.abi_version),
+            featureFlags: Number(info.feature_flags),
+            runtimeVersion: decodeText(info.runtime_version),
+            gitCommit: decodeText(info.git_commit),
+            southboundBackend: decodeText(info.southbound_backend),
+            allocatorBackend: decodeText(info.allocator_backend),
+            docsHint: decodeText(info.docs_hint),
+        };
+    }
+    createRuntime(config) {
+        const runtime = this.createRuntimeFn({
+            system_name: config.systemName,
+            node_id: config.nodeId,
+            strict_no_drop: config.strictNoDrop ? 1 : 0,
+            queue_capacity: config.queueCapacity,
+        });
+        if (runtime == null) {
+            throw new Error("coakka_v2_runtime_create returned null");
+        }
+        return runtime;
+    }
+    destroyRuntime(runtime) {
+        this.destroyRuntimeFn(runtime);
+    }
+    getHostHandles(runtime, flags) {
+        const handles = {
+            struct_size: koffi.sizeof(HostHandlesStruct),
+            flags,
+        };
+        this.requireOk(this.getHostHandlesFn(runtime, handles), "get_host_handles");
+        return {
+            flags: Number(handles.flags),
+            requestWriteFd: Number(handles.request_write_fd),
+            responseReadFd: Number(handles.response_read_fd),
+            deadletterReadFd: Number(handles.deadletter_read_fd),
+            controlWriteFd: Number(handles.control_write_fd),
+            monitorReadFd: Number(handles.monitor_read_fd),
+            deliveredRequestReadFd: Number(handles.delivered_request_read_fd),
+        };
+    }
+    startRuntime(runtime) {
+        this.requireOk(this.startRuntimeFn(runtime), "runtime_start");
+    }
+    stopRuntime(runtime) {
+        this.requireOk(this.stopRuntimeFn(runtime), "runtime_stop");
+    }
+    getHealth(runtime) {
+        const health = { struct_size: koffi.sizeof(RuntimeHealthStruct) };
+        this.requireOk(this.getHealthFn(runtime, health), "runtime_get_health");
+        return {
+            runtimeState: Number(health.runtime_state),
+            flags: Number(health.flags),
+            appliedGeneration: Number(health.applied_generation),
+        };
+    }
+    getStats(runtime) {
+        const stats = { struct_size: koffi.sizeof(RuntimeStatsStruct) };
+        this.requireOk(this.getStatsFn(runtime, stats), "runtime_get_stats");
+        return {
+            appliedGeneration: Number(stats.applied_generation),
+            routeCount: Number(stats.route_count),
+            runtimeState: Number(stats.runtime_state),
+            queueRejectedCount: Number(stats.queue_rejected_count),
+            routeMissCount: Number(stats.route_miss_count),
+            deadletterCount: Number(stats.deadletter_count),
+            deliveryFailedCount: Number(stats.delivery_failed_count),
+            controlRejectedCount: Number(stats.control_rejected_count),
+            monitorEventEmittedCount: Number(stats.monitor_event_emitted_count),
+            monitorEventDroppedCount: Number(stats.monitor_event_dropped_count),
+            monitorEventEmittedLifetimeCount: Number(stats.monitor_event_emitted_lifetime_count),
+            monitorEventDroppedLifetimeCount: Number(stats.monitor_event_dropped_lifetime_count),
+            localWorkQueueCapacity: Number(stats.local_work_queue_capacity),
+            localWorkQueueDepth: Number(stats.local_work_queue_depth),
+            localWorkQueueHighWatermark: Number(stats.local_work_queue_high_watermark),
+            deliveredRequestOutboundDirectWriteCount: Number(stats.delivered_request_outbound_direct_write_count),
+            responseOutboundDirectWriteCount: Number(stats.response_outbound_direct_write_count),
+            deadletterOutboundDirectWriteCount: Number(stats.deadletter_outbound_direct_write_count),
+            remoteOutboundQueueCapacity: Number(stats.remote_outbound_queue_capacity),
+            remoteOutboundQueueDepth: Number(stats.remote_outbound_queue_depth),
+            remoteOutboundQueueHighWatermark: Number(stats.remote_outbound_queue_high_watermark),
+            remoteOutboundQueueRejectedCount: Number(stats.remote_outbound_queue_rejected_count),
+            remoteOutboundExpiredDropCount: Number(stats.remote_outbound_expired_drop_count),
+            remoteOutboundReplyReserveSlots: Number(stats.remote_outbound_reply_reserve_slots),
+            remoteOutboundReplyReservationRejectCount: Number(stats.remote_outbound_reply_reservation_reject_count),
+            remoteOutboundOneWayDropCount: Number(stats.remote_outbound_one_way_drop_count),
+        };
+    }
+    getConfig(runtime) {
+        const config = { struct_size: koffi.sizeof(RuntimeConfigViewStruct) };
+        this.requireOk(this.getConfigFn(runtime, config), "runtime_get_config");
+        return {
+            systemName: decodeText(config.system_name),
+            nodeId: decodeText(config.node_id),
+            runtimeState: Number(config.runtime_state),
+            snapshotPresent: Number(config.snapshot_present) !== 0,
+            appliedGeneration: Number(config.applied_generation),
+            routeCount: Number(config.route_count),
+            southboundBindHost: decodeText(config.southbound_bind_host),
+            southboundBindPort: Number(config.southbound_bind_port),
+            effectiveIngressOverloadMode: Number(config.effective_ingress_overload_mode),
+            effectiveLocalDeliveryOverloadMode: Number(config.effective_local_delivery_overload_mode),
+            effectiveRemoteOutboundOverloadMode: Number(config.effective_remote_outbound_overload_mode),
+            effectiveRemoteOutboundReplyReserveSlots: Number(config.effective_remote_outbound_reply_reserve_slots),
+        };
+    }
+    submitEnvelope(runtime, bytes) {
+        this.requireOk(this.submitEnvelopeFn(runtime, bytes, bytes.byteLength), "submit_envelope");
+    }
+    applyControlEnvelope(runtime, bytes) {
+        this.requireOk(this.applyControlEnvelopeFn(runtime, bytes, bytes.byteLength), "apply_control_envelope");
+    }
+    requireOk(rc, what) {
+        if (rc !== COAKKA_OK) {
+            throw new Error(`${what} failed rc=${rc}`);
+        }
+    }
+}

package/native/.gitkeep

@@ -0,0 +1 @@
+

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "coakka-v2-connector-node",
+  "version": "1.3.1",
+  "description": "Node.js connector package for the CoAkka runtime v2",
+  "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": {
+    "prepare": "npm run build",
+    "build": "npm run stage:native && tsc -p tsconfig.build.json && node scripts/vendor-koffi.mjs",
+    "stage:native": "node scripts/stage-runtime-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",
+    "demo:web": "tsx ../examples/node-jvm-order-demo/service_a.ts",
+    "benchmark": "node --import tsx ../examples/node-jvm-order-demo/benchmark.ts",
+    "benchmark:matrix": "node --import tsx ../examples/node-jvm-order-demo/benchmark_matrix.ts"
+  },
+  "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.