downstream 1.1.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b7d5e8e2cd8390bbb0eef4fc8df4615c1bb2a5f5202ac0711f417b6347b7adc
-  data.tar.gz: 2a13ccafc25da88885ce49a309c41d4fc0cda93a7ffbd37cc2454e94359c1248
+  metadata.gz: 0770f84f43315d12f61f304600f5bdbb45679de5fc32820a6d599fdab4f0028d
+  data.tar.gz: aa877161f770583a778578d165b36e61df405eeecc4522ffe8af212085f5f2d7
 SHA512:
-  metadata.gz: 5b1cc9d3110a38b6575363b929cf8d2b8a6df186e4099268a9f66f6c20f4d04d3e1c62df9b0c308ee21a5a8e1fcdf9c1f62070e39708db22be739173f8a0d788
-  data.tar.gz: 4ff6301363da1ebff02ba743571166b89eaf35151427a3f6f8e70d54e8bd18a244ae863cdab4247afb412f97ed1a7a7b01a91a3c54d0ab35a56810584d87ef39
+  metadata.gz: 7c245ff4501fbd5d1efd3d17958a2784d9cf2ff28037c647a7b25a89f6cafd13c716947f7a0fc94b50c64952e5a175a6117858ef7c94bc339119f01e4bda98b8
+  data.tar.gz: 97defc1ff2d152767d833b4be84ac9b9c1202dce8f0e0673c7f5a25af09763b1ff54ea61839e7dfe1c9d16ebb6f45a8efff5d43d87d6494f193387f341b971a1

data/README.md

@@ -3,7 +3,7 @@
 
 # Downstream
 
-This gem provides a straightforward way to implement communication between Rails Engines using the Publish-Subscribe pattern. The gem allows decreasing decoupling engines with events. An event is a recorded object in the system that reflects an action that the engine performs, and the params that lead to its creation.
+This gem provides a straightforward way to implement communication between Rails Engines using the Publish-Subscribe pattern. The gem allows decreasing the coupling of engines with events. An event is a recorded object in the system that reflects an action that the engine performs, and the params that lead to its creation.
 
 The gem inspired by [`active_event_store`](https://github.com/palkan/active_event_store), and initially based on its codebase. Having said that, it does not store in a database all happened events which ensures simplicity and performance.
 
@@ -27,6 +27,7 @@ Downstream supports various adapters for event handling. It can be configured in
 ```ruby
 Downstream.configure do |config|
   config.pubsub = :stateless # it's a default adapter
+  config.async_queue = :high_priority # nil by default
 end
 ```
 
@@ -112,10 +113,30 @@ Downstream.subscribed(subscriber, to: ProfileCreated) do
 end
 ```
 
+If you want to handle events in a background job, you can pass the `async: true` option:
+
+```ruby
+store.subscribe OnProfileCreated::DoThat, async: true
+```
+
+By default, a job will be enqueued into `async_queue` name from the Downstream config. You can define your own queue name for a specific subscriber:
+
+```ruby
+store.subscribe OnProfileCreated::DoThat, async: {queue: :low_priority}
+```
+
+**NOTE:** all subscribers are synchronous by default
+
 ## Testing
 
 You can test subscribers as normal Ruby objects.
 
+First, load testing helpers in the `spec_helper.rb`:
+
+```ruby
+require "downstream/rspec"
+```
+
 To test that a given subscriber exists, you can do the following:
 
 ```ruby
@@ -128,6 +149,14 @@ it "is subscribed to some event" do
 
   expect(MySubscriberService).to have_received(:call).with(event)
 end
+
+# for asynchronous subscriptions
+it "is subscribed to some event" do
+  event = MyEvent.new(some: "data")
+  expect { Downstream.publish event }.
+    to have_enqueued_async_subscriber_for(MySubscriberService).
+    with(event)
+end
 ```
 
 To test publishing use `have_published_event` matcher:

data/lib/downstream/config.rb

@@ -4,6 +4,7 @@ require "active_support/inflections"
 
 module Downstream
   class Config
+    attr_accessor :async_queue
     attr_writer :namespace
 
     def namespace
@@ -16,10 +17,10 @@ module Downstream
 
     def pubsub=(value)
       @pubsub = case value
-        when String, Symbol
-          lookup_pubsub(value)
-        else
-          value
+      when String, Symbol
+        lookup_pubsub(value)
+      else
+        value
       end
     end
 

data/lib/downstream/event.rb

@@ -1,10 +1,24 @@
 # frozen_string_literal: true
 
+GlobalID::Locator.use :downstream do |gid|
+  params = gid.params.each_with_object({}) do |(key, value), memo|
+    memo[key.to_sym] = if value.is_a?(String) && value.start_with?("gid://")
+      GlobalID::Locator.locate(value)
+    else
+      value
+    end
+  end
+
+  gid.model_name.constantize
+    .new(event_id: gid.model_id, **params)
+end
+
 module Downstream
   class Event
     extend ActiveModel::Naming
+    include GlobalID::Identification
 
-    RESERVED_ATTRIBUTES = %i[event_id type].freeze
+    RESERVED_ATTRIBUTES = %i[id event_id type].freeze
 
     class << self
       attr_writer :identifier
@@ -57,6 +71,8 @@ module Downstream
 
     attr_reader :event_id, :data, :errors
 
+    alias_method :id, :event_id
+
     def initialize(event_id: nil, **params)
       @event_id = event_id || SecureRandom.hex(10)
       validate_attributes!(params)
@@ -77,6 +93,20 @@ module Downstream
       }
     end
 
+    def to_global_id
+      new_data = data.each_with_object({}) do |(key, value), memo|
+        memo[key] = if value.respond_to?(:to_global_id)
+          value.to_global_id
+        else
+          value
+        end
+      end
+
+      super(new_data.merge!(app: :downstream))
+    end
+
+    alias_method :to_gid, :to_global_id
+
     def inspect
       "#{self.class.name}<#{type}##{event_id}>, data: #{data}"
     end
@@ -85,6 +115,15 @@ module Downstream
       data.fetch(attr)
     end
 
+    def ==(other)
+      super ||
+        other.instance_of?(self.class) &&
+          !event_id.nil? &&
+          other.event_id == event_id
+    end
+
+    alias_method :eql?, :==
+
     private
 
     def validate_attributes!(params)

data/lib/downstream/pubsub_adapters/abstract_pubsub.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Downstream
   class AbstractPubsub
     def subscribe(identifier, callable)

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

@@ -1,14 +1,13 @@
+# frozen_string_literal: true
+
 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)
-        )
+      def subscribe(identifier, callable, async: false)
+        Subscriber.new(callable, async: async).tap { |s| s.subscribe(identifier) }
       end
 
       def subscribed(identifier, callable, &block)
@@ -20,7 +19,7 @@ module Downstream
       end
 
       def publish(identifier, event)
-        ActiveSupport::Notifications.publish(identifier, event)
+        ActiveSupport::Notifications.instrument(identifier, event)
       end
     end
   end

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

@@ -1,19 +1,66 @@
+# frozen_string_literal: true
+
 module Downstream
   module Stateless
     class Subscriber
-      attr_reader :callable
+      include AfterCommitEverywhere
+
+      attr_reader :callable, :async
 
-      def initialize(callable)
+      def initialize(callable, async: false)
         @callable = callable
+        @async = async
+      end
+
+      def async?
+        !!async
       end
 
-      def call(name, event)
-        if (callable.respond_to?(:arity) && callable.arity == 2) || callable.method(:call).arity == 2
-          callable.call(name, event)
+      def call(_name, _start, _finish, _id, event)
+        if async?
+          if callable.is_a?(Proc) || callable.name.nil?
+            raise ArgumentError, "Anonymous subscribers (blocks/procs/lambdas or anonymous modules) cannot be asynchronous"
+          end
+
+          raise ArgumentError, "Async subscriber must be a module/class, not instance" unless callable.is_a?(Module)
+
+          after_commit do
+            SubscriberJob.then do |job|
+              if (queue_name = async_queue_name)
+                job.set(queue: queue_name)
+              else
+                job
+              end
+            end.perform_later(event, callable.name)
+          end
         else
           callable.call(event)
         end
       end
+
+      def subscribe(identifier)
+        @notification_subscriber = ActiveSupport::Notifications.subscribe(
+          identifier,
+          self
+        )
+      end
+
+      def unsubscribe
+        ActiveSupport::Notifications.unsubscribe(notification_subscriber)
+      end
+
+      private
+
+      attr_reader :notification_subscriber
+
+      def async_queue_name
+        return @async_queue_name if defined?(@async_queue_name)
+
+        name = async[:queue] if async.is_a?(Hash)
+        name ||= Downstream.config.async_queue
+
+        @async_queue_name = name
+      end
     end
   end
 end

data/lib/downstream/rspec/have_enqueued_async_subscriber_for.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "rspec/rails/matchers/active_job"
+
+module Downstream
+  class HaveEnqueuedAsyncSubscriberFor < RSpec::Rails::Matchers::ActiveJob::HaveEnqueuedJob
+    class EventMatcher
+      include ::RSpec::Matchers::Composable
+
+      attr_reader :event
+
+      def initialize(event)
+        @event = event
+      end
+
+      def matches?(actual)
+        actual == event
+      end
+
+      def description
+        "be #{event.inspect}"
+      end
+    end
+
+    attr_reader :callable
+
+    def initialize(callable)
+      @callable = callable
+      super(SubscriberJob)
+    end
+
+    def with(event)
+      super(EventMatcher.new(event), callable.name)
+    end
+
+    def matches?(proc)
+      raise ArgumentError, "have_enqueued_async_subscriber_for only supports block expectations" unless Proc === proc
+      super
+    end
+  end
+end
+
+RSpec.configure do |config|
+  config.include(Module.new do
+    def have_enqueued_async_subscriber_for(*args)
+      Downstream::HaveEnqueuedAsyncSubscriberFor.new(*args)
+    end
+  end)
+end

data/lib/downstream/rspec.rb

@@ -1,3 +1,4 @@
 # frozen_string_literal: true
 
 require_relative "rspec/have_published_event"
+require_relative "rspec/have_enqueued_async_subscriber_for"

data/lib/downstream/subscriber_job.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Downstream
+  class SubscriberJob < ActiveJob::Base
+    def perform(event, callable)
+      callable.constantize.call(event)
+    end
+  end
+end

data/lib/downstream/version.rb

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

data/lib/downstream.rb

@@ -1,12 +1,15 @@
 # frozen_string_literal: true
 
 require "active_support"
+require "active_job"
 require "active_model"
+require "globalid"
+require "after_commit_everywhere"
 
 require "downstream/config"
 require "downstream/event"
 require "downstream/pubsub_adapters/abstract_pubsub"
-require "downstream/rspec" if defined?(RSpec)
+require "downstream/subscriber_job"
 
 module Downstream
   class << self
@@ -20,13 +23,13 @@ module Downstream
       yield config
     end
 
-    def subscribe(subscriber = nil, to: nil, &block)
+    def subscribe(subscriber = nil, to: nil, async: false, &block)
       subscriber ||= block if block
       raise ArgumentError, "Subsriber must be present" if subscriber.nil?
 
       identifier = construct_identifier(subscriber, to)
 
-      pubsub.subscribe(identifier, subscriber)
+      pubsub.subscribe(identifier, subscriber, async: async)
     end
 
     # temporary subscriptions

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: downstream
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.4.0
 platform: ruby
 authors:
 - merkushin.m.s@gmail.com
@@ -9,8 +9,36 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-10-29 00:00:00.000000000 Z
+date: 2022-05-22 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: after_commit_everywhere
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: globalid
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
@@ -53,6 +81,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.16'
+- !ruby/object:Gem::Dependency
+  name: combustion
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
 - !ruby/object:Gem::Dependency
   name: debug
   requirement: !ruby/object:Gem::Requirement
@@ -95,6 +137,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
 - !ruby/object:Gem::Dependency
   name: standard
   requirement: !ruby/object:Gem::Requirement
@@ -125,7 +195,9 @@ files:
 - lib/downstream/pubsub_adapters/stateless/pubsub.rb
 - lib/downstream/pubsub_adapters/stateless/subscriber.rb
 - lib/downstream/rspec.rb
+- lib/downstream/rspec/have_enqueued_async_subscriber_for.rb
 - lib/downstream/rspec/have_published_event.rb
+- lib/downstream/subscriber_job.rb
 - lib/downstream/version.rb
 homepage: https://github.com/bibendi/downstream
 licenses:
@@ -147,7 +219,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
+rubygems_version: 3.2.32
 signing_key:
 specification_version: 4
 summary: Straightforward way to implement communication between Rails Engines using