@zlink-systems/zlink 0.17.3

package/native/src/addon_message_values.h

@@ -0,0 +1,345 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
+#pragma once
+
+#include "addon_common_api.h"
+
+#include <atomic>
+#include <cstring>
+#include <new>
+#include <vector>
+
+// A Message owns this frame. Its Buffer is only a JavaScript view of the
+// zlink_msg_t storage; it is never the owning payload allocation.
+struct native_message_frame_t
+{
+    native_message_frame_t () : references (1) {}
+    zlink_msg_t message;
+    std::atomic<uint32_t> references;
+};
+
+struct native_message_frame_handle_t
+{
+    explicit native_message_frame_handle_t (native_message_frame_t *frame_) : frame (frame_) {}
+    native_message_frame_t *frame;
+};
+
+class native_message_frame_pool_t
+{
+  public:
+    native_message_frame_pool_t () { frames_.reserve (64); }
+
+    ~native_message_frame_pool_t ()
+    {
+        for (size_t index = 0; index < frames_.size (); ++index)
+            delete frames_[index];
+    }
+
+    native_message_frame_t *acquire ()
+    {
+        if (frames_.empty ())
+            return new (std::nothrow) native_message_frame_t ();
+        native_message_frame_t *frame = frames_.back ();
+        frames_.pop_back ();
+        frame->references.store (1, std::memory_order_relaxed);
+        return frame;
+    }
+
+    void recycle (native_message_frame_t *frame)
+    {
+        // Routed single-part receive creates one frame per message. N-API
+        // receive and finalizers run on the owning JS thread, so a bounded
+        // thread-local reserve removes allocator traffic without a lock.
+        if (frames_.size () < 64) {
+            frames_.push_back (frame);
+            return;
+        }
+        delete frame;
+    }
+
+  private:
+    std::vector<native_message_frame_t *> frames_;
+};
+
+inline native_message_frame_pool_t &native_message_frame_pool ()
+{
+    static thread_local native_message_frame_pool_t pool;
+    return pool;
+}
+
+inline native_message_frame_t *acquire_native_message_frame ()
+{
+    return native_message_frame_pool ().acquire ();
+}
+
+inline void recycle_native_message_frame (native_message_frame_t *frame)
+{
+    native_message_frame_pool ().recycle (frame);
+}
+
+inline void retain_native_message_frame (native_message_frame_t *frame)
+{
+    frame->references.fetch_add (1, std::memory_order_relaxed);
+}
+
+inline void release_native_message_frame (native_message_frame_t *frame)
+{
+    if (!frame || frame->references.fetch_sub (1, std::memory_order_acq_rel) != 1)
+        return;
+    zlink_msg_close (&frame->message);
+    recycle_native_message_frame (frame);
+}
+
+inline native_message_frame_t *get_native_message_frame (napi_env env, napi_value value,
+                                                          const char *error_message)
+{
+    native_message_frame_handle_t *handle = NULL;
+    if (napi_get_value_external (env, value, reinterpret_cast<void **> (&handle)) != napi_ok
+        || !handle || !handle->frame) {
+        napi_throw_type_error (env, NULL, error_message);
+        return NULL;
+    }
+    return handle->frame;
+}
+
+inline void finalize_native_message_frame (napi_env env, void *data, void *hint)
+{
+    (void) env;
+    (void) hint;
+    native_message_frame_handle_t *handle =
+      static_cast<native_message_frame_handle_t *> (data);
+    if (!handle)
+        return;
+    release_native_message_frame (handle->frame);
+    delete handle;
+}
+
+inline void finalize_native_message_buffer (napi_env env, void *data, void *hint)
+{
+    (void) env;
+    (void) data;
+    release_native_message_frame (static_cast<native_message_frame_t *> (hint));
+}
+
+inline napi_value create_native_message_data_buffer (napi_env env, native_message_frame_t *frame)
+{
+    napi_value data;
+    retain_native_message_frame (frame);
+    const napi_status status = napi_create_external_buffer (
+      env, zlink_msg_size (&frame->message), zlink_msg_data (&frame->message),
+      finalize_native_message_buffer, frame, &data);
+    if (status != napi_ok) {
+        release_native_message_frame (frame);
+        napi_throw_error (env, NULL, "native message buffer creation failed");
+        return NULL;
+    }
+    return data;
+}
+
+inline napi_value create_native_message_frame_handle (napi_env env, native_message_frame_t *frame)
+{
+    native_message_frame_handle_t *handle =
+      new (std::nothrow) native_message_frame_handle_t (frame);
+    if (!handle) {
+        napi_throw_error (env, NULL, "native message frame handle allocation failed");
+        return NULL;
+    }
+    napi_value native_message;
+    retain_native_message_frame (frame);
+    const napi_status status = napi_create_external (
+      env, handle, finalize_native_message_frame, NULL, &native_message);
+    if (status != napi_ok) {
+        release_native_message_frame (frame);
+        delete handle;
+        napi_throw_error (env, NULL, "native message frame creation failed");
+        return NULL;
+    }
+    return native_message;
+}
+
+inline napi_value create_native_message_value (napi_env env, native_message_frame_t *frame,
+                                               bool include_data = true)
+{
+    napi_value data = NULL;
+    if (include_data) {
+        data = create_native_message_data_buffer (env, frame);
+        if (!data) {
+            release_native_message_frame (frame);
+            return NULL;
+        }
+    }
+    napi_value native_message = create_native_message_frame_handle (env, frame);
+    if (!native_message) {
+        release_native_message_frame (frame);
+        return NULL;
+    }
+
+    napi_value out;
+    napi_create_object (env, &out);
+    if (include_data)
+        napi_set_named_property (env, out, "data", data);
+    napi_set_named_property (env, out, "nativeMessage", native_message);
+    release_native_message_frame (frame);
+    return out;
+}
+
+inline napi_value move_message_to_native_value (napi_env env, zlink_msg_t *source)
+{
+    native_message_frame_t *frame = acquire_native_message_frame ();
+    if (!frame) {
+        napi_throw_error (env, NULL, "native message frame allocation failed");
+        return NULL;
+    }
+    if (zlink_msg_init (&frame->message) != 0) {
+        recycle_native_message_frame (frame);
+        return throw_last_error (env, "native message frame init failed");
+    }
+    if (zlink_msg_move (&frame->message, source) != 0) {
+        zlink_msg_close (&frame->message);
+        recycle_native_message_frame (frame);
+        return throw_last_error (env, "native message frame move failed");
+    }
+    return create_native_message_value (env, frame);
+}
+
+inline napi_value move_message_to_native_frame_value (napi_env env, zlink_msg_t *source)
+{
+    native_message_frame_t *frame = acquire_native_message_frame ();
+    if (!frame) {
+        napi_throw_error (env, NULL, "native message frame allocation failed");
+        return NULL;
+    }
+    if (zlink_msg_init (&frame->message) != 0) {
+        recycle_native_message_frame (frame);
+        return throw_last_error (env, "native message frame init failed");
+    }
+    if (zlink_msg_move (&frame->message, source) != 0) {
+        zlink_msg_close (&frame->message);
+        recycle_native_message_frame (frame);
+        return throw_last_error (env, "native message frame move failed");
+    }
+    napi_value native_message = create_native_message_frame_handle (env, frame);
+    release_native_message_frame (frame);
+    return native_message;
+}
+
+inline napi_value create_buffer_copy_or_empty (napi_env env, const void *data, size_t len)
+{
+    napi_value out = NULL;
+    const napi_status status =
+      napi_create_buffer_copy (env, len, len == 0 ? NULL : data, NULL, &out);
+    if (status != napi_ok) {
+        napi_throw_error (env, NULL, "message buffer allocation failed");
+        return NULL;
+    }
+    return out;
+}
+
+// Receive materialization copies payload bytes into a JS-owned Buffer.
+inline napi_value create_received_message_buffer (napi_env env, zlink_msg_t *msg)
+{
+    return create_buffer_copy_or_empty (env, zlink_msg_data (msg), zlink_msg_size (msg));
+}
+
+inline napi_value create_routing_id_value (napi_env env, const zlink_routing_id_t &rid)
+{
+    if (rid.size == 0) {
+        napi_value none;
+        napi_get_null (env, &none);
+        return none;
+    }
+    return create_buffer_copy_or_empty (env, rid.data, rid.size);
+}
+
+inline napi_value create_routing_id_value_reusing (
+  napi_env env, const zlink_routing_id_t &rid, napi_value candidate)
+{
+    if (candidate != NULL && rid.size > 0) {
+        bool is_buffer = false;
+        if (napi_is_buffer (env, candidate, &is_buffer) == napi_ok && is_buffer) {
+            void *data = NULL;
+            size_t size = 0;
+            if (napi_get_buffer_info (env, candidate, &data, &size) == napi_ok
+                && size == rid.size
+                && std::memcmp (data, rid.data, size) == 0) {
+                // HOT PATH: stable routed peers repeat the same small identity
+                // on every receive. Reuse the caller-held Buffer after byte
+                // validation instead of allocating and copying it again.
+                return candidate;
+            }
+        }
+    }
+    return create_routing_id_value (env, rid);
+}
+
+enum message_snapshot_flags_t
+{
+    MESSAGE_SNAPSHOT_DEFAULT = 0,
+    MESSAGE_SNAPSHOT_ALWAYS_REF_COUNT = 1 << 0,
+    MESSAGE_SNAPSHOT_ALWAYS_PROPERTIES = 1 << 1
+};
+
+// The Core raw API exposes no message property API, so the binding derives its
+// synthetic routed identity properties itself and avoids repeated native
+// property probes on every data-only receive.
+inline napi_value create_message_properties_snapshot (napi_env env,
+                                                      const zlink_routing_id_t *routing_id,
+                                                      zlink_msg_t *msg,
+                                                      bool force)
+{
+    (void) msg;
+    const bool has_routing_id_bytes = routing_id && routing_id->size > 0;
+
+    if (!has_routing_id_bytes && !force)
+        return NULL;
+
+    napi_value props;
+    napi_create_object (env, &props);
+
+    if (has_routing_id_bytes) {
+        napi_value out;
+        napi_create_string_utf8 (env, reinterpret_cast<const char *> (routing_id->data),
+                                 routing_id->size, &out);
+        napi_set_named_property (env, props, "Routing-Id", out);
+        napi_set_named_property (env, props, "Identity", out);
+    }
+
+    return props;
+}
+
+inline napi_value create_message_snapshot_value (napi_env env,
+                                                 const zlink_routing_id_t *routing_id,
+                                                 zlink_msg_t *msg,
+                                                 int flags = MESSAGE_SNAPSHOT_DEFAULT)
+{
+    napi_value obj;
+    napi_create_object (env, &obj);
+
+    // A freshly received message is solely owned by the binding, so its
+    // reference count is always 1 on the receive path and the "refCount" field
+    // is omitted. Only query the library when a caller explicitly asks for the
+    // count to be surfaced by an explicit diagnostic path.
+    int refcnt = 1;
+    if (flags & MESSAGE_SNAPSHOT_ALWAYS_REF_COUNT) {
+        zlink_config_result_t refcnt_err = ZLINK_CONFIG_OK;
+        refcnt = zlink_msg_refcnt (msg, &refcnt_err);
+        if (refcnt_err != ZLINK_CONFIG_OK)
+            return throw_last_error (env, "message refcnt failed");
+    }
+
+    napi_value data = create_received_message_buffer (env, msg);
+    if (!data)
+        return NULL;
+
+    napi_set_named_property (env, obj, "data", data);
+    if (refcnt != 1 || (flags & MESSAGE_SNAPSHOT_ALWAYS_REF_COUNT)) {
+        napi_value ref_count;
+        napi_create_int32 (env, refcnt, &ref_count);
+        napi_set_named_property (env, obj, "refCount", ref_count);
+    }
+    napi_value props = create_message_properties_snapshot (
+      env, routing_id, msg, (flags & MESSAGE_SNAPSHOT_ALWAYS_PROPERTIES) != 0);
+    if (props)
+        napi_set_named_property (env, obj, "properties", props);
+    return obj;
+}

package/native/src/addon_monitor_status_values.h

@@ -0,0 +1,71 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
+#pragma once
+
+#include "addon_common_api.h"
+
+inline napi_value create_monitor_status_value (napi_env env,
+                                               const zlink_monitor_status_t &snapshot)
+{
+    napi_value obj;
+    napi_create_object (env, &obj);
+    set_uint32_property (env, obj, "abiVersion", snapshot.abi_version);
+    set_uint32_property (env, obj, "structSize", snapshot.struct_size);
+    set_uint32_property (env, obj, "sourceKind", static_cast<uint32_t> (snapshot.source_kind));
+    set_uint32_property (env, obj, "stateFlags", snapshot.state_flags);
+    set_uint32_property (env, obj, "detailFlags", snapshot.detail_flags);
+    set_uint64_bigint_property (env, obj, "sndPendingMsgs", snapshot.snd_pending_msgs);
+    set_uint64_bigint_property (env, obj, "rcvPendingMsgs", snapshot.rcv_pending_msgs);
+    set_uint64_bigint_property (env, obj, "sndPendingBytes", snapshot.snd_pending_bytes);
+    set_uint64_bigint_property (env, obj, "rcvPendingBytes", snapshot.rcv_pending_bytes);
+    napi_value auto_hwm_enabled;
+    napi_get_boolean (env, snapshot.auto_hwm_enabled != 0, &auto_hwm_enabled);
+    napi_set_named_property (env, obj, "autoHwmEnabled", auto_hwm_enabled);
+    set_uint32_property (env, obj, "autoHwmProfile", snapshot.auto_hwm_profile);
+    set_uint32_property (env, obj, "autoHwmRole", snapshot.auto_hwm_role);
+    set_uint32_property (env, obj, "autoHwmPolicyClass", snapshot.auto_hwm_policy_class);
+    set_uint64_bigint_property (env, obj, "autoHwmPlannedSndHwmBytes",
+                                snapshot.auto_hwm_planned_sndhwm_bytes);
+    set_uint64_bigint_property (env, obj, "autoHwmPlannedRcvHwmBytes",
+                                snapshot.auto_hwm_planned_rcvhwm_bytes);
+    set_uint64_bigint_property (env, obj, "autoHwmAppliedSndHwmBytes",
+                                snapshot.auto_hwm_applied_sndhwm_bytes);
+    set_uint64_bigint_property (env, obj, "autoHwmAppliedRcvHwmBytes",
+                                snapshot.auto_hwm_applied_rcvhwm_bytes);
+    set_int64_property (env, obj, "autoHwmEffectiveSndBuf", snapshot.auto_hwm_effective_sndbuf);
+    set_int64_property (env, obj, "autoHwmEffectiveRcvBuf", snapshot.auto_hwm_effective_rcvbuf);
+    set_uint64_bigint_property (env, obj, "autoHwmLastRecalcMs",
+                                snapshot.auto_hwm_last_recalc_ms);
+    set_uint32_property (env, obj, "autoHwmLastRecalcReason", snapshot.auto_hwm_last_recalc_reason);
+    set_uint32_property (env, obj, "autoHwmSendBlockedRatioPpm",
+                         snapshot.auto_hwm_send_blocked_ratio_ppm);
+    set_uint64_bigint_property (env, obj, "autoHwmDeferredSndHwmBytes",
+                                snapshot.auto_hwm_deferred_sndhwm_bytes);
+    set_uint64_bigint_property (env, obj, "autoHwmDeferredRcvHwmBytes",
+                                snapshot.auto_hwm_deferred_rcvhwm_bytes);
+    napi_value deferred_snd_valid;
+    napi_get_boolean (env, snapshot.auto_hwm_deferred_sndhwm_valid != 0, &deferred_snd_valid);
+    napi_set_named_property (env, obj, "autoHwmDeferredSndHwmValid", deferred_snd_valid);
+    napi_value deferred_rcv_valid;
+    napi_get_boolean (env, snapshot.auto_hwm_deferred_rcvhwm_valid != 0, &deferred_rcv_valid);
+    napi_set_named_property (env, obj, "autoHwmDeferredRcvHwmValid", deferred_rcv_valid);
+    set_uint64_bigint_property (env, obj, "sndBytesInFlight", snapshot.snd_bytes_in_flight);
+    set_uint64_bigint_property (env, obj, "rcvBytesInFlight", snapshot.rcv_bytes_in_flight);
+    set_uint64_bigint_property (env, obj, "minimumCoreMessageChargeBytes",
+                                snapshot.minimum_core_message_charge_bytes);
+    set_uint64_bigint_property (env, obj, "oversizeMessageAdmissionCount",
+                                snapshot.oversize_message_admission_count);
+    set_uint64_bigint_property (env, obj, "oversizeMessageAdmissionMaxBytes",
+                                snapshot.oversize_message_admission_max_bytes);
+    set_uint64_bigint_property (env, obj, "flowPausedConnections",
+                                snapshot.flow_paused_connections);
+    set_uint64_bigint_property (env, obj, "flowPauseAppliedTotal",
+                                snapshot.flow_pause_applied_total);
+    set_uint64_bigint_property (env, obj, "flowResumeAppliedTotal",
+                                snapshot.flow_resume_applied_total);
+    set_uint64_bigint_property (env, obj, "flowStateStaleTotal",
+                                snapshot.flow_state_stale_total);
+    set_uint64_bigint_property (env, obj, "flowPauseDurationMs",
+                                snapshot.flow_pause_duration_ms);
+    return obj;
+}

package/native/src/addon_submit_results.h

@@ -0,0 +1,30 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
+#pragma once
+
+#include "addon_common_api.h"
+
+#include <errno.h>
+
+inline int preserve_try_send_result (int result)
+{
+    if (result >= ZLINK_SUBMIT_OK)
+        return result;
+
+    switch (zlink_errno ()) {
+        case EAGAIN:
+            return ZLINK_SUBMIT_BACKPRESSURED;
+#ifdef ENOTCONN
+        case ENOTCONN:
+#endif
+#ifdef EHOSTUNREACH
+        case EHOSTUNREACH:
+#endif
+#ifdef ETIMEDOUT
+        case ETIMEDOUT:
+#endif
+            return ZLINK_SUBMIT_NOT_CONNECTED;
+        default:
+            return -1;
+    }
+}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@zlink-systems/zlink",
+  "version": "0.17.3",
+  "description": "zlink Node.js bindings \u2014 high-performance async messaging library",
+  "license": "MPL-2.0",
+  "author": "Zlink Systems",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zlink-systems/zlink.git",
+    "directory": "bindings/node"
+  },
+  "homepage": "https://zlink.systems/",
+  "bugs": {
+    "url": "https://github.com/zlink-systems/zlink/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/**/*",
+    "prebuilds/**/zlink.node",
+    "prebuilds/linux-*/libzlink.so.*.*.*",
+    "prebuilds/darwin-*/*.dylib",
+    "prebuilds/win32-*/*.dll",
+    "provenance/core-package-provenance.json",
+    "native/src/**/*",
+    "scripts/install.js",
+    "scripts/resolve_core.js",
+    "binding.gyp",
+    "README.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "gypfile": true,
+  "scripts": {
+    "install": "node scripts/install.js",
+    "clean": "node scripts/clean.js",
+    "build": "npm run clean && npm run build:incremental",
+    "build:incremental": "tsc -p tsconfig.json && node scripts/generate_esm_wrapper.js && tsc -p tsconfig.tools.json && node scripts/link_dist_tools.js",
+    "verify:prebuilds": "node scripts/verify_prebuilds.js",
+    "rebuild-native": "./scripts/rebuild_native.sh",
+    "perf:single": "./perf/single/run_benchmarks.sh",
+    "perf:multi": "./perf/multi/run_benchmarks.sh",
+    "perf": "./perf/run_benchmarks.sh",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "typecheck:src-review": "tsc -p tsconfig.src-review.json",
+    "prepare": "npm run build",
+    "pretest": "npm run build && npm run typecheck && npm run rebuild-native",
+    "test": "./tests/run_tests.sh",
+    "presamples": "npm run build && npm run rebuild-native",
+    "samples": "./samples/run_samples.sh"
+  },
+  "dependencies": {
+    "@types/node": "^22.15.30"
+  },
+  "devDependencies": {
+    "node-gyp": "^12.4.0",
+    "typescript": "^5.8.3"
+  }
+}

package/provenance/core-package-provenance.json

@@ -0,0 +1,73 @@
+{
+  "schema": 1,
+  "package": "zlink-core",
+  "version": "0.17.3",
+  "abiMajor": 0,
+  "runtime": {
+    "path": "lib/libzlink.so.0.17.3",
+    "sha256": "dc518b5fde5b6fba348612774cb5d0976a9867890604430ba737b0b3bb565d40",
+    "soname": "libzlink.so.0"
+  },
+  "source": {
+    "revision": "0761c1d4d06cec7fb207178e12fc28e5f2557c97",
+    "dirty": false
+  },
+  "release": {
+    "tag": "core/v0.17.3",
+    "checksumsSha256": "c92058fba62fb9087a3a4220f0f9bc12816b5fcfe31c05edbea6929bcf023ed8"
+  },
+  "files": [
+    {
+      "path": "include/zlink_enum.h",
+      "sha256": "a7d0fec0f0c6a35cd21d8a25adda44d4ec2ab4bcd66854fbd9271c6445ee3e22"
+    },
+    {
+      "path": "include/zlink_errno.h",
+      "sha256": "aad14ff78cd7a890b660163387290070ab60b6bcea9c6627ceb64094013b3faa"
+    },
+    {
+      "path": "include/zlink.h",
+      "sha256": "2f01c667960154f79c0e2c5c10a7bba72b129d025230b0c3efb951456cd420ea"
+    },
+    {
+      "path": "include/zlink/common.h",
+      "sha256": "8adb46869a3fb570e7a46a9c415f2dedb15fee1e2b3cfb640959f38876444ef4"
+    },
+    {
+      "path": "include/zlink/core/api.h",
+      "sha256": "8a6cd736ab2bd477edd5d8845445c844682a2783b5e10b313aab5c5b76c560f1"
+    },
+    {
+      "path": "include/zlink/eventing/api.h",
+      "sha256": "c2444588975fafd996c5154e2f06a48d6b2bae4dbd7af5e4a08cb3c593684341"
+    },
+    {
+      "path": "include/zlink/message/api.h",
+      "sha256": "2bccce404fcda4da6d20c82e74c33993453f3a4fd4b2b1aa1578f6e32b0ba525"
+    },
+    {
+      "path": "include/zlink/socket/api.h",
+      "sha256": "257ea1f9af25f402087f8052750131030fb89273b12944713ef0a50eded89dad"
+    },
+    {
+      "path": "lib/cmake/zlink/zlinkConfig.cmake",
+      "sha256": "b462641e7111910a0b0ed581c060e7846b2de6879683cfe9cc976171d7b1ba41"
+    },
+    {
+      "path": "lib/cmake/zlink/zlinkConfigVersion.cmake",
+      "sha256": "755d8eef89428cfba9d3077400112f93666f9a59f93c01e61aed6dc730529ed8"
+    },
+    {
+      "path": "lib/libzlink.so.0.17.3",
+      "sha256": "dc518b5fde5b6fba348612774cb5d0976a9867890604430ba737b0b3bb565d40"
+    },
+    {
+      "path": "share/zlink/release-checksums.txt",
+      "sha256": "c92058fba62fb9087a3a4220f0f9bc12816b5fcfe31c05edbea6929bcf023ed8"
+    },
+    {
+      "path": "share/zlink/release-provenance.txt",
+      "sha256": "c1e9373a9f7d65eefac89cd27685b3358c0147b9a7eb0b7a8bd7d8a841765a96"
+    }
+  ]
+}

package/scripts/install.js

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: MPL-2.0
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const packageRoot = path.resolve(__dirname, '..');
+const prebuiltAddon = path.join(
+  packageRoot,
+  'prebuilds',
+  `${process.platform}-${process.arch}`,
+  'zlink.node'
+);
+
+if (process.env.ZLINK_SKIP_NATIVE_INSTALL === '1') {
+  process.exit(0);
+}
+
+// Published packages carry platform prebuilds. A source checkout may not, so
+// retain node-gyp as the development fallback without rebuilding consumers.
+if (fs.existsSync(prebuiltAddon)) {
+  process.exit(0);
+}
+
+const nodeGyp = process.platform === 'win32' ? 'node-gyp.cmd' : 'node-gyp';
+const result = spawnSync(nodeGyp, ['rebuild'], {
+  cwd: packageRoot,
+  stdio: 'inherit',
+  shell: process.platform === 'win32'
+});
+
+if (result.error) {
+  throw result.error;
+}
+process.exit(result.status === null ? 1 : result.status);