website-healthcheck

Hybrid Node.js + Go diagnostics toolkit for websites/hosts.

It’s designed like a small “network health” library:

• DNS resolution (A/AAAA)
• ICMP ping (via a small Go binary)
• TCP connect (port open + latency)
• HTTP/HTTPS response (status, headers, latency)
• TLS/SSL certificate info (validity dates, issuer/subject)

Install

After you publish to npm, users install it like any other package:

npm install website-healthcheck

Native ping binary (no Go required for users)

• DNS/TCP/HTTP/SSL run in pure Node.js.
• Ping runs via a prebuilt native binary shipped with the package (Windows/Linux/macOS; x64 + arm64).

Go is only needed by you (the maintainer) when building the release binaries before publishing.

Quick start (recommended)

CommonJS project

const { checkWebsite } = require("website-healthcheck");

(async () => {
  const report = await checkWebsite("example.com", {
    dns: {},
    ping: { count: 3, timeoutMs: 2000, intervalMs: 200, privileged: false },
    tcp: { port: 443, timeoutMs: 2500 },
    http: { url: "https://example.com", timeoutMs: 8000, followRedirects: true },
    ssl: { host: "example.com", port: 443, servername: "example.com", timeoutMs: 4000 }
  });

  console.log(JSON.stringify(report, null, 2));
})();

ESM project ("type": "module")

import pkg from "website-healthcheck";
const { checkWebsite } = pkg;

const report = await checkWebsite("example.com", {
  dns: {},
  http: { url: "https://example.com", timeoutMs: 8000, followRedirects: true }
});

console.log(report);

API

checkWebsite(target, options)

Runs multiple checks in parallel and returns a combined report.

options supports:

• dns: { families?: (4|6)[] }
• ping: { count?: number, timeoutMs?: number, intervalMs?: number, privileged?: boolean }
• tcp: { port?: number, timeoutMs?: number }
• http: { url?: string, timeoutMs?: number, method?: string, followRedirects?: boolean, headers?: Record<string,string> }
• ssl: { host?: string, port?: number, servername?: string, timeoutMs?: number, rejectUnauthorized?: boolean }

Individual checks

You can also call modules directly:

const { dnsCheck, tcpCheck, httpCheck, sslCheck, pingCheck } = require("website-healthcheck");

const dns = await dnsCheck("example.com");
const tcp = await tcpCheck("example.com", { port: 443 });
const http = await httpCheck("https://example.com", { followRedirects: true });
const ssl = await sslCheck("example.com", { servername: "example.com" });
const ping = await pingCheck("example.com", { count: 2, privileged: false });

CLI

After install, run via npx:

npx website-healthcheck example.com --port 443 --url https://example.com --ping-count 3

Or run the shorter alias:

npx wac example.com --port 443 --url https://example.com --ping-count 3

Or if installed as a dependency:

./node_modules/.bin/wac example.com --port 443 --url https://example.com --ping-count 3

Output shape (high level)

checkWebsite() returns:

• target: input target
• startedAt: ISO timestamp
• results.dns | ping | tcp | http | ssl: each module returns { ok, latencyMs, ... } plus error when it fails

Troubleshooting

Ping fails with “Failed to execute .../wac-ping(.exe)”

• This means the native binary for your platform wasn’t included in the install.
• Ensure you installed the package normally (not from a partial copy).
• If you are the maintainer, rebuild native binaries before publishing:

npm run build:natives

Ping permissions

ICMP can require admin/root privileges depending on OS and ping mode. Try privileged: false first (it often works on Windows), and if needed run your terminal as Administrator.

Local development (this repo)

npm run build:natives
npm test