downstream 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 44d7614f5509bb04efddc18f5dd26f4030a4262c00e6a370da13797d1efd99a6
+  data.tar.gz: 8ea205b3d718e21b01a82cb65b51ae1870068f1065f679af4e4fe94bcdebe87a
+SHA512:
+  metadata.gz: 5376229dc224f18496764928e4019bd72791ac660bc90f975abba38fe961e305dd9e6d997573aae7ef9acd3b785659ff9171678d2ccd1dd02f89add6fa5b01cb
+  data.tar.gz: f5a17a4a6f8383b35820914cc658fe97a41b2554df16c2088dcac3857af264e7976c5af3ab5249635e884de1ffe590dd32d270583230e79fa63ad09b5ae5294e

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Michael Merkushin
+
+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,122 @@
+[![Gem Version](https://badge.fury.io/rb/downstream.svg)](https://badge.fury.io/rb/downstream)
+[![Build Status](https://github.com/bibendi/downstream/workflows/Ruby/badge.svg?branch=master)](https://github.com/bibendi/downstream/actions?query=branch%3Amaster)
+
+# 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.
+
+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.
+
+<a href="https://evilmartians.com/?utm_source=bibendi-downstream">
+<img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54"></a>
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+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.
+
+### Describe events
+
+Events are represented by _event classes_, which describe events payloads and identifiers:
+
+```ruby
+class ProfileCreated < Downstream::Event
+  # (optional)
+  # Event identifier is used for streaming events to subscribers.
+  # By default, identifier is equal to underscored class name.
+  # You don't need to specify identifier manually, only for backward compatibility when
+  # class name is changed.
+  self.identifier = "profile_created"
+
+  # Add attributes accessors
+  attributes :user
+end
+```
+
+Each event has predefined (_reserved_) fields:
+- `event_id` – unique event id
+- `type` – event type (=identifier)
+
+**NOTE:** events should be in the past tense and describe what happened (e.g. "ProfileCreated", "EventPublished", etc.).
+
+Events are stored in `app/events` folder.
+
+### Publish events
+
+To publish an event you must first create an instance of the event class and call `Downstream.publish` method:
+
+```ruby
+event = ProfileCompleted.new(user: user)
+
+# then publish the event
+Downstream.publish(event)
+```
+
+That's it! Your event has been stored and propagated.
+
+### Subscribe to events
+
+To subscribe a handler to an event you must use `Downstream.subscribe` method.
+
+You should do this in your app or engine initializer:
+
+```ruby
+# some/engine.rb
+
+initializer "my_engine.subscribe_to_events" do
+  # To make sure event store is initialized use load hook
+  # `store` == `Downstream`
+  ActiveSupport.on_load "downstream-events" do |store|
+    store.subscribe MyEventHandler, to: ProfileCreated
+
+    # anonymous handler (could only be synchronous)
+    store.subscribe(to: ProfileCreated) do |name, event|
+      # do something
+    end
+
+    # you can omit event if your subscriber follows the convention
+    # for example, the following subscriber would subscribe to
+    # ProfileCreated event
+    store.subscribe OnProfileCreated::DoThat
+  end
+end
+```
+
+**NOTE:** event handler **must** be a callable object.
+
+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`).
+
+## Testing
+
+You can test subscribers as normal Ruby objects.
+
+To test that a given subscriber exists, you can do the following:
+
+```ruby
+it "is subscribed to some event" do
+  allow(MySubscriberService).to receive(:call)
+
+  event = MyEvent.new(some: "data")
+
+  Downstream.publish event
+
+  expect(MySubscriberService).to have_received(:call).with(event)
+end
+```
+
+To test publishing use `have_published_event` matcher:
+
+```ruby
+expect { subject }.to have_published_event(ProfileCreated).with(user: user)
+```
+
+**NOTE:** `have_published_event` only supports block expectations.
+
+**NOTE 2** `with` modifier works like `have_attributes` matcher (not `contain_exactly`);

data/lib/downstream/config.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Downstream
+  class Config
+    attr_writer :namespace
+
+    def namespace
+      @namespace ||= "downstream-events"
+    end
+  end
+end

data/lib/downstream/engine.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module Downstream
+  class Engine < ::Rails::Engine
+    config.downstream = Downstream.config
+
+    config.to_prepare do
+      ActiveSupport.run_load_hooks("downstream-events", Downstream)
+    end
+  end
+end

data/lib/downstream/event.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Downstream
+  class Event
+    extend ActiveModel::Naming
+
+    RESERVED_ATTRIBUTES = %i[event_id type].freeze
+
+    class << self
+      attr_writer :identifier
+
+      def identifier
+        return @identifier if instance_variable_defined?(:@identifier)
+
+        @identifier = name.underscore.tr("/", ".")
+      end
+
+      # define store readers
+      def attributes(*fields)
+        fields.each do |field|
+          raise ArgumentError, "#{field} is reserved" if RESERVED_ATTRIBUTES.include?(field)
+
+          defined_attributes << field
+
+          # TODO: rewrite with define_method
+          class_eval <<~CODE, __FILE__, __LINE__ + 1
+            def #{field}
+              data[:#{field}]
+            end
+          CODE
+        end
+      end
+
+      def defined_attributes
+        return @defined_attributes if instance_variable_defined?(:@defined_attributes)
+
+        @defined_attributes =
+          if superclass.respond_to?(:defined_attributes)
+            superclass.defined_attributes.dup
+          else
+            []
+          end
+      end
+
+      def i18n_scope
+        :activemodel
+      end
+
+      def human_attribute_name(attr, options = {})
+        attr
+      end
+
+      def lookup_ancestors
+        [self]
+      end
+    end
+
+    attr_reader :event_id, :data, :errors
+
+    def initialize(event_id: nil, **params)
+      @event_id = event_id || SecureRandom.hex(10)
+      validate_attributes!(params)
+
+      @errors = ActiveModel::Errors.new(self)
+      @data = params
+    end
+
+    def type
+      self.class.identifier
+    end
+
+    def to_h
+      {
+        type: type,
+        event_id: event_id,
+        data: data
+      }
+    end
+
+    def inspect
+      "#{self.class.name}<#{type}##{event_id}>, data: #{data}"
+    end
+
+    def read_attribute_for_validation(attr)
+      data.fetch(attr)
+    end
+
+    private
+
+    def validate_attributes!(params)
+      unknown_fields = params.keys.map(&:to_sym) - self.class.defined_attributes
+      unless unknown_fields.empty?
+        raise ArgumentError, "Unknown event attributes: #{unknown_fields.join(", ")}"
+      end
+    end
+  end
+end

data/lib/downstream/rspec/have_published_event.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Downstream
+  class HavePublishedEvent < RSpec::Matchers::BuiltIn::BaseMatcher
+    attr_reader :event_class, :attributes
+
+    def initialize(event_class)
+      @event_class = event_class
+      set_expected_number(:exactly, 1)
+    end
+
+    def with(attributes)
+      @attributes = attributes
+      self
+    end
+
+    def exactly(count)
+      set_expected_number(:exactly, count)
+      self
+    end
+
+    def at_least(count)
+      set_expected_number(:at_least, count)
+      self
+    end
+
+    def at_most(count)
+      set_expected_number(:at_most, count)
+      self
+    end
+
+    def times
+      self
+    end
+
+    def once
+      exactly(:once)
+    end
+
+    def twice
+      exactly(:twice)
+    end
+
+    def thrice
+      exactly(:thrice)
+    end
+
+    def supports_block_expectations?
+      true
+    end
+
+    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, @unmatching_events =
+        events.partition do |actual_event|
+          (event_class.identifier == actual_event.type) &&
+            (attributes.nil? || attributes_match?(actual_event))
+        end
+
+      @matching_count = @matching_events.size
+
+      case @expectation_type
+      when :exactly then @expected_number == @matching_count
+      when :at_most then @expected_number >= @matching_count
+      when :at_least then @expected_number <= @matching_count
+      end
+    end
+
+    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
+      end
+    end
+
+    def failure_message_when_negated
+      "expected not to publish #{event_class.identifier} event"
+    end
+
+    private
+
+    def attributes_match?(event)
+      RSpec::Matchers::BuiltIn::HaveAttributes.new(attributes).matches?(event)
+    end
+
+    def set_expected_number(relativity, count)
+      @expectation_type = relativity
+      @expected_number =
+        case count
+        when :once then 1
+        when :twice then 2
+        when :thrice then 3
+        else Integer(count)
+        end
+    end
+
+    def message_expectation_modifier
+      number_modifier = @expected_number == 1 ? "once" : "#{@expected_number} times"
+      case @expectation_type
+      when :exactly then "exactly #{number_modifier}"
+      when :at_most then "at most #{number_modifier}"
+      when :at_least then "at least #{number_modifier}"
+      end
+    end
+  end
+end
+
+RSpec.configure do |config|
+  config.include(Module.new do
+    def have_published_event(*args)
+      Downstream::HavePublishedEvent.new(*args)
+    end
+  end)
+end

data/lib/downstream/rspec.rb

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

data/lib/downstream/version.rb

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

data/lib/downstream.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_model"
+
+require "downstream/config"
+require "downstream/event"
+require "downstream/rspec" if defined?(RSpec)
+
+module Downstream
+  class << self
+    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
+
+      subscriber ||= block if block
+
+      if subscriber.nil?
+        raise ArgumentError, "Subsriber must be present"
+      end
+
+      identifier =
+        if to.is_a?(Class) && Event >= to
+          to.identifier
+        else
+          to
+        end
+
+      ActiveSupport::Notifications.subscribe("#{config.namespace}.#{identifier}", subscriber)
+    end
+
+    # temporary subscriptions
+    def subscribed(subscriber, 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
+
+      identifier =
+        if to.is_a?(Class) && Event >= to
+          to.identifier
+        else
+          to
+        end
+
+      ActiveSupport::Notifications.subscribed(subscriber, "#{config.namespace}.#{identifier}", &block)
+    end
+
+    def publish(event)
+      ActiveSupport::Notifications.publish("#{config.namespace}.#{event.type}", event)
+    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
+        parts.shift if parts.first.empty?
+        # drop last part – it's a unique subscriber name
+        parts.pop
+
+        parts.last.sub!(/^On/, "")
+
+        parts.join("::")
+      end
+
+      event_class_name.safe_constantize
+    end
+  end
+end
+
+require "downstream/engine"

metadata

@@ -0,0 +1,152 @@
+--- !ruby/object:Gem::Specification
+name: downstream
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- merkushin.m.s@gmail.com
+- dementiev.vm@gmail.com
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2021-10-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5'
+- !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'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.16'
+- !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: 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: []
+files:
+- LICENSE.txt
+- README.md
+- lib/downstream.rb
+- lib/downstream/config.rb
+- lib/downstream/engine.rb
+- lib/downstream/event.rb
+- lib/downstream/rspec.rb
+- lib/downstream/rspec/have_published_event.rb
+- lib/downstream/version.rb
+homepage: https://github.com/bibendi/downstream
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.5'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.2
+signing_key:
+specification_version: 4
+summary: Straightforward way to implement communication between Rails Engines using
+  the Publish-Subscribe pattern
+test_files: []