reachlo 1.2.1 → 1.3.0

package/index.js

@@ -6,13 +6,58 @@ class Reachlo {
         this.socket = null;
         this.channels = new Map();
         this.pendingSubs = new Set();
+        this.offlineBuffer = []; // Buffer for publish events when disconnected
 
-        // Resilience state
-        this.heartbeatInterval = options.heartbeatInterval || 20000; // 20s default
-        this.reconnectInterval = options.reconnectInterval || 3000;   // 3s default
+        // Options
+        this.bufferPublish = options.bufferPublish ?? false; // Drop by default for AI
+        this.heartbeatInterval = options.heartbeatInterval || 20000;
+        this.reconnectInterval = options.reconnectInterval || 3000;
+
+        // State
         this.heartbeatTimer = null;
         this.reconnectTimer = null;
         this.shouldReconnect = true;
+        this.lastPong = Date.now();
+        this.reconnecting = false; // Prevent duplicate events
+
+        // Protocol v2 State
+        this.msgId = 0;
+        this.ackPending = new Map(); // id -> { resolve, reject, timeout }
+
+        // Lifecycle Listeners
+        this.listeners = {
+            connect: new Set(),
+            disconnect: new Set(),
+            reconnecting: new Set(),
+            error: new Set()
+        };
+    }
+
+    /**
+     * Register lifecycle event listener
+     * @param {string} event - 'connect' | 'disconnect' | 'reconnecting'
+     * @param {function} cb 
+     */
+    on(event, cb) {
+        if (this.listeners[event]) {
+            this.listeners[event].add(cb);
+        }
+        return () => this.off(event, cb);
+    }
+
+    off(event, cb) {
+        if (this.listeners[event]) {
+            this.listeners[event].delete(cb);
+        }
+    }
+
+    _emitLifecycle(event) {
+        if (this.listeners[event]) {
+            this.listeners[event].forEach(cb => {
+                // Wrap in microtasks to prevent blocking
+                queueMicrotask(() => cb());
+            });
+        }
     }
 
     connect() {
@@ -20,26 +65,63 @@ class Reachlo {
         return new Promise((resolve, reject) => {
             if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
 
-            const urlWithAuth = `${this.url}?api_key=${this.apiKey}`;
-            this.socket = new WebSocket(urlWithAuth);
+            // Auth via Subprotocol (Preferred)
+            // Fallback to query param if needed (can be toggled via options if we want strict mode)
+            // For v1.1 we try protocol first.
+            let protocols = ['reachlo', this.apiKey];
+
+            // Note: Some browsers/proxies dislike spaces in protocols. 
+            // We pass array to WebSocket constructor which handles formatting.
+            this.socket = new WebSocket(this.url, protocols);
 
             this.socket.onopen = () => {
                 console.log("Reachlo: Connected");
+                this.reconnecting = false;
+                this.lastPong = Date.now();
                 this._startHeartbeat();
+                this._emitLifecycle('connect');
 
                 // Resubscribe active channels + flush pending
                 const toSubscribe = new Set([...this.channels.keys(), ...this.pendingSubs]);
-                toSubscribe.forEach(channel =>
-                    this._send({ type: 'subscribe', channel })
-                );
+                toSubscribe.forEach(channelName => {
+                    const channel = this.channels.get(channelName);
+                    // Pass capabilities if available (if it was already created)
+                    // If it was just pendingSub (no channel obj yet? Wait, pendingSub is only added if channel obj created)
+                    // Yes, logic: create Channel obj -> if socket open send, else add to pending.
+                    // So channel obj always exists when using pendingSubs for resubscribe
+                    const options = channel ? channel.options : {};
+                    this._send({ type: 'subscribe', channel: channelName, options: options });
+                });
                 this.pendingSubs.clear();
+
+                // Flush Offline Buffer (if enabled)
+                if (this.bufferPublish && this.offlineBuffer.length > 0) {
+                    const toFlush = [...this.offlineBuffer];
+                    this.offlineBuffer = [];
+                    toFlush.forEach(msg => this._send(msg));
+                }
+
                 resolve();
             };
 
             this.socket.onclose = () => {
                 console.log("Reachlo: Connection closed");
                 this._stopHeartbeat();
+
+                // SDK Review Fix: ACK Memory Leak Protection
+                this.ackPending.forEach(({ reject, timeout }) => {
+                    clearTimeout(timeout);
+                    reject(new Error('Disconnected'));
+                });
+                this.ackPending.clear();
+
+                this._emitLifecycle('disconnect');
+
                 if (this.shouldReconnect) {
+                    if (!this.reconnecting) {
+                        this.reconnecting = true;
+                        this._emitLifecycle('reconnecting');
+                    }
                     console.log(`Reachlo: Retrying in ${this.reconnectInterval / 1000}s...`);
                     this.reconnectTimer = setTimeout(() => this.connect(), this.reconnectInterval);
                 }
@@ -47,17 +129,38 @@ class Reachlo {
 
             this.socket.onerror = (err) => {
                 console.error("Reachlo: Socket error", err);
-                // Reject only if first attempt, otherwise let onclose handle reconnect
-                if (this.socket.readyState !== 1) reject(err);
+                if (this.socket.readyState !== 1 && !this.reconnecting) reject(err);
             };
 
             this.socket.onmessage = (event) => {
                 try {
                     const payload = JSON.parse(event.data);
-                    if (payload.type === 'pong') return; // Heartbeat response
+                    if (payload.type === 'pong') {
+                        this.lastPong = Date.now();
+                        return;
+                    }
 
-                    if (payload.channel && this.channels.has(payload.channel)) {
-                        this.channels.get(payload.channel)._emit(payload.data);
+                    if (payload.type === 'ack') {
+                        const pending = this.ackPending.get(payload.id);
+                        if (pending) {
+                            pending.resolve();
+                            clearTimeout(pending.timeout);
+                            this.ackPending.delete(payload.id);
+                        }
+                        return;
+                    }
+
+                    const channelObj = this.channels.get(payload.channel);
+                    if (channelObj) {
+                        if (payload.type === 'publish') {
+                            channelObj._emit(payload.data);
+                        } else if (payload.type === 'backpressure') {
+                            channelObj._emitEvent('backpressure', payload);
+                        } else if (payload.type === 'join') {
+                            channelObj._emitEvent('join', payload);
+                        } else if (payload.type === 'leave') {
+                            channelObj._emitEvent('leave', payload);
+                        }
                     }
                 } catch (e) {
                     console.error("Reachlo: Message parse error", e);
@@ -69,7 +172,14 @@ class Reachlo {
     _startHeartbeat() {
         this._stopHeartbeat();
         this.heartbeatTimer = setInterval(() => {
+            // Heartbeat Logic: Send Ping
             this._send({ type: 'ping' });
+
+            // Detect Half-Open: If Pong expired
+            if (Date.now() - this.lastPong > (this.heartbeatInterval * 2)) {
+                console.warn("Reachlo: Heartbeat timeout. Simulating disconnect.");
+                if (this.socket) this.socket.close(); // Triggers onclose -> reconnect
+            }
         }, this.heartbeatInterval);
     }
 
@@ -83,22 +193,22 @@ class Reachlo {
         if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
         this._stopHeartbeat();
 
+
         if (this.socket) {
             this.socket.close();
             this.socket = null;
         }
-        // NOTE: We keep this.channels so we can resubscribe on manual reconnect
-        // but we clear pendingSubs because we're explicitly stopping.
         this.pendingSubs.clear();
+        this.offlineBuffer = [];
     }
 
-    channel(channelName) {
+    channel(channelName, options = {}) {
         if (!this.channels.has(channelName)) {
-            const channel = new ReachloChannel(channelName, this);
+            const channel = new ReachloChannel(channelName, this, options);
             this.channels.set(channelName, channel);
 
             if (this.socket?.readyState === 1) { // WebSocket.OPEN is 1
-                this._send({ type: 'subscribe', channel: channelName });
+                this._send({ type: 'subscribe', channel: channelName, options: options });
             } else {
                 this.pendingSubs.add(channelName);
             }
@@ -108,17 +218,30 @@ class Reachlo {
     }
 
     _send(payload) {
-        if (this.socket && this.socket.readyState === 1) { // WebSocket.OPEN
+        if (this.socket && this.socket.readyState === 1) {
             this.socket.send(JSON.stringify(payload));
+            return true;
+        } else {
+            if (this.bufferPublish && payload.type === 'publish') {
+                this.offlineBuffer.push(payload);
+                return true; // Queued
+            }
+            return false; // Dropped
         }
     }
 }
 
 class ReachloChannel {
-    constructor(name, client) {
+    constructor(name, client, options = {}) {
         this.name = name;
         this.client = client;
+        this.options = options; // { type: 'durable' | 'presence' | 'stream' }
         this.callbacks = new Set();
+        this.eventListeners = {
+            join: new Set(),
+            leave: new Set(),
+            backpressure: new Set()
+        };
     }
 
     subscribe(cb) {
@@ -126,13 +249,75 @@ class ReachloChannel {
         return () => this.callbacks.delete(cb); // unsubscribe handle
     }
 
-    publish(data) {
-        this.client._send({ type: 'publish', channel: this.name, data });
+    on(event, cb) {
+        if (this.eventListeners[event]) {
+            this.eventListeners[event].add(cb);
+        }
+        return () => this.off(event, cb);
+    }
+
+    off(event, cb) {
+        if (this.eventListeners[event]) {
+            this.eventListeners[event].delete(cb);
+        }
+    }
+
+    publish(data, options = {}) {
+        const payload = {
+            type: 'publish',
+            channel: this.name,
+            data
+        };
+
+        if (options.delivery === 'ack') {
+            payload.delivery = 'ack';
+            const id = ++this.client.msgId;
+            payload.id = id;
+
+            return new Promise((resolve, reject) => {
+                const timeoutMs = options.timeout || 5000;
+                const timeout = setTimeout(() => {
+                    this.client.ackPending.delete(id);
+                    reject(new Error('ACK timeout'));
+                }, timeoutMs);
+
+                this.client.ackPending.set(id, { resolve, reject, timeout });
+
+                const sentOrQueued = this.client._send(payload);
+                if (!sentOrQueued) {
+                    clearTimeout(timeout);
+                    this.client.ackPending.delete(id);
+                    reject(new Error('Socket not connected'));
+                }
+            });
+        }
+
+        // Fire-and-forget
+        this.client._send(payload);
+        return Promise.resolve();
+    }
+
+    sync(lastSeenId = 0) {
+        this.client._send({
+            type: 'sync',
+            channel: this.name,
+            lastSeenId
+        });
     }
 
     _emit(data) {
-        // Sends the raw data to all registered listeners for this channel
-        this.callbacks.forEach(cb => cb(data));
+        // Microtask Delivery to prevent Event Loop Blocking
+        this.callbacks.forEach(cb => {
+            queueMicrotask(() => cb(data));
+        });
+    }
+
+    _emitEvent(event, payload) {
+        if (this.eventListeners[event]) {
+            this.eventListeners[event].forEach(cb => {
+                queueMicrotask(() => cb(payload));
+            });
+        }
     }
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "reachlo",
-    "version": "1.2.1",
-    "description": "Real-time infrastructure for AI streaming.",
+    "version": "1.3.0",
+    "description": "Streaming-native real-time infrastructure. Ordered channels, durable replay, presence, backpressure, and ACK delivery.",
     "main": "index.js",
     "type": "module",
     "author": "Reachlo Team",