@deitylamb/mcping 1.1.0

package/dist/src-HHWxQmnZ.mjs

@@ -0,0 +1,364 @@
+import * as dns from "node:dns/promises";
+import * as net from "node:net";
+import * as dgram from "node:dgram";
+import * as crypto from "node:crypto";
+//#region src/target.ts
+/**
+* Resolves host and port, handling SRV records and lookups.
+*/
+async function resolveTarget(targetStr, type) {
+	let host = targetStr;
+	let port = type === "bedrock" ? 19132 : 25565;
+	const parts = targetStr.split(":");
+	if (parts.length === 2 && !isNaN(parseInt(parts[1]))) {
+		host = parts[0];
+		port = parseInt(parts[1]);
+		const ip = await resolveIp(host);
+		return {
+			host,
+			port,
+			protocol: type === null ? "java" : type,
+			ip
+		};
+	}
+	if (type !== "bedrock") try {
+		const srv = await dns.resolveSrv(`_minecraft._tcp.${host}`);
+		if (srv && srv.length > 0) {
+			const srvHost = srv[0].name;
+			return {
+				host: srvHost,
+				port: srv[0].port,
+				protocol: "java",
+				ip: await resolveIp(srvHost)
+			};
+		}
+	} catch (e) {}
+	if (type === "bedrock" && parts.length === 1) try {
+		const srv = await dns.resolveSrv(`_minecraft._udp.${host}`);
+		if (srv && srv.length > 0) {
+			const srvHost = srv[0].name;
+			return {
+				host: srvHost,
+				port: srv[0].port,
+				protocol: "bedrock",
+				ip: await resolveIp(srvHost)
+			};
+		}
+	} catch (e) {}
+	const ip = await resolveIp(host);
+	return {
+		host,
+		port,
+		protocol: type || "java",
+		ip
+	};
+}
+async function resolveIp(host) {
+	try {
+		return (await dns.lookup(host)).address;
+	} catch (e) {
+		return host;
+	}
+}
+//#endregion
+//#region src/varint.ts
+/**
+* VarInt encoding and decoding for Minecraft protocol.
+* Based on the specification at https://wiki.vg/Protocol#VarInt_and_VarLong
+*/
+function encodeVarInt(value) {
+	const bytes = [];
+	let temp = value >>> 0;
+	while (temp >= 128) {
+		bytes.push(temp & 127 | 128);
+		temp >>>= 7;
+	}
+	bytes.push(temp);
+	return Buffer.from(bytes);
+}
+function decodeVarInt(buffer, offset = 0) {
+	let value = 0;
+	let length = 0;
+	let currentByte;
+	while (true) {
+		currentByte = buffer.readUInt8(offset + length);
+		value |= (currentByte & 127) << length * 7;
+		length++;
+		if (length > 5) throw new Error("VarInt is too big");
+		if ((currentByte & 128) !== 128) break;
+	}
+	return {
+		value: value | 0,
+		length
+	};
+}
+function encodeString(str) {
+	const content = Buffer.from(str, "utf8");
+	return Buffer.concat([encodeVarInt(content.length), content]);
+}
+function decodeString(buffer, offset = 0) {
+	const { value: strLen, length: varIntLen } = decodeVarInt(buffer, offset);
+	return {
+		value: buffer.toString("utf8", offset + varIntLen, offset + varIntLen + strLen),
+		length: varIntLen + strLen
+	};
+}
+//#endregion
+//#region src/java-ping.ts
+async function pingJava(host, port, timeout) {
+	return new Promise((resolve, reject) => {
+		const client = new net.Socket();
+		let startTime;
+		let response;
+		const timeoutHandler = setTimeout(() => {
+			client.destroy();
+			reject(/* @__PURE__ */ new Error(`Connection timed out after ${timeout}ms`));
+		}, timeout);
+		client.connect(port, host, () => {
+			const protocolVersion = encodeVarInt(763);
+			const serverAddress = encodeString(host);
+			const serverPort = Buffer.alloc(2);
+			serverPort.writeUInt16BE(port);
+			const nextState = encodeVarInt(1);
+			const handshakePayload = Buffer.concat([
+				protocolVersion,
+				serverAddress,
+				serverPort,
+				nextState
+			]);
+			const packetIdBuffer = encodeVarInt(0);
+			const handshake = Buffer.concat([
+				encodeVarInt(handshakePayload.length + packetIdBuffer.length),
+				packetIdBuffer,
+				handshakePayload
+			]);
+			client.write(handshake);
+			const statusRequest = Buffer.concat([encodeVarInt(1), encodeVarInt(0)]);
+			client.write(statusRequest);
+			startTime = Date.now();
+		});
+		let data = Buffer.alloc(0);
+		client.on("data", (chunk) => {
+			data = Buffer.concat([data, chunk]);
+			while (data.length > 0) try {
+				const { value: packetLen, length: varIntLen } = decodeVarInt(data, 0);
+				if (data.length < packetLen + varIntLen) return;
+				const packet = data.subarray(varIntLen, varIntLen + packetLen);
+				data = data.subarray(varIntLen + packetLen);
+				const { value: packetId, length: idLen } = decodeVarInt(packet, 0);
+				if (packetId === 0) {
+					const { value: jsonStr } = decodeString(packet, idLen);
+					response = JSON.parse(jsonStr);
+					const pingPayload = Buffer.alloc(8);
+					pingPayload.writeBigInt64BE(BigInt(startTime));
+					const pingPacket = Buffer.concat([
+						encodeVarInt(9),
+						encodeVarInt(1),
+						pingPayload
+					]);
+					client.write(pingPacket);
+				} else if (packetId === 1) {
+					const latency = Date.now() - startTime;
+					clearTimeout(timeoutHandler);
+					client.destroy();
+					resolve({
+						response,
+						latency
+					});
+					return;
+				}
+			} catch (e) {
+				return;
+			}
+		});
+		client.on("error", (err) => {
+			clearTimeout(timeoutHandler);
+			reject(err);
+		});
+	});
+}
+//#endregion
+//#region src/bedrock-ping.ts
+const RAKNET_MAGIC = Buffer.from("00ffff00fefefefefdfdfdfd12345678", "hex");
+async function pingBedrock(host, port, timeout) {
+	return new Promise((resolve, reject) => {
+		const client = dgram.createSocket("udp4");
+		const timeoutHandler = setTimeout(() => {
+			client.close();
+			reject(/* @__PURE__ */ new Error(`Bedrock ping timed out after ${timeout}ms`));
+		}, timeout);
+		const startTime = BigInt(Date.now());
+		const clientGUID = crypto.randomBytes(8);
+		const packet = Buffer.alloc(33);
+		packet.writeUInt8(1, 0);
+		packet.writeBigInt64BE(startTime, 1);
+		RAKNET_MAGIC.copy(packet, 9);
+		clientGUID.copy(packet, 25);
+		client.send(packet, port, host);
+		client.on("message", (msg) => {
+			if (msg.readUInt8(0) === 28) {
+				clearTimeout(timeoutHandler);
+				client.close();
+				msg.readBigInt64BE(1);
+				msg.readBigInt64BE(9);
+				if (!msg.slice(17, 33).equals(RAKNET_MAGIC)) {
+					reject(/* @__PURE__ */ new Error("Invalid RakNet magic"));
+					return;
+				}
+				const stringLength = msg.readUInt16BE(33);
+				const parts = msg.toString("utf8", 35, 35 + stringLength).split(";");
+				resolve({
+					edition: parts[0] || "MCPE",
+					motdLine1: parts[1] || "",
+					protocolVersion: parseInt(parts[2]) || 0,
+					versionName: parts[3] || "",
+					playerCount: parseInt(parts[4]) || 0,
+					maxPlayerCount: parseInt(parts[5]) || 0,
+					serverUniqueId: parts[6] || "",
+					motdLine2: parts[7] || "",
+					gameMode: parts[8] || "",
+					nintendoLimited: parseInt(parts[9]) || 0,
+					ipv4Port: parts[10] ? parseInt(parts[10]) : null,
+					ipv6Port: parts[11] ? parseInt(parts[11]) : null
+				});
+			}
+		});
+		client.on("error", (err) => {
+			clearTimeout(timeoutHandler);
+			client.close();
+			reject(err);
+		});
+	});
+}
+//#endregion
+//#region src/chat.ts
+function parseChat(chat) {
+	if (typeof chat === "string") return chat;
+	if (!chat || typeof chat !== "object") return "";
+	let text = "";
+	const colorMap = {
+		black: "0",
+		dark_blue: "1",
+		dark_green: "2",
+		dark_aqua: "3",
+		dark_red: "4",
+		dark_purple: "5",
+		gold: "6",
+		gray: "7",
+		dark_gray: "8",
+		blue: "9",
+		green: "a",
+		aqua: "b",
+		red: "c",
+		light_purple: "d",
+		yellow: "e",
+		white: "f"
+	};
+	if (chat.color && colorMap[chat.color]) text += `§${colorMap[chat.color]}`;
+	if (chat.bold) text += "§l";
+	if (chat.italic) text += "§o";
+	if (chat.underlined) text += "§n";
+	if (chat.strikethrough) text += "§m";
+	if (chat.obfuscated) text += "§k";
+	text += chat.text || "";
+	if (chat.extra && Array.isArray(chat.extra)) for (const part of chat.extra) text += parseChat(part);
+	return text;
+}
+//#endregion
+//#region src/cache.ts
+const cache = /* @__PURE__ */ new Map();
+function getCache(target, options) {
+	const entry = cache.get(target);
+	if (!entry) return null;
+	if (!(Date.now() - entry.timestamp > options.ttl) || options.strategy === "swr") return {
+		...entry.response,
+		cached: true
+	};
+	return null;
+}
+function setCache(target, response) {
+	if (response.cached) return;
+	cache.set(target, {
+		response,
+		timestamp: Date.now()
+	});
+}
+function isExpired(target, options) {
+	const entry = cache.get(target);
+	if (!entry) return true;
+	return Date.now() - entry.timestamp > options.ttl;
+}
+//#endregion
+//#region src/index.ts
+async function ping(target, options) {
+	const timeout = options?.timeout || 5e3;
+	const type = options?.type || null;
+	const cacheOptions = options?.cache;
+	if (cacheOptions) {
+		const cached = getCache(target, cacheOptions);
+		if (cached) {
+			if (cacheOptions.strategy === "swr" && isExpired(target, cacheOptions)) pingServer(target, timeout, type).then((refreshed) => setCache(target, refreshed)).catch(() => {});
+			return cached;
+		}
+	}
+	const result = await pingServer(target, timeout, type);
+	if (cacheOptions) setCache(target, result);
+	return result;
+}
+async function pingServer(target, timeout, type) {
+	const resolved = await resolveTarget(target, type);
+	let javaError;
+	if (type === "java" || type === null) try {
+		const { response, latency } = await pingJava(resolved.host, resolved.port, timeout);
+		return {
+			type: "java",
+			version: {
+				name: response.version.name,
+				protocol: response.version.protocol
+			},
+			players: {
+				online: response.players.online,
+				max: response.players.max
+			},
+			motd: parseChat(response.description),
+			latency,
+			target: {
+				host: resolved.host,
+				port: resolved.port,
+				ip: resolved.ip
+			},
+			raw: response
+		};
+	} catch (e) {
+		javaError = e;
+		if (type === "java") throw e;
+	}
+	try {
+		const bedrockResolved = type === "bedrock" ? resolved : await resolveTarget(target, "bedrock");
+		const response = await pingBedrock(bedrockResolved.host, bedrockResolved.port, timeout);
+		return {
+			type: "bedrock",
+			version: {
+				name: response.versionName,
+				protocol: response.protocolVersion
+			},
+			players: {
+				online: response.playerCount,
+				max: response.maxPlayerCount
+			},
+			motd: response.motdLine2 ? `${response.motdLine1}\n${response.motdLine2}` : response.motdLine1,
+			latency: 0,
+			target: {
+				host: bedrockResolved.host,
+				port: bedrockResolved.port,
+				ip: bedrockResolved.ip
+			},
+			raw: response
+		};
+	} catch (bedrockErr) {
+		if (type === null && javaError) throw new Error(`Both Java and Bedrock pings failed. Java: ${javaError.message}. Bedrock: ${bedrockErr.message}`);
+		throw bedrockErr;
+	}
+}
+//#endregion
+export { ping as t };

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@deitylamb/mcping",
+  "version": "1.1.0",
+  "description": "Minecraft server ping library",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.cts"
+    }
+  },
+  "bin": {
+    "mcping": "./dist/cli.mjs"
+  },
+  "scripts": {
+    "dev": "tsdown src/index.ts --watch",
+    "build": "tsdown src/index.ts src/cli.ts --format cjs,esm --dts",
+    "test": "npm run test:unit && npm run test:e2e",
+    "test:unit": "vitest run test/unit",
+    "test:e2e": "vitest run test/e2e",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "keywords": [
+    "minecraft",
+    "ping",
+    "server",
+    "java",
+    "bedrock"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "prettier": "^3.8.1",
+    "tsdown": "^0.21.7",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  }
+}

package/src/ansi.ts

@@ -0,0 +1,50 @@
+const mcColorMap: Record<string, string> = {
+  "0": "\x1b[30m", // black
+  "1": "\x1b[34m", // dark_blue
+  "2": "\x1b[32m", // dark_green
+  "3": "\x1b[36m", // dark_aqua
+  "4": "\x1b[31m", // dark_red
+  "5": "\x1b[35m", // dark_purple
+  "6": "\x1b[33m", // gold
+  "7": "\x1b[37m", // gray
+  "8": "\x1b[90m", // dark_gray
+  "9": "\x1b[94m", // blue
+  a: "\x1b[92m", // green
+  b: "\x1b[96m", // aqua
+  c: "\x1b[91m", // red
+  d: "\x1b[95m", // light_purple
+  e: "\x1b[93m", // yellow
+  f: "\x1b[97m", // white
+  l: "\x1b[1m", // bold
+  m: "\x1b[9m", // strikethrough
+  n: "\x1b[4m", // underline
+  o: "\x1b[3m", // italic
+  r: "\x1b[0m", // reset
+};
+
+/**
+ * Converts Minecraft color codes (§) to ANSI terminal colors.
+ */
+export function mcToAnsi(text: string): string {
+  const reset = "\x1b[0m";
+  let result = "";
+  const parts = text.split("§");
+
+  result += parts[0];
+
+  for (let i = 1; i < parts.length; i++) {
+    const part = parts[i];
+    if (part.length === 0) continue;
+
+    const code = part[0].toLowerCase();
+    const ansi = mcColorMap[code];
+
+    if (ansi) {
+      result += ansi + part.substring(1);
+    } else {
+      result += "§" + part;
+    }
+  }
+
+  return result + reset;
+}

package/src/bedrock-ping.ts

@@ -0,0 +1,88 @@
+import * as dgram from "node:dgram";
+import * as crypto from "node:crypto";
+
+export interface BedrockRawResponse {
+  edition: string;
+  motdLine1: string;
+  motdLine2: string;
+  protocolVersion: number;
+  versionName: string;
+  playerCount: number;
+  maxPlayerCount: number;
+  serverUniqueId: string;
+  gameMode: string;
+  nintendoLimited: number;
+  ipv4Port: number | null;
+  ipv6Port: number | null;
+}
+
+const RAKNET_MAGIC = Buffer.from("00ffff00fefefefefdfdfdfd12345678", "hex");
+
+export async function pingBedrock(
+  host: string,
+  port: number,
+  timeout: number,
+): Promise<BedrockRawResponse> {
+  return new Promise((resolve, reject) => {
+    const client = dgram.createSocket("udp4");
+    const timeoutHandler = setTimeout(() => {
+      client.close();
+      reject(new Error(`Bedrock ping timed out after ${timeout}ms`));
+    }, timeout);
+
+    const startTime = BigInt(Date.now());
+    const clientGUID = crypto.randomBytes(8);
+
+    // Unconnected Ping (0x01)
+    const packet = Buffer.alloc(1 + 8 + 16 + 8);
+    packet.writeUInt8(0x01, 0); // Packet ID
+    packet.writeBigInt64BE(startTime, 1); // Time
+    RAKNET_MAGIC.copy(packet, 9); // Magic
+    clientGUID.copy(packet, 25); // Client GUID
+
+    client.send(packet, port, host);
+
+    client.on("message", (msg) => {
+      if (msg.readUInt8(0) === 0x1c) {
+        // Unconnected Pong (0x1C)
+        clearTimeout(timeoutHandler);
+        client.close();
+
+        const time = msg.readBigInt64BE(1);
+        const serverGUID = msg.readBigInt64BE(9);
+        const magic = msg.slice(17, 33);
+
+        if (!magic.equals(RAKNET_MAGIC)) {
+          reject(new Error("Invalid RakNet magic"));
+          return;
+        }
+
+        const stringLength = msg.readUInt16BE(33);
+        const body = msg.toString("utf8", 35, 35 + stringLength);
+
+        const parts = body.split(";");
+        const response: BedrockRawResponse = {
+          edition: parts[0] || "MCPE",
+          motdLine1: parts[1] || "",
+          protocolVersion: parseInt(parts[2]) || 0,
+          versionName: parts[3] || "",
+          playerCount: parseInt(parts[4]) || 0,
+          maxPlayerCount: parseInt(parts[5]) || 0,
+          serverUniqueId: parts[6] || "",
+          motdLine2: parts[7] || "",
+          gameMode: parts[8] || "",
+          nintendoLimited: parseInt(parts[9]) || 0,
+          ipv4Port: parts[10] ? parseInt(parts[10]) : null,
+          ipv6Port: parts[11] ? parseInt(parts[11]) : null,
+        };
+        resolve(response);
+      }
+    });
+
+    client.on("error", (err) => {
+      clearTimeout(timeoutHandler);
+      client.close();
+      reject(err);
+    });
+  });
+}

package/src/cache.ts

@@ -0,0 +1,42 @@
+import type { PingResponse } from "./index.js";
+
+export interface CacheOptions {
+  ttl: number;
+  strategy: "lazy" | "swr";
+}
+
+interface CacheEntry {
+  response: PingResponse;
+  timestamp: number;
+}
+
+const cache = new Map<string, CacheEntry>();
+
+export function getCache(
+  target: string,
+  options: CacheOptions,
+): PingResponse | null {
+  const entry = cache.get(target);
+  if (!entry) return null;
+
+  const age = Date.now() - entry.timestamp;
+  const isExpired = age > options.ttl;
+
+  if (!isExpired || options.strategy === "swr") {
+    return { ...entry.response, cached: true };
+  }
+
+  return null;
+}
+
+export function setCache(target: string, response: PingResponse): void {
+  // Only cache successful, non-cached results
+  if (response.cached) return;
+  cache.set(target, { response, timestamp: Date.now() });
+}
+
+export function isExpired(target: string, options: CacheOptions): boolean {
+  const entry = cache.get(target);
+  if (!entry) return true;
+  return Date.now() - entry.timestamp > options.ttl;
+}

package/src/chat.ts

@@ -0,0 +1,45 @@
+export function parseChat(chat: any): string {
+  if (typeof chat === "string") return chat;
+  if (!chat || typeof chat !== "object") return "";
+
+  let text = "";
+
+  // Minecraft legacy color code mapping in JSON
+  const colorMap: Record<string, string> = {
+    black: "0",
+    dark_blue: "1",
+    dark_green: "2",
+    dark_aqua: "3",
+    dark_red: "4",
+    dark_purple: "5",
+    gold: "6",
+    gray: "7",
+    dark_gray: "8",
+    blue: "9",
+    green: "a",
+    aqua: "b",
+    red: "c",
+    light_purple: "d",
+    yellow: "e",
+    white: "f",
+  };
+
+  if (chat.color && colorMap[chat.color]) {
+    text += `§${colorMap[chat.color]}`;
+  }
+  if (chat.bold) text += "§l";
+  if (chat.italic) text += "§o";
+  if (chat.underlined) text += "§n";
+  if (chat.strikethrough) text += "§m";
+  if (chat.obfuscated) text += "§k";
+
+  text += chat.text || "";
+
+  if (chat.extra && Array.isArray(chat.extra)) {
+    for (const part of chat.extra) {
+      text += parseChat(part);
+    }
+  }
+
+  return text;
+}