fastly_nsq 1.7.0 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: be99f97fe78325dd7d99285e0f7f63387ad20cc3
-  data.tar.gz: a85de6cdf4520e2e83844f71f6feaab7d1f81865
+  metadata.gz: e9dbcfdeefbc796bb32482bd3ab9806b548284d4
+  data.tar.gz: 7d0257332788312bbbbad212e3060fe3ae6a79ea
 SHA512:
-  metadata.gz: a200725047fd0b365e03041b4a7806c7bee7daa557b2f6919dcd5f562b43c982d5597257c62b698de46aba63b02752ef970b22ea47f342183b911015676e7a29
-  data.tar.gz: 3ddcf60d8bc3c62d9af1726a05135296b131effa6f9319c8665d39b2d4b9d6d08977f9aecd00bbe618894f8b1c5ffeedd09826487f52430638e214aa23f7a55c
+  metadata.gz: d0e7305d476a86045538ffe42ebda32a6998edd64df5535487c2acec9a003a2d5b1bff4720cb3d13fa34d68fcb94750b1a1b82bd550086a3f08b51efaa9d8353
+  data.tar.gz: 0715abca959a7d08400aeb4f5f233c37c61912e172cccd0cab7792d0e4763193f53751716a346b240ea6ffb16cd133da307df0e72f7e97b43d23767401f5cd64

data/.gitignore

@@ -5,3 +5,5 @@
 /pkg/
 /vendor/cache/*.gem
 spec/examples.txt
+.yardoc
+/doc

data/README.md

@@ -24,6 +24,7 @@ Please use [GitHub Issues] to report bugs.
 
 [GitHub Issues]: https://github.com/fastly/fastly_nsq/issues
 
+**[Documentation](https://www.rubydoc.info/gems/fastly_nsq)**
 
 ## Install
 
@@ -243,19 +244,33 @@ FastlyNsq::Http::Nsqlookupd.nodes
 FastlyNsq::Http::Nsqlookupd.lookup(topic: 'foo')
 ```
 
-### `Real vs. Fake`
+### Testing
 
-The real strategy
-creates a connection
-to `nsq-ruby`'s
-`Nsq::Producer` and `Nsq::Consumer` classes.
+`FastlyNsq` provides a test mode and a helper class to make testing easier.
 
-The fake strategy
-mocks the connection
-to NSQ for testing purposes.
-It adheres to the same API
-as the real adapter.
+In order to test classes that use FastlyNsq without having real connections
+to NSQ:
 
+```ruby
+require 'fastly_nsq/testing'
+
+RSpec.configure do |config|
+  config.before(:each) do
+    FastlyNsq::Testing.fake!
+    FastlyNsq::Testing.reset!
+  end
+end
+```
+
+To test processor classes you can create test messages:
+
+```ruby
+test_message = FastlyNsq::Testing.message(data: { 'count' => 123 })
+
+My::ProcessorKlass.call(test_message)
+
+expect(some_result)
+```
 
 ## Configuration
 

data/fastly_nsq.gemspec

@@ -28,6 +28,7 @@ Gem::Specification.new do |gem|
   gem.add_development_dependency 'rspec-eventually', '0.2'
   gem.add_development_dependency 'timecop'
   gem.add_development_dependency 'webmock', '~> 3.0'
+  gem.add_development_dependency 'yard'
 
   gem.add_dependency 'concurrent-ruby', '~> 1.0'
   gem.add_dependency 'nsq-ruby', '~> 2.3'

data/lib/fastly_nsq.rb

@@ -12,12 +12,37 @@ module FastlyNsq
   NotConnectedError = Class.new(StandardError)
   ConnectionFailed = Class.new(StandardError)
 
+  LIFECYCLE_EVENTS = %i[startup shutdown heartbeat].freeze
+
   class << self
+    # @return [String] NSQ Channel
     attr_accessor :channel
+
+    # @return [Proc] global preprocessor
     attr_accessor :preprocessor
+
+    # Maximum number of times an NSQ message will be attempted.
+    # When set to +nil+, the number of attempts will be unlimited.
+    # @return [Integer]
     attr_accessor :max_attempts
+
+    # @return [Logger]
     attr_writer :logger
 
+    ##
+    # Map of lifecycle events
+    # @return [Hash]
+    def events
+      @events ||= LIFECYCLE_EVENTS.each_with_object({}) { |e, a| a[e] = [] }
+    end
+
+    ##
+    # Create a FastlyNsq::Listener
+    #
+    # @param topic [String] NSQ topic on which to listen
+    # @param processor [Proc] processor that will be +call+ed per message
+    # @param options [Hash] additional options that are passed to FastlyNsq::Listener's constructor
+    # @return FastlyNsq::Listener
     def listen(topic, processor, **options)
       FastlyNsq::Listener.new(topic: topic, processor: processor, **options)
     end
@@ -26,22 +51,73 @@ module FastlyNsq
       @logger ||= Logger.new(nil)
     end
 
+    ##
+    # Configuration for FastlyNsq
+    # @example
+    #   FastlyNsq.configure do |config|
+    #     config.channel = 'Z'
+    #     config.logger = Logger.new
+    #   end
+    # @example
+    #   FastlyNsq.configure do |config|
+    #     config.channel = 'fnsq'
+    #     config.logger = Logger.new
+    #     config.preprocessor = ->(_) { FastlyNsq.logger.info 'PREPROCESSESES' }
+    #     lc.listen 'posts', ->(m) { puts "posts: #{m.body}" }
+    #     lc.listen 'blogs', ->(m) { puts "blogs: #{m.body}" }, priority: 3
+    #   end
     def configure
       yield self
     end
 
+    ##
+    # Returns a new FastlyNsq::Manager or the memoized
+    # instance +@manager+.
+    # @return [FastlyNsq::Manager]
     def manager
       @manager ||= FastlyNsq::Manager.new
     end
 
+    ##
+    # Set a new manager and transfer listeners to the new manager.
+    # @param manager [FastlyNsq::Manager]
+    # @return [FastlyNsq::Manager]
     def manager=(manager)
       @manager&.transfer(manager)
       @manager = manager
     end
 
+    ##
+    # Return an array of NSQ lookupd http addresses sourced from ENV['NSQLOOKUPD_HTTP_ADDRESS']
+    # @return [Array<String>] list of nsqlookupd http addresses
     def lookupd_http_addresses
       ENV.fetch('NSQLOOKUPD_HTTP_ADDRESS').split(',').map(&:strip)
     end
+
+    # Register a block to run at a point in the lifecycle.
+    # :startup, :heartbeat or :shutdown are valid events.
+    #
+    #   FastlyNsq.configure do |config|
+    #     config.on(:shutdown) do
+    #       puts "Goodbye cruel world!"
+    #     end
+    #   end
+    def on(event, &block)
+      event = event.to_sym
+      raise ArgumentError, "Invalid event name: #{event}" unless LIFECYCLE_EVENTS.include?(event)
+      events[event] << block
+    end
+
+    def fire_event(event)
+      blocks = FastlyNsq.events.fetch(event)
+      blocks.each do |block|
+        begin
+          block.call
+        rescue => e
+          logger.error "[#{event}] #{e.inspect}"
+        end
+      end
+    end
   end
 end
 

data/lib/fastly_nsq/cli.rb

@@ -10,6 +10,20 @@ require 'fileutils'
 require 'optparse'
 require 'singleton'
 
+# Provides functionality to support running FastlyNsq as a command line
+# application that listens and processes NSQ messages.
+#
+# @example
+#   begin
+#     cli = FastlyNsq::CLI.instance
+#     cli.parse_options
+#     cli.run
+#   rescue => e
+#     raise e if $DEBUG
+#     STDERR.puts e.message
+#     STDERR.puts e.backtrace.join("\n")
+#     exit 1
+#   end
 class FastlyNsq::CLI
   include Singleton
 

data/lib/fastly_nsq/consumer.rb

@@ -1,15 +1,82 @@
 # frozen_string_literal: true
 
+# Provides an adapter to an Nsq::Consumer
+# and used to read messages off the queue.
+#
+# @example
+#   consumer = FastlyNsq::Consumer.new(
+#     topic: 'topic',
+#     channel: 'channel'
+#   )
+#   consumer.size #=> 1
+#   message = consumer.pop
+#   message.body #=> "{ 'data': { 'key': 'value' } }"
+#   message.finish
+#   consumer.size #=> 0
+#   consumer.terminate
+
 class FastlyNsq::Consumer
   extend Forwardable
 
-  DEFAULT_CONNECTION_TIMEOUT = 5 # seconds
+  # Default NSQ connection timeout in seconds
+  DEFAULT_CONNECTION_TIMEOUT = 5
+
+  # @return [String] NSQ Channel
+  attr_reader :channel
+
+  # @return [String] NSQ Topic
+  attr_reader :topic
+
+  # @return [Nsq::Consumer]
+  attr_reader :connection
+
+  # @return [Integer] connection timeout in seconds
+  attr_reader :connect_timeout
 
-  attr_reader :channel, :topic, :connection, :connect_timeout
+  # @return [Integer] maximum number of times an NSQ message will be attempted
   attr_reader :max_attempts
 
-  def_delegators :connection, :size, :terminate, :connected?, :pop, :pop_without_blocking
+  # @!method connected?
+  #   Delegated to +self.connection+
+  #   @return [Nsq::Consumer#connected?]
+  #   @see https://www.rubydoc.info/gems/nsq-ruby/Nsq/ClientBase#connected%3F-instance_method Nsq::ClientBase#connected?
+  # @!method pop
+  #   Delegated to +self.connection+
+  #   @return [Nsq::Consumer#pop]
+  #   @see https://www.rubydoc.info/gems/nsq-ruby/Nsq%2FConsumer:pop Nsq::Consumer#pop
+  # @!method pop_without_blocking
+  #   Delegated to +self.connection+
+  #   @return [Nsq::Consumer#pop_without_blocking]
+  #   @see https://www.rubydoc.info/gems/nsq-ruby/Nsq%2FConsumer:pop_without_blocking Nsq::Consumer#pop_without_blocking
+  # @!method size
+  #   Delegated to +self.connection+
+  #   @return [Nsq::Consumer#size]
+  #   @see https://www.rubydoc.info/gems/nsq-ruby/Nsq%2FConsumer:size Nsq::Consumer#size
+  # @!method terminate
+  #   Delegated to +self.connection+
+  #   @return [Nsq::Consumer#terminate]
+  #   @see https://www.rubydoc.info/gems/nsq-ruby/Nsq%2FConsumer:terminate Nsq::Consumer#terminate
+  def_delegators :connection, :connected?, :pop, :pop_without_blocking, :size, :terminate
 
+  ##
+  # Create a FastlyNsq::Consumer
+  #
+  # @param topic [String] NSQ topic from which to consume
+  # @param channel [String] NSQ channel from which to consume
+  # @param queue [#pop, #size] Queue object, most likely an instance of {FastlyNsq::Feeder}
+  # @param tls_options [Hash] Hash of TSL options passed the connection.
+  #   In most cases this should be nil unless you need to override the
+  #   default values set in ENV.
+  # @param connect_timeout [Integer] NSQ connection timeout in seconds
+  # @param max_attempts [Integer] maximum number of times an NSQ message will be attemped
+  #   When set to +nil+, attempts will be unlimited
+  # @param options [Hash] addtional options forwarded to the connection contructor
+  #
+  # @example
+  #   consumer = FastlyNsq::Consumer.new(
+  #     topic: 'topic',
+  #     channel: 'channel'
+  #   )
   def initialize(topic:, channel:, queue: nil, tls_options: nil, connect_timeout: DEFAULT_CONNECTION_TIMEOUT, max_attempts: FastlyNsq.max_attempts, **options)
     @topic           = topic
     @channel         = channel
@@ -20,6 +87,9 @@ class FastlyNsq::Consumer
     @connection = connect(queue, **options)
   end
 
+  ##
+  # Is the message queue empty?
+  # @return [Boolean]
   def empty?
     size.zero?
   end

data/lib/fastly_nsq/feeder.rb

@@ -1,15 +1,36 @@
 # frozen_string_literal: true
 
+##
+# FastlyNsq::Feeder is a queue interface wrapper for the manager's thread pool.
+# This allows a consumer read loop to post a message directly to a
+# processor (FastlyNsq::Listener) with a specified priority.
 class FastlyNsq::Feeder
   attr_reader :processor, :priority
 
+  ##
+  # Create a FastlyNsq::Feeder
+  # @param processor [FastlyNsq::Listener]
+  # @param priority [Numeric]
   def initialize(processor, priority)
     @processor = processor
     @priority = priority
   end
 
+  ##
+  # Send a message to the processor with specified priority
+  #
+  # This will +post+ to the FastlyNsq.manager.pool with a queue priority and block
+  # that will +call+ed. FastlyNsq.manager.pool is a PriorityThreadPool which is a
+  # Concurrent::ThreadPoolExecutor that has @queue which in turn is a priority queue
+  # that manages job priority
+  #
+  # The ThreadPoolExecutor is what actually works the @queue and sends +call+ to the queued Proc.
+  # When that code is exec'ed +processer.call(message)+ is run. Processor in this context is
+  # a FastlyNsq::Listener
+  #
+  # @param message [Nsq::Message]
   # @see http://ruby-concurrency.github.io/concurrent-ruby/Concurrent/ThreadPoolExecutor.html#post-instance_method
-  # @see {Nsq::Connection#read_loop}
+  # @see Nsq::Connection#read_loop
   def push(message)
     FastlyNsq.manager.pool.post(priority) { processor.call(message) }
   end

data/lib/fastly_nsq/http.rb

@@ -4,6 +4,16 @@ require 'net/https'
 require 'fastly_nsq/http/nsqd'
 require 'fastly_nsq/http/nsqlookupd'
 
+##
+# Adapter class for HTTP requests to NSQD
+#
+# @example
+#   uri = URI.join(nsqd_url, '/info')
+#   client = FastlyNsq::Http.new(uri: uri)
+#   client.use_ssl
+#
+# @see FastlyNsq::Http::Nsqd
+# @see FastlyNsq::Http::Nsqlookupd
 class FastlyNsq::Http
   def initialize(uri:, cert_filename: ENV['NSQ_SSL_CERTIFICATE'], key_filename: ENV['NSQ_SSL_KEY'])
     @uri = uri.is_a?(URI) ? uri : URI.parse(uri)

data/lib/fastly_nsq/http/nsqd.rb

@@ -3,6 +3,11 @@
 require 'fastly_nsq/http'
 
 class FastlyNsq::Http
+  ##
+  # Provides an interface to the the functionality provided by
+  # the nsqd HTTP interface
+  #
+  # @see https://nsq.io/components/nsqd.html
   class Nsqd
     extend Forwardable
     def_delegator :client, :get

data/lib/fastly_nsq/http/nsqlookupd.rb

@@ -3,6 +3,11 @@
 require 'fastly_nsq/http'
 
 class FastlyNsq::Http
+  ##
+  # Provides an interface to the functionality exposed by
+  # the nsqlookupd HTTP interface
+  #
+  # @see https://nsq.io/components/nsqlookupd.html
   class Nsqlookupd
     extend Forwardable
     def_delegator :client, :get

data/lib/fastly_nsq/launcher.rb

@@ -2,6 +2,11 @@
 
 require 'fastly_nsq/safe_thread'
 
+##
+# FastlyNsq::Launcher is a lighweight wrapper of a thread manager
+# and heartbeat.
+#
+# This class is used internally by FastlyNsq::CLI.
 class FastlyNsq::Launcher
   include FastlyNsq::SafeThread
 
@@ -19,6 +24,7 @@ class FastlyNsq::Launcher
     @logger  = logger
 
     FastlyNsq.manager = FastlyNsq::Manager.new(options)
+    FastlyNsq.fire_event :startup
   end
 
   def beat
@@ -28,6 +34,7 @@ class FastlyNsq::Launcher
   def stop
     @done = true
     manager.terminate(timeout)
+    FastlyNsq.fire_event :shutdown
   end
 
   def stop_listeners
@@ -57,6 +64,8 @@ class FastlyNsq::Launcher
     #       ::Process.kill('dieing because...', $$)
   rescue => e
     logger.error "Heartbeat error: #{e.message}"
+  ensure
+    FastlyNsq.fire_event :heartbeat
   end
 
   def start_heartbeat

data/lib/fastly_nsq/listener.rb

@@ -1,16 +1,81 @@
 # frozen_string_literal: true
 
+##
+# The main interface to setting up a thread that listens for and
+# processes NSQ messages from a given topic/channel.
+#
+# @example
+#   FastlyNsq::Listener.new(
+#     topic: topic,
+#     channel: channel,
+#     processor: ->(m) { puts 'got: '+ m.body }
+#   )
 class FastlyNsq::Listener
   extend Forwardable
 
+  # Default queue priority used when setting up the consumer queue
   DEFAULT_PRIORITY = 0
-  DEFAULT_CONNECTION_TIMEOUT = 5 # seconds
 
+  # Default NSQ connection timeout in seconds
+  DEFAULT_CONNECTION_TIMEOUT = 5
+
+  # @!method connected?
+  #   Delegated to +self.consumer+
+  #   @return [FastlyNsq::Consumer#connected?]
   def_delegators :consumer, :connected?
 
-  attr_reader :preprocessor, :topic, :processor, :priority, :channel, :logger, :consumer
+  # @return [String] NSQ Channel
+  attr_reader :channel
+
+  # @return [FastlyNsq::Consumer]
+  attr_reader :consumer
+
+  # @return [Logger]
+  attr_reader :logger
+
+  # @return [Integer] maxium number of times an NSQ message will be attempted
   attr_reader :max_attempts
 
+  # @return [Proc]
+  attr_reader :preprocessor
+
+  # @return [String] NSQ Topic
+  attr_reader :topic
+
+  # @return [Integer] Queue priority
+  attr_reader :priority
+
+  # @return [Proc] processor that is called for each message
+  attr_reader :processor
+
+  ##
+  # Create a FastlyNsq::Listener
+  #
+  # @param topic [String] NSQ topic on which to listen
+  # @param processor [Proc#call] Any object that responds to +call+. Each message will
+  #   be processed with +processor.call(FastlyNsq::Message.new(nsq_message))+.
+  #   The processor should return +true+ to indicate that processing is complete
+  #   and NSQ message can be finished. The processor is passed an instance of {FastlyNsq::Message}
+  #   so the provided Proc can optionally manage the message state using methods provided by {FastlyNsq::Message}.
+  # @param preprocessor [Proc#call] Any object that responds to +call+. Similar to the processor
+  #   each message it processes via +preprocessor.call(message)+. Default: {FastlyNsq.preprocessor}
+  # @param channel [String] NSQ Channel on which to listen. Default: {FastlyNsq.channel}
+  # @param consumer [FastlyNsq::Consumer] interface to read messages off the queue. If value is +nil+ the
+  #   constructor will create a {FastlyNsq::Consumer} based on the provided parameters.
+  # @param logger [Logger] Default: {FastlyNsq.logger}
+  # @param priority [Integer] Queue piority. Default: {DEFAULT_PRIORITY}
+  # @param connect_timeout [Integer] NSQ connection timeout in seconds. Default: {DEFAULT_CONNECTION_TIMEOUT}
+  # @param max_attempts [Integer] maximum number of times an NSQ message will be attemped Default: {FastlyNsq.max_attempts}
+  #   When set to +nil+, attempts will be unlimited
+  # @param consumer_options [Hash] additional options forwarded to the {FastlyNsq::Consumer}} contructor
+  #
+  # @example
+  #   FastlyNsq::Listener.new(
+  #     topic: topic,
+  #     channel: channel,
+  #     processor: MessageProcessor,
+  #     max_attempts: 15,
+  #   )
   def initialize(topic:, processor:, preprocessor: FastlyNsq.preprocessor, channel: FastlyNsq.channel, consumer: nil,
                  logger: FastlyNsq.logger, priority: DEFAULT_PRIORITY, connect_timeout: DEFAULT_CONNECTION_TIMEOUT,
                  max_attempts: FastlyNsq.max_attempts, **consumer_options)
@@ -36,6 +101,15 @@ class FastlyNsq::Listener
     FastlyNsq.manager.add_listener(self)
   end
 
+  ##
+  # Process an NSQ message.
+  #
+  # @see FastlyNsq::Feeder#push
+  #
+  # @param nsq_message [Nsq::Message]
+  #   @see {https://www.rubydoc.info/gems/nsq-ruby/Nsq/Message}
+  #
+  # @return [FastlyNsq::Message]
   def call(nsq_message)
     message = FastlyNsq::Message.new(nsq_message)
 
@@ -57,6 +131,10 @@ class FastlyNsq::Listener
     message
   end
 
+  ##
+  # Close the NSQ Conneciton
+  #
+  # @see FastlyNsq::Consumer#terminate
   def terminate
     return unless connected?
     consumer.terminate

data/lib/fastly_nsq/manager.rb

@@ -1,11 +1,25 @@
 # frozen_string_literal: true
 
+##
+# Interface for tracking listeners and managing the processing pool.
 class FastlyNsq::Manager
   DEADLINE = 30
   DEFAULT_POOL_SIZE = 5
 
-  attr_reader :done, :pool, :logger
+  # @return [Boolean] Set true when all listeners are stopped
+  attr_reader :done
 
+  # @return [FastlyNsq::PriorityThreadPool]
+  attr_reader :pool
+
+  # @return [Logger]
+  attr_reader :logger
+
+  ##
+  # Create a FastlyNsq::Manager
+  #
+  # @param logger [Logger]
+  # @param pool_options [Hash] Options forwarded to {FastlyNsq::PriorityThreadPool} constructor.
   def initialize(logger: FastlyNsq.logger, **pool_options)
     @done      = false
     @logger    = logger
@@ -14,18 +28,31 @@ class FastlyNsq::Manager
     )
   end
 
+  ##
+  # Hash of listeners. Keys are topics, values are {FastlyNsq::Listener} instances.
+  # @return [Hash]
   def topic_listeners
     @topic_listeners ||= {}
   end
 
+  ##
+  # Array of listening topic names
+  # @return [Array]
   def topics
     topic_listeners.keys
   end
 
+  ##
+  # Set of {FastlyNsq::Listener} objects
+  # @return [Set]
   def listeners
     topic_listeners.values.to_set
   end
 
+  ##
+  # Stop the manager.
+  # Terminates the listeners and stops all processing in the pool.
+  # @param deadline [Integer] Number of seconds to wait for pool to stop processing
   def terminate(deadline = DEADLINE)
     return if done
 
@@ -38,10 +65,16 @@ class FastlyNsq::Manager
     @done = true
   end
 
+  ##
+  # Manager state
+  # @return [Boolean]
   def stopped?
     done
   end
 
+  ##
+  # Add a {FastlyNsq::Listener} to the @topic_listeners
+  # @param listener [FastlyNsq::Listener}
   def add_listener(listener)
     logger.info { "topic #{listener.topic}, channel #{listener.channel}: listening" }
 
@@ -52,6 +85,10 @@ class FastlyNsq::Manager
     topic_listeners[listener.topic] = listener
   end
 
+  ##
+  # Transer listeners to a new manager and stop processing from the existing pool.
+  # @param new_manager [FastlyNsq::Manager] new manager to which listeners will be added
+  # @param deadline [Integer] Number of seconds to wait for exsiting pool to stop processing
   def transfer(new_manager, deadline: DEADLINE)
     new_manager.topic_listeners.merge!(topic_listeners)
     stop_processing(deadline)
@@ -59,6 +96,8 @@ class FastlyNsq::Manager
     @done = true
   end
 
+  ##
+  # Terminate all listeners
   def stop_listeners
     logger.info { 'Stopping listeners' }
     listeners.each(&:terminate)
@@ -67,6 +106,9 @@ class FastlyNsq::Manager
 
   protected
 
+  ##
+  # Shutdown the pool
+  # @param deadline [Integer] Number of seconds to wait for pool to stop processing
   def stop_processing(deadline)
     logger.info { 'Stopping processors' }
     pool.shutdown

data/lib/fastly_nsq/message.rb

@@ -2,14 +2,40 @@
 
 require 'json'
 
+##
+# Adapter to Nsq::Message. Provides convenience methods for interacting
+# with a message. Delegates management methods to the Nsq::Message
 class FastlyNsq::Message
   extend Forwardable
 
+  # @!method attempts
+  #   Delegated to +self.nsq_message+
+  #   @return [Nsq::Message#attempts]
+  #   @see https://www.rubydoc.info/gems/nsq-ruby/Nsq/Message#attempts-instance_method
+  # @!method touch
+  #   Delegated to +self.nsq_message+
+  #   @return [Nsq::Message#touch]
+  #   @see https://www.rubydoc.info/gems/nsq-ruby/Nsq/Message#touch-instance_method
+  # @!method timestamp
+  #   Delegated to +self.nsq_message+
+  #   @return [Nsq::Message#timestamp]
+  #   @see https://www.rubydoc.info/gems/nsq-ruby/Nsq/Message#timestamp-instance_method
   def_delegators :@nsq_message, :attempts, :touch, :timestamp
 
-  attr_reader :managed, :nsq_message, :raw_body
+  # @return [Symbol] Message state. Returns +nil+ if message has not been requeued or finished.
+  attr_reader :managed
+
+  # @return [Nsq::Message]
+  # @see https://www.rubydoc.info/gems/nsq-ruby/Nsq/Message
+  attr_reader :nsq_message
+
+  # @return [String] Nsq::Message body
+  attr_reader :raw_body
+
   alias to_s raw_body
 
+  ##
+  # @param nsq_message [Nsq::Message]
   def initialize(nsq_message)
     @nsq_message = nsq_message
     @raw_body = nsq_message.body
@@ -27,6 +53,8 @@ class FastlyNsq::Message
     @body ||= JSON.parse(raw_body)
   end
 
+  ##
+  # Finish an NSQ message
   def finish
     return managed if managed
 
@@ -34,6 +62,9 @@ class FastlyNsq::Message
     nsq_message.finish
   end
 
+  ##
+  # Requeue an NSQ Message
+  # @param timeout [Integer] timeout in milliseconds
   def requeue(timeout = nil)
     return managed if managed
     timeout ||= requeue_period

data/lib/fastly_nsq/messenger.rb

@@ -1,11 +1,27 @@
 # frozen_string_literal: true
 
+##
+# Provides interface for writing messages to NSQ.
+# Manages tracking and creation of {FastlyNsq::Producer}s
+# @example
+#   FastlyNsq::Messenger.deliver(
+#     message: message,
+#     topic: 'topic',
+#     meta: metadata_hash,
+#   )
 module FastlyNsq::Messenger
   DEFAULT_ORIGIN = 'Unknown'
   @originating_service = DEFAULT_ORIGIN
 
   module_function
 
+  ##
+  # Deliver an NSQ message
+  # @param message [#to_s] written to the +data+ key of the NSQ message payload
+  # @param topic [String] NSQ topic on which to deliver the message
+  # @param originating_service [String] added to meta key of message payload
+  # @param meta [Hash]
+  # @return [Void]
   def deliver(message:, topic:, originating_service: nil, meta: {})
     meta[:originating_service] = originating_service || self.originating_service
     meta[:sent_at] = Time.now.iso8601(5)
@@ -22,6 +38,9 @@ module FastlyNsq::Messenger
     @originating_service = service
   end
 
+  ##
+  # @param topic [String] NSQ topic
+  # @return [FastlyNsq::Producer] returns producer for given topic
   def producer_for(topic:)
     producer = producers[topic]
 
@@ -30,10 +49,16 @@ module FastlyNsq::Messenger
     producer
   end
 
+  ##
+  # Map of subscribed topics to FastlyNsq::Producer
+  # @return [Hash]
   def producers
     @producers ||= Hash.new { |hash, topic| hash[topic] = FastlyNsq::Producer.new(topic: topic) }
   end
 
+  ##
+  # Terminate producer for given topic
+  # @param topic [String] NSQ topic
   def terminate_producer(topic:)
     producer_for(topic: topic).terminate
     producers.delete(topic)

data/lib/fastly_nsq/testing.rb

@@ -1,6 +1,39 @@
 # frozen_string_literal: true
 
 module FastlyNsq
+  ##
+  # Interface for testing FastlyNsq
+  # @example
+  #   require 'fastly_nsq/testing'
+  #   FastlyNsq::Testing.enabled? #=> true
+  #   FastlyNsq::Testing.disabled? #=> false
+
+  #   producer = FastlyNsq::Producer.new(topic: topic)
+  #   listener = FastlyNsq::Listener.new(topic: topic, channel: channel, processor: ->(m) { puts 'got: '+ m.body })
+
+  #   FastlyNsq::Testing.fake! # default, messages accumulate on the listeners
+
+  #   producer.write '{"foo":"bar"}'
+  #   listener.messages.size #=> 1
+
+  #   FastlyNsq::Testing.reset!  # remove all accumulated messages
+
+  #   listener.messages.size #=> 0
+
+  #   producer.write '{"foo":"bar"}'
+  #   listener.messages.size #=> 1
+
+  #   listener.drain
+  #   # got: {"foo"=>"bar"}
+  #   listener.messages.size #=> 0
+
+  #   FastlyNsq::Testing.inline! # messages are processed as they are produced
+  #   producer.write '{"foo":"bar"}'
+  #   # got: {"foo"=>"bar"}
+  #   listener.messages.size #=> 0
+
+  #   FastlyNsq::Testing.disable! # do it live
+  #   FastlyNsq::Testing.enable!  # re-enable testing mode
   class Testing
     class << self
       attr_accessor :__test_mode
@@ -52,6 +85,18 @@ module FastlyNsq
         FastlyNsq::Messages.messages.clear
       end
 
+      ##
+      # Creates a FastlyNsq::TestMessage that is used to create a FastlyNsq::Message where the underlying
+      # +nsq_message+ is the TestMessage and not an Nsq::Message. This aids in testing application code that
+      # is doing message processing
+      #
+      # @param data [String] NSQ message data
+      # @param meta [String] NSQ message metadata
+      #
+      # @example
+      #   test_message = FastlyNsq::Testing.message(data: post_data, meta: {})
+      #   processor_klass.call(test_message)
+      #   expect(Post.find(post_data['id']).not_to be nil
       def message(data:, meta: nil)
         test_message = FastlyNsq::TestMessage.new(JSON.dump('data' => data, 'meta' => meta))
         FastlyNsq::Message.new(test_message)
@@ -65,6 +110,10 @@ module FastlyNsq
     end
   end
 
+  ##
+  # Stub for Nsq::Message used for testing.
+  # Use this class instead of a struct or test stubs
+  # when testing application logic that requires a Nsq::Message.
   class TestMessage
     attr_reader :raw_body
     attr_reader :attempts

data/lib/fastly_nsq/tls_options.rb

@@ -2,6 +2,9 @@
 
 module FastlyNsq
   class TlsOptions
+    ##
+    # Return hash of TLS options for creating an NSQ connection.
+    # @param context [Hash]
     def self.as_hash(context = nil)
       new(context).to_h
     end

data/lib/fastly_nsq/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FastlyNsq
-  VERSION = '1.7.0'
+  VERSION = '1.8.0'
 end

data/spec/fastly_nsq_spec.rb

@@ -69,4 +69,20 @@ RSpec.describe FastlyNsq do
       expect(subject.lookupd_http_addresses).to eq(ENV['NSQLOOKUPD_HTTP_ADDRESS'].split(','))
     end
   end
+
+  describe '#on' do
+    before { FastlyNsq.events.each { |(_, v)| v.clear } }
+    after  { FastlyNsq.events.each { |(_, v)| v.clear } }
+
+    it 'registers callbacks for events' do
+      %i[startup shutdown heartbeat].each do |event|
+        block = -> {}
+        expect { FastlyNsq.on(event, &block) }.to change { FastlyNsq.events[event] }.by([block])
+      end
+    end
+
+    it 'limits callback registration to valid events' do
+      expect { FastlyNsq.on(:foo, &-> {}) }.to raise_error(ArgumentError, /Invalid event name/)
+    end
+  end
 end

data/spec/launcher_spec.rb

@@ -3,19 +3,21 @@
 require 'spec_helper'
 
 RSpec.describe FastlyNsq::Launcher do
+  let!(:channel)  { 'fnsq' }
   let!(:options)  { { max_threads: 3, timeout: 9 } }
-  let!(:launcher) { FastlyNsq::Launcher.new options }
   let!(:topic)    { 'fnsq' }
-  let!(:channel)  { 'fnsq' }
+
+  let(:launcher) { FastlyNsq::Launcher.new options }
   let(:listener)  { FastlyNsq::Listener.new(topic: topic, channel: channel, processor: ->(*) {}) }
+  let(:manager) { launcher.manager }
 
   before { reset_topic(topic, channel: channel) }
   before { expect { listener }.to eventually(be_connected).within(5) }
   after  { listener.terminate if listener.connected? }
 
-  let(:manager) { launcher.manager }
-
   it 'creates a manager with correct options' do
+    launcher
+
     expect(FastlyNsq.manager.pool.max_threads).to eq(3)
   end
 
@@ -30,6 +32,8 @@ RSpec.describe FastlyNsq::Launcher do
   end
 
   describe '#stop_listeners' do
+    before { launcher }
+
     it 'stops listeners and sets done' do
       expect(launcher).not_to be_stopping
       expect(manager).to receive(:stop_listeners)
@@ -42,9 +46,45 @@ RSpec.describe FastlyNsq::Launcher do
   end
 
   describe '#stop' do
+    before { launcher }
+
     it 'stops the manager within a deadline' do
       expect(manager).to receive(:terminate).with(options[:timeout])
       launcher.stop
     end
   end
+
+  describe 'callbacks' do
+    before { FastlyNsq.events.each { |(_, v)| v.clear } }
+    after  { FastlyNsq.events.each { |(_, v)| v.clear } }
+
+    it 'fires :startup event on initialization' do
+      obj = spy
+      block = -> { obj.start }
+      FastlyNsq.on(:startup, &block)
+
+      launcher
+      expect(obj).to have_received(:start)
+    end
+
+    it 'fires :shutdown event on #stop' do
+      launcher
+
+      obj = spy
+      block = -> { obj.stop }
+      FastlyNsq.on(:shutdown, &block)
+
+      launcher.stop
+      expect(obj).to have_received(:stop)
+    end
+
+    it 'fires :heartbeat event on #heartbeat' do
+      obj = spy
+      block = -> { obj.beat }
+      FastlyNsq.on(:heartbeat, &block)
+      launcher.beat
+
+      expect { obj }.to eventually(have_received(:beat).at_least(:once)).within(0.5)
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fastly_nsq
 version: !ruby/object:Gem::Version
-  version: 1.7.0
+  version: 1.8.0
 platform: ruby
 authors:
 - Tommy O'Neil
@@ -13,7 +13,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-04-26 00:00:00.000000000 Z
+date: 2018-05-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: awesome_print
@@ -127,6 +127,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
   requirement: !ruby/object:Gem::Requirement
@@ -254,7 +268,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.6.14
 signing_key: 
 specification_version: 4
 summary: Fastly NSQ Adapter