- BUNDLED FILES
- SOURCE REPOSITORY
- COPYRIGHT AND LICENSE
Mojolicious::Plugin::Multiplex - A websocket multiplexing layer for Mojolicious applications
This module is in its infancy and things can and will change in incompatible ways until this warning is removed. That said, the author is using it for real work so hopefully incompatible changes will be minimal (for his own sanity).
Their proposal only includes a partially implemented reference implementation. This module extends the protocol slightly in order to enough of the "WebSocket API" to be useful. More extensions may be necessary if the API is to be completely implemented, however those last few details are rarely used and will likely not be missed.
On the server-side the logic is entirely up to the application author. The module simply parses the multiplexed messages and emits events in accordance with them. A typical use case may be to relay message to a bus, subscribing and unsubscribing from topics that it presents. Another might be to stream updates to multiple types of data (perhaps in multiple parts of a single page application). (Indeed those might not be distinct cases from each other).
my $multiplex = $c->multiplex;
Establishes the WebSocket connection (if it hasn't been already) and returns an instance of Mojolicious::Plugin::Multiplex::Multiplexer. The multiplexer is attached to the websocket stream and begins listening for messages. The multiplexer emits events for incoming messages and has methods to send outgoing messages; more details about those are contained in its own documentation.
Note that for each websocket connection the same instance of the multiplexer will be returned on any subsequent call. Though not prevented, the user is highly discouraged from sending other traffic over any websocket connection that is managed by a multiplexer.
websocket_multiplex.js. It provides the new class
WebSocketMultiplex whose constructor takes as its only argument an existing WebSocket object. This then is used to open new channel objects via the
channel method which takes a topic string as an arugment. Topics can be almost any string, however they must not contain a comma (a limitation of the protocol). The resulting channel objects implement the same API as a WebSocket (though they do not inherit from it).
The client-side multiplexer will also attempt to reconnect to closed sockets and when successful will automatically resubscribe to the channels that were subscribed.
N.B. This library is the least stable of the entire project. Use with caution.
Joel Berger, <firstname.lastname@example.org>
Copyright (C) 2016 by Joel Berger
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.