Mercurial > prosody-modules

annotate mod_muc_eventsource/README.markdown @ 4974:807007913f67

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_log_json: Prefer native Lua table.pack over Prosody util.table one Prosody is removing support for Lua 5.1, which was the reason for util.table.pack to exist in the first place, since Lua 5.2+ provides table.pack. In prosody rev 5eaf77114fdb everything was switched over to use table.pack, opening the door for removing util.table.pack at some point. This change here is to prepare for that future eventuality.
author Kim Alvefur <zash@zash.se>
date Mon, 11 Jul 2022 20:08:41 +0200
parents 7c16afc70d11
children 694b62d8a82f
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
2883
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
1 ---
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
2 labels: 'Stage-Beta'
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
3 summary: Subscribe to MUC rooms using the HTML5 EventSource API
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
4 ...
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
5
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
6 Introduction
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
7 ------------
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
8
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
9 This module and its docs shamelessly forked from mod_pubsub_eventsource.
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
10
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
11 [Server-Sent Events](https://en.wikipedia.org/wiki/Server-sent_events)
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
12 is a simple HTTP/line-based protocol supported in HTML5, making it easy
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
13 to receive a stream of "events" in realtime using the Javascript
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
14 [EventSource
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
15 API](https://developer.mozilla.org/en-US/docs/Web/API/EventSource).
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
16
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
17 EventSource is supported in [most modern
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
18 browsers](http://caniuse.com/#feat=eventsource), and for the remainder
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
19 there are 'polyfill' compatibility layers such as
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
20 [EventSource.js](https://github.com/remy/polyfills/blob/master/EventSource.js)
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
21 and [jquery.eventsource](https://github.com/rwldrn/jquery.eventsource).
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
22
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
23 Details
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
24 -------
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
25
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
26 Subscribing to a node from Javascript is easy:
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
27
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
28 var source = new EventSource('http://muc.example.org:5280/eventsource/myroom');
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
29 source.onmessage = function (event) {
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
30 console.log(event.data); // Do whatever you want with the data here
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
31 };
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
32
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
33 ### Access control
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
34
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
35 Be warned that this module currently performs no access control. It will expose
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
36 the messages of ALL rooms on the host it is loaded on. This may be changed in
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
37 future revisions.
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
38
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
39 ### Cross-domain issues
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
40
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
41 The same cross-domain restrictions apply to EventSource that apply to
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
42 BOSH, and support for CORS is not clearly standardized yet. You may want
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
43 to proxy connections through your web server for this reason. See [BOSH:
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
44 Cross-domain
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
45 issues](https://prosody.im/doc/setting_up_bosh#proxying_requests) for
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
46 more information.
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
47
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
48 Configuration
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
49 -------------
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
50
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
51 There is no special configuration for this module. Simply load it onto a
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
52 MUC component like so:
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
53
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
54 Component "muc.example.org" "muc"
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
55 modules_enabled = { "muc_eventsource" }
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
56
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
57 As it uses HTTP to serve the event streams, you can use Prosody's
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
58 standard [HTTP configuration options](https://prosody.im/doc/http) to
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
59 control how/where the streams are served.
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
60
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
61 **Note about URLs:** It is important to get the event streams from the
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
62 correct hostname (that of the MUC host). An example stream URL is
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
63 `http://muc.example.org:5280/eventsource/myroom`. If you need to
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
64 access the streams using another hostname (e.g. `example.org`) you can
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
65 use the `http_host` option under the Component, e.g.
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
66 `http_host = "example.org"`. For more information see the ['Virtual
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
67 Hosts'](https://prosody.im/doc/http#virtual_hosts) section of our HTTP
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
68 documentation.
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
69
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
70 Compatibility
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
71 -------------
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
72
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
73 ------- --------------
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
74 0.10 ?
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
75 0.9 ?
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
76 0.8 Doesn't work
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
77 Trunk Works
7c16afc70d11 mod_muc_eventsource: New module forked from mod_pubsub_eventsource, exposes room message stream over SSE
Matthew Wild <mwild1@gmail.com>
parents:
diff changeset
78 ------- --------------