Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 123 lines (98 sloc) 5.895 kb
c4fd143 @vinoski add support for W3C Server-Sent Events
vinoski authored
1 <erl>
2
3 out(A) ->
4 {ssi, "TAB.inc", "%%",[{"sse", "choosen"}]}.
5
6
7 </erl>
8
9 <div id="entry">
10
11 <h1>Server-sent events</h1>
12
13 <p>HTTP is a client-server protocol &mdash; the client makes a request
14 and the server replies with a response. For some applications, though,
15 the request-reply model is limiting or unsuitable. These applications
16 tend to want server-to-client notification capabilities. While such
17 notifications can be simulated using polling, and web-based polling can
18 be much more efficient than one would think due to intermediary
19 caching, it's still less efficient and less timely than a notification
20 model.
21 </p>
22
23 <p>Yaws users have a few options for notification-oriented applications:</p>
24
25 <ul><li><p>Yaws supports an older technique called "long polling" or
26 "Comet" where the client sends a request that the server sits on and
27 doesn't answer until it actually has an event for the client. The problem
28 with long polling is that it requires the client and server applications
29 to be bound tightly to each other via the specialized ad hoc long-polling
30 protocol they share.</p></li>
31
32 <li><p><a href="websockets.yaws">The WebSockets protocol</a> (<a
33 href="http://tools.ietf.org/html/rfc6455">RFC 6455</a>) allows web client
34 and server to upgrade their TCP connection from using HTTP to using some
35 other protocol they agree on. The protocol they choose can be
36 bidirectional and can transmit whatever data transfer formats they wish
37 to use. WebSockets afford applications a great deal of freedom and
38 flexibility, but they also require client and server to agree on
39 specialized protocols, framing, and data formats to be able to
40 communicate successfully.</p></li>
41
42 <li><p><a href="http://www.w3.org/TR/eventsource/">Server-Sent Events</a>
43 (SSE) is a W3C working draft that unlike long polling is on a path to
44 standardization and unlike WebSockets is pretty simple. Despite being a
fd81730 @tuncer Fix trivial typo in server_sent_events.yaws
tuncer authored
45 working draft, it's already fairly widely used. With SSE, a client sends a
c4fd143 @vinoski add support for W3C Server-Sent Events
vinoski authored
46 standard HTTP request asking for an event stream, and the server responds
47 initially with a standard HTTP response and holds the connection
48 open. When appropriate, the server sends standard text-based event data
49 back to the client as part of the initial response, and continues to do
50 so until either end closes the connection. Clients can disconnect and
51 later reconnect, indicate the last event they received, and pick up new
52 events from that point.</p></li> </ul>
53
54 <p>Currently, Chrome, Firefox, Opera, and Safari support SSE. Older
55 browsers do not support SSE directly, but they can be made to do so with
56 suitable JavaScript packages.</p>
57
58 <h2>Writing a Yaws SSE application</h2>
59
60 <p>Yaws supports SSE through its <a href="stream.yaws">streaming
61 capabilities</a>. SSE applications typically consist of an entry point
62 page and an appmod. The entry page returns HTML and JavaScript that acts
63 as the SSE client, with the JavaScript invoking the appmod's
64 <code>out/1</code> function that creates a streaming process responsible
65 for sending events back to the client. The appmod uses the
66 <code>yaws_sse</code> module to properly format and send its event
67 data.</p>
68
69 <p>Yaws supplies an example that uses SSE to return the server's time of
70 day clock to the client. Each second, the server sends a new event to the
71 client updating its time of day, which the client dynamically displays in
72 a web page.</p>
73
d6e7d36 @vinoski add note about the sse appmod to the Server-Sent Events yaws page
vinoski authored
74 <p><em>Note: if you're running this on your own Yaws installation, make
75 sure your server configuration includes the following appmod
76 entry:</em><p>
77
78 <p><code>appmods = &lt;"/sse", server_sent_events&gt;</code></p>
79
80 <p><em>and also make sure <code>server_sent_events.beam</code> is on the
81 Yaws load path, which it should be if you followed regular installation
82 procedures.</em></p>
83
c4fd143 @vinoski add support for W3C Server-Sent Events
vinoski authored
84 <p>First, the entry HTML page is here: <a
85 href="server_sent_events.html">server_sent_events.html</a>. It presents
86 a page title and a placeholder for the server date string. It also
87 supplies a bit of JavaScript that receives events from Yaws, using the
88 browser's <code>EventSource</code> JavaScript class to receive them. It
89 then pulls the data out of the event and displays it dynamically in the
90 HTML.</p>
91
92 <p>Next, the server appmod code is here: <a
d6e7d36 @vinoski add note about the sse appmod to the Server-Sent Events yaws page
vinoski authored
93 href="https://github.com/klacke/yaws/blob/master/examples/src/server_sent_events.erl">
94 server_sent_events.erl</a>. Its <code>out/1</code> function create a
95 gen_server event generation process, returning the pid in a
96 <code>streamcontent_from_pid</code> directive to Yaws along with suitable
97 headers. Note that it obtains the desired <code>out/1</code> return value
98 via the <code>yaws_sse:headers/1</code> function. Its gen_server is
99 fairly simple in that it creates a timer that, once per second, generates
100 a time of day string and sends it as an event to the client formatted via
101 the <code>yaws_sse:data/1</code> function.</p>
c4fd143 @vinoski add support for W3C Server-Sent Events
vinoski authored
102
103 <p>The <code>yaws_sse</code> module supplies all the SSE primitives
104 required for formatting event data, event identifiers, and event retry
105 settings. See the <a href="http://www.w3.org/TR/eventsource/">Server-Sent
106 Events</a> working draft for more details on using these features.</p>
107
108 <p>The <code>yaws_sse</code> module also supplies functions for
109 formatting and sending event data on a socket. If you're using the
110 <code>yaws_sse</code> module outside of a Yaws streaming application, you
111 should use the arity 3 version of <code>yaws_sse:send_events</code> and
112 pass <code>fun yaws:gen_tcp_send/2</code> as the third argument.</p>
113
114 <p><strong>Note:</strong> be aware that because the W3C Server-Sent
115 Events spec is still a working draft, any future changes in it might
116 cause API-incompatible changes in how Yaws supports it.</p>
117
118 </div>
119
120 <erl>
121 out(A) -> {ssi, "END2",[],[]}.
122 </erl>
Something went wrong with that request. Please try again.