ruby_event_store 0.30.0 → 0.31.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4df1be4d7e983bb77d1c069496cdca690f72d593a0c0d83f9d3d7519d63ed115
-  data.tar.gz: 0d156019cb436a9fb262b680e3e46d007d7c64ec46f1186bae82c5e4344b03c8
+  metadata.gz: 7bc6504270eee043e23b424f0aa08bb484d857629f28bda3332f1a7ba68afcef
+  data.tar.gz: 1088258a8ac91e24006ef5f9b12422a12bfaed0b00e264047b84fecafd060966
 SHA512:
-  metadata.gz: 490e25c72237a78d241df447ad97d55f2d245d40ea4d3b7665b5c699e5273d3b8257f06d2a0a3a1d8d3bc0940158819f433d72b47460620a5c4ed756fad5d646
-  data.tar.gz: 4355818327a762070c48a8121728c9914b74881187f028c8dc8c440d46c9b51556621b5fb697cdbbd97fc93c3eaff03cafa69fefa6d84f6655023cb053336ae4
+  metadata.gz: d0ed208c9c47f2fdac29afa6206ae5d0d4eaeb3095abc416ed77239ab05d9b3b203181dd6cb88e3ad87e1c85c919785b56ecea1532c1e2fefb75e2c6d630531d
+  data.tar.gz: c4d92331c73f56c91ad6016407031e2407874589b0421d8cc9b0472d7f5bdbcac8b2e11579e00f8b7ae05f43ac554b8d92d892e7e12b78d88899c10ed6eb3b36

data/Makefile

@@ -15,7 +15,12 @@ IGNORE      = RubyEventStore.const_missing \
               RubyEventStore::Client\#read_events_forward \
               RubyEventStore::Client\#read_events_backward \
               RubyEventStore::DeprecatedReadAPIRunner* \
-              RubyEventStore::DeprecatedReadAPIRewriter*
+              RubyEventStore::DeprecatedReadAPIRewriter* \
+              RubyEventStore::Client\#publish_event \
+              RubyEventStore::Client\#publish_events \
+              RubyEventStore::Client\#link_to_stream \
+              RubyEventStore::Client\#append_to_stream \
+
 SUBJECT     ?= RubyEventStore*
 
 install: ## Install gem dependencies

data/lib/ruby_event_store.rb

@@ -1,4 +1,5 @@
 require 'ruby_event_store/pub_sub/dispatcher'
+require 'ruby_event_store/pub_sub/subscriptions'
 require 'ruby_event_store/pub_sub/broker'
 require 'ruby_event_store/in_memory_repository'
 require 'ruby_event_store/projection'
@@ -16,4 +17,8 @@ require 'ruby_event_store/mappers/default'
 require 'ruby_event_store/mappers/protobuf'
 require 'ruby_event_store/mappers/null_mapper'
 require 'ruby_event_store/batch_enumerator'
+require 'ruby_event_store/correlated_commands'
+require 'ruby_event_store/link_by_metadata'
+require 'ruby_event_store/async_proxy_strategy'
+require 'ruby_event_store/async_dispatcher'
 require 'ruby_event_store/version'

data/lib/ruby_event_store/async_dispatcher.rb

@@ -0,0 +1,20 @@
+module RubyEventStore
+  class AsyncDispatcher < PubSub::Dispatcher
+    def initialize(proxy_strategy: AsyncProxyStrategy::Inline.new, scheduler:)
+      @async_proxy_strategy = proxy_strategy
+      @scheduler = scheduler
+    end
+
+    def call(subscriber, _, serialized_event)
+      if @scheduler.async_handler?(subscriber)
+        @async_proxy_strategy.call(->{ @scheduler.call(subscriber, serialized_event) })
+      else
+        super
+      end
+    end
+
+    def verify(subscriber)
+      super unless @scheduler.async_handler?(subscriber)
+    end
+  end
+end

data/lib/ruby_event_store/async_proxy_strategy.rb

@@ -0,0 +1,9 @@
+module RubyEventStore
+  module AsyncProxyStrategy
+    class Inline
+      def call(schedule_proc)
+        schedule_proc.call
+      end
+    end
+  end
+end

data/lib/ruby_event_store/client.rb

@@ -1,49 +1,118 @@
+require 'concurrent'
+
 module RubyEventStore
   class Client
+
     def initialize(repository:,
                    mapper: Mappers::Default.new,
-                   event_broker:  PubSub::Broker.new,
+                   subscriptions: PubSub::Subscriptions.new,
+                   dispatcher: PubSub::Dispatcher.new,
                    page_size: PAGE_SIZE,
-                   metadata_proc: nil,
                    clock: ->{ Time.now.utc })
       @repository     = repository
       @mapper         = mapper
-      @event_broker   = event_broker
+      @broker         = PubSub::Broker.new(subscriptions: subscriptions, dispatcher: dispatcher)
       @page_size      = page_size
-      warn "`RubyEventStore::Client#metadata_proc` has been deprecated. Use `RubyEventStore::Client#with_metadata` instead." if metadata_proc
-      @metadata_proc  = metadata_proc
       @clock          = clock
+      @metadata       = Concurrent::ThreadLocalVar.new
     end
 
-    def publish_events(events, stream_name: GLOBAL_STREAM, expected_version: :any)
-      append_to_stream(events, stream_name: stream_name, expected_version: expected_version)
-      events.each do |ev|
-        event_broker.notify_subscribers(ev)
+
+    # Persists events and notifies subscribed handlers about them
+    #
+    # @param events [Array<Event, Proto>, Event, Proto] event(s)
+    # @param stream_name [String] name of the stream for persisting events.
+    # @param expected_version [:any, :auto, :none, Integer] controls optimistic locking strategy. {http://railseventstore.org/docs/expected_version/ Read more}
+    # @return [:ok]
+    def publish(events, stream_name: GLOBAL_STREAM, expected_version: :any)
+      enriched_events = enrich_events_metadata(events)
+      serialized_events = serialize_events(enriched_events)
+      append_to_stream_serialized_events(serialized_events, stream_name: stream_name, expected_version: expected_version)
+      enriched_events.zip(serialized_events) do |event, serialized_event|
+        with_metadata(
+          correlation_id: event.metadata[:correlation_id] || event.event_id,
+          causation_id:   event.event_id,
+        ) do
+          broker.(event, serialized_event)
+        end
       end
       :ok
     end
 
+    # @deprecated Use {#publish} instead
+    def publish_events(events, stream_name: GLOBAL_STREAM, expected_version: :any)
+      warn <<~EOW
+        RubyEventStore::Client#publish_events has been deprecated.
+
+        Use RubyEventStore::Client#publish instead
+      EOW
+      publish(events, stream_name: stream_name, expected_version: expected_version)
+    end
+
+    # @deprecated Use {#publish} instead
     def publish_event(event, stream_name: GLOBAL_STREAM, expected_version: :any)
-      publish_events([event], stream_name: stream_name, expected_version: expected_version)
+      warn <<~EOW
+        RubyEventStore::Client#publish_event has been deprecated.
+
+        Use RubyEventStore::Client#publish instead
+      EOW
+      publish(event, stream_name: stream_name, expected_version: expected_version)
     end
 
+    # @deprecated Use {#append} instead
     def append_to_stream(events, stream_name: GLOBAL_STREAM, expected_version: :any)
-      events = normalize_to_array(events)
-      events.each{|event| enrich_event_metadata(event) }
-      repository.append_to_stream(serialized_events(events), Stream.new(stream_name), ExpectedVersion.new(expected_version))
+      warn <<~EOW
+        RubyEventStore::Client#append_to_stream has been deprecated.
+
+        Use RubyEventStore::Client#append instead
+      EOW
+      append(events, stream_name: stream_name, expected_version: expected_version)
+    end
+
+    # Persists new event(s) without notifying any subscribed handlers
+    #
+    # @param (see #publish)
+    # @return [:ok]
+    def append(events, stream_name: GLOBAL_STREAM, expected_version: :any)
+      serialized_events = serialize_events(enrich_events_metadata(events))
+      append_to_stream_serialized_events(serialized_events, stream_name: stream_name, expected_version: expected_version)
       :ok
     end
 
-    def link_to_stream(event_ids, stream_name:, expected_version: :any)
+    # Links already persisted event(s) to a different stream.
+    # Does not notify any subscribed handlers.
+    #
+    # @param event_ids [String, Array<String>] ids of events
+    # @param stream_name (see #publish)
+    # @param expected_version (see #publish)
+    # @return [self]
+    def link(event_ids, stream_name:, expected_version: :any)
       repository.link_to_stream(event_ids, Stream.new(stream_name), ExpectedVersion.new(expected_version))
       self
     end
 
+    # @deprecated Use {#link} instead
+    def link_to_stream(event_ids, stream_name:, expected_version: :any)
+      warn <<~EOW
+        RubyEventStore::Client#link_to_stream has been deprecated.
+
+        Use RubyEventStore::Client#link instead
+      EOW
+      link(event_ids, stream_name: stream_name, expected_version: expected_version)
+    end
+
+    # Deletes a stream.
+    # All events from the stream remain intact but they are no
+    # longer linked to the stream.
+    #
+    # @param stream_name [String] name of the stream to be cleared.
+    # @return [:ok]
     def delete_stream(stream_name)
       repository.delete_stream(Stream.new(stream_name))
       :ok
     end
 
+    # @deprecated Use {#read} instead. {https://github.com/RailsEventStore/rails_event_store/releases/tag/v0.30.0 More info}
     def read_events_forward(stream_name, start: :head, count: page_size)
       warn <<~EOW
         RubyEventStore::Client#read_events_forward has been deprecated.
@@ -54,6 +123,7 @@ module RubyEventStore
       read.stream(stream_name).limit(count).from(start).each.to_a
     end
 
+    # @deprecated Use {#read} instead. {https://github.com/RailsEventStore/rails_event_store/releases/tag/v0.30.0 More info}
     def read_events_backward(stream_name, start: :head, count: page_size)
       warn <<~EOW
         RubyEventStore::Client#read_events_backward has been deprecated.
@@ -64,6 +134,7 @@ module RubyEventStore
       read.stream(stream_name).limit(count).from(start).backward.each.to_a
     end
 
+    # @deprecated Use {#read} instead. {https://github.com/RailsEventStore/rails_event_store/releases/tag/v0.30.0 More info}
     def read_stream_events_forward(stream_name)
       warn <<~EOW
         RubyEventStore::Client#read_stream_events_forward has been deprecated.
@@ -74,6 +145,7 @@ module RubyEventStore
       read.stream(stream_name).each.to_a
     end
 
+    # @deprecated Use {#read} instead. {https://github.com/RailsEventStore/rails_event_store/releases/tag/v0.30.0 More info}
     def read_stream_events_backward(stream_name)
       warn <<~EOW
         RubyEventStore::Client#read_stream_events_backward has been deprecated.
@@ -84,6 +156,7 @@ module RubyEventStore
       read.stream(stream_name).backward.each.to_a
     end
 
+    # @deprecated Use {#read} instead. {https://github.com/RailsEventStore/rails_event_store/releases/tag/v0.30.0 More info}
     def read_all_streams_forward(start: :head, count: page_size)
       warn <<~EOW
         RubyEventStore::Client#read_all_streams_forward has been deprecated.
@@ -94,6 +167,7 @@ module RubyEventStore
       read.limit(count).from(start).each.to_a
     end
 
+    # @deprecated Use {#read} instead. {https://github.com/RailsEventStore/rails_event_store/releases/tag/v0.30.0 More info}
     def read_all_streams_backward(start: :head, count: page_size)
       warn <<~EOW
         RubyEventStore::Client#read_all_streams_backward has been deprecated.
@@ -104,70 +178,125 @@ module RubyEventStore
       read.limit(count).from(start).backward.each.to_a
     end
 
+    # Returns a single, persisted event based on its ID.
+    #
+    # @param event_id [String] event id
+    # @return [Event, Proto]
     def read_event(event_id)
       deserialize_event(repository.read_event(event_id))
     end
 
+    # Starts building a query specification for reading events.
+    # {http://railseventstore.org/docs/read/ More info.}
+    #
+    # @return [Specification]
     def read
       Specification.new(repository, mapper)
     end
 
-    # subscribe(subscriber, to:)
-    # subscribe(to:, &subscriber)
+    # Subscribes a handler (subscriber) that will be invoked for published events of provided type.
+    #
+    # @overload subscribe(subscriber, to:)
+    #   @param to [Array<Class>] types of events to subscribe
+    #   @param subscriber [Object, Class] handler
+    #   @return [Proc] - unsubscribe proc. Call to unsubscribe.
+    #   @raise [ArgumentError, SubscriberNotExist]
+    # @overload subscribe(to:, &subscriber)
+    #   @param to [Array<Class>] types of events to subscribe
+    #   @param subscriber [Proc] handler
+    #   @return [Proc] - unsubscribe proc. Call to unsubscribe.
+    #   @raise [ArgumentError, SubscriberNotExist]
     def subscribe(subscriber = nil, to:, &proc)
       raise ArgumentError, "subscriber must be first argument or block, cannot be both" if subscriber && proc
-      raise SubscriberNotExist, "subscriber must be first argument or block" unless subscriber || proc
       subscriber ||= proc
-      event_broker.add_subscriber(subscriber, to)
+      broker.add_subscription(subscriber, to)
     end
 
-    # subscribe_to_all_events(subscriber)
-    # subscribe_to_all_events(&subscriber)
+    # Subscribes a handler (subscriber) that will be invoked for all published events
+    #
+    # @overload subscribe_to_all_events(subscriber)
+    #   @param subscriber [Object, Class] handler
+    #   @return [Proc] - unsubscribe proc. Call to unsubscribe.
+    #   @raise [ArgumentError, SubscriberNotExist]
+    # @overload subscribe_to_all_events(&subscriber)
+    #   @param subscriber [Proc] handler
+    #   @return [Proc] - unsubscribe proc. Call to unsubscribe.
+    #   @raise [ArgumentError, SubscriberNotExist]
     def subscribe_to_all_events(subscriber = nil, &proc)
       raise ArgumentError, "subscriber must be first argument or block, cannot be both" if subscriber && proc
-      raise SubscriberNotExist, "subscriber must be first argument or block" unless subscriber || proc
-      event_broker.add_global_subscriber(subscriber || proc)
+      broker.add_global_subscription(subscriber || proc)
     end
 
+    # Builder object for collecting temporary handlers (subscribers)
+    # which are active only during the invocation of the provided
+    # block of code.
     class Within
-      def initialize(block, event_broker)
+      def initialize(block, broker)
         @block = block
-        @event_broker = event_broker
+        @broker = broker
         @global_subscribers = []
         @subscribers = Hash.new {[]}
       end
 
+      # Subscribes temporary handlers that
+      # will be called for all published events.
+      # The subscription is active only during the invocation
+      # of the block of code provided to {Client#within}.
+      # {http://railseventstore.org/docs/subscribe/#temporary-subscriptions Read more.}
+      #
+      # @param handlers [Object, Class] handlers passed as objects or classes
+      # @param handler2 [Proc] handler passed as proc
+      # @return [self]
       def subscribe_to_all_events(*handlers, &handler2)
         handlers << handler2 if handler2
         @global_subscribers += handlers
         self
       end
 
+      # Subscribes temporary handlers that
+      # will be called for published events of provided type.
+      # The subscription is active only during the invocation
+      # of the block of code provided to {Client#within}.
+      # {http://railseventstore.org/docs/subscribe/#temporary-subscriptions Read more.}
+      #
+      # @overload subscribe(handler, to:)
+      #   @param handler [Object, Class] handler passed as objects or classes
+      #   @param to [Array<Class>] types of events to subscribe
+      #   @return [self]
+      # @overload subscribe(to:, &handler)
+      #   @param to [Array<Class>] types of events to subscribe
+      #   @param handler [Proc] handler passed as proc
+      #   @return [self]
       def subscribe(handler=nil, to:, &handler2)
         raise ArgumentError if handler && handler2
         @subscribers[handler || handler2] += normalize_to_array(to)
         self
       end
 
+      # Invokes the block of code provided to {Client#within}
+      # and then unsubscribes temporary handlers.
+      # {http://railseventstore.org/docs/subscribe/#temporary-subscriptions Read more.}
+      #
+      # @return [Object] value returned by the invoked block of code
       def call
         unsubs  = add_thread_global_subscribers
         unsubs += add_thread_subscribers
         @block.call
       ensure
-        unsubs.each(&:call)
+        unsubs.each(&:call) if unsubs
       end
 
       private
 
       def add_thread_subscribers
-        @subscribers.map do |handler, types|
-          @event_broker.add_thread_subscriber(handler, types)
+        @subscribers.map do |subscriber, types|
+          @broker.add_thread_subscription(subscriber, types)
         end
       end
 
       def add_thread_global_subscribers
-        @global_subscribers.map do |s|
-          @event_broker.add_thread_global_subscriber(s)
+        @global_subscribers.map do |subscriber|
+          @broker.add_thread_global_subscription(subscriber)
         end
       end
 
@@ -176,22 +305,52 @@ module RubyEventStore
       end
     end
 
+    # Use for starting temporary subscriptions.
+    # {http://railseventstore.org/docs/subscribe/#temporary-subscriptions Read more}
+    #
+    # @param block [Proc] block of code during which the temporary subscriptions will be active
+    # @return [Within] builder object which collects temporary subscriptions
     def within(&block)
       raise ArgumentError if block.nil?
-      Within.new(block, event_broker)
+      Within.new(block, broker)
     end
 
+    # Set additional metadata for all events published within the provided block
+    # {http://railseventstore.org/docs/request_metadata#passing-your-own-metadata-using-with_metadata-method Read more}
+    #
+    # @param metadata [Hash] metadata to set for events
+    # @param block [Proc] block of code during which the metadata will be added
+    # @return [Object] last value returned by the provided block
     def with_metadata(metadata, &block)
       previous_metadata = metadata()
-      self.metadata = (previous_metadata || {}).merge(metadata)
+      self.metadata = previous_metadata.merge(metadata)
       block.call if block_given?
     ensure
       self.metadata = previous_metadata
     end
 
+    # Deserialize event which was serialized for async event handlers
+    # {http://railseventstore.org/docs/subscribe/#async-handlers Read more}
+    #
+    # @return [Event, Proto] deserialized event
+    def deserialize(event_type:, event_id:, data:, metadata:)
+      mapper.serialized_record_to_event(SerializedRecord.new(event_type: event_type, event_id: event_id, data: data, metadata: metadata))
+    end
+
+    # Read additional metadata which will be added for published events
+    # {http://railseventstore.org/docs/request_metadata#passing-your-own-metadata-using-with_metadata-method Read more}
+    #
+    # @return [Hash]
+    def metadata
+      @metadata.value || EMPTY_HASH
+    end
+
+    EMPTY_HASH = {}.freeze
+    private_constant :EMPTY_HASH
+
     private
 
-    def serialized_events(events)
+    def serialize_events(events)
       events.map do |ev|
         mapper.event_to_serialized_record(ev)
       end
@@ -205,27 +364,27 @@ module RubyEventStore
       return *events
     end
 
+    def enrich_events_metadata(events)
+      events = normalize_to_array(events)
+      events.each{|event| enrich_event_metadata(event) }
+      events
+    end
+
     def enrich_event_metadata(event)
-      if metadata_proc
-        md = metadata_proc.call || {}
-        md.each{|k,v| event.metadata[k]=(v) }
-      end
-      if metadata
-        metadata.each { |key, value| event.metadata[key] = value }
-      end
+      metadata.each { |key, value| event.metadata[key] ||= value }
       event.metadata[:timestamp] ||= clock.call
     end
 
-    attr_reader :repository, :mapper, :event_broker, :clock, :metadata_proc, :page_size
+    def append_to_stream_serialized_events(serialized_events, stream_name:, expected_version:)
+      repository.append_to_stream(serialized_events, Stream.new(stream_name), ExpectedVersion.new(expected_version))
+    end
 
     protected
 
-    def metadata
-      Thread.current["ruby_event_store_#{hash}"]
-    end
-
     def metadata=(value)
-      Thread.current["ruby_event_store_#{hash}"] = value
+      @metadata.value = value
     end
+
+    attr_reader :repository, :mapper, :broker, :clock, :page_size
   end
 end