Initial Commit

Reason for Change
=================
* Create an initial commit of the work which was happening privately.

Changes
=======
* Add all of the files including the documentation.

.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+README.md
+CHANGELOG.md
+
+LICENSE.txt

.gitignore

@@ -0,0 +1,5 @@
+/.bundle
+/Gemfile.lock
+/html/
+/pkg/
+/vendor/cache/*.gem

.rdoc_options

@@ -0,0 +1,16 @@
+--- !ruby/object:RDoc::Options
+encoding: UTF-8
+static_path: []
+rdoc_include:
+  - .
+charset: UTF-8
+exclude:
+hyperlink_all: false
+line_numbers: false
+main_page: README.md
+markup: markdown
+show_hash: false
+tab_width: 8
+title: fastly_nsq Documentation
+visibility: :protected
+webcvs:

.travis.yml

@@ -0,0 +1,18 @@
+language: ruby
+cache: bundler
+rvm:
+  - 2.0
+  - 2.1
+  - 2.2
+  - 2.3
+script:
+  - bundle exec rake test
+notifications:
+  slack:
+    rooms:
+      - 'fastly:hFvhBQKliYl9QAO3VujcrLhe#billy'
+    on_success: change
+    on_failure: change
+  email:
+    on_success: never
+    on_failure: never

ChangeLog.md

@@ -0,0 +1,3 @@
+### 0.1.0 / 2016-01-25
+
+* Initial release:

Gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'minitest-utils', require: false

LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2016 Fastly, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -0,0 +1,200 @@
+# fastly_nsq
+
+NSQ adapter and testing objects
+for using the NSQ messaging system
+in your Ruby project.
+
+This library is intended
+to facilitate publishing and consuming
+messages on an NSQ messaging queue.
+
+We also include a fake queue
+to make testing easier.
+
+This library is dependent
+on the [`nsq-ruby`] gem.
+
+[`nsq-ruby`]: https://github.com/wistia/nsq-ruby
+
+Please use [GitHub Issues] to report bugs.
+
+[GitHub Issues]: https://github.com/fastly/fastly_nsq/issues
+
+
+## Install
+
+`fastly_nsq` is a Ruby Gem
+tested against Rails `>= 4.2`
+and Ruby `>= 2.0`.
+
+To get started,
+add `fastly_nsq` to your `Gemfile`
+and `bundle install`.
+
+The gem includes the following objects:
+
+### [`MessageQueue`]
+
+This is an adapter class
+which takes a required `topic` string
+and provides entry points
+for the queue's message producer and consumer classes.
+
+The queue strategy used
+can be switched
+by adding an environment variable
+to your application:
+
+```ruby
+if ENV['FAKE_QUEUE'] == true
+  FakeMessageQueue
+else
+  NsqMessageQueue
+end
+```
+
+[`MessageQueue`]: lib/fastly_nsq/message_queue.rb
+
+
+### [`NsqMessageQueue`]
+
+This strategy
+creates a connection
+to `nsq-ruby`'s
+`Nsq::Producer` and `Nsq::Consumer` classes.
+
+[`NsqMessageQueue`]: lib/fastly_nsq/nsq_message_queue.rb
+
+
+### [`FakeMessageQueue`]
+
+This strategy
+mocks the connection
+to NSQ for testing purposes.
+
+It adheres to the same API
+as `NsqMessageQueue`.
+
+[`FakeMessageQueue`]: lib/fastly_nsq/fake_message_queue.rb
+
+
+*IMPORTANT NOTE:* You must create your own `MessageProcessor` class
+for this gem to work in your application.
+
+See more information below.
+
+
+## Configuration
+
+### Processing Messages
+
+This gem expects you to create a
+new class called `MessageProcessor`
+which will process messages
+once they are consumed off of the queue topic.
+
+This class needs to adhere to the following API:
+
+```ruby
+class MessageProcessor
+  # This an instance of NSQ::Message or FakeMessageQueue::Message
+  def initialize(message)
+    @message = message
+  end
+
+  def start
+    # Do things with the message. It's JSON body is accessible by @message.body.
+
+    # Finish the message to let the queue know it is complete like so:
+    @message.finish
+  end
+end
+```
+
+### Environment Variables
+
+The URLs for the various
+NSQ endpoints are expected
+in `ENV` variables.
+
+Below are the required variables
+and sample values for using
+stock NSQ on OS X,
+installed via Homebrew:
+
+```shell
+BROADCAST_ADDRESS='127.0.0.1'
+NSQD_TCP_ADDRESS='127.0.0.1:4150'
+NSQD_HTTP_ADDRESS='127.0.0.1:4151'
+NSQLOOKUPD_TCP_ADDRESS='127.0.0.1:4160'
+NSQLOOKUPD_HTTP_ADDRESS='127.0.0.1:4161'
+```
+
+See the [`.sample.env`](examples/.sample.env) file
+for more detail.
+
+### Live vs. Fake
+
+In the gem's test suite,
+the fake message queue is used.
+
+If you would like to force
+use of the real NSQ adapter,
+ensure `FAKE_QUEUE` is *not* set to anything in `ENV`.
+
+When you are developing your application,
+it is recommended to
+start by using the fake queue:
+
+```shell
+FAKE_QUEUE=true
+```
+
+Also note that during gem tests,
+we are aliasing `MessageProcessor` to `SampleMessageProcessor`.
+You can also refer to the latter
+as an example of how
+you might write your own processor.
+
+
+## How to Use the Gem
+### Publishing Messages
+
+To publish a message on the queue:
+
+```ruby
+message_data = {
+  "event_type": "heartbeat",
+  "data": {
+    "service": "Northstar"
+  }
+}
+message_string = message_data.to_json
+producer = MessageQueue.new(topic: 'northstar').producer
+producer.write(message_string)
+```
+
+### Consuming Messages
+
+To consume the next message on the queue:
+
+```ruby
+# TBD!!!!!
+# Waiting until I put the `QueueListener` stuff in here...
+```
+
+## Additional Reference
+
+## Acknowledgements
+
+* Documentation inspired by [Steve Losh's "Teach Don't Tell"] post.
+* Thanks to Wistia for `nsq-ruby`.
+
+[Steve Losh's "Teach Don't Tell"]: http://stevelosh.com/blog/2013/09/teach-dont-tell/
+
+
+## Copyright
+
+Copyright (c) 2016 Fastly, Inc under an MIT license.
+
+See [LICENSE.txt](LICENSE.txt) for details.

Rakefile

@@ -0,0 +1,40 @@
+# encoding: utf-8
+
+require 'rubygems'
+
+begin
+  require 'bundler/setup'
+rescue LoadError => e
+  abort e.message
+end
+
+require 'rake'
+
+require 'rubygems/tasks'
+Gem::Tasks.new
+
+require 'rdoc/task'
+RDoc::Task.new
+task doc: :rdoc
+
+require 'rake/testtask'
+
+Rake::TestTask.new do |test|
+  test.libs << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+require 'bundler/audit/cli'
+
+namespace :bundler do
+  desc 'Updates the ruby-advisory-db and runs audit'
+  task :audit do
+    %w(update check).each do |command|
+      Bundler::Audit::CLI.start [command]
+    end
+  end
+end
+
+task(:default).clear
+task default: ['test', 'bundler:audit']

env_configuration_for_local_gem_tests.yml

@@ -0,0 +1,6 @@
+BROADCAST_ADDRESS: '127.0.0.1'
+NSQD_TCP_ADDRESS: '127.0.0.1:4150'
+NSQD_HTTP_ADDRESS: '127.0.0.1:4151'
+NSQLOOKUPD_TCP_ADDRESS: '127.0.0.1:4160'
+NSQLOOKUPD_HTTP_ADDRESS: '127.0.0.1:4161'
+FAKE_QUEUE: 'true'

examples/.sample.env

@@ -0,0 +1,17 @@
+# NSQ
+# In the Fastly Dev VM
+BROADCAST_ADDRESS='billing'
+NSQD_TCP_ADDRESS='billing:1910'
+NSQD_HTTP_ADDRESS='billing:1911'
+NSQLOOKUPD_TCP_ADDRESS='billing:4160'
+NSQLOOKUPD_HTTP_ADDRESS='billing:4161'
+
+# On OSX with Homebrew defaults (brew install nsq)
+BROADCAST_ADDRESS='127.0.0.1'
+NSQD_TCP_ADDRESS='127.0.0.1:4150'
+NSQD_HTTP_ADDRESS='127.0.0.1:4151'
+NSQLOOKUPD_TCP_ADDRESS='127.0.0.1:4160'
+NSQLOOKUPD_HTTP_ADDRESS='127.0.0.1:4161'
+
+# Uncomment to test against a live queue
+#LIVE_QUEUE=true

fastly_nsq.gemspec

@@ -0,0 +1,35 @@
+# -*- encoding: utf-8 -*-
+
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'fastly_nsq/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = 'fastly_nsq'
+  gem.version       = FastlyNsq::VERSION
+  gem.summary       = 'Fastly NSQ Adapter'
+  gem.description   = "Helper classes for Fastly's NSQ Services"
+  gem.license       = 'MIT'
+  gem.authors       = ["Tommy O'Neill, Adarsh Pandit"]
+  gem.email         = '[email protected]'
+  gem.homepage      = 'https://github.com/fastly/fastly-nsq'
+
+  gem.files         = ['lib/fastly_nsq']
+
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|features)/})
+  gem.require_paths = ['lib']
+
+  gem.add_development_dependency 'awesome_print', '~> 1.6'
+  gem.add_development_dependency 'bundler', '~> 1.10'
+  gem.add_development_dependency 'bundler-audit', '~> 0.4'
+  gem.add_development_dependency 'minitest', '~> 5.8'
+  gem.add_development_dependency 'pry-byebug', '~> 3.3'
+  gem.add_development_dependency 'rake', '~> 10.5'
+  gem.add_development_dependency 'rdoc', '~> 4.2'
+  gem.add_development_dependency 'rspec-mocks', '~> 3.4'
+  gem.add_development_dependency 'rubygems-tasks', '~> 0.2'
+
+  gem.add_dependency 'activesupport', '~> 4.2', '>= 4.2.5.1'
+  gem.add_dependency 'nsq-ruby', '~> 1.5.0', '>= 1.5.0'
+end

lib/fastly_nsq.rb

@@ -0,0 +1,7 @@
+require 'fastly_nsq/version'
+
+require 'fastly_nsq/message_queue'
+require 'fastly_nsq/fake_message_queue'
+require 'fastly_nsq/nsq_message_queue'
+
+require 'fastly_nsq/queue_listener'