-
Notifications
You must be signed in to change notification settings - Fork 0
/
server_sent_events.yaws
201 lines (155 loc) · 8.75 KB
/
server_sent_events.yaws
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<meta name="keywords" content="Yaws"/>
<title>Yaws</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<link rel="stylesheet" type="text/css" href="stil.css"/>
<link rel="shortcut icon" href="/icons/yaws_y.gif" type="image/x-icon"/>
</head>
<body>
<div class="logo">
<img src="icons/yaws_head.gif" width="600" alt="YAWS"/>
</div>
<div id="sidebar">
<h4> Yaws </h4>
<div class=""> <a href="index.yaws" id="index" >Top Page</a> </div>
<div class=""> <a href="configuration.yaws" id="configuration">Build Config and Run</a></div>
<div class=""> <a href="dynamic.yaws" id="dynamic" >Dynamic Content</a> </div>
<div class=""> <a href="https://github.com/erlyaws/yaws/releases/" id="download">Download </a> </div>
<div class=""> <a href="contact.yaws" id="contact">Contact </a> </div>
<div class=""> <a href="doc.yaws" id="doc">Documentation</a> </div>
<div class=""> <a href="articles.yaws" id="resources">Articles</a> </div>
<h4> Examples </h4>
<div class=""> <a href="/json_intro.yaws">AJAX/JSON RPC</a></div>
<div class=""> <a href="/appmods.yaws">Appmods</a> </div>
<div class=""> <a href="/arg.yaws">Arg</a> </div>
<div class=""> <a href="/privbind.yaws">Binding to Privileged Ports</a></div>
<div class=""> <a href="/bindings.yaws">Bindings</a> </div>
<div class=""> <a href="/cgi.yaws">CGI</a></div>
<div class=""> <a href="/session.yaws">Cookie Sessions</a> </div>
<div class=""> <a href="/cookies.yaws">Cookies</a> </div>
<div class=""> <a href="/dynamic.yaws">Dynamic Content</a> </div>
<div class=""> <a href="/embed.yaws">Embedding Yaws</a></div>
<div class=""> <a href="/upload0.yaws">File Upload</a> </div>
<div class=""> <a href="/form.yaws">Forms</a> </div>
<div class=""> <a href="/haxe_intro.yaws">haXe Remoting</a></div>
<div class=""> <a href="/pcookie.yaws">Persistent Cookies</a> </div>
<div class=""> <a href="/query.yaws">Query Part of URL</a></div>
<div class=""> <a href="/rebar_release.yaws">Rebar Releases</a></div>
<div class=""> <a href="/redirect.yaws">Redirect</a> </div>
<div class="choosen"> <a href="/server_sent_events.yaws">Server-Sent Events</a> </div>
<div class=""> <a href="/ssi.yaws">Server Side Includes</a> </div>
<div class=""> <a href="/simple.yaws">Simple</a> </div>
<div class=""> <a href="/soap_intro.yaws">SOAP with Yaws</a></div>
<div class=""> <a href="/stream.yaws">Streaming Data</a> </div>
<div class=""> <a href="/websockets.yaws">Web Sockets</a> </div>
<a href="/shoppingcart/index.yaws">Tiny Shopping Cart</a>
<div class=""> <a href="/yapp_intro.yaws">Yaws Applications (yapps)</a></div>
<div class=""> <a href="/logger_mod.yaws">Write Your Own Logger</a></div>
<h4> Misc </h4>
<div class=""> <a href="/internals.yaws">Internals</a> </div>
</div>
<div id="entry">
<h1>Server-sent events</h1>
<p>HTTP is a client-server protocol — the client makes a request
and the server replies with a response. For some applications, though,
the request-reply model is limiting or unsuitable. These applications
tend to want server-to-client notification capabilities. While such
notifications can be simulated using polling, and web-based polling can
be much more efficient than one would think due to intermediary
caching, it's still less efficient and less timely than a notification
model.
</p>
<p>Yaws users have a few options for notification-oriented applications:</p>
<ul><li><p>Yaws supports an older technique called "long polling" or
"Comet" where the client sends a request that the server sits on and
doesn't answer until it actually has an event for the client. The problem
with long polling is that it requires the client and server applications
to be bound tightly to each other via the specialized ad hoc long-polling
protocol they share.</p></li>
<li><p><a href="websockets.yaws">The WebSockets protocol</a> (<a
href="https://tools.ietf.org/html/rfc6455">RFC 6455</a>) allows web client
and server to upgrade their TCP connection from using HTTP to using some
other protocol they agree on. The protocol they choose can be
bidirectional and can transmit whatever data transfer formats they wish
to use. WebSockets afford applications a great deal of freedom and
flexibility, but they also require client and server to agree on
specialized protocols, framing, and data formats to be able to
communicate successfully.</p></li>
<li><p><a href="https://www.w3.org/TR/eventsource/">Server-Sent Events</a>
(SSE) is a W3C working draft that unlike long polling is on a path to
standardization and unlike WebSockets is pretty simple. Despite being a
working draft, it's already fairly widely used. With SSE, a client sends a
standard HTTP request asking for an event stream, and the server responds
initially with a standard HTTP response and holds the connection
open. When appropriate, the server sends standard text-based event data
back to the client as part of the initial response, and continues to do
so until either end closes the connection. Clients can disconnect and
later reconnect, indicate the last event they received, and pick up new
events from that point.</p></li> </ul>
<p>Currently, Chrome, Firefox, Opera, and Safari support SSE. Older
browsers do not support SSE directly, but they can be made to do so with
suitable JavaScript packages.</p>
<h2>Writing a Yaws SSE application</h2>
<p>Yaws supports SSE through its <a href="stream.yaws">streaming
capabilities</a>. SSE applications typically consist of an entry point
page and an appmod. The entry page returns HTML and JavaScript that acts
as the SSE client, with the JavaScript invoking the appmod's
<code>out/1</code> function that creates a streaming process responsible
for sending events back to the client. The appmod uses the
<code>yaws_sse</code> module to properly format and send its event
data.</p>
<p>Yaws supplies an example that uses SSE to return the server's time of
day clock to the client. Each second, the server sends a new event to the
client updating its time of day, which the client dynamically displays in
a web page.</p>
<p><em>Note: if you're running this on your own Yaws installation, make
sure your server configuration includes the following appmod
entry:</em><p>
<p><code>appmods = <"/sse", server_sent_events></code></p>
<p><em>and also make sure <code>server_sent_events.beam</code> is on the
Yaws load path, which it should be if you followed regular installation
procedures.</em></p>
<p>First, the entry HTML page is here: <a
href="server_sent_events.html">server_sent_events.html</a>. It presents
a page title and a placeholder for the server date string. It also
supplies a bit of JavaScript that receives events from Yaws, using the
browser's <code>EventSource</code> JavaScript class to receive them. It
then pulls the data out of the event and displays it dynamically in the
HTML.</p>
<p>Next, the server appmod code is here: <a
href="https://github.com/erlyaws/yaws/blob/master/examples/src/server_sent_events.erl">
server_sent_events.erl</a>. Its <code>out/1</code> function create a
gen_server event generation process, returning the pid in a
<code>streamcontent_from_pid</code> directive to Yaws along with suitable
headers. Note that it obtains the desired <code>out/1</code> return value
via the <code>yaws_sse:headers/1</code> function. Its gen_server is
fairly simple in that it creates a timer that, once per second, generates
a time of day string and sends it as an event to the client formatted via
the <code>yaws_sse:data/1</code> function.</p>
<p>The <code>yaws_sse</code> module supplies all the SSE primitives
required for formatting event data, event identifiers, and event retry
settings. See the <a href="https://www.w3.org/TR/eventsource/">Server-Sent
Events</a> working draft for more details on using these features.</p>
<p>The <code>yaws_sse</code> module also supplies functions for
formatting and sending event data on a socket. If you're using the
<code>yaws_sse</code> module outside of a Yaws streaming application, you
should use the arity 3 version of <code>yaws_sse:send_events</code> and
pass <code>fun yaws:gen_tcp_send/2</code> as the third argument.</p>
<p><strong>Note:</strong> be aware that because the W3C Server-Sent
Events spec is still a working draft, any future changes in it might
cause API-incompatible changes in how Yaws supports it.</p>
</div>
<div class="logo">
<img src="/icons/yaws_pb.gif" alt="pbyaws" />
</div>
<p>
<a href="https://validator.w3.org/check?uri=referer"><img
src="https://www.w3.org/Icons/valid-xhtml10"
alt="Valid XHTML 1.0!" height="31" width="88" /></a>
</p>
</body>
</html>