django-gevent-websocket 0.2.0

Settings

Add the following to your $PROJECT_DIR/wsgi.py:

from django_websocket.wsgi import get_wsgi_websocket_application
websocket = get_wsgi_websocket_application()

Add the following to your $PROJECT_DIR/settings.py:

WEBSOCKET_URLCONF = '<path-to-websocket-urlconf>'

A suggested urlconf would be $PROJECT_DIR/websocket_urls.py.

You then need to add your WebSocket urls to that file: they will be very similar to your normal urls, but will only contain the endpoints that should accept a WebSocket connection:

from django.conf.urls import patterns, url

urlpatterns = patterns('',
    url(r'^chat/$', 'path.to.view', name='chat'),
)

If you want to use {% websocket_url %} to get absolute urls that point to the correct WebSocket server and port, then you’ll need to set

Views

A WebSocket view function looks very much like a normal django view function, indeed, it is called by the regular django request cycle, but it does not return an HttpResponse object. Instead, you grab the websocket object from the request, and .receive() data from it, or .send(data) to it.

To make things easier, you can use the decorators to wrap your views:

from django_websocket.decorators import websocket

@websocket
def view_function(request, websocket, *args, **kwargs):
    # do stuff here.

This decorator adds the websocket as the second argument to your view: you still have the request object, allowing you to do things like permissions checking. You can still use any of the regular django decorators if you wish.

from select import select

from django_websocket.decorators import websocket

@websocket
def view_function(request, websocket):
    ws_sock = websocket.handler.socket.fileno()
    other_sock = ... # other socket to listen on.

    while not websocket.closed():
        fd = select([ws_sock, other_sock], [], [])[0][0]

        if fd == ws_sock:
            data = websocket.receive()
            # Deal with incoming data.
        else: ## fd == other_sock:
            # Deal with data from the other source
            websocket.send(message)

from select import select

import redis

from ..decorators import websocket

@websocket
def chat(request, websocket, *args, **kwargs):

    conn = redis.StrictRedis()
    subs = conn.pubsub()
    subs.subscribe('CHAT')

    def incoming():
        data = websocket.receive()
        if data:
            conn.publish('CHAT', data)

    def outgoing():
        msg_type, channel, message = subs.parse_response()
        if msg_type == 'message':
            websocket.send(message)

    sockets = {
        websocket.handler.socket.fileno(): incoming,
        subs.connection._sock.fileno(): outgoing
    }

    while not websocket.closed:
        fd = select(sockets.keys(), [], [])[0][0]
        sockets[fd]()

Template Tag

Because you should have a different urlconf for your WebSocket views, you will need to use a slightly different template tag to get access to the WebSocket urls:

{% load websockets %}

<script>
  var ws = new WebSocket("{% websocket_url 'urlname' %}");

  // Do something with your shiny new WebSocket!
  // ws.send('foo');
</script>

Starting the Server

You will need to start the geventwebsocket server seperately: there is no django management command (which mirrors the deprecation of run_gunicorn):

gunicorn -k "geventwebsocket.gunicorn.workers.GeventWebSocketWorker" $PROJECT_DIR.wsgi:websocket -b 127.0.0.1:8001

Note this runs on a different port than your django development server (or gunicorn in production). In production you will probably stick both of them behind an nginx proxy or similar. If you want to do this, you may have to do some tricky to get the splitting out of the websocket connections to work. I did something like:

server {
  listen  80;
  proxy_set_header Host $host;

  location /static/ {
    alias ...
  }

  if ($http_upgrade) {
    rewrite ^(.*)$ /__ws__/$1 break;
  }

  location /__ws__/ {
    proxy_pass http://127.0.0.1:8001;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    rewrite ^/__ws__/(.*)$ $1 break;
    return;
  }

  location / {
    proxy_pass http://127.0.0.1:8000;
  }
}

Notice the double rewrite. It rewrites the url when the Upgrade header is present, and then rewrites it back, so that the url matches within django.