create-caspian-app 1.8.2 → 1.8.4

package/dist/src/lib/websocket/sockets.py

@@ -40,6 +40,16 @@ There is no status line inside an open connection, so failure is a frame:
 `{"error": "..."}` -- that key alone -- followed by a close. The client
 runtime routes it to `onError` rather than `onMessage`.
 
+## Liveness
+
+A quiet connection is not a dead one. The client runtime sends a heartbeat,
+`{"__pp": "ping"}`, every 25 seconds and the server answers
+`{"__pp": "pong"}`; neither frame ever reaches a handler or `onMessage`. The
+idle timeout (`WEBSOCKET_IDLE_TIMEOUT_SECONDS`) therefore only fires for a
+peer that stopped answering, and it closes with `IDLE_CLOSE_CODE` (4000)
+rather than 1000, so the client knows to reconnect. A 1000 close still means
+the handler returned: the conversation ended, and the client stays closed.
+
 ## Registration timing
 
 A `@socket()` in a route's `index.py` registers when that module is first
@@ -95,8 +105,17 @@ ARGS_TIMEOUT_SECONDS = 10
 SEND_QUEUE_SIZE = 32
 
 
+# The client runtime pings every 25 seconds, and a background tab may stretch
+# that to once a minute (Chrome's intensive timer throttling). The floor keeps
+# a misconfigured timeout from closing healthy, quiet connections in a loop.
+MIN_IDLE_TIMEOUT_SECONDS = 60
+
+
 def _idle_timeout_seconds() -> int:
-    return max(10, int(os.getenv("WEBSOCKET_IDLE_TIMEOUT_SECONDS", 120)))
+    return max(
+        MIN_IDLE_TIMEOUT_SECONDS,
+        int(os.getenv("WEBSOCKET_IDLE_TIMEOUT_SECONDS", 120)),
+    )
 
 
 def _max_message_bytes() -> int:
@@ -254,6 +273,26 @@ def socket(require_auth: bool = False, allowed_roles: list[str] | None = None):
 
 # ==== WIRE HELPERS ====
 
+# Close code for a connection the server dropped because nothing arrived in
+# time. It is deliberately not 1000: a normal closure means the conversation
+# ended (the handler returned), and the client does not reconnect after one.
+# An idle close means the peer stopped answering -- the client runtime
+# reconnects after it.
+IDLE_CLOSE_CODE = 4000
+
+# The control frame key. An object whose only key is `__pp` is wire
+# housekeeping, never a message: the client runtime sends `{"__pp": "ping"}`
+# as its heartbeat and the server answers `{"__pp": "pong"}`. Neither side
+# hands a control frame to application code.
+CONTROL_KEY = "__pp"
+_PONG_FRAME = json.dumps({CONTROL_KEY: "pong"})
+
+# How many received messages may wait for a handler that is not reading yet.
+# Past this the connection is closed with an error frame rather than grown
+# without bound; the per-connection message rate already caps how fast it can
+# fill.
+RECV_QUEUE_SIZE = 64
+
 
 def _error_frame(message: str) -> str:
     """`{"error": "..."}` -- the frame shape the client routes to `onError`.
@@ -272,6 +311,28 @@ def _is_reserved_error_shape(value: Any) -> bool:
     )
 
 
+def _is_control_shape(value: Any) -> bool:
+    return isinstance(value, dict) and set(value.keys()) == {CONTROL_KEY}
+
+
+def _control_of(text: str) -> str | None:
+    """The control verb of a heartbeat frame, or None for an ordinary one.
+
+    Cheap substring gate first: nearly every frame is application data, and
+    those never pay for a second JSON parse.
+    """
+    if CONTROL_KEY not in text:
+        return None
+    try:
+        value = json.loads(text)
+    except json.JSONDecodeError:
+        return None
+    if not _is_control_shape(value):
+        return None
+    verb = value[CONTROL_KEY]
+    return verb if isinstance(verb, str) else ""
+
+
 class _MessageRate:
     """Sliding-window receive budget for one connection.
 
@@ -305,6 +366,11 @@ class _Shared:
         self.outgoing: asyncio.Queue[str | None] = asyncio.Queue(maxsize=SEND_QUEUE_SIZE)
         self.closed = False
         self.last_activity = time.monotonic()
+        # The code the writer closes with once it drains. 1000 unless the
+        # server is ending the connection for a reason the client should act
+        # on (see IDLE_CLOSE_CODE).
+        self.close_code = status.WS_1000_NORMAL_CLOSURE
+        self.close_reason: str | None = None
 
 
 class SocketSender:
@@ -334,6 +400,11 @@ class SocketSender:
                 'The frame shape {"error": "..."} is reserved for failures. '
                 "Wrap the value or rename the key."
             )
+        if _is_control_shape(serialized):
+            raise ValueError(
+                'The frame shape {"__pp": ...} is reserved for the wire\'s '
+                "heartbeat. Wrap the value or rename the key."
+            )
         try:
             frame = json.dumps(serialized)
         except (TypeError, ValueError) as e:
@@ -391,6 +462,13 @@ class Socket:
     another task or a [`SocketPool`] may hold, which is how a chat room
     reaches the people in it.
 
+    Two tasks own the wire. The writer is the only task that sends, so cloned
+    senders on other tasks never interleave partial sends. The reader is the
+    only task that receives, and it keeps reading whether or not the handler
+    is: that is what lets the heartbeat be answered, the idle timeout be
+    enforced, and a disconnect be noticed by a handler that only ever sends
+    (a notification feed awaiting `socket.wait_closed()`).
+
     When the handler returns, the connection closes: a handler that returns
     is a conversation that ends.
     """
@@ -401,9 +479,11 @@ class Socket:
         self._shared = _Shared()
         self._sender = SocketSender(self._shared)
         self._rate = _MessageRate(_messages_per_window(), _rate_window_seconds())
-        # One task owns the write side of the wire, so cloned senders on other
-        # tasks never interleave partial sends.
+        self._incoming: asyncio.Queue[str | None] = asyncio.Queue(maxsize=RECV_QUEUE_SIZE)
+        self._incoming_done = False
+        self._peer_gone = asyncio.Event()
         self._writer = asyncio.create_task(self._pump_outgoing())
+        self._reader = asyncio.create_task(self._pump_incoming())
 
     async def _pump_outgoing(self) -> None:
         try:
@@ -418,11 +498,85 @@ class Socket:
             pass
         finally:
             self._shared.closed = True
+            self._peer_gone.set()
             try:
-                await self._websocket.close(code=status.WS_1000_NORMAL_CLOSURE)
+                await self._websocket.close(
+                    code=self._shared.close_code, reason=self._shared.close_reason
+                )
             except Exception:
                 pass
 
+    async def _pump_incoming(self) -> None:
+        """Read every frame for as long as the connection lives.
+
+        Heartbeats are answered here and never reach the handler. Application
+        frames are checked against the size and rate limits and queued for
+        `recv`. The idle timeout counts traffic in both directions -- a
+        passive listener in an active room is not idle, it is listening --
+        and closes with IDLE_CLOSE_CODE so the client knows to reconnect.
+        """
+        idle_timeout = _idle_timeout_seconds()
+        try:
+            while not self._shared.closed:
+                # Wait only for what is left of the idle window. Waiting a
+                # full window each time let a connection with any outbound
+                # traffic shortly after its last receive survive almost two
+                # windows before the check could fire.
+                remaining = idle_timeout - (time.monotonic() - self._shared.last_activity)
+                if remaining <= 0:
+                    self._shared.close_code = IDLE_CLOSE_CODE
+                    self._shared.close_reason = "idle timeout"
+                    await self._shared.outgoing.put(None)
+                    return
+                try:
+                    text = await asyncio.wait_for(self._websocket.receive_text(), timeout=remaining)
+                except asyncio.TimeoutError:
+                    continue
+                except Exception:
+                    # Disconnect, or receive after close: the peer is gone.
+                    # The write side finds out on its next send.
+                    return
+
+                self._shared.last_activity = time.monotonic()
+
+                if len(text.encode("utf-8")) > _max_message_bytes():
+                    await self._close_with(status.WS_1009_MESSAGE_TOO_BIG)
+                    return
+
+                verb = _control_of(text)
+                if verb is not None:
+                    # Unknown verbs are ignored rather than refused, so a
+                    # newer client never breaks an older server.
+                    if verb == "ping" and not self._shared.closed:
+                        await self._shared.outgoing.put(_PONG_FRAME)
+                    continue
+
+                if not self._rate.allow():
+                    await self._sender._error("Too many messages. Slow down.")
+                    return
+                try:
+                    self._incoming.put_nowait(text)
+                except asyncio.QueueFull:
+                    await self._sender._error(
+                        f"`{self._name}` is not reading its messages. The "
+                        "handler must call socket.recv() to receive them."
+                    )
+                    return
+        finally:
+            self._peer_gone.set()
+            self._end_incoming()
+
+    def _end_incoming(self) -> None:
+        """Queue the end-of-conversation marker `recv` answers None for."""
+        while True:
+            try:
+                self._incoming.put_nowait(None)
+                return
+            except asyncio.QueueFull:
+                # A full queue of unread frames the handler will never get to:
+                # the conversation is over, so the end marker takes priority.
+                self._incoming.get_nowait()
+
     async def send(self, value: Any) -> bool:
         """Send one JSON value. False means the browser is gone."""
         return await self._sender.send(value)
@@ -450,36 +604,31 @@ class Socket:
         """The next frame as it arrived, for a handler that would rather
         parse it itself. None is the connection closing.
 
-        Enforces the shared limits: an oversized frame closes with 1009, a
-        flooding connection closes with 1008, and a connection idle in both
-        directions past the timeout closes with 1000.
+        The shared limits are enforced by the reader before a frame gets
+        here: an oversized frame closes with 1009, a flooding connection gets
+        an error frame, and a connection idle in both directions past the
+        timeout closes with IDLE_CLOSE_CODE. Heartbeat frames never arrive.
         """
-        idle_timeout = _idle_timeout_seconds()
-        while not self._shared.closed:
+        if self._incoming_done:
+            return None
+        text = await self._incoming.get()
+        if text is None:
+            self._incoming_done = True
+        return text
+
+    async def wait_closed(self) -> None:
+        """Wait until the browser is gone or the connection closed.
+
+        For a handler that only sends -- a notification feed that parks its
+        sender in a pool -- and so has no `recv` loop to end on:
+
+            pool.add(socket.sender())
             try:
-                text = await asyncio.wait_for(self._websocket.receive_text(), timeout=idle_timeout)
-            except asyncio.TimeoutError:
-                # Outbound traffic counts as liveness: a passive listener in
-                # an active room is not idle, it is listening.
-                if time.monotonic() - self._shared.last_activity >= idle_timeout:
-                    await self.close()
-                    return None
-                continue
-            except Exception:
-                # Disconnect, or receive after close: the conversation ended.
-                self._shared.closed = True
-                return None
-
-            self._shared.last_activity = time.monotonic()
-
-            if len(text.encode("utf-8")) > _max_message_bytes():
-                await self._close_with(status.WS_1009_MESSAGE_TOO_BIG)
-                return None
-            if not self._rate.allow():
-                await self._sender._error("Too many messages. Slow down.")
-                return None
-            return text
-        return None
+                await socket.wait_closed()
+            finally:
+                pool.discard(socket.sender())
+        """
+        await self._peer_gone.wait()
 
     def sender(self) -> SocketSender:
         """A sending handle another task, or a [`SocketPool`], may hold."""
@@ -498,6 +647,7 @@ class Socket:
 
     async def _close_with(self, code: int) -> None:
         self._shared.closed = True
+        self._peer_gone.set()
         self._writer.cancel()
         try:
             await self._websocket.close(code=code)
@@ -505,12 +655,18 @@ class Socket:
             pass
 
     async def _finish(self) -> None:
-        """Let queued frames drain, then reclaim the writer task."""
+        """Let queued frames drain, then reclaim both pump tasks."""
         try:
             await asyncio.wait_for(self._writer, timeout=5)
         except asyncio.CancelledError, Exception:
             self._writer.cancel()
         self._shared.closed = True
+        if self._reader is not asyncio.current_task() and not self._reader.done():
+            self._reader.cancel()
+            try:
+                await self._reader
+            except asyncio.CancelledError, Exception:
+                pass
 
 
 # ==== ENDPOINT ====

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-caspian-app",
-  "version": "1.8.2",
+  "version": "1.8.4",
   "description": "Scaffold a new Caspian project (FastAPI-powered reactive Python framework).",
   "main": "dist/index.js",
   "type": "module",