Mercurial > prosody-modules

annotate mod_muc_eventsource/README.markdown @ 5920:254a21a104aa

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_server_contact_info: Backport from prosody trunk
author Matthew Wild <mwild1@gmail.com>
date Fri, 07 Jun 2024 16:14:58 +0100
parents 694b62d8a82f
children
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 ---
5899
694b62d8a82f various/README: Fix 'labels' metadata, should be a list
Kim Alvefur <zash@zash.se>
parents: 2883
diff changeset
2 labels:
694b62d8a82f various/README: Fix 'labels' metadata, should be a list
Kim Alvefur <zash@zash.se>
parents: 2883
diff changeset
3 - Stage-Beta
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
4 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
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
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 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
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
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 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
11
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 [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
13 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
14 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
15 [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 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
17
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 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
19 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
20 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
21 [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
22 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
23
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 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
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
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 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
28
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 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
30 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
31 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
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
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 ### 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
35
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 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
37 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
38 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
39
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 ### 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
41
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 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
43 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
44 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
45 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
46 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
47 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
48
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 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
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
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 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
53 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
54
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 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
56 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
57
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 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
59 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
60 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
61
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 **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
63 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
64 `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
65 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
66 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
67 `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
68 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
69 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
70
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 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
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 ------- --------------
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.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
76 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
77 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
78 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
79 ------- --------------