@deitylamb/mcping 1.1.0

package/src/cli.ts

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+import { ping } from "./index.js";
+import { mcToAnsi } from "./ansi.js";
+
+const colors = {
+  reset: "\x1b[0m",
+  bright: "\x1b[1m",
+  cyan: "\x1b[36m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  magenta: "\x1b[35m",
+  white: "\x1b[37m",
+  gray: "\x1b[90m",
+};
+
+/**
+ * Poor man's argument parser
+ */
+function parseArgs(args: string[]) {
+  const result: {
+    target?: string;
+    type?: "java" | "bedrock";
+    timeout?: number;
+  } = {};
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--type" || arg === "-t") {
+      const val = args[++i]?.toLowerCase();
+      if (val === "java" || val === "bedrock") {
+        result.type = val;
+      }
+    } else if (arg === "--timeout") {
+      const val = parseInt(args[++i]);
+      if (!isNaN(val)) {
+        result.timeout = val;
+      }
+    } else if (!result.target && !arg.startsWith("-")) {
+      result.target = arg;
+    }
+  }
+  return result;
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const parsed = parseArgs(args);
+
+  if (!parsed.target) {
+    console.log(
+      `\n${colors.bright}Usage:${colors.reset} mcping <host[:port]> [options]`,
+    );
+    console.log(`\n${colors.bright}Options:${colors.reset}`);
+    console.log(`  --type, -t <java|bedrock>  Force protocol type`);
+    console.log(
+      `  --timeout <ms>             Connection timeout (default: 5000)`,
+    );
+    console.log(`\n${colors.bright}Examples:${colors.reset}`);
+    console.log(`  mcping mc.hypixel.net`);
+    console.log(`  mcping geo.hivebedrock.network --type bedrock`);
+    console.log(`  mcping play.example.com --timeout 2000\n`);
+    process.exit(1);
+  }
+
+  try {
+    const res = await ping(parsed.target, {
+      type: parsed.type,
+      timeout: parsed.timeout,
+    });
+
+    // Header Line: Input -> IP:Port
+    const resolvedStr = `${res.target.ip}:${res.target.port}`;
+    const targetDisplay =
+      parsed.target === resolvedStr
+        ? parsed.target
+        : `${parsed.target} ${colors.gray}→${colors.reset} ${resolvedStr}`;
+
+    console.log(`\n ${colors.bright}${targetDisplay}${colors.reset}`);
+
+    // Edition line
+    const editionStr = `${colors.bright}${res.type.toUpperCase()}${colors.reset}`;
+    const versionStr = `${colors.gray}${res.version.name}${colors.reset}`;
+    const latencyStr =
+      res.type === "java"
+        ? ` ${colors.magenta}${res.latency}ms${colors.reset}`
+        : "";
+
+    console.log(
+      ` ${editionStr} ${colors.gray}•${colors.reset} ${versionStr}${latencyStr}`,
+    );
+
+    // Players line
+    console.log(
+      ` ${colors.bright}${res.players.online}${colors.reset} ${colors.gray}/ ${res.players.max} players${colors.reset}`,
+    );
+
+    // MOTD with indent and colors
+    const coloredMotd = mcToAnsi(res.motd);
+    const cleanMotd = coloredMotd
+      .trim()
+      .split("\n")
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0)
+      .join(`\n `);
+
+    console.log(`\n ${cleanMotd}${colors.reset}\n`);
+  } catch (err: any) {
+    console.error(`\n ${colors.yellow}Error:${colors.reset} ${err.message}\n`);
+    process.exit(1);
+  }
+}
+
+main();

package/src/index.ts

@@ -0,0 +1,143 @@
+import { resolveTarget } from "./target.js";
+import { pingJava, JavaRawResponse } from "./java-ping.js";
+import { pingBedrock, BedrockRawResponse } from "./bedrock-ping.js";
+import { parseChat } from "./chat.js";
+import * as cache from "./cache.js";
+
+export interface PingOptions {
+  timeout?: number;
+  type?: "java" | "bedrock" | null;
+  cache?: cache.CacheOptions;
+}
+
+export interface PingResponse {
+  type: "java" | "bedrock";
+  version: {
+    name: string;
+    protocol: number;
+  };
+  players: {
+    online: number;
+    max: number;
+  };
+  motd: string;
+  latency: number;
+  target: {
+    host: string;
+    port: number;
+    ip: string;
+  };
+  raw: JavaRawResponse | BedrockRawResponse;
+  cached?: boolean;
+}
+
+export async function ping(
+  target: string,
+  options?: PingOptions,
+): Promise<PingResponse> {
+  const timeout = options?.timeout || 5000;
+  const type = options?.type || null;
+  const cacheOptions = options?.cache;
+
+  if (cacheOptions) {
+    const cached = cache.getCache(target, cacheOptions);
+    if (cached) {
+      if (
+        cacheOptions.strategy === "swr" &&
+        cache.isExpired(target, cacheOptions)
+      ) {
+        // Refresh in background
+        pingServer(target, timeout, type)
+          .then((refreshed) => cache.setCache(target, refreshed))
+          .catch(() => {});
+      }
+      return cached;
+    }
+  }
+
+  const result = await pingServer(target, timeout, type);
+  if (cacheOptions) {
+    cache.setCache(target, result);
+  }
+
+  return result;
+}
+
+async function pingServer(
+  target: string,
+  timeout: number,
+  type: "java" | "bedrock" | null,
+): Promise<PingResponse> {
+  const resolved = await resolveTarget(target, type);
+
+  let javaError: any;
+  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: any) {
+    if (type === null && javaError) {
+      throw new Error(
+        `Both Java and Bedrock pings failed. Java: ${javaError.message}. Bedrock: ${bedrockErr.message}`,
+      );
+    }
+    throw bedrockErr;
+  }
+}

package/src/java-ping.ts

@@ -0,0 +1,114 @@
+import * as net from "node:net";
+import {
+  encodeVarInt,
+  encodeString,
+  decodeVarInt,
+  decodeString,
+} from "./varint.js";
+
+export interface JavaRawResponse {
+  version: { name: string; protocol: number };
+  players: {
+    max: number;
+    online: number;
+    sample?: { name: string; id: string }[];
+  };
+  description: any;
+  favicon?: string;
+  enforcesSecureChat?: boolean;
+  previewsChat?: boolean;
+}
+
+export async function pingJava(
+  host: string,
+  port: number,
+  timeout: number,
+): Promise<{ response: JavaRawResponse; latency: number }> {
+  return new Promise((resolve, reject) => {
+    const client = new net.Socket();
+    let startTime: number;
+    let response: JavaRawResponse;
+
+    const timeoutHandler = setTimeout(() => {
+      client.destroy();
+      reject(new Error(`Connection timed out after ${timeout}ms`));
+    }, timeout);
+
+    client.connect(port, host, () => {
+      // 1. Handshake
+      const protocolVersion = encodeVarInt(763); // 1.20.1
+      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);
+
+      // 2. Status Request
+      const statusRequest = Buffer.concat([encodeVarInt(1), encodeVarInt(0)]);
+      client.write(statusRequest);
+      startTime = Date.now();
+    });
+
+    let data = Buffer.alloc(0);
+    client.on("data", (chunk: Buffer) => {
+      data = Buffer.concat([data, chunk]);
+
+      while (data.length > 0) {
+        try {
+          // Read packet length
+          const { value: packetLen, length: varIntLen } = decodeVarInt(data, 0);
+          if (data.length < packetLen + varIntLen) return; // Wait for more data
+
+          const packet = data.subarray(varIntLen, varIntLen + packetLen);
+          data = data.subarray(varIntLen + packetLen); // Consume packet
+
+          // Read packet ID
+          const { value: packetId, length: idLen } = decodeVarInt(packet, 0);
+
+          if (packetId === 0) {
+            const { value: jsonStr } = decodeString(packet, idLen);
+            response = JSON.parse(jsonStr);
+
+            // 3. Ping
+            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 if we can't decode yet
+          return;
+        }
+      }
+    });
+
+    client.on("error", (err) => {
+      clearTimeout(timeoutHandler);
+      reject(err);
+    });
+  });
+}

package/src/target.ts

@@ -0,0 +1,65 @@
+import * as dns from "node:dns/promises";
+
+export interface Target {
+  host: string;
+  port: number;
+  protocol: "java" | "bedrock";
+  ip: string;
+}
+
+/**
+ * Resolves host and port, handling SRV records and lookups.
+ */
+export async function resolveTarget(
+  targetStr: string,
+  type: "java" | "bedrock" | null,
+): Promise<Target> {
+  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 };
+  }
+
+  // Attempt SRV resolution
+  if (type !== "bedrock") {
+    try {
+      const srv = await dns.resolveSrv(`_minecraft._tcp.${host}`);
+      if (srv && srv.length > 0) {
+        const srvHost = srv[0].name;
+        const srvPort = srv[0].port;
+        const ip = await resolveIp(srvHost);
+        return { host: srvHost, port: srvPort, protocol: "java", ip };
+      }
+    } 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;
+        const srvPort = srv[0].port;
+        const ip = await resolveIp(srvHost);
+        return { host: srvHost, port: srvPort, protocol: "bedrock", ip };
+      }
+    } catch (e) {}
+  }
+
+  const ip = await resolveIp(host);
+  return { host, port, protocol: type || "java", ip };
+}
+
+async function resolveIp(host: string): Promise<string> {
+  try {
+    const addresses = await dns.lookup(host);
+    return addresses.address;
+  } catch (e) {
+    // If lookup fails, return the host itself as a fallback
+    return host;
+  }
+}

package/src/varint.ts

@@ -0,0 +1,53 @@
+/**
+ * VarInt encoding and decoding for Minecraft protocol.
+ * Based on the specification at https://wiki.vg/Protocol#VarInt_and_VarLong
+ */
+
+export function encodeVarInt(value: number): Buffer {
+  const bytes: number[] = [];
+  let temp = value >>> 0;
+
+  while (temp >= 0x80) {
+    bytes.push((temp & 0x7f) | 0x80);
+    temp >>>= 7;
+  }
+  bytes.push(temp);
+  return Buffer.from(bytes);
+}
+
+export function decodeVarInt(
+  buffer: Buffer,
+  offset = 0,
+): { value: number; length: number } {
+  let value = 0;
+  let length = 0;
+  let currentByte: number;
+
+  while (true) {
+    currentByte = buffer.readUInt8(offset + length);
+    value |= (currentByte & 0x7f) << (length * 7);
+    length++;
+    if (length > 5) throw new Error("VarInt is too big");
+    if ((currentByte & 0x80) !== 0x80) break;
+  }
+
+  return { value: value | 0, length };
+}
+
+export function encodeString(str: string): Buffer {
+  const content = Buffer.from(str, "utf8");
+  return Buffer.concat([encodeVarInt(content.length), content]);
+}
+
+export function decodeString(
+  buffer: Buffer,
+  offset = 0,
+): { value: string; length: number } {
+  const { value: strLen, length: varIntLen } = decodeVarInt(buffer, offset);
+  const value = buffer.toString(
+    "utf8",
+    offset + varIntLen,
+    offset + varIntLen + strLen,
+  );
+  return { value, length: varIntLen + strLen };
+}