natsy 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f5f7c3cffa8ab383960e32e70a795804170393d4d98ffcd6e54b437a4d07a48d
-  data.tar.gz: 6759b66239fc91b067b765013d77be9e25b182c240b1a9d02d5f145c8ed2254b
+  metadata.gz: c6bc9668d49b9d899ccff640de76b89dfdd2063e44d08d8189a1fcce934e2d70
+  data.tar.gz: 3a7b7f59a818778db5a8fd48c5b34d26842a900e8b340a3be1d8541569c671bf
 SHA512:
-  metadata.gz: 564f92f38f7cc36eea88fcad6a32ca464a51f55fe6af72cac63b86dfc54610fa9f55a7281440acb235041c3145bf18390e0206988e499e6983a4f7dab1f85014
-  data.tar.gz: 4f3cb62d940a2622f1787310ea59062124373b862430356f925804632cfc1380b06cda2263fef2fc50ea53a682fd5a52b60a0d012b3833205760d6247ecc16ca
+  metadata.gz: 2c4f742f409308fae258a8c0de19c4072757855073b1ccab1114b5e818bd29c53bdd269aa330942457c2c737ee798f2b1b6606c678055babc815d576fbb9dd78
+  data.tar.gz: 9b879994fe87e9a4430accf0a837a03989cdd50b18388e13877541203f91d47f394af8fd64f43e49a4fd34196dee4ca0e1af2bd9035b2e4061419a419115a123

data/README.md

@@ -58,6 +58,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
@@ -68,23 +119,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.)
@@ -96,13 +148,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>
@@ -155,15 +207,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!
 ```
@@ -174,7 +240,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 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.
 
@@ -231,8 +297,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")
 >
 > # ...
 >

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)
@@ -180,17 +137,7 @@ module Natsy
       end
 
       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}] Natsy | #{indentation}#{line}")
-        end
-
-        nil
+        Utils.log(Config.logger, text, level: level, indent: indent)
       end
 
       def kill!
@@ -241,7 +188,7 @@ module Natsy
         reply = {
           subject: subject,
           handler: handler,
-          queue: Utils.presence(queue) || default_queue,
+          queue: Utils.presence(queue) || Config.default_queue,
         }
 
         replies << reply
@@ -250,7 +197,7 @@ 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)

data/lib/natsy/config.rb

@@ -0,0 +1,261 @@
+# 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)
+      #
+      def logger=(new_logger)
+        @logger = new_logger
+        Utils.log(@logger, "Set the logger to #{@logger.inspect}", level: :debug)
+      end
+
+      # Optional logger for lifecycle events, messages received, etc.
+      #
+      # @see Natsy::Config::Options#logger=
+      #
+      attr_reader :logger
+
+      # 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
+      #
+      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
+
+      # Optional default queue for message subscription and replies.
+      #
+      # @see Natsy::Config::Options#default_queue=
+      #
+      attr_reader :default_queue
+
+      # 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,18 @@ 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 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 +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.1"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: natsy
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Keegan Leitz
@@ -170,6 +170,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 +179,7 @@ homepage: https://github.com/openbay/natsy
 licenses:
 - MIT
 metadata:
-  documentation_uri: https://www.rubydoc.info/gems/natsy/0.3.1
+  documentation_uri: https://www.rubydoc.info/gems/natsy/0.4.0
 post_install_message: 
 rdoc_options: []
 require_paths: