@blueyerobotics/blueye-ts 4.0.3 → 5.0.0

package/dist/src/connection-state.d.ts

@@ -0,0 +1,36 @@
+export type SocketName = "sub" | "rpc" | "pub" | "sonar";
+export type ConnectionState = "connecting" | "connected" | "disconnected";
+export type ConnectionTransition = {
+    scope: "socket";
+    name: SocketName;
+    state: ConnectionState;
+} | {
+    scope: "client";
+    state: ConnectionState;
+};
+/**
+ * Owns every piece of connection state: the connect/disconnect intent, the
+ * per-socket readiness, and whether a detected sonar makes the sonar socket
+ * required. All mutations go through the methods below, and each returns the
+ * exact list of transitions that occurred — a transition is only ever
+ * reported when something actually changed, so consumers can treat the
+ * resulting events as edge-triggered.
+ */
+export declare class ConnectionTracker {
+    private intent;
+    private sonarRequired;
+    private pending;
+    private sockets;
+    /** True between connectRequested() and disconnectRequested(). */
+    get intended(): boolean;
+    /** True once a sonar has been detected on the current connection. */
+    get isSonarRequired(): boolean;
+    get state(): ConnectionState;
+    connectRequested(): ConnectionTransition[];
+    disconnectRequested(): ConnectionTransition[];
+    socketReady(name: SocketName): ConnectionTransition[];
+    socketLost(name: SocketName): ConnectionTransition[];
+    sonarDetected(): ConnectionTransition[];
+    private setSocket;
+    private collect;
+}

package/dist/src/connection-state.js

@@ -0,0 +1,100 @@
+const CORE_SOCKETS = ["sub", "rpc", "pub"];
+/**
+ * Owns every piece of connection state: the connect/disconnect intent, the
+ * per-socket readiness, and whether a detected sonar makes the sonar socket
+ * required. All mutations go through the methods below, and each returns the
+ * exact list of transitions that occurred — a transition is only ever
+ * reported when something actually changed, so consumers can treat the
+ * resulting events as edge-triggered.
+ */
+export class ConnectionTracker {
+    intent = false;
+    sonarRequired = false;
+    pending = [];
+    sockets = {
+        sub: "disconnected",
+        rpc: "disconnected",
+        pub: "disconnected",
+        sonar: "disconnected",
+    };
+    /** True between connectRequested() and disconnectRequested(). */
+    get intended() {
+        return this.intent;
+    }
+    /** True once a sonar has been detected on the current connection. */
+    get isSonarRequired() {
+        return this.sonarRequired;
+    }
+    get state() {
+        if (!this.intent)
+            return "disconnected";
+        const required = this.sonarRequired
+            ? [...CORE_SOCKETS, "sonar"]
+            : CORE_SOCKETS;
+        return required.every((name) => this.sockets[name] === "connected")
+            ? "connected"
+            : "connecting";
+    }
+    connectRequested() {
+        if (this.intent)
+            return [];
+        return this.collect(() => {
+            this.intent = true;
+            for (const name of CORE_SOCKETS) {
+                this.setSocket(name, "connecting");
+            }
+        });
+    }
+    disconnectRequested() {
+        if (!this.intent)
+            return [];
+        return this.collect(() => {
+            this.intent = false;
+            // Sonar detection is per-connection: the next connect() starts without
+            // requiring the sonar socket until a sonar is detected again.
+            this.sonarRequired = false;
+            for (const name of Object.keys(this.sockets)) {
+                this.setSocket(name, "disconnected");
+            }
+        });
+    }
+    socketReady(name) {
+        if (!this.intent)
+            return [];
+        return this.collect(() => {
+            this.setSocket(name, "connected");
+        });
+    }
+    socketLost(name) {
+        if (!this.intent)
+            return [];
+        return this.collect(() => {
+            this.setSocket(name, "connecting");
+        });
+    }
+    sonarDetected() {
+        if (!this.intent || this.sonarRequired)
+            return [];
+        return this.collect(() => {
+            this.sonarRequired = true;
+            this.setSocket("sonar", "connecting");
+        });
+    }
+    setSocket(name, state) {
+        if (this.sockets[name] === state)
+            return;
+        this.sockets[name] = state;
+        this.pending.push({ scope: "socket", name, state });
+    }
+    collect(mutate) {
+        const before = this.state;
+        this.pending = [];
+        mutate();
+        const transitions = this.pending;
+        this.pending = [];
+        if (this.state !== before) {
+            transitions.push({ scope: "client", state: this.state });
+        }
+        return transitions;
+    }
+}

package/dist/src/in-memory-transport.d.ts

@@ -0,0 +1,75 @@
+import type { SocketKind, Transport, TransportEvents, TransportFrame, TransportSocket } from "./transport";
+export type InMemoryReply = (frames: TransportFrame[]) => void;
+export type InMemoryMessageHandler = (frames: Uint8Array[], reply: InMemoryReply) => void;
+/**
+ * The "server" end of an in-memory URL. Tests use it to receive what the
+ * client sends and to publish or reply with frames of their own.
+ */
+export declare class InMemoryEndpoint {
+    readonly url: string;
+    private hub;
+    private handlers;
+    closed: boolean;
+    constructor(url: string, hub: InMemoryTransport);
+    onMessage(handler: InMemoryMessageHandler): void;
+    /** Broadcast frames to every subscribed socket connected to this URL. */
+    send(frames: TransportFrame[]): void;
+    /** Simulate server loss: connected sockets emit "lost" and re-attach when a new endpoint is listening. */
+    close(): void;
+    /**
+     * Simulate a silently-dead link (tether/radio drop with no TCP FIN/RST):
+     * the endpoint stops delivering in either direction, but connected sockets
+     * receive NO "lost" event and continue to believe they are attached.
+     */
+    sever(): void;
+    deliver(frames: Uint8Array[], reply: InMemoryReply): void;
+}
+declare class InMemorySocket implements TransportSocket {
+    readonly kind: SocketKind;
+    private hub;
+    private emitter;
+    private wantedUrls;
+    private attachedUrls;
+    private subscriptions;
+    private closed;
+    constructor(kind: SocketKind, hub: InMemoryTransport);
+    connect(url: string): void;
+    disconnect(url: string): void;
+    close(): void;
+    send(frames: TransportFrame[]): void;
+    dropConnection(): void;
+    subscribe(topic: string): void;
+    unsubscribe(topic: string): void;
+    setReconnectInterval(_ms: number): void;
+    on<E extends keyof TransportEvents>(event: E, listener: (...args: TransportEvents[E]) => void): void;
+    once<E extends keyof TransportEvents>(event: E, listener: (...args: TransportEvents[E]) => void): void;
+    off<E extends keyof TransportEvents>(event: E, listener: (...args: TransportEvents[E]) => void): void;
+    wants(url: string): boolean;
+    isAttached(url: string): boolean;
+    attach(url: string): void;
+    detach(url: string): void;
+    emitMessage(frames: Uint8Array[]): void;
+}
+/**
+ * In-memory adapter for the transport seam. Deterministic and portless:
+ * sockets attach to endpoints the moment both sides exist, loss and recovery
+ * are explicit method calls, and no timers are involved.
+ */
+export declare class InMemoryTransport implements Transport {
+    private endpoints;
+    private sockets;
+    createSocket(kind: SocketKind): TransportSocket;
+    /** Bring up the server end of a URL. Sockets wanting it attach immediately. */
+    listen(url: string): InMemoryEndpoint;
+    endpoint(url: string): InMemoryEndpoint | undefined;
+    /** Close every endpoint — simulates losing the whole server. */
+    closeAll(): void;
+    /** Sever every endpoint silently — simulates a dead link with no close event. */
+    severAll(): void;
+    tryAttach(socket: InMemorySocket, url: string): void;
+    dropEndpoint(url: string): void;
+    severEndpoint(url: string): void;
+    removeSocket(socket: InMemorySocket): void;
+    broadcast(url: string, frames: Uint8Array[]): void;
+}
+export {};

package/dist/src/in-memory-transport.js

@@ -0,0 +1,253 @@
+const utf8Encoder = new TextEncoder();
+const encodeFrame = (frame) => typeof frame === "string" ? utf8Encoder.encode(frame) : frame;
+class MiniEmitter {
+    listeners = new Map();
+    on(event, listener) {
+        let set = this.listeners.get(event);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(event, set);
+        }
+        set.add(listener);
+    }
+    once(event, listener) {
+        const wrapper = (...args) => {
+            this.off(event, wrapper);
+            listener(...args);
+        };
+        // Track the original so off(listener) also removes the wrapper
+        wrapper.original = listener;
+        this.on(event, wrapper);
+    }
+    off(event, listener) {
+        const set = this.listeners.get(event);
+        if (!set)
+            return;
+        for (const registered of set) {
+            if (registered === listener ||
+                registered.original === listener) {
+                set.delete(registered);
+            }
+        }
+    }
+    emit(event, ...args) {
+        const set = this.listeners.get(event);
+        if (!set)
+            return;
+        for (const listener of [...set]) {
+            listener(...args);
+        }
+    }
+}
+/**
+ * The "server" end of an in-memory URL. Tests use it to receive what the
+ * client sends and to publish or reply with frames of their own.
+ */
+export class InMemoryEndpoint {
+    url;
+    hub;
+    handlers = [];
+    closed = false;
+    constructor(url, hub) {
+        this.url = url;
+        this.hub = hub;
+    }
+    onMessage(handler) {
+        this.handlers.push(handler);
+    }
+    /** Broadcast frames to every subscribed socket connected to this URL. */
+    send(frames) {
+        this.hub.broadcast(this.url, frames.map(encodeFrame));
+    }
+    /** Simulate server loss: connected sockets emit "lost" and re-attach when a new endpoint is listening. */
+    close() {
+        this.closed = true;
+        this.hub.dropEndpoint(this.url);
+    }
+    /**
+     * Simulate a silently-dead link (tether/radio drop with no TCP FIN/RST):
+     * the endpoint stops delivering in either direction, but connected sockets
+     * receive NO "lost" event and continue to believe they are attached.
+     */
+    sever() {
+        this.closed = true;
+        this.hub.severEndpoint(this.url);
+    }
+    deliver(frames, reply) {
+        for (const handler of this.handlers) {
+            handler(frames, reply);
+        }
+    }
+}
+class InMemorySocket {
+    kind;
+    hub;
+    emitter = new MiniEmitter();
+    wantedUrls = new Set();
+    attachedUrls = new Set();
+    subscriptions = new Set();
+    closed = false;
+    constructor(kind, hub) {
+        this.kind = kind;
+        this.hub = hub;
+    }
+    connect(url) {
+        if (this.closed)
+            return;
+        this.wantedUrls.add(url);
+        this.hub.tryAttach(this, url);
+    }
+    disconnect(url) {
+        this.wantedUrls.delete(url);
+        this.attachedUrls.delete(url);
+    }
+    close() {
+        this.closed = true;
+        this.wantedUrls.clear();
+        this.attachedUrls.clear();
+        this.hub.removeSocket(this);
+    }
+    send(frames) {
+        if (this.closed)
+            return;
+        const encoded = frames.map(encodeFrame);
+        for (const url of this.attachedUrls) {
+            const endpoint = this.hub.endpoint(url);
+            endpoint?.deliver(encoded, (reply) => {
+                this.emitMessage(reply.map(encodeFrame));
+            });
+        }
+    }
+    dropConnection() {
+        if (this.closed)
+            return;
+        for (const url of [...this.attachedUrls]) {
+            this.detach(url);
+        }
+        // Mimic the transport's automatic reconnection: if the endpoint is
+        // still listening, the socket re-attaches right after the loss.
+        for (const url of this.wantedUrls) {
+            this.hub.tryAttach(this, url);
+        }
+    }
+    subscribe(topic) {
+        this.subscriptions.add(topic);
+    }
+    unsubscribe(topic) {
+        this.subscriptions.delete(topic);
+    }
+    setReconnectInterval(_ms) {
+        // Reconnection is event-driven in-memory: sockets re-attach as soon as an
+        // endpoint starts listening again, so the interval is irrelevant.
+    }
+    on(event, listener) {
+        this.emitter.on(event, listener);
+    }
+    once(event, listener) {
+        this.emitter.once(event, listener);
+    }
+    off(event, listener) {
+        this.emitter.off(event, listener);
+    }
+    wants(url) {
+        return !this.closed && this.wantedUrls.has(url);
+    }
+    isAttached(url) {
+        return this.attachedUrls.has(url);
+    }
+    attach(url) {
+        if (this.closed || !this.wantedUrls.has(url))
+            return;
+        if (this.attachedUrls.has(url))
+            return;
+        this.attachedUrls.add(url);
+        queueMicrotask(() => {
+            if (this.attachedUrls.has(url)) {
+                this.emitter.emit("ready");
+            }
+        });
+    }
+    detach(url) {
+        if (!this.attachedUrls.delete(url))
+            return;
+        queueMicrotask(() => {
+            if (!this.closed) {
+                this.emitter.emit("lost");
+            }
+        });
+    }
+    emitMessage(frames) {
+        if (this.closed)
+            return;
+        const [topic, payload] = frames;
+        queueMicrotask(() => {
+            if (!this.closed) {
+                this.emitter.emit("message", topic, payload);
+            }
+        });
+    }
+}
+/**
+ * In-memory adapter for the transport seam. Deterministic and portless:
+ * sockets attach to endpoints the moment both sides exist, loss and recovery
+ * are explicit method calls, and no timers are involved.
+ */
+export class InMemoryTransport {
+    endpoints = new Map();
+    sockets = new Set();
+    createSocket(kind) {
+        const socket = new InMemorySocket(kind, this);
+        this.sockets.add(socket);
+        return socket;
+    }
+    /** Bring up the server end of a URL. Sockets wanting it attach immediately. */
+    listen(url) {
+        const endpoint = new InMemoryEndpoint(url, this);
+        this.endpoints.set(url, endpoint);
+        for (const socket of this.sockets) {
+            this.tryAttach(socket, url);
+        }
+        return endpoint;
+    }
+    endpoint(url) {
+        return this.endpoints.get(url);
+    }
+    /** Close every endpoint — simulates losing the whole server. */
+    closeAll() {
+        for (const endpoint of [...this.endpoints.values()]) {
+            endpoint.close();
+        }
+    }
+    /** Sever every endpoint silently — simulates a dead link with no close event. */
+    severAll() {
+        for (const endpoint of [...this.endpoints.values()]) {
+            endpoint.sever();
+        }
+    }
+    tryAttach(socket, url) {
+        if (this.endpoints.has(url) && socket.wants(url)) {
+            socket.attach(url);
+        }
+    }
+    dropEndpoint(url) {
+        this.endpoints.delete(url);
+        for (const socket of this.sockets) {
+            socket.detach(url);
+        }
+    }
+    severEndpoint(url) {
+        // Silent: the endpoint disappears but sockets are not detached and get
+        // no "lost" — they keep believing the link is up.
+        this.endpoints.delete(url);
+    }
+    removeSocket(socket) {
+        this.sockets.delete(socket);
+    }
+    broadcast(url, frames) {
+        for (const socket of this.sockets) {
+            if (socket.kind === "sub" && socket.isAttached(url)) {
+                socket.emitMessage(frames);
+            }
+        }
+    }
+}

package/dist/src/protocol.d.ts

@@ -0,0 +1,29 @@
+import { blueye } from "@blueyerobotics/protocol-definitions";
+export type Protocol = typeof blueye.protocol;
+export type ProtocolType = "Req" | "Rep" | "Tel" | "Ctrl";
+export type ProtocolKey = Extract<keyof Protocol, `${string}${ProtocolType}`>;
+export type Req = keyof Pick<Protocol, Extract<ProtocolKey, `${string}Req`>>;
+export type Rep = keyof Pick<Protocol, Extract<ProtocolKey, `${string}Rep`>>;
+export type Tel = keyof Pick<Protocol, Extract<ProtocolKey, `${string}Tel`>>;
+export type Ctrl = keyof Pick<Protocol, Extract<ProtocolKey, `${string}Ctrl`>>;
+export type ReqToRep<T extends Req> = T extends `${infer Prefix}Req` ? `${Prefix}Rep` extends ProtocolKey ? Protocol[`${Prefix}Rep`] : never : never;
+export type MsgHandler<T extends Req | Ctrl> = Protocol[T];
+export type CreateArgs<T extends Req | Ctrl> = Parameters<MsgHandler<T>["create"]>[0];
+export type DecodedOutput<T extends Req> = ReturnType<ReqToRep<T>["decode"]>;
+export type DecodedTelOutput<T extends Tel> = ReturnType<Protocol[T]["decode"]>;
+export type DecodedMessage<K extends ProtocolKey> = ReturnType<Protocol[K]["decode"]>;
+export declare const isInProtocol: (key: string) => key is keyof typeof blueye.protocol;
+export declare const isReq: (key: string) => key is Req;
+export declare const isRep: (key: string) => key is Rep;
+export declare const isTel: (key: string) => key is Tel;
+export declare const isCtrl: (key: string) => key is Ctrl;
+/**
+ * Extract the protocol key from a fully-qualified topic or typeUrl —
+ * "blueye.protocol.BatteryTel" (as text or bytes) becomes "BatteryTel".
+ */
+export declare const topicToKey: (topic: Uint8Array | string) => string;
+/** The inverse of topicToKey: "BatteryTel" becomes "blueye.protocol.BatteryTel". */
+export declare const keyToTopic: (key: ProtocolKey) => string;
+export declare const protocolTypeOf: (key: ProtocolKey) => ProtocolType;
+export declare const encodeMessage: <T extends Req | Ctrl>(key: T, opts: CreateArgs<T>) => Uint8Array;
+export declare const decodeMessage: <K extends ProtocolKey>(key: K, data: Uint8Array) => DecodedMessage<K>;

package/dist/src/protocol.js

@@ -0,0 +1,38 @@
+import { blueye } from "@blueyerobotics/protocol-definitions";
+const utf8Decoder = new TextDecoder();
+export const isInProtocol = (key) => {
+    return key in blueye.protocol;
+};
+export const isReq = (key) => isInProtocol(key) && key.endsWith("Req");
+export const isRep = (key) => isInProtocol(key) && key.endsWith("Rep");
+export const isTel = (key) => isInProtocol(key) && key.endsWith("Tel");
+export const isCtrl = (key) => isInProtocol(key) && key.endsWith("Ctrl");
+/**
+ * Extract the protocol key from a fully-qualified topic or typeUrl —
+ * "blueye.protocol.BatteryTel" (as text or bytes) becomes "BatteryTel".
+ */
+export const topicToKey = (topic) => {
+    const text = typeof topic === "string" ? topic : utf8Decoder.decode(topic);
+    return text.split(".").at(-1) ?? "";
+};
+/** The inverse of topicToKey: "BatteryTel" becomes "blueye.protocol.BatteryTel". */
+export const keyToTopic = (key) => `blueye.protocol.${key}`;
+export const protocolTypeOf = (key) => {
+    if (key.endsWith("Ctrl"))
+        return "Ctrl";
+    if (key.endsWith("Rep"))
+        return "Rep";
+    if (key.endsWith("Req"))
+        return "Req";
+    return "Tel";
+};
+export const encodeMessage = (key, opts) => {
+    const codec = blueye.protocol[key];
+    const message = codec.create(opts);
+    // The union of all message codecs collapses each encode parameter to never;
+    // `message` came from the same codec's create, so the call is sound.
+    return codec.encode(message).finish();
+};
+export const decodeMessage = (key, data) => {
+    return blueye.protocol[key].decode(data);
+};

package/dist/src/request-pipeline.d.ts

@@ -0,0 +1,23 @@
+import type { TransportFrame, TransportSocket } from "./transport";
+export type ReplyFrames = [topic: Uint8Array, payload: Uint8Array];
+/**
+ * Owns the request/reply cycle over a REQ socket: requests are serialized
+ * (one in flight at a time), each reply is correlated to the request that is
+ * actually awaiting it, timeouts clean up after themselves, and one failed
+ * request never affects the next.
+ *
+ * REQ sockets are lockstep — a new request cannot be sent while a reply is
+ * still owed. After a timeout the pipeline keeps tracking the owed reply:
+ * a late arrival is discarded (never mis-delivered to a later request), and
+ * requests made while the reply is still owed fail fast. A connection loss
+ * clears the slate.
+ */
+export declare class RequestPipeline {
+    private socket;
+    private tail;
+    private waiter;
+    private expectingReply;
+    constructor(socket: TransportSocket);
+    request(frames: TransportFrame[], timeoutMs: number): Promise<ReplyFrames>;
+    private execute;
+}

package/dist/src/request-pipeline.js

@@ -0,0 +1,74 @@
+/**
+ * Owns the request/reply cycle over a REQ socket: requests are serialized
+ * (one in flight at a time), each reply is correlated to the request that is
+ * actually awaiting it, timeouts clean up after themselves, and one failed
+ * request never affects the next.
+ *
+ * REQ sockets are lockstep — a new request cannot be sent while a reply is
+ * still owed. After a timeout the pipeline keeps tracking the owed reply:
+ * a late arrival is discarded (never mis-delivered to a later request), and
+ * requests made while the reply is still owed fail fast. A connection loss
+ * clears the slate.
+ */
+export class RequestPipeline {
+    socket;
+    tail = Promise.resolve();
+    waiter = null;
+    expectingReply = false;
+    constructor(socket) {
+        this.socket = socket;
+        this.socket.on("message", (topic, payload) => {
+            this.expectingReply = false;
+            const waiter = this.waiter;
+            this.waiter = null;
+            // No waiter means the request timed out — the late reply is discarded
+            waiter?.resolve([topic, payload]);
+        });
+        this.socket.on("lost", () => {
+            this.expectingReply = false;
+            const waiter = this.waiter;
+            this.waiter = null;
+            waiter?.reject(new Error("[rpc] connection lost while awaiting reply"));
+        });
+    }
+    request(frames, timeoutMs) {
+        const result = this.tail.then(() => this.execute(frames, timeoutMs));
+        // Isolation: one failed request must not poison the pipeline
+        this.tail = result.catch(() => { });
+        return result;
+    }
+    execute(frames, timeoutMs) {
+        return new Promise((resolve, reject) => {
+            if (this.expectingReply) {
+                reject(new Error("[rpc] previous request timed out and its reply is still owed; waiting for the reply or a reconnect"));
+                return;
+            }
+            const timer = setTimeout(() => {
+                // Keep expectingReply set: the reply is still owed, and the message
+                // handler must discard it when (if) it arrives.
+                this.waiter = null;
+                reject(new Error("[rpc] request timed out"));
+            }, timeoutMs);
+            this.waiter = {
+                resolve: (reply) => {
+                    clearTimeout(timer);
+                    resolve(reply);
+                },
+                reject: (error) => {
+                    clearTimeout(timer);
+                    reject(error);
+                },
+            };
+            this.expectingReply = true;
+            try {
+                this.socket.send(frames);
+            }
+            catch (error) {
+                clearTimeout(timer);
+                this.waiter = null;
+                this.expectingReply = false;
+                reject(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
+    }
+}

package/dist/src/sonar-device.d.ts

@@ -0,0 +1,25 @@
+import type { DecodedTelOutput } from "./protocol";
+export declare const MULTIBEAM_DEVICE_IDS: number[];
+export type SonarDetection = {
+    detected: true;
+    deviceId: number;
+} | {
+    detected: false;
+    reason: "incompatible-firmware";
+    version: string | undefined;
+} | {
+    detected: false;
+    reason: "no-multibeam-device";
+};
+/**
+ * The sonar telemetry endpoint exists on Blunux >= 4.7.0; "-dev" builds are
+ * assumed to be newer than any release.
+ */
+export declare const hasSonarEndpoint: (version: string) => boolean;
+/**
+ * Decide from a DroneInfoTel whether a multibeam sonar is connected and
+ * reachable: the firmware must expose the sonar endpoint and a known
+ * multibeam device ID must be present in one of the guest-port device lists.
+ * Pure — no sockets, no side effects.
+ */
+export declare const detectSonar: (msg: DecodedTelOutput<"DroneInfoTel">) => SonarDetection;