feat(realtime): add ping/pong heartbeat and watchdog reconnect

- support ping incoming event and pong outgoing response
- add web heartbeat interval to keep ws alive
- add stale-connection watchdog to force reconnect on missing pong

app/realtime/router.py

@@ -40,6 +40,15 @@ async def websocket_gateway(websocket: WebSocket) -> None:
                 raw_data = await websocket.receive_json()
                 try:
                     event = IncomingRealtimeEvent.model_validate(raw_data)
+                    if event.event == "ping":
+                        await websocket.send_json(
+                            OutgoingRealtimeEvent(
+                                event="pong",
+                                payload={},
+                                timestamp=datetime.now(timezone.utc),
+                            ).model_dump(mode="json")
+                        )
+                        continue
                     await _dispatch_event(db, user.id, event)
                 except ValidationError:
                     await websocket.send_json(

app/realtime/schemas.py

@@ -17,6 +17,7 @@ RealtimeEventName = Literal[
     "message_delivered",
     "user_online",
     "user_offline",
+    "pong",
     "error",
 ]
 
@@ -40,7 +41,7 @@ class MessageStatusPayload(BaseModel):
 
 
 class IncomingRealtimeEvent(BaseModel):
-    event: Literal["send_message", "typing_start", "typing_stop", "message_read", "message_delivered"]
+    event: Literal["send_message", "typing_start", "typing_stop", "message_read", "message_delivered", "ping"]
     payload: dict[str, Any]