ruby_nest_nats 0.1.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 655b85cbd8f941a46595d30adde13826cf69e8978a829653596aaa1ebd4d6437
-  data.tar.gz: 1d72decb7def437e62a6302d1885ef18e66940285ccd10abc3bb34b34e44bbd3
+  metadata.gz: 115d647c8fddd551ecd29db19c99ecc6ee958b80406322141d9773219dd24345
+  data.tar.gz: b000384383eef9cf1f484195115aba6ef9bb4727b5baa852a818006a8bbbf876
 SHA512:
-  metadata.gz: 17de52f910afb1eb74da267e29f80cbcfdfb0e2f929c4cc8912b4d7dcb8c445c15a063eb30c11a74b2504ec51196a1af72f141b05a9f96ada6103e8cb519c617
-  data.tar.gz: ffb654a55f20b835fb7e516af5425c192627146a3be9e2fb61cb07f4de79357f7ee6f7eeb2a1f4a36642fb719270ec30005eef39fe2961b65813157c26d49b4d
+  metadata.gz: dbe204fb29c5acc514ff48c026ce34f93e297bcaebceb5e6fade77512e373e2a722b733dc92ac8e5b1228cf9e551f138659ad7511e6ff8a7d9d23740a0e91e74
+  data.tar.gz: 3f2b68a7473b4facddbc954aae0fd38b5d0a1e9b2a72adfd69415a1e7ec712a4d2723a04935d9a30aa25aa83aa681262149aab3047da3d26333d2e98125834fe

data/.rubocop.yml

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

data/README.md

@@ -1,38 +1,318 @@
 # 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.
+The `ruby_nest_nats` gem allows you to listen for (and reply to) NATS messages asynchronously in a Ruby application.
 
-TODO: Delete this and the text above, and describe your gem
+## TODO
+
+- [x] docs
+- [ ] tests
+- [x] "controller"-style classes for reply organization
+- [x] runtime subscription additions
+- [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`)
+- [ ] consider using child processes instead of threads
 
 ## 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:
+
+```bash
+bundle install
+```
 
-    $ bundle install
+### Globally (to your system)
+
+Alternatively, install it globally:
+
+```bash
+gem install ruby_nest_nats
+```
 
-Or install it yourself as:
+### NATS server (important!)
 
-    $ gem install ruby_nest_nats
+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
 
-TODO: Write usage instructions here
+### 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
+
+Attach a logger to have `ruby_nest_nats` write out logs for messages received, responses sent, errors raised, lifecycle events, etc.
+
+```ruby
+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:
+
+```ruby
+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.)
+
+<a id="default-queue-section"></a>
+
+### Setting a default queue
+
+Set a default queue for subscriptions.
+
+```ruby
+RubyNestNats::Client.default_queue = "foobar"
+```
+
+Leave the `::default_queue` blank (or assign `nil`) to use no default queue.
+
+```ruby
+RubyNestNats::Client.default_queue = nil
+```
+
+<a id="reply-to-section"></a>
+
+### 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).
+
+```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}" }
+
+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.
+
+```ruby
+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.
+
+> **NOTE:** For a more organized structure and implementation in a larger app (like a Rails project), see the ["controller" section below](#controller-section).
+
+```ruby
+require 'ruby_nest_nats'
+require 'logger'
+
+nats_logger = Logger.new(STDOUT)
+nats_logger.level = Logger::DEBUG
+
+RubyNestNats::Client.logger = nats_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!
+```
+
+<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 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 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.
+
+```ruby
+class HelloController < RubyNestNats::Controller
+  default_queue "foobar"
+
+  subject "hello" do
+    subject "jerk" do
+      response do |data|
+        # The subject at this point is "hello.jerk"
+        "Hey #{data['name']}... that's not cool, man."
+      end
+    end
+
+    subject "and" do
+      subject "wassup" do
+        response do |data|
+          # The subject at this point is "hello.and.wassup"
+          "Hey, how ya doin', #{data['name']}?"
+        end
+      end
+
+      subject "goodbye" do
+        response do |data|
+          # The subject at this point is "hello.and.goodbye"
+          "Hi #{data['name']}! But also GOODBYE."
+        end
+      end
+    end
+  end
+
+  subject "hows" do
+    subject "*" do
+      subject "doing" do
+        response do |data, subject|
+          # The subject at this point is "hows.<wildcard>.doing" (i.e., the
+          # subjects "hows.jack.doing" and "hows.jill.doing" will both match)
+          sender_name = data["name"]
+          other_person_name = subject.split(".")[1]
+          desc = rand < 0.5 ? "terribly" : "great"
+          "Well, #{sender_name}, #{other_person_name} is actually doing #{desc}."
+        end
+      end
+    end
+  end
+end
+```
+
+> **NOTE:** If you implement controllers like this and you are using code-autoloading machinery (like Zeitwerk in Rails), you will need to make sure these paths are eager-loaded when your app starts. **If you don't, `ruby_nest_nats` will not register the listeners,** and will not respond to messages for the specified subjects.
+>
+> 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`):
+>
+> ```ruby
+> RubyNestNats::Client.logger = Rails.logger
+> RubyNestNats::Client.default_queue = "foobar"
+>
+> # ...
+>
+> Rails.application.config.after_initialize do
+>   nats_controller_paths = Dir[Rails.root.join("app", "nats", "**", "*_controller.rb")]
+>   nats_controller_paths.each { |file_path| require_dependency(file_path) }
+>
+>   RubyNestNats::Client.start!
+> end
+> ```
 
 ## Development
 
+### Install dependencies
+
+To install the Ruby dependencies, run:
+
+```bash
+bin/setup
+```
+
+This gem also requires a NATS server to be installed and running. See [the NATS documentation](https://docs.nats.io/nats-server/installation) for more details.
+<!-- sudo docker run -p 4222:4222 -p 8222:8222 -p 6222:6222 -ti nats:latest -->
+<!-- nats-tail -s nats://localhost:4222 ">" -->
+<!-- curl --data '{"name":"Keegan"}' --header 'Content-Type: application/json' http://localhost:3000/hello -->
+
+### 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

@@ -1,59 +1,17 @@
 # frozen_string_literal: true
 
-require_relative "ruby_nest_nats/version"
 require "nats/client"
+require_relative "ruby_nest_nats/version"
+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
+  # :nodoc:
   class Error < StandardError; end
 
-  class Client
-    class << self
-      def queue=(some_queue)
-        @queue = some_queue.to_s
-      end
-
-      def queue
-        @queue
-      end
-
-      def replies
-        @replies ||= []
-      end
-
-      def started?
-        !!@started
-      end
-
-      def reply_to(raw_subject, with:)
-        subject = raw_subject.to_s
-
-        if started?
-          raise StandardError, "NATS already started"
-        elsif !with.respond_to?(:call)
-          raise ArgumentError, "Option `:with` must be callable"
-        elsif replies.any? { |reply| reply[:subject] == subject }
-          raise ArgumentError, "Already registered a reply to #{subject}"
-        end
-
-        replies << { subject: subject, handler: with, queue: queue }
-      end
-
-      def start!
-        @started = true
-
-        fiber = Fiber.new do
-          NATS.start do
-            replies.each do |replier|
-              NATS.subscribe(replier[:subject], queue: replier[:queue]) do |message, reply, _subject|
-                response = replier[:handler].call(JSON.parse(message)["data"])
-                NATS.publish(reply, response.to_json, queue: reply[:queue])
-              end
-            end
-          end
-        end
-
-        fiber.resume
-      end
-    end
-  end
+  # :nodoc:
+  class NewSubscriptionsError < RubyNestNats::Error; end
 end

data/lib/ruby_nest_nats/client.rb

@@ -0,0 +1,264 @@
+# 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
+      # :nodoc:
+      attr_reader :logger, :default_queue
+
+      # Attach a logger to have +ruby_nest_nats+ write out logs for messages
+      # received, responses sent, errors raised, lifecycle events, etc.
+      #
+      # @example
+      #   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:
+      #
+      # @example
+      #   RubyNestNats::Client.logger = Rails.logger
+      #
+      def logger=(some_logger)
+        log("Setting the logger to #{some_logger.inspect}")
+        @logger = some_logger
+      end
+
+      # Set a default queue for subscriptions.
+      #
+      # @example
+      #   RubyNestNats::Client.default_queue = "foobar"
+      #
+      # Leave the +::default_queue+ blank (or assign +nil+) to use no default
+      # queue.
+      #
+      # @example
+      #   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
+
+      # 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).
+      #
+      # @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("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
+        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.
+      #
+      # @example
+      #   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)
+
+        if started?
+          log("NATS is already running", level: :debug)
+          return
+        end
+
+        started!
+
+        self.current_thread = Thread.new do
+          Thread.handle_interrupt(StandardError => :never) do
+            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
+
+      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 stop!
+        log("Stopping NATS", level: :debug)
+
+        begin
+          NATS.stop
+        rescue StandardError
+          nil
+        end
+
+        stopped!
+      end
+
+      def restart!
+        log("Restarting NATS", level: :warn)
+        stop!
+        start!
+      end
+
+      def started!
+        @started = true
+      end
+
+      def stopped!
+        @started = false
+      end
+
+      def replies
+        @replies ||= []
+      end
+
+      attr_accessor :current_thread
+
+      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 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)
+
+        reply = {
+          subject: subject,
+          handler: handler,
+          queue: Utils.presence(queue) || default_queue,
+        }
+
+        replies << reply
+
+        current_thread.raise(NewSubscriptionsError, "New reply registered") if started?
+      end
+
+      def listen
+        NATS.start do
+          replies.each do |replier|
+            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)
+              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
+    end
+  end
+end

data/lib/ruby_nest_nats/controller.rb

@@ -0,0 +1,158 @@
+# 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
+    # :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+.
+      #
+      # - 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
+      #   class FoobarNatsController < RubyNatsController
+      #     default_queue "foobar"
+      #
+      #     # ...
+      #   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
+        # default set with +RubyNestNats::Client::default_queue=+).
+        if some_queue == NO_QUEUE_GIVEN
+          @default_queue || Client.default_queue
+        else
+          @default_queue = Utils.presence(some_queue.to_s)
+        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
+        self.current_queue = queue if Utils.present?(queue)
+        yield
+        self.current_queue = old_queue
+        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)
+      end
+
+      private
+
+      def subject_chain
+        @subject_chain ||= []
+      end
+
+      def current_subject
+        subject_chain.join(".")
+      end
+
+      def current_queue
+        @current_queue ||= nil
+      end
+
+      def current_queue=(some_queue)
+        @current_queue = Utils.presence(some_queue)
+      end
+    end
+  end
+end

data/lib/ruby_nest_nats/utils.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby_nest_nats
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.2
 platform: ruby
 authors:
 - Keegan Leitz
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-05-11 00:00:00.000000000 Z
+date: 2021-05-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -155,6 +155,9 @@ files:
 - bin/console
 - bin/setup
 - lib/ruby_nest_nats.rb
+- lib/ruby_nest_nats/client.rb
+- lib/ruby_nest_nats/controller.rb
+- lib/ruby_nest_nats/utils.rb
 - lib/ruby_nest_nats/version.rb
 - ruby_nest_nats.gemspec
 homepage: https://github.com/openbay/ruby_nest_nats