ws2s(websocket to socket)--bring socket to browser-side js.
Switch branches/tags
Nothing to show
Clone or download
Latest commit f7e045b Apr 16, 2018
Type Name Latest commit message Commit time
Failed to load latest commit information.
ws2s-js ws2s.js redis: onReconnected Apr 16, 2018
ws2s change github userame Apr 16, 2018
.gitignore init Feb 12, 2018
LICENSE.txt rename LICENSE file Apr 13, 2018
Pipfile ssh tunnel Apr 12, 2018
Pipfile.lock ssh tunnel Apr 12, 2018 update readme Apr 13, 2018
setup.cfg init Feb 12, 2018 install_requires add sshtunnel>=0.1.3 Apr 13, 2018

ws2s--bring socket to browser-side js

ws2s(websocket to socket) is a websocket server that handle socket(tcp)s.

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:// is ready for test case.
  • an online redis gui client powered by ws2s is provided at

use origin javaScript

var ws = new WebSocket("wss://")
ws.onmessage = (event) => {
    console.log("onmessage: ",
ws.onopen = () => {
            command: "connect",
            host: "",
            port: 80
            command: "send",
            data: "GET / HTTP/1.1\r\nHost:\r\nConnection: close\r\n\r\n"
ws.onclose = () => {

use ws2s.js

var socket = new WS2S("wss://").newSocket()

$('#connect-button').bind("click", () => {
    socket.connect("", 80)

$('#send-button').bind("click",  () => {
    socket.send("GET / HTTP/1.1\r\nHost:\r\nConnection: close\r\n\r\n")

socket.onRecv = (data) => {
    console.log('onRecv', data)


ws2s works on py2、py3、Linux、OSX. I tried to support Windows, but there is too much adaptation to be handled for Windows.

It is recommended to install from github:

pip install git+ --upgrade

you can also install ws2s from pypi:

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 file is store at ~/.ws2s/config.json. modify it then exec ws2sd restart



here are some examples of requests:

    "command": "connect",
    "command": "send",
    "data":"GET / HTTP/1.1\r\nHost:\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 commands
  3. this wiki describes details of each command.


message(we called response) received from ws2s_sever, is a json format string too:

    "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:    

    when "code" = 4:    
        usually means you want ws2s_server to connect,    
        but ws2s_server refused to do that     
    when "code" = 5:    
        socket connection closed by socket server you connected to    

    when "code" = 6:    
        failed to open ssh tunnel