downstream 1.5.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7596d3ccbd47d258c9b949be9674651c600b75276cd8e38a3bbc021e95ec6214
-  data.tar.gz: 8c7c3a0525f38c1a2e155153edca9d5edf39b646495dcc9815dd9181ca502987
+  metadata.gz: 6117947c15849270ac37c5d1a02877b5903884f224cb87bb10fca63f8535c0b1
+  data.tar.gz: 11fcc576683c11ed8bd56fd6f2abc22d7adfd56d39cd33162a41f706debebc0b
 SHA512:
-  metadata.gz: a02e6ffa1585f399a003750332bc4807bc1d50675f8a8d50968eb8e39de8a7589da82322225a2383d72416d6c2c5fe67aabb376c6df71e6b952579737b587054
-  data.tar.gz: 72223db631146986eeb611bd320bae2bf6fc2aa70dc23037a5a8bc820ad84a0015b1b888d51717fb706257ea2a241113552024dde565636adef1951d871286e7
+  metadata.gz: 8228d50071d6929e3ec64cdfe1a46c81a7a4045b043329044d731e746a7da0e4f1363a70420d04e5db1c5a66166bc8732245c1c10ccfcec4563ce382b277becc
+  data.tar.gz: 30e6fbf37793b809158a128db70cd24121d39ac83510ad024db68874d38485f5b576b9d9d1a4d5775092401ccc8f22dae66b7d557836065055da974922479f60

data/README.md

@@ -59,6 +59,22 @@ Each event has predefined (_reserved_) fields:
 
 Events are stored in `app/events` folder.
 
+You can also define events using the Data-interface:
+
+```ruby
+ProfileCreated = Downstream::Event.define(:user)
+
+# or with an explicit identifier
+ProfileCreated = Downstream::Event.define(:user) do
+  self.identifier = "user.profile_created"
+end
+```
+
+Date-events provide the same interface as regular events but use Data classes for keeping event payloads (`event.data`) and are frozen (as well as their derivatives, such as `event.to_h`).
+
+> [!NOTE]
+> Data-events are only available in Ruby 3.2+.
+
 ### Publish events
 
 To publish an event you must first create an instance of the event class and call `Downstream.publish` method:
@@ -127,6 +143,26 @@ store.subscribe OnProfileCreated::DoThat, async: {queue: :low_priority}
 
 **NOTE:** all subscribers are synchronous by default
 
+### Subscriber classes
+
+You can also use subscriber objects based on `Downstream::Subscriber` class. For example:
+
+```ruby
+class CRMSubscriber < Downstream::Subscriber
+  def profile_created(event)
+    # handle "profile_created" event
+  end
+
+  def project_created(event)
+    # handle "project_created" event
+  end
+end
+
+store.subscribe CRMSubscriber, async: true
+```
+
+The subscriber object allows you to subscribe to multiple events at once: each public method is considered an event handler for the same named event.
+
 ## Testing
 
 You can test subscribers as normal Ruby objects.
@@ -153,9 +189,9 @@ 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)
+  expect { Downstream.publish event }
+    .to have_enqueued_async_subscriber_for(MySubscriberService)
+    .with(event)
 end
 ```
 

data/lib/downstream/data_event.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Downstream
+  class DataEvent < Event
+    class << self
+      attr_writer :data_class
+
+      def data_class
+        return @data_class if @data_class
+
+        @data_class = superclass.data_class
+      end
+
+      undef_method :attributes
+      undef_method :defined_attributes
+    end
+
+    def initialize(event_id: nil, **attrs)
+      @event_id = event_id || SecureRandom.hex(10)
+      @data = self.class.data_class.new(**attrs)
+      freeze
+    end
+
+    def to_h
+      {
+        type:,
+        event_id:,
+        data: data.to_h.freeze
+      }.freeze
+    end
+  end
+end

data/lib/downstream/engine.rb

@@ -6,7 +6,21 @@ module Downstream
   class Engine < ::Rails::Engine
     config.downstream = Downstream.config
 
+    ::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
+
     config.to_prepare do
+      Downstream.pubsub.reset
       ActiveSupport.run_load_hooks("downstream-events", Downstream)
     end
   end

data/lib/downstream/event.rb

@@ -1,18 +1,5 @@
 # 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
@@ -26,7 +13,7 @@ module Downstream
       def identifier
         return @identifier if instance_variable_defined?(:@identifier)
 
-        @identifier = name.underscore.tr("/", ".")
+        @identifier = name.underscore.tr("/", ".").gsub(/_event$/, "")
       end
 
       # define store readers
@@ -56,6 +43,20 @@ module Downstream
           end
       end
 
+      def define(*fields, &)
+        fields.each do |field|
+          raise ArgumentError, "#{field} is reserved" if RESERVED_ATTRIBUTES.include?(field)
+        end
+
+        data_class = ::Data.define(*fields)
+
+        Class.new(DataEvent, &).tap do
+          _1.data_class = data_class
+
+          _1.delegate(*fields, to: :data)
+        end
+      end
+
       def i18n_scope
         :activemodel
       end
@@ -94,7 +95,7 @@ module Downstream
     end
 
     def to_global_id
-      new_data = data.each_with_object({}) do |(key, value), memo|
+      new_data = data.to_h.each_with_object({}) do |(key, value), memo|
         memo[key] = if value.respond_to?(:to_global_id)
           value.to_global_id
         else

data/lib/downstream/pubsub_adapters/abstract_pubsub.rb

@@ -2,6 +2,10 @@
 
 module Downstream
   class AbstractPubsub
+    def reset
+      raise NotImplementedError
+    end
+
     def subscribe(identifier, callable)
       raise NotImplementedError
     end

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

@@ -6,8 +6,20 @@ require_relative "subscriber"
 module Downstream
   module Stateless
     class Pubsub < AbstractPubsub
+      def initialize
+        @subscribers = []
+      end
+
+      def reset
+        @subscribers.each(&:unsubscribe)
+        @subscribers.clear
+      end
+
       def subscribe(identifier, callable, async: false)
-        Subscriber.new(callable, async: async).tap { |s| s.subscribe(identifier) }
+        Subscriber.new(callable, async: async).tap do |s|
+          s.subscribe(identifier)
+          @subscribers << s
+        end
       end
 
       def subscribed(identifier, callable, &block)

data/lib/downstream/rspec/have_published_event.rb

@@ -74,7 +74,7 @@ module Downstream
     end
 
     def failure_message
-      (+"expected to publish #{event_class.identifier} event").tap do |msg|
+      "expected to publish #{event_class.identifier} event".tap do |msg|
         msg << " #{message_expectation_modifier}, but haven't published"
       end
     end

data/lib/downstream/subscriber.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Downstream
+  class Subscriber
+    class << self
+      # All public names are considered event handlers
+      # (same concept as action_names in controllers/mailers)
+      def event_names
+        @event_names ||= begin
+          # All public instance methods of this class, including ancestors
+          methods = (public_instance_methods(true) -
+            # Except for public instance methods of Base and its ancestors
+            Downstream.public_instance_methods(true) +
+            # Be sure to include shadowed public instance methods of this class
+            public_instance_methods(false)).uniq.map(&:to_s)
+          methods.to_set
+        end
+      end
+
+      # Downstream subscriber interface
+      def call(event)
+        new.process_event(event)
+      end
+    end
+
+    def process_event(event)
+      # TODO: callbacks? instrumentation?
+      # TODO: namespaced events?
+      public_send(event.type, event)
+    end
+  end
+end

data/lib/downstream/version.rb

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

data/lib/downstream.rb

@@ -8,6 +8,8 @@ require "after_commit_everywhere"
 
 require "downstream/config"
 require "downstream/event"
+require "downstream/data_event"
+require "downstream/subscriber"
 require "downstream/pubsub_adapters/abstract_pubsub"
 require "downstream/subscriber_job"
 
@@ -27,18 +29,26 @@ module Downstream
       subscriber ||= block if block
       raise ArgumentError, "Subsriber must be present" if subscriber.nil?
 
-      identifier = construct_identifier(subscriber, to)
+      construct_identifiers(subscriber, to).map do
+        pubsub.subscribe(_1, subscriber, async: async)
+      end.then do
+        next _1.first if _1.size == 1
 
-      pubsub.subscribe(identifier, subscriber, async: async)
+        _1
+      end
     end
 
     # temporary subscriptions
     def subscribed(subscriber, to: nil, &block)
       raise ArgumentError, "Subsriber must be present" if subscriber.nil?
 
-      identifier = construct_identifier(subscriber, to)
+      construct_identifiers(subscriber, to).map do
+        pubsub.subscribed(_1, subscriber, &block)
+      end.then do
+        next _1.first if _1.size == 1
 
-      pubsub.subscribed(identifier, subscriber, &block)
+        _1
+      end
     end
 
     def publish(event)
@@ -47,28 +57,34 @@ module Downstream
 
     private
 
-    def construct_identifier(subscriber, to)
-      to ||= infer_event_from_subscriber(subscriber) if subscriber.is_a?(Module)
+    def construct_identifiers(subscriber, to)
+      to ||= infer_events_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
 
-      identifier = if to.is_a?(Class) && Event >= to # rubocop:disable Style/YodaCondition
-        to.identifier
-      else
-        to
-      end
+      Array(to).map do
+        identifier = if _1.is_a?(Class) && Event >= _1 # rubocop:disable Style/YodaCondition
+          _1.identifier
+        else
+          _1
+        end
 
-      "#{config.namespace}.#{identifier}"
+        "#{config.namespace}.#{identifier}"
+      end
     end
 
-    def infer_event_from_subscriber(subscriber)
+    def infer_events_from_subscriber(subscriber)
+      if subscriber.is_a?(Class) && Subscriber >= subscriber # rubocop:disable Style/YodaCondition
+        return subscriber.event_names
+      end
+
       event_class_name = subscriber.name.split("::").yield_self do |parts|
         # handle explicti top-level name, e.g. ::Some::Event
         parts.shift if parts.first.empty?
-        # drop last part – it's a unique subscriber name
+        # drop last part—it's a unique subscriber name
         parts.pop
 
         parts.last.sub!(/^On/, "")

metadata

@@ -1,15 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: downstream
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 2.0.0
 platform: ruby
 authors:
 - merkushin.m.s@gmail.com
 - dementiev.vm@gmail.com
-autorequire: 
-bindir: exe
+bindir: bin
 cert_chain: []
-date: 2024-04-26 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: after_commit_everywhere
@@ -45,28 +44,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6'
+        version: '7'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6'
-- !ruby/object:Gem::Dependency
-  name: appraisal
-  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'
+        version: '7'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -95,48 +80,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
-- !ruby/object:Gem::Dependency
-  name: debug
-  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: 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: rspec-rails
   requirement: !ruby/object:Gem::Requirement
@@ -151,36 +108,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '6.0'
-- !ruby/object:Gem::Dependency
-  name: sqlite3
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 1.4.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 1.4.0
-- !ruby/object:Gem::Dependency
-  name: standard
-  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'
-description: 
-email: 
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -189,6 +116,7 @@ files:
 - README.md
 - lib/downstream.rb
 - lib/downstream/config.rb
+- lib/downstream/data_event.rb
 - lib/downstream/engine.rb
 - lib/downstream/event.rb
 - lib/downstream/pubsub_adapters/abstract_pubsub.rb
@@ -197,14 +125,19 @@ files:
 - lib/downstream/rspec.rb
 - lib/downstream/rspec/have_enqueued_async_subscriber_for.rb
 - lib/downstream/rspec/have_published_event.rb
+- lib/downstream/subscriber.rb
 - lib/downstream/subscriber_job.rb
 - lib/downstream/version.rb
 homepage: https://github.com/palkan/downstream
 licenses:
 - MIT
 metadata:
+  bug_tracker_uri: http://github.com/palkan/downstream/issues
+  changelog_uri: https://github.com/palkan/downstream/blob/master/CHANGELOG.md
+  documentation_uri: http://github.com/palkan/downstream
+  homepage_uri: http://github.com/palkan/downstream
+  source_code_uri: http://github.com/palkan/downstream
   allowed_push_host: https://rubygems.org
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -212,15 +145,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.7'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
-signing_key: 
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Straightforward way to implement communication between Rails Engines using
   the Publish-Subscribe pattern