Live updates
A message sent by one person shows up on every open page: the page opens one long-lived response with ypy-stream, and the server writes HTML patches into it.
The page
<script src="https://cdn.jsdelivr.net/gh/ypy-develop/[email protected]/dist/ypy.min.js"></script>
<script src="https://cdn.jsdelivr.net/gh/ypy-develop/[email protected]/dist/ext/ypy-stream.min.js"></script>
<section ypy-stream="/room/events">
<ul id="messages"></ul>
</section>
<form ypy-post="/room/messages" ypy-target="this" ypy-swap="innerHTML">
<input name="body" autocomplete="off" required>
<button>Send</button>
</form>The <section> opens GET /room/events when it loads and keeps the connection open. The form posts a message; the
answer to that request only clears the form, because the message itself arrives through the stream.
What the server answers
GET /room/events answers with a stream, not a fragment:
HTTP/1.1 200 OK
Content-Type: text/event-stream
Cache-Control: no-cacheThe first event is the whole current state, so a page that has just connected or reconnected is up to date. Without a
selector, a patch goes to the page element that has the same id as its top-level element:
event: ypy-patch-elements
id: 41
data: elements <ul id="messages">
data: elements <li>Helena: the deploy is out</li>
data: elements <li>Rui: confirmed, checking the logs</li>
data: elements </ul>
When someone sends a message, every open connection receives one more event. selector and mode say where the new
<li> goes:
event: ypy-patch-elements
id: 42
data: selector #messages
data: mode append
data: elements <li>Marta: logs look clean</li>
POST /room/messages answers with the form again, empty:
<input name="body" autocomplete="off" required>
<button>Send</button>Headers of the POST answer: Content-Type: text/html; charset=utf-8 and Vary: YPY-Request. An empty message gets
204 and nothing changes.
How it works
-
The stream is plain server-sent events. Each frame has an
event:name anddata:lines written askey value; a repeated key joins its values with a line feed. The namesypy-patch-elements,ypy-patch-signals,ypy-redirect,ypy-eventandypy-refreshare the ones the extension reads. An unknown name is ignored. -
mode appendadds the new<li>at the end of#messages. With no mode, the patch morphs the element with the sameid, which is what the first event does to bring the page up to date. -
The client sends
Last-Event-IDwith the lastid:it saw when it reconnects. The server answers with the full state again, so the page never has to remember what it missed. -
The connection reconnects by itself with a growing delay. It stays open while the tab is in the background, unless you set
stream.pauseOnBackground, which closes it until the tab is visible again. - Escape message text on the server. A patch is HTML, and it goes through the same checks as a swapped response.
Variations
-
For one client only, any handler that writes
text/event-streamworks: the extension reads the response of the request whatever started it.ypy-stream.post="/jobs/7/run"starts a stream with aPOST. -
To change signals as well as HTML, send
ypy-patch-signals. To send the page somewhere,ypy-redirect. To fire a named event on the page,ypy-event. -
A plain server-sent events endpoint works with the
ypy-sseextension, without the patch events. Each unnamed message is HTML swapped into the element:<ul ypy-sse:connect="/ticker" ypy-swap="beforeend"></ul>. Loadypy-streambeforeypy-ssewhen both are on the page. - For a state that changes, not just grows, polling is simpler and needs no open connection.