docs(websockets): add infrastructure requirements and troubleshooting to guides

documentation/GUIDE__V3_FRONTEND_WEBSOCKETS.md

@@ -131,7 +131,32 @@ Keep the connection alive and refresh presence in the backend. Should be sent ev
 
 ---
 
-## 6. Migration Guide (V2 to V3)
+## 6. Infrastructure Requirements (Nginx)
+
+Unlike standard REST endpoints, WebSockets require explicit "Upgrade" handling in the Nginx gateway. If you are deploying to a new server, ensure the following block is present in your Nginx configuration:
+
+```nginx
+location /v3/ws {
+    proxy_pass http://fastapi_backend;
+    proxy_http_version 1.1;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+    proxy_set_header Host $http_host;
+    proxy_read_timeout 2100s; # Match your app's max heartbeat/session time
+}
+```
+
+---
+
+## 7. Common Pitfalls & Troubleshooting
+
+- **HTTP 404 Errors**: This almost always means Nginx is missing the `location /v3/ws` block and is trying to serve the request as a static file from the disk.
+- **HTTP 400 Errors**: Check your `Host` header. Nginx routes requests based on the `server_name` directive. If you connect to an IP or a non-standard hostname (like `localhost`), ensure it is explicitly listed in your Nginx config.
+- **Connection Drops**: If the connection drops exactly after 60 seconds, check your Nginx `proxy_read_timeout`. It should be set high (e.g., `2100s`) to allow for long-lived WebSocket sessions.
+
+---
+
+## 8. Migration Guide (V2 to V3)
 
 If you are upgrading from the legacy V2 WebSocket (`/ws/group/...`):
 

tests/README.md

@@ -86,5 +86,15 @@ Always run test scripts from the **project root** directory. Most scripts includ
     ```
     (Note: Restarts are NOT necessary if you are only modifying the test scripts themselves).
 3.  **Clean Up**: Clean up any temporary or debug files created during testing. However, **keep your test scripts**! Refactor them slightly for future use and clarity so they remain valuable assets for the project.
-4.  **Stay Current**: Update this `README.md` when you add new tests or learn something that could help others. This is a living document; keep the **Script Inventory** and tips up to date.
+4.  **Host Header Routing**: When testing through the Nginx gateway (port 5060), ensure your client uses a recognized Host header (e.g., `fastapi.localhost`). Nginx uses this to decide which proxy block to use.
-5.  **Commit Often**: Don't forget to commit your working code and tests before moving on to the next task!
+5.  **Stay Current**: Update this `README.md` when you add new tests or learn something that could help others. This is a living document; keep the **Script Inventory** and tips up to date.
+6.  **Commit Often**: Don't forget to commit your working code and tests before moving on to the next task!
+
+---
+
+## 🛠️ Troubleshooting Common Test Errors
+
+-   **HTTP 404 (WebSockets)**: Nginx doesn't recognize the path. Check the `location` blocks in the Nginx `.conf` files.
+-   **HTTP 400 (WebSockets)**: Usually a Host header mismatch. Nginx is hitting the default "localhost" block instead of the API proxy.
+-   **Connection Refused (Redis)**: The script is likely running on the host but trying to hit `localhost:6379` while Redis is only reachable inside the Docker network or mapped to a different port.
+-   **Hanging Scripts**: If using `TestClient` with multiple WebSockets, the script may dead-lock. Use an asynchronous library like `websockets` or `httpx` for multi-client tests.