mirror of
https://github.com/minescope/mineping.git
synced 2025-07-14 17:54:41 +03:00
refactor!: decouple Raknet MOTD parsing and response shaping
The previous implementation of the RakNet ping was monolithic, mixing socket management, raw packet validation, and data transformation into a single, complex flow. This refactor introduces a clear, multi-stage processing pipeline that separates these concerns. The logic is now broken down into multi-stage pipeline: extracting the MOTD string from the raw pong packet -> parsing that string into a raw object -> transforming the raw data into a user-friendly response object. Additionally, the socket handling logic is improved with idempotent cleanup function to prevent resource leaks or race conditions. As part of this overhaul, external TypeScript definition (`.d.ts`) files have been removed in favor of rich JSDoc annotations. BREAKING CHANGE: The structure of the resolved `BedrockPingResponse` object has been significantly changed to improve clarity and consistency.
This commit is contained in:
61
types/lib/bedrock.d.ts
vendored
61
types/lib/bedrock.d.ts
vendored
@ -1,61 +0,0 @@
|
||||
/**
|
||||
* @param port The server port (1-65535).
|
||||
* @param timeout The read/write socket timeout in milliseconds.
|
||||
*/
|
||||
export type BedrockPingOptions = {
|
||||
port?: number & { _brand: "Port" }; // 1-65535
|
||||
timeout?: number & { _brand: "Timeout" }; // > 0
|
||||
};
|
||||
|
||||
export type BedrockPingResponse = {
|
||||
edition: string;
|
||||
name: string;
|
||||
version: {
|
||||
protocolVersion: number;
|
||||
minecraftVersion: string;
|
||||
};
|
||||
players: {
|
||||
online: number;
|
||||
max: number;
|
||||
};
|
||||
serverId: string;
|
||||
mapName: string;
|
||||
gameMode: string;
|
||||
};
|
||||
|
||||
/**
|
||||
* Asynchronously ping Minecraft Bedrock server.
|
||||
*
|
||||
* @param host The Bedrock server address.
|
||||
* @param options The configuration for pinging Minecraft Bedrock server.
|
||||
*
|
||||
* ```js
|
||||
* import { pingBedrock } from '@minescope/mineping';
|
||||
*
|
||||
* const data = await pingBedrock('mco.mineplex.com');
|
||||
* console.log(data);
|
||||
* ```
|
||||
*
|
||||
* The resulting output will resemble:
|
||||
* ```console
|
||||
* {
|
||||
* edition: "MCPE",
|
||||
* name: "Mineplex",
|
||||
* version: {
|
||||
* protocolVersion: 475,
|
||||
* minecraftVersion: "1.18.0"
|
||||
* },
|
||||
* players: {
|
||||
* online: 5206,
|
||||
* max: 5207
|
||||
* },
|
||||
* serverId: "12345678",
|
||||
* mapName: "Lobby",
|
||||
* gameMode: "Survival"
|
||||
* }
|
||||
* ```
|
||||
*/
|
||||
export function pingBedrock(
|
||||
host: string,
|
||||
options?: BedrockPingOptions
|
||||
): Promise<BedrockPingResponse>;
|
||||
83
types/lib/java.d.ts
vendored
83
types/lib/java.d.ts
vendored
@ -1,83 +0,0 @@
|
||||
/**
|
||||
* @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;
|
||||
virtualHost?: string | undefined;
|
||||
};
|
||||
|
||||
/**
|
||||
* JSON format chat component used for description field.
|
||||
* @see https://minecraft.wiki/w/Minecraft_Wiki:Projects/wiki.vg_merge/Chat
|
||||
*/
|
||||
export type ChatComponent = {
|
||||
text: string;
|
||||
bold?: boolean;
|
||||
italic?: boolean;
|
||||
underlined?: boolean;
|
||||
strikethrough?: boolean;
|
||||
obfuscated?: boolean;
|
||||
color?: string;
|
||||
extra?: ChatComponent[];
|
||||
};
|
||||
|
||||
export type SampleProp = {
|
||||
name: string;
|
||||
id: string;
|
||||
};
|
||||
|
||||
/**
|
||||
* `JSON Response` field of Response packet.
|
||||
* @see https://minecraft.wiki/w/Minecraft_Wiki:Projects/wiki.vg_merge/Server_List_Ping#Status_Response
|
||||
*/
|
||||
export type JavaPingResponse = {
|
||||
version: {
|
||||
name: string;
|
||||
protocol: number;
|
||||
};
|
||||
players: {
|
||||
max: number;
|
||||
online: number;
|
||||
sample?: SampleProp[];
|
||||
};
|
||||
description: string | ChatComponent;
|
||||
favicon?: string;
|
||||
enforcesSecureChat?: boolean;
|
||||
previewsChat?: boolean;
|
||||
};
|
||||
|
||||
/**
|
||||
* 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.
|
||||
*
|
||||
* @param host The Java server address.
|
||||
* @param options The configuration for pinging Minecraft Java server.
|
||||
*
|
||||
* ```js
|
||||
* import { pingJava } from '@minescope/mineping';
|
||||
*
|
||||
* const data = await pingJava('mc.hypixel.net');
|
||||
* console.log(data);
|
||||
* ```
|
||||
*
|
||||
* The resulting output will resemble:
|
||||
* ```console
|
||||
* {
|
||||
* version: { name: 'Requires MC 1.8 / 1.18', protocol: 47 },
|
||||
* players: { max: 200000, online: 67336, sample: [] },
|
||||
* description: ' §f☃ §aHypixel Network §eTRIPLE COINS & EXP §f☃\n' +
|
||||
* ' §6✰ §f§lHOLIDAY SALE §c§lUP TO 85% OFF §6✰',
|
||||
* favicon: 'data:image/png;base64,iVBORw0KGg...
|
||||
}
|
||||
* ```
|
||||
* @see [source](https://github.com/minescope/mineping/blob/915edbec9c9ad811459458600af3531ec0836911/lib/java.js#L117)
|
||||
*/
|
||||
export function pingJava(
|
||||
host: string,
|
||||
options?: JavaPingOptions
|
||||
): Promise<JavaPingResponse>;
|
||||
44
types/lib/varint.d.ts
vendored
44
types/lib/varint.d.ts
vendored
@ -1,44 +0,0 @@
|
||||
export default varint;
|
||||
declare namespace varint {
|
||||
/**
|
||||
* Encodes an integer value into a varint byte buffer.
|
||||
* @param val - The integer value to encode.
|
||||
*/
|
||||
function encodeInt(val: number): Buffer;
|
||||
|
||||
/**
|
||||
* Encodes a string value into a UTF-8 byte buffer.
|
||||
* @param val - The string value to encode.
|
||||
*/
|
||||
function encodeString(val: string): Buffer;
|
||||
|
||||
/**
|
||||
* Encodes an unsigned short value into a byte buffer.
|
||||
* @param val - The unsigned short value to encode.
|
||||
*/
|
||||
function encodeUShort(val: number): Buffer;
|
||||
|
||||
/**
|
||||
* Concatenates multiple byte buffers into a single byte buffer.
|
||||
* @param chunks - An array of byte buffers to concatenate.
|
||||
*/
|
||||
function concat(chunks: Buffer[]): Buffer;
|
||||
|
||||
/**
|
||||
* Decodes a varint integer value from a buffer.
|
||||
* @param buffer - The byte buffer to decode from.
|
||||
* @param offset - The offset in the buffer to start decoding from.
|
||||
*/
|
||||
function decodeInt(buffer: Buffer, offset: number): number;
|
||||
|
||||
/**
|
||||
* Calculates how many bytes are needed to encode a number as a VarInt.
|
||||
* VarInts use a variable number of bytes to efficiently encode integers.
|
||||
* Each byte uses 7 bits for the value and 1 bit to indicate if more bytes follow.
|
||||
* VarInts are never longer than 5 bytes.
|
||||
*
|
||||
* @param val - The number to calculate the VarInt length for.
|
||||
* @returns The number of bytes needed to encode the value (1-5).
|
||||
*/
|
||||
function decodeLength(val: number): 1 | 2 | 3 | 4 | 5;
|
||||
}
|
||||
Reference in New Issue
Block a user