@bun-win32/netdiag 1.0.0

package/sockets.ts

@@ -0,0 +1,179 @@
+import type { Pointer } from 'bun:ffi';
+
+import { ipv4FromU32, ipv6FromBytes, portFromNetworkOrder } from './addr';
+import { AF_INET, AF_INET6, type AddressFamilyName, TCP_TABLE_OWNER_MODULE_ALL, TCP_TABLE_OWNER_PID_ALL, TCPIP_OWNER_MODULE_INFO_BASIC, tcpStateName, UDP_TABLE_OWNER_PID } from './constants';
+import { Iphlpapi, Kernel32, readWideAt, SizedBufferState } from './win32';
+
+// Fixed x64 row strides (do NOT derive from buffer size — net-xray ground truth).
+const TCP4_PID_ROW = 24; // MIB_TCPROW_OWNER_PID
+const TCP6_PID_ROW = 56; // MIB_TCP6ROW_OWNER_PID
+const TCP4_MODULE_ROW = 160; // MIB_TCPROW_OWNER_MODULE (24 basic + liCreateTimestamp(8) + OwningModuleInfo[16](128))
+const TCP6_MODULE_ROW = 192; // MIB_TCP6ROW_OWNER_MODULE (56 basic + 8 + 128)
+const UDP4_ROW = 12; // MIB_UDPROW_OWNER_PID
+const UDP6_ROW = 28; // MIB_UDP6ROW_OWNER_PID
+const PROCESS_QUERY_LIMITED_INFORMATION = 0x0000_1000;
+
+export type NameResolution = 'none' | 'module' | 'image';
+
+export interface SocketOptions {
+  family?: AddressFamilyName;
+  resolveNames?: NameResolution;
+}
+
+export interface TcpConnection {
+  family: 'ipv4' | 'ipv6';
+  localAddress: string;
+  localPort: number;
+  remoteAddress: string;
+  remotePort: number;
+  state: string;
+  pid: number;
+  processName?: string;
+}
+
+export interface UdpEndpoint {
+  family: 'ipv4' | 'ipv6';
+  localAddress: string;
+  localPort: number;
+  pid: number;
+  processName?: string;
+}
+
+const tcp4State = new SizedBufferState();
+const tcp6State = new SizedBufferState();
+const udp4State = new SizedBufferState();
+const udp6State = new SizedBufferState();
+const moduleState = new SizedBufferState(0x0000_2000);
+const imageNameBuffer = Buffer.allocUnsafeSlow(0x0000_0420); // 528 wchars, own buffer
+const imageSizeBuffer = Buffer.allocUnsafeSlow(4);
+
+// The owning MODULE name (iphlpapi-only moat) — pModuleName is an offset-pointer INTO the out buffer.
+function resolveModuleName(rowPointer: Pointer): string {
+  try {
+    moduleState.fill((dataPointer, sizePointer) => Iphlpapi.GetOwnerModuleFromTcpEntry(rowPointer, TCPIP_OWNER_MODULE_INFO_BASIC, dataPointer, sizePointer));
+  } catch {
+    return ''; // ERROR_ACCESS_DENIED for other-user / protected PIDs — fall back to the bare PID
+  }
+  const base = moduleState.buffer;
+  const moduleNamePointer = Number(base.readBigUInt64LE(0)); // TCPIP_OWNER_MODULE_BASIC_INFO.pModuleName
+  return moduleNamePointer === 0 ? '' : readWideAt(base, moduleNamePointer - Number(base.ptr));
+}
+
+// The full image basename via kernel32 (the richer, cross-DLL mode).
+function resolveImageName(pid: number): string {
+  if (pid <= 4) return pid === 4 ? 'System' : 'Idle';
+  const handle = Kernel32.OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, 0, pid);
+  if (handle === 0n) return '';
+  try {
+    imageSizeBuffer.writeUInt32LE(0x0000_0210, 0); // 528 chars in/out
+    if (!Kernel32.QueryFullProcessImageNameW(handle, 0, imageNameBuffer.ptr, imageSizeBuffer.ptr)) return '';
+    const path = imageNameBuffer.toString('utf16le', 0, imageSizeBuffer.readUInt32LE(0) * 2);
+    const slash = path.lastIndexOf('\\');
+    return slash < 0 ? path : path.slice(slash + 1);
+  } finally {
+    Kernel32.CloseHandle(handle);
+  }
+}
+
+function decodeTcp(view: DataView, base: Buffer, family: 'ipv4' | 'ipv6', rowStride: number, headerOffset: number, resolveNames: NameResolution, cache: Map<number, string>, result: TcpConnection[]): void {
+  const count = view.getUint32(0, true);
+  for (let index = 0; index < count; index++) {
+    const offset = headerOffset + index * rowStride;
+    let state: number;
+    let localAddress: string;
+    let localPort: number;
+    let remoteAddress: string;
+    let remotePort: number;
+    let pid: number;
+    if (family === 'ipv4') {
+      state = view.getUint32(offset, true);
+      localAddress = ipv4FromU32(view.getUint32(offset + 4, true));
+      localPort = portFromNetworkOrder(view.getUint32(offset + 8, true));
+      remoteAddress = ipv4FromU32(view.getUint32(offset + 12, true));
+      remotePort = portFromNetworkOrder(view.getUint32(offset + 16, true));
+      pid = view.getUint32(offset + 20, true);
+    } else {
+      localAddress = ipv6FromBytes(base, offset);
+      localPort = portFromNetworkOrder(view.getUint32(offset + 20, true));
+      remoteAddress = ipv6FromBytes(base, offset + 24);
+      remotePort = portFromNetworkOrder(view.getUint32(offset + 44, true));
+      state = view.getUint32(offset + 48, true);
+      pid = view.getUint32(offset + 52, true);
+    }
+    let processName: string | undefined;
+    if (resolveNames !== 'none') {
+      processName = cache.get(pid);
+      if (processName === undefined) {
+        processName = resolveNames === 'module' ? resolveModuleName(base.subarray(offset, offset + rowStride).ptr) : resolveImageName(pid);
+        cache.set(pid, processName);
+      }
+    }
+    result.push({ family, localAddress, localPort, remoteAddress, remotePort, state: tcpStateName(state), pid, processName });
+  }
+}
+
+function decodeUdp(view: DataView, base: Buffer, family: 'ipv4' | 'ipv6', rowStride: number, resolveNames: NameResolution, cache: Map<number, string>, result: UdpEndpoint[]): void {
+  const count = view.getUint32(0, true);
+  for (let index = 0; index < count; index++) {
+    const offset = 4 + index * rowStride;
+    let localAddress: string;
+    let localPort: number;
+    let pid: number;
+    if (family === 'ipv4') {
+      localAddress = ipv4FromU32(view.getUint32(offset, true));
+      localPort = portFromNetworkOrder(view.getUint32(offset + 4, true));
+      pid = view.getUint32(offset + 8, true);
+    } else {
+      localAddress = ipv6FromBytes(base, offset);
+      localPort = portFromNetworkOrder(view.getUint32(offset + 20, true));
+      pid = view.getUint32(offset + 24, true);
+    }
+    // UDP has no owning-module table here → process names use the kernel32 image basename.
+    let processName: string | undefined;
+    if (resolveNames !== 'none') {
+      processName = cache.get(pid);
+      if (processName === undefined) {
+        processName = resolveImageName(pid);
+        cache.set(pid, processName);
+      }
+    }
+    result.push({ family, localAddress, localPort, pid, processName });
+  }
+}
+
+/** Socket→PID(+module) over GetExtendedTcpTable — one syscall, no netstat -ano parse. IPv4 + IPv6. */
+export function tcpConnections(options: SocketOptions = {}): TcpConnection[] {
+  const family = options.family ?? 'all';
+  const resolveNames = options.resolveNames ?? 'none';
+  const useModule = resolveNames === 'module';
+  const tableClass = useModule ? TCP_TABLE_OWNER_MODULE_ALL : TCP_TABLE_OWNER_PID_ALL;
+  const headerOffset = useModule ? 8 : 4; // OWNER_MODULE rows are 8-aligned (liCreateTimestamp) → table[] starts at +8, not +4
+  const cache = new Map<number, string>();
+  const result: TcpConnection[] = [];
+  if (family === 'all' || family === 'ipv4') {
+    const view = tcp4State.fill((dataPointer, sizePointer) => Iphlpapi.GetExtendedTcpTable(dataPointer, sizePointer, 0, AF_INET, tableClass, 0));
+    decodeTcp(view, tcp4State.buffer, 'ipv4', useModule ? TCP4_MODULE_ROW : TCP4_PID_ROW, headerOffset, resolveNames, cache, result);
+  }
+  if (family === 'all' || family === 'ipv6') {
+    const view = tcp6State.fill((dataPointer, sizePointer) => Iphlpapi.GetExtendedTcpTable(dataPointer, sizePointer, 0, AF_INET6, tableClass, 0));
+    decodeTcp(view, tcp6State.buffer, 'ipv6', useModule ? TCP6_MODULE_ROW : TCP6_PID_ROW, headerOffset, resolveNames, cache, result);
+  }
+  return result;
+}
+
+/** UDP endpoints with owning PID over GetExtendedUdpTable. IPv4 + IPv6. */
+export function udpListeners(options: SocketOptions = {}): UdpEndpoint[] {
+  const family = options.family ?? 'all';
+  const resolveNames = options.resolveNames ?? 'none';
+  const cache = new Map<number, string>();
+  const result: UdpEndpoint[] = [];
+  if (family === 'all' || family === 'ipv4') {
+    const view = udp4State.fill((dataPointer, sizePointer) => Iphlpapi.GetExtendedUdpTable(dataPointer, sizePointer, 0, AF_INET, UDP_TABLE_OWNER_PID, 0));
+    decodeUdp(view, udp4State.buffer, 'ipv4', UDP4_ROW, resolveNames, cache, result);
+  }
+  if (family === 'all' || family === 'ipv6') {
+    const view = udp6State.fill((dataPointer, sizePointer) => Iphlpapi.GetExtendedUdpTable(dataPointer, sizePointer, 0, AF_INET6, UDP_TABLE_OWNER_PID, 0));
+    decodeUdp(view, udp6State.buffer, 'ipv6', UDP6_ROW, resolveNames, cache, result);
+  }
+  return result;
+}

package/stats.ts

@@ -0,0 +1,220 @@
+import { addressFamilyValue } from './constants';
+import { Iphlpapi, mibTable, readWideAt, Win32Error } from './win32';
+
+type StatsFamily = 'ipv4' | 'ipv6';
+
+// MIB_TCPSTATS / MIB_IPSTATS / MIB_UDPSTATS are flat DWORD arrays (Ex variants take a family).
+const TCP_STATS_SIZE = 60;
+const IP_STATS_SIZE = 92;
+const UDP_STATS_SIZE = 20;
+
+// MIB_IF_TABLE2 { ULONG NumEntries; MIB_IF_ROW2 Table[] } — rows 8-aligned; GetIfTable2 self-allocates → mibTable.
+const IF_TABLE_FIRST_ROW = 8;
+const IF_ROW_SIZE = 1352; // sizeof(MIB_IF_ROW2) x64 — verified vs alias decode + climbing octets (S9.2)
+const IF_ROW_INTERFACE_INDEX = 8;
+const IF_ROW_ALIAS = 28; // WCHAR Alias[257]
+const IF_ROW_MTU = 1124;
+const IF_ROW_OPER_STATUS = 1156;
+const IF_ROW_IN_OCTETS = 1208; // ULONG64
+const IF_ROW_IN_DISCARDS = 1232;
+const IF_ROW_IN_ERRORS = 1240;
+const IF_ROW_OUT_OCTETS = 1280;
+const IF_ROW_OUT_DISCARDS = 1304;
+const IF_ROW_OUT_ERRORS = 1312;
+
+const OPER_STATUS_NAMES: ReadonlyMap<number, string> = new Map([
+  [1, 'up'],
+  [2, 'down'],
+  [3, 'testing'],
+  [4, 'unknown'],
+  [5, 'dormant'],
+  [6, 'not-present'],
+  [7, 'lower-layer-down'],
+]);
+
+export interface TcpStatistics {
+  activeOpens: number;
+  passiveOpens: number;
+  attemptFails: number;
+  establishedResets: number;
+  currentEstablished: number;
+  inSegments: number;
+  outSegments: number;
+  retransmittedSegments: number;
+  inErrors: number;
+  outResets: number;
+}
+
+export interface IpStatistics {
+  inReceives: number;
+  inHeaderErrors: number;
+  inAddressErrors: number;
+  forwardedDatagrams: number;
+  inDiscards: number;
+  inDelivers: number;
+  outRequests: number;
+  outDiscards: number;
+  outNoRoutes: number;
+  reassemblyRequired: number;
+  reassemblyOk: number;
+  fragmentsOk: number;
+  fragmentsFailed: number;
+}
+
+export interface UdpStatistics {
+  inDatagrams: number;
+  noPorts: number;
+  inErrors: number;
+  outDatagrams: number;
+}
+
+export interface InterfaceCounters {
+  interfaceIndex: number;
+  name: string;
+  mtu: number;
+  operStatus: string;
+  inOctets: number;
+  outOctets: number;
+  inErrors: number;
+  outErrors: number;
+  inDiscards: number;
+  outDiscards: number;
+}
+
+export interface ThroughputSample {
+  interfaceIndex: number;
+  name: string;
+  rxBytesPerSec: number;
+  txBytesPerSec: number;
+  rxErrors: number;
+  txErrors: number;
+}
+
+const tcpStatsBuffer = Buffer.allocUnsafeSlow(TCP_STATS_SIZE);
+const ipStatsBuffer = Buffer.allocUnsafeSlow(IP_STATS_SIZE);
+const udpStatsBuffer = Buffer.allocUnsafeSlow(UDP_STATS_SIZE);
+
+/** TCP protocol counters (typed netstat -s) — 32-bit DWORDs that wrap on busy hosts; treat deltas modulo 2^32. */
+export function tcpStatistics(family: StatsFamily = 'ipv4'): TcpStatistics {
+  const error = Iphlpapi.GetTcpStatisticsEx(tcpStatsBuffer.ptr, addressFamilyValue(family));
+  if (error !== 0) throw new Win32Error(error);
+  const buffer = tcpStatsBuffer;
+  return {
+    activeOpens: buffer.readUInt32LE(16),
+    passiveOpens: buffer.readUInt32LE(20),
+    attemptFails: buffer.readUInt32LE(24),
+    establishedResets: buffer.readUInt32LE(28),
+    currentEstablished: buffer.readUInt32LE(32),
+    inSegments: buffer.readUInt32LE(36),
+    outSegments: buffer.readUInt32LE(40),
+    retransmittedSegments: buffer.readUInt32LE(44),
+    inErrors: buffer.readUInt32LE(48),
+    outResets: buffer.readUInt32LE(52),
+  };
+}
+
+/** IP protocol counters. */
+export function ipStatistics(family: StatsFamily = 'ipv4'): IpStatistics {
+  const error = Iphlpapi.GetIpStatisticsEx(ipStatsBuffer.ptr, addressFamilyValue(family));
+  if (error !== 0) throw new Win32Error(error);
+  const buffer = ipStatsBuffer;
+  return {
+    inReceives: buffer.readUInt32LE(8),
+    inHeaderErrors: buffer.readUInt32LE(12),
+    inAddressErrors: buffer.readUInt32LE(16),
+    forwardedDatagrams: buffer.readUInt32LE(20),
+    inDiscards: buffer.readUInt32LE(28),
+    inDelivers: buffer.readUInt32LE(32),
+    outRequests: buffer.readUInt32LE(36),
+    outDiscards: buffer.readUInt32LE(44),
+    outNoRoutes: buffer.readUInt32LE(48),
+    reassemblyRequired: buffer.readUInt32LE(56),
+    reassemblyOk: buffer.readUInt32LE(60),
+    fragmentsOk: buffer.readUInt32LE(68),
+    fragmentsFailed: buffer.readUInt32LE(72),
+  };
+}
+
+/** UDP protocol counters. */
+export function udpStatistics(family: StatsFamily = 'ipv4'): UdpStatistics {
+  const error = Iphlpapi.GetUdpStatisticsEx(udpStatsBuffer.ptr, addressFamilyValue(family));
+  if (error !== 0) throw new Win32Error(error);
+  const buffer = udpStatsBuffer;
+  return { inDatagrams: buffer.readUInt32LE(0), noPorts: buffer.readUInt32LE(4), inErrors: buffer.readUInt32LE(8), outDatagrams: buffer.readUInt32LE(12) };
+}
+
+/** Per-interface counters from GetIfTable2 — octets are ULONG64; error/discard counters systeminformation drops. */
+export function interfaceCounters(): InterfaceCounters[] {
+  return mibTable(
+    (tablePointer) => Iphlpapi.GetIfTable2(tablePointer),
+    IF_TABLE_FIRST_ROW,
+    IF_ROW_SIZE,
+    (table, row) => ({
+      interfaceIndex: table.readUInt32LE(row + IF_ROW_INTERFACE_INDEX),
+      name: readWideAt(table, row + IF_ROW_ALIAS),
+      mtu: table.readUInt32LE(row + IF_ROW_MTU),
+      operStatus: OPER_STATUS_NAMES.get(table.readUInt32LE(row + IF_ROW_OPER_STATUS)) ?? 'unknown',
+      inOctets: Number(table.readBigUInt64LE(row + IF_ROW_IN_OCTETS)),
+      outOctets: Number(table.readBigUInt64LE(row + IF_ROW_OUT_OCTETS)),
+      inErrors: Number(table.readBigUInt64LE(row + IF_ROW_IN_ERRORS)),
+      outErrors: Number(table.readBigUInt64LE(row + IF_ROW_OUT_ERRORS)),
+      inDiscards: Number(table.readBigUInt64LE(row + IF_ROW_IN_DISCARDS)),
+      outDiscards: Number(table.readBigUInt64LE(row + IF_ROW_OUT_DISCARDS)),
+    }),
+  );
+}
+
+interface OctetSample {
+  interfaceIndex: number;
+  name: string;
+  inOctets: bigint;
+  outOctets: bigint;
+  inErrors: bigint;
+  outErrors: bigint;
+}
+
+function sampleOctets(): Map<number, OctetSample> {
+  const rows = mibTable(
+    (tablePointer) => Iphlpapi.GetIfTable2(tablePointer),
+    IF_TABLE_FIRST_ROW,
+    IF_ROW_SIZE,
+    (table, row) => ({
+      interfaceIndex: table.readUInt32LE(row + IF_ROW_INTERFACE_INDEX),
+      name: readWideAt(table, row + IF_ROW_ALIAS),
+      inOctets: table.readBigUInt64LE(row + IF_ROW_IN_OCTETS),
+      outOctets: table.readBigUInt64LE(row + IF_ROW_OUT_OCTETS),
+      inErrors: table.readBigUInt64LE(row + IF_ROW_IN_ERRORS),
+      outErrors: table.readBigUInt64LE(row + IF_ROW_OUT_ERRORS),
+    }),
+  );
+  const map = new Map<number, OctetSample>();
+  for (const sample of rows) map.set(sample.interfaceIndex, sample);
+  return map;
+}
+
+/**
+ * Live per-interface throughput: two GetIfTable2 samples, octet deltas in bigint,
+ * narrowed to bytes/sec by the MEASURED elapsed time (so pacing quantization can't
+ * skew the rate). The dashboard primitive — sub-ms syscall, zero shell.
+ */
+export async function throughput(intervalMs = 1000): Promise<ThroughputSample[]> {
+  const first = sampleOctets();
+  const startNanos = Bun.nanoseconds();
+  await Bun.sleep(intervalMs);
+  const second = sampleOctets();
+  const elapsedSeconds = (Bun.nanoseconds() - startNanos) / 1_000_000_000;
+  const result: ThroughputSample[] = [];
+  for (const [interfaceIndex, later] of second) {
+    const earlier = first.get(interfaceIndex);
+    if (earlier === undefined) continue;
+    result.push({
+      interfaceIndex,
+      name: later.name,
+      rxBytesPerSec: Number(later.inOctets - earlier.inOctets) / elapsedSeconds,
+      txBytesPerSec: Number(later.outOctets - earlier.outOctets) / elapsedSeconds,
+      rxErrors: Number(later.inErrors - earlier.inErrors),
+      txErrors: Number(later.outErrors - earlier.outErrors),
+    });
+  }
+  return result;
+}

package/traceroute.ts

@@ -0,0 +1,35 @@
+import { ICMP_SUCCESS, icmpStatusName } from './constants';
+import { resolveIPv4, sendEcho } from './ping';
+
+export interface TraceHop {
+  ttl: number;
+  address: string;
+  roundTripMs: number;
+  status: number;
+  statusText: string;
+}
+
+export interface TracerouteOptions {
+  maxHops?: number;
+  timeoutMs?: number;
+  payloadSize?: number;
+}
+
+/**
+ * No-admin, no-raw-socket traceroute: an IcmpSendEcho TTL ramp. A router that
+ * decrements TTL to 0 replies IP_TTL_EXPIRED_TRANSIT with its own address (the
+ * hop); the walk stops when the destination echoes back (IP_SUCCESS).
+ */
+export async function traceroute(host: string, options: TracerouteOptions = {}): Promise<TraceHop[]> {
+  const destination = resolveIPv4(host);
+  const maxHops = options.maxHops ?? 30;
+  const timeoutMs = options.timeoutMs ?? 2000;
+  const payloadSize = options.payloadSize ?? 32;
+  const hops: TraceHop[] = [];
+  for (let ttl = 1; ttl <= maxHops; ttl++) {
+    const echo = sendEcho(destination, ttl, timeoutMs, payloadSize);
+    hops.push({ ttl, address: echo.replied ? echo.address : '*', roundTripMs: echo.roundTripMs, status: echo.status, statusText: icmpStatusName(echo.status) });
+    if (echo.replied && echo.status === ICMP_SUCCESS) break;
+  }
+  return hops;
+}