chore: bump version to 1.5.0

BREAKING CHANGE: new bedrock ping response format

example/single.js

@@ -0,0 +1,5 @@
+import { pingBedrock } from "../index.js";
+
+const host = "mc.nevertime.su";
+const ping = await pingBedrock(host);
+console.log(ping);

lib/bedrock.js

@@ -1,124 +1,61 @@
 /**
  * Implementation of the RakNet ping/pong protocol.
- * @see https://wiki.vg/Raknet_Protocol#Unconnected_Ping
+ * @see https://wiki.vg/Raknet_Protocol
- *
- * Data types:
- * @see https://wiki.vg/Raknet_Protocol#Data_types
  */
 
 'use strict';
 
-import dgram from 'dgram';
+import dgram from 'node:dgram';
+import crypto from 'node:crypto'
 
+const MAGIC = "00ffff00fefefefefdfdfdfd12345678";
 const START_TIME = new Date().getTime();
 
 /**
- * Creates a buffer with the specified length.
+ * Creates an Unconnected Ping packet.
- * @param {number} length - The length of the buffer.
+ * @param {number} pingId
- * @returns {Buffer} - The created buffer.
+ * @returns {Buffer}
- */
-const createBuffer = (length) => {
-    const buffer = Buffer.alloc(length);
-    buffer[0] = 0x01;
-    return buffer;
-};
-
-/**
- * Writes a BigInt value to the buffer at the specified offset using big-endian byte order.
- * @param {Buffer} buffer - The buffer to write to.
- * @param {number} value - The BigInt value to write.
- * @param {number} offset - The offset in the buffer to write the value.
- */
-const writeBigInt64BE = (buffer, value, offset) => {
-    buffer.writeBigInt64BE(BigInt(value), offset);
-};
-
-/**
- * Copies the specified hex value to the buffer at the specified offset.
- * @param {Buffer} buffer - The buffer to copy to.
- * @param {string} hex - The hex value to copy.
- * @param {number} offset - The offset in the buffer to copy the value.
- */
-const copyHexToBuffer = (buffer, hex, offset) => {
-    Buffer.from(hex, 'hex').copy(buffer, offset);
-};
-
-/**
- * Reads a BigInt value from the buffer at the specified offset using big-endian byte order.
- * @param {Buffer} buffer - The buffer to read from.
- * @param {number} offset - The offset in the buffer to read the value.
- * @returns {BigInt} - The read BigInt value.
- */
-const readBigInt64BE = (buffer, offset) => {
-    return buffer.readBigInt64BE(offset);
-};
-
-/**
- * Reads a string from the buffer at the specified offset.
- * @param {Buffer} buffer - The buffer to read from.
- * @param {number} offset - The offset in the buffer to read the string.
- * @returns {string} - The read string.
- */
-const readStringFromBuffer = (buffer, offset) => {
-    const length = buffer.readUInt16BE(offset);
-    return buffer.toString('utf8', offset + 2, offset + 2 + length);
-};
-
-/**
- * Parses the advertise string into an object with properties.
- * @param {string} advertiseStr - The advertise string to parse.
- * @returns {Object} - The parsed object with properties.
- */
-const parseAdvertiseString = (advertiseStr) => {
-    const parts = advertiseStr.split(';');
-    return {
-        gameId: parts[0],
-        description: parts[1],
-        protocolVersion: parts[2],
-        gameVersion: parts[3],
-        currentPlayers: parts[4],
-        maxPlayers: parts[5],
-        name: parts[7],
-        mode: parts[8]
-    };
-};
-
-/**
- * Creates an Unconnected Ping buffer.
- * @param {number} pingId - The ping ID.
- * @returns {Buffer} - The Unconnected Ping buffer.
  * @see {@link https://wiki.vg/Raknet_Protocol#Unconnected_Ping}
  */
-const UNCONNECTED_PING = (pingId) => {
+const createUnconnectedPingFrame = (timestamp) => {
-    const buffer = createBuffer(35);
+    const buffer = Buffer.alloc(33);
-    writeBigInt64BE(buffer, pingId, 1);
+    buffer.writeUInt8(0x01, 0); // Packet ID
-    copyHexToBuffer(buffer, '00ffff00fefefefefdfdfdfd12345678', 9);
+    buffer.writeBigInt64LE(BigInt(timestamp), 1); // Timestamp
-    writeBigInt64BE(buffer, 0, 25);
+    Buffer.from(MAGIC, "hex").copy(buffer, 9); // OFFLINE_MESSAGE_DATA_ID (Magic)
+    Buffer.from(crypto.randomBytes(8)).copy(buffer, 25); // Client GUID
     return buffer;
 };
 
 /**
- * Decodes an Unconnected Pong buffer and returns the parsed data.
+ * Extract Modt from Unconnected Pong Packet and convert to an object
- * @param {Buffer} buffer - The Unconnected Pong buffer.
+ * @param {Buffer} unconnectedPongPacket
- * @returns {Object} - The parsed Unconnected Pong data.
+ * @returns {Object}
  * @see {@link https://wiki.vg/Raknet_Protocol#Unconnected_Pong}
  */
-const UNCONNECTED_PONG = (buffer) => {
+const extractModt = (unconnectedPongPacket) => {
-    const pingId = readBigInt64BE(buffer, 1);
+    // Skip everything to Modt
-    const serverId = readBigInt64BE(buffer, 9);
+    const offset = 33;
-    let offset = 25;
+    const length = unconnectedPongPacket.readUInt16BE(offset);
-    let advertiseStr;
+    let modt = unconnectedPongPacket.toString("utf-8", offset + 2, offset + 2 + length);
 
-    try {
+    const components = modt.split(';');
-        advertiseStr = readStringFromBuffer(buffer, offset);
+    const parsedComponents = {
-    } catch (err) {
+        edition: components[0],
-        const length = parseInt(err.message.substr(err.message.indexOf(',') + 2, 3));
+        name: components[1],
-        advertiseStr = buffer.toString('utf8', offset, offset + length);
+        version: {
-    }
+            protocolVersion: Number(components[2]),
+            minecraftVersion: components[3],
+        },
+        players: {
+            online: Number(components[4]),
+            max: Number(components[5])
+        },
+        serverId: components[6],
+        mapName: components[7],
+        gameMode: components[8]
+    };
 
-    const parsedAdvertiseStr = parseAdvertiseString(advertiseStr);
+    return parsedComponents;
-
-    return { pingId, advertiseStr, serverId, offset, ...parsedAdvertiseStr };
 };
 
 /**
@@ -161,33 +98,20 @@ const ping = (host, port = 19132, cb, timeout = 5000) => {
     };
 
     try {
-        const ping = UNCONNECTED_PING(new Date().getTime() - START_TIME);
+        const ping = createUnconnectedPingFrame(new Date().getTime() - START_TIME);
         socket.send(ping, 0, ping.length, port, host);
     } catch (err) {
         handleError(err);
     }
 
-    socket.on('message', (msg) => {
+    socket.on('message', (pongPacket) => {
-        const id = msg[0];
+        const id = pongPacket[0];
 
         switch (id) {
             case 0x1c: {
-                const pong = UNCONNECTED_PONG(msg);
+                const modtObject = extractModt(pongPacket);
-                const clientData = {
-                    version: {
-                        name: pong.name,
-                        protocol: pong.protocolVersion
-                    },
-                    players: {
-                        max: pong.maxPlayers,
-                        online: pong.currentPlayers
-                    },
-                    description: pong.description.replace(/\xA7[0-9A-FK-OR]/ig, ''),
-                    gamemode: pong.mode
-                };
-
                 closeSocket();
-                cb(clientData, null);
+                cb(modtObject, null);
                 break;
             }
 

lib/java.js

@@ -5,19 +5,18 @@
 
 'use strict';
 
-import net from 'net';
+import net from 'node:net';
 import varint from './varint.js';
 
-const PROTOCOL_VERSION = 0;
-
 /**
  * Ping a Minecraft Java server.
  * @param {string} host The host of the Java server.
  * @param {number} [port=25565] The port of the Java server.
  * @param {function} cb The callback function to handle the ping response.
  * @param {number} [timeout=5000] The timeout duration in milliseconds.
+ * @param {number} [protocolVersion=-1] The protocol version of the Java client.
  */
-function ping(host, port = 25565, cb, timeout = 5000) {
+function ping(host, port = 25565, cb, timeout = 5000, protocolVersion = -1) {
     const socket = net.createConnection(({ host, port }));
 
     // Set manual timeout interval.
@@ -56,7 +55,7 @@ function ping(host, port = 25565, cb, timeout = 5000) {
     socket.on('connect', () => {
         const handshake = varint.concat([
             varint.encodeInt(0),
-            varint.encodeInt(PROTOCOL_VERSION),
+            varint.encodeInt(protocolVersion),
             varint.encodeInt(host.length),
             varint.encodeString(host),
             varint.encodeUShort(port),
@@ -118,7 +117,7 @@ function ping(host, port = 25565, cb, timeout = 5000) {
 
 /**
  * Asynchronously ping Minecraft Java server.
- * The optional `options` argument can be an object with a `ping` (default is `25565`) or/and `timeout` (default is `5000`) property.
+ * The optional `options` argument can be an object with a `port` (default is `25565`) or/and `timeout` (default is `5000`) or/and `protocolVersion` (default is `-1`) property.
  * @param {string} host The Java server address.
  * @param {import('../types/index.js').PingOptions} options The configuration for pinging Minecraft Java server.
  * @returns {Promise<import('../types/index.js').JavaPingResponse>}
@@ -126,11 +125,11 @@ function ping(host, port = 25565, cb, timeout = 5000) {
 export function pingJava(host, options = {}) {
     if (!host) throw new Error('Host argument is not provided');
 
-    const { port = 25565, timeout = 5000 } = options;
+    const { port = 25565, timeout = 5000, protocolVersion = -1 } = options;
 
     return new Promise((resolve, reject) => {
         ping(host, port, (res, err) => {
             err ? reject(err) : resolve(res);
-        }, timeout);
+        }, timeout, protocolVersion);
     });
-}
+}

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minescope/mineping",
-  "version": "1.1.1",
+  "version": "1.5.0",
   "description": "Ping both Minecraft Bedrock and Java servers.",
   "main": "index.js",
   "types": "types/index.d.ts",

types/lib/bedrock.d.ts

@@ -2,22 +2,25 @@
  * @param port The server port.
  * @param timeout The read/write socket timeout.
  */
-export type PingOptions = {
+export type BedrockPingOptions = {
-    port: number,
+    port?: number;
-    timeout: number;
+    timeout?: number;
 };
 
 export type BedrockPingResponse = {
+    edition: string;
+    name: string;
     version: {
-        name: string;
+        protocolVersion: number;
-        protocol: string;
+        minecraftVersion: string;
     };
     players: {
-        max: string;
+        online: number;
-        online: string;
+        max: number;
     };
-    description: string;
+    serverId: string;
-    gamemode: string;
+    mapName: string;
+    gameMode: string;
 };
 
 /**
@@ -26,6 +29,7 @@ export type BedrockPingResponse = {
  * The optional `options` argument can be an object with a `ping` (default is `19132`) or/and `timeout` (default is `5000`) property.
  * 
  * @param host The Bedrock server address.
+ * @param options The configuration for pinging Minecraft Bedrock server.
  * 
  * ```js
  * import { pingBedrock } from '@minescope/mineping';
@@ -45,5 +49,5 @@ export type BedrockPingResponse = {
  * ```
  * @see [source](https://github.com/minescope/mineping/blob/915edbec9c9ad811459458600af3531ec0836911/lib/bedrock.js#L204)
  */
-export function pingBedrock(host: string, options?: PingOptions): Promise<BedrockPingResponse>;
+export function pingBedrock(host: string, options?: BedrockPingOptions): Promise<BedrockPingResponse>;
 

types/lib/java.d.ts

@@ -1,4 +1,13 @@
-import { PingOptions } from "./bedrock";
+/**
+ * @param port The server port.
+ * @param timeout The read/write socket timeout.
+ * @param protocolVersion The protocol version.
+ */
+export type JavaPingOptions = {
+    port?: number | undefined,
+    timeout?: number | undefined,
+    protocolVersion?: number | undefined;
+};
 
 /**
  * JSON format chat component used for description field.
@@ -67,5 +76,5 @@ export type JavaPingResponse = {
  * ```
  * @see [source](https://github.com/minescope/mineping/blob/915edbec9c9ad811459458600af3531ec0836911/lib/java.js#L117)
  */
-export function pingJava(host: string, options?: PingOptions): Promise<JavaPingResponse>;
+export function pingJava(host: string, options?: JavaPingOptions): Promise<JavaPingResponse>;