ruby_nest_nats 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0dbcc88e2386b8f1b6408688c8fafba196037fb70e089a6f51fd4fca2f4b06a1
-  data.tar.gz: 96b78dccc0a509f21bd1ed5573940e57b76a51df21e20b6a95fd2f145b067714
+  metadata.gz: 12ced8e11e87c01a5106285c4b01e7cb75f338adbb952b95d2362d928c76133c
+  data.tar.gz: '049dd24c5e1015e8b3e90be3f77f352bd934c7837c71881e8f4235a47498e2ec'
 SHA512:
-  metadata.gz: 06db896c2a6e94bac268624a7e75e9e6fa203bc6c6955a6893f661b11c5249faf0b97c397ebc9b646b395b781597b8d4b5cf2d0718ee233014bb62f3ccc27d9f
-  data.tar.gz: 0d5f123eadb77873eeed442162f72b20693696a9f1a57b9759edac7df74ab147df48a8ebe16a7d4f124a897bddc303941f84cac294457a08fcc3bf8ef3199b5f
+  metadata.gz: 3340f499fe967b290f3b2b21e2f34b69a55ed8b8a003c9e0af897df556890fcb884bdf99f25f67e5195a614c4fde21f311d395d7376bab07b1f51fe88bd37b56
+  data.tar.gz: 23eabe3e8b26ba41f9e4ca38f55e8ae48c7362a4658d16d92a9b6284843d55ce34a912c3eae8ad8d312a14457b5ea230cc85422bbde3539c66b3788f1c52ba6d

data/README.md

@@ -1,46 +1,202 @@
 # RubyNestNats
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/ruby_nest_nats`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+The `ruby_nest_nats` gem allows you to listen for (and reply to) NATS messages asynchronously in a Ruby application.
 
 ## TODO
 
-- [ ] docs
+- [x] docs
 - [ ] tests
-- [ ] multiple queues
+- [ ] "controller"-style classes for reply organization
+- [x] multiple queues
 - [ ] `on_error` handler so you can send a response (what's standard?)
+- [ ] config options for URL/host/port/etc.
 - [ ] config for restart behavior (default is to restart listening on any `StandardError`)
 
 ## Installation
 
-Add this line to your application's Gemfile:
+### Locally (to your application)
+
+Add the gem to your application's `Gemfile`:
 
 ```ruby
 gem 'ruby_nest_nats'
 ```
 
-And then execute:
+...and then run:
 
-    $ bundle install
+```bash
+bundle install
+```
 
-Or install it yourself as:
+### Globally (to your system)
 
-    $ gem install ruby_nest_nats
+Alternatively, install it globally:
+
+```bash
+gem install ruby_nest_nats
+```
 
 ## Usage
 
-TODO: Write usage instructions here
+### Logging
+
+#### Attaching a logger
+
+Attach a logger to have `ruby_nest_nats` write out logs for messages received, responses sent, errors raised, lifecycle events, etc.
+
+```rb
+require 'logger'
+
+nats_logger = Logger.new(STDOUT)
+nats_logger.level = Logger::INFO
+
+RubyNestNats::Client.logger = nats_logger
+```
+
+In a Rails application, you might do this instead:
+
+```rb
+RubyNestNats::Client.logger = Rails.logger
+```
+
+#### Log levels
+
+The following will be logged at the specified log levels
+
+- `DEBUG`: Lifecycle events (starting NATS listeners, stopping NATS, reply registration, setting the default queue, etc.), as well as everything under `INFO`, `WARN`, and `ERROR`
+- `INFO`: Message activity over NATS (received a message, replied with a message, etc.), as well as everything under `WARN` and `ERROR`
+- `WARN`: Error handled gracefully (listening restarted due to some exception, etc.), as well as everything under `ERROR`
+- `ERROR`: Some exception was raised in-thread (error in handler, error in subscription, etc.)
+
+### Setting a default queue
+
+Set a default queue for subscriptions.
+
+```rb
+RubyNestNats::Client.default_queue = "foobar"
+```
+
+Leave the `::default_queue` blank (or assign `nil`) to use no default queue.
+
+```rb
+RubyNestNats::Client.default_queue = nil
+```
+
+### Registering message handlers
+
+Register a message handler with the `RubyNestNats::Client::reply_to` method. Pass a subject string as the first argument (either a static subject string or a pattern to match more than one subject). Specify a queue (or don't) with the `queue:` option. If you don't provide the `queue:` option, it will be set to the value of `default_queue`, or to `nil` (no queue) if a default queue hasn't been set.
+
+The result of the given block will be published in reply to the message. The block is passed two arguments when a message matching the subject is received: `data` and `subject`. The `data` argument is the payload of the message (JSON objects/arrays will be parsed into string-keyed `Hash` objects/`Array` objects, respectively). The `subject` argument is the subject of the message received (mostly only useful if a _pattern_ was specified instead of a static subject string).
+
+```rb
+RubyNestNats::Client.reply_to("some.subject", queue: "foobar") { |data| "Got it! #{data.inspect}" }
+
+RubyNestNats::Client.reply_to("some.*.pattern") { |data, subject| "Got #{data} on #{subject}" }
+
+RubyNestNats::Client.reply_to("other.subject") do |data|
+  if data["foo"] == "bar"
+    { is_bar: "Yep!" }
+  else
+    { is_bar: "No way!" }
+  end
+end
+
+RubyNestNats::Client.reply_to("subject.in.queue", queue: "barbaz") do
+  "My turn!"
+end
+```
+
+### Starting the listeners
+
+Start listening for messages with the `RubyNestNats::Client::start!` method. This will spin up a non-blocking thread that subscribes to subjects (as specified by invocation(s) of `::reply_to`) and waits for messages to come in. When a message is received, the appropriate `::reply_to` block will be used to compute a response, and that response will be published.
+
+> **NOTE:** If an error is raised in one of the handlers, `RubyNestNats::Client` will restart automatically.
+
+```rb
+RubyNestNats::Client.start!
+```
+
+### Full example
+
+```rb
+RubyNestNats::Client.logger = Rails.logger
+RubyNestNats::Client.default_queue = "foobar"
+
+RubyNestNats::Client.reply_to("some.subject") { |data| "Got it! #{data.inspect}" }
+RubyNestNats::Client.reply_to("some.*.pattern") { |data, subject| "Got #{data} on #{subject}" }
+RubyNestNats::Client.reply_to("subject.in.queue", queue: "barbaz") { { msg: "My turn!", turn: 5 } }
+
+RubyNestNats::Client.start!
+```
 
 ## Development
 
+### Install dependencies
+
+To install the Ruby dependencies, run:
+
+```bash
+bin/setup
+```
+
+This gem also requires a NATS server to be running. See [the NATS documentation](https://docs.nats.io/nats-server/installation) for more details.
+
+### Open a console
+
+To open a REPL with the gem's code loaded, run:
+
+```bash
+bin/console
+```
+
+### Run the tests
+
+To run the RSpec test suites, run:
+
+```bash
+bundle exec rake spec
+```
+
+...or (if your Ruby setup has good defaults) just this:
+
+```bash
+rake spec
+```
+
+### Run the linter
+
+```bash
+bundle exec rubocop
+```
+
+### Create a release
+
+Bump the `RubyNestNats::VERSION` value in `lib/ruby_nest_nats/version.rb`, commit, and then run:
+
+```bash
+bundle exec rake release
+```
+
+...or (if your Ruby setup has good defaults) just this:
+
+```bash
+rake release
+```
+
+This will:
+
+1. create a git tag for the new version,
+1. push the commits,
+1. build the gem, and
+1. push it to [rubygems.org](https://rubygems.org/gems/ruby_nest_nats).
+
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/ruby_nest_nats.
+Bug reports and pull requests are welcome on GitHub at https://github.com/Openbay/ruby_nest_nats.
 
 ## License
 

data/lib/ruby_nest_nats.rb

@@ -9,6 +9,7 @@ module RubyNestNats
   class Client
     class << self
       def logger=(some_logger)
+        log("Setting the logger to #{some_logger.inspect}")
         @logger = some_logger
       end
 
@@ -16,82 +17,148 @@ module RubyNestNats
         @logger
       end
 
-      def log(text)
-        logger.info("RubyNestNats | #{text}") if logger
+      def default_queue=(some_queue)
+        queue = presence(some_queue.to_s)
+        log("Setting the default queue to #{queue}", level: :debug)
+        @default_queue = queue
       end
 
-      def queue=(some_queue)
-        @queue = some_queue.to_s
-      end
-
-      def queue
-        @queue
-      end
-
-      def replies
-        @replies ||= []
+      def default_queue
+        @default_queue
       end
 
       def started?
         @started ||= false
       end
 
-      def reply_to(raw_subject, &block)
-        subject = raw_subject.to_s
-
-        if started?
-          raise StandardError, "NATS already started"
-        elsif !block_given?
-          raise ArgumentError, "Response block must be provided"
-        elsif replies.any? { |reply| reply[:subject] == subject }
-          raise ArgumentError, "Already registered a reply to #{subject}"
-        end
+      def stopped?
+        !started?
+      end
 
-        log("Registering a reply handler for subject '#{subject}'#{" in queue '#{queue}'" if queue}")
-        replies << { subject: subject, handler: block, queue: queue }
+      def reply_to(subject, queue: nil, &block)
+        subject = subject.to_s
+        queue = (presence(queue) || default_queue).to_s
+        log("Registering a reply handler for subject '#{subject}'#{" in queue '#{queue}'" if queue}", level: :debug)
+        register_reply!(subject: subject, handler: block, queue: queue)
       end
 
       def listen
         NATS.start do
           replies.each do |replier|
+            log("Subscribing to subject '#{replier[:subject]}'#{" in queue '#{replier[:queue]}'" if replier[:queue]}", level: :debug)
+
             NATS.subscribe(replier[:subject], queue: replier[:queue]) do |message, inbox, subject|
-              log("Received the message '#{message}' for subject '#{subject}' with reply inbox '#{inbox}'")
-              response = replier[:handler].call(JSON.parse(message)["data"])
-              log("Responding with '#{response}'")
-              NATS.publish(inbox, response.to_json, queue: replier[:queue])
+              parsed_message = JSON.parse(message)
+              id, data, pattern = parsed_message.values_at("id", "data", "pattern")
+
+              log("Received a message!")
+              message_desc = <<~LOG_MESSAGE
+                id:      #{id || '(none)'}
+                pattern: #{pattern || '(none)'}
+                subject: #{subject || '(none)'}
+                data:    #{data.to_json}
+                inbox:   #{inbox || '(none)'}
+              LOG_MESSAGE
+              log(message_desc, indent: 2)
+
+              response_data = replier[:handler].call(data)
+
+              log("Responding with '#{response_data}'")
+
+              NATS.publish(inbox, response_data.to_json, queue: replier[:queue])
             end
           end
         end
       end
 
       def stop!
-        log("Stopping NATS")
-        NATS.stop
-        @started = false
+        log("Stopping NATS", level: :debug)
+        NATS.stop rescue nil
+        stopped!
       end
 
       def restart!
-        log("Restarting NATS...")
+        log("Restarting NATS", level: :warn)
         stop!
         start!
       end
 
       def start!
-        log("Starting NATS")
-        return log("NATS is already running") if started?
+        log("Starting NATS", level: :debug)
 
-        @started = true
+        if started?
+          log("NATS is already running", level: :debug)
+          return
+        end
+
+        started!
 
         Thread.new do
           Thread.handle_interrupt(StandardError => :never) do
             begin
               Thread.handle_interrupt(StandardError => :immediate) { listen }
-            ensure
+            rescue => e
+              log("Encountered an error:", level: :error)
+              log(e.full_message, level: :error, indent: 2)
+
               restart!
+              raise e
             end
           end
         end
       end
+
+      private
+
+      def log(text, level: :info, indent: 0)
+        return unless logger
+
+        timestamp = Time.now.to_s
+        text_lines = text.split("\n")
+        indentation = indent.is_a?(String) ? indent : (" " * indent)
+
+        text_lines.each do |line|
+          logger.send(level, "[#{timestamp}] RubyNestNats | #{indentation}#{line}")
+        end
+      end
+
+      def started!
+        @started = true
+      end
+
+      def stopped!
+        @started = false
+      end
+
+      def replies
+        @replies ||= []
+      end
+
+      def reply_registered?(raw_subject)
+        subject = raw_subject.to_s
+        replies.any? { |reply| reply[:subject] == subject }
+      end
+
+      def register_reply!(subject:, handler:, queue: nil)
+        raise StandardError, "NATS already started" if started? # TODO: remove when runtime additions are implemented
+        raise ArgumentError, "Subject must be a string" unless subject.is_a?(String)
+        raise ArgumentError, "Must provide a message handler for #{subject}" unless handler.respond_to?(:call)
+        raise ArgumentError, "Already registered a reply to #{subject}" if reply_registered?(subject)
+
+        replies << { subject: subject, handler: handler, queue: presence(queue) || default_queue }
+      end
+
+      def blank?(value)
+        value.respond_to?(:empty?) ? value.empty? : !value
+      end
+
+      def present?(value)
+        !blank?(value)
+      end
+
+      def presence(value)
+        present?(value) ? value : nil
+      end
     end
   end
 end

data/lib/ruby_nest_nats/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RubyNestNats
-  VERSION = "0.1.2"
+  VERSION = "0.1.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_nest_nats
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Keegan Leitz