@srvquery/core 0.0.1-next.0

package/README.md

@@ -0,0 +1,130 @@
+# @srvquery/core
+
+![npm Version](https://shieldcn.dev/npm/@srvquery/core.svg?variant=secondary) ![npm Weekly Downloads](https://shieldcn.dev/npm/@srvquery/core/downloads.svg)
+
+Shared binary parsing and UDP query primitives for `srvquery` packages.
+
+## Installation
+
+```sh
+pnpm add @srvquery/core
+```
+
+## API
+
+### BufferCursor
+
+```ts
+import { BufferCursor } from "@srvquery/core";
+
+const cursor = new BufferCursor(
+  Buffer.from([
+    0x2a, // UInt8
+    0x34,
+    0x12, // UInt16LE
+    0xff,
+    0xff,
+    0xff,
+    0xff, // Int32LE
+    0x78,
+    0x56,
+    0x34,
+    0x12, // UInt32LE
+    0x00,
+    0x00,
+    0xc0,
+    0x3f, // FloatLE
+    0x01,
+    0x00,
+    0x00,
+    0x00,
+    0x00,
+    0x00,
+    0x00,
+    0x00, // BigUInt64LE
+    0x68,
+    0x69,
+    0x00, // C string
+    0xaa,
+    0xbb, // bytes
+    0xcc, // skipped byte
+    0xdd,
+    0xee, // remaining bytes
+  ]),
+);
+
+console.log(cursor.offset); // 0
+console.log(cursor.readUInt8()); // 42
+console.log(cursor.readUInt16LE()); // 4660
+console.log(cursor.readInt32LE()); // -1
+console.log(cursor.readUInt32LE()); // 305419896
+console.log(cursor.readFloatLE()); // 1.5
+console.log(cursor.readBigUInt64LE()); // 1n
+console.log(cursor.readCString()); // "hi"
+console.log(cursor.readBytes(2)); // <Buffer aa bb>
+
+cursor.skip(1);
+
+console.log(cursor.remaining); // 2
+console.log(cursor.readRemaining()); // <Buffer dd ee>
+```
+
+### createUdpSocket
+
+Raw UDP sockets do not retry unless `retry` is provided. `using` invokes `Symbol.dispose` when the
+socket leaves scope:
+
+```ts
+import { backoffStrategy, createUdpSocket } from "@srvquery/core";
+
+using socket = createUdpSocket(
+  {
+    host: "127.0.0.1",
+    port: 27015,
+  },
+  {
+    timeout: 2_000,
+    type: "udp4",
+    retry: {
+      retries: 3,
+      strategy: backoffStrategy,
+    },
+  },
+);
+
+const packets = await socket.send(
+  { payload: Buffer.from("status\0") },
+  {
+    accept: (packet) => packet.length > 0,
+    end: (accepted) => accepted.length === 1,
+  },
+);
+
+console.log(packets[0]);
+```
+
+Call `close` when the lifetime cannot be expressed with `using`:
+
+```ts
+const socket = createUdpSocket({ host: "127.0.0.1", port: 27015 });
+
+socket.close();
+```
+
+### withRetry
+
+Use the retry helper independently when an asynchronous operation needs the same retry behavior:
+
+```ts
+import { backoffStrategy, withRetry } from "@srvquery/core";
+
+const result = await withRetry(query, {
+  retries: 3,
+  strategy: backoffStrategy,
+  fatal: (error) => error instanceof TypeError,
+});
+```
+
+The exported `RetryStrategy` type has the signature `(attempt: number) => number`. Its return value
+is the delay in milliseconds before the next attempt. The included `backoffStrategy` uses
+exponential delays of 100 ms, 200 ms, 400 ms, and so on.

package/dist/bin/buffer-cursor.d.ts

@@ -0,0 +1,44 @@
+/** Reads typed values sequentially from a buffer while tracking the current offset. */
+export declare class BufferCursor {
+    #private;
+    readonly buffer: Buffer;
+    /**
+     * Creates a cursor positioned at the start of a buffer.
+     * @param buffer Buffer to read from.
+     */
+    constructor(buffer: Buffer);
+    /** Zero-based position of the next byte to read. */
+    get offset(): number;
+    /** Number of unread bytes after the current offset. */
+    get remaining(): number;
+    /** Reads an unsigned 8-bit integer and advances the cursor by one byte. */
+    readUInt8(): number;
+    /** Reads a little-endian unsigned 16-bit integer and advances the cursor by two bytes. */
+    readUInt16LE(): number;
+    /** Reads a little-endian signed 32-bit integer and advances the cursor by four bytes. */
+    readInt32LE(): number;
+    /** Reads a little-endian unsigned 32-bit integer and advances the cursor by four bytes. */
+    readUInt32LE(): number;
+    /** Reads a little-endian 32-bit float and advances the cursor by four bytes. */
+    readFloatLE(): number;
+    /** Reads a little-endian unsigned 64-bit integer and advances the cursor by eight bytes. */
+    readBigUInt64LE(): bigint;
+    /**
+     * Reads a null-terminated UTF-8 string.
+     * Advances to the byte after the terminator, or to the end when no terminator is present.
+     */
+    readCString(): string;
+    /**
+     * Reads a buffer view of the requested length and advances the cursor.
+     * @throws {RangeError} When `length` is invalid or exceeds the remaining bytes.
+     */
+    readBytes(length: number): Buffer;
+    /**
+     * Advances the cursor without reading bytes.
+     * @throws {RangeError} When `length` is invalid or exceeds the remaining bytes.
+     */
+    skip(length: number): void;
+    /** Reads all unread bytes and advances the cursor to the end of the buffer. */
+    readRemaining(): Buffer;
+}
+//# sourceMappingURL=buffer-cursor.d.ts.map

package/dist/bin/buffer-cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buffer-cursor.d.ts","sourceRoot":"","sources":["../../src/bin/buffer-cursor.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,qBAAa,YAAY;;IAOX,QAAQ,CAAC,MAAM,EAAE,MAAM;IAJnC;;;OAGG;IACH,YAAqB,MAAM,EAAE,MAAM,EAAI;IAEvC,oDAAoD;IACpD,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,uDAAuD;IACvD,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,2EAA2E;IAC3E,SAAS,IAAI,MAAM,CAIlB;IAED,0FAA0F;IAC1F,YAAY,IAAI,MAAM,CAIrB;IAED,yFAAyF;IACzF,WAAW,IAAI,MAAM,CAIpB;IAED,2FAA2F;IAC3F,YAAY,IAAI,MAAM,CAIrB;IAED,gFAAgF;IAChF,WAAW,IAAI,MAAM,CAIpB;IAED,4FAA4F;IAC5F,eAAe,IAAI,MAAM,CAIxB;IAED;;;OAGG;IACH,WAAW,IAAI,MAAM,CASpB;IAED;;;OAGG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAOhC;IAED;;;OAGG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAKzB;IAED,+EAA+E;IAC/E,aAAa,IAAI,MAAM,CAItB;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { BufferCursor } from "./bin/buffer-cursor";
+export { type CreateUdpSocketOptions, type CreateUdpSocketParams, type UdpSocketSendOptions, type UdpSocketSendParams, type UdpSocket, createUdpSocket, } from "./net/udp-socket";
+export { type CreateHttpClientOptions, type CreateHttpClientParams, type HttpClient, createHttpClient, } from "./net/http-client";
+export { QueryDnsResolutionError, QueryTransportError, QueryTimeoutError } from "./net/errors";
+export { resolveIpv4 } from "./net/dns";
+export { type RetryOptions, type RetryStrategy, backoffStrategy, defaultRetryOptions, withRetry, } from "./util/retry";
+export { defaultTimeout } from "./util/timing";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAInD,OAAO,EACL,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,SAAS,EACd,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,UAAU,EACf,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAC/F,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAIxC,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,eAAe,EACf,mBAAmB,EACnB,SAAS,GACV,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,361 @@
+import dgram from "node:dgram";
+import http from "node:http";
+import https from "node:https";
+import dns from "node:dns";
+//#region src/bin/buffer-cursor.ts
+/** Reads typed values sequentially from a buffer while tracking the current offset. */
+var BufferCursor = class {
+	#offset = 0;
+	/**
+	* Creates a cursor positioned at the start of a buffer.
+	* @param buffer Buffer to read from.
+	*/
+	constructor(buffer) {
+		this.buffer = buffer;
+	}
+	/** Zero-based position of the next byte to read. */
+	get offset() {
+		return this.#offset;
+	}
+	/** Number of unread bytes after the current offset. */
+	get remaining() {
+		return this.buffer.length - this.#offset;
+	}
+	/** Reads an unsigned 8-bit integer and advances the cursor by one byte. */
+	readUInt8() {
+		const value = this.buffer.readUInt8(this.#offset);
+		this.#offset += 1;
+		return value;
+	}
+	/** Reads a little-endian unsigned 16-bit integer and advances the cursor by two bytes. */
+	readUInt16LE() {
+		const value = this.buffer.readUInt16LE(this.#offset);
+		this.#offset += 2;
+		return value;
+	}
+	/** Reads a little-endian signed 32-bit integer and advances the cursor by four bytes. */
+	readInt32LE() {
+		const value = this.buffer.readInt32LE(this.#offset);
+		this.#offset += 4;
+		return value;
+	}
+	/** Reads a little-endian unsigned 32-bit integer and advances the cursor by four bytes. */
+	readUInt32LE() {
+		const value = this.buffer.readUInt32LE(this.#offset);
+		this.#offset += 4;
+		return value;
+	}
+	/** Reads a little-endian 32-bit float and advances the cursor by four bytes. */
+	readFloatLE() {
+		const value = this.buffer.readFloatLE(this.#offset);
+		this.#offset += 4;
+		return value;
+	}
+	/** Reads a little-endian unsigned 64-bit integer and advances the cursor by eight bytes. */
+	readBigUInt64LE() {
+		const value = this.buffer.readBigUInt64LE(this.#offset);
+		this.#offset += 8;
+		return value;
+	}
+	/**
+	* Reads a null-terminated UTF-8 string.
+	* Advances to the byte after the terminator, or to the end when no terminator is present.
+	*/
+	readCString() {
+		const terminator = this.buffer.indexOf(0, this.#offset);
+		const value = this.buffer.toString("utf8", this.#offset, terminator === -1 ? this.buffer.length : terminator);
+		this.#offset = terminator === -1 ? this.buffer.length : terminator + 1;
+		return value;
+	}
+	/**
+	* Reads a buffer view of the requested length and advances the cursor.
+	* @throws {RangeError} When `length` is invalid or exceeds the remaining bytes.
+	*/
+	readBytes(length) {
+		if (!Number.isInteger(length) || length < 0 || length > this.remaining) throw new RangeError("Read length is outside the buffer bounds");
+		const value = this.buffer.subarray(this.#offset, this.#offset + length);
+		this.#offset += length;
+		return value;
+	}
+	/**
+	* Advances the cursor without reading bytes.
+	* @throws {RangeError} When `length` is invalid or exceeds the remaining bytes.
+	*/
+	skip(length) {
+		if (!Number.isInteger(length) || length < 0 || length > this.remaining) throw new RangeError("Skip length is outside the buffer bounds");
+		this.#offset += length;
+	}
+	/** Reads all unread bytes and advances the cursor to the end of the buffer. */
+	readRemaining() {
+		const value = this.buffer.subarray(this.#offset);
+		this.#offset = this.buffer.length;
+		return value;
+	}
+};
+//#endregion
+//#region src/net/errors.ts
+/**
+* Error thrown when a query does not receive any response within the
+* configured timeout window, after all retries have been exhausted.
+*/
+var QueryTimeoutError = class extends Error {
+	constructor({ host, port, attempts }) {
+		super(`Query to ${host}:${port} timed out after ${attempts} attempt${attempts === 1 ? "" : "s"}`);
+		this.name = this.constructor.name;
+		this.host = host;
+		this.port = port;
+		this.attempts = attempts;
+	}
+};
+/**
+* Error thrown for transport-level failures unrelated to timeout: low-level socket failures
+* (e.g. `ECONNREFUSED`, `EHOSTUNREACH`), non-2xx HTTP responses, and malformed response bodies.
+*/
+var QueryTransportError = class extends Error {
+	constructor({ message, cause }) {
+		super(message);
+		this.name = this.constructor.name;
+		this.cause = cause;
+	}
+};
+/** Error thrown when a hostname cannot be resolved to an IPv4 address. */
+var QueryDnsResolutionError = class extends Error {
+	constructor({ host, cause }) {
+		super(`Failed to resolve host "${host}" to an IPv4 address`);
+		this.name = this.constructor.name;
+		this.host = host;
+		this.cause = cause;
+	}
+};
+//#endregion
+//#region src/util/timing.ts
+/** Resolves after the requested number of milliseconds. */
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Default time in milliseconds to wait for a response to a single request attempt. */
+const defaultTimeout = 2e3;
+//#endregion
+//#region src/util/retry.ts
+/** Exponential retry strategy producing delays of 100 ms, 200 ms, 400 ms, and so on. */
+const backoffStrategy = (attempt) => 100 * 2 ** (attempt - 1);
+/** Default retry policy: three attempts with exponential backoff. */
+const defaultRetryOptions = Object.freeze({
+	retries: 3,
+	strategy: backoffStrategy
+});
+/**
+* Calls `fn` up to `options.retries` times, retrying on rejection unless
+* `fatal` says otherwise. Throws the last error when every attempt fails.
+* @param fn Asynchronous operation to execute.
+* @param options Attempt count, delay strategy, and fatal-error predicate.
+* @returns The first successful result.
+* @throws The fatal error or the final error after all attempts fail.
+*/
+async function withRetry(fn, { retries, fatal, strategy }) {
+	if (!Number.isInteger(retries) || retries < 1) throw new RangeError("Retry option 'retries' must be a positive integer");
+	let lastError;
+	for (let attempt = 1; attempt <= retries; attempt++) try {
+		return await fn();
+	} catch (err) {
+		lastError = err;
+		if (fatal?.(err)) throw err;
+		if (attempt < retries && strategy) await delay(strategy(attempt));
+	}
+	throw lastError;
+}
+//#endregion
+//#region src/net/udp-socket.ts
+/**
+* Creates a reusable UDP query socket for one destination.
+*
+* Each `send` call collects accepted packets until its completion callback succeeds. When retry
+* options are configured, a timed-out or failed send is repeated on the same socket.
+*/
+const createUdpSocket = ({ host, port }, { timeout = defaultTimeout, type = "udp4", retry } = {}) => {
+	const socket = dgram.createSocket({ type });
+	const sendAttempt = ({ payload }, { accept = () => true, end = () => true } = {}) => {
+		return new Promise((resolve, reject) => {
+			let settled = false;
+			const packets = [];
+			let timer;
+			const settle = (fn) => {
+				if (settled) return;
+				settled = true;
+				cleanup();
+				fn();
+			};
+			const resetTimer = () => {
+				clearTimeout(timer);
+				timer = setTimeout(() => {
+					settle(() => reject(new QueryTimeoutError({
+						host,
+						port,
+						attempts: 1
+					})));
+				}, timeout);
+			};
+			const onMessage = (msg) => {
+				if (settled || !accept(msg)) return;
+				packets.push(msg);
+				if (end(packets)) settle(() => resolve(packets));
+				else resetTimer();
+			};
+			const onError = (err) => {
+				settle(() => reject(new QueryTransportError({
+					message: `Socket error querying ${host}:${port}`,
+					cause: err
+				})));
+			};
+			const cleanup = () => {
+				clearTimeout(timer);
+				socket.off("message", onMessage);
+				socket.off("error", onError);
+			};
+			socket.on("message", onMessage);
+			socket.on("error", onError);
+			resetTimer();
+			socket.send(payload, port, host, (err) => {
+				if (err) settle(() => reject(new QueryTransportError({
+					message: `Failed to send to ${host}:${port}`,
+					cause: err
+				})));
+			});
+		});
+	};
+	const send = async (params, options = {}) => {
+		if (!retry) return sendAttempt(params, options);
+		try {
+			return await withRetry(() => sendAttempt(params, options), retry);
+		} catch (lastError) {
+			if (lastError instanceof QueryTimeoutError) throw new QueryTimeoutError({
+				host,
+				port,
+				attempts: retry.retries
+			});
+			throw lastError;
+		}
+	};
+	return {
+		send,
+		ctx: {
+			host,
+			port
+		},
+		close: () => {
+			socket.close();
+		},
+		[Symbol.dispose]: () => {
+			socket.close();
+		}
+	};
+};
+//#endregion
+//#region src/net/http-client.ts
+const transports = {
+	http,
+	https
+};
+/**
+* Creates a reusable HTTP query client for one destination.
+*
+* Intended for query protocols that expose their state over plain JSON HTTP endpoints. Each `getJson` call is subject to the configured timeout and, when provided, retried according to `options.retry`.
+*/
+const createHttpClient = ({ host, port }, { protocol = "http", timeout = defaultTimeout, retry } = {}) => {
+	const { request } = transports[protocol];
+	const attempt = (path) => new Promise((resolve, reject) => {
+		const req = request({
+			host,
+			port,
+			path,
+			method: "GET"
+		}, (res) => {
+			const chunks = [];
+			res.on("data", (chunk) => chunks.push(chunk));
+			res.on("error", (err) => {
+				reject(new QueryTransportError({
+					message: `HTTP response error from ${protocol}://${host}:${port}${path}`,
+					cause: err
+				}));
+			});
+			res.on("end", () => {
+				const { statusCode = 0 } = res;
+				if (statusCode < 200 || statusCode >= 300) {
+					reject(new QueryTransportError({
+						message: `Received HTTP ${statusCode} from ${protocol}://${host}:${port}${path}`,
+						cause: void 0
+					}));
+					return;
+				}
+				try {
+					resolve(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+				} catch (err) {
+					reject(new QueryTransportError({
+						message: `Received a non-JSON response from ${protocol}://${host}:${port}${path}`,
+						cause: err
+					}));
+				}
+			});
+		});
+		req.setTimeout(timeout, () => {
+			req.destroy(new QueryTimeoutError({
+				host,
+				port,
+				attempts: 1
+			}));
+		});
+		req.on("error", (err) => {
+			if (err instanceof QueryTimeoutError) {
+				reject(err);
+				return;
+			}
+			reject(new QueryTransportError({
+				message: `Failed to query ${protocol}://${host}:${port}${path}`,
+				cause: err
+			}));
+		});
+		req.end();
+	});
+	const getJson = async (path) => {
+		if (!retry) return attempt(path);
+		try {
+			return await withRetry(() => attempt(path), retry);
+		} catch (lastError) {
+			if (lastError instanceof QueryTimeoutError) throw new QueryTimeoutError({
+				host,
+				port,
+				attempts: retry.retries
+			});
+			throw lastError;
+		}
+	};
+	return {
+		getJson,
+		ctx: {
+			host,
+			port
+		}
+	};
+};
+//#endregion
+//#region src/net/dns.ts
+/**
+* Resolves a hostname or IP address to its IPv4 address.
+*
+* Useful for protocols that must embed a numeric IPv4 address in a request
+* packet (rather than a hostname), since query protocols typically operate
+* directly over raw sockets without a resolver of their own.
+*
+* @param host The hostname or IP address to resolve.
+* @returns A promise that resolves to the IPv4 address.
+* @throws {QueryDnsResolutionError} If the host cannot be resolved to an IPv4 address.
+*/
+const resolveIpv4 = (host) => new Promise((resolve, reject) => {
+	dns.lookup(host, { family: 4 }, (err, address) => {
+		if (err) reject(new QueryDnsResolutionError({
+			host,
+			cause: err
+		}));
+		else resolve(address);
+	});
+});
+//#endregion
+export { BufferCursor, QueryDnsResolutionError, QueryTimeoutError, QueryTransportError, backoffStrategy, createHttpClient, createUdpSocket, defaultRetryOptions, defaultTimeout, resolveIpv4, withRetry };

package/dist/net/dns.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Resolves a hostname or IP address to its IPv4 address.
+ *
+ * Useful for protocols that must embed a numeric IPv4 address in a request
+ * packet (rather than a hostname), since query protocols typically operate
+ * directly over raw sockets without a resolver of their own.
+ *
+ * @param host The hostname or IP address to resolve.
+ * @returns A promise that resolves to the IPv4 address.
+ * @throws {QueryDnsResolutionError} If the host cannot be resolved to an IPv4 address.
+ */
+export declare const resolveIpv4: (host: string) => Promise<string>;
+//# sourceMappingURL=dns.d.ts.map

package/dist/net/dns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dns.d.ts","sourceRoot":"","sources":["../../src/net/dns.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,WAAW,SAAU,MAAM,KAAG,OAAO,CAAC,MAAM,CAMrD,CAAC"}

package/dist/net/errors.d.ts

@@ -0,0 +1,45 @@
+type QueryTimeoutErrorCtor = {
+    host: string;
+    port: number;
+    attempts: number;
+};
+/**
+ * Error thrown when a query does not receive any response within the
+ * configured timeout window, after all retries have been exhausted.
+ */
+export declare class QueryTimeoutError extends Error {
+    /** Host targeted by the query. */
+    readonly host: string;
+    /** Port targeted by the query. */
+    readonly port: number;
+    /** Total number of attempts made before the timeout was reported. */
+    readonly attempts: number;
+    constructor({ host, port, attempts }: QueryTimeoutErrorCtor);
+}
+type QueryTransportErrorCtor = {
+    message: string;
+    cause: unknown;
+};
+/**
+ * Error thrown for transport-level failures unrelated to timeout: low-level socket failures
+ * (e.g. `ECONNREFUSED`, `EHOSTUNREACH`), non-2xx HTTP responses, and malformed response bodies.
+ */
+export declare class QueryTransportError extends Error {
+    /** Original error that caused the query to fail, if any. */
+    readonly cause: unknown;
+    constructor({ message, cause }: QueryTransportErrorCtor);
+}
+type QueryDnsResolutionErrorCtor = {
+    host: string;
+    cause: unknown;
+};
+/** Error thrown when a hostname cannot be resolved to an IPv4 address. */
+export declare class QueryDnsResolutionError extends Error {
+    /** Hostname that failed to resolve. */
+    readonly host: string;
+    /** Original DNS lookup error. */
+    readonly cause: unknown;
+    constructor({ host, cause }: QueryDnsResolutionErrorCtor);
+}
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/net/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/net/errors.ts"],"names":[],"mappings":"AAAA,KAAK,qBAAqB,GAAG;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,kCAAkC;IAClC,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,kCAAkC;IAClC,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,qEAAqE;IACrE,SAAgB,QAAQ,EAAE,MAAM,CAAC;IAEjC,YAAY,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,qBAAqB,EAQ1D;CACF;AAED,KAAK,uBAAuB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,4DAA4D;IAC5D,SAAgB,KAAK,EAAE,OAAO,CAAC;IAE/B,YAAY,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,uBAAuB,EAItD;CACF;AAED,KAAK,2BAA2B,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,0EAA0E;AAC1E,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,uCAAuC;IACvC,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,iCAAiC;IACjC,SAAgB,KAAK,EAAE,OAAO,CAAC;IAE/B,YAAY,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,2BAA2B,EAKvD;CACF"}

package/dist/net/http-client.d.ts

@@ -0,0 +1,45 @@
+import { RetryOptions } from "../util/retry";
+/** Destination addressed by an HTTP query client. */
+export type CreateHttpClientParams = {
+    /**
+     * Target host.
+     */
+    host: string;
+    /**
+     * Target port.
+     */
+    port: number;
+};
+/** Transport and retry settings for an HTTP query client. */
+export type CreateHttpClientOptions = {
+    /**
+     * URL scheme used to reach the server.
+     * @default "http"
+     */
+    protocol?: "http" | "https";
+    /**
+     * Time in milliseconds to wait for a response to a single request attempt.
+     * @default 2000
+     */
+    timeout?: number;
+    /** Retry behavior for each call to `getJson`. Retries are disabled when omitted. */
+    retry?: RetryOptions;
+};
+/** HTTP transport bound to a single query destination. */
+export interface HttpClient {
+    /**
+     * Requests `path` and resolves with its response body parsed as JSON.
+     * @param path Path (including leading `/`) to request, relative to the client's base URL.
+     * @returns The parsed JSON response body.
+     */
+    getJson<T = unknown>(path: string): Promise<T>;
+    /** Destination associated with this client. */
+    readonly ctx: Readonly<CreateHttpClientParams>;
+}
+/**
+ * Creates a reusable HTTP query client for one destination.
+ *
+ * Intended for query protocols that expose their state over plain JSON HTTP endpoints. Each `getJson` call is subject to the configured timeout and, when provided, retried according to `options.retry`.
+ */
+export declare const createHttpClient: ({ host, port }: CreateHttpClientParams, { protocol, timeout, retry }?: CreateHttpClientOptions) => HttpClient;
+//# sourceMappingURL=http-client.d.ts.map

package/dist/net/http-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-client.d.ts","sourceRoot":"","sources":["../../src/net/http-client.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAa,MAAM,eAAe,CAAC;AAGxD,qDAAqD;AACrD,MAAM,MAAM,sBAAsB,GAAG;IACnC;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,6DAA6D;AAC7D,MAAM,MAAM,uBAAuB,GAAG;IACpC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC5B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oFAAoF;IACpF,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB,CAAC;AAEF,0DAA0D;AAC1D,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC/C,+CAA+C;IAC/C,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,sBAAsB,CAAC,CAAC;CAChD;AAID;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,mBACX,sBAAsB,iCACkB,uBAAuB,KAC9E,UAmFF,CAAC"}

package/dist/net/udp-socket.d.ts

@@ -0,0 +1,66 @@
+import { RetryOptions } from "../util/retry";
+/** Destination addressed by a UDP query socket. */
+export type CreateUdpSocketParams = {
+    /**
+     * Target host.
+     */
+    host: string;
+    /**
+     * Target port.
+     */
+    port: number;
+};
+/** Transport and retry settings for a UDP query socket. */
+export type CreateUdpSocketOptions = {
+    /**
+     * Type of socket (udp4 or udp6).
+     * @default "udp4"
+     */
+    type?: "udp4" | "udp6";
+    /**
+     * Time in milliseconds to wait for a response to a single send attempt.
+     * @default 2000
+     */
+    timeout?: number;
+    /** Retry behavior for each call to `send`. Retries are disabled when omitted. */
+    retry?: RetryOptions;
+};
+/** Payload sent by a UDP query. */
+export type UdpSocketSendParams = {
+    /** Payload to send over the UDP socket. */
+    payload: Buffer;
+};
+/** Packet filtering and completion callbacks for a UDP query. */
+export type UdpSocketSendOptions = {
+    /**
+     * Called to determine if a received packet should be accepted.
+     * @param packet The received packet.
+     * @returns `true` if the packet should be accepted, `false` otherwise.
+     */
+    accept?: (packet: Buffer) => boolean;
+    /**
+     * Called after each accepted packet.
+     * Return true once enough packets have arrived.
+     * @default `() => true` (always end after the first accepted packet)
+     */
+    end?: (packets: Buffer[]) => boolean;
+};
+/** UDP transport bound to a single query destination. */
+export interface UdpSocket {
+    /** Sends a payload and resolves with the accepted response packets. */
+    send(params: UdpSocketSendParams, options?: UdpSocketSendOptions): Promise<Buffer[]>;
+    /** Destination associated with this socket. */
+    readonly ctx: Readonly<CreateUdpSocketParams>;
+    /** Closes the underlying UDP socket. */
+    close(): void;
+    /** Closes the underlying UDP socket when leaving a `using` scope. */
+    [Symbol.dispose](): void;
+}
+/**
+ * Creates a reusable UDP query socket for one destination.
+ *
+ * Each `send` call collects accepted packets until its completion callback succeeds. When retry
+ * options are configured, a timed-out or failed send is repeated on the same socket.
+ */
+export declare const createUdpSocket: ({ host, port }: CreateUdpSocketParams, { timeout, type, retry }?: CreateUdpSocketOptions) => UdpSocket;
+//# sourceMappingURL=udp-socket.d.ts.map

package/dist/net/udp-socket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"udp-socket.d.ts","sourceRoot":"","sources":["../../src/net/udp-socket.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAa,MAAM,eAAe,CAAC;AAGxD,mDAAmD;AACnD,MAAM,MAAM,qBAAqB,GAAG;IAClC;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,2DAA2D;AAC3D,MAAM,MAAM,sBAAsB,GAAG;IACnC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB,CAAC;AAEF,mCAAmC;AACnC,MAAM,MAAM,mBAAmB,GAAG;IAChC,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,iEAAiE;AACjE,MAAM,MAAM,oBAAoB,GAAG;IACjC;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;IACrC;;;;OAIG;IACH,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC;CACtC,CAAC;AAEF,yDAAyD;AACzD,MAAM,WAAW,SAAS;IACxB,uEAAuE;IACvE,IAAI,CAAC,MAAM,EAAE,mBAAmB,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACrF,+CAA+C;IAC/C,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,qBAAqB,CAAC,CAAC;IAC9C,wCAAwC;IACxC,KAAK,IAAI,IAAI,CAAC;IACd,qEAAqE;IACrE,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC;CAC1B;AAED;;;;;GAKG;AACH,eAAO,MAAM,eAAe,mBACV,qBAAqB,6BACe,sBAAsB,KACzE,SA0GF,CAAC"}

package/dist/util/retry.d.ts

@@ -0,0 +1,28 @@
+/** Calculates the delay before retrying after a failed, one-based attempt. */
+export type RetryStrategy = (attempt: number) => number;
+/** Exponential retry strategy producing delays of 100 ms, 200 ms, 400 ms, and so on. */
+export declare const backoffStrategy: RetryStrategy;
+/** Controls how an asynchronous operation is retried after failure. */
+export interface RetryOptions {
+    /** Total number of attempts, including the first (non-retry) call. */
+    retries: number;
+    /** ms delay before the next attempt, given the attempt number just completed (1-based). */
+    strategy?: RetryStrategy;
+    /** Return true if this error should stop retrying and be thrown immediately. */
+    fatal?: (err: unknown) => boolean;
+}
+/** Default retry policy: three attempts with exponential backoff. */
+export declare const defaultRetryOptions: Readonly<{
+    retries: 3;
+    strategy: RetryStrategy;
+}>;
+/**
+ * Calls `fn` up to `options.retries` times, retrying on rejection unless
+ * `fatal` says otherwise. Throws the last error when every attempt fails.
+ * @param fn Asynchronous operation to execute.
+ * @param options Attempt count, delay strategy, and fatal-error predicate.
+ * @returns The first successful result.
+ * @throws The fatal error or the final error after all attempts fail.
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, { retries, fatal, strategy }: RetryOptions): Promise<T>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/util/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/util/retry.ts"],"names":[],"mappings":"AAEA,8EAA8E;AAC9E,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;AAExD,wFAAwF;AACxF,eAAO,MAAM,eAAe,EAAE,aAAqD,CAAC;AAEpF,uEAAuE;AACvE,MAAM,WAAW,YAAY;IAC3B,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,2FAA2F;IAC3F,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,gFAAgF;IAChF,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC;CACnC;AAED,qEAAqE;AACrE,eAAO,MAAM,mBAAmB;;;EAGP,CAAC;AAE1B;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,YAAY,GACzC,OAAO,CAAC,CAAC,CAAC,CAmBZ"}

package/dist/util/timing.d.ts

@@ -0,0 +1,5 @@
+/** Resolves after the requested number of milliseconds. */
+export declare const delay: (ms: number) => Promise<unknown>;
+/** Default time in milliseconds to wait for a response to a single request attempt. */
+export declare const defaultTimeout = 2000;
+//# sourceMappingURL=timing.d.ts.map

package/dist/util/timing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timing.d.ts","sourceRoot":"","sources":["../../src/util/timing.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAC3D,eAAO,MAAM,KAAK,OAAQ,MAAM,qBAAsD,CAAC;AAEvF,uFAAuF;AACvF,eAAO,MAAM,cAAc,OAAO,CAAC"}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@srvquery/core",
+  "version": "0.0.1-next.0",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "devDependencies": {
+    "@internal/typescript-config": "0.0.0",
+    "@types/node": "^26.4.1",
+    "rolldown": "^1.2.7",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.0"
+  },
+  "scripts": {
+    "build": "rolldown -c rolldown.config.ts && tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}