Skip to content

Commit 0637520

Browse files
mattmakaimattmakai
committed
major update to websockets page
1 parent 98c9bab commit 0637520

File tree

12 files changed

+627
-43
lines changed

12 files changed

+627
-43
lines changed

‎all.html‎

Lines changed: 55 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -4424,6 +4424,8 @@ <h1>Change Log</h1>
44244424
<h2>2015</h2>
44254425
<h3>January</h3>
44264426
<ul>
4427+
<li>Major update to <a href="/websockets.html">WebSockets page</a> with new diagrams
4428+
and better explanations for why server push is useful.</li>
44274429
<li>New task queue resources.</li>
44284430
<li>Major update with the beginning of a page on <a href="/docker.html">Docker</a>, split
44294431
out static file handling resources on the <a href="/django.html">Django</a> page
@@ -4824,19 +4826,33 @@ <h3>Resources for Python enterprise advocacy</h3>
48244826
<h2>What else would you like to know about Python?</h2>
48254827
<h1>WebSockets</h1>
48264828
<p>A WebSocket is a <a href="http://tools.ietf.org/html/rfc6455">standard protocol</a> for
4827-
two-way communication between servers and clients. The WebSockets protocol does
4828-
not run over HTTP, instead it is a separate implementation on top of
4829+
two-way data transfer between a client and server. The WebSockets protocol
4830+
does not run over HTTP, instead it is a separate implementation on top of
48294831
<a href="http://en.wikipedia.org/wiki/Transmission_Control_Protocol">TCP</a>.</p>
48304832
<h2>Why use WebSockets?</h2>
4831-
<p>WebSockets allow two-way communication between the client and server.
4832-
A WebSockets-enabled application allows a web server to push data to a web
4833-
browser without the browser having to poll for updates via HTTP. Allowing
4834-
push from the server to the client and vice versa is much more efficient than
4835-
having the client constantly ask the server "are there any updates?".</p>
4836-
<p>Previous approaches for for keeping a connection alive between client and
4837-
server over HTTP, such as
4838-
[Comet](http://en.wikipedia.org/wiki/Comet_(programming), have either used
4839-
long polling or were not implemented by all browsers.</p>
4833+
<p>A WebSocket connection allows full-duplex communication between a client
4834+
and server so that either side can push data to the other through an
4835+
established connection. The reason why WebSockets, along with the related
4836+
technologies of
4837+
<a href="http://en.wikipedia.org/wiki/Server-sent_events">Server-sent Events</a> (SSE)
4838+
and
4839+
<a href="https://tools.ietf.org/html/draft-ietf-rtcweb-data-channel-12">WebRTC data channels</a>,
4840+
are important is that HTTP is not meant for keeping open a connection for
4841+
the server to frequently push data to a web browser. Previously, most web
4842+
applications would implement long polling via frequent
4843+
Asynchronous JavaScript and XML (AJAX) requests as shown in the below diagram. </p>
4844+
<p><img src="theme/img/ajax-long-polling.png" width="100%" alt="Long polling via AJAX is incredibly inefficient for some applications." class="technical-diagram" /></p>
4845+
<p>Server push, as shown in the below diagram, is more efficient and scalable
4846+
than long polling because the web browser does not have to constantly ask for
4847+
updates through a stream of AJAX requests.</p>
4848+
<p><img src="theme/img/websockets-flow.png" width="100%" alt="WebSockets are more efficient than long polling for server sent updates." class="technical-diagram" /></p>
4849+
<p>The WebSockets approach for server pushed updates works well for certain
4850+
categories of web applications such as chat room, which is why that's often
4851+
the example application for a WebSocket library.</p>
4852+
<p>Both a JavaScript library on the web browser and a WebSockets
4853+
implementation on the server are necessary to establish and maintain the
4854+
connection between the client and server. Examples of JavaScript client
4855+
libraries and WSGI implementations can be found below.</p>
48404856
<h2>JavaScript client libraries</h2>
48414857
<ul>
48424858
<li>
@@ -4848,13 +4864,38 @@ <h2>JavaScript client libraries</h2>
48484864
client-side WebSockets implementation.</p>
48494865
</li>
48504866
</ul>
4851-
<h2>Websockets with Nginx</h2>
4867+
<h2>Nginx WebSocket proxying</h2>
48524868
<p>Nginx officially supports WebSocket proxying as of
48534869
<a href="http://nginx.com/blog/websocket-nginx/">version 1.3</a>. However, you have
48544870
to configure the Upgrade and Connection headers to ensure requests are
48554871
passed through Nginx to your WSGI server. It can be tricky to set this up
4856-
the first time. The following resources are helpful for setting up the
4857-
configuration properly.</p>
4872+
the first time. </p>
4873+
<p>Here are the configuration settings I use in my Nginx file as part of my
4874+
WebSockets proxy.</p>
4875+
<div class="codehilite"><pre><span class="n">server</span> <span class="p">{</span>
4876+
4877+
<span class="err">#</span> <span class="n">my</span> <span class="n">typical</span> <span class="n">web</span> <span class="n">server</span> <span class="n">configuration</span> <span class="n">goes</span> <span class="n">here</span>
4878+
4879+
<span class="err">#</span> <span class="n">this</span> <span class="n">is</span> <span class="n">specific</span> <span class="n">to</span> <span class="n">the</span> <span class="n">WebSockets</span> <span class="n">proxying</span>
4880+
<span class="n">location</span> <span class="o">/</span><span class="n">socket</span><span class="p">.</span><span class="n">io</span> <span class="p">{</span>
4881+
<span class="n">proxy_pass</span> <span class="n">http</span><span class="o">:</span><span class="c1">//app_server_wsgiapp/socket.io;</span>
4882+
<span class="n">proxy_redirect</span> <span class="n">off</span><span class="p">;</span>
4883+
4884+
<span class="n">proxy_set_header</span> <span class="n">Host</span> <span class="err">$</span><span class="n">host</span><span class="p">;</span>
4885+
<span class="n">proxy_set_header</span> <span class="n">X</span><span class="o">-</span><span class="n">Real</span><span class="o">-</span><span class="n">IP</span> <span class="err">$</span><span class="n">remote_addr</span><span class="p">;</span>
4886+
<span class="n">proxy_set_header</span> <span class="n">X</span><span class="o">-</span><span class="n">Forwarded</span><span class="o">-</span><span class="n">For</span> <span class="err">$</span><span class="n">proxy_add_x_forwarded_for</span><span class="p">;</span>
4887+
4888+
<span class="n">proxy_http_version</span> <span class="mf">1.1</span><span class="p">;</span>
4889+
<span class="n">proxy_set_header</span> <span class="n">Upgrade</span> <span class="err">$</span><span class="n">http_upgrade</span><span class="p">;</span>
4890+
<span class="n">proxy_set_header</span> <span class="n">Connection</span> <span class="s">&quot;upgrade&quot;</span><span class="p">;</span>
4891+
<span class="n">proxy_read_timeout</span> <span class="mi">600</span><span class="p">;</span>
4892+
<span class="p">}</span>
4893+
<span class="p">}</span>
4894+
</pre></div>
4895+
4896+
4897+
<p>The following resources are also helpful for setting up the configuration
4898+
properly.</p>
48584899
<ul>
48594900
<li>
48604901
<p>Nginx has <a href="http://nginx.org/en/docs/http/websocket.html">an official page for WebSocket proxying</a>.</p>

‎change-log.html‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,8 @@ <h1>Change Log</h1>
4646
<h2>2015</h2>
4747
<h3>January</h3>
4848
<ul>
49+
<li>Major update to <a href="/websockets.html">WebSockets page</a> with new diagrams
50+
and better explanations for why server push is useful.</li>
4951
<li>New task queue resources.</li>
5052
<li>Major update with the beginning of a page on <a href="/docker.html">Docker</a>, split
5153
out static file handling resources on the <a href="/django.html">Django</a> page

‎feeds/all.atom.xml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,2 @@
11
<?xml version="1.0" encoding="utf-8"?>
2-
<feed xmlns="http://www.w3.org/2005/Atom"><title>Matt Makai</title><link href="http://www.fullstackpython.com/" rel="alternate"></link><link href="http://www.fullstackpython.com/feeds/all.atom.xml" rel="self"></link><id>http://www.fullstackpython.com/</id><updated>2015-01-24T12:45:11Z</updated></feed>
2+
<feed xmlns="http://www.w3.org/2005/Atom"><title>Matt Makai</title><link href="http://www.fullstackpython.com/" rel="alternate"></link><link href="http://www.fullstackpython.com/feeds/all.atom.xml" rel="self"></link><id>http://www.fullstackpython.com/</id><updated>2015-01-25T12:39:17Z</updated></feed>

‎source/content/pages/11-misc/1104-change-log.markdown‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,8 @@ the
2424

2525
## 2015
2626
### January
27+
* Major update to [WebSockets page](/websockets.html) with new diagrams
28+
and better explanations for why server push is useful.
2729
* New task queue resources.
2830
* Major update with the beginning of a page on [Docker](/docker.html), split
2931
out static file handling resources on the [Django](/django.html) page

‎source/content/pages/12-next/1201-websockets.markdown‎

Lines changed: 58 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -18,22 +18,40 @@ choice4text:
1818

1919
# WebSockets
2020
A WebSocket is a [standard protocol](http://tools.ietf.org/html/rfc6455) for
21-
two-way communication between servers and clients. The WebSockets protocol does
22-
not run over HTTP, instead it is a separate implementation on top of
21+
two-way data transfer between a client and server. The WebSockets protocol
22+
does not run over HTTP, instead it is a separate implementation on top of
2323
[TCP](http://en.wikipedia.org/wiki/Transmission_Control_Protocol).
2424

2525

2626
## Why use WebSockets?
27-
WebSockets allow two-way communication between the client and server.
28-
A WebSockets-enabled application allows a web server to push data to a web
29-
browser without the browser having to poll for updates via HTTP. Allowing
30-
push from the server to the client and vice versa is much more efficient than
31-
having the client constantly ask the server "are there any updates?".
27+
A WebSocket connection allows full-duplex communication between a client
28+
and server so that either side can push data to the other through an
29+
established connection. The reason why WebSockets, along with the related
30+
technologies of
31+
[Server-sent Events](http://en.wikipedia.org/wiki/Server-sent_events) (SSE)
32+
and
33+
[WebRTC data channels](https://tools.ietf.org/html/draft-ietf-rtcweb-data-channel-12),
34+
are important is that HTTP is not meant for keeping open a connection for
35+
the server to frequently push data to a web browser. Previously, most web
36+
applications would implement long polling via frequent
37+
Asynchronous JavaScript and XML (AJAX) requests as shown in the below diagram.
3238

33-
Previous approaches for for keeping a connection alive between client and
34-
server over HTTP, such as
35-
[Comet](http://en.wikipedia.org/wiki/Comet_(programming), have either used
36-
long polling or were not implemented by all browsers.
39+
<img src="theme/img/ajax-long-polling.png" width="100%" alt="Long polling via AJAX is incredibly inefficient for some applications." class="technical-diagram" />
40+
41+
Server push, as shown in the below diagram, is more efficient and scalable
42+
than long polling because the web browser does not have to constantly ask for
43+
updates through a stream of AJAX requests.
44+
45+
<img src="theme/img/websockets-flow.png" width="100%" alt="WebSockets are more efficient than long polling for server sent updates." class="technical-diagram" />
46+
47+
The WebSockets approach for server pushed updates works well for certain
48+
categories of web applications such as chat room, which is why that's often
49+
the example application for a WebSocket library.
50+
51+
Both a JavaScript library on the web browser and a WebSockets
52+
implementation on the server are necessary to establish and maintain the
53+
connection between the client and server. Examples of JavaScript client
54+
libraries and WSGI implementations can be found below.
3755

3856

3957
## JavaScript client libraries
@@ -44,13 +62,39 @@ long polling or were not implemented by all browsers.
4462
client-side WebSockets implementation.
4563

4664

47-
## Websockets with Nginx
65+
## Nginx WebSocket proxying
4866
Nginx officially supports WebSocket proxying as of
4967
[version 1.3](http://nginx.com/blog/websocket-nginx/). However, you have
5068
to configure the Upgrade and Connection headers to ensure requests are
5169
passed through Nginx to your WSGI server. It can be tricky to set this up
52-
the first time. The following resources are helpful for setting up the
53-
configuration properly.
70+
the first time.
71+
72+
Here are the configuration settings I use in my Nginx file as part of my
73+
WebSockets proxy.
74+
75+
server {
76+
77+
# my typical web server configuration goes here
78+
79+
# this is specific to the WebSockets proxying
80+
location /socket.io {
81+
proxy_pass http://app_server_wsgiapp/socket.io;
82+
proxy_redirect off;
83+
84+
proxy_set_header Host $host;
85+
proxy_set_header X-Real-IP $remote_addr;
86+
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
87+
88+
proxy_http_version 1.1;
89+
proxy_set_header Upgrade $http_upgrade;
90+
proxy_set_header Connection "upgrade";
91+
proxy_read_timeout 600;
92+
}
93+
}
94+
95+
96+
The following resources are also helpful for setting up the configuration
97+
properly.
5498

5599
* Nginx has [an official page for WebSocket proxying](http://nginx.org/en/docs/http/websocket.html).
56100

0 commit comments

Comments
 (0)