dredless 0.7.0 → 1.0.1

package/src/client/core.js

@@ -5,6 +5,7 @@ import {TipDomain} from "./domains/tips.js";
 import {cookieHeader} from "../network/cookies.js";
 import {fetchServers} from "../network/servers.js";
 import {Connection} from "../network/connection.js";
+import {DropReason, DisconnectError, normalizeDisconnect} from "../network/disconnect.js";
 import {itemEquipmentSlotFromId} from "../state/items.js";
 import {WorldStore} from "../state/world/index.js";
 import {buildBlueprintPlacementMessage} from "../protocol/outbound/blueprint.js";
@@ -14,15 +15,22 @@ import {buildSignedCommandPacket} from "../protocol/outbound/commands.js";
 import {buildInventoryDragCommand, normalizeEquipmentSlot, normalizeInventoryEvent} from "../protocol/outbound/inventory.js";
 import {
     buildBanPlayerMessage,
+    buildUnbanPlayerMessage,
     buildDemoteSelfMessage,
     buildInviteResetMessage,
     buildKickPlayerMessage,
     buildPlayerListMessage,
+    buildSaveShipMessage,
+    buildShipRenameRequestMessage,
+    buildShipRenameCommitMessage,
     buildSetPlayerRankMessage,
     buildShipManagementMessage,
     buildShipPrivacyMessage,
+    buildShipGravityMessage,
+    buildSetPatronPerksMessage,
     buildStarterRecoveryMessage,
     normalizeCaptainSubrank,
+    normalizeCrewLog,
     normalizeShipConfig,
     normalizeShipPlayerList
 } from "../protocol/outbound/ship-management.js";
@@ -133,6 +141,7 @@ export class DredlessClient extends EventBus {
         this.ready = false;
         this.packetCount = 0;
         this.lastPacket = null;
+        this.lastDisconnect = null;
         this.packets = [];
         // Retained history is bounded by default: these arrays previously grew for
         // the lifetime of the client, holding every decoded packet and its binary
@@ -161,6 +170,7 @@ export class DredlessClient extends EventBus {
         this.shipConfig = null;
         this.captainSubrank = null;
         this.playerList = null;
+        this.crewLog = null;
         this.outfits = new Map();
         this.commandAcks = new Map();
         this.lastCommandAck = null;
@@ -169,6 +179,9 @@ export class DredlessClient extends EventBus {
             this.#resolveReady = resolve;
             this.#rejectReady = reject;
         });
+        // Consumers may attach only close listeners. Keep the original promise
+        // rejectable through whenReady() without an unhandled rejection on close.
+        this.readyPromise.catch(() => {});
 
         this.attachMode = attachMode;
         this.attached = Boolean(attachMode);
@@ -193,6 +206,10 @@ export class DredlessClient extends EventBus {
     #attachedOpened = false;
     #resolveReady = null;
     #rejectReady = null;
+    #savePending = false;
+    #renamePending = false;
+    #starterRecoveryPending = false;
+    #managementPending = new Set();
     #inputSettings = {
         wrench_mode: 1,
         turret_mode: 0
@@ -242,20 +259,181 @@ export class DredlessClient extends EventBus {
         return this.sendMessage(buildShipManagementMessage(act, arg));
     }
 
+    canSaveShip() {
+        if (!this.connected || !this.ready) return false;
+        const ship = this.worlds.shipWorld();
+        if (!ship || ship.isOverworld !== false || ship.parentWorld == null) return false;
+        const parent = this.worlds.worlds.get(Number(ship.parentWorld));
+        return parent?.meta?.danger_level === 0;
+    }
+
+    async saveShip({timeout = 10000} = {}) {
+        this.#assertWritable();
+        if (!Number.isFinite(timeout) || timeout <= 0 || timeout > 2147483647) {
+            throw new RangeError("timeout must be positive milliseconds no greater than 2147483647");
+        }
+        if (this.#savePending) throw new Error("A ship save is already in progress");
+        if (!this.canSaveShip()) throw new Error("Saving requires a connected, ready client with its ship in a known Safe Zone");
+        this.#savePending = true;
+        try {
+            return await new Promise((resolve, reject) => {
+                const cleanup = () => {
+                    clearTimeout(timer);
+                    this.off("disconnect", disconnected);
+                };
+                const disconnected = (info) => {
+                    cleanup();
+                    if (info.code === DropReason.Saved) resolve(info);
+                    else reject(new DisconnectError(info, "Ship save was not confirmed"));
+                };
+                const timer = setTimeout(() => {
+                    cleanup();
+                    reject(new Error("Timed out waiting for ship save confirmation (Saved close code)"));
+                }, timeout);
+                // Subscribe before sending; attached sockets can close synchronously.
+                this.on("disconnect", disconnected);
+                try {
+                    this.sendMessage(buildSaveShipMessage());
+                } catch (error) {
+                    cleanup();
+                    reject(error);
+                }
+            });
+        } finally {
+            this.#savePending = false;
+        }
+    }
+
+    async renameShip(name, {color, timeout = 10000} = {}) {
+        this.#assertWritable();
+        // Validate before requesting permission. Omitted color comes from the response.
+        buildShipRenameCommitMessage(name, color === undefined ? "#000000" : color);
+        if (!Number.isFinite(timeout) || timeout <= 0 || timeout > 2147483647) {
+            throw new RangeError("timeout must be positive milliseconds no greater than 2147483647");
+        }
+        if (!this.connected || !this.ready) throw new Error("Renaming requires a connected, ready client");
+        if (this.#renamePending) throw new Error("A ship rename is already in progress");
+        const worldId = this.worlds.currentWorldId;
+        this.#renamePending = true;
+        try {
+            await new Promise((resolve, reject) => {
+                const cleanup = () => {
+                    clearTimeout(timer);
+                    this.off("session", responded);
+                    this.off("disconnect", disconnected);
+                    this.off("demote", demoted);
+                };
+                const demoted = () => {
+                    cleanup();
+                    reject(new Error("Ship rename interrupted by demotion"));
+                };
+                const disconnected = (info) => {
+                    cleanup();
+                    reject(new DisconnectError(info, "Ship rename interrupted"));
+                };
+                const responded = (packet) => {
+                    const response = packet.submessage;
+                    if (response?.type !== "rename_response") return;
+                    cleanup();
+                    try {
+                        if (!response.allow) throw new Error(response.message || "Ship rename unavailable");
+                        if (this.worlds.currentWorldId !== worldId) throw new Error("World changed while requesting ship rename");
+                        this.sendMessage(buildShipRenameCommitMessage(name, color === undefined ? response.initial_color : color));
+                        resolve();
+                    } catch (error) {
+                        reject(error);
+                    }
+                };
+                const timer = setTimeout(() => {
+                    cleanup();
+                    reject(new Error("Timed out waiting for ship rename permission"));
+                }, timeout);
+                this.on("session", responded);
+                this.on("disconnect", disconnected);
+                this.on("demote", demoted);
+                try {
+                    this.sendMessage(buildShipRenameRequestMessage());
+                } catch (error) {
+                    cleanup();
+                    reject(error);
+                }
+            });
+        } finally {
+            this.#renamePending = false;
+        }
+    }
+
     requestPlayerList() {
         return this.sendMessage(buildPlayerListMessage());
     }
 
-    resetInvite() {
-        return this.sendMessage(buildInviteResetMessage());
+    resetInvite(options = {}) {
+        const previousKey = this.shipConfig?.inviteKey;
+        return this.#awaitManagementConfirmation("Invite reset", buildInviteResetMessage(), "ship-config", (config) =>
+            typeof config?.inviteKey === "string" && config.inviteKey.length > 0 && config.inviteKey !== previousKey, options);
     }
 
     setShipPrivacy(privacy) {
         return this.sendMessage(buildShipPrivacyMessage(privacy));
     }
 
-    recoverStarterItem(itemId) {
-        return this.sendMessage(buildStarterRecoveryMessage(itemId));
+    setShipGravity(direction) {
+        return this.sendMessage(buildShipGravityMessage(direction));
+    }
+
+    setShipPatronPerks(enabled) {
+        return this.sendMessage(buildSetPatronPerksMessage(enabled));
+    }
+
+    async recoverStarterItem(itemId, {timeout = 10000} = {}) {
+        this.#assertWritable();
+        const message = buildStarterRecoveryMessage(itemId);
+        if (!Number.isFinite(timeout) || timeout <= 0 || timeout > 2147483647) {
+            throw new RangeError("timeout must be positive milliseconds no greater than 2147483647");
+        }
+        if (!this.connected || !this.ready) throw new Error("Starter recovery requires a connected, ready client");
+        if (this.#starterRecoveryPending) throw new Error("A starter recovery is already in progress");
+        const worldId = this.worlds.currentWorldId;
+        this.#starterRecoveryPending = true;
+        try {
+            await new Promise((resolve, reject) => {
+                const cleanup = () => {
+                    clearTimeout(timer);
+                    this.off("starter-recovery", responded);
+                    this.off("disconnect", disconnected);
+                    this.off("demote", demoted);
+                };
+                const disconnected = (info) => {
+                    cleanup();
+                    reject(new DisconnectError(info, "Starter recovery interrupted"));
+                };
+                const demoted = () => {
+                    cleanup();
+                    reject(new Error("Starter recovery interrupted by demotion"));
+                };
+                const responded = (result) => {
+                    cleanup();
+                    if (this.worlds.currentWorldId !== worldId) reject(new Error("World changed during starter recovery"));
+                    else if (!result.success) reject(new Error(result.failReason));
+                    else resolve();
+                };
+                const timer = setTimeout(() => {
+                    cleanup();
+                    reject(new Error("Timed out waiting for starter recovery response"));
+                }, timeout);
+                this.on("starter-recovery", responded);
+                this.on("disconnect", disconnected);
+                this.on("demote", demoted);
+                try {
+                    this.sendMessage(message);
+                } catch (error) {
+                    cleanup();
+                    reject(error);
+                }
+            });
+        } finally {
+            this.#starterRecoveryPending = false;
+        }
     }
 
     setPlayerRank(refId, rank) {
@@ -282,8 +460,58 @@ export class DredlessClient extends EventBus {
         return this.sendMessage(buildBanPlayerMessage(refId));
     }
 
-    demoteSelf() {
-        return this.sendMessage(buildDemoteSelfMessage());
+    unbanPlayer(refId) {
+        return this.sendMessage(buildUnbanPlayerMessage(refId));
+    }
+
+    async demoteSelf(options = {}) {
+        await this.#awaitManagementConfirmation("Self-demotion", buildDemoteSelfMessage(), "demote", () => true, options);
+    }
+
+    async #awaitManagementConfirmation(operation, message, event, accept, {timeout = 10000} = {}) {
+        this.#assertWritable();
+        if (!Number.isFinite(timeout) || timeout <= 0 || timeout > 2147483647) {
+            throw new RangeError("timeout must be positive milliseconds no greater than 2147483647");
+        }
+        if (!this.connected || !this.ready) throw new Error(`${operation} requires a connected, ready client`);
+        if (this.#managementPending.has(operation)) throw new Error(`${operation} is already in progress`);
+        const worldId = this.worlds.currentWorldId;
+        this.#managementPending.add(operation);
+        try {
+            return await new Promise((resolve, reject) => {
+                const cleanup = () => {
+                    clearTimeout(timer);
+                    this.off(event, responded);
+                    this.off("disconnect", disconnected);
+                    if (event !== "demote") this.off("demote", demoted);
+                };
+                const fail = (error) => {
+                    cleanup();
+                    reject(error);
+                };
+                const disconnected = (info) => fail(new DisconnectError(info, `${operation} interrupted`));
+                const demoted = () => fail(new Error(`${operation} interrupted by demotion`));
+                const responded = (result) => {
+                    if (this.worlds.currentWorldId !== worldId) {
+                        fail(new Error(`World changed during ${operation.toLowerCase()}`));
+                    } else if (accept(result)) {
+                        cleanup();
+                        resolve(result);
+                    }
+                };
+                const timer = setTimeout(() => fail(new Error(`Timed out waiting for ${operation.toLowerCase()} confirmation`)), timeout);
+                this.on(event, responded);
+                this.on("disconnect", disconnected);
+                if (event !== "demote") this.on("demote", demoted);
+                try {
+                    this.sendMessage(message);
+                } catch (error) {
+                    fail(error);
+                }
+            });
+        } finally {
+            this.#managementPending.delete(operation);
+        }
     }
 
     sendEntityCommand(cmd, args = [-1, -1, -1]) {
@@ -663,12 +891,14 @@ export class DredlessClient extends EventBus {
             shipConfig: this.shipConfig,
             captainSubrank: this.captainSubrank,
             playerList: this.playerList,
+            crewLog: this.crewLog,
             outfits: [...this.outfits.entries()].map(([sid, outfit]) => ({sid, outfit})),
             commandAcks: [...this.commandAcks.entries()].map(([world, commandNumber]) => ({world, commandNumber})),
             lastCommandAck: this.lastCommandAck,
             decodeErrors: this.decodeErrors.slice(-50),
             packetCount: this.packetCount,
-            lastPacket: this.lastPacket
+            lastPacket: this.lastPacket,
+            lastDisconnect: this.lastDisconnect
         };
     }
 
@@ -819,6 +1049,7 @@ export class DredlessClient extends EventBus {
             }
             this.#resolveReady?.(this);
             this.#resolveReady = null;
+            this.#rejectReady = null;
         }
         this.#bindAttachedSocket();
         if (this.connected && this.#ownsSocket) this.#attachedOpen();
@@ -827,6 +1058,7 @@ export class DredlessClient extends EventBus {
 
     #bindSocket() {
         this.ws.onopen = () => {
+            this.lastDisconnect = null;
             this.connected = true;
             this.ws.send(encodeMsgpack({type: 1}));
             this.emit("open", this);
@@ -842,7 +1074,7 @@ export class DredlessClient extends EventBus {
         const open = () => this.#attachedOpen();
         const message = (event) => this.#handleSocketMessage(event?.data ?? event);
         const error = (event) => this.#fail(event?.error || new Error("WebSocket error"));
-        const close = (event) => this.#handleSocketClose(event);
+        const close = (event, reason) => this.#handleSocketClose(event, reason);
 
         if (typeof this.ws.addEventListener === "function") {
             this.ws.addEventListener("open", open);
@@ -858,14 +1090,17 @@ export class DredlessClient extends EventBus {
             this.ws.on("close", close);
             return;
         }
-        const previousMessage = this.ws.onmessage;
-        this.ws.onmessage = (event) => {
-            if (typeof previousMessage === "function") previousMessage.call(this.ws, event);
-            message(event);
-        };
+        for (const [type, handler] of Object.entries({open, message, error, close})) {
+            const previous = this.ws[`on${type}`];
+            this.ws[`on${type}`] = (...args) => {
+                if (typeof previous === "function") previous.apply(this.ws, args);
+                handler(...args);
+            };
+        }
     }
 
     #attachedOpen() {
+        this.lastDisconnect = null;
         this.connected = true;
         if (this.#attachedOpened) return;
         this.#attachedOpened = true;
@@ -874,11 +1109,32 @@ export class DredlessClient extends EventBus {
         if (this.#allowWrites) this.#flushMessages();
     }
 
-    #handleSocketClose(event) {
+    #handleSocketClose(event, reason) {
+        const info = normalizeDisconnect(event, reason);
         this.connected = false;
+        this.ready = false;
+        this.sid = null;
+        this.lastDisconnect = info;
         clearInterval(this.#keepalive);
         this.#keepalive = null;
-        this.emit("close", event);
+        this.#bootstrapped = false;
+        this.#attachedOpened = false;
+        this.#queuedCommands.length = 0;
+        this.#queuedMessages.length = 0;
+        this.shipConfig = null;
+        this.captainSubrank = null;
+        this.playerList = null;
+        this.crewLog = null;
+        this.puiPanels.clear();
+        this.commsPanels.clear();
+        this.currentCommsPanel = null;
+        this.commandAcks.clear();
+        this.lastCommandAck = null;
+        this.#rejectReady?.(new DisconnectError(info, "Disconnected before the client was ready"));
+        this.#resolveReady = null;
+        this.#rejectReady = null;
+        this.emit("disconnect", info);
+        this.emit("close", event, reason);
     }
 
     #socketLooksOpen(websocket) {
@@ -887,6 +1143,7 @@ export class DredlessClient extends EventBus {
 
     #assertWritable() {
         if (!this.#allowWrites) throw new Error("DredlessClient is attached in readonly mode");
+        if (this.lastDisconnect) throw new DisconnectError(this.lastDisconnect);
     }
 
     #handleSocketMessage(data) {
@@ -900,6 +1157,7 @@ export class DredlessClient extends EventBus {
     }
 
     #handleMessage(data) {
+        if (this.lastDisconnect) return;
         let packet;
         try {
             packet = decodeIncomingFrame(data);
@@ -928,6 +1186,7 @@ export class DredlessClient extends EventBus {
 
     #markReady(packet) {
         this.sid = packet.sid >>> 0;
+        this.worlds.apply(packet);
         this.worlds.currentWorldId = packet.world ?? this.worlds.currentWorldId;
         this.ready = true;
         if (this.#ownsSocket) {
@@ -940,6 +1199,7 @@ export class DredlessClient extends EventBus {
         }
         this.#resolveReady?.(this);
         this.#resolveReady = null;
+        this.#rejectReady = null;
         this.emit("ready", this);
     }
 
@@ -1025,6 +1285,33 @@ export class DredlessClient extends EventBus {
     #handleSessionSubmessage(packet) {
         const submessage = packet?.submessage;
         if (!submessage || typeof submessage !== "object") return;
+        if (submessage.type === "demote") {
+            // Permission-scoped state must not survive losing captain access.
+            this.shipConfig = null;
+            this.captainSubrank = null;
+            this.playerList = null;
+            this.crewLog = null;
+            this.emit("demote", packet);
+            this.emit("ship-config", null, packet);
+            this.emit("captain-subrank", null, packet);
+            this.emit("player-list", null, packet);
+            this.emit("crew-log", null, packet);
+            return;
+        }
+        if (submessage.type === "log") {
+            this.crewLog = normalizeCrewLog(submessage, this.crewLog);
+            this.emit("crew-log", this.crewLog, packet);
+            return;
+        }
+        if (submessage.type === "starter_recovery_response") {
+            const failReason = submessage.fail_reason == null ? null : String(submessage.fail_reason);
+            this.emit("starter-recovery", Object.freeze({success: failReason === null, failReason}), packet);
+            return;
+        }
+        if (submessage.type === "perk_response") {
+            this.emit("patron-perks-response", Object.freeze({failure: Boolean(submessage.failure)}), packet);
+            return;
+        }
         if (submessage.type === "config") {
             this.shipConfig = normalizeShipConfig(submessage);
             this.emit("ship-config", this.shipConfig, packet);

package/src/client/domains/index.js

@@ -32,6 +32,10 @@ export class ClientNetDomain {
         return this.client.lastPacket;
     }
 
+    get lastDisconnect() {
+        return this.client.lastDisconnect;
+    }
+
     send(command = {}) {
         return this.client.send(command);
     }
@@ -191,20 +195,58 @@ export class ShipManagementDomain {
         this.client = client;
     }
 
+    canSave() {
+        return this.client.canSaveShip();
+    }
+
+    save(options = {}) {
+        return this.client.saveShip(options);
+    }
+
+    rename(name, options = {}) {
+        return this.client.renameShip(name, options);
+    }
+
     requestPlayerList() {
         return this.client.requestPlayerList();
     }
 
-    resetInvite() {
-        return this.client.resetInvite();
+    resetInvite(options = {}) {
+        return this.client.resetInvite(options);
     }
 
     setPrivacy(privacy) {
         return this.client.setShipPrivacy(privacy);
     }
 
-    recoverStarterItem(itemId) {
-        return this.client.recoverStarterItem(itemId);
+    setGravity(direction) {
+        return this.client.setShipGravity(direction);
+    }
+
+    setPatronPerks(enabled) {
+        return this.client.setShipPatronPerks(enabled);
+    }
+
+    enablePatronPerks() {
+        return this.setPatronPerks(true);
+    }
+
+    disablePatronPerks() {
+        return this.setPatronPerks(false);
+    }
+
+    patronPerks() {
+        return this.client.shipConfig?.patronPerks ?? null;
+    }
+
+    hasPatronPerks(name) {
+        if (name !== undefined && typeof name !== "string") throw new TypeError("name must be a string");
+        const perks = this.patronPerks();
+        return name === undefined ? Boolean(perks?.length) : Boolean(perks?.some((perk) => perk.name === name));
+    }
+
+    recoverStarterItem(itemId, options = {}) {
+        return this.client.recoverStarterItem(itemId, options);
     }
 
     setPlayerRank(refId, rank) {
@@ -219,8 +261,12 @@ export class ShipManagementDomain {
         return this.client.banPlayer(refId);
     }
 
-    demoteSelf() {
-        return this.client.demoteSelf();
+    unbanPlayer(refId) {
+        return this.client.unbanPlayer(refId);
+    }
+
+    demoteSelf(options = {}) {
+        return this.client.demoteSelf(options);
     }
 
     config() {
@@ -234,6 +280,10 @@ export class ShipManagementDomain {
     playerList() {
         return this.client.playerList;
     }
+
+    crewLog() {
+        return this.client.crewLog;
+    }
 }
 
 export class InventoryDomain {
@@ -1602,7 +1652,7 @@ export function currentPlayerSummary(client, scope = "current") {
     const players = worldStateFor(client, scope)?.model.players() || [];
     // `sid` is the websocket session id, not the ECS entity id used by the
     // player component. The local-player flag identifies the ECS entity.
-    return players.find((player) => player.state?.q109) || null;
+    return players.find((player) => player.isLocal) || null;
 }
 
 function currentPlayerRank(client) {

package/src/client/index.d.ts

@@ -1,2 +1,2 @@
 export {DredlessClient, WrenchMode, TurretMode} from "../index.js";
-export type {DredlessClientOptions, ClientSnapshot, TipDomain, TipList, TipOptions} from "../index.js";
+export type {DredlessClientOptions, ClientSnapshot, TipDomain, TipList, TipOptions, RenameShipOptions, ShipManagementOptions, StarterRecoveryOptions, StarterRecoveryResult, CrewLog, CrewLogEntry, ShipGravityDirection, ShipPatronPerk, PatronPerksResponse} from "../index.js";