doover-js 0.9.1 → 0.10.1

package/dist/gateway/gateway-client.js

@@ -5,6 +5,40 @@ const errors_1 = require("../http/errors");
 const snowflake_1 = require("../utils/snowflake");
 const RECONNECT_BASE_MS = 1000;
 const RECONNECT_CAP_MS = 30000;
+/** Schemes a WebSocket can be opened on — it maps http(s) to ws(s) itself. */
+const ALLOWED_WSS_PROTOCOLS = new Set(["ws:", "wss:", "http:", "https:"]);
+/**
+ * Reject a `dataWssUrl` that cannot address a gateway.
+ *
+ * An empty or relative value is the dangerous case, because nothing rejects it
+ * on its own: the WebSocket constructor resolves a relative URL against the
+ * document and maps https to wss, so in a browser `new WebSocket("")` silently
+ * points the gateway at whatever page is open. That page answers the upgrade
+ * with its own HTML and a 200, the browser reports "the server did not accept
+ * the WebSocket handshake", and the client retries against it forever — a loop
+ * that looks like a server problem and never names the real cause. It reached
+ * a kiosk panel that way, from a client built with `dataWssUrl: ""` because the
+ * build it was bundled into defined no env for it.
+ *
+ * Absolute http(s) is allowed as well as ws(s), since the WebSocket
+ * constructor maps those itself and existing configs rely on it.
+ */
+function assertAbsoluteWssUrl(url) {
+    if (typeof url !== "string" || url.trim() === "") {
+        throw new Error("dataWssUrl is empty, so a gateway connection would resolve against the " +
+            "current page rather than a gateway; set it to an absolute ws(s):// URL");
+    }
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`dataWssUrl must be an absolute ws(s):// URL, not the relative value ${JSON.stringify(url)}`);
+    }
+    if (!ALLOWED_WSS_PROTOCOLS.has(parsed.protocol)) {
+        throw new Error(`dataWssUrl must be ws(s):// or http(s)://, not ${parsed.protocol}//`);
+    }
+}
 class GatewayClient {
     constructor(config, auth) {
         this.config = config;
@@ -90,6 +124,10 @@ class GatewayClient {
         }
     }
     async openSocket() {
+        // Before auth, before any socket: a URL that cannot address a gateway is a
+        // configuration fault, and finding out now costs one error instead of an
+        // endless handshake failure that reads like a broken server.
+        assertAbsoluteWssUrl(this.config.dataWssUrl);
         if (this.auth) {
             await this.auth.ensureReady();
         }

package/dist/react/useSendRpc.d.ts

@@ -32,6 +32,13 @@ export interface UseSendRpcOptions {
      * `["doover", "agent", agentId, "channel", channelName, "rpc", method]`.
      */
     mutationKey?: readonly unknown[];
+    /** How long to wait to hear from the device at all. See `SendRpcOptions`. */
+    timeoutMs?: number;
+    /**
+     * How long the command may then stay in flight once the device has answered,
+     * re-armed on every progress report. See `SendRpcOptions`.
+     */
+    pendingTimeoutMs?: number;
 }
 export interface UseSendRpcResult<TRequest, TResponse, TPending> extends Omit<UseMutationResult<TResponse, unknown, SendRpcVariables<TRequest>, void>, "isPending" | "mutate" | "mutateAsync"> {
     /** Most recent status across all commands (by `submittedAt`). */

package/dist/react/useSendRpc.js

@@ -120,6 +120,12 @@ function useSendRpc(identifier, options) {
             }
             return client.rpc.send({ agentId: identifier.agentId, channelName: identifier.channelName }, rpcRequest, {
                 onStatus: (status) => appendStatus(commandId, status),
+                ...(options.timeoutMs !== undefined
+                    ? { timeoutMs: options.timeoutMs }
+                    : {}),
+                ...(options.pendingTimeoutMs !== undefined
+                    ? { pendingTimeoutMs: options.pendingTimeoutMs }
+                    : {}),
             });
         },
         onSuccess: (data, variables) => settleCommand(variables.commandId, {

package/dist/rpc/rpc-dispatcher.d.ts

@@ -5,7 +5,20 @@ import type { RpcRequest, RpcStatus } from "../types/common";
 export interface SendRpcOptions<TPending = undefined> {
     onStatus?: (status: RpcStatus<TPending>) => void;
     signal?: AbortSignal;
+    /**
+     * How long to wait to hear from the device at all. A healthy device answers
+     * within seconds however long the work then takes, so keep this short and
+     * use `pendingTimeoutMs` for the work itself.
+     */
     timeoutMs?: number;
+    /**
+     * How long the command may then stay in flight once the device has answered
+     * it — acknowledged it, or reported progress. Re-armed on every subsequent
+     * status update, so a device that keeps reporting keeps its command alive,
+     * while one that answers and then dies still fails. Without this, a handler
+     * that legitimately runs longer than `timeoutMs` is killed mid-flight.
+     */
+    pendingTimeoutMs?: number;
 }
 interface ChannelIdentifierLike {
     agentId: string;

package/dist/rpc/rpc-dispatcher.js

@@ -2,6 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RpcDispatcher = void 0;
 const errors_1 = require("./errors");
+/** Whether the device has answered this command, rather than only received it. */
+function hasDeviceAnswered(status) {
+    return status.code === "acknowledged" || status.code === "pending";
+}
 function isRpcMessageData(data) {
     return (typeof data === "object" &&
         data !== null &&
@@ -45,6 +49,7 @@ class RpcDispatcher {
                     channelKey,
                     channel: channelRef,
                     startedAt,
+                    pendingTimeoutMs: options?.pendingTimeoutMs,
                 };
                 if (options?.signal) {
                     const onAbort = () => this.settle(message.id, "abort", undefined, options.signal?.reason);
@@ -109,6 +114,15 @@ class RpcDispatcher {
         else if (status.code === "error") {
             this.settle(msg.id, "error", undefined, new errors_1.DooverRpcError(status, pending.request));
         }
+        else if (hasDeviceAnswered(status) && pending.pendingTimeoutMs !== undefined) {
+            // The device is alive and working: swap the "no response" deadline for
+            // the pending budget, and re-arm it on every report that follows.
+            if (pending.timer)
+                clearTimeout(pending.timer);
+            pending.timer = setTimeout(() => {
+                this.settle(msg.id, "timeout", undefined, new Error("Device stopped reporting progress"));
+            }, pending.pendingTimeoutMs);
+        }
     }
     settle(messageId, outcome, response, rejection) {
         const pending = this.pending.get(messageId);

package/dist/test/gateway-client.test.js

@@ -393,4 +393,82 @@ class RejectingAuth extends doover_auth_1.DooverAuth {
         (0, chai_1.expect)(helpers_1.MockWebSocket.instances.length).to.equal(11);
         randomStub.restore();
     });
+    (0, mocha_1.describe)("an unusable dataWssUrl", () => {
+        // A relative or empty value is resolved against the document by the
+        // WebSocket constructor, so the gateway silently points at whatever page
+        // is open, gets that page's HTML and a 200 back, and retries against it
+        // forever. Refusing it names the cause once instead.
+        (0, mocha_1.it)("refuses an empty one rather than resolving against the page", async () => {
+            const client = new gateway_client_1.GatewayClient({
+                dataRestUrl: "https://api.example.com",
+                controlApiUrl: "https://control.example.com",
+                dataWssUrl: "",
+                organisationId: null,
+                sharing: "none",
+                impersonateUserStorageKey: "doover:test",
+            });
+            await (0, chai_1.expect)(client.connect()).to.be.rejectedWith(/dataWssUrl is empty/);
+            (0, chai_1.expect)(helpers_1.MockWebSocket.instances).to.have.length(0);
+        });
+        (0, mocha_1.it)("refuses a relative one", async () => {
+            const client = new gateway_client_1.GatewayClient({
+                dataRestUrl: "https://api.example.com",
+                controlApiUrl: "https://control.example.com",
+                dataWssUrl: "/widget/some_widget?app_key=k",
+                organisationId: null,
+                sharing: "none",
+                impersonateUserStorageKey: "doover:test",
+            });
+            await (0, chai_1.expect)(client.connect()).to.be.rejectedWith(/not the relative value/);
+            (0, chai_1.expect)(helpers_1.MockWebSocket.instances).to.have.length(0);
+        });
+        (0, mocha_1.it)("refuses a scheme a WebSocket cannot be opened on", async () => {
+            const client = new gateway_client_1.GatewayClient({
+                dataRestUrl: "https://api.example.com",
+                controlApiUrl: "https://control.example.com",
+                dataWssUrl: "file:///etc/hosts",
+                organisationId: null,
+                sharing: "none",
+                impersonateUserStorageKey: "doover:test",
+            });
+            await (0, chai_1.expect)(client.connect()).to.be.rejectedWith(/must be ws\(s\):\/\/ or http\(s\)/);
+            (0, chai_1.expect)(helpers_1.MockWebSocket.instances).to.have.length(0);
+        });
+        (0, mocha_1.it)("reports it through wssError once when a subscribe connects in the background", async () => {
+            // `subscribe` is fire-and-forget, so the fault has to surface as an event
+            // rather than a rejected promise nobody holds — and only once, because
+            // reconnects are scheduled on socket close and no socket was ever opened.
+            const client = new gateway_client_1.GatewayClient({
+                dataRestUrl: "https://api.example.com",
+                controlApiUrl: "https://control.example.com",
+                dataWssUrl: "",
+                organisationId: null,
+                sharing: "none",
+                impersonateUserStorageKey: "doover:test",
+            });
+            const errors = [];
+            client.on("wssError", (event) => errors.push(String(event.message)));
+            client.subscribe({ agent_id: "111", name: "tag_values" });
+            // The rejection travels connect -> openSocket -> catch, which is several
+            // microtasks; draining them is not the same as advancing fake timers.
+            for (let tick = 0; tick < 5; tick += 1)
+                await Promise.resolve();
+            (0, chai_1.expect)(errors).to.have.length(1);
+            (0, chai_1.expect)(errors[0]).to.match(/dataWssUrl is empty/);
+            (0, chai_1.expect)(helpers_1.MockWebSocket.instances).to.have.length(0);
+        });
+        (0, mocha_1.it)("still accepts an absolute http(s) URL, which WebSocket maps itself", async () => {
+            const client = new gateway_client_1.GatewayClient({
+                dataRestUrl: "https://api.example.com",
+                controlApiUrl: "https://control.example.com",
+                dataWssUrl: "https://ws.example.com/gateway",
+                organisationId: null,
+                sharing: "none",
+                impersonateUserStorageKey: "doover:test",
+            });
+            await client.connect();
+            (0, chai_1.expect)(helpers_1.MockWebSocket.instances).to.have.length(1);
+            (0, chai_1.expect)(helpers_1.MockWebSocket.instances[0].url).to.equal("https://ws.example.com/gateway");
+        });
+    });
 });

package/dist/test/rpc-dispatcher.test.js

@@ -188,3 +188,64 @@ describe("RpcDispatcher stats integration", () => {
         (0, chai_1.expect)(snap.rpc.peakPendingRpcs).to.equal(1);
     });
 });
+describe("RpcDispatcher pending timeout", () => {
+    const setup = (id) => {
+        const gw = makeFakeGateway();
+        const messages = makeFakeMessagesApi();
+        messages.setNextId(id);
+        const dispatcher = new rpc_dispatcher_1.RpcDispatcher(gw, messages);
+        return { gw, dispatcher, channel: { agent_id: "a1", name: "c1" } };
+    };
+    it("replaces the initial timeout once the device answers", async () => {
+        const { gw, dispatcher, channel } = setup("rpc-p1");
+        const promise = dispatcher.send({ agentId: "a1", channelName: "c1" }, { method: "do", request: {} }, { timeoutMs: 10, pendingTimeoutMs: 200 });
+        await new Promise((r) => setImmediate(r));
+        // Acknowledged before the 10ms deadline: the command must survive well past
+        // it, because the device has proven it is working.
+        gw.emitMessageUpdate(rpcMessage("rpc-p1", channel, { code: "acknowledged", message: { timestamp: 1 } }, {}));
+        await new Promise((r) => setTimeout(r, 60));
+        gw.emitMessageUpdate(rpcMessage("rpc-p1", channel, { code: "success" }, {}, { ok: true }));
+        (0, chai_1.expect)(await promise).to.deep.equal({ ok: true });
+    });
+    it("re-arms the pending budget on every progress report", async () => {
+        const { gw, dispatcher, channel } = setup("rpc-p2");
+        const promise = dispatcher.send({ agentId: "a1", channelName: "c1" }, { method: "do", request: {} }, { timeoutMs: 10, pendingTimeoutMs: 50 });
+        await new Promise((r) => setImmediate(r));
+        // Four reports, each well inside the 50ms budget but cumulatively past it.
+        for (let i = 0; i < 4; i += 1) {
+            gw.emitMessageUpdate(rpcMessage("rpc-p2", channel, { code: "pending", message: { text: `step ${i}` } }, {}));
+            await new Promise((r) => setTimeout(r, 30));
+        }
+        gw.emitMessageUpdate(rpcMessage("rpc-p2", channel, { code: "success" }, {}, { ok: 1 }));
+        (0, chai_1.expect)(await promise).to.deep.equal({ ok: 1 });
+    });
+    it("fails a device that answers and then goes quiet", async () => {
+        const { gw, dispatcher, channel } = setup("rpc-p3");
+        const promise = dispatcher.send({ agentId: "a1", channelName: "c1" }, { method: "do", request: {} }, { timeoutMs: 1000, pendingTimeoutMs: 20 });
+        await new Promise((r) => setImmediate(r));
+        gw.emitMessageUpdate(rpcMessage("rpc-p3", channel, { code: "acknowledged", message: { timestamp: 1 } }, {}));
+        let caught;
+        try {
+            await promise;
+        }
+        catch (e) {
+            caught = e;
+        }
+        // Distinct from "RPC timed out": it answered, then stopped.
+        (0, chai_1.expect)(caught?.message).to.equal("Device stopped reporting progress");
+    });
+    it("keeps the flat deadline when no pending budget is given", async () => {
+        const { gw, dispatcher, channel } = setup("rpc-p4");
+        const promise = dispatcher.send({ agentId: "a1", channelName: "c1" }, { method: "do", request: {} }, { timeoutMs: 20 });
+        await new Promise((r) => setImmediate(r));
+        gw.emitMessageUpdate(rpcMessage("rpc-p4", channel, { code: "acknowledged", message: { timestamp: 1 } }, {}));
+        let caught;
+        try {
+            await promise;
+        }
+        catch (e) {
+            caught = e;
+        }
+        (0, chai_1.expect)(caught?.message).to.equal("RPC timed out");
+    });
+});

package/dist/test/utils.test.js

@@ -12,6 +12,16 @@ const path_parsing_1 = require("../viewer/path-parsing");
         (0, chai_1.expect)(extracted.timestamp).to.equal(date.getTime());
         (0, chai_1.expect)(id).to.match(/^\d+$/);
     });
+    (0, mocha_1.it)("floors a pre-epoch time at the oldest addressable id", () => {
+        // Ids are unsigned; the API rejects a negative one outright and fails the whole
+        // request, so a caller reaching further back than 2025-01-01 gets the epoch.
+        (0, chai_1.expect)((0, snowflake_1.generateSnowflakeIdAtTime)(new Date("2023-11-18T02:58:19.326Z"))).to.equal("0");
+        (0, chai_1.expect)((0, snowflake_1.generateSnowflakeIdAtTime)(new Date("2025-01-01T00:00:00.000Z"))).to.equal("0");
+        (0, chai_1.expect)((0, snowflake_1.generateSnowflakeIdAtTime)(new Date(0))).to.equal("0");
+    });
+    (0, mocha_1.it)("rejects an invalid time rather than emitting a garbage id", () => {
+        (0, chai_1.expect)(() => (0, snowflake_1.generateSnowflakeIdAtTime)(new Date("nonsense"))).to.throw(TypeError);
+    });
     (0, mocha_1.it)("adds an epoch-ms timestamp to messages", () => {
         const date = new Date("2026-01-02T03:04:05.000Z");
         const id = (0, snowflake_1.generateSnowflakeIdAtTime)(date);

package/dist/types/common.d.ts

@@ -146,9 +146,18 @@ export interface DataSeries {
     __source?: SourceProvenance;
 }
 /**
- * Lifecycle status for an RPC. `pending` carries arbitrary intermediate
- * payloads (progress updates) emitted by the server while the request is
- * in flight.
+ * Lifecycle status for an RPC.
+ *
+ * `sent` is written by the sender; the other non-terminal codes come from the
+ * device handling the request. `acknowledged` means it has picked the request
+ * up, and `pending` carries arbitrary intermediate payloads (progress updates)
+ * it emits while still working — by convention a `{ text }` summary, plus
+ * whatever structured fields the handler wants alongside it. Both prove the
+ * device is alive, so consumers should treat either as a reason to extend how
+ * long they are willing to wait (see `SendRpcOptions.pendingTimeoutMs`), never
+ * as a completion.
+ *
+ * `success` and `error` are the only terminal codes.
  */
 export type RpcStatus<TPending = undefined> = {
     code: "awaiting_confirmation";

package/dist/utils/snowflake.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Snowflake id for a point in time, floored at the epoch.
+ *
+ * Ids are unsigned, so a pre-epoch time has no id to generate. Returning the
+ * negative arithmetic result produced a value the API rejects outright
+ * ("expected a snowflake id value"), failing the whole request; `0` is the
+ * oldest addressable id, which is what a caller reaching further back wants.
+ */
 export declare function generateSnowflakeIdAtTime(time: {
     valueOf(): number;
 }): string;

package/dist/utils/snowflake.js

@@ -3,10 +3,22 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateSnowflakeIdAtTime = generateSnowflakeIdAtTime;
 exports.extractSnowflakeId = extractSnowflakeId;
 exports.addTimestampToMessage = addTimestampToMessage;
+/** Doover's snowflake epoch: 2025-01-01T00:00:00Z. Nothing predates it. */
+const SNOWFLAKE_EPOCH_MS = 1735689600000;
+/**
+ * Snowflake id for a point in time, floored at the epoch.
+ *
+ * Ids are unsigned, so a pre-epoch time has no id to generate. Returning the
+ * negative arithmetic result produced a value the API rejects outright
+ * ("expected a snowflake id value"), failing the whole request; `0` is the
+ * oldest addressable id, which is what a caller reaching further back wants.
+ */
 function generateSnowflakeIdAtTime(time) {
-    const offset = 1735689600000;
-    const bigTime = BigInt(time.valueOf() - offset);
-    const bigId = bigTime << 22n;
+    const offsetMs = time.valueOf() - SNOWFLAKE_EPOCH_MS;
+    if (Number.isNaN(offsetMs)) {
+        throw new TypeError("generateSnowflakeIdAtTime received an invalid time");
+    }
+    const bigId = BigInt(Math.max(0, offsetMs)) << 22n;
     return bigId.toString();
 }
 function extractSnowflakeId(id) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doover-js",
-  "version": "0.9.1",
+  "version": "0.10.1",
   "description": "TypeScript client for Doover.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",