natsy 0.3.0 → 0.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a037edf2d9a4b510d45ac57b9a891ccaf5c8b14a82ad359b5ef24974f119342f
-  data.tar.gz: 7351f54131880e05d0ddf5955a8bc48af0635abf53de8fcd13a06f8ef9587e72
+  metadata.gz: e8c3433d746ea11eacc51f7e602ab6a0d0816a69c5ef7db7e802847cf5b931fd
+  data.tar.gz: 79dc340ffefbe6371558fa1cd901977e55215f8cbda71024fcd930dda94eab2c
 SHA512:
-  metadata.gz: 071a63d868fbd6441c0b33f459c643d0d23f471c63317274dc5ae45ddf896fd69cee84701da5c1cd8ccb86ff1b8cc90e8c9cc9f98ced72508b48879a93e8b572
-  data.tar.gz: 13345e7ab11e6f770310d27d8dbd2cffa64b0e27dd04b63096bce5827562361b261b81f7e762c328f7a01d6d971399cb8f0c39d61efd370d69fc7aee9a3cd031
+  metadata.gz: e7c12f04962acfb2e36bfd1ad580da552678dd26a6c5c51b7b373ef69f816a2018bc72a1c2ad2278b394f0e9e7d18f3d942dd46883a01630b1e30384e21fcc9a
+  data.tar.gz: af46e5498949a3806972d9a5a26fdadfc275e3d8914338c634a3cc01ab33c45b26fb48849103ec8a786903d580685912b418df099ace08f9aa5fbdcc9b05dfbb

data/.github/workflows/main.yml

@@ -18,6 +18,14 @@ jobs:
 
     runs-on: ubuntu-latest
 
+    services:
+      nats:
+        image: nats:latest
+        ports:
+          - 4222:4222
+          - 8222:8222
+          - 6222:6222
+
     strategy:
       matrix:
         ruby-version:

data/.rubocop.yml

@@ -26,13 +26,20 @@ Layout/FirstArrayElementIndentation:
 # Metrics
 
 Metrics/AbcSize:
-  Max: 30
+  Max: 35
   CountRepeatedAttributes: false
   Exclude:
     - 'spec/**/*_spec.rb'
     - '*.gemspec'
 
 Metrics/BlockLength:
+  Max: 50
+  Exclude:
+    - 'spec/**/*_spec.rb'
+    - '*.gemspec'
+
+Metrics/CyclomaticComplexity:
+  Max: 15
   Exclude:
     - 'spec/**/*_spec.rb'
     - '*.gemspec'
@@ -55,6 +62,9 @@ Metrics/MethodLength:
     - array
     - hash
     - heredoc
+  Exclude:
+    - 'spec/**/*_spec.rb'
+    - '*.gemspec'
 
 Metrics/ModuleLength:
   Max: 150
@@ -67,6 +77,12 @@ Metrics/ModuleLength:
     - 'spec/**/*_spec.rb'
     - '*.gemspec'
 
+Metrics/PerceivedComplexity:
+  Max: 20
+  Exclude:
+    - 'spec/**/*_spec.rb'
+    - '*.gemspec'
+
 # Rspec
 
 RSpec/ExampleLength:

data/README.md

@@ -5,14 +5,15 @@ The `natsy` gem allows you to listen for (and reply to) NATS messages asynchrono
 ## TODO
 
 - [x] docs
-- [ ] tests
+- [x] 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.
+- [x] 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
+- [ ] `on_error` handler so you can send a response (what's standard?)
+- [ ] support lifecycle callbacks (like `on_connect`, `on_disconnect`, etc.) provided by the `nats` gem
+- [ ] ability to _request_ (not just reply)
 
 ## Installation
 
@@ -44,6 +45,8 @@ This gem also requires a NATS server to be installed and running before use. See
 
 ## Usage
 
+<a id="starting-the-nats-server-section">
+
 ### 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:
@@ -56,6 +59,57 @@ docker run -p 4222:4222 -p 8222:8222 -p 6222:6222 -ti nats:latest
 
 > **NOTE:** For other methods of running a NATS server, see [the NATS documentation](https://docs.nats.io/nats-server/installation).
 
+### Configuration
+
+Use `Natsy::Config::set` to set configuration options. These options can either be set via a `Hash`/keyword arguments passed to the `::set` method, or set by invoking the method with a block and assigning your options to the yielded `Natsy::Config::Options` instance.
+
+This README will use the following two syntaxes interchangably; remember that they do **exactly the same thing:**
+
+```ruby
+Natsy::Config.set(
+  urls: ["nats://foo.bar:4567", "nats://foo.bar:5678"],
+  default_queue: "foobar",
+  logger: Rails.logger,
+)
+```
+
+```ruby
+Natsy::Config.set do |options|
+  options.urls = ["nats://foo.bar:4567", "nats://foo.bar:5678"]
+  options.default_queue = "foobar"
+  options.logger = Rails.logger
+end
+```
+
+The following options are available:
+
+- `url`: A single URL string (including protocol, domain, and port) which points to the relevant NATS server (see [here](#setting-nats-server-url-section) for more info)
+- `urls`: An array of URL strings in case you need to listen to multiple NATS servers (see [here](#setting-nats-server-url-section) for more info)
+- `logger`: A logger where `natsy` can write helpful information (see [here](#logging-section) for more info)
+- `default_queue`: The default queue that your application should fall back to if none is given in a more specific context (see [here](#default-queue-section) for more info)
+
+<a id="setting-nats-server-url-section"></a>
+
+### Setting the NATS server URL(s)
+
+Set the URL/URLs at which your NATS server mediates messages.
+
+```ruby
+Natsy::Config.set do |options|
+  options.url = "nats://foo.bar:4567"
+end
+```
+
+```ruby
+Natsy::Config.set do |options|
+  options.urls = ["nats://foo.bar:4567", "nats://foo.bar:5678"]
+end
+```
+
+> **NOTE:** If no `url`/`urls` option is specified, `natsy` will fall back on the default NATS server URL, which is `nats://localhost:4222`.
+
+<a id="logging-section"></a>
+
 ### Logging
 
 #### Attaching a logger
@@ -66,23 +120,24 @@ Attach a logger to have `natsy` write out logs for messages received, responses
 require 'natsy'
 require 'logger'
 
-nats_logger = Logger.new(STDOUT)
-nats_logger.level = Logger::INFO
-
-Natsy::Client.logger = nats_logger
+Natsy::Config.set do |options|
+  nats_logger = Logger.new(STDOUT)
+  nats_logger.level = Logger::INFO
+  options.logger = nats_logger
+end
 ```
 
 In a Rails application, you might do this instead:
 
 ```ruby
-Natsy::Client.logger = Rails.logger
+Natsy::Config.set(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`
+- `DEBUG`: Lifecycle events (starting NATS listeners, stopping NATS, reply registration, 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.)
@@ -94,13 +149,13 @@ The following will be logged at the specified log levels
 Set a default queue for subscriptions.
 
 ```ruby
-Natsy::Client.default_queue = "foobar"
+Natsy::Config.set(default_queue: "foobar")
 ```
 
-Leave the `::default_queue` blank (or assign `nil`) to use no default queue.
+Leave the `default_queue` blank (or assign `nil`) to use no default queue.
 
 ```ruby
-Natsy::Client.default_queue = nil
+Natsy::Config.set(default_queue: nil)
 ```
 
 <a id="reply-to-section"></a>
@@ -153,15 +208,29 @@ The following should be enough to start a `natsy` setup in your Ruby application
 require 'natsy'
 require 'logger'
 
-nats_logger = Logger.new(STDOUT)
-nats_logger.level = Logger::DEBUG
+Natsy::Config.set do |options|
+  nats_logger = Logger.new(STDOUT)
+  nats_logger.level = Logger::DEBUG
 
-Natsy::Client.logger = nats_logger
-Natsy::Client.default_queue = "foobar"
+  options.logger = nats_logger
+  options.urls = ["nats://foo.bar:4567", "nats://foo.bar:5678"]
+  options.default_queue = "foobar"
+end
 
-Natsy::Client.reply_to("some.subject") { |data| "Got it! #{data.inspect}" }
-Natsy::Client.reply_to("some.*.pattern") { |data, subject| "Got #{data} on #{subject}" }
-Natsy::Client.reply_to("subject.in.queue", queue: "barbaz") { { msg: "My turn!", turn: 5 } }
+Natsy::Client.reply_to("some.subject") do |data|
+  "Got it! #{data.inspect}"
+end
+
+Natsy::Client.reply_to("some.*.pattern") do |data, subject|
+  "Got #{data} on #{subject}"
+end
+
+Natsy::Client.reply_to("subject.in.queue", queue: "barbaz") do
+  {
+    msg: "My turn!",
+    turn: 5,
+  }
+end
 
 Natsy::Client.start!
 ```
@@ -172,7 +241,7 @@ Natsy::Client.start!
 
 Create controller classes which inherit from `Natsy::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 `Natsy::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 `::default_queue` macro to set a default queue string. If omitted, the controller will fall back on the global default queue assigned to `Natsy::Config::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 fall back to the global default queue.
 
 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.
 
@@ -208,9 +277,13 @@ class HelloController < Natsy::Controller
   end
 
   subject "hows" do
-    subject "*" do
+    # The queue at this point is "foobar"
+    subject "*", queue: "barbaz" do # Override the default queue at any point
+      # The queue at this point is "barbaz" (!)
       subject "doing" do
-        response do |data, subject|
+        # The queue at this point is "barbaz"
+        response queue: "bazbam" do |data, subject|
+          # The queue at this point is "bazbam" (!)
           # 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"]
@@ -229,8 +302,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`):
 >
 > ```ruby
-> Natsy::Client.logger = Rails.logger
-> Natsy::Client.default_queue = "foobar"
+> Natsy::Config.set(logger: Rails.logger, default_queue: "foobar")
 >
 > # ...
 >
@@ -267,7 +339,7 @@ bin/console
 
 ### Run the tests
 
-To run the RSpec test suites, run:
+To run the RSpec test suites, first [start the NATS server](#starting-the-nats-server-section). Then, run the tests:
 
 ```bash
 bundle exec rake spec
@@ -285,6 +357,12 @@ rake spec
 bundle exec rubocop
 ```
 
+...or (if your Ruby setup has good defaults) just this:
+
+```bash
+rubocop
+```
+
 ### Create a release
 
 Bump the `Natsy::VERSION` value in `lib/natsy/version.rb`, commit, and then run:

data/lib/natsy.rb

@@ -3,6 +3,7 @@
 require "nats/client"
 require_relative "natsy/version"
 require_relative "natsy/utils"
+require_relative "natsy/config"
 require_relative "natsy/client"
 require_relative "natsy/controller"
 
@@ -14,4 +15,7 @@ module Natsy
 
   # New subscription has been added at runtime
   class NewSubscriptionsError < Natsy::Error; end
+
+  # Invalid options have been provided to +Natsy::Config+
+  class InvalidConfigError < Natsy::Error; end
 end

data/lib/natsy/client.rb

@@ -10,50 +10,6 @@ module Natsy
   # most functionality if desired.
   class Client
     class << self
-      # Optional logger for lifecycle events, messages received, etc.
-      attr_reader :logger
-
-      # Optional default queue for message subscription and replies.
-      attr_reader :default_queue
-
-      # Attach a logger to have +natsy+ write out logs for messages
-      # received, responses sent, errors raised, lifecycle events, etc.
-      #
-      # @example
-      #   require 'natsy'
-      #   require 'logger'
-      #
-      #   nats_logger = Logger.new(STDOUT)
-      #   nats_logger.level = Logger::INFO
-      #
-      #   Natsy::Client.logger = nats_logger
-      #
-      # In a Rails application, you might do this instead:
-      #
-      # @example
-      #   Natsy::Client.logger = Rails.logger
-      #
-      def logger=(some_logger)
-        @logger = some_logger
-        log("Set the logger to #{@logger.inspect}")
-      end
-
-      # Set a default queue for subscriptions.
-      #
-      # @example
-      #   Natsy::Client.default_queue = "foobar"
-      #
-      # Leave the +::default_queue+ blank (or assign +nil+) to use no default
-      # queue.
-      #
-      # @example
-      #   Natsy::Client.default_queue = nil
-      #
-      def default_queue=(some_queue)
-        @default_queue = Utils.presence(some_queue.to_s)
-        log("Setting the default queue to #{@default_queue || '(none)'}", level: :debug)
-      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.
@@ -72,8 +28,9 @@ module Natsy
       # 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:+ option, it will be set to the value of
+      # +Natsy::Config::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
@@ -101,7 +58,7 @@ module Natsy
       #   end
       #
       def reply_to(subject, queue: nil, &block)
-        queue = Utils.presence(queue) || default_queue
+        queue = Utils.presence(queue) || Config.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)
@@ -145,44 +102,54 @@ module Natsy
 
         started!
 
-        self.current_thread = Thread.new do
+        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
+          rescue NewSubscriptionsError => _e
             log("New subscriptions! Restarting...", level: :info)
             restart!
-            raise e # TODO: there has to be a better way
+            Thread.current.exit
+            # 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
+            Thread.current.exit
+            # raise e
           end
         end
+
+        threads << thread
       end
 
-      private
+      # **USE WITH CAUTION:** This method (+::reset!+) clears all subscriptions,
+      # stops listening (if started), and kills any active threads.
+      def reset!
+        replies.clear
+        stop!
+        kill!
+      end
 
-      attr_accessor :current_thread
+      private
 
-      def log(text, level: :info, indent: 0)
-        return unless logger
+      def threads
+        @threads ||= []
+      end
 
-        timestamp = Time.now.to_s
-        text_lines = text.split("\n")
-        indentation = indent.is_a?(String) ? indent : (" " * indent)
+      def current_thread
+        threads.last
+      end
 
-        text_lines.each do |line|
-          logger.send(level, "[#{timestamp}] Natsy | #{indentation}#{line}")
-        end
+      def log(text, level: :info, indent: 0)
+        Utils.log(Config.logger, text, level: level, indent: indent)
       end
 
       def kill!
-        current_thread.kill if current_thread && current_thread.alive?
+        threads.each { |thread| thread.kill if thread.alive? }
       end
 
       def stop!
@@ -200,6 +167,7 @@ module Natsy
       def restart!
         log("Restarting NATS", level: :warn)
         stop!
+        kill!
         start!
       end
 
@@ -228,7 +196,7 @@ module Natsy
         reply = {
           subject: subject,
           handler: handler,
-          queue: Utils.presence(queue) || default_queue,
+          queue: Utils.presence(queue) || Config.default_queue,
         }
 
         replies << reply
@@ -237,30 +205,43 @@ module Natsy
       end
 
       def listen
-        NATS.start do
+        NATS.start(servers: Natsy::Config.urls) 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")
+            NATS.subscribe(replier[:subject], queue: replier[:queue]) do |message, reply_subject, subject|
+              parsed_message = begin
+                JSON.parse(message)
+              rescue StandardError
+                message
+              end
+
+              id, data, pattern = if parsed_message.is_a?(Hash)
+                parsed_message.values_at("id", "data", "pattern")
+              else
+                [nil, parsed_message, nil]
+              end
+
+              message_data = id && data && pattern ? data : parsed_message
 
               log("Received a message!")
               message_desc = <<~LOG_MESSAGE
                 id:      #{id || '(none)'}
                 pattern: #{pattern || '(none)'}
                 subject: #{subject || '(none)'}
-                data:    #{data.to_json}
-                inbox:   #{inbox || '(none)'}
+                data:    #{message_data.to_json}
+                inbox:   #{reply_subject || '(none)'}
+                queue:   #{replier[:queue] || '(none)'}
+                message: #{message}
               LOG_MESSAGE
               log(message_desc, indent: 2)
 
-              response_data = replier[:handler].call(data)
+              raw_response = replier[:handler].call(message_data, subject)
 
-              log("Responding with '#{response_data}'")
+              log("Responding with '#{raw_response}'")
 
-              NATS.publish(inbox, response_data.to_json, queue: replier[:queue])
+              NATS.publish(reply_subject, raw_response.to_json) if Utils.present?(reply_subject)
             end
           end
         end

data/lib/natsy/config.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+require "ostruct"
+require_relative "./utils"
+
+module Natsy
+  # Represents the configuration options for +Natsy+. Configuration options are
+  # set using the `Natsy::Config::set` method, either as arguments or by using
+  # the appropriate setters on the object passed to the block.
+  class Config
+    # A +Natsy::Config::Options+ object is passed as a single argument to the
+    # block (if provided) for the +Natsy::Config::set+ method. This class should
+    # probably *NOT* be instantiated directly; instead, set the relevant options
+    # using +Natsy::Config.set(some_option: "...", some_other_option: "...")+.
+    # If you find yourself instantiating this class directly, there's probably a
+    # better way to do what you're trying to do.
+    class Options
+      # Specify a NATS server URL (or multiple URLs)
+      #
+      # **NOTE:** The following two examples do exactly the same thing.
+      #
+      # @example
+      #   Natsy::Config.set(url: "nats://foo.bar:4567"))
+      #
+      # @example
+      #   Natsy::Config.set do |options|
+      #     options.url = "nats://foo.bar:4567"
+      #   end
+      #
+      # **NOTE:** The following two examples do exactly the same thing.
+      #
+      # @example
+      #   Natsy::Config.set(urls: ["nats://foo.bar:4567", "nats://foo.bar:5678"])
+      #
+      # @example
+      #   Natsy::Config.set do |options|
+      #     options.urls = ["nats://foo.bar:4567", "nats://foo.bar:5678"]
+      #   end
+      #
+      # If left blank/omitted, +natsy+ will fall back on the default URL, which
+      # is +nats://localhost:4222+.
+      #
+      attr_accessor :url, :urls
+
+      # Attach a logger to have +natsy+ write out logs for messages
+      # received, responses sent, errors raised, lifecycle events, etc.
+      #
+      # **NOTE:** The following two examples do exactly the same thing.
+      #
+      # @example
+      #   require 'natsy'
+      #   require 'logger'
+      #
+      #   nats_logger = Logger.new(STDOUT)
+      #   nats_logger.level = Logger::INFO
+      #
+      #   Natsy::Config.set(logger: nats_logger)
+      #
+      # @example
+      #   require 'natsy'
+      #   require 'logger'
+      #
+      #   Natsy::Config.set do |options|
+      #     nats_logger = Logger.new(STDOUT)
+      #     nats_logger.level = Logger::INFO
+      #
+      #     options.logger = nats_logger
+      #   end
+      #
+      #
+      # In a Rails application, you might do this instead:
+      #
+      # @example
+      #   Natsy::Config.set(logger: Rails.logger)
+      #
+      attr_reader :logger
+
+      # {include:Natsy::Config::Options#logger}
+      def logger=(new_logger)
+        @logger = new_logger
+        Utils.log(@logger, "Set the logger to #{@logger.inspect}", level: :debug)
+      end
+
+      # Set a default queue for subscriptions.
+      #
+      # **NOTE:** The following two examples do exactly the same thing.
+      #
+      # @example
+      #   Natsy::Config.set(default_queue: "foobar")
+      #
+      # @example
+      #   Natsy::Config.set do |options|
+      #     options.default_queue = "foobar"
+      #   end
+      #
+      # Leave the +::default_queue+ blank (or assign +nil+) to use no default
+      # queue.
+      #
+      # **NOTE:** The following two examples do exactly the same thing.
+      #
+      # @example
+      #   Natsy::Config.set(default_queue: nil)
+      #
+      # @example
+      #   Natsy::Config.set do |options|
+      #     options.default_queue = nil
+      #   end
+      #
+      attr_reader :default_queue
+
+      # {include:Natsy::Config::Options#default_queue}
+      def default_queue=(new_queue)
+        @default_queue = Utils.presence(new_queue.to_s)
+        Utils.log(logger, "Setting the default queue to #{@default_queue || '(none)'}", level: :debug)
+      end
+
+      # Returns ONLY the config options THAT HAVE BEEN SET as a +Hash+. Will not
+      # have keys for properties that are unassigned, but will have keys for
+      # properties assigned +nil+.
+      def to_h
+        hash = {}
+        hash[:url] = url if defined?(@url)
+        hash[:urls] = urls if defined?(@urls)
+        hash[:logger] = logger if defined?(@logger)
+        hash[:default_queue] = default_queue if defined?(@default_queue)
+        hash
+      end
+    end
+
+    # Valid option keys that can be given to +Natsy::Config::set+, either in a
+    # +Hash+ passed to the method, keyword arguments passed to the method, or by
+    # using setters on the +Natsy::Config::Options+ object passed to the block.
+    VALID_OPTIONS = %i[
+      url
+      urls
+      logger
+      default_queue
+    ].freeze
+
+    # The default NATS server URL (used if none is configured)
+    DEFAULT_URL = "nats://localhost:4222"
+
+    class << self
+      # Specify configuration options, either by providing them as keyword
+      # arguments or by using a block. Should you choose to set options using
+      # a block, it will be passed a single argument (an instance of
+      # +Natsy::Config::Options+). You can set any options on the instance that
+      # you see fit.
+      #
+      # **NOTE:** The following two examples do exactly the same thing.
+      #
+      # @example
+      #   Natsy::Config.set(
+      #     urls: ["nats://foo.bar:4567", "nats://foo.bar:5678"],
+      #     default_queue: "foobar",
+      #     logger: Rails.logger,
+      #   )
+      #
+      # @example
+      #   Natsy::Config.set do |options|
+      #     options.urls = ["nats://foo.bar:4567", "nats://foo.bar:5678"]
+      #     options.default_queue = "foobar"
+      #     options.logger = Rails.logger
+      #   end
+      #
+      def set(keyword_options = {})
+        new_hash_options = (keyword_options || {}).transform_keys(&:to_sym)
+
+        invalid_config = lambda do |detail, keys|
+          raise InvalidConfigError, "Invalid options provided #{detail}: #{keys.join(', ')}"
+        end
+
+        invalid_keys = invalid_option_keys(new_hash_options)
+        invalid_config.call("as arguments", invalid_keys) if invalid_keys.any?
+
+        # Want to take advantage of the setters on +Natsy::Config::Options+...
+        new_hash_options_object = new_hash_options.each_with_object(Options.new) do |(key, value), options|
+          options.send(:"#{key}=", value)
+        end
+
+        given_options.merge!(new_hash_options_object.to_h)
+
+        new_block_options_object = Options.new
+        yield(new_block_options_object) if block_given?
+
+        invalid_keys = invalid_option_keys(new_block_options_object)
+        invalid_config.call("in block", invalid_keys) if invalid_keys.any?
+
+        given_options.merge!(new_block_options_object.to_h)
+      end
+
+      # The NATS server URLs that +natsy+ should listen on.
+      #
+      # See also: {Natsy::Config::Options#urls=}
+      #
+      def urls
+        given_url_list = [given_options[:url]].flatten
+        given_urls_list = [given_options[:urls]].flatten
+        all_given_urls = [*given_url_list, *given_urls_list].compact.uniq
+        Utils.presence(all_given_urls) || [DEFAULT_URL]
+      end
+
+      # The logger that +natsy+ should use to write out logs for messages
+      # received, responses sent, errors raised, lifecycle events, etc.
+      #
+      # See also: {Natsy::Config::Options#logger=}
+      #
+      def logger
+        Utils.presence(given_options[:logger])
+      end
+
+      # The default queue that +natsy+ should use for subscriptions.
+      #
+      # See also: {Natsy::Config::Options#default_queue=}
+      #
+      def default_queue
+        Utils.presence(given_options[:default_queue])
+      end
+
+      # Returns all config options as a +Hash+.
+      def to_h
+        {
+          urls: urls,
+          logger: logger,
+          default_queue: default_queue,
+        }
+      end
+
+      # Alias for {Natsy::Config::to_h}.
+      def as_json(*_args)
+        to_h
+      end
+
+      # Serialize the configuration into a JSON object string.
+      def to_json(*_args)
+        to_h.to_json
+      end
+
+      # Reset the configuration to default values.
+      def reset!
+        @given_options = nil
+      end
+
+      private
+
+      def given_options
+        @given_options ||= {}
+      end
+
+      def invalid_option_keys(options)
+        options.to_h.keys - VALID_OPTIONS
+      end
+    end
+  end
+end

data/lib/natsy/controller.rb

@@ -25,18 +25,17 @@ module Natsy
       #   end
       #
       # If omitted, the controller will fall back on the global default queue
-      # assigned with +Natsy::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.
+      # assigned with +Natsy::Config::set+. 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 fall back to the global
+      # default queue.
       #
       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 +Natsy::Client::default_queue=+).
+        # default set with +Natsy::Client::set+).
         if some_queue == NO_QUEUE_GIVEN
-          @default_queue || Client.default_queue
+          @default_queue || Config.default_queue
         else
           @default_queue = Utils.presence(some_queue.to_s)
         end

data/lib/natsy/utils.rb

@@ -15,6 +15,20 @@ module Natsy
       def presence(value)
         present?(value) ? value : nil
       end
+
+      def log(logger, 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}] Natsy | #{indentation}#{line}")
+        end
+
+        nil
+      end
     end
   end
 end

data/lib/natsy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Natsy
-  VERSION = "0.3.0"
+  VERSION = "0.4.3"
 end

data/natsy.gemspec

@@ -28,6 +28,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_development_dependency "bundler", "~> 2.2"
+  spec.add_development_dependency "pry"
   spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency "rubocop", "~> 1.10"
@@ -35,7 +36,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rubocop-rake", "~> 0.5"
   spec.add_development_dependency "rubocop-rspec", "~> 2.2"
   spec.add_development_dependency "solargraph"
-  spec.add_development_dependency "pry"
 
   spec.add_runtime_dependency "nats", "~> 0.11"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: natsy
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.3
 platform: ruby
 authors:
 - Keegan Leitz
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-05-17 00:00:00.000000000 Z
+date: 2021-05-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.2'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -122,20 +136,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: pry
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 - !ruby/object:Gem::Dependency
   name: nats
   requirement: !ruby/object:Gem::Requirement
@@ -161,7 +161,6 @@ files:
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
-- CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -170,6 +169,7 @@ files:
 - bin/setup
 - lib/natsy.rb
 - lib/natsy/client.rb
+- lib/natsy/config.rb
 - lib/natsy/controller.rb
 - lib/natsy/utils.rb
 - lib/natsy/version.rb
@@ -178,7 +178,7 @@ homepage: https://github.com/openbay/natsy
 licenses:
 - MIT
 metadata:
-  documentation_uri: https://www.rubydoc.info/gems/natsy/0.3.0
+  documentation_uri: https://www.rubydoc.info/gems/natsy/0.4.3
 post_install_message: 
 rdoc_options: []
 require_paths:

data/CHANGELOG.md

@@ -1,5 +0,0 @@
-## [Unreleased]
-
-## [0.1.0] - 2021-05-10
-
-- Initial release