@entrinsik/vite-plugin-informer 2.10.0 → 2.12.0

package/src/dev-channel-shim.js

@@ -1,25 +1,32 @@
-import { CHANNEL_NAME, CHANNEL_NAME_MAX_LENGTH, DEV_CHANNEL_EVENT } from './dev-channels.js';
+import { CHANNEL_NAME, CHANNEL_NAME_MAX_LENGTH, EVENT_NAME, EVENT_NAME_MAX_LENGTH, RESERVED_EVENTS, USER_CHANNEL_PREFIX, DEV_CHANNEL_EVENT, DEV_CHANNEL_API } from './dev-channels.js';
 
 /**
- * The dev `__INFORMER__.channel(name)` mock: the App Channels client surface
- * (App API v2 §1.9) with the same synchronous name check, `on(event, fn)` →
- * `fn(payload, frame)` dispatch by `frame.event`, unsubscribe fn, `error`
- * codes (`join_refused` | `disconnected` | `not_supported`; `rate_limited`
- * never happens locally), phase-1 `send()` rejection and idempotent
- * `close()` as the origin-mode shim in html-utils.js generateChannelShim.
+ * The dev `__INFORMER__.channel(name, opts)` mock: the App Channels client
+ * surface (App API v2 §1.9) as the origin-mode shim in html-utils.js
+ * generateChannelShim implements it —
  *
- * Transport: production subscribes each channel over a nes socket minted
- * from `/_socket`. Dev has no such socket, and opening one would mean a
- * second websocket, a `ws: true` proxy and a credential the dev server
- * cannot mint. Frames instead ride Vite's own dev websocket as the custom
- * event DEV_CHANNEL_EVENT (`server.ws.send({ type: 'custom', ... })` on the
- * node side, `import.meta.hot.on(...)` here) and are filtered by channel
- * name on the page. Vite owns reconnection; a drop surfaces to every open
- * channel as `disconnected`, the way a lost nes socket does.
+ *   var ch = __INFORMER__.channel('rooms/east', { since: 12 });  // sync; throws join_refused on a bad name
+ *   ch.on('created', function (payload, frame) {});   // first handler subscribes
+ *   ch.on('connected', function (info) {});           // { replayed: n } after each (re)subscribe
+ *   ch.on('error', function (err) {});                // err.code: join_refused | rate_limited | budget_exhausted | handler_failed | disconnected | replay_gap
+ *   ch.send(event, payload).then(result);             // rejects: send_refused | rate_limited | budget_exhausted | handler_failed | disconnected
+ *   ch.close();
+ *
+ * Transport: production subscribes each channel over a nes socket; dev POSTs
+ * subscribe / unsubscribe / send to DEV_CHANNEL_API, where the matching
+ * channels/ handler runs (dev-channel-handlers.js). Frames ride Vite's own dev
+ * websocket as the custom event DEV_CHANNEL_EVENT and reach every page; a
+ * channel dispatches only once its subscribe was admitted, matching frames by
+ * exact name or, for a `rooms/*` wildcard, by the frame's wildcard parents.
+ * Every frame carries a per-channel `seq`; after a dropped socket the shim
+ * re-subscribes on `vite:ws:connect` (or the next `on()`), replays from the
+ * last seq it saw via GET /replay, drops what it already delivered, and
+ * reports `replay_gap` when the buffer no longer reaches back that far.
  *
  * Returned as source (an `installDevChannels(hot, informer)` function
  * declaration) so it can be evaluated in a test `vm` against a fake hot
- * context, the same way the server spec drives the production shim.
+ * context and a fake fetch, the same way the server spec drives the
+ * production shim.
  */
 export function generateDevChannelShim() {
     return `
@@ -27,50 +34,153 @@ export function generateDevChannelShim() {
     function installDevChannels(hot, informer, unavailableReason) {
         var CHANNEL_NAME = /${CHANNEL_NAME.source}/;
         var CHANNEL_NAME_MAX_LENGTH = ${CHANNEL_NAME_MAX_LENGTH};
+        var EVENT_NAME = /${EVENT_NAME.source}/;
+        var EVENT_NAME_MAX_LENGTH = ${EVENT_NAME_MAX_LENGTH};
+        var RESERVED_EVENTS = ${JSON.stringify(RESERVED_EVENTS)};
+        var USER_PREFIX = '${USER_CHANNEL_PREFIX}';
         var FRAME_EVENT = '${DEV_CHANNEL_EVENT}';
-        var open = [];          // channels holding at least one handler
+        var API = '${DEV_CHANNEL_API}';
+        var clientId = newClientId();   // identifies this page to the dev server
+        var open = [];                  // channels holding at least one handler
+
+        function newClientId() {
+            var c = typeof crypto !== 'undefined' ? crypto : null;
+            if (c && typeof c.randomUUID === 'function') return c.randomUUID();
+            return Math.random().toString(36).slice(2) + Date.now().toString(36);
+        }
 
-        function channelError(code, message) {
+        function channelError(code, message, channel) {
             var e = new Error(message);
             e.code = code;
+            if (channel) e.channel = channel;
             return e;
         }
 
+        function isWildcard(name) {
+            return name.indexOf(USER_PREFIX) !== 0 && name.slice(-2) === '/*';
+        }
+
+        // The wildcard names a frame on \`channel\` also belongs to: a/b/c → a/b/*, a/*.
+        function wildcardParents(channel) {
+            if (channel.indexOf(USER_PREFIX) === 0) return [];
+            var segments = channel.split('/');
+            var parents = [];
+            for (var i = segments.length - 1; i >= 1; i--) parents.push(segments.slice(0, i).join('/') + '/*');
+            return parents;
+        }
+
+        function covers(ch, frameChannel) {
+            if (ch.name === frameChannel) return true;
+            return isWildcard(ch.name) && wildcardParents(frameChannel).indexOf(ch.name) !== -1;
+        }
+
+        // A refused subscribe maps the server's status the way nes errors do.
+        // A handler that threw is its own code: 'disconnected' would make a
+        // typo in a join handler read exactly like a dropped network.
+        function mapStatus(status) {
+            if (status === 403) return 'join_refused';
+            if (status === 429) return 'rate_limited';
+            if (status === 402) return 'budget_exhausted';
+            if (status >= 400 && status < 500) return 'join_refused';
+            if (status >= 500) return 'handler_failed';
+            return 'disconnected';
+        }
+
+        function call(method, path, body) {
+            var opts = { method: method, credentials: 'same-origin', headers: {} };
+            if (body !== undefined) {
+                opts.headers['Content-Type'] = 'application/json';
+                opts.body = JSON.stringify(body);
+            }
+            return fetch(API + path, opts).then(function (res) {
+                return res.text().then(function (text) {
+                    var data = null;
+                    try { data = text ? JSON.parse(text) : null; } catch (e) { data = null; }
+                    return { ok: res.ok, status: res.status, body: data };
+                });
+            }, function (e) {
+                throw channelError('disconnected', 'The dev server could not be reached: ' + ((e && e.message) || e));
+            });
+        }
+
+        function refusal(res, channel, fallback) {
+            return channelError(mapStatus(res.status), (res.body && res.body.error) || (fallback + ' (' + res.status + ')'), channel);
+        }
+
         function deliver(frame) {
             if (!frame || typeof frame.channel !== 'string') return;
             open.slice().forEach(function (ch) {
-                if (ch.name === frame.channel) ch._deliver(frame);
+                if (covers(ch, frame.channel)) ch._deliver(frame);
             });
         }
 
+        // A dropped socket: every open channel reports it and re-subscribes on
+        // reconnect, replaying from the last seq it saw.
         function dropAll() {
             open.slice().forEach(function (ch) {
-                ch._emitError(channelError('disconnected', 'The dev server connection was lost'));
+                ch._admitted = false;
+                ch._resume = true;
+                ch._emitError(channelError('disconnected', 'The dev server connection was lost', ch.name));
             });
         }
 
+        function subscribeAll() {
+            open.slice().forEach(function (ch) { ch._subscribe(); });
+        }
+
         if (hot) {
             hot.on(FRAME_EVENT, deliver);
             hot.on('vite:ws:disconnect', dropAll);
+            hot.on('vite:ws:connect', subscribeAll);
         }
 
-        function Channel(name) {
+        function Channel(name, opts) {
             this.name = name;
-            this._handlers = {};
+            // null-prototype: an event name admits 'constructor' and 'toString',
+            // which resolve through Object.prototype on a plain object
+            this._handlers = Object.create(null);
             this._closed = false;
             this._unavailable = false;
+            this._admitted = false;
+            this._subscribing = null;   // in-flight subscribe (never rejects)
+            this._replaying = false;    // live frames queue behind an in-flight replay
+            this._pending = [];
+            this._lastSeq = Object.create(null);          // concrete channel → highest seq seen
+            this._replayedThrough = Object.create(null);  // → how far a replay caught it up
+            this._since = (opts && typeof opts.since === 'number') ? opts.since : null;
+            this._resume = this._since !== null;   // replay on the next subscribe
         }
 
-        Channel.prototype._deliver = function (frame) {
-            if (this._closed) return;
-            var list = this._handlers[frame.event];
+        Channel.prototype._dispatch = function (event, payload, frame) {
+            var list = this._handlers[event];
             if (!list) return;
             list.slice().forEach(function (fn) {
-                try { fn(frame.payload, frame); }
+                try { fn(payload, frame); }
                 catch (e) { console.error('[Informer] channel handler failed:', e); }
             });
         };
 
+        // Only a frame the replay already handed over is a duplicate. Seq is
+        // allocated atomically but published separately, so on a real server two
+        // concurrent broadcasts can arrive out of seq order; deduping against
+        // the running max would drop the lower one for good.
+        // Returns whether it was dispatched.
+        Channel.prototype._accept = function (frame) {
+            if (typeof frame.seq === 'number') {
+                if (frame.seq <= (this._replayedThrough[frame.channel] || 0)) return false;
+                if (frame.seq > (this._lastSeq[frame.channel] || 0)) this._lastSeq[frame.channel] = frame.seq;
+            }
+            this._dispatch(frame.event, frame.payload, frame);
+            return true;
+        };
+
+        // A live frame in: only once admitted, and behind any in-flight replay.
+        Channel.prototype._deliver = function (frame) {
+            if (this._closed || !this._admitted) return false;
+            if (this._replaying) { this._pending.push(frame); return false; }
+            return this._accept(frame);
+        };
+
         Channel.prototype._emitError = function (err) {
             if (this._closed) return;
             var list = this._handlers.error;
@@ -84,6 +194,89 @@ export function generateDevChannelShim() {
             });
         };
 
+        Channel.prototype._subscribe = function () {
+            var self = this;
+            if (!hot || this._closed || this._admitted || this._subscribing) return;
+            this._subscribing = call('POST', '/subscribe', { clientId: clientId, channel: this.name }).then(function (res) {
+                if (!res.ok) throw refusal(res, self.name, 'Subscribe refused');
+                if (self._closed) return 0;
+                self._admitted = true;
+                return self._replay();
+            }).then(function (replayed) {
+                self._subscribing = null;
+                if (self._closed || !self._admitted) return;
+                self._dispatch('connected', { replayed: replayed || 0 });
+            }, function (err) {
+                self._subscribing = null;
+                self._emitError(err);
+            });
+        };
+
+        // Catch up from the dev server's buffer: the concrete channels this
+        // handle has seen frames from (or itself, from \`since\` on a first
+        // subscribe). Live frames arriving meanwhile queue behind the replay so
+        // the seq dedupe sees the buffered frames first. Resolves the count delivered.
+        Channel.prototype._replay = function () {
+            var self = this;
+            var since = this._since;
+            this._since = null;
+            var targets = [];
+            if (this._resume) {
+                if (isWildcard(this.name)) targets = Object.keys(this._lastSeq);
+                else if (since !== null || this._lastSeq[this.name] !== undefined) targets = [this.name];
+            }
+            this._resume = false;
+            if (!targets.length) return Promise.resolve(0);
+            var delivered = 0;
+            this._replaying = true;
+            return targets.reduce(function (chain, concrete) {
+                return chain.then(function () {
+                    var last = self._lastSeq[concrete] || 0;
+                    if (since !== null && since > last) last = since;
+                    return call('GET', '/replay?channel=' + encodeURIComponent(concrete) + '&since=' + last).then(function (res) {
+                        if (!res.ok) throw refusal(res, concrete, 'Replay refused');
+                        var data = res.body || {};
+                        var current = typeof data.current === 'number' ? data.current : 0;
+                        var oldest = typeof data.oldest === 'number' ? data.oldest : null;
+                        if (current < last) {
+                            // the counter restarted (an idle channel's key expired,
+                            // or redis was flushed): nothing seen applies
+                            delete self._lastSeq[concrete];
+                            delete self._replayedThrough[concrete];
+                            last = 0;
+                        } else if (current > last && (oldest === null || oldest > last + 1)) {
+                            self._emitError(channelError('replay_gap', 'Frames on "' + concrete + '" after seq ' + last + ' are no longer buffered', concrete));
+                        }
+                        // the mark queued live frames dedupe against: what the
+                        // page already held, raised as the replay hands frames
+                        // over. Set before the loop, so a frame at or below
+                        // that seq is dropped rather than dispatched twice.
+                        self._replayedThrough[concrete] = last;
+                        (data.frames || []).forEach(function (frame) {
+                            if (self._closed || !frame || frame.channel !== concrete) return;
+                            if (self._accept(frame)) delivered++;
+                            if (typeof frame.seq === 'number' && frame.seq > self._replayedThrough[concrete]) self._replayedThrough[concrete] = frame.seq;
+                        });
+                    }).catch(function (err) {
+                        // a read refused for one channel (over the inbound rate,
+                        // say) is reported on that channel and must not throw
+                        // away the others, as on the server
+                        self._emitError(err && err.code ? err : channelError('disconnected', String((err && err.message) || err), concrete));
+                    });
+                });
+            }, Promise.resolve()).then(function () {
+                self._replaying = false;
+                var queued = self._pending;
+                self._pending = [];
+                queued.forEach(function (frame) { self._deliver(frame); });
+                return delivered;
+            }, function (err) {
+                self._replaying = false;
+                self._pending = [];
+                throw err;
+            });
+        };
+
         Channel.prototype.on = function (event, fn) {
             if (this._closed) throw channelError('disconnected', 'The channel is closed');
             if (typeof event !== 'string' || !event) throw new TypeError('channel.on: event name required');
@@ -91,14 +284,29 @@ export function generateDevChannelShim() {
             var list = this._handlers[event] || (this._handlers[event] = []);
             list.push(fn);
             if (open.indexOf(this) === -1) open.push(this);
-            if (!hot && !this._unavailable) {
-                // Not served by the Vite dev server: no frames can ever arrive.
-                // Reported once, asynchronously, like a failed connection.
-                this._unavailable = true;
-                var self = this;
-                Promise.resolve().then(function () {
-                    self._emitError(channelError('disconnected', unavailableReason || 'The Vite dev websocket is not available'));
-                });
+            var self = this;
+            if (!hot) {
+                if (!this._unavailable) {
+                    // Not served by the Vite dev server: no frames can ever arrive.
+                    // Reported once, asynchronously, like a failed connection.
+                    this._unavailable = true;
+                    Promise.resolve().then(function () {
+                        self._emitError(channelError('disconnected', unavailableReason || 'The Vite dev websocket is not available', self.name));
+                    });
+                }
+            } else if (this._admitted) {
+                // A late listener still learns the channel is up.
+                if (event === 'connected') {
+                    Promise.resolve().then(function () {
+                        if (self._closed || list.indexOf(fn) === -1) return;
+                        try { fn({ replayed: 0 }); }
+                        catch (e) { console.error('[Informer] channel handler failed:', e); }
+                    });
+                }
+            } else {
+                // A use: after a dropped socket, bring every open channel back
+                // before this one registers its own handlers.
+                subscribeAll();
             }
             return function () {
                 var i = list.indexOf(fn);
@@ -106,8 +314,28 @@ export function generateDevChannelShim() {
             };
         };
 
-        Channel.prototype.send = function () {
-            return Promise.reject(channelError('not_supported', 'Sending on a channel is not supported yet'));
+        Channel.prototype.send = function (event, payload) {
+            var self = this;
+            if (this._closed) return Promise.reject(channelError('disconnected', 'The channel is closed', this.name));
+            if (typeof event !== 'string' || !event || event.length > EVENT_NAME_MAX_LENGTH || !EVENT_NAME.test(event) || RESERVED_EVENTS.indexOf(event) !== -1) {
+                return Promise.reject(channelError('send_refused', 'Invalid event name: ' + event, this.name));
+            }
+            if (isWildcard(this.name)) {
+                return Promise.reject(channelError('send_refused', 'Cannot send on a wildcard channel; send to a concrete channel instead', this.name));
+            }
+            if (!hot) return Promise.reject(channelError('disconnected', unavailableReason || 'The Vite dev websocket is not available', this.name));
+            // a send right after the first on(): let the subscribe land first
+            return (this._subscribing || Promise.resolve()).then(function () {
+                return call('POST', '/send', { clientId: clientId, channel: self.name, event: event, payload: payload === undefined ? null : payload });
+            }).then(function (res) {
+                if (res.ok) return res.body ? res.body.result : null;
+                var message = (res.body && res.body.error) || ('Send refused (' + res.status + ')');
+                if (res.status === 429) throw channelError('rate_limited', message, self.name);
+                if (res.status === 402) throw channelError('budget_exhausted', message, self.name);
+                if (res.status >= 400 && res.status < 500) throw channelError('send_refused', message, self.name);
+                if (res.status >= 500) throw channelError('handler_failed', message, self.name);
+                throw channelError('disconnected', message, self.name);
+            });
         };
 
         Channel.prototype.close = function () {
@@ -115,14 +343,23 @@ export function generateDevChannelShim() {
             this._closed = true;
             var i = open.indexOf(this);
             if (i !== -1) open.splice(i, 1);
-            this._handlers = {};
+            this._handlers = Object.create(null);
+            var pending = this._subscribing;
+            var subscribed = this._admitted || pending;
+            this._admitted = false;
+            if (!hot || !subscribed) return;
+            var self = this;
+            // after an in-flight subscribe lands, so the server forgets what it just recorded
+            (pending || Promise.resolve()).then(function () {
+                return call('POST', '/unsubscribe', { clientId: clientId, channel: self.name });
+            }).catch(function () {});
         };
 
-        informer.channel = function (name) {
+        informer.channel = function (name, opts) {
             if (typeof name !== 'string' || name.length > CHANNEL_NAME_MAX_LENGTH || !CHANNEL_NAME.test(name)) {
                 throw channelError('join_refused', 'Invalid channel name: ' + name);
             }
-            return new Channel(name);
+            return new Channel(name, opts);
         };
     }`;
 }