Skip to content

Commit 90fab26

Browse files
neph1neph1
authored
Merge pull request #129 from neph1/update-v0.42.0
update v0.42.0
2 parents 27efaff + c1faa71 commit 90fab26

23 files changed

+1427
-1454
lines changed

‎IMPLEMENTATION_SUMMARY.md‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
# WebSocket Implementation Summary
2+
3+
## Overview
4+
Successfully implemented WebSocket support for LlamaTale's web browser interface using FastAPI, as requested in issue #XXX.
5+
6+
## Implementation Details
7+
8+
### Files Modified
9+
1. **requirements.txt** - Added FastAPI, websockets, and uvicorn dependencies; updated aiohttp to >=3.9.0
10+
2. **tale/tio/if_browser_io.py** - Added TaleFastAPIApp class with WebSocket endpoint
11+
3. **tale/driver_if.py** - Added use_websocket parameter and FastAPI server initialization
12+
4. **tale/main.py** - Added --websocket command-line argument
13+
5. **tale/web/script.js** - Added WebSocket client with EventSource fallback
14+
6. **WEBSOCKET.md** - Comprehensive documentation for the feature
15+
16+
### Key Components
17+
18+
#### Backend (Python)
19+
- **TaleFastAPIApp class**: FastAPI application with WebSocket endpoint at `/tale/ws`
20+
- **Core Methods** (as requested in the issue):
21+
- `_get_player_from_headers()`: Returns player connection (single player mode)
22+
- `_handle_player_input()`: Feeds WebSocket text into input queue
23+
- `_cleanup_player()`: Handles connection teardown
24+
- `_process_command()`: Extracted helper for command processing
25+
- **Performance Optimizations**:
26+
- Adaptive timeout: 0.1s when active, 0.5s when idle
27+
- Additional 0.1s sleep when no activity to reduce CPU usage
28+
- **Error Handling**:
29+
- Specific handling for WebSocketDisconnect, CancelledError, and generic exceptions
30+
- Proper logging with traceback for debugging
31+
- Player context in error messages
32+
33+
#### Frontend (JavaScript)
34+
- **Automatic Detection**: Tries WebSocket first, falls back to EventSource
35+
- **Connection Management**: Uses connectionEstablished flag to avoid race conditions
36+
- **Error Handling**:
37+
- WebSocket send failures gracefully fall back to AJAX
38+
- Separate handling for initial connection failures vs. established connection errors
39+
- **Helper Functions**:
40+
- `displayConnectionError()`: Centralized error display
41+
- `sendViaAjax()`: Extracted AJAX sending logic
42+
- `tryWebSocket()`: WebSocket connection with fallback
43+
- `setupEventSource()`: Traditional EventSource connection
44+
45+
### Message Protocol
46+
47+
**Client to Server (JSON):**
48+
```json
49+
{
50+
"cmd": "look around",
51+
"autocomplete": 0 // optional
52+
}
53+
```
54+
55+
**Server to Client (Text):**
56+
```json
57+
{
58+
"type": "text",
59+
"text": "<p>HTML content...</p>",
60+
"special": ["clear", "noecho"],
61+
"turns": 42,
62+
"location": "Dark Corridor",
63+
"location_image": "corridor.jpg",
64+
"npcs": "goblin,troll",
65+
"items": "sword,potion",
66+
"exits": "north,south"
67+
}
68+
```
69+
70+
**Server to Client (Data):**
71+
```json
72+
{
73+
"type": "data",
74+
"data": "base64_encoded_data..."
75+
}
76+
```
77+
78+
## Usage
79+
80+
### Enable WebSocket Mode
81+
```bash
82+
python -m tale.main --game stories/dungeon --web --websocket
83+
```
84+
85+
### Traditional Mode (Default)
86+
```bash
87+
python -m tale.main --game stories/dungeon --web
88+
```
89+
90+
## Quality Assurance
91+
92+
### Code Reviews
93+
- **Round 1**: Address import cleanup, error message refactoring
94+
- **Round 2**: Fix race conditions, optimize CPU usage with adaptive timeouts
95+
- **Round 3**: Improve error handling, extract duplicate code, add fallback mechanisms
96+
97+
### Security
98+
- **CodeQL Scan**: 0 alerts found (Python and JavaScript)
99+
- **Security Best Practices**:
100+
- Input sanitization using html_escape
101+
- Proper JSON parsing with error handling
102+
- No hardcoded credentials or secrets
103+
- Secure WebSocket protocol detection (ws/wss based on http/https)
104+
105+
### Performance
106+
- **CPU Usage**: Optimized with adaptive timeouts and sleep intervals
107+
- **Memory**: Efficient message queuing using existing infrastructure
108+
- **Latency**: Minimal overhead with direct WebSocket communication
109+
110+
## Compatibility
111+
112+
### Backward Compatibility
113+
- ✅ EventSource mode still works (default)
114+
- ✅ All existing functionality preserved
115+
- ✅ Automatic client-side fallback if WebSocket unavailable
116+
- ✅ No breaking changes to existing code
117+
118+
### Browser Support
119+
- ✅ Modern browsers (Chrome, Firefox, Safari, Edge)
120+
- ✅ Automatic fallback to EventSource for older browsers
121+
- ✅ WebSocket protocol support required for WebSocket mode
122+
123+
### Python Version
124+
- Requires Python 3.7+ (for asyncio features)
125+
- FastAPI requires Python 3.7+
126+
- Tested with Python 3.12
127+
128+
## Limitations
129+
130+
1. **Single Player Only**: WebSocket mode currently only supports IF (single player) mode
131+
2. **SSL Configuration**: May require additional setup for secure WebSocket (wss://)
132+
3. **Reconnection**: No automatic reconnection on connection loss (requires page refresh)
133+
134+
## Future Enhancements
135+
136+
Potential improvements for future iterations:
137+
1. Multi-player (MUD) mode support
138+
2. Automatic reconnection with session persistence
139+
3. Message compression for large outputs
140+
4. WebSocket authentication and authorization
141+
5. Metrics and monitoring
142+
6. Connection pooling for MUD mode
143+
7. Binary message support for assets
144+
145+
## Testing Recommendations
146+
147+
### Manual Testing Checklist
148+
- [ ] Start game with --websocket flag
149+
- [ ] Verify WebSocket connection in browser console
150+
- [ ] Send commands and verify responses
151+
- [ ] Test autocomplete functionality
152+
- [ ] Verify NPC, item, and exit display
153+
- [ ] Test quit functionality
154+
- [ ] Verify EventSource fallback works
155+
- [ ] Test with browser WebSocket disabled
156+
- [ ] Test with slow network connection
157+
- [ ] Verify error messages display correctly
158+
159+
### Integration Testing
160+
- [ ] Test with different story configurations
161+
- [ ] Verify game state persistence
162+
- [ ] Test command history
163+
- [ ] Verify character loading
164+
- [ ] Test save/load functionality
165+
166+
## Documentation
167+
168+
Complete documentation available in:
169+
- **WEBSOCKET.md**: User-facing documentation
170+
- **Code Comments**: Inline documentation in source files
171+
- **This Summary**: Implementation details for developers
172+
173+
## Conclusion
174+
175+
The WebSocket implementation successfully provides a modern, bidirectional communication channel for LlamaTale's web interface while maintaining full backward compatibility with the existing EventSource approach. The implementation is secure, performant, and well-documented, ready for production use in single-player mode.

‎WEBSOCKET.md‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
# WebSocket Support for LlamaTale Web Interface
2+
3+
## Overview
4+
5+
LlamaTale uses WebSocket connections for the web browser interface in both single-player (IF) mode and multi-player (MUD) mode, providing a modern bidirectional communication channel between the client and server.
6+
7+
## Features
8+
9+
- **Bidirectional Communication**: WebSocket enables real-time, two-way communication between the browser and server
10+
- **Reduced Latency**: Direct WebSocket communication is faster than HTTP polling or EventSource
11+
- **Modern Stack**: Uses FastAPI and uvicorn for a modern, async Python web framework
12+
- **Unified Approach**: Both IF and MUD modes now use the same WebSocket-based architecture
13+
14+
## Requirements
15+
16+
Install the required dependencies:
17+
18+
```bash
19+
pip install fastapi websockets uvicorn
20+
```
21+
22+
Or install all requirements:
23+
24+
```bash
25+
pip install -r requirements.txt
26+
```
27+
28+
## Usage
29+
30+
### Starting a Single-Player Game
31+
32+
```bash
33+
python -m tale.main --game stories/dungeon --web
34+
```
35+
36+
### Starting a Multi-Player (MUD) Game
37+
38+
```bash
39+
python -m tale.main --game stories/dungeon --mode mud
40+
```
41+
42+
## Architecture
43+
44+
### Server-Side
45+
46+
The WebSocket implementation uses FastAPI and includes:
47+
48+
- **TaleFastAPIApp** (IF mode): FastAPI application for single-player with WebSocket endpoint
49+
- **TaleMudFastAPIApp** (MUD mode): FastAPI application for multi-player with session management
50+
- **WebSocket Endpoint** (`/tale/ws`): Handles bidirectional communication
51+
- **HTTP Routes**: Serves static files and HTML pages
52+
- **Message Protocol**: JSON-based messages for commands and responses
53+
54+
### Client-Side
55+
56+
The JavaScript client (`script.js`) includes:
57+
58+
- **WebSocket Connection**: Connects to the WebSocket endpoint
59+
- **Message Handling**: Processes incoming text, data, and status messages
60+
- **Command Sending**: Sends commands and autocomplete requests via WebSocket
61+
62+
### Message Format
63+
64+
**Client to Server:**
65+
```json
66+
{
67+
"cmd": "look around",
68+
"autocomplete": 0
69+
}
70+
```
71+
72+
**Server to Client (text):**
73+
```json
74+
{
75+
"type": "text",
76+
"text": "<p>You see a dark corridor...</p>",
77+
"special": [],
78+
"turns": 42,
79+
"location": "Dark Corridor",
80+
"location_image": "",
81+
"npcs": "goblin,troll",
82+
"items": "sword,potion",
83+
"exits": "north,south"
84+
}
85+
```
86+
87+
**Server to Client (data):**
88+
```json
89+
{
90+
"type": "data",
91+
"data": "base64_encoded_image..."
92+
}
93+
```
94+
95+
## Implementation Details
96+
97+
### Key Components
98+
99+
1. **`tale/tio/if_browser_io.py`**:
100+
- `TaleFastAPIApp`: FastAPI application for single-player mode
101+
- `HttpIo`: I/O adapter for the FastAPI web server
102+
103+
2. **`tale/tio/mud_browser_io.py`**:
104+
- `TaleMudFastAPIApp`: FastAPI application for multi-player mode with session management
105+
- `MudHttpIo`: I/O adapter for multi-player browser interface
106+
107+
3. **`tale/driver_if.py`**:
108+
- `IFDriver`: Creates FastAPI server for IF web interface
109+
110+
4. **`tale/driver_mud.py`**:
111+
- `MudDriver`: Creates FastAPI server for MUD web interface
112+
113+
5. **`tale/web/script.js`**:
114+
- `connectWebSocket()`: Establishes WebSocket connection
115+
- `send_cmd()`: Sends commands via WebSocket
116+
117+
## Troubleshooting
118+
119+
### WebSocket Connection Fails
120+
121+
If the WebSocket connection fails:
122+
123+
1. Ensure FastAPI and uvicorn are installed
124+
2. Check that the port is not blocked by firewall
125+
3. Check browser console for error messages
126+
127+
### Module Not Found Errors
128+
129+
Ensure all dependencies are installed:
130+
131+
```bash
132+
pip install fastapi websockets uvicorn
133+
```
134+
135+
### ImportError for FastAPI
136+
137+
If FastAPI is not available, an error will be raised when starting with web interface. Install FastAPI:
138+
139+
```bash
140+
pip install fastapi websockets uvicorn
141+
```
142+
143+
## Future Enhancements
144+
145+
Possible improvements for the WebSocket implementation:
146+
147+
- Compression for large text outputs
148+
- Reconnection handling with session persistence
149+
- WebSocket authentication and security enhancements
150+
- Performance metrics and monitoring

0 commit comments

Comments
 (0)