polyn 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30b50a04cee7e5a540b48d8d80276ca87e8c3b247b70da41a9e00c6950a8c4d3
-  data.tar.gz: '09c36399cec8f4e51188489d21aab4a49a41a8d420b273f4f5a9181b7c572b2d'
+  metadata.gz: 10ceff0b77d79960f425d6d7d6d1502095ed2b04533e9bd9fa5d37756f510e18
+  data.tar.gz: db2a410f4aa57312f72b7882c537a15d055fac0611f7eb7f2b31b3d5bf38a27e
 SHA512:
-  metadata.gz: d631676305632f5379e6db7a8286b09b56b9764c118f2c957a06e13ea3bad8158365e164ec1e5a7f982d6578b7a32881fb972a5b4021c9422fb3a811f41031aa
-  data.tar.gz: 6dde4a3a64edeaf92e06dc7f3a47c54d84f55309156fad1499ea8189639d9c0c6d72c6d14b8cc40b6cd2bef76b29d3fbfe43a889a42906cbca0d7ff1fe8210ad
+  metadata.gz: e3b6c51512bcd60cf9276b69d5559f23d057625583832e74c40d271dc5cadbea82891bc41a053eb2d2695bcd374c65e2fe65f30e032acd8974cac0b62b9440d0
+  data.tar.gz: 879c217506428483c0842f306dac110b94da2188cbb57cf7c68bfaba6c5db11dd9a9f1fce86bc50f95d527fc613a6366ef0ff1d51268a1d30aceb83f9a23d050

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    polyn (0.1.0)
+    polyn (0.2.0)
       json_schemer (~> 0.2)
       nats-pure (~> 2.0)
       yard (~> 0.9)
@@ -62,7 +62,9 @@ GEM
     timecop (0.9.4)
     unicode-display_width (2.1.0)
     uri_template (0.7.0)
-    yard (0.9.26)
+    webrick (1.7.0)
+    yard (0.9.28)
+      webrick (~> 1.7.0)
 
 PLATFORMS
   arm64-darwin-20

data/README.md

@@ -66,22 +66,25 @@ require "nats/client"
 require "polyn"
 
 nats = NATS.connect
+polyn = Polyn.connect(nats)
 
-Polyn.publish(nats, "user.created.v1", { name: "Mary" })
+polyn.publish("user.created.v1", { name: "Mary" })
 ```
 
 Add `:source` to make the `source` of the event more specific
 
 
 ```ruby
-Polyn.publish(nats, "user.created.v1", { name: "Mary" }, source: "new.users")
+polyn.publish("user.created.v1", { name: "Mary" }, source: "new.users")
 ```
 
 Add `:triggered_by` to add a triggering event to the `polyntrace`
 
 ```ruby
+polyn = Polyn.connect(nats)
+
 event = Polyn::Event.new
-Polyn.publish(nats, "user.created.v1", { name: "Mary" }, triggered_by: event)
+polyn.publish("user.created.v1", { name: "Mary" }, triggered_by: event)
 ```
 
 You can also include options of `:header` and/or `:reply_to` to passthrough to NATS
@@ -93,8 +96,9 @@ require "nats/client"
 require "polyn"
 
 nats = NATS.connect
+polyn = Polyn.connect(nats)
 
-psub = Polyn.pull_subscribe(nats, "user.created.v1")
+psub = Polyn.pull_subscribe("user.created.v1")
 
 loop do
   msgs = psub.fetch(5)
@@ -116,8 +120,9 @@ require "nats/client"
 require "polyn"
 
 nats = NATS.connect
+polyn = Polyn.connect
 
-sub = Polyn.subscribe(nats, "user.created.v1") { |msg| puts msg.data }
+sub = polyn.subscribe("user.created.v1") { |msg| puts msg.data }
 ```
 
 `Polyn.subscribe` will process the block you pass it asynchronously in a separate thread
@@ -131,10 +136,35 @@ require "nats/client"
 
 nats = NATS.connect
 nats.on_error { |e| raise e }
+polyn = Polyn.connect(nats)
 
-sub = Polyn.subscribe(nats, "user.created.v1") { |msg| puts msg.data }
+sub = polyn.subscribe("user.created.v1") { |msg| puts msg.data }
 ```
 
+## Testing
+
+### Setup
+
+Set an environment variable of `POLYN_ENV=test` or `RAILS_ENV=test`.
+
+Add the following to your `spec_helper.rb`
+
+```ruby
+require "polyn/testing"
+
+Polyn::Testing.setup
+```
+
+Add the following to individual test files `include_context :polyn`
+
+### Test Isolation
+
+Following the test setup instructions replaces *most* `Polyn` calls to NATS with mocks. Rather than hitting a real nats-server, the mocks will create an isolated sandbox for each test to ensure that message passing in one test is not affecting any other test. This will help prevent flaky tests and race conditions. It also makes concurrent testing possible. The tests will also all share the same schema store so that schemas aren't fetched from the nats-server repeatedly.
+
+Despite mocking some NATS functionality you will still need a running nats-server for your testing.
+When the tests start it will load all your schemas. The tests themselves will also use the running server to verify
+stream and consumer configuration information. This hybrid mocking approach is intended to give isolation and reliability while also ensuring correct integration.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run

data/lib/polyn/configuration.rb

@@ -7,8 +7,11 @@ module Polyn
     def initialize
       @domain      = nil
       @source_root = nil
+      @polyn_env   = ENV["POLYN_ENV"] || ENV["RAILS_ENV"] || "development"
     end
 
+    attr_reader :polyn_env
+
     def domain
       @domain ||= Polyn::Naming.validate_domain_name!(@domain)
     end

data/lib/polyn/naming.rb

@@ -93,6 +93,27 @@ module Polyn
       end
     end
 
+    ##
+    # Determine if a given subject matches a subscription pattern
+    def self.subject_matches?(subject, pattern)
+      separator         = "."
+
+      pattern_tokens = pattern.split(separator).map { |token| build_subject_pattern_part(token) }
+      pattern_tokens = pattern_tokens.join("\\#{separator}")
+      subject.match?(Regexp.new(pattern_tokens))
+    end
+
+    def self.build_subject_pattern_part(token)
+      single_wildcard   = "*"
+      multiple_wildcard = ">"
+
+      return "(\\w+)" if token == single_wildcard
+
+      return "((\\w+\\.)*\\w)" if token == multiple_wildcard
+
+      token
+    end
+
     def self.domain
       Polyn.configuration.domain
     end

data/lib/polyn/nats/msg.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Polyn
+  class Nats
+    ##
+    # Wrapper around Nats::Msg so that we own it
+    class Msg
+      def initialize(msg)
+        @msg = msg
+      end
+
+      attr_accessor :subject, :reply, :data, :header
+
+      def subject
+        @msg.subject
+      end
+
+      def reply
+        @msg.reply
+      end
+
+      def data
+        @msg.data
+      end
+
+      def data=(data)
+        @msg.data = data
+      end
+
+      def header
+        @msg.header
+      end
+
+      def ack(**params)
+        @msg.ack(**params)
+      end
+
+      def ack_sync(**params)
+        @msg.ack_sync(**params)
+      end
+
+      def nak(**params)
+        @msg.nack(**params)
+      end
+
+      def term(**params)
+        @msg.term(**params)
+      end
+
+      def in_progress(**params)
+        @msg.in_progress(**params)
+      end
+
+      def metadata
+        @msg.metadata
+      end
+
+      def respond(data = "")
+        @msg.respond(data)
+      end
+
+      def respond_msg(msg)
+        @msg.respond_msg(msg)
+      end
+
+      def inspect
+        @msg.inspect
+      end
+    end
+  end
+end

data/lib/polyn/nats.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Polyn
+  ##
+  # Adapter/wrapper around Nats
+  class Nats
+    def initialize(nats)
+      @nats = nats
+    end
+
+    def publish(type, json, reply, **opts)
+      @nats.publish(type, json, reply, **opts)
+    end
+
+    def subscribe(type, opts = {}, &callback)
+      @nats.subscribe(type, opts) { |msg| callback.call(Polyn::Nats::Msg.new(msg)) }
+    end
+
+    def jetstream
+      @jetstream ||= @nats.jetstream
+    end
+  end
+end

data/lib/polyn/pull_subscriber.rb

@@ -17,7 +17,7 @@ module Polyn
       @stream        = @nats.jetstream.find_stream_name_by_subject(@type)
       self.class.validate_consumer_exists!(@nats, @stream, @consumer_name)
       @psub          = @nats.jetstream.pull_subscribe(@type, @consumer_name)
-      @store_name    = store_name(fields)
+      @serializer    = fields.fetch(:serializer)
     end
 
     # nats-pure will create a consumer if the one you passed does not exist.
@@ -41,7 +41,8 @@ module Polyn
     def fetch(batch = 1, params = {})
       msgs = @psub.fetch(batch, params)
       msgs.map do |msg|
-        event    = Polyn::Serializers::Json.deserialize(@nats, msg.data, store_name: @store_name)
+        msg   = Polyn::Nats::Msg.new(msg)
+        event = @serializer.deserialize(msg.data)
         if event.is_a?(Polyn::Errors::Error)
           msg.term
           raise event
@@ -51,11 +52,5 @@ module Polyn
         msg
       end
     end
-
-    private
-
-    def store_name(opts)
-      opts.fetch(:store_name, Polyn::SchemaStore.store_name)
-    end
   end
 end

data/lib/polyn/schema_store.rb

@@ -4,47 +4,74 @@ module Polyn
   ##
   # Persisting and interacting with persisted schemas
   class SchemaStore
-    STORE_NAME = "POLYN_SCHEMAS"
+    STORE_NAME   = "POLYN_SCHEMAS"
+
+    def initialize(nats, **opts)
+      @nats       = nats
+      @store_name = opts[:name] || STORE_NAME
+      @key_prefix = "$KV.#{@store_name}"
+      @schemas    = opts[:schemas] || fetch_schemas
+    end
+
+    attr_reader :schemas
 
     ##
     # Persist a schema. In prod/dev schemas should have already been persisted via
     # the Polyn CLI.
-    def self.save(nats, type, schema, **opts)
+    def save(type, schema)
       json_schema?(schema)
-      kv = nats.jetstream.key_value(store_name(**opts))
-      kv.put(type, JSON.generate(schema))
+      schemas[type] = JSON.generate(schema)
     end
 
-    def self.json_schema?(schema)
+    def json_schema?(schema)
       JSONSchemer.schema(schema)
     end
 
-    def self.get!(nats, type, **opts)
-      result = get(nats, type, **opts)
+    def get!(type)
+      result = get(type)
       raise result if result.is_a?(Polyn::Errors::SchemaError)
 
       result
     end
 
-    def self.get(nats, type, **opts)
-      kv    = nats.jetstream.key_value(store_name(**opts))
-      entry = kv.get(type)
-      entry.value
-    rescue NATS::KeyValue::BucketNotFoundError
-      Polyn::Errors::SchemaError.new(
-        "The Schema Store has not been setup on your NATS server. Make sure you use "\
-        "the Polyn CLI to create it",
-      )
+    def get(type)
+      schema = schemas[type]
+
+      if schema.nil?
+        return Polyn::Errors::SchemaError.new(
+            "Schema for #{type} does not exist. Make sure it's "\
+            "been added to your `events` codebase and has been loaded "\
+            "into the schema store on your NATS server",
+          )
+      end
+
+      schema
+    end
+
+    private
+
+    def fetch_schemas
+      loop_store_keys
     rescue NATS::JetStream::Error::NotFound
-      Polyn::Errors::SchemaError.new(
-        "Schema for #{type} does not exist. Make sure it's "\
-        "been added to your `events` codebase and has been loaded "\
-        "into the schema store on your NATS server",
-      )
+      raise Polyn::Errors::SchemaError, "The Schema Store #{@store_name} has "\
+        "not been setup on your NATS server. Make sure you use Polyn CLI to create it"
     end
 
-    def self.store_name(**opts)
-      opts.fetch(:name, STORE_NAME)
+    def loop_store_keys
+      sub            = @nats.jetstream.subscribe("#{@key_prefix}.>")
+      results        = {}
+
+      loop do
+        msg                                              = sub.next_msg
+        results[msg.subject.gsub("#{@key_prefix}.", "")] = msg.data unless msg.data.empty?
+      # A timeout is the only mechanism given to indicate there are no
+      # more messages
+      rescue NATS::IO::Timeout
+        break
+      end
+
+      sub.unsubscribe
+      results
     end
   end
 end

data/lib/polyn/serializers/json.rb

@@ -22,50 +22,54 @@ module Polyn
     ##
     # Handles serializing and deserializing data to and from JSON.
     class Json
-      def self.serialize!(nats, event, **opts)
+      def initialize(schema_store)
+        @schema_store = schema_store
+      end
+
+      def serialize!(event)
         validate_event_instance!(event)
         event = event.to_h
-        validate!(nats, event, **opts)
+        validate!(event)
         JSON.generate(event)
       end
 
-      def self.deserialize!(nats, json, **opts)
-        data = deserialize(nats, json, **opts)
+      def deserialize!(json)
+        data = deserialize(json)
         raise data if data.is_a?(Polyn::Errors::Error)
 
         data
       end
 
-      def self.deserialize(nats, json, **opts)
+      def deserialize(json)
         data = decode(json)
         return data if data.is_a?(Polyn::Errors::Error)
 
-        error = validate(nats, data, **opts)
+        error = validate(data)
         return error if error.is_a?(Polyn::Errors::Error)
 
         data   = Polyn::Utils::Hash.deep_symbolize_keys(data)
         Event.new(data)
       end
 
-      def self.decode(json)
+      def decode(json)
         JSON.parse(json)
       rescue JSON::ParserError
         Polyn::Errors::ValidationError.new("Polyn was unable to decode the following message: \n#{json}")
       end
 
-      def self.validate!(nats, event, **opts)
-        result = validate(nats, event, **opts)
+      def validate!(event)
+        result = validate(event)
         raise result if result.is_a?(Polyn::Errors::Error)
       end
 
-      def self.validate(nats, event, **opts)
+      def validate(event)
         error = validate_cloud_event(event)
         return error if error.is_a?(Polyn::Errors::Error)
 
-        validate_data(nats, event, **opts)
+        validate_data(event)
       end
 
-      def self.validate_event_instance!(event)
+      def validate_event_instance!(event)
         if event.instance_of?(Polyn::Event)
           event
         else
@@ -74,22 +78,22 @@ module Polyn
         end
       end
 
-      def self.validate_cloud_event(event)
+      def validate_cloud_event(event)
         cloud_event_schema = Polyn::CloudEvent.to_h
         validate_schema(cloud_event_schema, event)
       end
 
-      def self.validate_data(nats, event, **opts)
+      def validate_data(event)
         type   = get_event_type(event)
         return type if type.is_a?(Polyn::Errors::Error)
 
-        schema = get_schema(nats, type, **opts)
+        schema = get_schema(type)
         return schema if schema.is_a?(Polyn::Errors::Error)
 
         validate_schema(schema, event)
       end
 
-      def self.validate_schema(schema, event)
+      def validate_schema(schema, event)
         schema = JSONSchemer.schema(schema)
         errors = schema.validate(event).to_a
         errors = format_schema_errors(errors)
@@ -101,7 +105,7 @@ module Polyn
         errors
       end
 
-      def self.get_event_type(event)
+      def get_event_type(event)
         if event["type"]
           Polyn::Naming.trim_domain_prefix(event["type"])
         else
@@ -111,26 +115,22 @@ module Polyn
         end
       end
 
-      def self.get_schema(nats, type, **opts)
-        Polyn::SchemaStore.get(nats, type, name: store_name(**opts))
+      def get_schema(type)
+        @schema_store.get(type)
       end
 
-      def self.format_schema_errors(errors)
+      def format_schema_errors(errors)
         errors.map do |error|
           "Property: `#{error['data_pointer']}` - #{error['type']} - #{error['details']}"
         end
       end
 
-      def self.combined_error_message(event, errors)
+      def combined_error_message(event, errors)
         [
           "Polyn event #{event['id']} from #{event['source']} is not valid",
           "Event data: #{event.inspect}",
         ].concat(errors).join("\n")
       end
-
-      def self.store_name(**opts)
-        opts[:store_name] || Polyn::SchemaStore.store_name
-      end
     end
   end
 end

data/lib/polyn/testing/mock_jetstream.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Polyn
+  class Testing
+    ##
+    # Mock JetStream for applications to use in testing
+    class MockJetStream
+      def initialize(mock_nats)
+        @mock_nats = mock_nats
+        @real_nats = mock_nats.nats
+      end
+
+      def consumer_info(stream, consumer_name)
+        @real_nats.jetstream.consumer_info(stream, consumer_name)
+      end
+
+      def find_stream_name_by_subject(subject)
+        @real_nats.jetstream.find_stream_name_by_subject(subject)
+      end
+
+      def pull_subscribe(subject, consumer_name)
+        Polyn::Testing::MockPullSubscription.new(
+          @mock_nats,
+          subject:       subject,
+          consumer_name: consumer_name,
+        )
+      end
+    end
+  end
+end

data/lib/polyn/testing/mock_msg.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Polyn
+  class Testing
+    class MockMsg
+      def initialize(opts = {})
+        @subject = opts[:subject]
+        @reply   = opts[:reply]
+        @data    = opts[:data]
+        @header  = opts[:header]
+      end
+
+      attr_accessor :subject, :reply, :data, :header
+
+      def ack(**params); end
+
+      def ack_sync(**params); end
+
+      def nak(**params); end
+
+      def term(**params); end
+
+      def in_progress(**params); end
+
+      def metadata; end
+    end
+  end
+end

data/lib/polyn/testing/mock_nats.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "nats/io/msg"
+require "polyn/naming"
+require "polyn/testing/mock_jetstream"
+require "polyn/testing/mock_msg"
+require "polyn/testing/mock_pull_subscription"
+
+module Polyn
+  class Testing
+    ##
+    # Mock Nats connection for applications to use in testing
+    class MockNats
+      def initialize(nats)
+        @nats        = nats
+        @messages    = []
+        @subscribers = []
+        @consumers   = []
+      end
+
+      attr_reader :nats, :messages
+
+      def publish(subject, data, reply_to = nil, **opts)
+        msg = Polyn::Testing::MockMsg.new(subject: subject, data: data, reply: reply_to,
+          header: opts[:header])
+        send_to_subscribers(msg)
+        @messages << msg
+        update_consumers
+      end
+
+      def subscribe(subject, _opts = {}, &callback)
+        @subscribers << { subject: subject, callback: callback }
+      end
+
+      def jetstream
+        @jetstream ||= MockJetStream.new(self)
+      end
+
+      def add_consumer(consumer)
+        @consumers << consumer
+      end
+
+      private
+
+      def send_to_subscribers(msg)
+        @subscribers.each do |sub|
+          sub[:callback].call(msg) if Polyn::Naming.subject_matches?(msg.subject, sub[:subject])
+        end
+      end
+
+      def update_consumers
+        @consumers.each(&:update_stream)
+      end
+    end
+  end
+end

data/lib/polyn/testing/mock_pull_subscription.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Polyn
+  class Testing
+    ##
+    # Mock Pull Subscription for applications to use in testing
+    class MockPullSubscription
+      def initialize(mock_nats, **opts)
+        @mock_nats       = mock_nats
+        @real_nats       = mock_nats.nats
+        @subject         = opts.fetch(:subject)
+        @consumer_name   = opts.fetch(:consumer_name)
+        @stream          = update_stream
+        @delivery_cursor = 0
+        @mock_nats.add_consumer(self)
+      end
+
+      def fetch(batch = 1, **_params)
+        start_pos        = @delivery_cursor
+        end_pos          = start_pos + batch - 1
+        update_cursor(end_pos)
+        @stream[start_pos..end_pos]
+      end
+
+      def update_stream
+        @stream = @mock_nats.messages.filter do |message|
+          Polyn::Naming.subject_matches?(message.subject, @subject)
+        end
+        @stream
+      end
+
+      def update_cursor(end_pos)
+        next_pos = end_pos + 1
+
+        @delivery_cursor = if @stream[next_pos]
+                             next_pos
+                           else
+                             @stream.length
+                           end
+      end
+    end
+  end
+end

data/lib/polyn/testing.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "polyn/schema_store"
+require "polyn/testing/mock_nats"
+
+module Polyn
+  ##
+  # Test helpers to help keep tests predictable
+  class Testing
+    ##
+    # Use this in spec_helper.rb to include a shared_context that can be
+    # used with `include_context :polyn`
+    def self.setup(**_opts)
+      conn         = NATS.connect
+      schema_store = Polyn::SchemaStore.new(conn)
+
+      RSpec.shared_context :polyn do
+        before(:each) do
+          # Have a global, shared schema store that only pulls the schemas
+          # once for the whole test suite. For testing an application the
+          # schemas are expected to be the same throughout the whole suite
+          Thread.current[:polyn_schema_store] = schema_store
+        end
+
+        after(:each) do
+          Thread.current[:polyn_schema_store] = nil
+        end
+      end
+    end
+  end
+end

data/lib/polyn/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Polyn
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/polyn.rb

@@ -28,6 +28,8 @@ require "polyn/cloud_event"
 require "polyn/errors/errors"
 require "polyn/event"
 require "polyn/naming"
+require "polyn/nats"
+require "polyn/nats/msg"
 require "polyn/pull_subscriber"
 require "polyn/schema_store"
 require "polyn/serializers/json"
@@ -38,79 +40,117 @@ require "polyn/version"
 # Polyn is a Reactive service framework.
 module Polyn
   ##
-  # Publishes a message on the Polyn network.
-  #
-  # @param nats [Object] Connected NATS instance from `NATS.connect`
-  # @param type [String] The type of event
-  # @param data [any] The data to include in the event
-  # @option options [String] :source - information to specify the source of the event
-  # @option options [String] :triggered_by - The event that triggered this one.
-  # Will use information from the event to build up the `polyntrace` data
-  # @option options [String] :reply_to - Reply to a specific topic
-  # @option options [String] :header - Headers to include in the message
-  def self.publish(nats, type, data, **opts)
-    event = Event.new({
-      type:         type,
-      source:       opts[:source],
-      data:         data,
-      triggered_by: opts[:triggered_by],
-    })
-
-    json = Polyn::Serializers::Json.serialize!(nats, event, **opts)
-
-    nats.publish(type, json, opts[:reply_to], header: opts[:header])
+  # Configuration information for Polyn
+  def self.configuration
+    @configuration ||= Configuration.new
   end
 
-  ## Create subscription which is dispatched asynchronously
-  # and sends messages to a callback.
-  #
-  # @param nats [Object] Connected NATS instance from `NATS.connect`
-  # @param type [String] The type of event
-  # @option options [String] :queue - Queue group to add subscriber to
-  # @option options [String] :max - Max msgs before unsubscribing
-  # @option options [String] :pending_msgs_limit
-  # @option options [String] :pending_bytes_limit
-  def self.subscribe(nats, type, opts = {}, &callback)
-    nats.subscribe(type, opts) do |msg|
-      event    = Polyn::Serializers::Json.deserialize!(nats, msg.data,
-        store_name: opts[:store_name])
-      msg.data = event
-      callback.call(msg)
-    end
+  ##
+  # Configuration block to configure Polyn
+  def self.configure
+    yield(configuration)
   end
 
   ##
-  # Subscribe to a pull consumer that already exists in the NATS server
+  # Connects Polyn to a NATS connection and loads all event schemas
   #
-  # @param nats [Object] Connected NATS instance from `NATS.connect`
-  # @param type [String] The type of event
-  # @option options [String] :source - If the `source` portion of the consumer name
-  # is more than the `source_root`
-  def self.pull_subscribe(nats, type, **opts)
-    Polyn::PullSubscriber.new({ nats: nats, type: type, source: opts[:source] })
-  end
-
-  # nats-pure will create a consumer if the one you passed does not exist.
-  # Polyn wants to avoid this functionality and instead encourage
-  # consumer creation in the centralized `events` codebase so that
-  # it's documented, discoverable, and polyn-cli can manage it
-  def self.validate_consumer_exists!(nats, stream, consumer_name)
-    nats.jetstream.consumer_info(stream, consumer_name)
-  rescue NATS::JetStream::Error::NotFound
-    raise Polyn::Errors::ValidationError,
-      "Consumer #{consumer_name} does not exist. Use polyn-cli to create "\
-      "it before attempting to subscribe"
+  # @param nats [NATS::IO::Client] A nats connection instance
+  def self.connect(nats, **opts)
+    Conn.new(nats, **opts)
   end
 
   ##
-  # Configuration information for Polyn
-  def self.configuration
-    @configuration ||= Configuration.new
-  end
+  # A Polyn connection to NATS
+  class Conn
+    def initialize(nats, **opts)
+      @nats         = nats_class.new(nats)
+      # Schema store nats has to be a real one, not a mock, because
+      # the only place to load the schemas is from a running nats-server
+      @schema_store = opts[:schema_store] || schema_store(nats, **opts)
+      @serializer   = Polyn::Serializers::Json.new(@schema_store)
+    end
 
-  ##
-  # Configuration block to configure Polyn
-  def self.configure
-    yield(configuration)
+    ##
+    # Publishes a message on the Polyn network.
+    #
+    # @param type [String] The type of event
+    # @param data [any] The data to include in the event
+    # @option options [String] :source - information to specify the source of the event
+    # @option options [String] :triggered_by - The event that triggered this one.
+    # Will use information from the event to build up the `polyntrace` data
+    # @option options [String] :reply_to - Reply to a specific topic
+    # @option options [String] :header - Headers to include in the message
+    def publish(type, data, **opts)
+      event = Event.new({
+        type:         type,
+        source:       opts[:source],
+        data:         data,
+        triggered_by: opts[:triggered_by],
+      })
+
+      # Ensure accidental message duplication doesn't happen
+      # https://docs.nats.io/using-nats/developer/develop_jetstream/model_deep_dive#message-deduplication
+      msg_id_header = { "Nats-Msg-Id" => event.id }
+      header        = opts.fetch(:header, {})
+      header        = msg_id_header.merge(header)
+
+      json = @serializer.serialize!(event)
+
+      @nats.publish(type, json, opts[:reply_to], header: header)
+    end
+
+    ## Create subscription which is dispatched asynchronously
+    # and sends messages to a callback.
+    #
+    # @param type [String] The type of event
+    # @option options [String] :queue - Queue group to add subscriber to
+    # @option options [String] :max - Max msgs before unsubscribing
+    # @option options [String] :pending_msgs_limit
+    # @option options [String] :pending_bytes_limit
+    def subscribe(type, opts = {}, &callback)
+      @nats.subscribe(type, opts) do |msg|
+        event    = @serializer.deserialize!(msg.data)
+        msg.data = event
+        callback.call(msg)
+      end
+    end
+
+    ##
+    # Subscribe to a pull consumer that already exists in the NATS server
+    #
+    # @param nats [Object] Connected NATS instance from `NATS.connect`
+    # @param type [String] The type of event
+    # @option options [String] :source - If the `source` portion of the consumer name
+    # is more than the `source_root`
+    def pull_subscribe(type, **opts)
+      Polyn::PullSubscriber.new({
+        nats:       @nats,
+        type:       type,
+        source:     opts[:source],
+        serializer: @serializer,
+      })
+    end
+
+    private
+
+    def schema_store(nats, **opts)
+      if Polyn.configuration.polyn_env == "test"
+        # For application tests reuse the same schema_store so we don't
+        # waste time fetching the schemas on every test
+        Thread.current[:polyn_schema_store]
+      else
+        Polyn::SchemaStore.new(nats, name: opts[:store_name])
+      end
+    end
+
+    ##
+    # NATS connection class to use based on environment
+    def nats_class
+      if Polyn.configuration.polyn_env == "test"
+        Polyn::MockNats
+      else
+        Polyn::Nats
+      end
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: polyn
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Jarod
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-08-18 00:00:00.000000000 Z
+date: 2022-09-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json_schemer
@@ -88,9 +88,16 @@ files:
 - lib/polyn/errors/validation_error.rb
 - lib/polyn/event.rb
 - lib/polyn/naming.rb
+- lib/polyn/nats.rb
+- lib/polyn/nats/msg.rb
 - lib/polyn/pull_subscriber.rb
 - lib/polyn/schema_store.rb
 - lib/polyn/serializers/json.rb
+- lib/polyn/testing.rb
+- lib/polyn/testing/mock_jetstream.rb
+- lib/polyn/testing/mock_msg.rb
+- lib/polyn/testing/mock_nats.rb
+- lib/polyn/testing/mock_pull_subscription.rb
 - lib/polyn/utils/hash.rb
 - lib/polyn/utils/string.rb
 - lib/polyn/utils/utils.rb