{"id":29131363,"url":"https://github.com/mrinalxdev/websocket","last_synced_at":"2025-08-16T11:09:17.111Z","repository":{"id":297397474,"uuid":"996602183","full_name":"mrinalxdev/websocket","owner":"mrinalxdev","description":"Building websocket from scratch","archived":false,"fork":false,"pushed_at":"2025-06-05T08:07:01.000Z","size":6,"stargazers_count":5,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-30T05:36:40.449Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mrinalxdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-05T07:25:14.000Z","updated_at":"2025-06-06T07:28:53.000Z","dependencies_parsed_at":"2025-06-05T09:23:35.244Z","dependency_job_id":"75dcd9a2-7314-456a-94aa-02a7fad47e99","html_url":"https://github.com/mrinalxdev/websocket","commit_stats":null,"previous_names":["mrinalxdev/websocket"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mrinalxdev/websocket","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrinalxdev%2Fwebsocket","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrinalxdev%2Fwebsocket/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrinalxdev%2Fwebsocket/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrinalxdev%2Fwebsocket/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mrinalxdev","download_url":"https://codeload.github.com/mrinalxdev/websocket/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mrinalxdev%2Fwebsocket/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270702562,"owners_count":24630877,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-16T02:00:11.002Z","response_time":91,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-30T05:32:43.681Z","updated_at":"2025-08-16T11:09:17.089Z","avatar_url":"https://github.com/mrinalxdev.png","language":"Python","readme":"# WebSocket Chat Application\n### Overview\nThis is a simple WebSocket-based chat application implemented in Python, following the RFC 6455 WebSocket protocol. It allows multiple clients to connect to a server, send messages, and receive broadcasts in real-time. The codebase includes frame encoding/decoding, server and client implementations, and a basic chat interface via the console.\n\nWhat have I done till now :\n\n- WebSocket Protocol: Compliant with RFC 6455 for handshake and frame handling.\n- Multi-Client Support: Server manages multiple clients using threading.\n- Message Broadcasting: Messages from one client are sent to all other connected clients.\n- Control Frames: Supports ping/pong and close frames for connection management.\n- Simple Interface: Clients interact via console input; server runs in the background.\n- Graceful Shutdown: Handles disconnections and server termination cleanly.\n\nWhat needs to be added :\n\n- [ ] secure communication\n- [ ] PM messaging\n- [ ] Type indications\n\n### Libraries I have used and their specific work\n\n- socket: For TCP socket communication.\n- threading: For handling multiple clients concurrently.\n- hashlib: For SHA-1 hashing during WebSocket handshake.\n- base64: For encoding/decoding WebSocket keys.\n- struct: For packing/unpacking frame data.\n- select: For non-blocking socket reads.\n- json: Included but not used (potential for future extensions).\n- time: For generating masking keys and timing.\n- sys: For command-line argument parsing.\n\nThere is no external libraries used but to ensure you can run this command\n```bash\nuv sync\n```\n\nfor running the project\n\n1. For Server part\n```bash\nuv run main.py server\n```\n\n2. For client on different terminal\n```bash\nuv run main.py client \u003cusername\u003e\n```\n\n### Here is the full breakdown \n\nUsage\nThe application can run in two modes: server or client, controlled via command-line arguments.\nRunning the Server\n\nCommand: \n```bash\nuv run main.py server\n```\n\n- Description: Starts a WebSocket server on `127.0.0.1:8000`.\n- Behavior:\n    1. Listens for incoming client connections.\n    2. Performs WebSocket handshake per RFC 6455.\n    3. Accepts a username as the first message from each client.\n    4. Broadcasts join/leave messages and chat content to all clients.\n    5. Runs until interrupted (e.g., Ctrl+C), then shuts down gracefully.\n\n\nOutput: Prints \"WebSocket server listening on 127.0.0.1:8000\" on start.\n\n- Description: Connects to the server at 127.0.0.1:8000 with the specified username.\n- Behavior:\n    1. Performs WebSocket handshake.\n    2. Sends the username as the first message.\n    3. Receives and displays broadcast messages from the server.\n    4. Accepts console input for sending messages.\n    5. Type /exit to disconnect gracefully.\n\n\nOutput: Displays received messages and a \u003e  prompt for input.\n\nExample\n\n1. Open a terminal and start the server:\n```bash\nuv run main.py server\n```\n\n2. Output: WebSocket server listening on 127.0.0.1:8000\nOpen another terminal and start a client :\n```bash\nuv run main.py client \u003cyour name\u003e\n```\n\n\n3. Output: Server broadcasts \"X joined the chat\" to all clients.\nOpen a third terminal for another client :\n```bash\nuv run main.py client \u003cyour second name\u003e\n```\n\nOutput: Server broadcasts \"Second X joined the chat\".\n\n4. Type messages in either client terminal (e.g., \"Hello, X!\"):\nMessage appears in all other clients’ terminals.\n\n\n5. Type /exit in a client to disconnect:\nServer broadcasts \" has left the chat\".\n\n### Code Structure\n\n1. WebSocketFrame Class:\nHandles frame encoding/decoding per RFC 6455.\nSupports opcodes: text (0x1), close (0x8), ping (0x9), pong (0xA).\ncreate_frame: Builds masked frames for sending.\nparse_frame: Decodes incoming frames, handles masking.\n\n\n2. WebSocketServer Class:\nManages server-side logic: binds to host/port, accepts clients.\nPerforms handshake, tracks clients (socket: username).\nBroadcasts messages; handles ping/pong and close frames.\nMethods: start, stop, broadcast, close_client.\n\n\n4. WebSocketClient Class:\nConnects to the server, performs handshake.\nSends username and chat messages; receives broadcasts.\nMethods: connect, send, receive, close.\n\n\n5. Chat Application:\nrun_chat_server: Runs the server in a thread.\nrun_chat_client: Runs the client, handles input/output.\nMain block parses arguments to launch server or client.\n\n\n\n### How It Works\n\n1. Handshake:\nClient sends HTTP GET with WebSocket headers (e.g., Sec-WebSocket-Key).\nServer responds with HTTP 101, computed Sec-WebSocket-Accept key.\n\n\n2. Framing:\nMessages are sent as WebSocket frames (FIN bit, opcode, payload).\nClients mask payloads; server unmasks them.\n\n\n3. Communication:\nServer broadcasts each client’s messages to others.\nSupports control frames (close, ping/pong) for connection health.\n\n\n4. Termination:\nClients send close frames or use /exit.\nServer closes connections and shuts down on interrupt.\n\n\n\n### These things needs to be done ASAP for resume worthy like project\n\n- Security: No encryption (e.g., WSS); runs over plain TCP.\n- Masking: Server doesn’t strictly enforce client masking (RFC 6455 requirement).\n- Scalability: Thread-per-client model may not scale for many users.\n- Error Handling: Basic; lacks detailed logging or robust frame validation.\n- Port: Hardcoded to 8000; no configuration option.\n\n### Things I am planning rn to make it a good OSS project\n\n- Add WSS (WebSocket Secure) with TLS for encryption.\n- Enforce client-side masking on the server.\n- Use async I/O (e.g., asyncio) for better scalability.\n- Add configuration for host/port via arguments or a config file.\n- Improve error handling with logging and user feedback.\n- Support JSON for structured messages (e.g., timestamps, user roles).\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrinalxdev%2Fwebsocket","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmrinalxdev%2Fwebsocket","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmrinalxdev%2Fwebsocket/lists"}