{"id":26187142,"url":"https://github.com/adarsh-kmt/websocketreverseproxy","last_synced_at":"2025-08-19T19:16:57.557Z","repository":{"id":254234390,"uuid":"837902811","full_name":"Adarsh-Kmt/WebsocketReverseProxy","owner":"Adarsh-Kmt","description":"A light weight fault tolerant reverse proxy, used to load balance websockets and http requests.","archived":false,"fork":false,"pushed_at":"2025-01-14T04:36:40.000Z","size":77,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-01-14T05:34:50.850Z","etag":null,"topics":["golang","health-checks","load-balancer","multithreading","websocket"],"latest_commit_sha":null,"homepage":"","language":"Go","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/Adarsh-Kmt.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}},"created_at":"2024-08-04T11:41:46.000Z","updated_at":"2025-01-14T04:36:43.000Z","dependencies_parsed_at":"2024-08-22T07:42:20.366Z","dependency_job_id":"5e7b1b49-bf36-48ae-b7b4-7c36ca303a2e","html_url":"https://github.com/Adarsh-Kmt/WebsocketReverseProxy","commit_stats":null,"previous_names":["adarsh-kmt/websocketreverseproxy"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Adarsh-Kmt%2FWebsocketReverseProxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Adarsh-Kmt%2FWebsocketReverseProxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Adarsh-Kmt%2FWebsocketReverseProxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Adarsh-Kmt%2FWebsocketReverseProxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Adarsh-Kmt","download_url":"https://codeload.github.com/Adarsh-Kmt/WebsocketReverseProxy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243131023,"owners_count":20241176,"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","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":["golang","health-checks","load-balancer","multithreading","websocket"],"created_at":"2025-03-11T23:39:34.325Z","updated_at":"2025-03-11T23:39:35.080Z","avatar_url":"https://github.com/Adarsh-Kmt.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WebsocketReverseProxy\nA light weight fault tolerant reverse proxy, used to load balance websockets and http requests.\n\n\n## Features:\n\n- Only 26.21 MB in size!!\n- The load balancer periodically performs health checks to monitor the health status of servers, ensuring that only healthy servers are used to handle incoming traffic.\n- Health checks for all servers are performed concurrently, and the list of healthy servers is updated in a thread-safe manner.\n- Health check (writer) and user connection requests (readers) are managed using a write-preferred reader-writer mutex, that prevents starvation of health check go routines.\n- Worker pool pattern used to maintain persistent TCP connections for each server, with each ”Worker” goroutine handling a connection to the server.\n- The number of workers may increase/decrease dynamically based on the load on the load balancer and idle time.\n- The number of worker go routines may:\n    - **Increase** if the buffered channel is full.\n    - **Decrease** if a worker remains idle for a configurable amount of time.\n- The load balancer also has support for Websocket connections. Two go routines per user are used, one to read from client and write to server, and the 2nd goroutine does the opposite.\n\n## Load Balancer Setup:\n\nFollow these steps to configure the load balancer for your application using an `.ini` file.\n\n\n1. **Create a `.ini` file:**\n\n   - Create a new `.ini` file to store your load balancer configuration.\n\n2. **Specify Frontend Settings:**\n\n   - Under the `[frontend]` section of the `.ini` file, specify the `host` and `port` for the load balancer to run.\n     \n3. **Specify Websocket Server Settings:**\n   \n   - Under the `[websocket]` section, define your WebSocket servers. \n   - Use `enable_health_check={true/false}` to enable health checks.\n   - Use `health_check_interval=W` to configure the frequency with which health checks are performed for Websocket servers.\n   - Use `algorithm={round-robin/random}` to specify load balancing algorithm. (random load balancing algorithm used by default)\n   - Use the format `serverN={host:port}` to list each server.\n\n4. **Specify HTTP Server Settings:**\n   \n   - Under the `[http]` section, define your HTTP servers.\n   - Use `enable_health_check={true/false}` to enable health checks.\n   - Use `health_check_interval=W` to configure the frequency with which health checks are performed for HTTP servers.\n   - Use `algorithm={round-robin/random}` to specify load balancing algorithm. (random load balancing algorithm used by default)\n   - Use the format `serverN={host:port}` to list the address of each server.\n   - Use `serverN_max_workers=X` to specify the maximum number of workers/TCP connections per server.\n   - Use `serverN_min_workers=Y` to specify the minimum number of workers/TCP connections to be maintained per server.\n   - Use `serverN_worker_timeout=Z` to specify the timeout (in seconds) after which an idle worker/TCP connection will terminate.\n   - Use `serverN_buffer_size=W` to specify the maximum number of requests that can be queued in a buffer before being sent to the server.\n\n5. **Create Health Check Endpoint:**\n\n   - Create a `/healthCheck` GET endpoint in your HTTP and Websocket Servers, which responds with the following json as a response:\n     \n     ```json\n     {\n     \t\"status\" : \"HTTP status code\"\n     }\n\n6. **Docker pull Command:**\n\n   - Execute the following docker command to pull the reverse proxy image from docker hub:\n     \n     ```powershell\n     docker pull adarshkamath/load-balancer:2.0.0\n   \n7. **Docker Run Command:**\n\n   - Execute the following docker command to create and run the reverse proxy container:\n\n     ```powershell\n     docker run -v {absolutePathToConfigFile}:/prod/reverse-proxy-config.ini adarshkamath/load-balancer:2.0.0\n\n## Default Configuration Values\n\n|     Configuration      |  Default Value  |\n|:----------------------:|:---------------:|\n|       algorithm        |     random      |\n|      max_workers       |       3         |\n|      min_workers       |       1         |\n|     worker_timeout     |       3 sec     |\n|      buffer_size       |      10         |\n|  health_check_interval |      10 sec     |\n\n\n## Example Configuration:\n\n   ```ini\n[frontend]\nhost=rp_v11\nport=8080\n\n[websocket]\nenable_health_check=true\nhealth_check_interval=10\nalgorithm=round-robin\nserver1=es1_hc:8080\nserver2=es2_hc:8080\nserver3=es3_hc:8080\n\n[http]\nenable_health_check=true\nhealth_check_interval=10\nalgorithm=random\n#server 1 configuration\nserver1_addr=es1_hc:8080\nserver1_max_workers=10\nserver1_min_workers=3\nserver1_worker_timeout=3\nserver1_buffer_size=20\n#server 2 configuration\nserver2_addr=es2_hc:8080\nserver2_max_workers=10\nserver2_min_workers=3\nserver2_worker_timeout=3\nserver2_buffer_size=20\n#server 3 configuration\nserver3_addr=es3_hc:8080\nserver3_max_workers=10\nserver3_min_workers=3\nserver3_worker_timeout=3\nserver3_buffer_size=20\n   ```\n\n## TODO:\n- [ ] Implement passive health checks by monitoring the number of 500 internal server error responses.\n- [ ] Implement dynamic weighted round robin, where the server responds to a health check with CPU and memory utilization, which is used to calculate its weight.\n  \n\n## License:\n\n```\nMIT License\n\nCopyright (c) 2024 Adarsh Kamath\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadarsh-kmt%2Fwebsocketreverseproxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadarsh-kmt%2Fwebsocketreverseproxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadarsh-kmt%2Fwebsocketreverseproxy/lists"}