diff --git a/app/main.py b/app/main.py index af50af7..3f451e6 100644 --- a/app/main.py +++ b/app/main.py @@ -12,10 +12,11 @@ STATIC_DIR = BASE_DIR / "static" app = FastAPI(title="Simple WebSocket Chatroom") -# WebSocket route: ws://localhost:8000/ws/{room_id}/{client_id} +# Registers the WebSocket endpoint: +# ws://localhost:8000/ws/{room_id}/{client_id} app.include_router(chat_router) -# Frontend files +# Serves CSS, JavaScript, font files, and the main HTML page from app/static. app.mount("/static", StaticFiles(directory=STATIC_DIR), name="static") @@ -27,7 +28,7 @@ async def home(): @app.get("/api/rooms") async def rooms(): - """Small helper endpoint for the GUI/debugging.""" + """Return active rooms and users for simple debugging during the demo.""" return manager.rooms_overview() diff --git a/app/static/app.js b/app/static/app.js index edc600d..fa91ca6 100644 --- a/app/static/app.js +++ b/app/static/app.js @@ -16,6 +16,7 @@ let socket = null; let currentUser = ''; let currentRoom = ''; +// Persist the last used identity locally so refreshing the page is convenient. usernameInput.value = localStorage.getItem('chat_username') || ''; roomInput.value = localStorage.getItem('chat_room') || 'عمومی'; @@ -48,6 +49,8 @@ function formatTime(timestamp) { if (!timestamp) return ''; const date = new Date(timestamp); if (Number.isNaN(date.getTime())) return ''; + + // The server stores UTC timestamps; the browser formats them for the user. return date.toLocaleTimeString('fa-IR', { hour: '2-digit', minute: '2-digit' }); } @@ -108,6 +111,7 @@ function connect() { const wsProtocol = window.location.protocol === 'https:' ? 'wss' : 'ws'; const wsUrl = `${wsProtocol}://${window.location.host}/ws/${encodeURIComponent(currentRoom)}/${encodeURIComponent(currentUser)}`; + // Opening this object starts the HTTP Upgrade handshake automatically. socket = new WebSocket(wsUrl); socket.addEventListener('open', () => { @@ -120,6 +124,7 @@ function connect() { socket.addEventListener('message', (event) => { const payload = JSON.parse(event.data); + // Presence messages update the sidebar; chat/system messages go to the feed. if (payload.type === 'presence') { updateUsers(payload.users || []); return; @@ -159,6 +164,7 @@ messageForm.addEventListener('submit', (event) => { const content = messageInput.value.trim(); if (!content || !socket || socket.readyState !== WebSocket.OPEN) return; + // The server accepts JSON messages and broadcasts the content to the room. socket.send(JSON.stringify({ content })); messageInput.value = ''; messageInput.focus(); diff --git a/app/static/style.css b/app/static/style.css index f4fe510..1a0279d 100644 --- a/app/static/style.css +++ b/app/static/style.css @@ -29,6 +29,7 @@ body { color: var(--text); background: var(--bg); direction: rtl; + /* The app shell owns scrolling so the page does not exceed the viewport. */ overflow: hidden; } @@ -98,6 +99,7 @@ h1 { } .layout { + /* Allows the chat and users panels to shrink and scroll inside the viewport. */ min-height: 0; flex: 1; display: grid; @@ -216,6 +218,7 @@ ul { #usersList { min-height: 0; + /* Long user lists scroll here instead of making the page taller. */ overflow-y: auto; } @@ -252,6 +255,7 @@ li { min-height: 0; flex: 1; padding: 18px; + /* Chat history scrolls inside the chat panel. */ overflow-y: auto; display: flex; flex-direction: column; diff --git a/app/websocket/chat.py b/app/websocket/chat.py index 882d974..0b27b7c 100644 --- a/app/websocket/chat.py +++ b/app/websocket/chat.py @@ -9,10 +9,12 @@ router = APIRouter() def now_iso() -> str: + """Return an ISO timestamp so browsers can format message time locally.""" return datetime.now(timezone.utc).isoformat() def event(event_type: str, room_id: str, client_id: str, content: str): + """Create the shared JSON shape sent from the server to the browser.""" return { "type": event_type, "room_id": room_id, @@ -23,17 +25,21 @@ def event(event_type: str, room_id: str, client_id: str, content: str): def clean_value(value: str, fallback: str) -> str: + """Use a default value when a route parameter is empty after trimming.""" value = value.strip() return value if value else fallback @router.websocket("/ws/{room_id}/{client_id}") async def websocket_endpoint(websocket: WebSocket, room_id: str, client_id: str): + """Handle one browser's full WebSocket lifecycle.""" room_id = clean_value(room_id, "عمومی") client_id = clean_value(client_id, "ناشناس") + # FastAPI accepts the HTTP Upgrade request here and switches to WebSocket. await manager.connect(websocket, room_id, client_id) + # Notify everyone in the room that the user joined, then refresh presence. await manager.broadcast_json( event("system", room_id, "سیستم", f"{client_id} وارد اتاق {room_id} شد."), room_id, @@ -52,8 +58,10 @@ async def websocket_endpoint(websocket: WebSocket, room_id: str, client_id: str) try: while True: + # Keep the socket open and wait for the next message from this client. raw_data = await websocket.receive_text() + # The browser sends JSON, but plain text is accepted for manual tests. try: data = json.loads(raw_data) message = str(data.get("content", "")).strip() @@ -69,6 +77,7 @@ async def websocket_endpoint(websocket: WebSocket, room_id: str, client_id: str) ) except WebSocketDisconnect: + # When the browser tab closes or disconnects, remove it and update the room. manager.disconnect(websocket, room_id) await manager.broadcast_json( event("system", room_id, "سیستم", f"{client_id} از اتاق {room_id} خارج شد."), diff --git a/app/websocket/manager.py b/app/websocket/manager.py index 36a523b..3e7d29d 100644 --- a/app/websocket/manager.py +++ b/app/websocket/manager.py @@ -6,15 +6,22 @@ from fastapi import WebSocket @dataclass class ClientConnection: + """A connected browser inside one chat room.""" + websocket: WebSocket client_id: str class ConnectionManager: + """Keeps all active WebSocket connections grouped by room name.""" + def __init__(self): + # Example: + # {"عمومی": [ClientConnection(...), ClientConnection(...)]} self.active_connections: dict[str, list[ClientConnection]] = {} async def connect(self, websocket: WebSocket, room_id: str, client_id: str): + """Accept the WebSocket handshake and remember this user in the room.""" await websocket.accept() self.active_connections.setdefault(room_id, []) self.active_connections[room_id].append( @@ -22,6 +29,7 @@ class ConnectionManager: ) def disconnect(self, websocket: WebSocket, room_id: str): + """Remove a socket from a room and delete the room when it becomes empty.""" if room_id not in self.active_connections: return @@ -38,11 +46,13 @@ class ConnectionManager: await websocket.send_json(payload) async def broadcast_json(self, payload: dict[str, Any], room_id: str): + """Send one JSON message to every connected client in the selected room.""" if room_id not in self.active_connections: return dead_connections: list[WebSocket] = [] + # Iterate over a copy so disconnected clients can be removed safely later. for connection in list(self.active_connections[room_id]): try: await connection.websocket.send_json(payload) @@ -53,12 +63,14 @@ class ConnectionManager: self.disconnect(websocket, room_id) def room_users(self, room_id: str) -> list[str]: + """Return display names of users currently connected to a room.""" return [ connection.client_id for connection in self.active_connections.get(room_id, []) ] def rooms_overview(self) -> dict[str, Any]: + """Build a small debug-friendly snapshot of all active rooms.""" return { "rooms": [ {