Django GRIP
Author: Justin Karneges justin@fanout.io
This library helps your Django application delegate long-lived HTTP/WebSocket connection management to a GRIP-compatible proxy such as Pushpin or Fastly Fanout.
Setup
First, install this module:
pip install django-gripIn your settings.py, add the GripMiddleware:
MIDDLEWARE = [
'django_grip.GripMiddleware',
...
]The middleware handles parsing/generating GRIP headers and WebSocket-Over-HTTP events. It should be placed early in the stack.
Additionally, set GRIP_URL with your proxy settings, e.g.:
# pushpin
GRIP_URL = 'http://localhost:5561'# fastly
GRIP_VERIFY_KEY = """
[ ... public key ... ]
"""
GRIP_URL = 'https://api.fastly.com/service/your-service-id?verify-iss=fastly:your-service-id&key=your-api-token'Usage
HTTP streaming
from django.http import HttpResponse, HttpResponseNotAllowed
from gripcontrol import HttpStreamFormat
from django_grip import set_hold_stream, publish
def myendpoint(request):
if request.method == 'GET':
# if the request didn't come through a GRIP proxy, throw 501
if not request.grip_proxied:
return HttpResponse('Not Implemented\n', status=501)
# subscribe every incoming request to a channel in stream mode
resp = HttpResponse('[stream open]\n', content_type='text/plain')
set_hold_stream(request, 'test')
return resp
elif request.method == 'POST':
# publish data to subscribers
data = request.POST['data']
publish('test', HttpStreamFormat(data + '\n'))
return HttpResponse('Ok\n')
else:
return HttpResponseNotAllowed(['GET', 'POST'])HTTP long-polling
from django.http import HttpResponse, HttpResponseNotModified, HttpResponseNotAllowed
from gripcontrol import HttpResponseFormat
from django_grip import set_hold_response, publish
def myendpoint(request):
if request.method == 'GET':
# get object and its etag
obj = ...
etag = ...
# if object is unchanged, long-poll, else return object
inm = request.META.get('HTTP_IF_NONE_MATCH')
if inm == etag:
# subscribe request to channel, return status 304 after timeout
resp = HttpResponseNotModified()
set_hold_longpoll(request, 'test')
else:
resp = HttpResponse(obj.serialize())
resp['ETag'] = etag
return resp
elif request.method == 'POST':
data = request.POST['data']
# update object based on request, and get resulting object and its etag
obj = ...
etag = ...
# publish data to subscribers
headers = {'ETag': etag}
publish('test', HttpResponseFormat(obj.serialize(), headers=headers))
return HttpResponse('Ok\n')
else:
return HttpResponseNotAllowed(['GET', 'POST'])WebSockets
Here's an echo service with a broadcast endpoint:
from django.http import HttpResponse, HttpResponseNotAllowed
from gripcontrol import WebSocketMessageFormat
from django_grip import websocket_only, publish
# decorator means reject non-websocket-related requests. it also means we
# don't need to return an HttpResponse object. the middleware will take care
# of that for us.
@websocket_only
def echo(request):
# since we used the decorator, this will always be a non-None value
ws = request.wscontext
# if this is a new connection, accept it and subscribe it to a channel
if ws.is_opening():
ws.accept()
ws.subscribe('test')
# here we loop over any messages
while ws.can_recv():
message = ws.recv()
# if return value is None, then the connection is closed
if message is None:
ws.close()
break
# echo the message
ws.send(message)
def broadcast(request):
if request.method == 'POST':
# publish data to all clients that are connected to the echo endpoint
data = request.POST['data']
publish('test', WebSocketMessageFormat(data))
return HttpResponse('Ok\n')
else:
return HttpResponseNotAllowed(['POST'])The while loop is deceptive. It looks like it's looping for the lifetime of the WebSocket connection, but what it's really doing is looping through a batch of WebSocket messages that was just received via HTTP. Often this will be one message, and so the loop performs one iteration and then exits. Similarly, the ws object only exists for the duration of the handler invocation, rather than for the lifetime of the connection as you might expect. It may look like socket code, but it's all an illusion. 🎩
For details on the underlying protocol conversion, see the WebSocket-Over-HTTP Protocol spec.
Advanced settings
If you need to communicate with more than one GRIP proxy (e.g. multiple Pushpin instances, or Fastly Fanout + Pushpin), you can use GRIP_PROXIES instead of GRIP_URL. For example:
GRIP_PROXIES = [
# pushpin
{
'control_uri': 'http://localhost:5561'
},
# fastly
{
'control_uri': 'https://api.fastly.com/service/your-service-id',
'key': 'your-api-token',
'verify_iss': 'fastly:your-service-id'
}
]If it's possible for clients to access the Django app directly, without necessarily going through a GRIP proxy, then you may want to avoid sending GRIP instructions to those clients. An easy way to achieve this is with the GRIP_PROXY_REQUIRED setting. If set, then any direct requests that trigger a GRIP instruction response will be given a 501 Not Implemented error instead.
GRIP_PROXY_REQUIRED = TrueTo prepend a fixed string to all channels used for publishing and subscribing, set GRIP_PREFIX in your configuration:
GRIP_PREFIX = 'myapp-'
