message_bus 2.1.6 → 2.2.0.pre

data/lib/message_bus/client.rb

@@ -1,9 +1,40 @@
 # frozen_string_literal: true
-class MessageBus::Client
-  attr_accessor :client_id, :user_id, :group_ids, :connect_time,
-                :subscribed_sets, :site_id, :cleanup_timer,
-                :async_response, :io, :headers, :seq, :use_chunked
 
+# Represents a connected subscriber and delivers published messages over its
+# connected socket.
+class MessageBus::Client
+  # @return [String] the unique ID provided by the client
+  attr_accessor :client_id
+  # @return [String,Integer] the user ID the client was authenticated for
+  attr_accessor :user_id
+  # @return [Array<String,Integer>] the group IDs the authenticated client is a member of
+  attr_accessor :group_ids
+  # @return [Time] the time at which the client connected
+  attr_accessor :connect_time
+  # @return [String] the site ID the client was authenticated for; used for hosting multiple
+  attr_accessor :site_id
+  # @return [MessageBus::TimerThread::Cancelable] a timer job that is used to
+  #   auto-disconnect the client at the configured long-polling interval
+  attr_accessor :cleanup_timer
+  # @return [Thin::AsyncResponse, nil]
+  attr_accessor :async_response
+  # @return [IO] the HTTP socket the client is connected on
+  attr_accessor :io
+  # @return [Hash<String => String>] custom headers to include in HTTP responses
+  attr_accessor :headers
+  # @return [Integer] the connection sequence number the client provided when connecting
+  attr_accessor :seq
+  # @return [Boolean] whether or not the client should use chunked encoding
+  attr_accessor :use_chunked
+
+  # @param [Hash] opts
+  # @option opts [String] :client_id the unique ID provided by the client
+  # @option opts [String,Integer] :user_id (`nil`) the user ID the client was authenticated for
+  # @option opts [Array<String,Integer>] :group_ids (`[]`) the group IDs the authenticated client is a member of
+  # @option opts [String] :site_id (`nil`) the site ID the client was authenticated for; used for hosting multiple
+  #   applications or instances of an application against a single message_bus
+  # @option opts [#to_i] :seq (`0`) the connection sequence number the client provided when connecting
+  # @option opts [MessageBus::Instance] :message_bus (`MessageBus`) a specific instance of message_bus
   def initialize(opts)
     self.client_id = opts[:client_id]
     self.user_id = opts[:user_id]
@@ -17,11 +48,14 @@ class MessageBus::Client
     @chunks_sent = 0
   end
 
+  # @yield executed with a lock on the Client instance
+  # @return [void]
   def synchronize
     @lock.synchronize { yield }
   end
 
-  def cancel
+  # Closes the client connection
+  def close
     if cleanup_timer
       # concurrency may nil cleanup timer
       cleanup_timer.cancel rescue nil
@@ -30,10 +64,12 @@ class MessageBus::Client
     ensure_closed!
   end
 
-  def in_async?
-    @async_response || @io
-  end
-
+  # Delivers a backlog of messages to the client, if there is anything in it.
+  # If chunked encoding/streaming is in use, will keep the connection open;
+  # if not, will close it.
+  #
+  # @param [Array<MessageBus::Message>] backlog the set of messages to deliver
+  # @return [void]
   def deliver_backlog(backlog)
     if backlog.length > 0
       if use_chunked
@@ -44,53 +80,41 @@ class MessageBus::Client
     end
   end
 
+  # If no data has yet been sent to the client, sends an empty chunk; prevents
+  # clients from entering a timeout state if nothing is delivered initially.
   def ensure_first_chunk_sent
     if use_chunked && @chunks_sent == 0
       write_chunk("[]")
     end
   end
 
-  def ensure_closed!
-    return unless in_async?
-    if use_chunked
-      write_chunk("[]")
-      if @io
-        @io.write("0\r\n\r\n")
-        @io.close
-        @io = nil
-      end
-      if @async_response
-        @async_response << ("0\r\n\r\n")
-        @async_response.done
-        @async_response = nil
-      end
-    else
-      write_and_close "[]"
-    end
-  rescue
-    # we may have a dead socket, just nil the @io
-    @io = nil
-    @async_response = nil
-  end
-
-  def close
-    ensure_closed!
-  end
-
+  # @return [Boolean] whether the connection is closed or not
   def closed?
     !@async_response && !@io
   end
 
+  # Subscribes the client to messages on a channel, optionally from a
+  # defined starting point.
+  #
+  # @param [String] channel the channel to subscribe to
+  # @param [Integer, nil] last_seen_id the ID of the last message the client
+  #   received. If nil, will be subscribed from the head of the backlog.
+  # @return [void]
   def subscribe(channel, last_seen_id)
     last_seen_id = nil if last_seen_id == ""
     last_seen_id ||= @bus.last_id(channel)
     @subscriptions[channel] = last_seen_id.to_i
   end
 
+  # @return [Hash<String => Integer>] the active subscriptions, mapping channel
+  #   names to last seen message IDs
   def subscriptions
     @subscriptions
   end
 
+  # Delivers a message to the client, even if it's empty
+  # @param [MessageBus::Message, nil] msg the message to deliver
+  # @return [void]
   def <<(msg)
     json = messages_to_json([msg])
     if use_chunked
@@ -100,10 +124,9 @@ class MessageBus::Client
     end
   end
 
-  def subscriptions
-    @subscriptions
-  end
-
+  # @param [MessageBus::Message] msg the message in question
+  # @return [Boolean] whether or not the client has permission to receive the
+  #   passed message
   def allowed?(msg)
     allowed = !msg.user_ids || msg.user_ids.include?(self.user_id)
     allowed &&= !msg.client_ids || msg.client_ids.include?(self.client_id)
@@ -116,6 +139,11 @@ class MessageBus::Client
     )
   end
 
+  # @return [Array<MessageBus::Message>] the set of messages the client is due
+  #   to receive, based on its subscriptions and permissions. Includes status
+  #   message if any channels have no messages available and the client
+  #   requested a message newer than the newest on the channel, or when there
+  #   are messages available that the client doesn't have permission for.
   def backlog
     r = []
     new_message_ids = nil
@@ -130,6 +158,7 @@ class MessageBus::Client
       end
 
       next if id < 0
+
       messages = @bus.backlog(k, id, site_id)
 
       if messages.length == 0
@@ -162,7 +191,7 @@ class MessageBus::Client
     r || []
   end
 
-  protected
+  private
 
   # heavily optimised to avoid all uneeded allocations
   NEWLINE = "\r\n".freeze
@@ -180,6 +209,7 @@ class MessageBus::Client
     @io.write(HTTP_11)
     @headers.each do |k, v|
       next if k == "Content-Type"
+
       @io.write(k)
       @io.write(COLON_SPACE)
       @io.write(v)
@@ -244,7 +274,35 @@ class MessageBus::Client
     end
   end
 
+  def ensure_closed!
+    return unless in_async?
+
+    if use_chunked
+      write_chunk("[]")
+      if @io
+        @io.write("0\r\n\r\n")
+        @io.close
+        @io = nil
+      end
+      if @async_response
+        @async_response << ("0\r\n\r\n")
+        @async_response.done
+        @async_response = nil
+      end
+    else
+      write_and_close "[]"
+    end
+  rescue
+    # we may have a dead socket, just nil the @io
+    @io = nil
+    @async_response = nil
+  end
+
   def messages_to_json(msgs)
     MessageBus::Rack::Middleware.backlog_to_json(msgs)
   end
+
+  def in_async?
+    @async_response || @io
+  end
 end

data/lib/message_bus/connection_manager.rb

@@ -1,10 +1,14 @@
 # frozen_string_literal: true
+
 require 'json' unless defined? ::JSON
 
+# Manages a set of subscribers with active connections to the server, such that
+# messages which are published during the connection may be dispatched.
 class MessageBus::ConnectionManager
   require 'monitor'
   include MonitorMixin
 
+  # @param [MessageBus::Instance] bus the message bus for which to manage connections
   def initialize(bus = nil)
     @clients = {}
     @subscriptions = {}
@@ -12,6 +16,9 @@ class MessageBus::ConnectionManager
     mon_initialize
   end
 
+  # Dispatches a message to any connected clients which are permitted to receive it
+  # @param [MessageBus::Message] msg the message to dispatch
+  # @return [void]
   def notify_clients(msg)
     synchronize do
       begin
@@ -34,37 +41,42 @@ class MessageBus::ConnectionManager
             remove_client(client) if client.closed?
           end
         end
-
       rescue => e
         @bus.logger.error "notify clients crash #{e} : #{e.backtrace}"
       end
     end
   end
 
+  # Keeps track of a client with an active connection
+  # @param [MessageBus::Client] client the client to track
+  # @return [void]
   def add_client(client)
     synchronize do
       existing = @clients[client.client_id]
       if existing && existing.seq > client.seq
-        client.cancel
+        client.close
       else
         if existing
           remove_client(existing)
-          existing.cancel
+          existing.close
         end
 
         @clients[client.client_id] = client
         @subscriptions[client.site_id] ||= {}
-        client.subscriptions.each do |k, v|
+        client.subscriptions.each do |k, _v|
           subscribe_client(client, k)
         end
       end
     end
   end
 
+  # Removes a client
+  # @param [MessageBus::Client] c the client to remove
+  # @return [void]
   def remove_client(c)
     synchronize do
       @clients.delete c.client_id
-      @subscriptions[c.site_id].each do |k, set|
+      @subscriptions[c.site_id].each do |_k, set|
         set.delete c.client_id
       end
       if c.cleanup_timer
@@ -74,12 +86,24 @@ class MessageBus::ConnectionManager
     end
   end
 
+  # Finds a client by ID
+  # @param [String] client_id the client ID to search by
+  # @return [MessageBus::Client] the client with the specified ID
   def lookup_client(client_id)
     synchronize do
       @clients[client_id]
     end
   end
 
+  # @return [Integer] the number of tracked clients
+  def client_count
+    synchronize do
+      @clients.length
+    end
+  end
+
+  private
+
   def subscribe_client(client, channel)
     synchronize do
       set = @subscriptions[client.site_id][channel]
@@ -90,20 +114,4 @@ class MessageBus::ConnectionManager
       set << client.client_id
     end
   end
-
-  def client_count
-    synchronize do
-      @clients.length
-    end
-  end
-
-  def stats
-    synchronize do
-      {
-        client_count: @clients.length,
-        subscriptions: @subscriptions
-      }
-    end
-  end
-
 end

data/lib/message_bus/diagnostics.rb

@@ -1,53 +1,62 @@
+# MessageBus diagnostics are used for troubleshooting the bus and optimising its configuration
+# @see MessageBus::Rack::Diagnostics
 class MessageBus::Diagnostics
-  def self.full_process_path
-    begin
-      system = `uname`.strip
-      if system == "Darwin"
-        `ps -o "comm=" -p #{Process.pid}`
-      elsif system == "FreeBSD"
-        `ps -o command -p #{Process.pid}`.split("\n",2)[1].strip()
-      else
-        info = `ps -eo "%p|$|%a" | grep '^\\s*#{Process.pid}'`
-        info.strip.split('|$|')[1]
+  class << self
+    # Enables diagnostics functionality
+    # @param [MessageBus::Instance] bus a specific instance of message_bus
+    # @return [void]
+    def enable(bus = MessageBus)
+      full_path = full_process_path
+      start_time = Time.now.to_f
+      hostname = self.hostname
+
+      # it may make sense to add a channel per machine/host to streamline
+      #  process to process comms
+      bus.subscribe('/_diagnostics/hup') do |msg|
+        if Process.pid == msg.data["pid"] && hostname == msg.data["hostname"]
+          $shutdown = true
+          sleep 4
+          Process.kill("HUP", $$)
+        end
       end
-    rescue
-      # skip it ... not linux or something weird
-    end
-  end
 
-  def self.hostname
-    begin
-      `hostname`.strip
-    rescue
-      # skip it
+      bus.subscribe('/_diagnostics/discover') do |msg|
+        bus.on_connect.call msg.site_id if bus.on_connect
+        bus.publish '/_diagnostics/process-discovery', {
+          pid: Process.pid,
+          process_name: $0,
+          full_path: full_path,
+          uptime: (Time.now.to_f - start_time).to_i,
+          hostname: hostname
+        }, user_ids: [msg.data["user_id"]]
+        bus.on_disconnect.call msg.site_id if bus.on_disconnect
+      end
     end
-  end
 
-  def self.enable(bus = MessageBus)
-    full_path = full_process_path
-    start_time = Time.now.to_f
-    hostname = self.hostname
+    private
 
-    # it may make sense to add a channel per machine/host to streamline
-    #  process to process comms
-    bus.subscribe('/_diagnostics/hup') do |msg|
-      if Process.pid == msg.data["pid"] && hostname == msg.data["hostname"]
-        $shutdown = true
-        sleep 4
-        Process.kill("HUP", $$)
+    def full_process_path
+      begin
+        system = `uname`.strip
+        if system == "Darwin"
+          `ps -o "comm=" -p #{Process.pid}`
+        elsif system == "FreeBSD"
+          `ps -o command -p #{Process.pid}`.split("\n", 2)[1].strip
+        else
+          info = `ps -eo "%p|$|%a" | grep '^\\s*#{Process.pid}'`
+          info.strip.split('|$|')[1]
+        end
+      rescue
+        # skip it ... not linux or something weird
       end
     end
 
-    bus.subscribe('/_diagnostics/discover') do |msg|
-      bus.on_connect.call msg.site_id if bus.on_connect
-      bus.publish '/_diagnostics/process-discovery', {
-        pid: Process.pid,
-        process_name: $0,
-        full_path: full_path,
-        uptime: (Time.now.to_f - start_time).to_i,
-        hostname: hostname
-      }, user_ids: [msg.data["user_id"]]
-      bus.on_disconnect.call msg.site_id if bus.on_disconnect
+    def hostname
+      begin
+        `hostname`.strip
+      rescue
+        # skip it
+      end
     end
   end
 end

data/lib/message_bus/distributed_cache.rb

@@ -1,16 +1,14 @@
 # frozen_string_literal: true
 
-# Like a hash, just does its best to stay in sync across the farm.
-# On boot all instances are blank, but they populate as various processes
-# fill it up.
-
 require 'weakref'
 require 'base64'
 require 'securerandom'
 
 module MessageBus
+  # Like a hash, just does its best to stay in sync across the farm.
+  # On boot all instances are blank, but they populate as various processes
+  # fill it up.
   class DistributedCache
-
     DEFAULT_SITE_ID = 'default'
 
     class Manager
@@ -50,7 +48,6 @@ module MessageBus
             when "delete" then hash.delete(payload["key"])
             when "clear"  then hash.clear
             end
-
           rescue WeakRef::RefError
             @subscribers.delete_at(i)
           ensure
@@ -61,8 +58,10 @@ module MessageBus
 
       def ensure_subscribe!
         return if @subscribed
+
         @lock.synchronize do
           return if @subscribed
+
           @message_bus.subscribe(CHANNEL_NAME) do |message|
             @lock.synchronize do
               process_message(message)
@@ -160,6 +159,5 @@ module MessageBus
 
       @data[site_id] ||= {}
     end
-
   end
 end