@hytaleone/query 1.0.1 → 1.1.0

package/README.md

@@ -1,6 +1,19 @@
 # @hytaleone/query
 
-Query Hytale servers using the UDP query protocol.
+[![npm version](https://img.shields.io/npm/v/@hytaleone/query.svg)](https://www.npmjs.com/package/@hytaleone/query)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Query Hytale servers using the UDP query protocol. Get server status, player count, player list, and plugin information.
+
+## Features
+
+- **Server Status** - Get server name, MOTD, version, player count
+- **Player List** - Retrieve online players with names and UUIDs
+- **Plugin List** - See installed plugins with versions
+- **V2 Protocol** - Enhanced protocol with challenge-based authentication and pagination
+- **Zero dependencies** - Uses only Node.js built-in modules
+- **TypeScript** - Full type definitions included
+- **Dual format** - Works with both ESM and CommonJS
 
 ## Installation
 
@@ -10,6 +23,8 @@ npm install @hytaleone/query
 
 ## Usage
 
+### V1 Protocol
+
 ```typescript
 import { query } from '@hytaleone/query';
 
@@ -17,17 +32,46 @@ import { query } from '@hytaleone/query';
 const info = await query('play.example.com', 5520);
 console.log(`${info.serverName}: ${info.currentPlayers}/${info.maxPlayers}`);
 
+// Check V2 support
+if (info.supportsV2) {
+  console.log('Server supports V2 protocol');
+}
+
 // Full query - includes players and plugins
 const full = await query('play.example.com', 5520, { full: true });
 console.log('Players:', full.players.map(p => p.name).join(', '));
 console.log('Plugins:', full.plugins.map(p => p.id).join(', '));
 ```
 
+### V2 Protocol
+
+```typescript
+import { query, queryV2 } from '@hytaleone/query';
+
+// Check if server supports V2
+const info = await query('play.example.com', 5520);
+
+if (info.supportsV2) {
+  // Basic V2 query
+  const v2Info = await queryV2('play.example.com', 5520);
+  console.log(`${v2Info.serverName}: ${v2Info.currentPlayers}/${v2Info.maxPlayers}`);
+
+  // V2 query with players (single page)
+  const withPlayers = await queryV2('play.example.com', 5520, { players: true });
+  console.log('Players:', withPlayers.players.map(p => p.name).join(', '));
+  console.log('Has more:', withPlayers.hasMore);
+
+  // V2 query with all players (auto-pagination)
+  const allPlayers = await queryV2('play.example.com', 5520, { players: 'all' });
+  console.log(`All ${allPlayers.totalPlayers} players fetched`);
+}
+```
+
 ## API
 
 ### query(host, port?, options?)
 
-Query a server for information.
+Query a server using the V1 protocol.
 
 ```typescript
 const info = await query('localhost', 5520, {
@@ -49,11 +93,71 @@ const info = await query('localhost', 5520, {
 - `version` - Server version
 - `protocolVersion` - Protocol version number
 - `protocolHash` - Protocol hash
+- `supportsV2` - Whether server supports V2 protocol
+- `isNetworkMode` - Whether server is in network aggregation mode
+- `v2Version` - V2 protocol version (0 if not supported)
 
 **With `full: true`, also returns:**
 - `players` - Array of `{ name, uuid }`
 - `plugins` - Array of `{ id, version, enabled }`
 
+### queryV2(host, port?, options?)
+
+Query a server using the V2 protocol with challenge-based authentication.
+
+```typescript
+const info = await queryV2('localhost', 5520, {
+  timeout: 5000,
+  players: true,
+  playerOffset: 0
+});
+```
+
+**Options:**
+- `timeout` - Query timeout in milliseconds (default: 5000)
+- `players` - Request player list: `false` (default), `true` (single page), or `'all'` (auto-paginate)
+- `playerOffset` - Starting offset for player pagination (default: 0)
+- `authToken` - Optional authentication token for private servers
+
+**Returns `ServerInfoV2`:**
+- `serverName` - Server display name
+- `motd` - Message of the day
+- `currentPlayers` - Current player count
+- `maxPlayers` - Maximum player capacity
+- `version` - Server version
+- `protocolVersion` - Protocol version number
+- `protocolHash` - Protocol hash
+- `isNetwork` - Whether response contains aggregated network data
+- `host` - Server host (if provided by server)
+- `hostPort` - Server port (if provided by server)
+
+**With `players: true` or `players: 'all'`, also returns:**
+- `players` - Array of `{ name, uuid }`
+- `totalPlayers` - Total player count on server
+- `offset` - Offset used for this response
+- `hasMore` - Whether more players are available
+
+### clearChallengeCache()
+
+Clear the V2 challenge token cache. Useful for testing or forcing fresh challenges.
+
+```typescript
+import { clearChallengeCache } from '@hytaleone/query';
+
+clearChallengeCache();
+```
+
+## V1 vs V2 Protocol
+
+| Feature | V1 | V2 |
+|---------|----|----|
+| Authentication | None | Challenge-based |
+| Player pagination | No | Yes |
+| Network aggregation | No | Yes |
+| Plugin list | Yes | No |
+
+Use V1 for simple queries or when you need plugin information. Use V2 for servers with many players or when you need pagination support.
+
 ## Requirements
 
 - Node.js >= 18
@@ -63,6 +167,10 @@ const info = await query('localhost', 5520, {
 
 MIT
 
+## Related
+
+- [@hytaleone/votifier](https://www.npmjs.com/package/@hytaleone/votifier) - Send votes to Hytale and Minecraft servers
+
 ---
 
 **[hytale.one](https://hytale.one/)** - Discover Hytale Servers

package/dist/index.cjs

@@ -30,7 +30,12 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  query: () => query
+  V2QueryType: () => V2QueryType,
+  V2ResponseFlag: () => V2ResponseFlag,
+  V2TLVType: () => V2TLVType,
+  clearChallengeCache: () => clearChallengeCache,
+  query: () => query,
+  queryV2: () => queryV2
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -42,6 +47,8 @@ var REQUEST_MAGIC = Buffer.from("HYQUERY\0", "ascii");
 var RESPONSE_MAGIC = Buffer.from("HYREPLY\0", "ascii");
 var TYPE_BASIC = 0;
 var TYPE_FULL = 1;
+var CAP_V2_PROTOCOL = 1;
+var CAP_NETWORK_MODE = 2;
 function buildRequest(type) {
   const buf = Buffer.alloc(REQUEST_MAGIC.length + 1);
   REQUEST_MAGIC.copy(buf, 0);
@@ -53,31 +60,58 @@ var BufferReader = class {
     this.buf = buf;
   }
   offset = 0;
+  checkBounds(needed) {
+    if (this.offset + needed > this.buf.length) {
+      throw new RangeError(
+        `Buffer underflow: need ${needed} bytes at offset ${this.offset}, but buffer is ${this.buf.length} bytes`
+      );
+    }
+  }
   readBytes(length) {
+    this.checkBounds(length);
     const slice = this.buf.subarray(this.offset, this.offset + length);
     this.offset += length;
     return slice;
   }
+  readUInt8() {
+    this.checkBounds(1);
+    return this.buf[this.offset++];
+  }
   readUInt16LE() {
+    this.checkBounds(2);
     const value = this.buf.readUInt16LE(this.offset);
     this.offset += 2;
     return value;
   }
+  readUInt32LE() {
+    this.checkBounds(4);
+    const value = this.buf.readUInt32LE(this.offset);
+    this.offset += 4;
+    return value;
+  }
   readInt32LE() {
+    this.checkBounds(4);
     const value = this.buf.readInt32LE(this.offset);
     this.offset += 4;
     return value;
   }
   readBigInt64BE() {
+    this.checkBounds(8);
     const value = this.buf.readBigInt64BE(this.offset);
     this.offset += 8;
     return value;
   }
   readBoolean() {
+    this.checkBounds(1);
     return this.buf[this.offset++] !== 0;
   }
   readString() {
     const length = this.readUInt16LE();
+    if (length > this.remaining) {
+      throw new RangeError(
+        `Invalid string length ${length} at offset ${this.offset - 2}, only ${this.remaining} bytes remaining`
+      );
+    }
     const bytes = this.readBytes(length);
     return bytes.toString("utf8");
   }
@@ -86,9 +120,23 @@ var BufferReader = class {
     const lsb = this.readBigInt64BE();
     return formatUUID(msb, lsb);
   }
+  readBigInt64LE() {
+    this.checkBounds(8);
+    const value = this.buf.readBigInt64LE(this.offset);
+    this.offset += 8;
+    return value;
+  }
+  readUUIDLE() {
+    const msb = this.readBigInt64LE();
+    const lsb = this.readBigInt64LE();
+    return formatUUID(msb, lsb);
+  }
   get remaining() {
     return this.buf.length - this.offset;
   }
+  get position() {
+    return this.offset;
+  }
 };
 function formatUUID(msb, lsb) {
   const toHex = (n) => {
@@ -106,6 +154,18 @@ function validateResponse(buf) {
   }
   return buf.subarray(0, RESPONSE_MAGIC.length).equals(RESPONSE_MAGIC);
 }
+function parseCapabilities(reader) {
+  if (reader.remaining >= 3) {
+    const caps = reader.readUInt16LE();
+    const v2Version = reader.readUInt8();
+    return {
+      supportsV2: (caps & CAP_V2_PROTOCOL) !== 0,
+      isNetworkMode: (caps & CAP_NETWORK_MODE) !== 0,
+      v2Version
+    };
+  }
+  return { supportsV2: false, isNetworkMode: false, v2Version: 0 };
+}
 function parseBasicResponse(buf) {
   if (!validateResponse(buf)) {
     throw new Error("Invalid response: magic mismatch");
@@ -113,15 +173,25 @@ function parseBasicResponse(buf) {
   const reader = new BufferReader(buf);
   reader.readBytes(RESPONSE_MAGIC.length);
   reader.readBytes(1);
+  const serverName = reader.readString();
+  const motd = reader.readString();
+  const currentPlayers = reader.readInt32LE();
+  const maxPlayers = reader.readInt32LE();
+  const hostPort = reader.readUInt16LE();
+  const version = reader.readString();
+  const protocolVersion = reader.readInt32LE();
+  const protocolHash = reader.readString();
+  const capabilities = parseCapabilities(reader);
   return {
-    serverName: reader.readString(),
-    motd: reader.readString(),
-    currentPlayers: reader.readInt32LE(),
-    maxPlayers: reader.readInt32LE(),
-    hostPort: reader.readUInt16LE(),
-    version: reader.readString(),
-    protocolVersion: reader.readInt32LE(),
-    protocolHash: reader.readString()
+    serverName,
+    motd,
+    currentPlayers,
+    maxPlayers,
+    hostPort,
+    version,
+    protocolVersion,
+    protocolHash,
+    ...capabilities
   };
 }
 function parseFullResponse(buf) {
@@ -156,6 +226,7 @@ function parseFullResponse(buf) {
       enabled: reader.readBoolean()
     });
   }
+  const capabilities = parseCapabilities(reader);
   return {
     serverName,
     motd,
@@ -166,7 +237,8 @@ function parseFullResponse(buf) {
     protocolVersion,
     protocolHash,
     players,
-    plugins
+    plugins,
+    ...capabilities
   };
 }
 
@@ -216,8 +288,327 @@ async function query(host, port = 5520, options = {}) {
   }
   return parseBasicResponse(response);
 }
+
+// src/query-v2.ts
+var import_node_dgram2 = __toESM(require("dgram"), 1);
+
+// src/types-v2.ts
+var V2QueryType = {
+  CHALLENGE: 0,
+  BASIC: 1,
+  PLAYERS: 2
+};
+var V2ResponseFlag = {
+  HAS_MORE_PLAYERS: 1,
+  AUTH_REQUIRED: 2,
+  IS_NETWORK: 16,
+  HAS_ADDRESS: 32
+};
+var V2TLVType = {
+  SERVER_INFO: 1,
+  PLAYER_LIST: 2
+};
+
+// src/protocol-v2.ts
+var V2_REQUEST_MAGIC = Buffer.from("ONEQUERY", "ascii");
+var V2_RESPONSE_MAGIC = Buffer.from("ONEREPLY", "ascii");
+var CHALLENGE_TOKEN_SIZE = 32;
+function buildChallengeRequest() {
+  const buf = Buffer.alloc(V2_REQUEST_MAGIC.length + 1);
+  V2_REQUEST_MAGIC.copy(buf, 0);
+  buf[V2_REQUEST_MAGIC.length] = V2QueryType.CHALLENGE;
+  return buf;
+}
+function buildV2Request(type, token, requestId, flags, offset, authToken) {
+  const authBuf = authToken ? Buffer.from(authToken, "utf8") : null;
+  const authLength = authBuf ? 2 + authBuf.length : 0;
+  const totalLength = V2_REQUEST_MAGIC.length + 1 + 32 + 4 + 2 + 4 + authLength;
+  const buf = Buffer.alloc(totalLength);
+  let pos = 0;
+  V2_REQUEST_MAGIC.copy(buf, pos);
+  pos += V2_REQUEST_MAGIC.length;
+  buf[pos++] = type;
+  token.copy(buf, pos);
+  pos += 32;
+  buf.writeUInt32LE(requestId, pos);
+  pos += 4;
+  buf.writeUInt16LE(flags, pos);
+  pos += 2;
+  buf.writeUInt32LE(offset, pos);
+  pos += 4;
+  if (authBuf) {
+    buf.writeUInt16LE(authBuf.length, pos);
+    pos += 2;
+    authBuf.copy(buf, pos);
+  }
+  return buf;
+}
+function validateV2Response(buf) {
+  if (buf.length < V2_RESPONSE_MAGIC.length) {
+    return false;
+  }
+  return buf.subarray(0, V2_RESPONSE_MAGIC.length).equals(V2_RESPONSE_MAGIC);
+}
+function parseChallengeResponse(buf) {
+  if (!validateV2Response(buf)) {
+    throw new Error("Invalid V2 response: magic mismatch");
+  }
+  const tokenOffset = V2_RESPONSE_MAGIC.length + 1;
+  if (buf.length < tokenOffset + CHALLENGE_TOKEN_SIZE) {
+    throw new Error("Invalid challenge response: too short");
+  }
+  return Buffer.from(buf.subarray(tokenOffset, tokenOffset + CHALLENGE_TOKEN_SIZE));
+}
+function parseV2ResponseHeader(buf) {
+  if (!validateV2Response(buf)) {
+    throw new Error("Invalid V2 response: magic mismatch");
+  }
+  const reader = new BufferReader(buf);
+  reader.readBytes(V2_RESPONSE_MAGIC.length);
+  const protocolVersion = reader.readUInt8();
+  const flags = reader.readUInt16LE();
+  const requestId = reader.readUInt32LE();
+  const payloadLength = reader.readUInt16LE();
+  return { protocolVersion, flags, requestId, payloadLength };
+}
+function parseTLVEntries(payload) {
+  const entries = [];
+  const reader = new BufferReader(payload);
+  while (reader.remaining >= 4) {
+    const type = reader.readUInt16LE();
+    const length = reader.readUInt16LE();
+    if (reader.remaining < length) {
+      throw new Error("Invalid TLV: truncated value");
+    }
+    const value = reader.readBytes(length);
+    entries.push({ type, value });
+  }
+  return entries;
+}
+function parseV2Response(buf) {
+  const header = parseV2ResponseHeader(buf);
+  const headerSize = V2_RESPONSE_MAGIC.length + 1 + 2 + 4 + 2;
+  const payload = buf.subarray(headerSize, headerSize + header.payloadLength);
+  const entries = parseTLVEntries(payload);
+  return { header, entries };
+}
+function parseTLVServerInfo(entry, hasAddress, isNetwork) {
+  if (entry.type !== V2TLVType.SERVER_INFO) {
+    throw new Error(`Expected SERVER_INFO TLV (${V2TLVType.SERVER_INFO}), got ${entry.type}`);
+  }
+  const reader = new BufferReader(entry.value);
+  const serverName = reader.readString();
+  const motd = reader.readString();
+  const currentPlayers = reader.readInt32LE();
+  const maxPlayers = reader.readInt32LE();
+  const version = reader.readString();
+  const protocolVersion = reader.readInt32LE();
+  const protocolHash = reader.readString();
+  const result = {
+    serverName,
+    motd,
+    currentPlayers,
+    maxPlayers,
+    version,
+    protocolVersion,
+    protocolHash,
+    isNetwork
+  };
+  if (hasAddress && reader.remaining >= 2) {
+    result.host = reader.readString();
+    if (reader.remaining >= 2) {
+      result.hostPort = reader.readUInt16LE();
+    }
+  }
+  return result;
+}
+function parseTLVPlayerList(entry) {
+  if (entry.type !== V2TLVType.PLAYER_LIST) {
+    throw new Error(`Expected PLAYER_LIST TLV (${V2TLVType.PLAYER_LIST}), got ${entry.type}`);
+  }
+  const reader = new BufferReader(entry.value);
+  const totalPlayers = reader.readInt32LE();
+  const playersInResponse = reader.readInt32LE();
+  const offset = reader.readInt32LE();
+  const players = [];
+  for (let i = 0; i < playersInResponse; i++) {
+    const name = reader.readString();
+    const uuid = reader.readUUIDLE();
+    players.push({ name, uuid });
+  }
+  return { players, totalPlayers, offset };
+}
+function findTLVEntry(entries, type) {
+  return entries.find((e) => e.type === type);
+}
+
+// src/query-v2.ts
+var DEFAULT_TIMEOUT2 = 5e3;
+var TOKEN_TTL_MS = 3e4;
+var TOKEN_REFRESH_BUFFER_MS = 5e3;
+var CLEANUP_INTERVAL_MS = 6e4;
+var challengeCache = /* @__PURE__ */ new Map();
+var cleanupScheduled = false;
+function scheduleCleanup() {
+  if (cleanupScheduled) return;
+  cleanupScheduled = true;
+  setTimeout(() => {
+    const now = Date.now();
+    for (const [key, entry] of challengeCache) {
+      if (now >= entry.expiresAt) {
+        challengeCache.delete(key);
+      }
+    }
+    cleanupScheduled = false;
+    if (challengeCache.size > 0) {
+      scheduleCleanup();
+    }
+  }, CLEANUP_INTERVAL_MS).unref();
+}
+function clearChallengeCache() {
+  challengeCache.clear();
+}
+function sendUDP(host, port, data, timeout) {
+  return new Promise((resolve, reject) => {
+    const socket = import_node_dgram2.default.createSocket("udp4");
+    let timeoutHandle;
+    let closed = false;
+    const cleanup = () => {
+      if (closed) return;
+      closed = true;
+      clearTimeout(timeoutHandle);
+      try {
+        socket.close();
+      } catch {
+      }
+    };
+    socket.on("message", (msg) => {
+      cleanup();
+      resolve(msg);
+    });
+    socket.on("error", (err) => {
+      cleanup();
+      reject(err);
+    });
+    timeoutHandle = setTimeout(() => {
+      cleanup();
+      reject(new Error(`Query timeout after ${timeout}ms`));
+    }, timeout);
+    socket.send(data, port, host, (err) => {
+      if (err) {
+        cleanup();
+        reject(err);
+      }
+    });
+  });
+}
+async function fetchChallenge(host, port, timeout) {
+  const request = buildChallengeRequest();
+  const response = await sendUDP(host, port, request, timeout);
+  return parseChallengeResponse(response);
+}
+async function ensureChallenge(host, port, timeout) {
+  const key = `${host}:${port}`;
+  const cached = challengeCache.get(key);
+  const now = Date.now();
+  if (cached && now < cached.expiresAt - TOKEN_REFRESH_BUFFER_MS) {
+    cached.requestId++;
+    return cached;
+  }
+  const token = await fetchChallenge(host, port, timeout);
+  const entry = {
+    token,
+    expiresAt: now + TOKEN_TTL_MS,
+    requestId: 1
+  };
+  challengeCache.set(key, entry);
+  scheduleCleanup();
+  return entry;
+}
+async function performV2Query(host, port, type, offset, timeout, authToken) {
+  const challenge = await ensureChallenge(host, port, timeout);
+  const request = buildV2Request(type, challenge.token, challenge.requestId, 0, offset, authToken);
+  const response = await sendUDP(host, port, request, timeout);
+  return parseV2Response(response);
+}
+async function queryV2(host, port = 5520, options = {}) {
+  const timeout = options.timeout ?? DEFAULT_TIMEOUT2;
+  const wantPlayers = options.players === true || options.players === "all";
+  const offset = options.playerOffset ?? 0;
+  const { header: basicHeader, entries: basicEntries } = await performV2Query(
+    host,
+    port,
+    V2QueryType.BASIC,
+    0,
+    timeout,
+    options.authToken
+  );
+  const hasAddress = (basicHeader.flags & V2ResponseFlag.HAS_ADDRESS) !== 0;
+  const isNetwork = (basicHeader.flags & V2ResponseFlag.IS_NETWORK) !== 0;
+  const serverInfoEntry = findTLVEntry(basicEntries, V2TLVType.SERVER_INFO);
+  if (!serverInfoEntry) {
+    throw new Error("Response missing SERVER_INFO TLV");
+  }
+  const serverInfo = parseTLVServerInfo(serverInfoEntry, hasAddress, isNetwork);
+  if (!wantPlayers) {
+    return serverInfo;
+  }
+  const { header: playersHeader, entries: playersEntries } = await performV2Query(
+    host,
+    port,
+    V2QueryType.PLAYERS,
+    offset,
+    timeout,
+    options.authToken
+  );
+  const hasMorePlayers = (playersHeader.flags & V2ResponseFlag.HAS_MORE_PLAYERS) !== 0;
+  const playerListEntry = findTLVEntry(playersEntries, V2TLVType.PLAYER_LIST);
+  if (!playerListEntry) {
+    throw new Error("Response missing PLAYER_LIST TLV");
+  }
+  const playerList = parseTLVPlayerList(playerListEntry);
+  let players = playerList.players;
+  let currentOffset = playerList.offset + players.length;
+  let hasMore = hasMorePlayers;
+  if (options.players === "all" && hasMore) {
+    const allPlayers = [...players];
+    while (hasMore) {
+      const nextResult = await performV2Query(
+        host,
+        port,
+        V2QueryType.PLAYERS,
+        currentOffset,
+        timeout,
+        options.authToken
+      );
+      const nextHasMore = (nextResult.header.flags & V2ResponseFlag.HAS_MORE_PLAYERS) !== 0;
+      const nextPlayerEntry = findTLVEntry(nextResult.entries, V2TLVType.PLAYER_LIST);
+      if (!nextPlayerEntry) {
+        break;
+      }
+      const nextPlayerList = parseTLVPlayerList(nextPlayerEntry);
+      allPlayers.push(...nextPlayerList.players);
+      currentOffset = nextPlayerList.offset + nextPlayerList.players.length;
+      hasMore = nextHasMore;
+    }
+    players = allPlayers;
+    hasMore = false;
+  }
+  return {
+    ...serverInfo,
+    players,
+    totalPlayers: playerList.totalPlayers,
+    offset: playerList.offset,
+    hasMore
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  query
+  V2QueryType,
+  V2ResponseFlag,
+  V2TLVType,
+  clearChallengeCache,
+  query,
+  queryV2
 });
 //# sourceMappingURL=index.cjs.map