API-ver2

Author: NhanAZ

.poggit.yml

@@ -0,0 +1,14 @@
+--- # Poggit-CI Manifest
+build-by-default: true
+branches:
+- master
+projects:
+  QueryServerCore:
+    type: library
+    path: ""
+  QueryServer:
+    path: ""
+    libs:
+      - src: NhanAZ-Libraries/QueryServer/QueryServerCore
+        version: ^0.0.3
+...

README.md

@@ -1,35 +1,46 @@
-# QueryServer
+# QueryServer (virion + plugin)
 
-A lightweight PocketMine-MP plugin that queries Bedrock servers using the public `api.mcsrvstat.us` v3 endpoint with a UDP fallback (libpmquery). It includes a small API so other plugins can request queries asynchronously without blocking the main thread.
+Two deliverables in one repo:
+- **QueryServerCore (virion/library)**: async HTTP (api.mcsrvstat.us v3) + UDP fallback (libpmquery) with a tiny callback-based API for other plugins.
+- **QueryServer (plugin)**: thin wrapper exposing `/query` command that uses the core.
 
 ## Features
-- `/query <host[:port]> [port]` — fetch server status via HTTP; automatically falls back to UDP.
-- Built-in UDP fallback uses an embedded, namespaced copy of **libpmquery**.
-- Non-blocking: both HTTP and UDP queries run on async workers.
-- Simple API for other plugins to trigger queries programmatically.
+- Async HTTP query (no main-thread blocking) with automatic UDP fallback.
+- Embedded, namespaced **libpmquery**.
+- Callback API for other plugins (no promises/futures needed).
 
-## Installation
-1. Drop the plugin phar into your `plugins/` folder.
-2. Ensure `php` version matches PocketMine-MP 5.x (PHP 8.1+).
-
-## Command
+## Command (plugin)
 - `/query <domain/ip[:port]> [port]`  
   Example: `/query test.pmmp.io 19132`
 
-## API Usage (for other plugins)
+## API Usage (virion)
 ```php
 use NhanAZ\QueryServer\Main;
 
 $api = Main::getInstance()->getApi();
 $api->query("test.pmmp.io", 19132, function(array $result): void {
     if (($result['ok'] ?? false) === true) {
-        // $result['data'] contains either API status (object) or UDP fields (array)
+        // $result['source'] === 'api' or 'udp'
+        // $result['data']  : API status object (api) or UDP array (udp)
     } else {
-        // handle $result['error']
+        // $result['error']
     }
 });
 ```
 
+## Installation
+### As plugin
+1. Download the `QueryServer` phar.
+2. Drop into `plugins/` (PocketMine-MP 5.x / PHP 8.1+).
+
+### As virion
+Add dependency in `.poggit.yml`:
+```yaml
+libs:
+  - src: NhanAZ-Libraries/QueryServer/QueryServerCore
+    version: ^0.0.3
+```
+
 ## License & Attribution
-- This plugin is licensed under **LGPL-3.0-or-later**.
-- Embedded library **libpmquery** (LGPL-3.0-or-later) by [jasonw4331/libpmquery](https://github.com/jasonw4331/libpmquery).
+- LGPL-3.0-or-later.
+- Bundled **libpmquery** (LGPL-3.0-or-later) by [jasonw4331/libpmquery](https://github.com/jasonw4331/libpmquery).

composer.json

@@ -1,6 +1,6 @@
 {
-  "name": "nhanaz/queryserver",
-  "description": "Query information of other Minecraft servers via HTTP API v3 with UDP fallback.",
+  "name": "nhanaz-libraries/queryserver",
+  "description": "QueryServerCore virion + QueryServer plugin: async HTTP (api.mcsrvstat.us v3) with UDP fallback.",
   "type": "project",
   "license": "LGPL-3.0-or-later",
   "require": {

src/FallbackQueryTask.php

@@ -17,9 +17,6 @@ public function __construct(
 	}
 
 	public function onRun(): void {
-		require_once dirname(__DIR__) . "/src/libpmquery/PMQuery.php";
-		require_once dirname(__DIR__) . "/src/libpmquery/PmQueryException.php";
-
 		$result = [
 			"ok" => false,
 			"host" => $this->host,

src/Main.php

@@ -77,6 +77,7 @@ public static function handleQueryResult(mixed $result): void {
 		$console = new ConsoleCommandSender(Server::getInstance(), Server::getInstance()->getLanguage());
 
 		$address = is_array($result) ? ($result["address"] ?? null) : null;
+		$requestId = is_array($result) ? ($result["requestId"] ?? null) : null;
 		[$host, $port] = self::splitAddress($address);
 
 		$apiShown = false;
@@ -89,17 +90,33 @@ public static function handleQueryResult(mixed $result): void {
 		} else {
 			$error = is_array($result) ? ($result["error"] ?? "Unknown error") : "No data returned";
 			$console->sendMessage(self::info("Primary API failed: " . $error));
+
+			if ($requestId !== null && self::getInstance()->deliverCallback($requestId, ["ok" => false, "source" => "api", "error" => $error])) {
+				// still allow fallback to run if available
+			}
 		}
 
 		if ($host !== null && $port !== null) {
 			$console->sendMessage(self::info("Using fallback UDP query..."));
-			Server::getInstance()->getAsyncPool()->submitTask(new FallbackQueryTask($host, $port));
+			Server::getInstance()->getAsyncPool()->submitTask(new FallbackQueryTask($host, $port, requestId: $result["requestId"] ?? null));
 			return;
 		}
 
 		if (!$apiShown && !$fallbackShown) {
 			$console->sendMessage(self::error("The server is offline or has blocked queries!"));
 			$console->sendMessage(self::info("Try another query method using /query <domain> <port>"));
+
+			if ($requestId !== null) {
+				self::getInstance()->deliverCallback($requestId, ["ok" => false, "source" => "api", "error" => "offline or blocked"]);
+			}
+		} elseif ($apiShown && $requestId !== null) {
+			// deliver API success to caller (even if fallback scheduled elsewhere, which returns separately)
+			self::getInstance()->deliverCallback($requestId, [
+				"ok" => true,
+				"source" => "api",
+				"address" => $address,
+				"data" => $result["data"] ?? null
+			]);
 		}
 	}
 

virion.yml

@@ -0,0 +1,8 @@
+name: QueryServerCore
+antigen: NhanAZ\\QueryServer
+api: 5.0.0
+version: 0.0.3
+authors:
+  - NhanAZ
+description: Core library for async server querying (HTTP v3 + UDP fallback)
+license: LGPL-3.0-or-later