ruby_nest_nats 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8ff7ec8086e242612ea12d75ef5a8a52330b8f84d3cd12bc097be093b00ef5c7
-  data.tar.gz: aae8c3e437f6c94abf4f3c4a551efd009308b0702a064c848e8935ee8087a01f
+  metadata.gz: 115d647c8fddd551ecd29db19c99ecc6ee958b80406322141d9773219dd24345
+  data.tar.gz: b000384383eef9cf1f484195115aba6ef9bb4727b5baa852a818006a8bbbf876
 SHA512:
-  metadata.gz: 49f30461903b281191bbd2aa1cfd2d579416b355b0d1f5c5abef3b42057b99a66989a33d8995318bf1c57d66ec4528d8e97f411759dba2cf5d74187d28060120
-  data.tar.gz: 73a64ce207bce9fcb050d535eb21a10ff561da69d328c4a3ebd4cbee6d9a5705f675d0bdbf086f9cffd31eb9a57691de001004a75be3b0cab7149b0744c630e4
+  metadata.gz: dbe204fb29c5acc514ff48c026ce34f93e297bcaebceb5e6fade77512e373e2a722b733dc92ac8e5b1228cf9e551f138659ad7511e6ff8a7d9d23740a0e91e74
+  data.tar.gz: 3f2b68a7473b4facddbc954aae0fd38b5d0a1e9b2a72adfd69415a1e7ec712a4d2723a04935d9a30aa25aa83aa681262149aab3047da3d26333d2e98125834fe

data/README.md

@@ -62,7 +62,7 @@ docker run -p 4222:4222 -p 8222:8222 -p 6222:6222 -ti nats:latest
 
 Attach a logger to have `ruby_nest_nats` write out logs for messages received, responses sent, errors raised, lifecycle events, etc.
 
-```rb
+```ruby
 require 'ruby_nest_nats'
 require 'logger'
 
@@ -74,7 +74,7 @@ RubyNestNats::Client.logger = nats_logger
 
 In a Rails application, you might do this instead:
 
-```rb
+```ruby
 RubyNestNats::Client.logger = Rails.logger
 ```
 
@@ -93,13 +93,13 @@ The following will be logged at the specified log levels
 
 Set a default queue for subscriptions.
 
-```rb
+```ruby
 RubyNestNats::Client.default_queue = "foobar"
 ```
 
 Leave the `::default_queue` blank (or assign `nil`) to use no default queue.
 
-```rb
+```ruby
 RubyNestNats::Client.default_queue = nil
 ```
 
@@ -111,7 +111,7 @@ Register a message handler with the `RubyNestNats::Client::reply_to` method. Pas
 
 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
+```ruby
 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}" }
@@ -133,7 +133,7 @@ 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
+```ruby
 RubyNestNats::Client.start!
 ```
 
@@ -149,7 +149,7 @@ The following should be enough to start a `ruby_nest_nats` setup in your Ruby ap
 
 > **NOTE:** For a more organized structure and implementation in a larger app (like a Rails project), see the ["controller" section below](#controller-section).
 
-```rb
+```ruby
 require 'ruby_nest_nats'
 require 'logger'
 
@@ -178,7 +178,7 @@ Use the `::subject` macro to create a block for listening to that subject segmen
 
 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
+```ruby
 class HelloController < RubyNestNats::Controller
   default_queue "foobar"
 
@@ -228,7 +228,7 @@ end
 >
 > For example: in a Rails project (assuming you have your NATS controllers in a directory called `app/nats/`), you may want to put something like the following in an initializer (such as `config/initializers/nats.rb`):
 >
-> ```rb
+> ```ruby
 > RubyNestNats::Client.logger = Rails.logger
 > RubyNestNats::Client.default_queue = "foobar"
 >

data/lib/ruby_nest_nats.rb

@@ -6,10 +6,12 @@ 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
+# The +RubyNestNats+ module provides the top-level namespace for the NATS client
 # and controller machinery.
 module RubyNestNats
-  class Error < StandardError; end # :nodoc:
+  # :nodoc:
+  class Error < StandardError; end
 
-  class NewSubscriptionsError < RubyNestNats::Error; end # :nodoc:
+  # :nodoc:
+  class NewSubscriptionsError < RubyNestNats::Error; end
 end

data/lib/ruby_nest_nats/client.rb

@@ -5,31 +5,30 @@ require "nats/client"
 require_relative "./utils"
 
 module RubyNestNats
-  # The `RubyNestNats::Client` class provides a basic interface for subscribing
+  # 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:
+      # :nodoc:
+      attr_reader :logger, :default_queue
 
-      # Attach a logger to have `ruby_nest_nats` write out logs for messages
+      # 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'
+      # @example
+      #   require 'ruby_nest_nats'
+      #   require 'logger'
       #
-      # nats_logger = Logger.new(STDOUT)
-      # nats_logger.level = Logger::INFO
+      #   nats_logger = Logger.new(STDOUT)
+      #   nats_logger.level = Logger::INFO
       #
-      # RubyNestNats::Client.logger = nats_logger
-      # ```
+      #   RubyNestNats::Client.logger = nats_logger
       #
       # In a Rails application, you might do this instead:
       #
-      # ```rb
-      # RubyNestNats::Client.logger = Rails.logger
-      # ```
+      # @example
+      #   RubyNestNats::Client.logger = Rails.logger
       #
       def logger=(some_logger)
         log("Setting the logger to #{some_logger.inspect}")
@@ -38,16 +37,14 @@ module RubyNestNats
 
       # Set a default queue for subscriptions.
       #
-      # ```rb
-      # RubyNestNats::Client.default_queue = "foobar"
-      # ```
+      # @example
+      #   RubyNestNats::Client.default_queue = "foobar"
       #
-      # Leave the `::default_queue` blank (or assign `nil`) to use no default
+      # Leave the +::default_queue+ blank (or assign +nil+) to use no default
       # queue.
       #
-      # ```rb
-      # RubyNestNats::Client.default_queue = nil
-      # ```
+      # @example
+      #   RubyNestNats::Client.default_queue = nil
       #
       def default_queue=(some_queue)
         queue = Utils.presence(some_queue.to_s)
@@ -55,52 +52,51 @@ module RubyNestNats
         @default_queue = 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
+      # 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
+      # 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.
+      # +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`
+      # 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.
+      # 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
+      # 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}" }
+      # @example
+      #   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("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!" }
+      #   RubyNestNats::Client.reply_to("other.subject") do |data|
+      #     if data["foo"] == "bar"
+      #       { is_bar: "Yep!" }
+      #     else
+      #       { is_bar: "No way!" }
+      #     end
       #   end
-      # end
       #
-      # RubyNestNats::Client.reply_to("subject.in.queue", queue: "barbaz") do
-      #   "My turn!"
-      # 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
@@ -109,34 +105,33 @@ module RubyNestNats
         register_reply!(subject: subject.to_s, handler: block, queue: queue.to_s)
       end
 
-      # Start listening for messages with the `RubyNestNats::Client::start!`
+      # 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
+      # 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
+      # +::reply_to+ block will be used to compute a response, and that response
       # will be published.
       #
-      # ```rb
-      # RubyNestNats::Client.start!
-      # ```
+      # @example
+      #   RubyNestNats::Client.start!
       #
       # **NOTE:** If an error is raised in one of the handlers,
-      # `RubyNestNats::Client` will restart automatically.
+      # +RubyNestNats::Client+ will restart automatically.
       #
-      # **NOTE:** You _can_ invoke `::reply_to` to create additional message
-      # subscriptions after `RubyNestNats::Client.start!`, but be aware that
+      # **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
+      # +::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!`
+      # **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).
+      # _"NATS is already running"_ log to the logger at the +DEBUG+ level).
       #
       def start!
         log("Starting NATS", level: :debug)

data/lib/ruby_nest_nats/controller.rb

@@ -3,38 +3,38 @@
 require_relative "./utils"
 
 module RubyNestNats
-  # Create controller classes which inherit from `RubyNestNats::Controller` in
+  # Create controller classes which inherit from +RubyNestNats::Controller+ in
   # order to give your message listeners some structure.
   class Controller
+    # :nodoc:
     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
-      # queue if the controller's default queue is `nil`.
+      # queue if the controller's default queue is +nil+.
       #
-      # - Call with no argument (`::default_queue`) to get the default queue.
-      # - Call as a macro with an argument (`default_queue "something"`) to set
+      # - Call with no argument (+::default_queue+) to get the default queue.
+      # - Call as a macro with an argument (+default_queue "something"+) to set
       #   the default queue.
       #
-      # Example:
+      # @example
+      #   class FoobarNatsController < RubyNatsController
+      #     default_queue "foobar"
       #
-      #     class FoobarNatsController < RubyNatsController
-      #       default_queue "foobar"
-      #
-      #       # ...
-      #     end
+      #     # ...
+      #   end
       #
       # If omitted, the controller will fall back on the global default queue
-      # assigned with `RubyNestNats::Client::default_queue=`. If no default
+      # 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
+      # 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
-        # default set with `RubyNestNats::Client::default_queue=`).
+        # +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
+        # default set with +RubyNestNats::Client::default_queue=+).
         if some_queue == NO_QUEUE_GIVEN
           @default_queue || Client.default_queue
         else
@@ -42,54 +42,52 @@ 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
+      # 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:
+      # @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
       #
-      #     class FoobarNatsController < RubyNatsController
-      #       # ...
+      # @example
+      #   class FoobarNatsController < RubyNatsController
+      #     # ...
       #
-      #       subject "hello.wassup" do
+      #     subject "hello" do
+      #       subject "wassup" do
       #         response do |data, subject|
       #           # The subject at this point is "hello.wassup"
       #           # ...
       #         end
       #       end
       #
-      #       subject "hello.howdy" do
+      #       subject "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
+      #   end
       #
       def subject(subject_segment, queue: nil)
         subject_chain.push(subject_segment)
@@ -101,38 +99,37 @@ module RubyNestNats
       end
 
       # You can register a response for the built-up subject/pattern string
-      # using the `::response` macro. Pass a block to `::response` which
+      # 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
+      # of +RubyNestNats::Client::reply_to+). The result of that block will be
       # sent as a response to the message received.
       #
-      # Example:
-      #
-      #     class FoobarNatsController < RubyNatsController
-      #       # ...
+      # @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
+      #     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
+      #       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

data/lib/ruby_nest_nats/utils.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 module RubyNestNats
-  class Utils # :nodoc:
+  # :nodoc:
+  class Utils
     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.1"
+  VERSION = "0.2.2"
 end

metadata

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