chore: bump version to 1.5.0

BREAKING CHANGE: new bedrock ping response format

README.md

@@ -1,6 +1,6 @@
 # mineping
 
-`mineping` is a Javasript library thar provides Minecraft server ping protocol implementation. It can be used to collect information about the server, such as MODT, current online, server icon (java edition only) and etc.
+This JavaScript library provides an implementation of the Minecraft server ping protocol. **It allows you to gather information about a Minecraft server**, such as the MOTD, current online players, server icon (Java Edition only), and more.
 
 Mirror on my [<img src="https://git.zeldon.ru/assets/img/logo.svg" align="center" width="20" height="20"/> Git](https://git.zeldon.ru/zeldon/mineping)
 
@@ -10,6 +10,8 @@ Mirror on my [<img src="https://git.zeldon.ru/assets/img/logo.svg" align="center
 
 ## Install
 
+To install `mineping`, simply run the following command:
+
 ```
 npm i @minescope/mineping
 ```
@@ -17,6 +19,7 @@ npm i @minescope/mineping
 ## Loading and configuration the module
 
 ### ES Modules (ESM)
+If you are using ES Modules, you can import the library like this:
 
 ```js
 import { pingJava, pingBedrock } from '@minescope/mineping';
@@ -59,5 +62,7 @@ console.log(data);
 
 ## Acknowledgements
 
+Special thanks to the following projects:
+
 - [mcping](https://github.com/Scetch/mcping) crate for Rust
 - [mcping-js](https://github.com/Cryptkeeper/mcping-js) library for quering Minecraft Java Edition servers

example/parallel.js

@@ -13,6 +13,7 @@ const results = await Promise.allSettled(pingPromises);
 for (let result of results) {
     if (result.status === 'rejected') {
         console.error(result.reason);
+        break;
     }
 
     console.log(result.value);

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>;