Scott.Idem/OSIT-AE-API-FastAPI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Scott Idem
2026-01-30 18:11:23 -05:00
parent 192a5d76b5
commit b89264fe19
2 changed files with 38 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
documentation/GUIDE__V3_FRONTEND_WEBSOCKETS.md
View File

@@ -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/...`):

14
tests/README.md
View File

@@ -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.
5. **Commit Often**: Don't forget to commit your working code and tests before moving on to the next task!
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. **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.