ruby_nest_nats 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12ced8e11e87c01a5106285c4b01e7cb75f338adbb952b95d2362d928c76133c
-  data.tar.gz: '049dd24c5e1015e8b3e90be3f77f352bd934c7837c71881e8f4235a47498e2ec'
+  metadata.gz: c27d22ced425f310876883bb15afd2aaa52b24235bb095551b7981bedca4b210
+  data.tar.gz: 2537c259848226de1481ce0579b2036200b7d0e45a2a6b098fddd988bae16b4d
 SHA512:
-  metadata.gz: 3340f499fe967b290f3b2b21e2f34b69a55ed8b8a003c9e0af897df556890fcb884bdf99f25f67e5195a614c4fde21f311d395d7376bab07b1f51fe88bd37b56
-  data.tar.gz: 23eabe3e8b26ba41f9e4ca38f55e8ae48c7362a4658d16d92a9b6284843d55ce34a912c3eae8ad8d312a14457b5ea230cc85422bbde3539c66b3788f1c52ba6d
+  metadata.gz: b8b7397a66a1f2984d54ae60bc3f299b384695f450a066cb00a64386fcfaf86be7dcad7e1c9e6f9fac4ede7994f41a2f1fa1cbd267563d5551dc2b53ac3512b0
+  data.tar.gz: a998c0f7015d4e6a1700ac23db6516cdd29572b92a1aaa18fe784b144862f5a229123820467a4d1e2e9baa5d5e30a618fbbe3bd526ac5e67b6640e08ca6b7e73

data/README.md

@@ -6,11 +6,13 @@ The `ruby_nest_nats` gem allows you to listen for (and reply to) NATS messages a
 
 - [x] docs
 - [ ] tests
-- [ ] "controller"-style classes for reply organization
+- [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
 
@@ -36,6 +38,10 @@ Alternatively, install it globally:
 gem install ruby_nest_nats
 ```
 
+### NATS server
+
+**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.
+
 ## Usage
 
 ### Logging
@@ -45,6 +51,7 @@ gem install ruby_nest_nats
 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)
@@ -68,6 +75,8 @@ The following will be logged at the specified log levels
 - `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.
@@ -82,6 +91,8 @@ Leave the `::default_queue` blank (or assign `nil`) to use no default queue.
 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.
@@ -116,10 +127,20 @@ Start listening for messages with the `RubyNestNats::Client::start!` method. Thi
 RubyNestNats::Client.start!
 ```
 
-### Full example
+### 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).
 
 ```rb
-RubyNestNats::Client.logger = Rails.logger
+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}" }
@@ -129,6 +150,86 @@ 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 `::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.
+
+```rb
+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`):
+>
+> ```rb
+> 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
@@ -139,7 +240,10 @@ To install the Ruby dependencies, run:
 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.
+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
 

data/lib/ruby_nest_nats.rb

@@ -1,164 +1,12 @@
 # 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"
 
 module RubyNestNats
   class Error < StandardError; end
-
-  class Client
-    class << self
-      def logger=(some_logger)
-        log("Setting the logger to #{some_logger.inspect}")
-        @logger = some_logger
-      end
-
-      def logger
-        @logger
-      end
-
-      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 default_queue
-        @default_queue
-      end
-
-      def started?
-        @started ||= false
-      end
-
-      def stopped?
-        !started?
-      end
-
-      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|
-              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", level: :debug)
-        NATS.stop rescue nil
-        stopped!
-      end
-
-      def restart!
-        log("Restarting NATS", level: :warn)
-        stop!
-        start!
-      end
-
-      def start!
-        log("Starting NATS", level: :debug)
-
-        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 }
-            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
+  class NewSubscriptionsError < StandardError; end
 end

data/lib/ruby_nest_nats/client.rb

@@ -0,0 +1,170 @@
+require "json"
+require "nats/client"
+require_relative "./utils"
+
+module RubyNestNats
+  class Client
+    class << self
+      def logger=(some_logger)
+        log("Setting the logger to #{some_logger.inspect}")
+        @logger = some_logger
+      end
+
+      def logger
+        @logger
+      end
+
+      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
+
+      def started?
+        @started ||= false
+      end
+
+      def stopped?
+        !started?
+      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)
+        register_reply!(subject: subject.to_s, handler: block, queue: queue.to_s)
+      end
+
+      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
+            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
+          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)
+        NATS.stop rescue nil
+        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
+
+      def current_thread
+        @current_thread
+      end
+
+      def current_thread=(some_thread)
+        @current_thread = some_thread
+      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 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
+
+        self.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)
+
+            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,67 @@
+require_relative "./utils"
+
+module RubyNestNats
+  class Controller
+    NO_QUEUE_GIVEN = :ruby_nest_nats_super_special_no_op_queue_symbol_qwertyuiop_1234567890
+
+    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
+      #
+      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
+
+      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
+
+      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,17 @@
+module RubyNestNats
+  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.3"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby_nest_nats
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
 platform: ruby
 authors:
 - Keegan Leitz
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-05-12 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