@james-pre/mc-admin 0.1.0

package/dist/common/rcon.d.ts

@@ -0,0 +1,58 @@
+export declare const enum PacketType {
+    /** A command's output. */
+    Value = 0,
+    /** Run a command. */
+    Command = 2,
+    /** Whether a login was accepted. */
+    AuthResponse = 2,
+    /** Log in. */
+    AuthRequest = 3
+}
+export interface Packet {
+    id: number;
+    type: PacketType;
+    body: string;
+}
+/** A request, ready to hand to a transport. */
+export declare function encode(id: number, type: PacketType, body: string): Uint8Array<ArrayBuffer>;
+export interface ConnectionOptions {
+    /**
+     * If set, resolve a command as soon as the first response packet is received rather than collecting the whole response.
+     */
+    shortCommandOutput?: boolean;
+}
+/** A command waiting on the server. */
+interface Pending extends PromiseWithResolvers<string> {
+    id: number;
+    received: string[];
+    endId: number | null;
+}
+/** A client RCON session */
+export declare class Connection {
+    protected readonly options: ConnectionOptions;
+    protected readonly pending: Map<number, Pending>;
+    protected auth: PromiseWithResolvers<void> | null;
+    protected nextId: number;
+    protected readonly writer: WritableStreamDefaultWriter<Uint8Array>;
+    /** Settles when the server's half of the stream ends */
+    readonly closed: Promise<void>;
+    /**
+     * @param stream The transport. Use Node.js `Socket`'s with `Duplex.toWeb`.
+     */
+    constructor(stream: ReadableWritablePair<Uint8Array, Uint8Array>, options?: ConnectionOptions);
+    /** Pull packets until the server stops sending them. */
+    protected read(readable: ReadableStream<Uint8Array>): Promise<void>;
+    protected buffer: Uint8Array<ArrayBuffer>;
+    /** Every whole packet the bytes received so far complete. */
+    protected push(chunk: Uint8Array): Generator<Packet>;
+    protected accept(packet: Packet): void;
+    /** Log in. Replies are treated as auth results until this settles. */
+    authenticate(password: string): Promise<void>;
+    /** Run a command and wait for its output. */
+    command(text: string): Promise<string>;
+    /** Close this end of the stream, leaving whatever owns the transport to tear it down. */
+    close(): Promise<void>;
+    /** Fail everything still in flight, e.g. once the socket closes. */
+    abort(reason: Error): void;
+}
+export {};

package/dist/common/rcon.js

@@ -0,0 +1,154 @@
+import { decodeUTF8, encodeUTF8 } from 'utilium';
+/* eslint-disable @typescript-eslint/no-duplicate-enum-values */
+export var PacketType;
+(function (PacketType) {
+    /** A command's output. */
+    PacketType[PacketType["Value"] = 0] = "Value";
+    /** Run a command. */
+    PacketType[PacketType["Command"] = 2] = "Command";
+    /** Whether a login was accepted. */
+    PacketType[PacketType["AuthResponse"] = 2] = "AuthResponse";
+    /** Log in. */
+    PacketType[PacketType["AuthRequest"] = 3] = "AuthRequest";
+})(PacketType || (PacketType = {}));
+/** Every packet opens with three `int32`s and ends with two nulls terminating the body. */
+const headerSize = 12;
+/** `length` counts everything after itself, never its own four bytes. */
+const lengthSize = 4;
+/** What `length` covers besides the body: `id`, `type`, and the two nulls. */
+const overhead = 10;
+/** A request, ready to hand to a transport. */
+export function encode(id, type, body) {
+    const bytes = encodeUTF8(body);
+    const packet = new Uint8Array(headerSize + bytes.byteLength + 2);
+    const view = new DataView(packet.buffer);
+    view.setInt32(0, overhead + bytes.byteLength, true);
+    view.setInt32(lengthSize, id, true);
+    view.setInt32(lengthSize + 4, type, true);
+    packet.set(bytes, headerSize);
+    return packet;
+}
+/** A client RCON session */
+export class Connection {
+    options;
+    pending = new Map();
+    auth = null;
+    nextId = 1;
+    writer;
+    /** Settles when the server's half of the stream ends */
+    closed;
+    /**
+     * @param stream The transport. Use Node.js `Socket`'s with `Duplex.toWeb`.
+     */
+    constructor(stream, options = {}) {
+        this.options = options;
+        this.writer = stream.writable.getWriter();
+        this.closed = this.read(stream.readable);
+        // Keep a lone failure from surfacing as an unhandled rejection; callers still see it.
+        this.closed.catch(() => { });
+    }
+    /** Pull packets until the server stops sending them. */
+    async read(readable) {
+        const reader = readable.getReader();
+        try {
+            for (let next = await reader.read(); !next.done; next = await reader.read())
+                for (const packet of this.push(next.value))
+                    this.accept(packet);
+        }
+        catch (error) {
+            this.abort(error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+        this.abort(new Error('the connection closed'));
+    }
+    buffer = new Uint8Array(0);
+    /** Every whole packet the bytes received so far complete. */
+    *push(chunk) {
+        const grown = new Uint8Array(this.buffer.byteLength + chunk.byteLength);
+        grown.set(this.buffer);
+        grown.set(chunk, this.buffer.byteLength);
+        this.buffer = grown;
+        // Every packet is at least `headerSize + 2` bytes long.
+        // Waiting for a whole header before reading `length` can't stall a packet that has fully arrived.
+        while (this.buffer.byteLength >= headerSize) {
+            const view = new DataView(this.buffer.buffer, this.buffer.byteOffset, this.buffer.byteLength);
+            const length = view.getInt32(0, true);
+            if (length < overhead)
+                throw new Error(`RCON packet claims an impossible length (${length})`);
+            const end = lengthSize + length;
+            if (this.buffer.byteLength < end)
+                return;
+            yield {
+                id: view.getInt32(lengthSize, true),
+                type: view.getInt32(lengthSize + 4, true),
+                body: decodeUTF8(this.buffer.subarray(headerSize, end - 2)),
+            };
+            this.buffer = this.buffer.subarray(end);
+        }
+    }
+    accept(packet) {
+        if (this.auth) {
+            if (packet.type !== PacketType.AuthResponse)
+                return;
+            const auth = this.auth;
+            this.auth = null;
+            if (packet.id === -1)
+                auth.reject(new Error('authentication failed (bad password)'));
+            else
+                auth.resolve();
+            return;
+        }
+        const pending = this.pending.get(packet.id);
+        if (!pending)
+            return;
+        if (pending.endId === null) {
+            this.pending.delete(pending.id);
+            pending.resolve(packet.body);
+            return;
+        }
+        if (packet.id !== pending.endId) {
+            pending.received.push(packet.body);
+            return;
+        }
+        this.pending.delete(pending.id);
+        this.pending.delete(pending.endId);
+        pending.resolve(pending.received.join(''));
+    }
+    /** Log in. Replies are treated as auth results until this settles. */
+    async authenticate(password) {
+        if (this.auth)
+            throw new Error('already authenticating');
+        const auth = Promise.withResolvers();
+        this.auth = auth;
+        await this.writer.write(encode(this.nextId++, PacketType.AuthRequest, password));
+        await auth.promise;
+    }
+    /** Run a command and wait for its output. */
+    async command(text) {
+        const id = this.nextId++;
+        const pending = { ...Promise.withResolvers(), id, received: [], endId: null };
+        this.pending.set(id, pending);
+        if (!this.options.shortCommandOutput) {
+            pending.endId = this.nextId++;
+            this.pending.set(pending.endId, pending);
+        }
+        await this.writer.write(encode(id, PacketType.Command, text));
+        if (pending.endId !== null)
+            await this.writer.write(encode(pending.endId, PacketType.Command, ''));
+        const result = await pending.promise;
+        return result.trimEnd();
+    }
+    /** Close this end of the stream, leaving whatever owns the transport to tear it down. */
+    async close() {
+        await this.writer.close();
+    }
+    /** Fail everything still in flight, e.g. once the socket closes. */
+    abort(reason) {
+        const auth = this.auth;
+        this.auth = null;
+        auth?.reject(reason);
+        for (const pending of this.pending.values())
+            pending.reject(reason);
+        this.pending.clear();
+    }
+}

package/dist/common/region.d.ts

@@ -0,0 +1,52 @@
+import * as chunk from './chunk.js';
+import type { RegionFile } from './level.js';
+/** Region files are addressed in 4 KiB sectors. */
+export declare const sectorSize = 4096;
+/** Chunks per region, per axis. */
+export declare const regionSize = 32;
+/** Chunks per region. */
+export declare const chunkCount: number;
+/** The region coordinates a file name encodes, or null if it isn't a region file. */
+export declare function parseName(name: string): {
+    x: number;
+    z: number;
+} | null;
+export declare class Region {
+    readonly file?: RegionFile | undefined;
+    readonly data: Uint8Array<ArrayBuffer>;
+    protected readonly view: DataView;
+    constructor(data: BufferSource, file?: RegionFile | undefined);
+    /**
+     * Whether the file is too short to hold the header.
+     *
+     * The server creates region files before it has anything to put in them, so a zero-length or
+     * truncated file is normal rather than damage.
+     */
+    get empty(): boolean;
+    /** Where chunk `index` lives, or null when the region has never stored it. */
+    entry(index: number): chunk.Entry | null;
+    /** Where the chunk at region-local coordinates lives, or null when the region lacks it. */
+    at(x: number, z: number): chunk.Entry | null;
+    /** Every chunk the region actually stores. */
+    entries(): Generator<chunk.Entry>;
+    /**
+     * A chunk's record, still compressed.
+     *
+     * @throws When the header points outside the file, which means the region is truncated.
+     */
+    raw(entry: chunk.Entry): chunk.Raw;
+    /** A chunk's NBT. */
+    chunk(entry: chunk.Entry): Promise<chunk.Parsed>;
+    /**
+     * Every chunk's NBT.
+     *
+     * A single bad chunk ends the iteration, since there is no way to report it otherwise. To
+     * survive damaged regions, walk {@link entries} and call {@link chunk} inside a try/catch.
+     */
+    chunksUnsafe(): AsyncGenerator<chunk.Parsed>;
+    /**
+     * Every chunk's NBT.
+     */
+    chunks(onError?: (error: Error, entry: chunk.Entry) => void): AsyncGenerator<chunk.Parsed>;
+    filterChunks(predicate: (chunk: chunk.Parsed) => boolean): Promise<chunk.Parsed[]>;
+}

package/dist/common/region.js

@@ -0,0 +1,128 @@
+import { toBytes } from './buffers.js';
+import * as chunk from './chunk.js';
+import { parse } from './nbt.js';
+/** Region files are addressed in 4 KiB sectors. */
+export const sectorSize = 4096;
+/** Chunks per region, per axis. */
+export const regionSize = 32;
+/** Chunks per region. */
+export const chunkCount = regionSize * regionSize;
+const namePattern = /^r\.(-?\d+)\.(-?\d+)\.mca$/;
+/** The region coordinates a file name encodes, or null if it isn't a region file. */
+export function parseName(name) {
+    const match = namePattern.exec(name);
+    return match ? { x: Number(match[1]), z: Number(match[2]) } : null;
+}
+export class Region {
+    file;
+    data;
+    view;
+    constructor(data, file) {
+        this.file = file;
+        this.data = toBytes(data);
+        this.view = new DataView(this.data.buffer, this.data.byteOffset, this.data.byteLength);
+    }
+    /**
+     * Whether the file is too short to hold the header.
+     *
+     * The server creates region files before it has anything to put in them, so a zero-length or
+     * truncated file is normal rather than damage.
+     */
+    get empty() {
+        return this.data.byteLength < sectorSize * 2;
+    }
+    /** Where chunk `index` lives, or null when the region has never stored it. */
+    entry(index) {
+        if (index < 0 || index >= chunkCount)
+            throw new RangeError(`chunk index ${index} is outside the region`);
+        if (this.empty)
+            return null;
+        // A location packs a 3-byte sector offset with a 1-byte sector count.
+        const location = this.view.getUint32(index * 4);
+        if (location === 0)
+            return null;
+        return {
+            index,
+            x: index % regionSize,
+            z: Math.floor(index / regionSize),
+            offset: (location >>> 8) * sectorSize,
+            sectors: location & 0xff,
+            timestamp: this.view.getInt32(sectorSize + index * 4),
+        };
+    }
+    /** Where the chunk at region-local coordinates lives, or null when the region lacks it. */
+    at(x, z) {
+        return this.entry(x + z * regionSize);
+    }
+    /** Every chunk the region actually stores. */
+    *entries() {
+        for (let index = 0; index < chunkCount; index++) {
+            const entry = this.entry(index);
+            if (entry)
+                yield entry;
+        }
+    }
+    /**
+     * A chunk's record, still compressed.
+     *
+     * @throws When the header points outside the file, which means the region is truncated.
+     */
+    raw(entry) {
+        const { offset } = entry;
+        if (offset + 5 > this.data.byteLength)
+            throw new RangeError(`chunk ${entry.x},${entry.z} starts past the end of the region`);
+        // The stored length counts the compression byte that follows it.
+        const end = offset + 4 + this.view.getUint32(offset);
+        if (end > this.data.byteLength)
+            throw new RangeError(`chunk ${entry.x},${entry.z} runs past the end of the region`);
+        const flags = this.view.getUint8(offset + 4);
+        return {
+            ...entry,
+            compression: flags & ~chunk.externalFlag,
+            external: (flags & chunk.externalFlag) !== 0,
+            data: this.data.subarray(offset + 5, end),
+        };
+    }
+    /** A chunk's NBT. */
+    async chunk(entry) {
+        const raw = this.raw(entry);
+        return { ...raw, tag: parse(await chunk.payload(raw)).tag };
+    }
+    /**
+     * Every chunk's NBT.
+     *
+     * A single bad chunk ends the iteration, since there is no way to report it otherwise. To
+     * survive damaged regions, walk {@link entries} and call {@link chunk} inside a try/catch.
+     */
+    async *chunksUnsafe() {
+        for (const entry of this.entries())
+            yield await this.chunk(entry);
+    }
+    /**
+     * Every chunk's NBT.
+     */
+    async *chunks(onError) {
+        for (const entry of this.entries()) {
+            try {
+                yield await this.chunk(entry);
+            }
+            catch (e) {
+                onError?.(e, entry);
+            }
+        }
+    }
+    async filterChunks(predicate) {
+        const chunks = [];
+        for (const entry of this.entries()) {
+            try {
+                const chunk = await this.chunk(entry);
+                if (predicate(chunk))
+                    chunks.push(chunk);
+            }
+            catch {
+                // Ignore chunks that can't be read
+            }
+        }
+        return chunks;
+    }
+}

package/dist/common/snbt.d.ts

@@ -0,0 +1,98 @@
+import type { Tag } from './nbt.js';
+import { TagType } from './nbt.js';
+export interface ParseOptions {
+    /**
+     * Accept unquoted words as string values, e.g. `{id:stone}`.
+     *
+     * Off by default, because {@link scan} relies on the strictness: without it, Brigadier's
+     * parse-error pointer `<--[HERE]` reads as a one-element list of the string `HERE` and gets
+     * treated like data. Minecraft always quotes the strings it prints, so nothing is lost.
+     */
+    bareStrings?: boolean;
+}
+export declare class SnbtError extends SyntaxError {
+    /** Index into the source where parsing gave up. */
+    readonly position: number;
+    constructor(message: string, 
+    /** Index into the source where parsing gave up. */
+    position: number);
+}
+/** @internal */
+export declare const escapes: Record<string, string>;
+/** @internal */
+export declare const suffixTags: Record<string, TagType>;
+/** The letter printed after a number of each type. Ints get nothing. */
+export declare const tagSuffixes: {
+    1: string;
+    2: string;
+    4: string;
+    5: string;
+    6: string;
+};
+/** The marker a typed array leads with, and the suffix its items carry. */
+export declare const arrayMarkers: {
+    7: string[];
+    11: string[];
+    12: string[];
+};
+/** @internal */
+export declare class Parser {
+    protected readonly source: string;
+    offset: number;
+    protected readonly bareStrings: boolean;
+    constructor(source: string, options?: ParseOptions);
+    protected error(message: string, position?: number): never;
+    protected get current(): string;
+    protected skipSpace(): void;
+    protected take(literal: string): boolean;
+    protected expect(literal: string): void;
+    protected match(pattern: RegExp): RegExpExecArray | null;
+    /** True when the character after a `length`-long match would continue the word. */
+    protected continues(length: number): boolean;
+    /** The character(s) a backslash stands for. */
+    protected escape(): string;
+    /** A quoted string, or null when the cursor isn't on a quote. */
+    protected quoted(): string | null;
+    /** A compound key: quoted, or a bare word. */
+    protected key(): string;
+    /** A number with its optional type suffix, or null when the cursor isn't on one. */
+    protected number(): Tag | null;
+    /** `true` and `false` are how the game prints bytes it knows are flags. */
+    protected boolean(): Tag | null;
+    /** An unsuffixed number is an int, or a double once it has a fraction or an exponent. */
+    protected numeric(digits: string, suffix: string, position: number): Tag;
+    /** Integer types reject a fractional or exponential literal, e.g. `1.5b`. */
+    protected whole(digits: string, position: number): number;
+    /** The integer an array item carries, whatever suffix it was written with. */
+    protected arrayItem(tag: Tag, position: number): bigint;
+    protected compound(): Tag;
+    /** A list, or one of the typed arrays that lead with their element type: `[I; 1, 2]`. */
+    protected list(): Tag;
+    /** The body of `[B;…]`, `[I;…]` or `[L;…]`, whose marker has already been consumed. */
+    protected array(marker: string): Tag;
+    value(): Tag;
+    /** One value and nothing else, ignoring the whitespace around it. */
+    document(): Tag;
+}
+/**
+ * Parse a whole SNBT document.
+ *
+ * @throws SnbtError when the source isn't well-formed SNBT.
+ */
+export declare function parse(source: string, options?: ParseOptions): Tag;
+export interface Span {
+    /** Index of the value's first character. */
+    start: number;
+    /** Index just past its last character. */
+    end: number;
+    tag: Tag;
+}
+/**
+ * Parse the value starting at `start`, returning it with the index just past it, or null when
+ * what's there isn't well-formed SNBT. Unlike {@link parse}, trailing text is fine.
+ */
+export declare function parseAt(source: string, start?: number, options?: ParseOptions): Span | null;
+/**
+ * Find the SNBT embedded in prose.
+ */
+export declare function scan(text: string): Generator<Span>;