omnes 0.1.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 68a21237b0a6749b982b68b732e134e79198654e92bc92824053c103280dd2bc
-  data.tar.gz: a282239e0f4eb501e3eb113066f1753ebfc859364cddbf07fc9200efbcad6bad
+  metadata.gz: 4d69bcb6ece79550d662ea1ed7cf734cc47940a39d432c58c849f8c15415472a
+  data.tar.gz: 459ff5514f310cc52492bb2fabc6bf8786e3a9119f760288aeef6329b609b4d3
 SHA512:
-  metadata.gz: 929b7a25696e1eaeb3ece983d46ccada028530f859483ebf80a65ce0b603360696a7b8304dfb8d801d543f26206024163154baa6223991a79f06fa58329cf2eb
-  data.tar.gz: fe5a4306002b44153992db90f13c54b76b211cfb7eb22975dfe2eb01a8fafd04bd7421dad414e2f82b38c5af00b0c466f52a624f0c0ce27f3ac1e7e711dbb382
+  metadata.gz: f395f3f775f8c44d54e17ad8502b0bf40c201edd861170242ac1ab29db90c2ace38273aceea5a257ed5e2910dcaca43370feec8e9563090847febe039ce99805
+  data.tar.gz: d2be4901c0fcc8bdd7bd8f1a1887c32445877300f1bf46f1396e7c16312c221f9c295fef1ee58756320a1be20c69f2a0e4dc4d0048451043998f51d89bb2c68c

data/.github/workflows/test.yml

@@ -12,7 +12,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        ruby-version: ['2.7', '3.0', '3.1']
+        ruby-version: ['2.5', '2.6', '2.7', '3.0', '3.1']
 
     steps:
     - name: Checkout repository

data/.gitignore

@@ -6,6 +6,7 @@
 /pkg/
 /spec/reports/
 /tmp/
+Gemfile.lock
 
 # rspec failure tracking
 .rspec_status

data/.rubocop.yml

@@ -1,5 +1,5 @@
 AllCops:
-  TargetRubyVersion: 2.7
+  TargetRubyVersion: 2.5
   NewCops: enable
   SuggestExtensions: false
 
@@ -29,7 +29,7 @@ Layout/LineLength:
   Max: 120
 
 Naming/MethodName:
-  IgnoredPatterns:
+  AllowedPatterns:
     - '.*Type'
 
 Lint/ConstantDefinitionInBlock:

data/CHANGELOG.md

@@ -6,6 +6,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.2] - 2022-05-03
+
+### Added
+- Support Ruby 2.5 & 2.6 [#6](https://github.com/nebulab/omnes/pull/6).
+
+## [0.2.1] - 2022-04-19
+
+### Added
+- Added `Omnes::Bus#clear` for autoloading [#4](https://github.com/nebulab/omnes/pull/4).
+
+### Changed
+- Fix re-adding autodiscovered subscriptions on subsequent calls [#5](https://github.com/nebulab/omnes/pull/5).
+
+## [0.2.0] - 2022-04-15
+
+### Added
+- Be able to fetch subscriptions by id from the bus [#1](https://github.com/nebulab/omnes/pull/1).
+- Use ad-hoc configuration system (and make Omnes zero-deps) [#2](https://github.com/nebulab/omnes/pull/2).
+- Bind a publication context to subscriptions [#3](https://github.com/nebulab/omnes/pull/3).
+
 ## [0.1.0] - 2022-03-23
 
-[Unreleased]: https://github.com/nebulab/omnes/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/nebulab/omnes/compare/v0.2.2...HEAD
+[0.2.1]: https://github.com/nebulab/omnes/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/nebulab/omnes/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/nebulab/omnes/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/nebulab/omnes/releases/tag/v0.1.0

data/README.md

@@ -37,7 +37,7 @@ The following examples will use the direct `Omnes::Bus` instance. The only
 difference for the mixing use case is that the methods are directly called in
 the including instance.
 
-### Registering events
+## Registering events
 
 Before being able to work with a given event, its name (which must be a
 `Symbol`) must be registered:
@@ -46,9 +46,9 @@ Before being able to work with a given event, its name (which must be a
 bus.register(:order_created)
 ```
 
-### Publishing events
+## Publishing events
 
-An event can be anything responding to a method `:name`, which must match with a
+An event can be anything responding to a method `:omnes_event_name`, which must match with a
 registered name.
 
 Typically, there're two main ways to generate events.
@@ -73,8 +73,7 @@ features, such as event persistence, can't be reliably built on top of them.
 
 You can also publish an instance of a class including
 [`Omnes::Event`](lib/omnes/event.rb). The only fancy thing it provides is an
-OOTB event name generated based on the class name. In fact, you can use
-anything responding to `#omnes_event_name`.
+OOTB event name generated based on the class name.
 
 ```ruby
 class OrderCreatedEvent
@@ -105,7 +104,7 @@ Omnes.config.event.name_builder = event_name_as_class
 Instance-backed events provide a well-defined structure, and other features,
 like event persistence, can be added on top of them.
 
-### Subscribing to events
+## Subscribing to events
 
 You can subscribe to a specific event to run some code whenever it's published.
 The event is yielded to the subscription block:
@@ -150,7 +149,7 @@ bus.subscribe(:order_created, OrderCreationEmailSubscription.new)
 However, see [Event subscribers](#event-subscribers) section bellow for a more powerful way
 to define standalone event handlers.
 
-#### Global subscriptions
+### Global subscriptions
 
 You can also create a subscription that will run for all events:
 
@@ -163,27 +162,43 @@ class LogEventsSubscription
   end
   
   def call(event)
-    logger.info("Event #{event.name} published")
+    logger.info("Event #{event.omnes_event_name} published")
   end
 end
 
 bus.subscribe_to_all(LogEventsSubscription.new)
 ```
 
-#### Custom matcher subscriptions
+### Custom matcher subscriptions
 
 Custom event matchers can be defined. A matcher is something responding to
 `#call` and taking the event as an argument. It must return `true` or `false`
 to match or ignore the event.
 
 ```ruby
-ORDER_EVENTS_MATCHER = ->(event) { event.name.start_with?(:order) }
+ORDER_EVENTS_MATCHER = ->(event) { event.omnes_event_name.start_with?(:order) }
 
 bus.subscribe_with_matcher(ORDER_EVENTS_MATCHER) do |event|
   # ...
 end
 ```
 
+### Referencing subscriptions
+
+For all subscription methods we've seen, an `Omnes::Subscription` instance is
+returned. Holding that reference can be useful for [debugging](#debugging) and
+[testing](#testing) purposes.
+
+Often though, you won't have the reference at hand when you need it.
+Thankfully, you can provide a subscription identifier on subscription time and
+use it later to fetch the subscription instance from the bus. A subscription
+identifier needs to be a `Symbol`:
+
+```ruby
+bus.subscribe(:order_created, OrderCreationEmailSubscription.new, id: :order_created_email)
+subscription = bus.subscription(:send_confirmation_email)
+```
+
 ## Event subscribers
 
 Events subscribers offer a way to define event subscriptions from a custom
@@ -207,7 +222,11 @@ class OrderCreationEmailSubscriber
     service.send(number: event.number, email: event.user_email)
   end
 end
+```
+
+You add the subscriptions by calling the `#subscribe_to` method on an instance:
 
+```ruby
 OrderCreationEmailSubscriber.new.subscribe_to(bus)
 ```
 
@@ -227,7 +246,7 @@ class LogEventsSubscriber
   end
 
   def log_event(event)
-    logger.info("Event #{event.name} published")
+    logger.info("Event #{event.omnes_event_name} published")
   end
 end
 ```
@@ -246,6 +265,21 @@ class OrderSubscriber
 end
 ```
 
+Likewise, you can provide [identifiers to reference
+subscriptions](#referencing-subscriptions):
+
+```ruby
+handle :order_created, with: :send_confirmation_email, id: :order_creation_email_subscriber
+```
+
+As you can subscribe multiple instances of a subscriber to the same bus, you
+might need to create a different identifier for each of them. For those cases,
+you can pass a lambda taking the subscriber instance:
+
+```ruby
+handle :order_created, with: :send_confirmation_email, id: ->(subscriber) { :"#{subscriber.id}_order_creation_email_subscriber" }
+```
+
 ### Autodiscovering event handlers
 
 You can let the event handlers to be automatically discovered.You need to
@@ -292,6 +326,12 @@ class OrderCreationEmailSubscriber
 end
 ```
 
+The strategy can also be globally set:
+
+```ruby
+Omnes.config.subscriber.autodiscover_strategy = AUTODISCOVER_STRATEGY
+```
+
 ### Adapters
 
 Subscribers are not limited to use a method as event handler. They can interact
@@ -389,7 +429,8 @@ Omnes.config.subscriber.adapter.active_job.serializer = :serialized_payload.to_p
 #### Custom adapters
 
 Custom adapters can be built. They need to implement a method `#call` taking
-the instance of `Omnes::Subscriber` and the event.
+the instance of `Omnes::Subscriber`, the event and, optionally, the publication
+context (see [debugging subscriptions](#subscription)).
 
 Here's a custom adapter executing a subscriber method in a different
 thread (we add an extra argument for the method name, and we partially apply it
@@ -402,7 +443,6 @@ end
 
 class OrderCreationEmailSubscriber
   include Omnes::Subscriber
-  include Sidekiq::Job
   
   handle :order_created, with: THREAD_ADAPTER.curry[:order_created]
   
@@ -413,8 +453,8 @@ end
 ```
 
 Alternatively, adapters can be curried and only take the instance as an
-argument, returning a one-argument callable taking the event. For instance, we
-could also have defined the thread adapter like this:
+argument, returning a callable taking the event. For instance, we could also
+have defined the thread adapter like this:
 
 ```ruby
 class ThreadAdapter
@@ -436,20 +476,29 @@ handle :order_created, with: ThreadAdapter.new(:order_created)
 # ...
 ```
 
-## Debugging
-
-### Unsubscribing
+## Unsubscribing & clearing
 
-When you create a subscription, an instance of
-[`Omnes::Subscription`](lib/omnes/subscription.rb) is returned (or an array for
-`Omnes::Subscriber`). It can be used to unsubscribe it in case you need to
-debug some behavior.
+You can unsubscribe a given subscription by passing its
+[reference](#referencing-subscriptions) to `Omnes::Bus#unsubscribe` (see how to
+[reference subscriptions](#referencing-subscriptions)):
 
 ```ruby
 subscription = bus.subscribe(:order_created, OrderCreationEmailSubscription.new)
 bus.unsubscribe(subscription)
 ```
 
+Sometimes you might need to leave your bus in a pristine state, with no events
+registered or active subscriptions. That can be useful for autoloading in
+development:
+
+```ruby
+bus.clear
+bus.registry.event_names # => []
+bus.subscriptions # => []
+```
+
+## Debugging
+
 ### Registration
 
 Whenever you register an event, you get back an [`Omnes::Registry::Registration`](lib/omnes/registry.rb)
@@ -478,10 +527,10 @@ When you publish an event, you get back an
 attributes that allow observing what happened:
 
 - `#event` contains the event instance that has been published.
-- `#caller_location` refers to the publication caller.
-- `#time` is the time stamp for the publication.
 - `#executions` contains an array of
   `Omnes::Execution`(lib/omnes/execution.rb). Read more below.
+- `#context` is an instance of
+  [`Omnes::PublicationContext`](lib/omnes/publication_context.rb).
   
 `Omnes::Execution` represents a subscription individual execution. It contains
 the following attributes:
@@ -491,6 +540,40 @@ the following attributes:
 - `#benchmark` of the operation.
 - `#time` is the time where the execution started.
 
+`Omnes::PublicationContext` represents the shared context for all triggered
+executions. See [Subscription][#subscription] for details.
+
+### Subscription
+
+If your subscription block or callable object takes a second argument, it'll
+contain an instance of an
+[`Omnes::PublicationContext`](lib/omnes/publication_context.rb). It allows you
+to inspect what triggered a given execution from within that execution code. It
+contains:
+
+- `#caller_location` refers to the publication caller.
+- `#time` is the time stamp for the publication.
+
+```ruby
+class OrderCreationEmailSubscriber
+  include Omnes::Subscriber
+  
+  handle :order_created, with: :send_confirmation_email
+
+  def send_confirmation_email(event, publication_context)
+    # debugging
+    abort(publication_context.caller_location.inspect)
+
+    OrderCreationEmail.send(number: event.number, email: event.user_email)
+  end
+end
+```
+
+In case you're developing your own async adapter, you can call `#serialized` on
+an instance of `Omnes::PublicationContext` to get a serialized version of it.
+It'll return a `Hash` with `"caller_location"` and `"time"` keys, and the
+respective `String` representations as values.
+
 ## Testing
 
 Ideally, you wouldn't need big setups to test your event-driven behavior. You
@@ -521,11 +604,30 @@ end
 bus.publish(:order_deleted, number: order.number) # `deletion_subscription` will run
 ```
 
-Remember that the array of created subscriptions is returned on `Omnes::Subscriber#subscribe_to`.
+Remember that you can get previous [subscription
+references](#referencing-subscriptions) thanks to
+subscription identifiers.
 
 There's also a specialized `Omnes::Bus#performing_nothing` method that runs no
 subscriptions for the duration of the block.
 
+## Configuration
+
+We've seen the relevant configurable settings in the corresponding sections.
+You can also access the configuration in the habitual block syntax:
+
+```ruby
+Omnes.configure do |config|
+  config.subscriber.adapter.sidekiq.serializer = :serialized_payload.to_proc
+end
+```
+
+Finally, nested settings can also be set directly from the affected class. E.g.:
+
+```ruby
+Omnes::Subscriber::Adapter::Sidekiq.config.serializer = :serialized_payload.to_proc
+```
+
 ## Recipes
 
 ### Rails
@@ -538,9 +640,14 @@ require "omnes"
 Omnes.config.subscriber.autodiscover = true
 
 Bus = Omnes::Bus.new
-Bus.register(:order_created)
 
-OrderCreationEmailSubscriber.new.subscribe_to(Bus)
+Rails.application.config.to_prepare do
+  Bus.clear
+
+  Bus.register(:order_created)
+
+  OrderCreationEmailSubscriber.new.subscribe_to(Bus)
+end
 ```
 
 We can define `OrderCreationEmailSubscriber` in

data/lib/omnes/bus.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "omnes/publication"
+require "omnes/publication_context"
 require "omnes/registry"
 require "omnes/subscription"
 require "omnes/unstructured_event"
@@ -22,8 +23,8 @@ module Omnes
   # bus.register(:foo)
   # ```
   #
-  # An event can be anything responding to a method `:name` which, needless to
-  # say, must match with a registered name.
+  # An event can be anything responding to a method `:omes_event_name` which,
+  # needless to say, must match with a registered name.
   #
   # Typically, there're two main ways to generate events.
   #
@@ -104,6 +105,21 @@ module Omnes
   #
   # bus.subscribe_with_matcher(matcher, MySubscription.new)
   # ```
+  #
+  # For all previous subscription methods, a subscription object is returned.
+  # You can supply a subscription id to it to be able to fetch it from the bus
+  # later on:
+  #
+  # ```
+  # subscription = bus.subscribe(:foo, MySubscription.new, id: :foo_sub)
+  # bus.subscription(:foo_sub) == subscription #=> true
+  # ```
+  #
+  # A subscription can be referenced when you want to unsubscribe:
+  #
+  # ```
+  # bus.unsubscribe(subscription)
+  # ```
   class Bus
     # @api private
     def self.EventType(value, **payload)
@@ -168,13 +184,13 @@ module Omnes
       publication_time = Time.now.utc
       event = self.class.EventType(event, **payload)
       registry.check_event_name(event.omnes_event_name)
-      executions = execute_subscriptions_for_event(event)
+      publication_context = PublicationContext.new(caller_location: caller_location, time: publication_time)
+      executions = execute_subscriptions_for_event(event, publication_context)
 
       Publication.new(
         event: event,
         executions: executions,
-        caller_location: caller_location,
-        time: publication_time
+        context: publication_context
       )
     end
 
@@ -182,37 +198,42 @@ module Omnes
     #
     # @param event_name [Symbol] Name of the event
     # @param callable [#call] Subscription callback taking the event
+    # @param id [Symbol] Unique identifier for the subscription
     # @yield [event] Subscription callback if callable is not given
     #
     # @return [Omnes::Subscription]
     #
     # @raise [Omnes::UnknownEventError] When event name has not been registered
-    def subscribe(event_name, callable = nil, &block)
+    def subscribe(event_name, callable = nil, id: Subscription.random_id, &block)
       registry.check_event_name(event_name)
 
-      subscribe_with_matcher(Subscription::SINGLE_EVENT_MATCHER.curry[event_name], callable, &block)
+      subscribe_with_matcher(Subscription::SINGLE_EVENT_MATCHER.curry[event_name], callable, id: id, &block)
     end
 
     # Adds a subscription for all events
     #
     # @param callable [#call] Subscription callback taking the event
+    # @param id [Symbol] Unique identifier for the subscription
     # @yield [event] Subscription callback if callable is not given
     #
     # @return [Omnes::Subscription]
-    def subscribe_to_all(callable = nil, &block)
-      subscribe_with_matcher(Subscription::ALL_EVENTS_MATCHER, callable, &block)
+    def subscribe_to_all(callable = nil, id: Subscription.random_id, &block)
+      subscribe_with_matcher(Subscription::ALL_EVENTS_MATCHER, callable, id: id, &block)
     end
 
     # Adds a subscription with given matcher
     #
     # @param matcher [#call] Callable taking the event and returning a boolean
     # @param callable [#call] Subscription callback taking the event
+    # @param id [Symbol] Unique identifier for the subscription
     # @yield [event] Subscription callback if callable is not given
     #
     # @return [Omnes::Subscription]
-    def subscribe_with_matcher(matcher, callable = nil, &block)
+    def subscribe_with_matcher(matcher, callable = nil, id: Subscription.random_id, &block)
+      raise DuplicateSubscriptionIdError.new(id: id, bus: self) if subscription(id)
+
       callback = callable || block
-      Subscription.new(matcher: matcher, callback: callback).tap do |subscription|
+      Subscription.new(matcher: matcher, callback: callback, id: id).tap do |subscription|
         @subscriptions << subscription
       end
     end
@@ -257,11 +278,32 @@ module Omnes
       performing_only(&block)
     end
 
+    # Fetch a subscription by its identifier
+    #
+    # @param id [Symbol] Subscription identifier
+    #
+    # @return [Omnes::Subscription]
+    def subscription(id)
+      subscriptions.find { |subscription| subscription.id == id }
+    end
+
+    # Clears all registered events and subscriptions
+    #
+    # Useful for code reloading.
+    #
+    # @return [Omnes::Bus]
+    def clear
+      tap do
+        @subscriptions = []
+        @registry = Registry.new
+      end
+    end
+
     private
 
-    def execute_subscriptions_for_event(event)
+    def execute_subscriptions_for_event(event, publication_context)
       subscriptions_for_event(event).map do |subscription|
-        subscription.(event)
+        subscription.(event, publication_context)
       end
     end
 

data/lib/omnes/configurable.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Omnes
+  # Ad-hoc configurable behavior for Omnes
+  #
+  # Example:
+  #
+  # ```
+  # Omnes.configure do |config|
+  #   config.event.name_builder = MY_NAME_BUILDER
+  # end
+  # ```
+  #
+  # or
+  #
+  # ```
+  # Omnes::Event.config.name_builder = MY_NAME_BUILDER
+  # ```
+  module Configurable
+    # Class where readers and writers are defined
+    class Config
+      # @api private
+      attr_reader :settings
+
+      # @api private
+      def initialize
+        @_mutex = Mutex.new
+        @settings = {}
+      end
+
+      # @api private
+      def add_setting(name, default)
+        @_mutex.synchronize do
+          @settings[name] = default
+          define_setting_reader(name)
+          define_setting_writter(name)
+        end
+      end
+
+      # @api private
+      def add_nesting(constant, name = default_nesting_name(constant))
+        @_mutex.synchronize do
+          define_nesting_reader(constant, name)
+        end
+      end
+
+      private
+
+      def define_setting_reader(name)
+        define_singleton_method(name) { @settings[name] }
+      end
+
+      def define_setting_writter(name)
+        define_singleton_method(:"#{name}=") do |value|
+          @_mutex.synchronize do
+            @settings[name] = value
+          end
+        end
+      end
+
+      def define_nesting_reader(constant, name)
+        define_singleton_method(name) { constant.config }
+      end
+    end
+
+    # @api private
+    def self.extended(klass)
+      klass.instance_variable_set(:@config, Config.new)
+    end
+
+    # Returns the configuration class
+    #
+    # Use this class to access readers and writers for the defined settings or
+    # nested configurations
+    #
+    # @return [Configurable::Config]
+    def config
+      @config
+    end
+
+    # Yields the configuration class
+    #
+    # @see #config
+    def configure
+      yield @config
+    end
+
+    # @api private
+    def setting(name, default:)
+      config.add_setting(name, default)
+    end
+
+    # @api private
+    def nest_config(constant, name: default_nesting_name(constant))
+      config.add_nesting(constant, name)
+    end
+
+    private
+
+    def default_nesting_name(constant)
+      constant.name
+              .split("::")
+              .last
+              .gsub(/([[:alpha:]])([[:upper:]])/, '\1_\2')
+              .downcase
+    end
+  end
+end

data/lib/omnes/errors.rb

@@ -18,7 +18,7 @@ module Omnes
     def default_message
       <<~MSG
         '#{event_name}' event is not registered.
-        #{suggestions_message}
+        #{suggestions_message if defined?(DidYouMean::PlainFormatter)}
 
         All known events are:
 
@@ -98,4 +98,42 @@ module Omnes
       MSG
     end
   end
+
+  # Raised when given subscription id is already in use
+  class DuplicateSubscriptionIdError < Error
+    attr_reader :id, :bus
+
+    def initialize(id:, bus:)
+      @id = id
+      @bus = bus
+      super(default_message)
+    end
+
+    private
+
+    def default_message
+      <<~MSG
+        #{id} has already been used as a subscription identifier
+      MSG
+    end
+  end
+
+  # Raised when trying to set an invalid subscription identifier
+  class InvalidSubscriptionNameError < Error
+    attr_reader :id
+
+    def initialize(id:)
+      @id = id
+      super(default_message)
+    end
+
+    private
+
+    def default_message
+      <<~MSG
+        #{id.inspect} is not a valid subscription identifier. Only symbols are
+        #allowed.
+      MSG
+    end
+  end
 end