@sagl/query 0.0.0-stage → 0.1.0-next.53

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Burnett-Taylor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+# @sagl/query
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Ask [SAGL](https://docs.sagl.mp) servers (GTA: San Andreas multiplayer) about themselves without joining them: their name, who's on, their branding and logo, and whatever the gamemode adds (a description, links, tags, its own values). For server lists, websites and bots. Plain Node.js, no dependencies.
+
+```sh
+npm install @sagl/query
+```
+
+```js
+import { queryServer } from "@sagl/query";
+
+const { info, ping } = await queryServer("play.example.com", 7777);
+console.log(`${info.name}: ${info.players?.online}/${info.players?.max} players, ${ping} ms`);
+for (const p of info.players?.list ?? []) console.log(`  ${p.name} (score ${p.score}, ${p.ping} ms)`);
+console.log(info.links?.discord);
+```
+
+`queryServer(host, port = 7777, options)` resolves to:
+
+- `info`: what the server says. Its fields are listed below.
+- `ping`: the round trip, in milliseconds.
+- `logo`: the logo's bytes (PNG or JPEG), when `logo: true` is passed and the server has one. They're checked against its SHA-256.
+
+It rejects if the server doesn't answer. The options are:
+
+- `timeout`: how long to wait for each reply, in ms. Default 1500.
+- `logo`: fetch the logo too. Default false.
+
+`info` has these fields:
+
+| Field | |
+|---|---|
+| `name`, `version`, `protocol` | The server's name, its SAGL version, and the protocol a game client needs to join it |
+| `players` | `{ online, max, list?: [{ id, name, score, ping }], truncated? }`. Left out, or without `list`, if the server hides it |
+| `branding` | `{ logo: { sha256, size } \| null, primary, secondary, showName }`. The colours are `"#rrggbb"` or `null` |
+| `description`, `gamemode`, `language`, `tags`, `links` | The gamemode's, if set. `links` is by name: `website`, `discord`, ... |
+| `values` | The gamemode's own key/values, which can change at any time |
+
+The query uses UDP on the server's game port. Servers can also serve the same JSON over HTTP (`GET /` and `GET /logo`) if their owner turns it on. The format is documented at [docs.sagl.mp](https://docs.sagl.mp/server-api/query/).
+
+MIT licence.

package/dist/query-client.d.ts

@@ -0,0 +1,66 @@
+/** A query value: the gamemode's own, changed whenever it likes. */
+export type QueryValue = string | number | boolean | null;
+/** What a query says (`queryServer`, or the HTTP endpoint). */
+export interface QueryResult {
+    /** The query format's version (1). */
+    query: number;
+    name: string;
+    /** The server's SAGL version. */
+    version: string;
+    /** Its protocol: a client needs the same to join. */
+    protocol: number;
+    /** Left out if the server hides them. */
+    players?: {
+        online: number;
+        max: number;
+        /** Left out if the server shows only the count. */
+        list?: {
+            id: number;
+            name: string;
+            score: number;
+            ping: number;
+        }[];
+        /** The list was too long to send whole. */
+        truncated?: boolean;
+    };
+    branding: {
+        /** Its logo (a square PNG or JPEG), to fetch by hash, or null. */
+        logo: {
+            sha256: string;
+            size: number;
+        } | null;
+        /** `"#rrggbb"`, or null for SAGL's own. */
+        primary: string | null;
+        secondary: string | null;
+        showName: boolean;
+    };
+    description?: string;
+    gamemode?: string;
+    language?: string;
+    tags?: string[];
+    links?: Record<string, string>;
+    values?: Record<string, QueryValue>;
+}
+export interface QueryServerOptions {
+    /** How long to wait for each reply, in ms. Default 1500. */
+    timeout?: number;
+    /** Fetches the logo too (checked against its hash). Default false. */
+    logo?: boolean;
+}
+export interface QueryServerResult {
+    info: QueryResult;
+    /** The round trip, in ms. */
+    ping: number;
+    /** With `logo: true`, if it has one. */
+    logo?: Buffer;
+}
+/**
+ * Asks a SAGL server about itself over UDP, as server lists do: its name,
+ * players, branding and the gamemode's fields. Rejects if it doesn't answer.
+ *
+ * ```ts
+ * const { info, ping } = await queryServer("play.example.com", 7777);
+ * console.log(`${info.name}: ${info.players?.online}/${info.players?.max}, ${ping} ms`);
+ * ```
+ */
+export declare function queryServer(host: string, port?: number, options?: QueryServerOptions): Promise<QueryServerResult>;

package/dist/query-client.js

@@ -0,0 +1,127 @@
+// Asking a SAGL server about itself without joining it (the query: see
+// docs/server-api/query.md). Plain Node, no addon: it's also published on
+// its own as @sagl/query, for websites, bots and server lists.
+import * as dgram from "node:dgram";
+import { createHash } from "node:crypto";
+// ---- Asking a server -----------------------------------------------------------------
+const REQUEST = 64;
+const HEADER = 8;
+const KIND_CHALLENGE = 0, KIND_INFO = 1, KIND_LOGO = 2;
+function request(kind, token, arg = 0) {
+    const b = Buffer.alloc(REQUEST);
+    b.write("SAGQ", 0, "latin1");
+    b[4] = 1;
+    b[5] = kind;
+    b.writeUInt32LE(token >>> 0, 8);
+    b.writeUInt32LE(arg >>> 0, 12);
+    return b;
+}
+/**
+ * Asks a SAGL server about itself over UDP, as server lists do: its name,
+ * players, branding and the gamemode's fields. Rejects if it doesn't answer.
+ *
+ * ```ts
+ * const { info, ping } = await queryServer("play.example.com", 7777);
+ * console.log(`${info.name}: ${info.players?.online}/${info.players?.max}, ${ping} ms`);
+ * ```
+ */
+export function queryServer(host, port = 7777, options = {}) {
+    const timeout = options.timeout ?? 1500;
+    const socket = dgram.createSocket("udp4");
+    let token = 0;
+    let listener = null;
+    socket.on("message", (msg) => {
+        if (msg.length < HEADER || msg.toString("latin1", 0, 4) !== "SAGR" || msg[4] !== 1)
+            return;
+        if (msg[5] === KIND_CHALLENGE && msg.length >= HEADER + 4)
+            token = msg.readUInt32LE(HEADER);
+        listener?.(msg);
+    });
+    const send = (b) => new Promise((resolve, reject) => socket.send(b, port, host, (e) => (e ? reject(e) : resolve())));
+    // Sends until `done` takes a reply (resolving), answering challenges.
+    const exchange = (make, take) => new Promise((resolve, reject) => {
+        let tries = 0;
+        let timer;
+        const attempt = () => {
+            if (++tries > 4) {
+                listener = null;
+                reject(new Error(`${host}:${port} didn't answer`));
+                return;
+            }
+            clearTimeout(timer);
+            timer = setTimeout(attempt, timeout);
+            send(make()).catch((e) => {
+                clearTimeout(timer);
+                listener = null;
+                reject(e);
+            });
+        };
+        listener = (msg) => {
+            if (msg[5] === KIND_CHALLENGE) {
+                tries = Math.max(0, tries - 1); // a challenge isn't a lost try
+                attempt();
+                return;
+            }
+            const got = take(msg);
+            if (got === undefined) {
+                clearTimeout(timer);
+                timer = setTimeout(attempt, timeout);
+                return;
+            }
+            clearTimeout(timer);
+            listener = null;
+            resolve(got);
+        };
+        attempt();
+    });
+    const run = async () => {
+        let parts = [];
+        let serial = -1, total = 0, have = 0, sent = 0, ping = 0;
+        const json = await exchange(() => {
+            sent = performance.now();
+            return request(KIND_INFO, token);
+        }, (msg) => {
+            if (msg[5] !== KIND_INFO || msg.length < HEADER + 12)
+                return undefined;
+            const s = msg.readUInt32LE(HEADER), part = msg.readUInt16LE(HEADER + 8), count = msg.readUInt16LE(HEADER + 10);
+            if (s !== serial) {
+                serial = s;
+                total = msg.readUInt32LE(HEADER + 4);
+                parts = new Array(count);
+                have = 0;
+                ping = Math.round(performance.now() - sent);
+            }
+            if (part >= parts.length || parts[part])
+                return undefined;
+            parts[part] = msg.subarray(HEADER + 12);
+            if (++have < parts.length)
+                return undefined;
+            const all = Buffer.concat(parts);
+            return all.length === total ? all.toString("utf8") : undefined;
+        });
+        const info = JSON.parse(json);
+        const result = { info, ping };
+        if (options.logo && info.branding?.logo) {
+            const want = info.branding.logo;
+            const chunks = [];
+            let got = 0;
+            while (got < want.size) {
+                const chunk = await exchange(() => request(KIND_LOGO, token, got), (msg) => (msg[5] === KIND_LOGO && msg.length >= HEADER + 40 && msg.readUInt32LE(HEADER + 4) === got ? msg : undefined));
+                const size = chunk.readUInt32LE(HEADER);
+                if (size !== want.size)
+                    throw new Error("the logo changed while it was fetched");
+                const data = chunk.subarray(HEADER + 40);
+                if (!data.length)
+                    throw new Error("the logo stopped short");
+                chunks.push(data);
+                got += data.length;
+            }
+            const logo = Buffer.concat(chunks);
+            if (createHash("sha256").update(logo).digest("hex") !== want.sha256)
+                throw new Error("the logo didn't match its hash");
+            result.logo = logo;
+        }
+        return result;
+    };
+    return run().finally(() => socket.close());
+}

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@sagl/query",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-next.53",
+  "description": "Ask SAGL (GTA: San Andreas multiplayer) servers about themselves: name, players, branding, links",
+  "type": "module",
+  "main": "dist/query-client.js",
+  "types": "dist/query-client.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/query-client.d.ts",
+      "default": "./dist/query-client.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "homepage": "https://docs.sagl.mp/server-api/query/",
+  "keywords": [
+    "gta",
+    "san-andreas",
+    "multiplayer",
+    "server-query",
+    "server-list",
+    "sagl"
+  ]
+}