# ws2s **Repository Path**: apihub/ws2s ## Basic Information - **Project Name**: ws2s - **Description**: ws2s(websocket to socket)让运行在浏览器上的js,能使用socket来通信。 - **Primary Language**: Python - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 49 - **Forks**: 12 - **Created**: 2018-02-13 - **Last Updated**: 2024-09-09 ## Categories & Tags **Categories**: web-dev-toolkits **Tags**: None ## README ## ws2s--bring socket to browser-side js ws2s(websocket to socket) is a websocket server that handle socket(tcp)s. ![](https://images.gitee.com/uploads/images/2019/0623/074921_47095ee0_5008803.png) the simplest workflow might be like this: 1. a websocket client(we called **`"ws"`**) ask ws2s_server to create a socket(we called **`"s"`**) for it. 2. **`"ws"`** ask ws2s_server to use **`"s"`** to send data. 3. when **`"s"`** received data, ws2s_server will notify **`"ws"`** with the received data. with this workflow, javaScript running on a browser got the ability to use socket. ## client case + a ws2s server at `wss://ws2s.feling.net/` is ready for test case, try it on [https://feling.net/wsp/](https://feling.net/wsp/). + an online redis gui client powered by ws2s is provided at [https://feling.net/redis/](https://feling.net/redis/). ### use origin javaScript ```javaScript var ws = new WebSocket("wss://ws2s.feling.net/") ws.onmessage = (event) => { console.log("onmessage: ", event.data) } ws.onopen = () => { console.log("onopen") ws.send(JSON.stringify( { command: "connect", host: "feling.net", port: 80 } )) ws.send(JSON.stringify( { command: "send", data: "GET / HTTP/1.1\r\nHost: feling.net\r\nConnection: close\r\n\r\n" } )) } ws.onclose = () => { console.log("onclose") } ``` ### use [ws2s.js](ws2s-js/) ```javaScript var socket = new WS2S("wss://ws2s.feling.net/").newSocket() $('#connect-button').bind("click", () => { socket.connect("feling.net", 80) }) $('#send-button').bind("click", () => { socket.send("GET / HTTP/1.1\r\nHost: feling.net\r\nConnection: close\r\n\r\n") }) socket.onRecv = (data) => { console.log('onRecv', data) } ``` ## install ws2s works with py2、py3 on Linux、OSX. Windows users please try Windows Subsystem for Linux(WSL). It is recommended to install from github: ```shell pip install git+https://github.com/playay/ws2s --upgrade ``` you can also install ws2s from pypi: ```shell pip install ws2s-python --upgrade ``` after installed ws2s: `ws2sd` command can be used in shell, `~/.ws2s/` directory will be created when you exec `ws2sd` ## config config file is store at `~/.ws2s/config.json`. modify it then exec `ws2sd restart` ## start on boot at see [this wiki](https://github.com/playay/ws2s/wiki/start-on-boot) ## protocol ### request here are some examples of requests: ```json { "command": "connect", "host":"127.0.0.1", "port":80 } { "command": "send", "data":"GET / HTTP/1.1\r\nHost: 127.0.0.1\r\nConnection: close\r\n\r\n" } ``` you can find out that: 1. message(we called request) send to ws2s_sever is a json format string. 2. a `command` field is required. other fields are dependent on different `command`s 3. [this wiki](https://github.com/playay/ws2s/wiki/command) describes details of each command. ### response message(we called response) received from ws2s_sever, is a json format string too: ```json { "success": true, "code": -1, "message": "recv data", "data": "JDINCk9LDQo=" } ``` ``` As the example above: - "message" field is for human. - "success" field can be ignored. when "code" field = -1, "data" field is presented. that means ws2s_server received data from peer. "data" is a base64 string representing a byte array. when "code" field = 0. usually means ws2s_server successfully completed the most recent command when "code" field > 0. means something is not normal: when "code" = 1: unknown exception, you can submit an issue to ws2s when "code" = 2: ConnectionRefusedError raisesd when ws2s_server try to connect host:port you specified when "code" = 3: IllegalSocketState, just reSend an "connect" request like: {"command":"connect","host":"127.0.0.1","port":80} when "code" = 4: usually means you want ws2s_server to connect 127.0.0.1, but ws2s_server refused to do that. this feature is configurable in `~/.ws2s/config.json` when "code" = 5: socket connection closed by socket server you connected to when "code" = 6: failed to open ssh tunnel ``` ### dev ``` pipenv shell python setup.py bdist_wheel python setup.py sdist twine upload dist/* ```