Author: Justin Karneges [email protected]
This library helps your Django application delegate long-lived HTTP/WebSocket connection management to a GRIP-compatible proxy such as Fanout Cloud or Pushpin.
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.:
# fanout cloud
GRIP_URL = 'http://api.fanout.io/realm/your-realm?iss=your-realm&key=base64:your-realm-key'# pushpin
GRIP_URL = 'http://localhost:5561'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'])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'])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.
If you need to communicate with more than one GRIP proxy (e.g. multiple Pushpin instances, or Fanout Cloud + Pushpin), you can use GRIP_PROXIES instead of GRIP_URL. For example:
GRIP_PROXIES = [
# pushpin
{
'control_uri': 'http://localhost:5561'
},
# fanout cloud
{
'key': b64decode('your-realm-key'),
'control_uri': 'http://api.fanout.io/realm/your-realm',
'control_iss': 'your-realm'
}
]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-'
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent