Merge pull request #131 from neph1/copilot/remove-old-eventsource-api

Remove EventSource-based WSGI API from IF mode

Author: neph1

WEBSOCKET.md

@@ -2,54 +2,41 @@
 
 ## Overview
 
-LlamaTale now supports WebSocket connections for the web browser interface, providing a modern bidirectional communication channel between the client and server. This is an alternative to the traditional Server-Sent Events (EventSource) approach.
+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.
 
 ## Features
 
 - **Bidirectional Communication**: WebSocket enables real-time, two-way communication between the browser and server
-- **Reduced Latency**: Direct WebSocket communication can be faster than HTTP polling or EventSource
+- **Reduced Latency**: Direct WebSocket communication is faster than HTTP polling or EventSource
 - **Modern Stack**: Uses FastAPI and uvicorn for a modern, async Python web framework
-- **Backward Compatibility**: The JavaScript client automatically falls back to EventSource if WebSocket is not available
+- **Unified Approach**: Both IF and MUD modes now use the same WebSocket-based architecture
 
 ## Requirements
 
-Install the additional dependencies:
+Install the required dependencies:
 
 ```bash
 pip install fastapi websockets uvicorn
 ```
 
-Or install all requirements including WebSocket support:
+Or install all requirements:
 
 ```bash
 pip install -r requirements.txt
 ```
 
 ## Usage
 
-### Starting a Game with WebSocket Support
-
-To enable WebSocket mode, use the `--websocket` flag when starting a game with the web interface:
+### Starting a Single-Player Game
 
-```bash
-python -m tale.main --game stories/dungeon --web --websocket
-```
-
-### Command-Line Arguments
-
-- `--web`: Enable web browser interface
-- `--websocket`: Use WebSocket instead of EventSource (requires `--web`)
-
-### Example Commands
-
-**Standard EventSource mode (default):**
 ```bash
 python -m tale.main --game stories/dungeon --web
 ```
 
-**WebSocket mode:**
+### Starting a Multi-Player (MUD) Game
+
 ```bash
-python -m tale.main --game stories/dungeon --web --websocket
+python -m tale.main --game stories/dungeon --mode mud
 ```
 
 ## Architecture
@@ -58,7 +45,8 @@ python -m tale.main --game stories/dungeon --web --websocket
 
 The WebSocket implementation uses FastAPI and includes:
 
-- **TaleFastAPIApp**: Main FastAPI application with WebSocket endpoint
+- **TaleFastAPIApp** (IF mode): FastAPI application for single-player with WebSocket endpoint
+- **TaleMudFastAPIApp** (MUD mode): FastAPI application for multi-player with session management
 - **WebSocket Endpoint** (`/tale/ws`): Handles bidirectional communication
 - **HTTP Routes**: Serves static files and HTML pages
 - **Message Protocol**: JSON-based messages for commands and responses
@@ -67,7 +55,7 @@ The WebSocket implementation uses FastAPI and includes:
 
 The JavaScript client (`script.js`) includes:
 
-- **Automatic Detection**: Tries WebSocket first, falls back to EventSource
+- **WebSocket Connection**: Connects to the WebSocket endpoint
 - **Message Handling**: Processes incoming text, data, and status messages
 - **Command Sending**: Sends commands and autocomplete requests via WebSocket
 
@@ -109,48 +97,44 @@ The JavaScript client (`script.js`) includes:
 ### Key Components
 
 1. **`tale/tio/if_browser_io.py`**:
-   - `TaleFastAPIApp`: FastAPI application with WebSocket support
-   - `HttpIo`: Updated to support both WSGI and FastAPI modes
-
-2. **`tale/driver_if.py`**:
-   - `IFDriver`: Updated constructor with `use_websocket` parameter
-   - `connect_player()`: Creates FastAPI server when WebSocket mode is enabled
+   - `TaleFastAPIApp`: FastAPI application for single-player mode
+   - `HttpIo`: I/O adapter for the FastAPI web server
 
-3. **`tale/web/script.js`**:
-   - `tryWebSocket()`: Attempts WebSocket connection
-   - `setupEventSource()`: Fallback to EventSource
-   - `send_cmd()`: Sends commands via WebSocket or AJAX
+2. **`tale/tio/mud_browser_io.py`**:
+   - `TaleMudFastAPIApp`: FastAPI application for multi-player mode with session management
+   - `MudHttpIo`: I/O adapter for multi-player browser interface
 
-4. **`tale/main.py`**:
-   - Added `--websocket` command-line argument
+3. **`tale/driver_if.py`**:
+   - `IFDriver`: Creates FastAPI server for IF web interface
 
-### Limitations
+4. **`tale/driver_mud.py`**:
+   - `MudDriver`: Creates FastAPI server for MUD web interface
 
-- WebSocket mode is currently only supported in single-player (IF) mode
-- SSL/TLS configuration may require additional setup for WebSocket secure connections
-- The implementation maintains backward compatibility with the original WSGI-based approach
+5. **`tale/web/script.js`**:
+   - `connectWebSocket()`: Establishes WebSocket connection
+   - `send_cmd()`: Sends commands via WebSocket
 
 ## Troubleshooting
 
 ### WebSocket Connection Fails
 
-If the WebSocket connection fails, the client will automatically fall back to EventSource. Check:
+If the WebSocket connection fails:
 
-1. FastAPI and uvicorn are installed
-2. Port is not blocked by firewall
-3. Browser console for error messages
+1. Ensure FastAPI and uvicorn are installed
+2. Check that the port is not blocked by firewall
+3. Check browser console for error messages
 
 ### Module Not Found Errors
 
 Ensure all dependencies are installed:
 
 ```bash
-pip install -r requirements.txt
+pip install fastapi websockets uvicorn
 ```
 
 ### ImportError for FastAPI
 
-If FastAPI is not available, the system will fall back to the traditional WSGI server. Install FastAPI to enable WebSocket support:
+If FastAPI is not available, an error will be raised when starting with web interface. Install FastAPI:
 
 ```bash
 pip install fastapi websockets uvicorn
@@ -160,7 +144,6 @@ pip install fastapi websockets uvicorn
 
 Possible improvements for the WebSocket implementation:
 
-- Multi-player (MUD) mode support
 - Compression for large text outputs
 - Reconnection handling with session persistence
 - WebSocket authentication and security enhancements

tale/driver_if.py

@@ -30,14 +30,13 @@ class IFDriver(driver.Driver):
     The Single user 'driver'.
     Used to control interactive fiction where there's only one 'player'.
     """
-    def __init__(self, *, screen_delay: int=DEFAULT_SCREEN_DELAY, gui: bool=False, web: bool=False, wizard_override: bool=False, character_to_load: str='', use_websocket: bool=False) -> None:
+    def __init__(self, *, screen_delay: int=DEFAULT_SCREEN_DELAY, gui: bool=False, web: bool=False, wizard_override: bool=False, character_to_load: str='') -> None:
         super().__init__()
         self.game_mode = GameMode.IF
         if screen_delay < 0 or screen_delay > 100:
             raise ValueError("invalid delay, valid range is 0-100")
         self.screen_delay = screen_delay
         self.io_type = "console"
-        self.use_websocket = use_websocket  # Store WebSocket preference
         if gui:
             self.io_type = "gui"
         if web:
@@ -115,28 +114,16 @@ def connect_player(self, player_io_type: str, line_delay: int) -> PlayerConnecti
             from .tio.tkinter_io import TkinterIo
             io = TkinterIo(self.story.config, connection)  # type: iobase.IoAdapterBase
         elif player_io_type == "web":
-            if self.use_websocket:
-                # Use FastAPI with WebSocket support
-                from .tio.if_browser_io import FASTAPI_AVAILABLE
-                if not FASTAPI_AVAILABLE:
-                    raise RuntimeError("FastAPI is not available. Install it with: pip install fastapi websockets uvicorn")
-                from .tio.if_browser_io import HttpIo, TaleFastAPIApp
-                fastapi_server = TaleFastAPIApp.create_app_server(self, connection, use_ssl=False, ssl_certs=None)
-                # you can enable SSL by using the following:
-                # fastapi_server = TaleFastAPIApp.create_app_server(self, connection, use_ssl=True,
-                #                   ssl_certs=("certs/localhost_cert.pem", "certs/localhost_key.pem", ""))
-                io = HttpIo(connection, fastapi_server)
-                io.fastapi_mode = True  # Mark as FastAPI mode
-                io.fastapi_server = fastapi_server  # Store reference
-            else:
-                # Use traditional WSGI server
-                from .tio.if_browser_io import HttpIo, TaleWsgiApp
-                wsgi_server = TaleWsgiApp.create_app_server(self, connection, use_ssl=False, ssl_certs=None)
-                # you can enable SSL by using the following:
-                # wsgi_server = TaleWsgiApp.create_app_server(self, connection, use_ssl=True,
-                #                   ssl_certs=("certs/localhost_cert.pem", "certs/localhost_key.pem", ""))
-                io = HttpIo(connection, wsgi_server)
-                io.fastapi_mode = False
+            # Use FastAPI with WebSocket support
+            from .tio.if_browser_io import FASTAPI_AVAILABLE
+            if not FASTAPI_AVAILABLE:
+                raise RuntimeError("FastAPI is not available. Install it with: pip install fastapi websockets uvicorn")
+            from .tio.if_browser_io import HttpIo, TaleFastAPIApp
+            fastapi_server = TaleFastAPIApp.create_app_server(self, connection, use_ssl=False, ssl_certs=None)
+            # you can enable SSL by using the following:
+            # fastapi_server = TaleFastAPIApp.create_app_server(self, connection, use_ssl=True,
+            #                   ssl_certs=("certs/localhost_cert.pem", "certs/localhost_key.pem", ""))
+            io = HttpIo(connection, fastapi_server)
         elif player_io_type == "console":
             from .tio.console_io import ConsoleIo
             io = ConsoleIo(connection)

tale/driver_mud.py

@@ -6,7 +6,6 @@
 """
 
 import time
-import socket
 import threading
 from typing import Union, Generator, Dict, Tuple, Optional, Any
 
@@ -20,7 +19,7 @@
 from . import pubsub
 from . import util
 from .player import PlayerConnection, Player
-from .tio.mud_browser_io import TaleMudWsgiApp
+from .tio.mud_browser_io import TaleMudFastAPIApp
 
 
 class MudDriver(driver.Driver):
@@ -35,28 +34,24 @@ def __init__(self, restricted=False) -> None:
         self.mud_accounts = None   # type: accounts.MudAccounts
 
     def start_main_loop(self):
-        # Driver runs as main thread, wsgi webserver runs in background thread
+        # Driver runs as main thread, FastAPI webserver runs in background thread
         accounts_db_file = self.user_resources.validate_path("useraccounts.sqlite")
         self.mud_accounts = accounts.MudAccounts(accounts_db_file)
         base._limbo.init_inventory([LimboReaper()])  # add the grim reaper to Limbo
-        wsgi_server = TaleMudWsgiApp.create_app_server(self, use_ssl=False, ssl_certs=None)    # you can enable SSL here
-        wsgi_thread = threading.Thread(name="wsgi", target=wsgi_server.serve_forever)
-        wsgi_thread.daemon = True
-        wsgi_thread.start()
+        fastapi_server = TaleMudFastAPIApp.create_app_server(self, use_ssl=False, ssl_certs=None)    # you can enable SSL here
+        fastapi_thread = threading.Thread(name="fastapi", target=fastapi_server.run, 
+                                          args=(self.story.config.mud_host, self.story.config.mud_port))
+        fastapi_thread.daemon = True
+        fastapi_thread.start()
         self.print_game_intro(None)
         if self.restricted:
             print("\n* Restricted mode: no new players allowed *\n")
-        protocol = "https" if wsgi_server.use_ssl else "http"
-        if wsgi_server.address_family == socket.AF_INET6:
-            hostname, port, _, _ = wsgi_server.server_address
-            if hostname[0] != '[':
-                hostname = '[' + hostname + ']'
-            print("Access the game on this web server url (ipv6):   %s://%s:%d/tale/" % (protocol, hostname, port), end="\n\n")
-        else:
-            hostname, port = wsgi_server.server_address
-            if hostname.startswith("127.0"):
-                hostname = "localhost"
-            print("Access the game on this web server url (ipv4):   %s://%s:%d/tale/" % (protocol, hostname, port), end="\n\n")
+        protocol = "https" if fastapi_server.use_ssl else "http"
+        hostname = self.story.config.mud_host
+        port = self.story.config.mud_port
+        if hostname.startswith("127.0"):
+            hostname = "localhost"
+        print("Access the game on this web server url (WebSocket):   %s://%s:%d/tale/" % (protocol, hostname, port), end="\n\n")
         self._main_loop_wrapper(None)   # this doesn't return!
 
     def show_motd(self, player: Player, notify_no_motd: bool=False) -> None:

tale/main.py

@@ -27,8 +27,7 @@ def run_from_cmdline(cmdline: Sequence[str]) -> None:
                         default=DEFAULT_SCREEN_DELAY)
     parser.add_argument('-m', '--mode', type=str, help='game mode, default=if', default="if", choices=["if", "mud"])
     parser.add_argument('-i', '--gui', help='gui interface', action='store_true')
-    parser.add_argument('-w', '--web', help='web browser interface', action='store_true')
-    parser.add_argument('--websocket', help='use WebSocket instead of EventSource for web interface (requires FastAPI)', action='store_true')
+    parser.add_argument('-w', '--web', help='web browser interface (uses WebSocket)', action='store_true')
     parser.add_argument('-r', '--restricted', help='restricted mud mode; do not allow new players', action='store_true')
     parser.add_argument('-z', '--wizard', help='force wizard mode on if story character (for debug purposes)', action='store_true')
     parser.add_argument('-c', '--character', help='load a v2 character card as player (skips character builder)')
@@ -38,7 +37,7 @@ def run_from_cmdline(cmdline: Sequence[str]) -> None:
         game_mode = GameMode(args.mode)
         if game_mode == GameMode.IF:
             from .driver_if import IFDriver
-            driver = IFDriver(screen_delay=args.delay, gui=args.gui, web=args.web, wizard_override=args.wizard, character_to_load=args.character, use_websocket=args.websocket)   # type: Driver
+            driver = IFDriver(screen_delay=args.delay, gui=args.gui, web=args.web, wizard_override=args.wizard, character_to_load=args.character)   # type: Driver
         elif game_mode == GameMode.MUD:
             from .driver_mud import MudDriver
             driver = MudDriver(args.restricted)