@fishenv/http 0.0.3 → 0.0.4

package/dist/ws/channels/handler.d.ts

@@ -7,6 +7,12 @@
  *   leave order holds); different sockets run concurrently
  * - nothing reaches a handler before the channel is joined and the payload
  *   validated against the contract
+ * - a joining socket is a room member from the moment its join handler
+ *   starts: channel events sent meanwhile (broadcasts, `push`) are queued and
+ *   delivered right after the join reply, so a snapshot returned by the
+ *   handler plus the events that follow never leave a gap. Events sent while
+ *   the handler runs may also be in its snapshot; dedupe on the client (a
+ *   sequence number in the payload) if that matters
  * - repeated protocol violations close the socket with `1008`
  */
 import { WsHub } from "../hub.ts";
@@ -19,6 +25,11 @@ export interface ChannelsOptions {
     maxViolations?: number;
     /** Frames queued behind a slow handler before closing with `1013`. Default 64. */
     maxPendingFrames?: number;
+    /**
+     * Channel events queued for a socket while its join handler runs. Default
+     * 1024. Exceeding it fails the join with `503 join_overflow`.
+     */
+    maxJoinBufferedFrames?: number;
     /**
      * Hub that backs channel membership — pass an instance or a DI token to
      * reach channels from server code via `hub.channel(name)`. A private hub is

package/dist/ws/channels/handler.js

@@ -7,6 +7,12 @@
  *   leave order holds); different sockets run concurrently
  * - nothing reaches a handler before the channel is joined and the payload
  *   validated against the contract
+ * - a joining socket is a room member from the moment its join handler
+ *   starts: channel events sent meanwhile (broadcasts, `push`) are queued and
+ *   delivered right after the join reply, so a snapshot returned by the
+ *   handler plus the events that follow never leave a gap. Events sent while
+ *   the handler runs may also be in its snapshot; dedupe on the client (a
+ *   sequence number in the payload) if that matters
  * - repeated protocol violations close the socket with `1008`
  */
 import * as v from "valibot";
@@ -21,6 +27,7 @@ const DEFAULTS = {
     maxChannelsPerSocket: 32,
     maxViolations: 10,
     maxPendingFrames: 64,
+    maxJoinBufferedFrames: 1024,
 };
 /** Errors for rejected frames, mapped onto the HTTP error vocabulary. */
 class ChannelError extends HttpError {
@@ -202,23 +209,43 @@ class ChannelSession {
         const data = parsePayload(contract.join.payload, frame.d);
         const context = this.#context(def, frame.ch);
         const args = { ...this.#base(path), data, channel: context };
-        const reply = def.join ? await def.join(args) : undefined;
-        checkOutbound(contract.join.reply, reply, this.#env.development, `join reply of "${frame.ch}"`);
-        // Resolve presence before committing, so a failing tracker aborts the join.
+        const room = channelRoom(frame.ch);
         const presence = contract.presence;
-        const tracked = presence != null && def.presence != null
-            ? (await def.presence(args))
-            : null;
-        if (tracked != null) {
-            checkOutbound(presence?.meta, tracked.meta, this.#env.development, `presence meta of "${frame.ch}"`);
+        // Member (held) before the handler runs, so nothing sent meanwhile is lost.
+        const held = this.#hub._hold(this.#socket, room, this.#opts.maxJoinBufferedFrames);
+        let reply;
+        let tracked = null;
+        try {
+            reply = def.join ? await def.join(args) : undefined;
+            checkOutbound(contract.join.reply, reply, this.#env.development, `join reply of "${frame.ch}"`);
+            // Resolve presence before committing, so a failing tracker aborts the join.
+            if (presence != null && def.presence != null) {
+                tracked = (await def.presence(args));
+            }
+            if (tracked != null) {
+                checkOutbound(presence?.meta, tracked.meta, this.#env.development, `presence meta of "${frame.ch}"`);
+            }
+        }
+        catch (err) {
+            if (held)
+                this.#hub.leave(this.#socket, room);
+            throw err;
         }
         if (this.#socket.closed)
             return;
-        const room = channelRoom(frame.ch);
-        this.#hub.join(this.#socket, room);
+        // Not held: the app already put the socket in the room through the hub.
+        const queued = held ? this.#hub._release(this.#socket, room) : [];
+        if (queued === null) {
+            throw new ChannelError(409, "join_aborted", "Removed from the channel while joining", false);
+        }
+        if (queued === "overflow") {
+            throw new ChannelError(503, "join_overflow", "Too many channel events while joining", false);
+        }
         this.#hub._onLeave(this.#socket, room, (reason) => this.#schedule(() => this.#serverLeave(frame.ch, "kicked", reason)));
         this.#joined.set(frame.ch, { impl: def, name: frame.ch, path, context });
         this.#reply(frame.ref, reply);
+        for (const queuedFrame of queued)
+            this.#socket.send(queuedFrame);
         if (presence != null) {
             const registry = presenceFor(this.#hub);
             if (tracked != null) {
@@ -392,7 +419,11 @@ class ChannelSession {
             },
             push: (event, payload) => {
                 check(event, payload);
-                return this.#socket.send(eventFrame(name, event, payload));
+                const frame = eventFrame(name, event, payload);
+                // From a join handler: queued behind the join reply.
+                if (this.#hub._holdFrame(this.#socket, room, frame))
+                    return "sent";
+                return this.#socket.send(frame);
             },
             leave: (reason = "") => {
                 this.#schedule(() => this.#serverLeave(name, "server", reason));

package/dist/ws/hub.d.ts

@@ -116,6 +116,24 @@ export declare class WsHub {
     join(socket: WsConnection, room: string): void;
     /** Remove a socket from a room. Does *not* run leave hooks. */
     leave(socket: WsConnection, room: string): void;
+    /**
+     * @internal Make a socket a member of `room` whose frames for the room are
+     * queued instead of sent, until {@link _release}. Channels use this while a
+     * join handler runs, so nothing broadcast meanwhile is missed and nothing
+     * arrives before the join reply. Past `limit` queued frames the hold is
+     * marked overflowed (further frames are dropped). `false` when nothing is
+     * held: the socket is closed or already a (normal) member.
+     */
+    _hold(socket: WsConnection, room: string, limit: number): boolean;
+    /**
+     * @internal End a hold: subscribe the socket normally and return the queued
+     * frames, oldest first, for the caller to send. `null` when the socket is no
+     * longer held (it left, was kicked or closed); `"overflow"` when the queue
+     * overflowed, in which case the socket also leaves the room.
+     */
+    _release(socket: WsConnection, room: string): Frame[] | "overflow" | null;
+    /** @internal Queue `frame` if `socket` is held in `room`; `false` otherwise. */
+    _holdFrame(socket: WsConnection, room: string, frame: Frame): boolean;
     /** Rooms a socket is in. */
     rooms(socket: WsConnection): string[];
     /** Every room with at least one local member. */

package/dist/ws/hub.js

@@ -114,6 +114,8 @@ export class WsHub {
     #roomsOf = new Map();
     #tracked = new Set();
     #leaveHooks = new Map();
+    /** Members whose room frames are queued until `_release` (pending joins). */
+    #held = new Map();
     #extensions = new Map();
     #bridge;
     #replicated;
@@ -161,29 +163,14 @@ export class WsHub {
     // ── Rooms ───────────────────────────────────────────────────────────
     /** Put a socket in a room (idempotent). Server-side only. */
     join(socket, room) {
-        if (socket.closed)
-            return;
-        let members = this.#rooms.get(room);
-        if (members == null) {
-            members = new Set();
-            this.#rooms.set(room, members);
-        }
-        if (members.has(socket))
-            return;
-        members.add(socket);
-        let rooms = this.#roomsOf.get(socket);
-        if (rooms == null) {
-            rooms = new Set();
-            this.#roomsOf.set(socket, rooms);
-        }
-        rooms.add(room);
-        if (serverOf(socket) != null)
+        if (this.#addMember(socket, room) && serverOf(socket) != null) {
             socket.raw.subscribe(this.#topic(room));
-        this.#track(socket);
+        }
     }
     /** Remove a socket from a room. Does *not* run leave hooks. */
     leave(socket, room) {
         this.#leaveHooks.get(socket)?.delete(room);
+        this.#unhold(socket, room);
         const members = this.#rooms.get(room);
         if (members == null || !members.delete(socket))
             return;
@@ -197,6 +184,86 @@ export class WsHub {
             socket.raw.unsubscribe(this.#topic(room));
         }
     }
+    /**
+     * @internal Make a socket a member of `room` whose frames for the room are
+     * queued instead of sent, until {@link _release}. Channels use this while a
+     * join handler runs, so nothing broadcast meanwhile is missed and nothing
+     * arrives before the join reply. Past `limit` queued frames the hold is
+     * marked overflowed (further frames are dropped). `false` when nothing is
+     * held: the socket is closed or already a (normal) member.
+     */
+    _hold(socket, room, limit) {
+        if (!this.#addMember(socket, room))
+            return false;
+        let held = this.#held.get(socket);
+        if (held == null) {
+            held = new Map();
+            this.#held.set(socket, held);
+        }
+        held.set(room, { frames: [], limit, overflowed: false });
+        return true;
+    }
+    /**
+     * @internal End a hold: subscribe the socket normally and return the queued
+     * frames, oldest first, for the caller to send. `null` when the socket is no
+     * longer held (it left, was kicked or closed); `"overflow"` when the queue
+     * overflowed, in which case the socket also leaves the room.
+     */
+    _release(socket, room) {
+        const held = this.#held.get(socket)?.get(room);
+        if (held == null)
+            return null;
+        this.#unhold(socket, room);
+        if (held.overflowed) {
+            this.leave(socket, room);
+            return "overflow";
+        }
+        if (serverOf(socket) != null)
+            socket.raw.subscribe(this.#topic(room));
+        return held.frames;
+    }
+    /** @internal Queue `frame` if `socket` is held in `room`; `false` otherwise. */
+    _holdFrame(socket, room, frame) {
+        const held = this.#held.get(socket)?.get(room);
+        if (held == null)
+            return false;
+        if (held.overflowed)
+            return true;
+        if (held.frames.length >= held.limit) {
+            held.overflowed = true;
+            held.frames = [];
+        }
+        else {
+            held.frames.push(frame);
+        }
+        return true;
+    }
+    /** `true` when the socket was added (not closed, not already a member). */
+    #addMember(socket, room) {
+        if (socket.closed)
+            return false;
+        let members = this.#rooms.get(room);
+        if (members == null) {
+            members = new Set();
+            this.#rooms.set(room, members);
+        }
+        if (members.has(socket))
+            return false;
+        members.add(socket);
+        let rooms = this.#roomsOf.get(socket);
+        if (rooms == null) {
+            rooms = new Set();
+            this.#roomsOf.set(socket, rooms);
+        }
+        rooms.add(room);
+        this.#track(socket);
+        return true;
+    }
+    #unhold(socket, room) {
+        const held = this.#held.get(socket);
+        if (held?.delete(room) && held.size === 0)
+            this.#held.delete(socket);
+    }
     /** Rooms a socket is in. */
     rooms(socket) {
         return [...(this.#roomsOf.get(socket) ?? [])];
@@ -330,6 +397,10 @@ export class WsHub {
             for (const socket of members) {
                 if (socket.closed)
                     continue;
+                if (this._holdFrame(socket, room, frame)) {
+                    delivered++;
+                    continue;
+                }
                 const server = serverOf(socket);
                 if (server == null) {
                     if (isDelivered(socket.send(frame)))
@@ -348,7 +419,9 @@ export class WsHub {
         for (const socket of [...members]) {
             if (!this.#matches(socket, filter))
                 continue;
-            if (isDelivered(socket.send(frame)))
+            if (this._holdFrame(socket, room, frame))
+                delivered++;
+            else if (isDelivered(socket.send(frame)))
                 delivered++;
         }
         return delivered;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fishenv/http",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Type-safe HTTP router for Bun with valibot validation, contracts and Server-Sent Events.",
   "license": "AGPL-3.0-only",
   "type": "module",