downstream 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44d7614f5509bb04efddc18f5dd26f4030a4262c00e6a370da13797d1efd99a6
-  data.tar.gz: 8ea205b3d718e21b01a82cb65b51ae1870068f1065f679af4e4fe94bcdebe87a
+  metadata.gz: 0b7d5e8e2cd8390bbb0eef4fc8df4615c1bb2a5f5202ac0711f417b6347b7adc
+  data.tar.gz: 2a13ccafc25da88885ce49a309c41d4fc0cda93a7ffbd37cc2454e94359c1248
 SHA512:
-  metadata.gz: 5376229dc224f18496764928e4019bd72791ac660bc90f975abba38fe961e305dd9e6d997573aae7ef9acd3b785659ff9171678d2ccd1dd02f89add6fa5b01cb
-  data.tar.gz: f5a17a4a6f8383b35820914cc658fe97a41b2554df16c2088dcac3857af264e7976c5af3ab5249635e884de1ffe590dd32d270583230e79fa63ad09b5ae5294e
+  metadata.gz: 5b1cc9d3110a38b6575363b929cf8d2b8a6df186e4099268a9f66f6c20f4d04d3e1c62df9b0c308ee21a5a8e1fcdf9c1f62070e39708db22be739173f8a0d788
+  data.tar.gz: 4ff6301363da1ebff02ba743571166b89eaf35151427a3f6f8e70d54e8bd18a244ae863cdab4247afb412f97ed1a7a7b01a91a3c54d0ab35a56810584d87ef39

data/README.md

@@ -20,7 +20,17 @@ gem "downstream", "~> 1.0"
 
 ## Usage
 
-Under the hood it's a wrapper for `ActiveSupport::Notifications`. But it provides a way more handy interface to build reactive apps. Each event has a strict schema described by a separate class. Also, the gem has convenient tooling to write tests.
+Downstream provides a way more handy interface to build reactive apps. Each event has a strict schema described by a separate class. The gem has convenient tooling to write tests.
+
+Downstream supports various adapters for event handling. It can be configured in a Rails initializer `config/initializers/downstream.rb`:
+
+```ruby
+Downstream.configure do |config|
+  config.pubsub = :stateless # it's a default adapter
+end
+```
+
+For now, it's implemented only one adapter. The `stateless` adapter is based on `ActiveSupport::Notifications`, and it doesn't store history events anywhere. All event invocations are synchronous. Adding asynchronous subscribers are on my road map.
 
 ### Describe events
 
@@ -77,7 +87,7 @@ initializer "my_engine.subscribe_to_events" do
     store.subscribe MyEventHandler, to: ProfileCreated
 
     # anonymous handler (could only be synchronous)
-    store.subscribe(to: ProfileCreated) do |name, event|
+    store.subscribe(to: ProfileCreated) do |event|
       # do something
     end
 
@@ -93,6 +103,15 @@ end
 
 Although subscriber could be any callable Ruby object, that have specific input format (event); thus we suggest putting subscribers under `app/subscribers/on_<event_type>/<subscriber.rb>`, e.g. `app/subscribers/on_profile_created/create_chat_user.rb`).
 
+Sometimes, you may be interested in using temporary subscriptions. For that, you can use this:
+
+```ruby
+subscriber = ->(event) { my_event_handler(event) }
+Downstream.subscribed(subscriber, to: ProfileCreated) do
+  some_invocation
+end
+```
+
 ## Testing
 
 You can test subscribers as normal Ruby objects.

data/lib/downstream/config.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "active_support/inflections"
+
 module Downstream
   class Config
     attr_writer :namespace
@@ -7,5 +9,33 @@ module Downstream
     def namespace
       @namespace ||= "downstream-events"
     end
+
+    def pubsub
+      @pubsub ||= lookup_pubsub(:stateless)
+    end
+
+    def pubsub=(value)
+      @pubsub = case value
+        when String, Symbol
+          lookup_pubsub(value)
+        else
+          value
+      end
+    end
+
+    private
+
+    def lookup_pubsub(name)
+      klass = name.camelize.safe_constantize if name.is_a?(String)
+
+      klass ||= begin
+        require "downstream/pubsub_adapters/#{name}/pubsub"
+        "Downstream::#{name.to_s.camelize}::Pubsub".safe_constantize
+      end
+
+      raise ArgumentError, "Uknown downstream pubsub adapter: #{name}" unless klass
+
+      klass.new
+    end
   end
 end

data/lib/downstream/pubsub_adapters/abstract_pubsub.rb

@@ -0,0 +1,15 @@
+module Downstream
+  class AbstractPubsub
+    def subscribe(identifier, callable)
+      raise NotImplementedError
+    end
+
+    def subscribed(identifier, callable, &block)
+      raise NotImplementedError
+    end
+
+    def publish(identifier, event)
+      raise NotImplementedError
+    end
+  end
+end

data/lib/downstream/pubsub_adapters/stateless/pubsub.rb

@@ -0,0 +1,27 @@
+require "active_support/notifications"
+require_relative "subscriber"
+
+module Downstream
+  module Stateless
+    class Pubsub < AbstractPubsub
+      def subscribe(identifier, callable)
+        ActiveSupport::Notifications.subscribe(
+          identifier,
+          Subscriber.new(callable)
+        )
+      end
+
+      def subscribed(identifier, callable, &block)
+        ActiveSupport::Notifications.subscribed(
+          Subscriber.new(callable),
+          identifier,
+          &block
+        )
+      end
+
+      def publish(identifier, event)
+        ActiveSupport::Notifications.publish(identifier, event)
+      end
+    end
+  end
+end

data/lib/downstream/pubsub_adapters/stateless/subscriber.rb

@@ -0,0 +1,19 @@
+module Downstream
+  module Stateless
+    class Subscriber
+      attr_reader :callable
+
+      def initialize(callable)
+        @callable = callable
+      end
+
+      def call(name, event)
+        if (callable.respond_to?(:arity) && callable.arity == 2) || callable.method(:call).arity == 2
+          callable.call(name, event)
+        else
+          callable.call(event)
+        end
+      end
+    end
+  end
+end

data/lib/downstream/rspec/have_published_event.rb

@@ -52,17 +52,17 @@ module Downstream
     def matches?(block)
       raise ArgumentError, "have_published_event only supports block expectations" unless block.is_a?(Proc)
 
-      events = []
-      namespace = /^#{Downstream.config.namespace}\./
-      ActiveSupport::Notifications.subscribed(->(name, event) { events << event }, namespace) do
-        block.call
-      end
+      @matching_events = []
 
-      @matching_events, @unmatching_events =
-        events.partition do |actual_event|
-          (event_class.identifier == actual_event.type) &&
-            (attributes.nil? || attributes_match?(actual_event))
+      subscriber = ->(event) do
+        if attributes.nil? || attributes_match?(event)
+          @matching_events << event
         end
+      end
+
+      Downstream.subscribed(subscriber, to: event_class) do
+        block.call
+      end
 
       @matching_count = @matching_events.size
 
@@ -75,16 +75,7 @@ module Downstream
 
     def failure_message
       (+"expected to publish #{event_class.identifier} event").tap do |msg|
-        msg << " #{message_expectation_modifier}, but"
-
-        if @unmatching_events.any?
-          msg << " published the following events:"
-          @unmatching_events.each do |unmatching_event|
-            msg << "\n  #{unmatching_event.inspect}"
-          end
-        else
-          msg << " haven't published anything"
-        end
+        msg << " #{message_expectation_modifier}, but haven't published"
       end
     end
 

data/lib/downstream/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Downstream
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/lib/downstream.rb

@@ -5,40 +5,46 @@ require "active_model"
 
 require "downstream/config"
 require "downstream/event"
+require "downstream/pubsub_adapters/abstract_pubsub"
 require "downstream/rspec" if defined?(RSpec)
 
 module Downstream
   class << self
+    delegate :pubsub, to: :config
+
     def config
       @config ||= Config.new
     end
 
-    def subscribe(subscriber = nil, to: nil, &block)
-      to ||= infer_event_from_subscriber(subscriber) if subscriber.is_a?(Module)
-
-      if to.nil?
-        raise ArgumentError, "Couldn't infer event from subscriber. " \
-                              "Please, specify event using `to:` option"
-      end
+    def configure
+      yield config
+    end
 
+    def subscribe(subscriber = nil, to: nil, &block)
       subscriber ||= block if block
+      raise ArgumentError, "Subsriber must be present" if subscriber.nil?
 
-      if subscriber.nil?
-        raise ArgumentError, "Subsriber must be present"
-      end
+      identifier = construct_identifier(subscriber, to)
 
-      identifier =
-        if to.is_a?(Class) && Event >= to
-          to.identifier
-        else
-          to
-        end
-
-      ActiveSupport::Notifications.subscribe("#{config.namespace}.#{identifier}", subscriber)
+      pubsub.subscribe(identifier, subscriber)
     end
 
     # temporary subscriptions
     def subscribed(subscriber, to: nil, &block)
+      raise ArgumentError, "Subsriber must be present" if subscriber.nil?
+
+      identifier = construct_identifier(subscriber, to)
+
+      pubsub.subscribed(identifier, subscriber, &block)
+    end
+
+    def publish(event)
+      pubsub.publish("#{config.namespace}.#{event.type}", event)
+    end
+
+    private
+
+    def construct_identifier(subscriber, to)
       to ||= infer_event_from_subscriber(subscriber) if subscriber.is_a?(Module)
 
       if to.nil?
@@ -46,22 +52,15 @@ module Downstream
                               "Please, specify event using `to:` option"
       end
 
-      identifier =
-        if to.is_a?(Class) && Event >= to
-          to.identifier
-        else
-          to
-        end
-
-      ActiveSupport::Notifications.subscribed(subscriber, "#{config.namespace}.#{identifier}", &block)
-    end
+      identifier = if to.is_a?(Class) && Event >= to
+        to.identifier
+      else
+        to
+      end
 
-    def publish(event)
-      ActiveSupport::Notifications.publish("#{config.namespace}.#{event.type}", event)
+      "#{config.namespace}.#{identifier}"
     end
 
-    private
-
     def infer_event_from_subscriber(subscriber)
       event_class_name = subscriber.name.split("::").yield_self do |parts|
         # handle explicti top-level name, e.g. ::Some::Event

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: downstream
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - merkushin.m.s@gmail.com
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-10-28 00:00:00.000000000 Z
+date: 2021-10-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -17,14 +17,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '5'
+        version: '6'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '5'
+        version: '6'
 - !ruby/object:Gem::Dependency
   name: appraisal
   requirement: !ruby/object:Gem::Requirement
@@ -121,6 +121,9 @@ files:
 - lib/downstream/config.rb
 - lib/downstream/engine.rb
 - lib/downstream/event.rb
+- lib/downstream/pubsub_adapters/abstract_pubsub.rb
+- lib/downstream/pubsub_adapters/stateless/pubsub.rb
+- lib/downstream/pubsub_adapters/stateless/subscriber.rb
 - lib/downstream/rspec.rb
 - lib/downstream/rspec/have_published_event.rb
 - lib/downstream/version.rb