view mod_muc_eventsource/README.markdown @ 5381:32a9817c7516

mod_firewall: Initialize compiled chunk just once for all handlers This should fix a case where some stateful dependencies (such as throttles) produce separate instances for every call to new_handler(), leading to surprising behaviour (e.g. rules executed via JUMP CHAIN vs ::deliver would have separate rate limits). This also adds better error handling in case the compiled code fails to run for some reason.
author Matthew Wild <mwild1@gmail.com>
date Fri, 28 Apr 2023 13:27:06 +0100
parents 7c16afc70d11
children 694b62d8a82f
line wrap: on
line source

---
labels: 'Stage-Beta'
summary: Subscribe to MUC rooms using the HTML5 EventSource API
...

Introduction
------------

This module and its docs shamelessly forked from mod_pubsub_eventsource.

[Server-Sent Events](https://en.wikipedia.org/wiki/Server-sent_events)
is a simple HTTP/line-based protocol supported in HTML5, making it easy
to receive a stream of "events" in realtime using the Javascript
[EventSource
API](https://developer.mozilla.org/en-US/docs/Web/API/EventSource).

EventSource is supported in [most modern
browsers](http://caniuse.com/#feat=eventsource), and for the remainder
there are 'polyfill' compatibility layers such as
[EventSource.js](https://github.com/remy/polyfills/blob/master/EventSource.js)
and [jquery.eventsource](https://github.com/rwldrn/jquery.eventsource).

Details
-------

Subscribing to a node from Javascript is easy:

    var source = new EventSource('http://muc.example.org:5280/eventsource/myroom');
    source.onmessage = function (event) {
      console.log(event.data); // Do whatever you want with the data here
    };

### Access control

Be warned that this module currently performs no access control. It will expose
the messages of ALL rooms on the host it is loaded on. This may be changed in
future revisions.

### Cross-domain issues

The same cross-domain restrictions apply to EventSource that apply to
BOSH, and support for CORS is not clearly standardized yet. You may want
to proxy connections through your web server for this reason. See [BOSH:
Cross-domain
issues](https://prosody.im/doc/setting_up_bosh#proxying_requests) for
more information.

Configuration
-------------

There is no special configuration for this module. Simply load it onto a
MUC component like so:

    Component "muc.example.org" "muc"
      modules_enabled = { "muc_eventsource" }

As it uses HTTP to serve the event streams, you can use Prosody's
standard [HTTP configuration options](https://prosody.im/doc/http) to
control how/where the streams are served.

**Note about URLs:** It is important to get the event streams from the
correct hostname (that of the MUC host). An example stream URL is
`http://muc.example.org:5280/eventsource/myroom`. If you need to
access the streams using another hostname (e.g. `example.org`) you can
use the `http_host` option under the Component, e.g.
`http_host = "example.org"`. For more information see the ['Virtual
Hosts'](https://prosody.im/doc/http#virtual_hosts) section of our HTTP
documentation.

Compatibility
-------------

  ------- --------------
  0.10    ?
  0.9     ?
  0.8     Doesn't work
  Trunk   Works
  ------- --------------