Native Addon

Native Addon

The ICMP probe is a small C addon built with N-API. It is ABI-stable, so one compiled binary works across Node.js versions.

Source layout

File	Role
native/src/addon.c	N-API binding, async work, building the result object
native/src/socket.c / socket.h	Open socket (DGRAM then RAW), send, receive, timeout, TTL
native/src/icmp.c / icmp.h	Build echo packets, parse replies, map ICMP errors to reasons
binding.gyp	node-gyp build configuration
src/utils/probes/ping.ts	Loads the addon, detects IP version, humanizes errors
src/probes/ping.ts	pingProbe() used by the monitor
test-icmp.js	Manual smoke test for the addon

Installing

When you run npm install pingflux, node-gyp-build looks for a binary in this order:

1. prebuilds/<platform>-<arch>/*.node, a prebuilt binary
2. build/Release/pingflux_icmp.node, a local build

If neither exists, the install step compiles the addon from source.

Building from source

Requirements: gcc, make, python3, Node.js headers (downloaded by node-gyp).

git clone https://github.com/AmirVoid12/pingflux.git
cd pingflux
npm install
npx node-gyp rebuild
npm run build

Testing the addon directly

node test-icmp.js

It covers IPv4, IPv6, several packets with aggregated stats, an unreachable host, and a low TTL that triggers Time Exceeded.

const addon = require("./build/Release/pingflux_icmp.node");

const result = await addon.pingIcmp(
  "1.1.1.1",          // host
  addon.IP_VERSION_4, // ip version
  1000,               // icmp id
  1,                  // first sequence number
  2000,               // timeout in ms
  5,                  // packet count (1-64)
  0                   // ttl, 0 = system default
);

Function signature

pingIcmp(host, ipVersion, id, seq, timeoutMs, count, ttl) -> Promise<Result>

Argument	Type	Notes
host	string	IPv4 or IPv6 literal, at most 63 characters
ipVersion	number	IP_VERSION_4 or IP_VERSION_6
id	number	ICMP identifier, masked to 16 bits
seq	number	Starting sequence number, masked to 16 bits
timeoutMs	number	Per-packet timeout, default 2000
count	number	Clamped to 1 through 64, default 1
ttl	number	0 keeps the system default

Prebuilds

Prebuilt binaries are made with prebuildify so users do not need a compiler:

npx prebuildify --napi --strip

glibc and musl (Alpine) binaries are not compatible with each other, so build both if you want to support Alpine.