README.md in message_bus-2.2.0.pre.1 vs README.md in message_bus-2.2.0.pre.2

- old
+ new

@@ -127,10 +127,36 @@ curl -H "Content-Type: application/x-www-form-urlencoded" -X POST --data "/message=0" https://chat.samsaffron.com/message-bus/client-id/poll\?dlp\=t ``` You should see a reply with the messages of that channel you requested (in this case `/message`) starting at the message ID you requested (`0`). The URL parameter `dlp=t` disables long-polling: we do not want this request to stay open. +### Diagnostics + +MessageBus comes with a diagnostics interface, which you can access at `/message-bus/_diagnostics`. This interface allows you visibility into the runtime behaviour of message_bus. + +In order to use the diagnostics UI in your application, it is necessary to: + +* Enable it +* Define a user ID for requests +* Define a check for admin role + +as an example, you can do something like this: + +```ruby +MessageBus.enable_diagnostics # Must be called after `MessageBus.after_fork` if using a forking webserver + +MessageBus.user_id_lookup do |_env| + 1 +end + +MessageBus.is_admin_lookup do |_env| + true +end +``` + +Of course, in your real-world application, you would define these values according to your authentication/authorization logic. + ### Transport MessageBus ships with 3 transport mechanisms. 1. Long Polling with chunked encoding (streaming) @@ -193,10 +219,12 @@ MessageBus.publish "/global/channel", "will go to all sites" ``` ### Client support +#### JavaScript Client + MessageBus ships a simple ~300 line JavaScript library which provides an API to interact with the server. JavaScript clients can listen on any channel and receive messages via polling or long polling. You may simply include the source file (located in `assets/` within the message_bus source code): ```html @@ -236,14 +264,12 @@ MessageBus.subscribe("/channel", function(data){ // data shipped from server }, -3); ``` -There is also [a Ruby implementation of the client library](https://github.com/lowjoel/message_bus-client) available with an API very similar to that of the JavaScript client. +#### JavaScript Client settings -#### Client settings - All client settings are settable via `MessageBus.OPTION` Setting|Default|Info ----|---|---| enableLongPolling|true|Allow long-polling (provided it is enabled by the server) @@ -256,11 +282,11 @@ ajax|$.ajax falling back to XMLHttpRequest|MessageBus will first attempt to use jQuery and then fallback to a plain XMLHttpRequest version that's contained in the `message-bus-ajax.js` file. `message-bus-ajax.js` must be loaded after `message-bus.js` for it to be used. You may override this option with a function that implements an ajax request by some other means headers|{}|Extra headers to be include with requests. Properties and values of object must be valid values for HTTP Headers, i.e. no spaces or control characters. minHiddenPollInterval|1500|Time to wait between poll requests performed by background or hidden tabs and windows, shared state via localStorage enableChunkedEncoding|true|Allows streaming of message bus data over the HTTP connection without closing the connection after each message. -#### Client API +#### Javascript Client API `MessageBus.start()` : Starts up the MessageBus poller `MessageBus.subscribe(channel,func,lastId)` : Subscribes to a channel. You may optionally specify the id of the last message you received in the channel. The callback receives three arguments on message delivery: `func(payload, globalId, messageId)`. You may save globalId or messageId of received messages and use then at a later time when client needs to subscribe, receiving the backlog since that id. @@ -276,10 +302,50 @@ `MessageBus.noConflict()` : Removes MessageBus from the global namespace by replacing it with whatever was present before MessageBus was loaded. Returns a reference to the MessageBus object. `MessageBus.diagnostics()` : Returns a log that may be used for diagnostics on the status of message bus. +#### Ruby + +The gem ships with a Ruby implementation of the client library available with an +API very similar to that of the JavaScript client. It was inspired by +https://github.com/lowjoel/message_bus-client. + +```ruby +# Creates a client with the default configuration +client = MessageBus::HTTPClient.new('http://some.test.com') + +# Listen for the latest messages +client.subscribe("/channel") { |data| puts data } + +# Listen for all messages after id 7 +client.subscribe("/channel", last_message_id: 7) { |data| puts data } + +# Listen for last message and all new messages +client.subscribe("/channel", last_message_id: -2) { |data| puts data } + +# Unsubscribe from a channel +client.unsubscribe("/channel") + +# Unsubscribe a particular callback from a channel +callback = -> { |data| puts data } +client.subscribe("/channel", &callback) +client.unsubscribe("/channel", &callback) +``` + +#### Ruby Client Settings + +Setting|Default|Info +----|---|---| +enable_long_polling|true|Allow long-polling (provided it is enabled by the server) +background_callback_interval|60s|Interval to poll when long polling is disabled +min_poll_interval|0.1s|When polling requests succeed, this is the minimum amount of time to wait before making the next request. +max_poll_interval|180s|If request to the server start failing, MessageBus will backoff, this is the upper limit of the backoff. +enable_chunked_encoding|true|Allows streaming of message bus data over the HTTP connection without closing the connection after each message. +headers|{}|Extra headers to be include with requests. Properties and values of object must be valid values for HTTP Headers, i.e. no spaces or control characters. + + ## Configuration message_bus can be configured to use one of several available storage backends, and each has its own configuration options. ### Redis @@ -403,10 +469,22 @@ Rails.application.config do |config| # do anything you wish with config.middleware here end ``` +Specifically, if you use a Rack middleware-based authentication solution (such as Warden) in a Rails application and wish to use it for authenticating message_bus requests, you must ensure that the MessageBus middleware comes after it in the stack. Unfortunately, this can be difficult, but the following solution is known to work: + +```ruby +# config/initializers/message_bus.rb +Rails.application.config do |config| + # See https://github.com/rails/rails/issues/26303#issuecomment-442894832 + MyAppMessageBusMiddleware = Class.new(MessageBus::Rack::Middleware) + config.middleware.delete(MessageBus::Rack::Middleware) + config.middleware.insert_after(Warden::Manager, MyAppMessageBusMiddleware) +end +``` + ### A Distributed Cache MessageBus ships with an optional `DistributedCache` API which provides a simple and efficient way of synchronizing a cache between processes, based on the core of message_bus: ```ruby @@ -579,5 +657,13 @@ ### Generating the documentation Run `rake yard` (or `docker-compose run docs rake yard`) in order to generate the implementation's API docs in HTML format, and `open doc/index.html` to view them. While working on documentation, it is useful to automatically re-build it as you make changes. You can do `yard server --reload` (or `docker-compose up docs`) and `open http://localhost:8808` to browse live-built docs as you edit them. + +### Benchmarks + +Some simple benchmarks are implemented in `spec/performance` and can be executed using `rake performance` (or `docker-compose run tests rake performance`). You should run these before and after your changes to avoid introducing performance regressions. + +### Diagnostics Interface + +It is possible to manually test the diagnostics interface by executing `docker-compose up example` and then `open http://localhost:9292`.