fastly_nsq 0.9.5 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4cee7eb576e0bfa95f3d894c52e99e15585a3832
-  data.tar.gz: 4c84b8b5b2ab8f59d88599cb7e06acdf64ed3873
+  metadata.gz: e00ef3c8f9fbbd967b2e97e2621a63734cbf953b
+  data.tar.gz: f5d6e19dbcd964481c2543b9a772ccde35c6b22f
 SHA512:
-  metadata.gz: f00684ae35a919fb7b9c8cf0e08d6590aff4a5a36e101cbc8c3c36dff58b3e042e3ca5c1eb84b41a5fd41cb5a53e9c0e459ad4ce5470431d89819b05e2f8ca2b
-  data.tar.gz: 6ea4abebaf60a445f714060eaf27f97d8fd2f9b937ac25cf5b704171bd8aa53b29ce227dafc22a0c7720d07270e72fe8d27a958628c53da7d31f7a148fc8ca53
+  metadata.gz: 304ccf3b5012900f32aae93993656b5f6d5866d325b91267848b64d4c2c321e78ee40cbe812e418761f4c597827153598c5d874e7bfe0d8059cfd4ab2a4a3f6c
+  data.tar.gz: 7aac209a0fdb90f650bd0287393a367eb16585de140bf2768635f0a0bcb39f98d6600eb5d96c4ad66ff6da5ce4d68a1236c6f20f27cde2e0889c9545706ba672

data/.gitignore

@@ -1,4 +1,5 @@
 /.bundle
+/.env.local
 /Gemfile.lock
 /html/
 /pkg/

data/README.md

@@ -159,6 +159,20 @@ The task can also define a `call`-able "preprocessor" (called before any `Proces
 See the [`Rakefile`](examples/Rakefile) file
 for more detail.
 
+### `FastlyNsq::CLI`
+
+To help facilitate running the `FastlyNsq::Listener` in a blocking fashion
+outside your application, a `CLI` and bin script [`fastly_nsq`](bin/fastly_nsq)
+are provided.
+
+This can be setup ahead of time by calling `FastlyNsq.configure` and passing
+block. An exmaple of this can be found here: [`Example Config`](exmaple_config_class.rb)
+
+An example of using the cli:
+```bash
+./bin/fastly_nsq -r ./example_config_class.rb -L ./test.log -P ./fastly_nsq.pid -v -d
+```
+
 ### FastlyNsq::Messgener
 
 Wrapper around a producer for sending messages and persisting producer objects.

data/bin/fastly_nsq

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+
+require 'pry'
+require 'fastly_nsq/cli'
+
+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

data/example_config_class.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+class MessageProcessor
+  def self.process(message)
+    FastlyNsq.logger.info("IN PROCESS: #{message}")
+
+    # Do Soemthing with message
+  end
+end
+
+FastlyNsq.configure do |config|
+  config.channel = 'my_channel'
+  config.logger = Logger.new
+  config.preprocessor = ->(_) { FastlyNsq.logger.info 'PREPROCESSESES' }
+
+  config.listener_config do |lc|
+    lc.add_topic('some_topic', MessageProcessor)
+    lc.add_topic('some_other_topic', MessageProcessor)
+  end
+end

data/fastly_nsq.gemspec

@@ -23,6 +23,7 @@ Gem::Specification.new do |gem|
   gem.add_development_dependency 'awesome_print', '~> 1.6'
   gem.add_development_dependency 'bundler', '~> 1.12'
   gem.add_development_dependency 'bundler-audit', '~> 0.5.0'
+  gem.add_development_dependency 'dotenv'
   gem.add_development_dependency 'overcommit', '~> 0.32.0'
   gem.add_development_dependency 'pry-byebug', '~> 3.3'
   gem.add_development_dependency 'rake', '~> 11.1.2'

data/lib/fastly_nsq.rb

@@ -10,15 +10,51 @@ require 'fastly_nsq/tls_options'
 require 'fastly_nsq/version'
 
 module FastlyNsq
-  def self.logger=(logger)
+  module_function
+
+  def channel=(channel)
+    @channel ||= channel
+  end
+
+  def logger=(logger)
     strategy.logger = logger
   end
 
-  def self.logger
+  def self.preprocessor=(preprocessor)
+    @preprocessor ||= preprocessor
+  end
+
+  def channel
+    @channel
+  end
+
+  def logger
     strategy.logger
   end
 
-  def self.strategy
+  def self.preprocessor
+    @preprocessor
+  end
+
+  def strategy
     Strategy.for_queue
   end
+
+  def configure
+    yield self
+  end
+
+  def topic_map
+    @listener_config.topic_map
+  end
+
+  def listener_config
+    @listener_config ||= FastlyNsq::Listener::Config.new
+    yield @listener_config if block_given?
+    @listener_config
+  end
+
+  def reset_config
+    @listener_config = nil
+  end
 end

data/lib/fastly_nsq/cli.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+$stdout.sync = true
+
+require 'fastly_nsq'
+require 'fastly_nsq/launcher'
+require 'fastly_nsq/manager'
+require 'fileutils'
+require 'optparse'
+require 'singleton'
+
+class FastlyNsq::CLI
+  include Singleton
+
+  attr_reader :options
+
+  def parse_options(args = ARGV)
+    parse(args)
+    setup_logger
+    check_pid
+    daemonize if daemonize?
+    write_pid
+  end
+
+  def run
+    startup
+    begin
+      # Multithreading begins here ----
+      launcher.run
+
+      read_loop
+    rescue Interrupt
+      FastlyNsq.logger.info 'Shutting down'
+      launcher.stop
+      # Explicitly exit so busy Processor threads can't block
+      # process shutdown.
+      FastlyNsq.logger.info 'Bye!'
+      exit(0)
+    end
+  end
+
+  private
+
+  def launcher
+    @launcher ||= FastlyNsq::Launcher.new(options)
+  end
+
+  def read_loop
+    trapped_read_io = trap_signals
+    loop do
+      readable_io = IO.select([trapped_read_io])
+      break unless readable_io
+      signal = readable_io.first[0].gets.strip
+      handle_signal signal
+    end
+  end
+
+  def startup
+    require options[:require] if options[:require]
+    FastlyNsq.logger.info "Running in #{RUBY_DESCRIPTION}"
+    FastlyNsq.logger.info 'Starting processing, hit Ctrl-C to stop' unless options[:daemon]
+  end
+
+  def parse(args)
+    opts = {}
+
+    @parser = OptionParser.new do |o|
+      o.on '-d', '--daemon', 'Daemonize process' do |arg|
+        opts[:daemonize] = arg
+      end
+
+      o.on '-L', '--logfile PATH', 'path to writable logfile' do |arg|
+        opts[:logfile] = arg
+      end
+
+      o.on '-P', '--pidfile PATH', 'path to pidfile' do |arg|
+        opts[:pidfile] = arg
+      end
+
+      o.on '-r', '--require [PATH|DIR]', 'Location of message_processor definition' do |arg|
+        opts[:require] = arg
+      end
+
+      o.on '-v', '--verbose', 'enable verbose logging output' do |arg|
+        opts[:verbose] = arg
+      end
+    end
+
+    @parser.banner = 'fastly_nsq [options]'
+    @parser.parse!(args)
+
+    @options = opts
+  end
+
+  def check_pid
+    if pidfile?
+      case pid_status(pidfile)
+      when :running, :not_owned
+        puts "A server is already running. Check #{pidfile}"
+        exit(1)
+      when :dead
+        File.delete(pidfile)
+      end
+    end
+  end
+
+  def pid_status(pidfile)
+    return :exited unless File.exist?(pidfile)
+    pid = ::File.read(pidfile).to_i
+    return :dead if pid == 0
+    Process.kill(0, pid) # check process status
+    :running
+  rescue Errno::ESRCH
+    :dead
+  rescue Errno::EPERM
+    :not_owned
+  end
+
+  def setup_logger
+    FastlyNsq.logger = Logger.new(options[:logfile]) if options[:logfile]
+
+    FastlyNsq.logger.level = ::Logger::DEBUG if options[:verbose]
+  end
+
+  def write_pid
+    if pidfile?
+      begin
+        File.open(pidfile, ::File::CREAT | ::File::EXCL | ::File::WRONLY) do |f|
+          f.write Process.pid.to_s
+        end
+        at_exit { File.delete(pidfile) if File.exist?(pidfile) }
+      rescue Errno::EEXIST
+        check_pid
+        retry
+      end
+    end
+  end
+
+  def trap_signals
+    self_read, self_write = IO.pipe
+    sigs = %w(INT TERM TTIN USR1)
+
+    sigs.each do |sig|
+      begin
+        trap sig do
+          self_write.puts(sig)
+        end
+      rescue ArgumentError
+        puts "Signal #{sig} not supported"
+      end
+    end
+    self_read
+  end
+
+  def handle_signal(sig)
+    FastlyNsq.logger.debug "Got #{sig} signal"
+    case sig
+    when 'INT'
+      # Handle Ctrl-C in JRuby like MRI
+      # http://jira.codehaus.org/browse/JRUBY-4637
+      raise Interrupt
+    when 'TERM'
+      # Heroku sends TERM and then waits 10 seconds for process to exit.
+      raise Interrupt
+    when 'USR1'
+      FastlyNsq.logger.info 'Received USR1, no longer accepting new work'
+      launcher.quiet
+    when 'TTIN'
+      handle_ttin
+    end
+  end
+
+  def handle_ttin
+    Thread.list.each do |thread|
+      FastlyNsq.logger.warn "Thread TID-#{thread.object_id.to_s(36)} #{thread['fastly_nsq_label']}"
+      if thread.backtrace
+        FastlyNsq.logger.warn thread.backtrace.join("\n")
+      else
+        FastlyNsq.logger.warn '<no backtrace available>'
+      end
+    end
+  end
+
+  def daemonize
+    return unless options[:daemonize]
+
+    files_to_reopen = []
+    ObjectSpace.each_object(File) do |file|
+      files_to_reopen << file unless file.closed?
+    end
+
+    ::Process.daemon(true, true)
+
+    reopen(files_to_reopen)
+
+    [$stdout, $stderr].each do |io|
+      File.open(options.fetch(:logfile, '/dev/null'), 'ab') do |f|
+        io.reopen(f)
+      end
+      io.sync = true
+    end
+    $stdin.reopen('/dev/null')
+
+    setup_logger
+  end
+
+  def reopen(files)
+    files.each do |file|
+      begin
+        file.reopen file.path, 'a+'
+        file.sync = true
+      rescue IOError => e
+        FastlyNsq.logger.warn "IOError reopening file:  #{e.message}"
+      rescue StandardError => e
+        FastlyNsq.logger.error "Non IOError reopening file:  #{e.message}"
+      end
+    end
+  end
+
+  def logfile?
+    !logfile.nil?
+  end
+
+  def pidfile?
+    !pidfile.nil?
+  end
+
+  def daemonize?
+    options[:daemonize]
+  end
+
+  def logfile
+    options[:logfile]
+  end
+
+  def pidfile
+    options[:pidfile]
+  end
+end

data/lib/fastly_nsq/launcher.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+require 'fastly_nsq/safe_thread'
+
+class FastlyNsq::Launcher
+  include FastlyNsq::SafeThread
+
+  def initialize(options)
+    @done = false
+    @manager = FastlyNsq::Manager.new options
+    @options = options
+  end
+
+  def run
+    @thread = safe_thread('heartbeat', &method(:start_heartbeat))
+    @manager.start
+  end
+
+  def quiet
+    @done = true
+    @manager.quiet
+  end
+
+  # Shuts down the process.  This method does not
+  # return until all work is complete and cleaned up.
+  # It can take up to the timeout to complete.
+  def stop
+    deadline = Time.now + @options.fetch(:timeout, 10)
+    quiet
+    @manager.stop deadline
+  end
+
+  def stopping?
+    @done
+  end
+
+  private
+
+  def heartbeat
+    FastlyNsq.logger.debug do
+      [
+        'HEARTBEAT:',
+        'thread_status:', @manager.listeners.map(&:status).join(', '),
+        'listener_count:', @manager.listeners.count
+      ].join(' ')
+    end
+
+    # TODO: Check the health of the system overall and kill it if needed
+    #       ::Process.kill('dieing because...', $$)
+  rescue => e
+    FastlyNsq.logger.error "heartbeat error: #{e.message}"
+  end
+
+  def start_heartbeat
+    loop do
+      heartbeat
+      sleep 5
+    end
+    FastlyNsq.logger.info('Heartbeat stopping...')
+  end
+end

data/lib/fastly_nsq/listener.rb

@@ -1,59 +1,114 @@
+# frozen_string_literal: true
 require 'fastly_nsq/message'
+require 'fastly_nsq/manager'
+require 'fastly_nsq/safe_thread'
+require 'fastly_nsq/listener/config'
 
 module FastlyNsq
   class Listener
-    def self.listen_to(**args)
-      new(**args).go
+    include FastlyNsq::SafeThread
+
+    def self.listen_to(*args)
+      new(*args).go
     end
 
     def initialize(topic:, processor:, channel: nil, consumer: nil, **options)
-      @topic        = topic
-      @processor    = processor
       @consumer     = consumer || FastlyNsq::Consumer.new(topic: topic, channel: channel)
+      @done         = false
       @logger       = options.fetch :logger, FastlyNsq.logger
+      @manager      = options[:manager] || FastlyNsq::Manager.new
       @preprocessor = options[:preprocessor]
+      @processor    = processor
+      @thread       = nil
+      @topic        = topic
     end
 
-    def go(run_once: false)
-      exit_on 'INT'
-      exit_on 'TERM'
+    def identity
+      {
+        consumer:     @consumer,
+        logger:       @logger,
+        manager:      @manager,
+        preprocessor: @preprocessor,
+        processor:    @processor,
+        topic:        @topic,
+      }
+    end
+
+    def reset_then_dup
+      reset
+      dup
+    end
 
-      loop do
+    def start
+      @logger.info { "> Listener Started: topic #{@topic}" }
+      @thread ||= safe_thread('listener', &method(:go))
+    end
+
+    def go(run_once: false)
+      until @done
         next_message do |message|
           log message
           preprocess message
-          processor.process message
+          @processor.process message
         end
 
-        break if run_once
+        terminate if run_once
       end
 
-      consumer.terminate
+      @manager.listener_stopped(self)
+    rescue FastlyNsq::Shutdown
+      @manager.listener_stopped(self)
+    rescue Exception => ex # rubocop:disable Lint/RescueException
+      @logger.error ex.inspect
+      @manager.listener_killed(self)
+    ensure
+      cleanup
     end
 
-    private
+    def status
+      @thread.status if @thread
+    end
+
+    def terminate
+      @done = true
+      return unless @thread
+      @logger.info "< Listener TERM: topic #{@topic}"
+    end
 
-    attr_reader :topic, :consumer, :preprocessor, :processor, :logger
+    def kill
+      @done = true
+      return unless @thread
+      @logger.info "< Listener KILL: topic #{@topic}"
+      @thread.raise FastlyNsq::Shutdown
+    end
+
+    private
 
     def log(message)
-      logger.info "[NSQ] Message Received: #{message}" if logger
+      @logger.info "[NSQ] Message Received: #{message}" if @logger
+    end
+
+    def cleanup
+      @consumer.terminate
+      @logger.info '< Consumer terminated'
     end
 
     def next_message
-      message = consumer.pop # TODO: consumer.pop do |message|
+      message = @consumer.pop # TODO: consumer.pop do |message|
       result  = yield FastlyNsq::Message.new(message.body)
       message.finish if result
     end
 
     def preprocess(message)
-      preprocessor.call(message) if preprocessor
+      @preprocessor.call(message) if @preprocessor
     end
 
-    def exit_on(signal)
-      Signal.trap(signal) do
-        consumer.terminate
-        exit
-      end
+    def reset
+      @done = false
+      @thread = nil
+      self
     end
   end
 end
+
+class FastlyNsq::Shutdown < StandardError; end

data/lib/fastly_nsq/listener/config.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+module FastlyNsq
+  class Listener
+    class Config
+      attr_reader :topic_map
+
+      def initialize
+        @topic_map = {}
+      end
+
+      def add_topic(topic_name, processor)
+        FastlyNsq.logger.info("topic: #{topic_name} : klass #{processor}")
+        validate topic_name, processor
+        topic_map[topic_name] = processor
+      end
+
+      private
+
+      def validate(topic_name, processor)
+        unless  processor.respond_to? :process
+          error_msg = "ConfigurationError: processor: #{processor} for #{topic_name} does not respond to :process!"
+          FastlyNsq.logger.error error_msg
+          raise ::ConfigurationError, error_msg
+        end
+
+        if topic_map[topic_name]
+          FastlyNsq.logger.warn("topic: #{topic_name} was added more than once")
+        end
+      end
+    end
+  end
+end
+
+class ConfigurationError < StandardError; end

data/lib/fastly_nsq/manager.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+require 'set'
+
+class FastlyNsq::Manager
+  attr_reader :listeners
+
+  def initialize(options = {})
+    @options = options
+    @done = false
+    @listeners = Set.new
+    @plock = Mutex.new
+  end
+
+  def start
+    setup_configured_listeners
+    @listeners.each(&:start)
+  end
+
+  def quiet
+    return if @done
+    @done = true
+
+    FastlyNsq.logger.info { 'Terminating quiet listeners' }
+    @listeners.each(&:terminate)
+  end
+
+  PAUSE_TIME = 0.5
+
+  def stop(deadline)
+    quiet
+
+    sleep PAUSE_TIME
+    return if @listeners.empty?
+
+    FastlyNsq.logger.info { 'Pausing to allow workers to finish...' }
+    remaining = deadline - Time.now
+    while remaining > PAUSE_TIME
+      return if @listeners.empty?
+      sleep PAUSE_TIME
+      remaining = deadline - Time.now
+    end
+    return if @listeners.empty?
+
+    hard_shutdown
+  end
+
+  def stopped?
+    @done
+  end
+
+  def listener_stopped(listener)
+    @plock.synchronize do
+      @listeners.delete listener
+    end
+  end
+
+  def listener_killed(listener)
+    @plock.synchronize do
+      @listeners.delete listener
+      unless @done
+        FastlyNsq.logger.info { "recreating listener for: #{listener.identity}" }
+        new_listener = listener.reset_then_dup
+        @listeners << new_listener
+        new_listener.start
+      end
+    end
+  end
+
+  private
+
+  def setup_configured_listeners
+    FastlyNsq.logger.debug { "options #{@options.inspect}" }
+    FastlyNsq.logger.debug { "starting listeners: #{FastlyNsq.topic_map.inspect}" }
+
+    FastlyNsq.topic_map.each_pair do |topic, processor|
+      @listeners << setup_listener(topic, processor)
+    end
+  end
+
+  def setup_listener(topic, processor)
+    FastlyNsq.logger.info { "Listening to topic:'#{topic}' on channel: '#{FastlyNsq.channel}'" }
+    FastlyNsq::Listener.new(
+      {
+        topic:        topic,
+        channel:      FastlyNsq.channel,
+        processor:    processor,
+        preprocessor: FastlyNsq.preprocessor,
+        manager:      self,
+      },
+    )
+  end
+
+  def hard_shutdown
+    cleanup = nil
+    @plock.synchronize do
+      cleanup = @listeners.dup
+    end
+
+    unless cleanup.empty?
+      FastlyNsq.logger.warn { "Terminating #{cleanup.size} busy worker threads" }
+    end
+
+    cleanup.each(&:kill)
+  end
+end

data/lib/fastly_nsq/safe_thread.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+module FastlyNsq::SafeThread
+  def safe_thread(name, &block)
+    Thread.new do
+      Thread.current['fastly_nsq_label'] = name
+      watchdog(name, &block)
+    end
+  end
+
+  def watchdog(last_words)
+    yield
+  rescue => ex
+    FastlyNsq.logger.error ex
+    FastlyNsq.logger.error last_words
+    FastlyNsq.logger.error ex.backtrace.join("\n") unless ex.backtrace.nil?
+    raise ex
+  end
+end

data/lib/fastly_nsq/version.rb

@@ -1,3 +1,3 @@
 module FastlyNsq
-  VERSION = '0.9.5'.freeze
+  VERSION = '0.10.0'.freeze
 end

data/spec/lib/fastly_nsq/cli_spec.rb

@@ -0,0 +1,5 @@
+require 'spec_helper'
+require 'fastly_nsq/cli'
+
+RSpec.describe FastlyNsq::CLI do
+end

data/spec/lib/fastly_nsq/launcher_spec.rb

@@ -0,0 +1,56 @@
+require 'spec_helper'
+require 'fastly_nsq/launcher'
+
+RSpec.describe FastlyNsq::Launcher do
+  let(:launcher) { FastlyNsq::Launcher.new options }
+  let(:manager)  { instance_double 'Manager', start: nil, quiet: nil, stop: nil }
+  let(:thread)   { instance_double 'Thread' }
+  let(:options)  { { joe: 'biden' } }
+
+  before do
+    allow(FastlyNsq::Manager).to receive(:new).and_return(manager)
+    allow(launcher).to receive(:safe_thread).and_return(thread)
+  end
+
+  it 'creates a manager with correct options' do
+    expect(FastlyNsq::Manager).to have_received(:new).with(options)
+  end
+
+  describe '#run' do
+    it 'creates a heartbeat thread' do
+      launcher.run
+      expect(launcher).to have_received(:safe_thread).with('heartbeat')
+      expect(launcher.stopping?).to eq false
+    end
+
+    it 'starts the setup manager' do
+      launcher.run
+      expect(manager).to have_received(:start)
+      expect(launcher.stopping?).to eq false
+    end
+  end
+
+  describe '#quiet' do
+    it 'quites the manager and sets done' do
+      expect(launcher.stopping?).to eq false
+      launcher.quiet
+      expect(manager).to have_received(:quiet)
+      expect(launcher.stopping?).to eq true
+    end
+  end
+
+  describe '#stop' do
+    it 'stops the manager within a deadline' do
+      now = Time.now
+      allow(Time).to receive(:now).and_return(now)
+      launcher.stop
+      expect(manager).to have_received(:stop).with(now + 10)
+    end
+
+    it 'quites the manager' do
+      launcher.stop
+      expect(manager).to have_received(:quiet)
+      expect(launcher.stopping?).to eq true
+    end
+  end
+end

data/spec/lib/fastly_nsq/listener_spec.rb

@@ -4,7 +4,7 @@ RSpec.describe FastlyNsq::Listener do
   let(:topic)    { 'testing_topic' }
   let(:channel)  { 'testing_channel' }
   let(:consumer) { FastlyNsq::FakeBackend::Consumer.new topic: topic, channel: channel }
-  let(:logger)   { double 'Logger', info: nil }
+  let(:logger)   { double 'Logger', info: nil, debug: nil, error: nil }
 
   module TestMessageProcessor
     @@messages_processed = []
@@ -36,7 +36,7 @@ RSpec.describe FastlyNsq::Listener do
 
   let(:message)            { TestMessageProcessor::Message.new 'this is message body' }
   let(:messages_processed) { TestMessageProcessor.messages_processed }
-  let(:expected_message)   { TestMessageProcessor::Message.new('this is message body') }
+  let(:expected_message)   { TestMessageProcessor::Message.new 'this is message body' }
   let(:expected_messages)  { [expected_message] }
 
   describe 'instantiating without a consumer' do
@@ -53,6 +53,12 @@ RSpec.describe FastlyNsq::Listener do
     end
   end
 
+  context 'when not passed a manager' do
+    it 'creates a blank manager' do
+      expect(listener.identity[:manager]).to_not be_nil
+    end
+  end
+
   context 'when using the fake queue and it is empty', fake_queue: true do
     before do
       TestMessageProcessor.clear
@@ -112,5 +118,74 @@ RSpec.describe FastlyNsq::Listener do
         expect(preprocessor_was_called).to be_truthy
       end
     end
+
+    context 'when running as a thread' do
+      let(:manager) { double 'Manager', listener_stopped: nil, listener_killed: nil }
+      let(:thread)  { double 'FakeThread', raise: nil, kill: nil, status: 'fake_thread' }
+      let(:listener) do
+        FastlyNsq::Listener.new topic:     topic,
+                                processor: TestMessageProcessor,
+                                logger:    logger,
+                                consumer:  consumer,
+                                manager:   manager
+      end
+
+      describe 'shutdown' do
+        it 'informs the manager of a shutdown when run once' do
+          listener.go run_once: true
+
+          expect(manager).to have_received(:listener_stopped).with(listener)
+        end
+      end
+
+      before do
+        allow(listener).to receive(:safe_thread).and_return(thread)
+      end
+
+      it 'starts and provide status' do
+        listener.start
+        expect(logger).to have_received(:info)
+        expect(listener.status).to eq 'fake_thread'
+      end
+
+      it 'can describe itself' do
+        id = listener.identity
+        expect(id[:consumer]).to_not be_nil
+        expect(id[:logger]).to be logger
+        expect(id[:manager]).to be manager
+        expect(id[:preprocessor]).to be_nil
+        expect(id[:processor]).to_not be_nil
+        expect(id[:topic]).to_not be_nil
+      end
+
+      it 'can be cleanly duplicated' do
+        new_listener = listener.reset_then_dup
+
+        expect(listener.identity).to eq new_listener.identity
+      end
+
+      it 'can be terminated' do
+        listener.start
+        state = listener.instance_variable_get(:@done)
+        expect(state).to eq false
+        listener.terminate
+
+        state = listener.instance_variable_get(:@done)
+        expect(logger).to have_received(:info).twice
+        expect(state).to eq true
+      end
+
+      it 'can be killed' do
+        listener.start
+        state = listener.instance_variable_get(:@done)
+        expect(state).to eq false
+        listener.kill
+
+        state = listener.instance_variable_get(:@done)
+        expect(logger).to have_received(:info).twice
+        expect(thread).to have_received(:raise).with(FastlyNsq::Shutdown)
+        expect(state).to eq true
+      end
+    end
   end
 end

data/spec/lib/fastly_nsq/manager_spec.rb

@@ -0,0 +1,129 @@
+require 'spec_helper'
+require 'fastly_nsq/manager'
+
+RSpec.describe FastlyNsq::Manager do
+  class TestProcessor
+    def self.process(message)
+      FastlyNsq.logger.info("IN PROCESS: #{message}")
+    end
+  end
+
+  let(:listener_1)   { instance_double 'Listener1', new: nil, start: nil, terminate: nil, kill: nil, reset_then_dup: listener_dup }
+  let(:listener_2)   { instance_double 'Listener2', new: nil, start: nil, terminate: nil, kill: nil, reset_then_dup: listener_dup }
+  let(:listener_dup) { instance_double 'ListenerDup', start: nil }
+  let(:manager)      { FastlyNsq::Manager.new options }
+  let(:options)      { { joe: 'biden' } }
+
+  let(:configed_topics) do
+    [
+      { topic: 'warm_topic', klass: TestProcessor },
+      { topic: 'cool_topic', klass: TestProcessor },
+    ]
+  end
+
+  before do
+    logger = Logger.new(STDOUT)
+    logger.level = Logger::FATAL
+
+    FastlyNsq.configure do |config|
+      config.channel = 'william'
+      config.logger = logger
+      config.listener_config do |lc|
+        configed_topics.each do |t|
+          lc.add_topic t[:topic], t[:klass]
+        end
+      end
+    end
+
+    allow(FastlyNsq::Listener).to receive(:new).and_return(listener_1, listener_2)
+    manager.start
+  end
+
+  after do
+    FastlyNsq.reset_config
+  end
+
+  describe '#start' do
+    it 'sets up each configured listener' do
+      configed_topics.each do |t|
+        expect(FastlyNsq::Listener).to have_received(:new).with(
+          {
+            channel:      FastlyNsq.channel,
+            manager:      manager,
+            preprocessor: FastlyNsq.preprocessor,
+            processor:    t[:klass],
+            topic:        t[:topic],
+          },
+        )
+      end
+    end
+
+    it 'starts all listeners' do
+      expect(listener_1).to have_received(:start)
+      expect(listener_2).to have_received(:start)
+    end
+
+    it 'populates @listeners with all created listeners' do
+      expect(manager.listeners).to eq Set.new([listener_1, listener_2])
+    end
+  end
+
+  describe '#quiet' do
+    it 'does nothing if stopping' do
+      manager.instance_variable_set(:@done, true)
+      manager.quiet
+      expect(listener_1).to_not have_received(:terminate)
+      expect(listener_2).to_not have_received(:terminate)
+    end
+
+    it 'terminates all listeners' do
+      manager.quiet
+      expect(listener_1).to have_received(:terminate)
+      expect(listener_2).to have_received(:terminate)
+    end
+  end
+
+  describe '#stop' do
+    it 'does nothing if no listeners exist post quiet' do
+      allow(manager).to receive(:quiet)
+      allow(manager).to receive(:hard_shutdown)
+      manager.instance_variable_set(:@listeners, Set.new)
+
+      manager.stop(Time.now)
+
+      expect(manager).to have_received(:quiet)
+      expect(manager).to_not have_received(:hard_shutdown)
+    end
+
+    it 'forces shutdown if listeners remain after deadline' do
+      allow(manager).to receive(:hard_shutdown).and_call_original
+
+      manager.stop(Time.now)
+
+      expect(manager).to have_received(:hard_shutdown)
+      expect(listener_1).to have_received(:kill)
+      expect(listener_2).to have_received(:kill)
+    end
+  end
+
+  describe '#listener_stopped' do
+    it 'removes listeners from set of listeners' do
+      manager.listener_stopped(listener_1)
+      expect(manager.listeners).to eq Set.new([listener_2])
+    end
+  end
+
+  describe '#listener_killed' do
+    it 'removes listeners from set of listeners' do
+      manager.quiet # mark for stopping
+      manager.listener_killed(listener_1)
+      expect(manager.listeners).to eq Set.new([listener_2])
+    end
+
+    it 'creates and starts replacements if not stopping' do
+      manager.listener_killed(listener_1)
+      expect(manager.listeners).to eq Set.new([listener_dup, listener_2])
+      expect(listener_dup).to have_received(:start)
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fastly_nsq
 version: !ruby/object:Gem::Version
-  version: 0.9.5
+  version: 0.10.0
 platform: ruby
 authors:
 - Tommy O'Neil
@@ -11,7 +11,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-05-25 00:00:00.000000000 Z
+date: 2017-06-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: awesome_print
@@ -55,6 +55,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.5.0
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  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: overcommit
   requirement: !ruby/object:Gem::Requirement
@@ -175,7 +189,8 @@ dependencies:
         version: 2.0.5
 description: Helper classes for Fastly's NSQ Services
 email: tommy@fastly.com
-executables: []
+executables:
+- fastly_nsq
 extensions: []
 extra_rdoc_files: []
 files:
@@ -192,25 +207,35 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- bin/fastly_nsq
 - env_configuration_for_local_gem_tests.yml
+- example_config_class.rb
 - examples/.sample.env
 - examples/Rakefile
 - fastly_nsq.gemspec
 - lib/fastly_nsq.rb
+- lib/fastly_nsq/cli.rb
 - lib/fastly_nsq/consumer.rb
 - lib/fastly_nsq/fake_backend.rb
+- lib/fastly_nsq/launcher.rb
 - lib/fastly_nsq/listener.rb
+- lib/fastly_nsq/listener/config.rb
+- lib/fastly_nsq/manager.rb
 - lib/fastly_nsq/message.rb
 - lib/fastly_nsq/messenger.rb
 - lib/fastly_nsq/producer.rb
 - lib/fastly_nsq/rake_task.rb
+- lib/fastly_nsq/safe_thread.rb
 - lib/fastly_nsq/strategy.rb
 - lib/fastly_nsq/tls_options.rb
 - lib/fastly_nsq/version.rb
+- spec/lib/fastly_nsq/cli_spec.rb
 - spec/lib/fastly_nsq/consumer_spec.rb
 - spec/lib/fastly_nsq/fake_backend_spec.rb
 - spec/lib/fastly_nsq/fastly_nsq_spec.rb
+- spec/lib/fastly_nsq/launcher_spec.rb
 - spec/lib/fastly_nsq/listener_spec.rb
+- spec/lib/fastly_nsq/manager_spec.rb
 - spec/lib/fastly_nsq/message_spec.rb
 - spec/lib/fastly_nsq/messenger_spec.rb
 - spec/lib/fastly_nsq/producer_spec.rb