ruby_nest_nats 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c27d22ced425f310876883bb15afd2aaa52b24235bb095551b7981bedca4b210
-  data.tar.gz: 2537c259848226de1481ce0579b2036200b7d0e45a2a6b098fddd988bae16b4d
+  metadata.gz: 8ff7ec8086e242612ea12d75ef5a8a52330b8f84d3cd12bc097be093b00ef5c7
+  data.tar.gz: aae8c3e437f6c94abf4f3c4a551efd009308b0702a064c848e8935ee8087a01f
 SHA512:
-  metadata.gz: b8b7397a66a1f2984d54ae60bc3f299b384695f450a066cb00a64386fcfaf86be7dcad7e1c9e6f9fac4ede7994f41a2f1fa1cbd267563d5551dc2b53ac3512b0
-  data.tar.gz: a998c0f7015d4e6a1700ac23db6516cdd29572b92a1aaa18fe784b144862f5a229123820467a4d1e2e9baa5d5e30a618fbbe3bd526ac5e67b6640e08ca6b7e73
+  metadata.gz: 49f30461903b281191bbd2aa1cfd2d579416b355b0d1f5c5abef3b42057b99a66989a33d8995318bf1c57d66ec4528d8e97f411759dba2cf5d74187d28060120
+  data.tar.gz: 73a64ce207bce9fcb050d535eb21a10ff561da69d328c4a3ebd4cbee6d9a5705f675d0bdbf086f9cffd31eb9a57691de001004a75be3b0cab7149b0744c630e4

data/.rubocop.yml

@@ -26,6 +26,7 @@ Layout/FirstArrayElementIndentation:
 # Metrics
 
 Metrics/AbcSize:
+  Max: 30
   CountRepeatedAttributes: false
   Exclude:
     - 'spec/**/*_spec.rb'

data/README.md

@@ -38,12 +38,24 @@ Alternatively, install it globally:
 gem install ruby_nest_nats
 ```
 
-### NATS server
+### NATS server (important!)
 
-**IMPORTANT:** This gem also requires a NATS server to be installed and running before use. See [the NATS documentation](https://docs.nats.io/nats-server/installation) for more details.
+This gem also requires a NATS server to be installed and running before use. See [the NATS documentation](https://docs.nats.io/nats-server/installation) for more details.
 
 ## Usage
 
+### Starting the NATS server
+
+You'll need to start a NATS server before running your Ruby application. If you installed it via Docker, you might start it like so:
+
+```bash
+docker run -p 4222:4222 -p 8222:8222 -p 6222:6222 -ti nats:latest
+```
+
+> **NOTE:** You may need to run that command with `sudo` on some systems, depending on the permissions of your Docker installation.
+
+> **NOTE:** For other methods of running a NATS server, see [the NATS documentation](https://docs.nats.io/nats-server/installation).
+
 ### Logging
 
 #### Attaching a logger
@@ -121,12 +133,16 @@ end
 
 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!
 ```
 
+> **NOTE:** If an error is raised in one of the handlers, `RubyNestNats::Client` will restart automatically.
+
+> **NOTE:** You _can_ invoke `::reply_to` to create additional message subscriptions after `RubyNestNats::Client.start!`, but be aware that this forces the client to restart. You may see (benign, already-handled) errors in the logs generated when this restart happens. It will force the client to restart and re-subscribe after _each additional `::reply_to` invoked after `::start!`._ So, if you have a lot of additional `::reply_to` invocations, you may want to consider refactoring so that your call to `RubyNestNats::Client.start!` occurs _after_ those additions.
+
+> **NOTE:** The `::start!` method can be safely called multiple times; only the first will be honored, and any subsequent calls to `::start!` after the client is already started will do nothing (except write a _"NATS is already running"_ log to the logger at the `DEBUG` level).
+
 ### Basic full working example (in vanilla Ruby)
 
 The following should be enough to start a `ruby_nest_nats` setup in your Ruby application, using what we've learned so far.
@@ -150,21 +166,17 @@ RubyNestNats::Client.reply_to("subject.in.queue", queue: "barbaz") { { msg: "My
 RubyNestNats::Client.start!
 ```
 
-> **NOTE:** You _can_ invoke `::reply_to` to create additional message subscriptions after `RubyNestNats::Client.start!`, but be aware that this forces the client to restart. You may see (benign, already-handled) errors in the logs generated when this restart happens. It will force the client to restart and re-subscribe after _each additional `::reply_to` invoked after `::start!`._ So, if you have a lot of additional `::reply_to` invocations, you may want to consider refactoring so that your call to `RubyNestNats::Client.start!` occurs _after_ those additions.
-
-> **NOTE:** The `::start!` method can be safely called multiple times; only the first will be honored, and any subsequent calls to `::start!` after the client is already started will do nothing (except write a _"NATS is already running"_ log to the logger at the `DEBUG` level).
-
 <a id="controller-section"></a>
 
 ### Creating "controller"-style classes for listener organization
 
 Create controller classes which inherit from `RubyNestNats::Controller` in order to give your message listeners some structure.
 
-Use the `::default_queue` macro to set a default queue string. If omitted, the controller will fall back on the default queue assigned with `RubyNestNats::Client::default_queue=` (as described [here](#default-queue-section)). If no default queue is set in either the controller or globally, then the default queue will be blank.
+Use the `::default_queue` macro to set a default queue string. If omitted, the controller will fall back on the global default queue assigned with `RubyNestNats::Client::default_queue=` (as described [here](#default-queue-section)). If no default queue is set in either the controller or globally, then the default queue will be blank. Set the default queue to `nil` in a controller to override the global default queue and explicitly make the default queue blank for that controller.
 
 Use the `::subject` macro to create a block for listening to that subject segment. Nested calls to `::subject` will append each subsequent subject/pattern string to the last (joined by a periods). There is no limit to the level of nesting.
 
-You can register a response for the built-up subject/pattern string using the `::response` macro. Pass a block to `::response` which optionally takes two arguments ([the same arguments supplied to `RubyNestNats::Client::reply_to`](#reply-to-section)). The result of that block will be sent as a response to the message received.
+You can register a response for the built-up subject/pattern string using the `::response` macro. Pass a block to `::response` which optionally takes two arguments ([the same arguments supplied to the block of `RubyNestNats::Client::reply_to`](#reply-to-section)). The result of that block will be sent as a response to the message received.
 
 ```rb
 class HelloController < RubyNestNats::Controller

data/lib/ruby_nest_nats.rb

@@ -6,7 +6,10 @@ require_relative "ruby_nest_nats/utils"
 require_relative "ruby_nest_nats/client"
 require_relative "ruby_nest_nats/controller"
 
+# The `RubyNestNats` module provides the top-level namespace for the NATS client
+# and controller machinery.
 module RubyNestNats
-  class Error < StandardError; end
-  class NewSubscriptionsError < StandardError; end
+  class Error < StandardError; end # :nodoc:
+
+  class NewSubscriptionsError < RubyNestNats::Error; end # :nodoc:
 end

data/lib/ruby_nest_nats/client.rb

@@ -1,43 +1,143 @@
+# frozen_string_literal: true
+
 require "json"
 require "nats/client"
 require_relative "./utils"
 
 module RubyNestNats
+  # The `RubyNestNats::Client` class provides a basic interface for subscribing
+  # to messages by subject & queue, and replying to those messages. It also logs
+  # most functionality if desired.
   class Client
     class << self
+      attr_reader :logger, :default_queue # :nodoc:
+
+      # Attach a logger to have `ruby_nest_nats` write out logs for messages
+      # received, responses sent, errors raised, lifecycle events, etc.
+      #
+      # ```rb
+      # require 'ruby_nest_nats'
+      # 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
+      # ```
+      #
       def logger=(some_logger)
         log("Setting the logger to #{some_logger.inspect}")
         @logger = some_logger
       end
 
-      def logger
-        @logger
-      end
-
+      # 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
+      # ```
+      #
       def default_queue=(some_queue)
         queue = Utils.presence(some_queue.to_s)
         log("Setting the default queue to #{queue || '(none)'}", level: :debug)
         @default_queue = queue
       end
 
-      def default_queue
-        @default_queue
-      end
-
+      # Returns `true` if `::start!` has already been called (meaning the client
+      # is listening to NATS messages). Returns `false` if it has not yet been
+      # called, or if it has been stopped.
       def started?
         @started ||= false
       end
 
+      # Opposite of `::started?`: returns `false` if `::start!` has already been
+      # called (meaning the client is listening to NATS messages). Returns
+      # `true` if it has not yet been called, or if it has been stopped.
       def stopped?
         !started?
       end
 
+      # 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
+      # ```
+      #
       def reply_to(subject, queue: nil, &block)
         queue = Utils.presence(queue) || default_queue
-        log("Registering a reply handler for subject '#{subject}'#{" in queue '#{queue}'" if queue}", level: :debug)
+        queue_desc = " in queue '#{queue}'" if queue
+        log("Registering a reply handler for subject '#{subject}'#{queue_desc}", level: :debug)
         register_reply!(subject: subject.to_s, handler: block, queue: queue.to_s)
       end
 
+      # 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.
+      #
+      # ```rb
+      # RubyNestNats::Client.start!
+      # ```
+      #
+      # **NOTE:** If an error is raised in one of the handlers,
+      # `RubyNestNats::Client` will restart automatically.
+      #
+      # **NOTE:** You _can_ invoke `::reply_to` to create additional message
+      # subscriptions after `RubyNestNats::Client.start!`, but be aware that
+      # this forces the client to restart. You may see (benign, already-handled)
+      # errors in the logs generated when this restart happens. It will force
+      # the client to restart and re-subscribe after _each additional
+      # `::reply_to` invoked after `::start!`._ So, if you have a lot of
+      # additional `::reply_to` invocations, you may want to consider
+      # refactoring so that your call to `RubyNestNats::Client.start!` occurs
+      # _after_ those additions.
+      #
+      # **NOTE:** The `::start!` method can be safely called multiple times;
+      # only the first will be honored, and any subsequent calls to `::start!`
+      # after the client is already started will do nothing (except write a
+      # _"NATS is already running"_ log to the logger at the `DEBUG` level).
+      #
       def start!
         log("Starting NATS", level: :debug)
 
@@ -50,22 +150,20 @@ module RubyNestNats
 
         self.current_thread = Thread.new do
           Thread.handle_interrupt(StandardError => :never) do
-            begin
-              Thread.handle_interrupt(StandardError => :immediate) { listen }
-            rescue NATS::ConnectError => e
-              log("Could not connect to NATS server:", level: :error)
-              log(e.full_message, level: :error, indent: 2)
-              Thread.current.exit
-            rescue NewSubscriptionsError => e
-              log("New subscriptions! Restarting...", level: :info)
-              restart!
-              raise e # TODO: there has to be a better way
-            rescue StandardError => e
-              log("Encountered an error:", level: :error)
-              log(e.full_message, level: :error, indent: 2)
-              restart!
-              raise e
-            end
+            Thread.handle_interrupt(StandardError => :immediate) { listen }
+          rescue NATS::ConnectError => e
+            log("Could not connect to NATS server:", level: :error)
+            log(e.full_message, level: :error, indent: 2)
+            Thread.current.exit
+          rescue NewSubscriptionsError => e
+            log("New subscriptions! Restarting...", level: :info)
+            restart!
+            raise e # TODO: there has to be a better way
+          rescue StandardError => e
+            log("Encountered an error:", level: :error)
+            log(e.full_message, level: :error, indent: 2)
+            restart!
+            raise e
           end
         end
       end
@@ -86,7 +184,13 @@ module RubyNestNats
 
       def stop!
         log("Stopping NATS", level: :debug)
-        NATS.stop rescue nil
+
+        begin
+          NATS.stop
+        rescue StandardError
+          nil
+        end
+
         stopped!
       end
 
@@ -108,13 +212,7 @@ module RubyNestNats
         @replies ||= []
       end
 
-      def current_thread
-        @current_thread
-      end
-
-      def current_thread=(some_thread)
-        @current_thread = some_thread
-      end
+      attr_accessor :current_thread
 
       def reply_registered?(raw_subject)
         subject = raw_subject.to_s
@@ -129,18 +227,19 @@ module RubyNestNats
         reply = {
           subject: subject,
           handler: handler,
-          queue: Utils.presence(queue) || default_queue
+          queue: Utils.presence(queue) || default_queue,
         }
 
         replies << reply
 
-        self.current_thread.raise(NewSubscriptionsError, "New reply registered") if started?
+        current_thread.raise(NewSubscriptionsError, "New reply registered") if started?
       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)
+            queue_desc = " in queue '#{replier[:queue]}'" if replier[:queue]
+            log("Subscribing to subject '#{replier[:subject]}'#{queue_desc}", level: :debug)
 
             NATS.subscribe(replier[:subject], queue: replier[:queue]) do |message, inbox, subject|
               parsed_message = JSON.parse(message)

data/lib/ruby_nest_nats/controller.rb

@@ -1,8 +1,12 @@
+# frozen_string_literal: true
+
 require_relative "./utils"
 
 module RubyNestNats
+  # Create controller classes which inherit from `RubyNestNats::Controller` in
+  # order to give your message listeners some structure.
   class Controller
-    NO_QUEUE_GIVEN = :ruby_nest_nats_super_special_no_op_queue_symbol_qwertyuiop_1234567890
+    NO_QUEUE_GIVEN = :ruby_nest_nats_super_special_no_op_queue_symbol_qwertyuiop1234567890
 
     class << self
       # Default queue for the controller. Falls back to the client's default
@@ -20,6 +24,13 @@ module RubyNestNats
       #       # ...
       #     end
       #
+      # If omitted, the controller will fall back on the global default queue
+      # assigned with `RubyNestNats::Client::default_queue=`. If no default
+      # queue is set in either the controller or globally, then the default
+      # queue will be blank. Set the default queue to `nil` in a controller to
+      # override the global default queue and explicitly make the default queue
+      # blank for that controller.
+      #
       def default_queue(some_queue = NO_QUEUE_GIVEN)
         # `NO_QUEUE_GIVEN` is a special symbol (rather than `nil`) so that the
         # default queue can be "unset" to `nil` (given a non-`nil` global
@@ -31,6 +42,55 @@ module RubyNestNats
         end
       end
 
+      # Use the `::subject` macro to create a block for listening to that
+      # subject segment. Nested calls to `::subject` will append each subsequent
+      # subject/pattern string to the last (joined by a periods). There is no
+      # limit to the level of nesting.
+      #
+      # **NOTE:** The following two examples do exactly the same thing.
+      #
+      # Example:
+      #
+      #     class FoobarNatsController < RubyNatsController
+      #       # ...
+      #
+      #       subject "hello.wassup" do
+      #         response do |data, subject|
+      #           # The subject at this point is "hello.wassup"
+      #           # ...
+      #         end
+      #       end
+      #
+      #       subject "hello.howdy" do
+      #         response do |data, subject|
+      #           # The subject at this point is "hello.howdy"
+      #           # ...
+      #         end
+      #       end
+      #     end
+      #
+      # Example:
+      #
+      #     class FoobarNatsController < RubyNatsController
+      #       # ...
+      #
+      #       subject "hello" do
+      #         subject "wassup" do
+      #           response do |data, subject|
+      #             # The subject at this point is "hello.wassup"
+      #             # ...
+      #           end
+      #         end
+      #
+      #         subject "howdy" do
+      #           response do |data, subject|
+      #             # The subject at this point is "hello.howdy"
+      #             # ...
+      #           end
+      #         end
+      #       end
+      #     end
+      #
       def subject(subject_segment, queue: nil)
         subject_chain.push(subject_segment)
         old_queue = current_queue
@@ -40,6 +100,40 @@ module RubyNestNats
         subject_chain.pop
       end
 
+      # You can register a response for the built-up subject/pattern string
+      # using the `::response` macro. Pass a block to `::response` which
+      # optionally takes two arguments (the same arguments supplied to the block
+      # of `RubyNestNats::Client::reply_to`). The result of that block will be
+      # sent as a response to the message received.
+      #
+      # Example:
+      #
+      #     class FoobarNatsController < RubyNatsController
+      #       # ...
+      #
+      #       subject "hello" do
+      #         subject "wassup" do
+      #           response do |data, subject|
+      #             # The subject at this point is "hello.wassup".
+      #             # Assume the message sent a JSON payload of {"name":"Bob"}
+      #             # in this example.
+      #             # We'll reply with a string response:
+      #             "I'm all right, #{data['name']}"
+      #           end
+      #         end
+      #
+      #         subject "howdy" do
+      #           response do |data, subject|
+      #             # The subject at this point is "hello.howdy".
+      #             # Assume the message sent a JSON payload of {"name":"Bob"}
+      #             # in this example.
+      #             # We'll reply with a JSON response (a Ruby `Hash`):
+      #             { message: "I'm okay, #{data['name']}. Thanks for asking!" }
+      #           end
+      #         end
+      #       end
+      #     end
+      #
       def response(queue: nil, &block)
         response_queue = Utils.presence(queue.to_s) || current_queue || default_queue
         Client.reply_to(current_subject, queue: response_queue, &block)

data/lib/ruby_nest_nats/utils.rb

@@ -1,5 +1,7 @@
+# frozen_string_literal: true
+
 module RubyNestNats
-  class Utils
+  class Utils # :nodoc:
     class << self
       def blank?(value)
         value.respond_to?(:empty?) ? value.empty? : !value

data/lib/ruby_nest_nats/version.rb

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

metadata

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