Documents MessageBus::Implementation interface

Documents MessageBus::Implementation interface

From 1666feece0bd8bcd9d75be08d954e7cc4fafeaf6 Mon Sep 17 00:00:00 2001
From: Ben Langfeld <blangfeld@powerhrg.com>
Date: Wed, 28 Nov 2018 15:02:59 -0200
Subject: [PATCH] Documents MessageBus::Implementation interface


diff --git a/lib/message_bus.rb b/lib/message_bus.rb
index 7627e84..d1e6501 100644
--- a/lib/message_bus.rb
+++ b/lib/message_bus.rb
@@ -16,13 +16,16 @@ if defined?(::Rails)
   require 'message_bus/rails/railtie'
 end
 
+# @see MessageBus::Implementation
 module MessageBus; end
 MessageBus::BACKENDS = {}
 class MessageBus::InvalidMessage < StandardError; end
 class MessageBus::BusDestroyed < StandardError; end
 
+# The main server-side interface to a message bus for the purposes of
+# configuration, publishing and subscribing
 module MessageBus::Implementation
-  # Configuration options hash
+  # @return [Hash<Symbol => Object>] Configuration options hash
   attr_reader :config
 
   # Like Mutex but safe for recursive calls
@@ -35,10 +38,13 @@ module MessageBus::Implementation
     @mutex = Synchronizer.new
   end
 
+  # @param [Boolean] val whether or not to cache static assets for the diagnostics pages
+  # @return [void]
   def cache_assets=(val)
     configure(cache_assets: val)
   end
 
+  # @return [Boolean] whether or not to cache static assets for the diagnostics pages
   def cache_assets
     if defined? @config[:cache_assets]
       @config[:cache_assets]
@@ -47,10 +53,14 @@ module MessageBus::Implementation
     end
   end
 
+  # @param [Logger] logger a logger object to be used by the bus
+  # @return [void]
   def logger=(logger)
     configure(logger: logger)
   end
 
+  # @return [Logger] the logger used by the bus. If not explicitly set,
+  #   is configured to log to STDOUT at INFO level.
   def logger
     return @config[:logger] if @config[:logger]
 
@@ -61,32 +71,47 @@ module MessageBus::Implementation
     logger
   end
 
+  # @return [Boolean] whether or not chunked encoding is enabled. If not
+  #   explicitly set, defaults to true.
   def chunked_encoding_enabled?
     @config[:chunked_encoding_enabled] == false ? false : true
   end
 
+  # @param [Boolean] val whether or not to enable chunked encoding
+  # @return [void]
   def chunked_encoding_enabled=(val)
     configure(chunked_encoding_enabled: val)
   end
 
+  # @return [Boolean] whether or not long polling is enabled. If not explicitly
+  #   set, defaults to true.
   def long_polling_enabled?
     @config[:long_polling_enabled] == false ? false : true
   end
 
+  # @param [Boolean] val whether or not to enable long polling
+  # @return [void]
   def long_polling_enabled=(val)
     configure(long_polling_enabled: val)
   end
 
-  # The number of simultanuous clients we can service
-  #  will revert to polling if we are out of slots
+  # @param [Integer] val The number of simultanuous clients we can service;
+  #   will revert to polling if we are out of slots
+  # @return [void]
   def max_active_clients=(val)
     configure(max_active_clients: val)
   end
 
+  # @return [Integer] The number of simultanuous clients we can service;
+  #   will revert to polling if we are out of slots. Defaults to 1000 if not
+  #   explicitly set.
   def max_active_clients
     @config[:max_active_clients] || 1000
   end
 
+  # @return [Boolean] whether or not Rack Hijack is enabled. If not explicitly
+  #   set, will default to true, unless we're on Passenger without the ability
+  #   to set the advertised_concurrency_level to 0.
   def rack_hijack_enabled?
     if @config[:rack_hijack_enabled].nil?
       enable = true
@@ -106,62 +131,102 @@ module MessageBus::Implementation
     @config[:rack_hijack_enabled]
   end
 
+  # @param [Boolean] val whether or not to enable Rack Hijack
+  # @return [void]
   def rack_hijack_enabled=(val)
     configure(rack_hijack_enabled: val)
   end
 
+  # @param [Integer] millisecs the long-polling interval in milliseconds
+  # @return [void]
   def long_polling_interval=(millisecs)
     configure(long_polling_interval: millisecs)
   end
 
+  # @return [Integer] the long-polling interval in milliseconds. If not
+  #   explicitly set, defaults to 25,000.
   def long_polling_interval
     @config[:long_polling_interval] || 25 * 1000
   end
 
+  # Disables publication to the bus
+  # @return [void]
   def off
     @off = true
   end
 
+  # Enables publication to the bus
+  # @return [void]
   def on
     @off = false
   end
 
+  # Overrides existing configuration
+  # @param [Hash<Symbol => Object>] config values to merge into existing config
+  # @return [void]
   def configure(config)
     @config.merge!(config)
   end
 
-  # Allow us to inject a redis db
+  # Overrides existing configuration, explicitly enabling the redis backend
+  # @param [Hash<Symbol => Object>] config values to merge into existing config
+  # @return [void]
   def redis_config=(config)
     configure(config.merge(backend: :redis))
   end
 
   alias redis_config config
 
+  # @yield [env] a routine to determine the site ID for a subscriber
+  # @yieldparam [optional, Rack::Request::Env] env the subscriber request environment
+  # @yieldreturn [optional, String] the site ID for the subscriber
+  # @return [void]
   def site_id_lookup(&blk)
     configure(site_id_lookup: blk) if blk
     @config[:site_id_lookup]
   end
 
+  # @yield [env] a routine to determine the user ID for a subscriber (authenticate)
+  # @yieldparam [optional, Rack::Request::Env] env the subscriber request environment
+  # @yieldreturn [optional, String, Integer] the user ID for the subscriber
+  # @return [void]
   def user_id_lookup(&blk)
     configure(user_id_lookup: blk) if blk
     @config[:user_id_lookup]
   end
 
+  # @yield [env] a routine to determine the group IDs for a subscriber
+  # @yieldparam [optional, Rack::Request::Env] env the subscriber request environment
+  # @yieldreturn [optional, Array<String,Integer>] the group IDs for the subscriber
+  # @return [void]
   def group_ids_lookup(&blk)
     configure(group_ids_lookup: blk) if blk
     @config[:group_ids_lookup]
   end
 
+  # @yield [env] a routine to determine if a request comes from an admin user
+  # @yieldparam [Rack::Request::Env] env the subscriber request environment
+  # @yieldreturn [Boolean] whether or not the request is from an admin user
+  # @return [void]
   def is_admin_lookup(&blk)
     configure(is_admin_lookup: blk) if blk
     @config[:is_admin_lookup]
   end
 
+  # @yield [env, e] a routine to handle exceptions raised when handling a subscriber request
+  # @yieldparam [Rack::Request::Env] env the subscriber request environment
+  # @yieldparam [Exception] e the exception that was raised
+  # @yieldreturn [optional, Array<(Integer,Hash,Array)>] a Rack response to be delivered
+  # @return [void]
   def on_middleware_error(&blk)
     configure(on_middleware_error: blk) if blk
     @config[:on_middleware_error]
   end
 
+  # @yield [env] a routine to determine extra headers to be set on a subscriber response
+  # @yieldparam [Rack::Request::Env] env the subscriber request environment
+  # @yieldreturn [Hash<String => String>] the extra headers to set on the response
+  # @return [void]
   def extra_response_headers_lookup(&blk)
     configure(extra_response_headers_lookup: blk) if blk
     @config[:extra_response_headers_lookup]
@@ -177,10 +242,14 @@ module MessageBus::Implementation
     @config[:on_disconnect]
   end
 
+  # @param [Boolean] val whether or not to allow broadcasting (debugging)
+  # @return [void]
   def allow_broadcast=(val)
     configure(allow_broadcast: val)
   end
 
+  # @return [Boolean] whether or not broadcasting is allowed. If not explicitly
+  #   set, defaults to false unless we're in Rails test or development mode.
   def allow_broadcast?
     @config[:allow_broadcast] ||=
       if defined? ::Rails
@@ -190,10 +259,14 @@ module MessageBus::Implementation
       end
   end
 
+  # @param [MessageBus::Backend::Base] pub_sub a configured backend
+  # @return [void]
   def reliable_pu

GitHub