{"id":19591389,"url":"https://github.com/taoso/nginx-websocket-module","last_synced_at":"2026-04-07T04:31:16.388Z","repository":{"id":68494087,"uuid":"89831729","full_name":"taoso/nginx-websocket-module","owner":"taoso","description":"make nginx as websocket server","archived":false,"fork":false,"pushed_at":"2017-05-21T02:21:00.000Z","size":49,"stargazers_count":23,"open_issues_count":0,"forks_count":8,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-27T13:37:15.695Z","etag":null,"topics":["nginx","push","websocket","wslay"],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/taoso.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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":"2017-04-30T05:36:13.000Z","updated_at":"2025-03-28T04:56:44.000Z","dependencies_parsed_at":"2023-02-21T10:30:17.792Z","dependency_job_id":null,"html_url":"https://github.com/taoso/nginx-websocket-module","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/taoso/nginx-websocket-module","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taoso%2Fnginx-websocket-module","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taoso%2Fnginx-websocket-module/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taoso%2Fnginx-websocket-module/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taoso%2Fnginx-websocket-module/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/taoso","download_url":"https://codeload.github.com/taoso/nginx-websocket-module/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taoso%2Fnginx-websocket-module/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31500397,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T03:10:19.677Z","status":"ssl_error","status_checked_at":"2026-04-07T03:10:13.982Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["nginx","push","websocket","wslay"],"created_at":"2024-11-11T08:28:53.457Z","updated_at":"2026-04-07T04:31:16.354Z","avatar_url":"https://github.com/taoso.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WebSocket Module for Nginx\n\n## how to work\n\nNginx use the multiprocess model. The worker process has no idea of eatch other.\nWhen there is a incoming http request, the request has been processed by one\nworker. This model is simple yet efficient. It works well for nginx as a proxy\nserver.\n\nHowever, if you want nginx work as an websocket server, we would face\nan intractable problem. Suppose we have two workers, A and B. When an websocket\nclient comes, it will be processed by A or B. Let's suppose it by A. And nginx\nthen send some id info the the client. If we want send somethig to the client,\nwe need make a request, as well. However, our push request maybe processed by\nanother worker B. The worker B has no idea about the client. It failed.\n\nIn order to fixup this problem, we make every worker listen an unique port\nbefore the worker start. However, in the latest nginx code base, it is hard to\nadd listen port on fly. So we make some nginx inner api public to simplify this\nprocess. We will try to make this patch be merged into the nginx code base.\n\n## install\n\n1. install [libwslay](https://github.com/tatsuhiro-t/wslay)\n1. download nginx source code\n1. go to base dir of nginx source code and run `patch -p1 \u003c /path/to/ngx_listen.diff`\n1. then run `./auto/configure --prefix=/tmp/ngx --add-module=path/to/src/nginx-websocket-module --with-debug`\n\n## usage\n\nThis module only offer one directive, **websocket**. This directive can be only\nused in the `location` context. An example conf:\n\n```\nlocation /ws {\n    websocket pingintvl=10000 idleintvl=15000;\n}\n````\n\nThe config above will make nginx listen websocket request on the `/ws` path.\nThe `pingintvl` arg is used to set the interval to send ping message to the\nclient. And the `idleintvl` arg is used to detect client timeout. If there is \nno message send or receive after `pingintvl`, nginx will send a `PING`,\nmessage and the client will ack the `PONG` message, which will reset the ping\ntimer. If ther is no message send or receive after `idleintvl`, nginx will\njust close the connection. Both units are millisecond. If not set, the default\nvalue of pingintvl is 5 minute and idleintvl 6 minute.\n\nBut why let server send the `PING` message? It is because that the browser does\nnot offer the api to ping server for javascript.\n\nThen you can make a websocket handshake to nginx. Once the handshake finished,\nnginx will send an text message reads\n`http://12@172.16.71.231:48775/ws,http://12@172.16.71.211:48775/ws`.\nYou can post message to this url by httpie like:\n```\necho 123|http http://12@172.16.71.231:48775/ws\n```\n\n## todo\n- [ ] ipv6\n- [x] more debug log\n- [ ] push binary data\n- [ ] process upstream message\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftaoso%2Fnginx-websocket-module","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftaoso%2Fnginx-websocket-module","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftaoso%2Fnginx-websocket-module/lists"}