zapo-js 0.1.0

package/dist/transport/WaComms.js

@@ -0,0 +1,531 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WaComms = void 0;
+const ConsoleLogger_1 = require("../infra/log/ConsoleLogger");
+const BoundedTaskQueue_1 = require("../infra/perf/BoundedTaskQueue");
+const constants_1 = require("../protocol/constants");
+const WaNoiseSession_1 = require("./noise/WaNoiseSession");
+const WaWebSocket_1 = require("./WaWebSocket");
+const base64_1 = require("../util/base64");
+const bytes_1 = require("../util/bytes");
+const primitives_1 = require("../util/primitives");
+const WA_FRAME_HANDLER_QUEUE_MAX_SIZE = 4096;
+const WA_FRAME_HANDLER_MAX_CONCURRENCY = 8;
+const WA_PENDING_FRAMES_MAX_COUNT = 2048;
+const WA_PENDING_FRAMES_MAX_BYTES = 16 * 1024 * 1024;
+class WaComms {
+    constructor(config, logger = new ConsoleLogger_1.ConsoleLogger('info')) {
+        if (!config.noise) {
+            throw new Error('WaComms requires noise config');
+        }
+        const routedSocketConfig = this.applyRoutingInfoToSocketConfig(config);
+        this.config = Object.freeze({
+            ...routedSocketConfig,
+            connectTimeoutMs: routedSocketConfig.connectTimeoutMs ?? 10000,
+            reconnectIntervalMs: routedSocketConfig.reconnectIntervalMs ?? 2000,
+            timeoutIntervalMs: routedSocketConfig.timeoutIntervalMs ?? 10000
+        });
+        this.logger = logger;
+        this.socket = new WaWebSocket_1.WaWebSocket({
+            url: this.config.url,
+            urls: this.config.urls,
+            protocols: this.config.protocols,
+            timeoutIntervalMs: this.config.timeoutIntervalMs
+        }, logger);
+        this.socket.setHandlers({
+            onOpen: async () => {
+                try {
+                    await this.onSocketOpened();
+                }
+                catch (error) {
+                    this.connected = false;
+                    this.logger.error('noise handshake failed', { message: (0, primitives_1.toError)(error).message });
+                    await this.socket.close(4003, 'noise_handshake_failed');
+                }
+            },
+            onClose: async (info) => {
+                await this.onSocketClosed(info);
+            },
+            onError: async (error) => {
+                this.logger.warn('socket runtime error', { message: error.message });
+            },
+            onMessage: (payload) => {
+                this.onSocketMessage(payload);
+            }
+        });
+        this.started = false;
+        this.connected = false;
+        this.handlingRequests = false;
+        this.preventRetry = false;
+        this.reconnectAttempts = 0;
+        this.reconnectTimer = null;
+        this.waiters = [];
+        this.stanzaHandler = null;
+        this.inflateFrame = null;
+        this.pendingFrames = [];
+        this.pendingFramesByteLength = 0;
+        this.pendingFramesMaxCount = WA_PENDING_FRAMES_MAX_COUNT;
+        this.pendingFramesMaxBytes = WA_PENDING_FRAMES_MAX_BYTES;
+        this.pendingFramesOverflowClosing = false;
+        this.resumeInFlight = false;
+        this.resumeHandshakeFailures = 0;
+        this.usedResumeHandshake = false;
+        this.noiseSession = null;
+        this.lastServerStaticKey = null;
+        this.frameProcessingQueue = Promise.resolve();
+        this.frameHandlerQueue = new BoundedTaskQueue_1.BoundedTaskQueue(WA_FRAME_HANDLER_QUEUE_MAX_SIZE, WA_FRAME_HANDLER_MAX_CONCURRENCY);
+    }
+    applyRoutingInfoToSocketConfig(config) {
+        const routingInfo = config.noise.routingInfo;
+        if (!routingInfo || routingInfo.byteLength === 0) {
+            return config;
+        }
+        const edValue = (0, base64_1.bytesToBase64UrlSafe)(routingInfo);
+        const appendEd = (url) => {
+            try {
+                const parsed = new URL(url);
+                if (!parsed.searchParams.has('ED')) {
+                    parsed.searchParams.set('ED', edValue);
+                }
+                return parsed.toString();
+            }
+            catch {
+                if (url.includes('ED=')) {
+                    return url;
+                }
+                const separator = url.includes('?') ? '&' : '?';
+                return `${url}${separator}ED=${encodeURIComponent(edValue)}`;
+            }
+        };
+        const cookieHeader = this.withStickyRoutingCookie(config.headers);
+        return {
+            ...config,
+            headers: cookieHeader,
+            url: config.url ? appendEd(config.url) : config.url,
+            urls: config.urls
+                ? config.urls.map((entry) => appendEd(entry))
+                : config.url
+                    ? undefined
+                    : constants_1.WA_DEFAULTS.CHAT_SOCKET_URLS.map((entry) => appendEd(entry))
+        };
+    }
+    startComms(handleStanza, inflateFrame) {
+        this.logger.info('comms start requested');
+        this.stanzaHandler = handleStanza;
+        this.inflateFrame = inflateFrame ?? null;
+        this.clearPendingFrames();
+        this.pendingFramesOverflowClosing = false;
+        this.started = true;
+        this.preventRetry = false;
+        this.connected = this.socket.isOpen();
+        this.handlingRequests = false;
+        this.frameProcessingQueue = Promise.resolve();
+        this.clearReconnectTimer();
+        void this.openSocket(false);
+    }
+    async waitForConnection(timeoutMs = this.config.connectTimeoutMs) {
+        if (!this.started) {
+            throw new Error('comms not started');
+        }
+        if (this.connected) {
+            this.logger.trace('comms waitForConnection immediate success');
+            return;
+        }
+        this.logger.debug('comms waiting for connection', { timeoutMs });
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.removeWaiter(reject);
+                reject(new Error(`comms connection timeout after ${timeoutMs}ms`));
+            }, timeoutMs);
+            this.waiters.push({
+                resolve,
+                reject,
+                timer
+            });
+        });
+    }
+    startHandlingRequests() {
+        this.handlingRequests = true;
+        this.logger.debug('comms request handling enabled');
+        this.frameProcessingQueue = this.frameProcessingQueue
+            .catch(() => undefined)
+            .then(async () => this.flushPendingFrames());
+    }
+    async stopComms() {
+        this.logger.info('comms stop requested');
+        this.resetConnectionState({
+            started: false,
+            connected: false,
+            handlingRequests: false,
+            preventRetry: true,
+            resumeInFlight: false,
+            clearHandlers: true,
+            rejectWaitersError: new Error('comms stopped')
+        });
+        await this.socket.close(1000, 'stop_comms');
+    }
+    async closeSocketAndResume() {
+        this.logger.info('comms close socket and resume requested');
+        this.resetConnectionState({
+            started: true,
+            connected: false,
+            handlingRequests: this.handlingRequests,
+            preventRetry: false,
+            resumeInFlight: true,
+            resetResumeHandshakeFailures: false
+        });
+        await this.socket.close(1000, 'resume_socket');
+        this.resumeInFlight = false;
+        void this.openSocket(true);
+    }
+    async closeSocketAndPreventRetry() {
+        this.logger.warn('comms close socket and prevent retry requested');
+        this.resetConnectionState({
+            started: false,
+            connected: false,
+            handlingRequests: false,
+            preventRetry: true,
+            resumeInFlight: false,
+            rejectWaitersError: new Error('socket closed and retry disabled')
+        });
+        await this.socket.close(1000, 'prevent_retry');
+    }
+    async sendFrame(payload) {
+        if (!this.noiseSession) {
+            throw new Error('noise session not ready');
+        }
+        const wire = await this.noiseSession.encryptFrame(payload);
+        await this.socket.send(wire);
+    }
+    getCommsState() {
+        return {
+            started: this.started,
+            connected: this.connected,
+            handlingRequests: this.handlingRequests,
+            reconnectAttempts: this.reconnectAttempts
+        };
+    }
+    getServerStaticKey() {
+        if (this.noiseSession) {
+            const current = this.noiseSession.getServerStaticKey();
+            if (current) {
+                this.lastServerStaticKey = current;
+                return current;
+            }
+        }
+        return this.lastServerStaticKey;
+    }
+    async openSocket(isReconnect) {
+        if (!this.started || this.preventRetry) {
+            this.logger.trace('comms openSocket skipped', {
+                started: this.started,
+                preventRetry: this.preventRetry
+            });
+            return;
+        }
+        if (this.socket.isOpen() || this.socket.isConnecting()) {
+            this.logger.trace('comms openSocket skipped: socket already open/connecting');
+            return;
+        }
+        if (isReconnect) {
+            this.reconnectAttempts += 1;
+            if (this.config.maxReconnectAttempts !== null &&
+                this.config.maxReconnectAttempts !== undefined &&
+                this.reconnectAttempts > this.config.maxReconnectAttempts) {
+                this.preventRetry = true;
+                this.started = false;
+                this.drainWaiters((waiter) => waiter.reject(new Error('max reconnect attempts reached')));
+                return;
+            }
+        }
+        try {
+            this.logger.debug('comms opening websocket', { isReconnect });
+            await this.socket.open();
+        }
+        catch (error) {
+            this.connected = false;
+            if (!this.preventRetry && this.started) {
+                this.scheduleReconnect();
+            }
+            this.logger.warn('socket open failed', { message: (0, primitives_1.toError)(error).message });
+        }
+    }
+    async onSocketClosed(info) {
+        this.connected = false;
+        this.noiseSession?.onSocketClosed(new Error(`socket closed (${info.code}:${info.reason})`));
+        this.noiseSession = null;
+        this.clearPendingFrames();
+        this.pendingFramesOverflowClosing = false;
+        if (!this.started || this.preventRetry) {
+            this.logger.trace('comms socket close ignored for reconnect', {
+                started: this.started,
+                preventRetry: this.preventRetry
+            });
+            return;
+        }
+        if (this.resumeInFlight) {
+            this.logger.trace('comms socket close while resume in-flight');
+            return;
+        }
+        this.scheduleReconnect();
+        this.logger.info('socket closed, scheduling reconnect', {
+            code: info.code,
+            reason: info.reason,
+            reconnectAfterMs: this.config.reconnectIntervalMs
+        });
+    }
+    onSocketMessage(payload) {
+        this.frameProcessingQueue = this.frameProcessingQueue
+            .catch(() => undefined)
+            .then(async () => this.processSocketPayload(payload));
+    }
+    async processSocketPayload(payload) {
+        if (!this.noiseSession) {
+            this.logger.warn('received socket payload before noise session init');
+            return;
+        }
+        try {
+            const frames = await this.noiseSession.pushWireChunk(payload);
+            this.routeDecodedFrames(frames);
+        }
+        catch (error) {
+            const normalized = (0, primitives_1.toError)(error);
+            this.logger.error('failed to decode noise frame', { message: normalized.message });
+            if (!this.started || this.preventRetry || this.resumeInFlight) {
+                return;
+            }
+            this.logger.warn('resuming socket after noise decode failure');
+            void this.closeSocketAndResume().catch((resumeError) => {
+                this.logger.warn('failed to resume socket after noise decode failure', {
+                    message: (0, primitives_1.toError)(resumeError).message
+                });
+            });
+        }
+    }
+    async onDecodedFrame(payload) {
+        if (!this.stanzaHandler) {
+            return;
+        }
+        if (!this.handlingRequests) {
+            this.logger.trace('comms frame queued until request handling starts', {
+                byteLength: payload.byteLength
+            });
+            this.tryQueuePendingFrames([payload], 'decoded_frame');
+            return;
+        }
+        try {
+            const frame = this.inflateFrame ? await this.inflateFrame(payload) : payload;
+            await this.stanzaHandler(frame);
+        }
+        catch (error) {
+            this.logger.error('failed to handle incoming frame', {
+                message: (0, primitives_1.toError)(error).message
+            });
+        }
+    }
+    async onSocketOpened() {
+        this.logger.debug('comms socket opened, starting noise session');
+        const noiseConfig = this.buildNoiseConfigForAttempt();
+        const session = new WaNoiseSession_1.WaNoiseSession(async (wire) => this.socket.send(wire), this.logger);
+        this.noiseSession = session;
+        try {
+            await session.start(noiseConfig);
+        }
+        catch (error) {
+            if (this.usedResumeHandshake) {
+                this.resumeHandshakeFailures += 1;
+                this.logger.warn('noise resume handshake failed, next attempt may fallback to full', {
+                    failures: this.resumeHandshakeFailures,
+                    threshold: constants_1.WA_DEFAULTS.NOISE_RESUME_FAILURES_BEFORE_FULL_HANDSHAKE
+                });
+            }
+            this.noiseSession = null;
+            throw error;
+        }
+        const buffered = await session.pushWireChunk(bytes_1.EMPTY_BYTES);
+        this.routeDecodedFrames(buffered);
+        this.resumeHandshakeFailures = 0;
+        this.lastServerStaticKey = session.getServerStaticKey();
+        this.connected = true;
+        this.reconnectAttempts = 0;
+        this.logger.info('comms connected and noise session established');
+        this.drainWaiters((waiter) => waiter.resolve());
+    }
+    async flushPendingFrames() {
+        if (!this.handlingRequests || !this.stanzaHandler || this.pendingFrames.length === 0) {
+            return;
+        }
+        this.logger.debug('flushing pending comms frames', { count: this.pendingFrames.length });
+        const buffered = this.pendingFrames;
+        this.pendingFrames = [];
+        this.pendingFramesByteLength = 0;
+        this.routeDecodedFrames(buffered);
+    }
+    routeDecodedFrames(frames) {
+        if (frames.length === 0) {
+            return;
+        }
+        if (!this.handlingRequests || !this.stanzaHandler) {
+            this.logger.trace('comms frame queued until request handling starts', {
+                count: frames.length
+            });
+            this.tryQueuePendingFrames(frames, 'decoded_batch');
+            return;
+        }
+        for (const frame of frames) {
+            this.scheduleDecodedFrame(frame);
+        }
+    }
+    clearPendingFrames() {
+        this.pendingFrames = [];
+        this.pendingFramesByteLength = 0;
+    }
+    tryQueuePendingFrames(frames, source) {
+        if (frames.length === 0) {
+            return true;
+        }
+        let incomingBytes = 0;
+        for (let index = 0; index < frames.length; index += 1) {
+            incomingBytes += frames[index].byteLength;
+        }
+        const nextCount = this.pendingFrames.length + frames.length;
+        const nextBytes = this.pendingFramesByteLength + incomingBytes;
+        if (nextCount > this.pendingFramesMaxCount || nextBytes > this.pendingFramesMaxBytes) {
+            this.logger.error('pending comms frame buffer overflow', {
+                source,
+                currentCount: this.pendingFrames.length,
+                currentBytes: this.pendingFramesByteLength,
+                incomingCount: frames.length,
+                incomingBytes,
+                maxCount: this.pendingFramesMaxCount,
+                maxBytes: this.pendingFramesMaxBytes
+            });
+            this.clearPendingFrames();
+            this.schedulePendingFramesOverflowClose();
+            return false;
+        }
+        this.pendingFrames.push(...frames);
+        this.pendingFramesByteLength = nextBytes;
+        return true;
+    }
+    schedulePendingFramesOverflowClose() {
+        if (this.pendingFramesOverflowClosing || this.preventRetry) {
+            return;
+        }
+        this.pendingFramesOverflowClosing = true;
+        // Pending frames are intentionally bounded to prevent unbounded memory growth.
+        void this.closeSocketAndPreventRetry()
+            .catch((error) => {
+            this.logger.warn('failed to close socket after pending frame overflow', {
+                message: (0, primitives_1.toError)(error).message
+            });
+        })
+            .finally(() => {
+            this.pendingFramesOverflowClosing = false;
+        });
+    }
+    scheduleDecodedFrame(frame) {
+        void this.frameHandlerQueue
+            .enqueue(async () => this.onDecodedFrame(frame))
+            .catch((error) => {
+            const normalized = (0, primitives_1.toError)(error);
+            this.logger.error('failed to enqueue decoded frame handler', {
+                message: normalized.message
+            });
+            if (!(error instanceof BoundedTaskQueue_1.BoundedTaskQueueFullError)) {
+                return;
+            }
+            this.logger.warn('frame handler queue is full, processing frame inline', {
+                pending: this.frameHandlerQueue.pending(),
+                inFlight: this.frameHandlerQueue.inFlight()
+            });
+            void this.onDecodedFrame(frame);
+        });
+    }
+    scheduleReconnect() {
+        if (this.reconnectTimer) {
+            this.logger.trace('reconnect already scheduled');
+            return;
+        }
+        this.logger.debug('scheduling reconnect timer', {
+            intervalMs: this.config.reconnectIntervalMs
+        });
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            void this.openSocket(true);
+        }, this.config.reconnectIntervalMs);
+    }
+    clearReconnectTimer() {
+        if (!this.reconnectTimer) {
+            return;
+        }
+        clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = null;
+    }
+    removeWaiter(reject) {
+        const index = this.waiters.findIndex((entry) => entry.reject === reject);
+        if (index === -1) {
+            return;
+        }
+        const [waiter] = this.waiters.splice(index, 1);
+        clearTimeout(waiter.timer);
+    }
+    withStickyRoutingCookie(headers) {
+        const out = headers ? { ...headers } : {};
+        const stickyCookie = out.Cookie ?? out.cookie ?? '';
+        delete out.cookie;
+        if (stickyCookie.includes('sticky_routing=')) {
+            return out;
+        }
+        out.Cookie = stickyCookie ? `${stickyCookie}; sticky_routing=` : 'sticky_routing=';
+        return out;
+    }
+    buildNoiseConfigForAttempt() {
+        const hasServerStaticKey = this.config.noise.serverStaticKey?.byteLength === 32;
+        if (hasServerStaticKey &&
+            this.resumeHandshakeFailures < constants_1.WA_DEFAULTS.NOISE_RESUME_FAILURES_BEFORE_FULL_HANDSHAKE) {
+            this.usedResumeHandshake = true;
+            return this.config.noise;
+        }
+        if (hasServerStaticKey) {
+            this.logger.info('noise resume temporarily disabled after previous failure(s)', {
+                failures: this.resumeHandshakeFailures
+            });
+        }
+        this.usedResumeHandshake = false;
+        return {
+            ...this.config.noise,
+            serverStaticKey: undefined
+        };
+    }
+    resetConnectionState(options) {
+        this.started = options.started;
+        this.connected = options.connected;
+        this.handlingRequests = options.handlingRequests;
+        this.preventRetry = options.preventRetry;
+        this.resumeInFlight = options.resumeInFlight;
+        if (options.resetResumeHandshakeFailures !== false) {
+            this.resumeHandshakeFailures = 0;
+        }
+        this.noiseSession = null;
+        this.clearPendingFrames();
+        this.pendingFramesOverflowClosing = false;
+        if (options.clearHandlers) {
+            this.stanzaHandler = null;
+            this.inflateFrame = null;
+        }
+        this.clearReconnectTimer();
+        if (options.rejectWaitersError) {
+            const rejectWaitersError = options.rejectWaitersError;
+            this.drainWaiters((waiter) => waiter.reject(rejectWaitersError));
+        }
+    }
+    drainWaiters(drain) {
+        const waiters = this.waiters.splice(0, this.waiters.length);
+        for (const waiter of waiters) {
+            clearTimeout(waiter.timer);
+            drain(waiter);
+        }
+    }
+}
+exports.WaComms = WaComms;