natsy 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a037edf2d9a4b510d45ac57b9a891ccaf5c8b14a82ad359b5ef24974f119342f
+  data.tar.gz: 7351f54131880e05d0ddf5955a8bc48af0635abf53de8fcd13a06f8ef9587e72
+SHA512:
+  metadata.gz: 071a63d868fbd6441c0b33f459c643d0d23f471c63317274dc5ae45ddf896fd69cee84701da5c1cd8ccb86ff1b8cc90e8c9cc9f98ced72508b48879a93e8b572
+  data.tar.gz: 13345e7ab11e6f770310d27d8dbd2cffa64b0e27dd04b63096bce5827562361b261b81f7e762c328f7a01d6d971399cb8f0c39d61efd370d69fc7aee9a3cd031

data/.github/workflows/main.yml

@@ -0,0 +1,44 @@
+name: Test and lint
+
+on:
+  push:
+    branches:
+      - main
+
+  pull_request:
+    branches:
+      - main
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Run RSpec tests and RuboCop lints
+
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        ruby-version:
+          - 2.7
+          - 2.6
+
+    steps:
+      - name: Checkout the repo
+        uses: actions/checkout@v2
+
+      - name: Set up Ruby v${{ matrix.ruby-version }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+          bundler-cache: true
+
+      - name: Install dependencies
+        run: bundle install
+
+      - name: Run RSpec tests
+        run: bundle exec rake spec
+
+      - name: Run RuboCop lints
+        run: bundle exec rubocop

data/.gitignore

@@ -0,0 +1,70 @@
+# generic stuff
+.env
+*.gem
+*.rbc
+log/*.log
+/.config
+/InstalledFiles
+/pkg/
+/tmp/
+
+# testy stuff
+.rspec
+.rspec_status
+*.orig
+/coverage/
+/coverage/
+/db/*.sqlite3
+/db/*.sqlite3-[0-9]*
+/db/*.sqlite3-journal
+/public/system
+/spec/examples.txt
+/spec/reports/
+/spec/tmp
+/test/tmp/
+/test/version_tmp/
+capybara-*.html
+pickle-email-*.html
+rerun.txt
+test/dummy/db/*.sqlite3
+test/dummy/db/*.sqlite3-journal
+test/dummy/log/*.log
+test/dummy/node_modules/
+test/dummy/storage/
+test/dummy/tmp/
+test/dummy/yarn-error.log
+
+# debuggy stuff
+.byebug_history
+
+## doccy stuff
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## bundly stuff
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# "for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments"
+Gemfile.lock
+.ruby-version
+.ruby-gemset
+
+# rvmmy stuff
+.rvmrc
+
+# editory stuff
+.idea
+.vscode
+*.rdb
+
+# systemy stuff
+*.swm
+*.swn
+*.swo
+*.swp
+*.DS_Store

data/.rubocop.yml

@@ -0,0 +1,103 @@
+require:
+  - rubocop-performance
+  - rubocop-rspec
+  - rubocop-rake
+
+# Globals
+
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 2.6
+
+# Layout
+
+Layout/LineLength:
+  Max: 120
+  Exclude:
+    - 'spec/**/*_spec.rb'
+    - '*.gemspec'
+
+Layout/EndAlignment:
+  EnforcedStyleAlignWith: variable
+
+Layout/FirstArrayElementIndentation:
+  EnforcedStyle: consistent
+
+# Metrics
+
+Metrics/AbcSize:
+  Max: 30
+  CountRepeatedAttributes: false
+  Exclude:
+    - 'spec/**/*_spec.rb'
+    - '*.gemspec'
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*_spec.rb'
+    - '*.gemspec'
+
+Metrics/ClassLength:
+  Max: 150
+  CountComments: false
+  CountAsOne:
+    - array
+    - hash
+    - heredoc
+  Exclude:
+    - 'spec/**/*_spec.rb'
+    - '*.gemspec'
+
+Metrics/MethodLength:
+  Max: 20
+  CountComments: false
+  CountAsOne:
+    - array
+    - hash
+    - heredoc
+
+Metrics/ModuleLength:
+  Max: 150
+  CountComments: false
+  CountAsOne:
+    - array
+    - hash
+    - heredoc
+  Exclude:
+    - 'spec/**/*_spec.rb'
+    - '*.gemspec'
+
+# Rspec
+
+RSpec/ExampleLength:
+  Max: 25
+
+RSpec/MessageSpies:
+  Enabled: false
+
+RSpec/MultipleExpectations:
+  Enabled: false
+
+RSpec/NestedGroups:
+  Max: 10
+
+# Style
+
+Style/DoubleNegation:
+  Enabled: false
+
+Style/ExpandPathArguments:
+  Exclude:
+    - 'adornable.gemspec'
+
+Style/StringLiterals:
+  Enabled: false
+
+Style/TrailingCommaInArguments:
+  EnforcedStyleForMultiline: consistent_comma
+
+Style/TrailingCommaInArrayLiteral:
+  EnforcedStyleForMultiline: consistent_comma
+
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: consistent_comma

data/CHANGELOG.md

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

data/Gemfile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in natsy.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Keegan Leitz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,319 @@
+# Natsy
+
+The `natsy` gem allows you to listen for (and reply to) NATS messages asynchronously in a Ruby application.
+
+## 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
+
+### Locally (to your application)
+
+Add the gem to your application's `Gemfile`:
+
+```ruby
+gem 'natsy'
+```
+
+...and then run:
+
+```bash
+bundle install
+```
+
+### Globally (to your system)
+
+Alternatively, install it globally:
+
+```bash
+gem install natsy
+```
+
+### 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
+
+### 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 `natsy` write out logs for messages received, responses sent, errors raised, lifecycle events, etc.
+
+```ruby
+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:
+
+```ruby
+Natsy::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
+Natsy::Client.default_queue = "foobar"
+```
+
+Leave the `::default_queue` blank (or assign `nil`) to use no default queue.
+
+```ruby
+Natsy::Client.default_queue = nil
+```
+
+<a id="reply-to-section"></a>
+
+### Registering message handlers
+
+Register a message handler with the `Natsy::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
+Natsy::Client.reply_to("some.subject", queue: "foobar") { |data| "Got it! #{data.inspect}" }
+
+Natsy::Client.reply_to("some.*.pattern") { |data, subject| "Got #{data} on #{subject}" }
+
+Natsy::Client.reply_to("other.subject") do |data|
+  if data["foo"] == "bar"
+    { is_bar: "Yep!" }
+  else
+    { is_bar: "No way!" }
+  end
+end
+
+Natsy::Client.reply_to("subject.in.queue", queue: "barbaz") do
+  "My turn!"
+end
+```
+
+### Starting the listeners
+
+Start listening for messages with the `Natsy::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
+Natsy::Client.start!
+```
+
+> **NOTE:** If an error is raised in one of the handlers, `Natsy::Client` will restart automatically.
+
+> **NOTE:** You _can_ invoke `::reply_to` to create additional message subscriptions after `Natsy::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 `Natsy::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 `natsy` 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 'natsy'
+require 'logger'
+
+nats_logger = Logger.new(STDOUT)
+nats_logger.level = Logger::DEBUG
+
+Natsy::Client.logger = nats_logger
+Natsy::Client.default_queue = "foobar"
+
+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.start!
+```
+
+<a id="controller-section"></a>
+
+### Creating "controller"-style classes for listener organization
+
+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 `::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 `Natsy::Client::reply_to`](#reply-to-section)). The result of that block will be sent as a response to the message received.
+
+```ruby
+class HelloController < Natsy::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, `natsy` 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
+> Natsy::Client.logger = Rails.logger
+> Natsy::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) }
+>
+>   Natsy::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 `Natsy::VERSION` value in `lib/natsy/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/natsy).
+
+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/Openbay/natsy.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "natsy"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/natsy.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "nats/client"
+require_relative "natsy/version"
+require_relative "natsy/utils"
+require_relative "natsy/client"
+require_relative "natsy/controller"
+
+# The +Natsy+ module provides the top-level namespace for the NATS client
+# and controller machinery.
+module Natsy
+  # Basic error
+  class Error < StandardError; end
+
+  # New subscription has been added at runtime
+  class NewSubscriptionsError < Natsy::Error; end
+end

data/lib/natsy/client.rb

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+
+require "json"
+require "nats/client"
+require_relative "./utils"
+
+module Natsy
+  # The +Natsy::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
+      # 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.
+      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 +Natsy::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
+      #   Natsy::Client.reply_to("some.subject", queue: "foobar") { |data| "Got it! #{data.inspect}" }
+      #
+      #   Natsy::Client.reply_to("some.*.pattern") { |data, subject| "Got #{data} on #{subject}" }
+      #
+      #   Natsy::Client.reply_to("other.subject") do |data|
+      #     if data["foo"] == "bar"
+      #       { is_bar: "Yep!" }
+      #     else
+      #       { is_bar: "No way!" }
+      #     end
+      #   end
+      #
+      #   Natsy::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 +Natsy::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
+      #   Natsy::Client.start!
+      #
+      # **NOTE:** If an error is raised in one of the handlers,
+      # +Natsy::Client+ will restart automatically.
+      #
+      # **NOTE:** You _can_ invoke +::reply_to+ to create additional message
+      # subscriptions after +Natsy::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 +Natsy::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
+
+      attr_accessor :current_thread
+
+      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
+      end
+
+      def kill!
+        current_thread.kill if current_thread && current_thread.alive?
+      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
+
+      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/natsy/controller.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require_relative "./utils"
+
+module Natsy
+  # Create controller classes which inherit from +Natsy::Controller+ in
+  # order to give your message listeners some structure.
+  class Controller
+    NO_QUEUE_GIVEN = :natsy_super_special_no_op_queue_symbol_qwertyuiop1234567890
+    private_constant :NO_QUEUE_GIVEN
+
+    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 +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.
+      #
+      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=+).
+        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 +Natsy::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/natsy/utils.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Natsy
+  # Some internal utility methods
+  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/natsy/version.rb

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

data/natsy.gemspec

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "lib/natsy/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "natsy"
+  spec.version = Natsy::VERSION
+  spec.authors = ["Keegan Leitz"]
+  spec.email = ["keegan@openbay.com"]
+
+  spec.summary = "Listen for (and reply to) NATS messages asynchronously in a Ruby application"
+  spec.description = "Listen for (and reply to) NATS messages asynchronously in a Ruby application"
+  spec.homepage = "https://github.com/openbay/natsy"
+  spec.license = "MIT"
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.6")
+
+  rubydoc_url = "https://www.rubydoc.info/gems/natsy/#{Natsy::VERSION}"
+  spec.metadata["documentation_uri"] = rubydoc_url
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 2.2"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "rubocop", "~> 1.10"
+  spec.add_development_dependency "rubocop-performance", "~> 1.9"
+  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

@@ -0,0 +1,201 @@
+--- !ruby/object:Gem::Specification
+name: natsy
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- Keegan Leitz
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2021-05-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: rubocop-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.9'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+- !ruby/object:Gem::Dependency
+  name: solargraph
+  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: 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
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+description: Listen for (and reply to) NATS messages asynchronously in a Ruby application
+email:
+- keegan@openbay.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/main.yml"
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/natsy.rb
+- lib/natsy/client.rb
+- lib/natsy/controller.rb
+- lib/natsy/utils.rb
+- lib/natsy/version.rb
+- natsy.gemspec
+homepage: https://github.com/openbay/natsy
+licenses:
+- MIT
+metadata:
+  documentation_uri: https://www.rubydoc.info/gems/natsy/0.3.0
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.9
+signing_key: 
+specification_version: 4
+summary: Listen for (and reply to) NATS messages asynchronously in a Ruby application
+test_files: []