Skip to content

Commit 808bc1a

Browse files
mattmakaimattmakai
committed
working to address errors and make clarifications recommended by Miguel in PR mattmakai#47 for WebSockets page
1 parent a8b31a2 commit 808bc1a

File tree

7 files changed

+385
-61
lines changed

7 files changed

+385
-61
lines changed

‎all.html‎

Lines changed: 40 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -4857,13 +4857,33 @@ <h2>Why use WebSockets?</h2>
48574857
web browser does not have to constantly ask for updates through a stream
48584858
of AJAX requests.</p>
48594859
<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>
4860-
<p>The WebSockets approach for server pushed updates works well for certain
4861-
categories of web applications such as chat room, which is why that's often
4862-
the example application for a WebSocket library.</p>
4863-
<p>Both a JavaScript library on the web browser and a WebSockets
4864-
implementation on the server are necessary to establish and maintain the
4865-
connection between the client and server. Examples of JavaScript client
4866-
libraries and WSGI implementations can be found below.</p>
4860+
<p>While the above diagram shows a server pushing data to the client, WebSockets
4861+
is a full-duplex connection so the client can also push data to the server
4862+
as shown in the diagram below.</p>
4863+
<p><img src="theme/img/websockets-flow-with-client-push.png" width="100%" alt="WebSockets also allow client push in addition to server pushed updates." class="technical-diagram" /></p>
4864+
<p>The WebSockets approach for server- and client-pushed updates works well for
4865+
certain categories of web applications such as chat room, which is why that's
4866+
often an example application for a WebSocket library.</p>
4867+
<h2>Implementing WebSockets</h2>
4868+
<p>Both the web browser and the server must implement the WebSockets protocol
4869+
to establish and maintain the connection. There are important implications for
4870+
servers since WebSockets connections are long lived, unlike typical HTTP
4871+
connections. </p>
4872+
<p>A multi-threaded or multi-process based server cannot scale appropriately for
4873+
WebSockets because it is designed to open a connection, handle a request as
4874+
quickly as possible and then close the connection. An asynchronous server such
4875+
as <a href="http://www.tornadoweb.org/en/stable/">Tornado</a> or
4876+
<a href="http://gunicorn.org/">Green Unicorn</a> monkey patched with
4877+
<a href="http://www.gevent.org/">gevent</a> is necessary for any practical WebSockets
4878+
server-side implementation.</p>
4879+
<p>On the client side, it is not necessary to use a JavaScript library for
4880+
WebSockets. Web browsers that implement WebSockets will expose all necessary
4881+
client-side functionality through the WebSockets object. However, a JavaScript
4882+
wrapper library can make a developer's life easier by implementing graceful
4883+
degradation (often falling back to long-polling when WebSockets are
4884+
not supported) and by providing a wrapper around browser-specific WebSocket
4885+
quirks. Examples of JavaScript client libraries and WSGI implementations
4886+
are found below.</p>
48674887
<h2>JavaScript client libraries</h2>
48684888
<ul>
48694889
<li>
@@ -4891,22 +4911,22 @@ <h2>Nginx WebSocket proxying</h2>
48914911

48924912
<span class="n">server</span> <span class="p">{</span>
48934913

4894-
<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>
4914+
<span class="err">#</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>
48954915

4896-
<span class="err">#</span> <span class="n">this</span> <span class="n">section</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>
4897-
<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>
4898-
<span class="n">proxy_pass</span> <span class="n">http</span><span class="o">:</span><span class="c1">//app_server_wsgiapp/socket.io;</span>
4899-
<span class="n">proxy_redirect</span> <span class="n">off</span><span class="p">;</span>
4916+
<span class="err">#</span> <span class="n">this</span> <span class="n">section</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>
4917+
<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>
4918+
<span class="n">proxy_pass</span> <span class="n">http</span><span class="o">:</span><span class="c1">//app_server_wsgiapp/socket.io;</span>
4919+
<span class="n">proxy_redirect</span> <span class="n">off</span><span class="p">;</span>
49004920

4901-
<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>
4902-
<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>
4903-
<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>
4921+
<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>
4922+
<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>
4923+
<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>
49044924

4905-
<span class="n">proxy_http_version</span> <span class="mf">1.1</span><span class="p">;</span>
4906-
<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>
4907-
<span class="n">proxy_set_header</span> <span class="n">Connection</span> <span class="s">&quot;upgrade&quot;</span><span class="p">;</span>
4908-
<span class="n">proxy_read_timeout</span> <span class="mi">600</span><span class="p">;</span>
4909-
<span class="p">}</span>
4925+
<span class="n">proxy_http_version</span> <span class="mf">1.1</span><span class="p">;</span>
4926+
<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>
4927+
<span class="n">proxy_set_header</span> <span class="n">Connection</span> <span class="s">&quot;upgrade&quot;</span><span class="p">;</span>
4928+
<span class="n">proxy_read_timeout</span> <span class="mi">600</span><span class="p">;</span>
4929+
<span class="p">}</span>
49104930
<span class="p">}</span>
49114931
</pre></div>
49124932

‎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-02-01T10:10:30Z</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-02-01T10:50:47Z</updated></feed>

‎source/content/pages/04-web-development/1201-websockets.markdown‎

Lines changed: 45 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -44,14 +44,39 @@ of AJAX requests.
4444

4545
<img src="theme/img/websockets-flow.png" width="100%" alt="WebSockets are more efficient than long polling for server sent updates." class="technical-diagram" />
4646

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.
47+
While the above diagram shows a server pushing data to the client, WebSockets
48+
is a full-duplex connection so the client can also push data to the server
49+
as shown in the diagram below.
5050

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.
51+
<img src="theme/img/websockets-flow-with-client-push.png" width="100%" alt="WebSockets also allow client push in addition to server pushed updates." class="technical-diagram" />
52+
53+
The WebSockets approach for server- and client-pushed updates works well for
54+
certain categories of web applications such as chat room, which is why that's
55+
often an example application for a WebSocket library.
56+
57+
58+
## Implementing WebSockets
59+
Both the web browser and the server must implement the WebSockets protocol
60+
to establish and maintain the connection. There are important implications for
61+
servers since WebSockets connections are long lived, unlike typical HTTP
62+
connections.
63+
64+
A multi-threaded or multi-process based server cannot scale appropriately for
65+
WebSockets because it is designed to open a connection, handle a request as
66+
quickly as possible and then close the connection. An asynchronous server such
67+
as [Tornado](http://www.tornadoweb.org/en/stable/) or
68+
[Green Unicorn](http://gunicorn.org/) monkey patched with
69+
[gevent](http://www.gevent.org/) is necessary for any practical WebSockets
70+
server-side implementation.
71+
72+
On the client side, it is not necessary to use a JavaScript library for
73+
WebSockets. Web browsers that implement WebSockets will expose all necessary
74+
client-side functionality through the WebSockets object. However, a JavaScript
75+
wrapper library can make a developer's life easier by implementing graceful
76+
degradation (often falling back to long-polling when WebSockets are
77+
not supported) and by providing a wrapper around browser-specific WebSocket
78+
quirks. Examples of JavaScript client libraries and WSGI implementations
79+
are found below.
5580

5681

5782
## JavaScript client libraries
@@ -80,22 +105,22 @@ WebSockets proxy.
80105

81106
server {
82107

83-
# my typical web server configuration goes here
108+
# typical web server configuration goes here
84109

85-
# this section is specific to the WebSockets proxying
86-
location /socket.io {
87-
proxy_pass http://app_server_wsgiapp/socket.io;
88-
proxy_redirect off;
110+
# this section is specific to the WebSockets proxying
111+
location /socket.io {
112+
proxy_pass http://app_server_wsgiapp/socket.io;
113+
proxy_redirect off;
89114

90-
proxy_set_header Host $host;
91-
proxy_set_header X-Real-IP $remote_addr;
92-
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
115+
proxy_set_header Host $host;
116+
proxy_set_header X-Real-IP $remote_addr;
117+
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
93118

94-
proxy_http_version 1.1;
95-
proxy_set_header Upgrade $http_upgrade;
96-
proxy_set_header Connection "upgrade";
97-
proxy_read_timeout 600;
98-
}
119+
proxy_http_version 1.1;
120+
proxy_set_header Upgrade $http_upgrade;
121+
proxy_set_header Connection "upgrade";
122+
proxy_read_timeout 600;
123+
}
99124
}
100125

101126

0 commit comments

Comments
 (0)