sequent 8.0.2 → 8.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 286e0bad8fae90e0442b711406e06744dd9b11bd761961886349368131fed005
-  data.tar.gz: 805cfede0b646d5aa0da4c4ccbb7a0e34af147bb43a60086c1829d2418a2e97c
+  metadata.gz: 5e7ff410ea483cffeb038904103ecad45b89c7f9907775362a18daf2a9a0a7e5
+  data.tar.gz: bcb33c8793653e31677e5883195dc0babc57c7259c8e4e76e7491f91272ee65f
 SHA512:
-  metadata.gz: 3966ba588ecb08107d2608a44af378e8698830a9f0001cb06bb001ed3536c17006911544ab6e3a7be520c9577ba0e5083ea17adc917c932ab58ab0cc9cb3ff03
-  data.tar.gz: 0f9fa0804ee084dfb0b3ab7144c52f53846019cdccbf95926a2be6b7f4b2d8e46b44e387c7a5084c09d49dfc48f7f550cd92aac8e5feb93c1a4de32268d299b8
+  metadata.gz: f5acb72e36e29fcf811734b8db7ee49b7a2e2cc915fafcc675636bfcd399e8961cf514c40d8312d59ea6c289379160ac3fd8f04f45c1cba7f529e6806ca3b415
+  data.tar.gz: 93fa973ab3fc2454bc49b2359e254733b9ca7a850f4c30b31a08a7d14b9cd7d72889d3386e1946bc85d18c16c4f5a326fa2198f7e5b6005e0eb55f320bdf993b

data/db/sequent_pgsql.sql

@@ -135,6 +135,7 @@ DECLARE
   _provided_events_partition_key aggregates.events_partition_key%TYPE;
   _events_partition_key aggregates.events_partition_key%TYPE;
   _snapshot_outdated_at aggregates_that_need_snapshots.snapshot_outdated_at%TYPE;
+  _unique_keys jsonb;
 BEGIN
   _command_id = store_command(_command);
 
@@ -159,12 +160,22 @@ BEGIN
    ORDER BY 1
       ON CONFLICT DO NOTHING;
 
+  FOR _aggregate IN SELECT row->0 FROM jsonb_array_elements(_aggregates_with_events) AS row LOOP
+    _aggregate_id = _aggregate->>'aggregate_id';
+    _unique_keys = COALESCE(_aggregate->'unique_keys', '{}'::jsonb);
+
+    DELETE FROM aggregate_unique_keys AS target
+     WHERE target.aggregate_id = _aggregate_id
+       AND NOT (_unique_keys ? target.scope);
+  END LOOP;
+
   FOR _aggregate, _events IN SELECT row->0, row->1 FROM jsonb_array_elements(_aggregates_with_events) AS row
                              ORDER BY row->0->'aggregate_id', row->1->0->'event_json'->'sequence_number'
   LOOP
     _aggregate_id = _aggregate->>'aggregate_id';
     _provided_events_partition_key = _aggregate->>'events_partition_key';
     _snapshot_outdated_at = _aggregate->>'snapshot_outdated_at';
+    _unique_keys = COALESCE(_aggregate->'unique_keys', '{}'::jsonb);
 
     SELECT * INTO _aggregate_row FROM aggregates WHERE aggregate_id = _aggregate_id;
     _events_partition_key = COALESCE(_provided_events_partition_key, _aggregate_row.events_partition_key, '');
@@ -179,6 +190,19 @@ BEGIN
       DO UPDATE SET events_partition_key = EXCLUDED.events_partition_key
               WHERE aggregates.events_partition_key IS DISTINCT FROM EXCLUDED.events_partition_key;
 
+    BEGIN
+      INSERT INTO aggregate_unique_keys AS target (aggregate_id, scope, key)
+      SELECT _aggregate_id, key, value
+        FROM jsonb_each(_unique_keys) AS x
+          ON CONFLICT (aggregate_id, scope) DO UPDATE
+         SET key = EXCLUDED.key
+       WHERE target.key <> EXCLUDED.key;
+    EXCEPTION
+      WHEN unique_violation THEN
+        RAISE unique_violation
+        USING MESSAGE = 'duplicate unique key value for aggregate ' || (_aggregate->>'aggregate_type') || ' ' || _aggregate_id || ' (' || SQLERRM || ')';
+    END;
+
     INSERT INTO events (partition_key, aggregate_id, sequence_number, created_at, command_id, event_type_id, event_json)
     SELECT _events_partition_key,
            _aggregate_id,

data/db/sequent_schema_indexes.sql

@@ -14,6 +14,11 @@ CREATE INDEX events_event_type_id_idx ON events (event_type_id);
 ALTER TABLE aggregates
   ADD FOREIGN KEY (aggregate_type_id) REFERENCES aggregate_types (id) ON UPDATE CASCADE;
 
+ALTER TABLE aggregate_unique_keys
+  ADD PRIMARY KEY (aggregate_id, scope),
+  ADD UNIQUE (scope, key),
+  ADD FOREIGN KEY (aggregate_id) REFERENCES aggregates (aggregate_id) ON UPDATE CASCADE ON DELETE CASCADE;
+
 ALTER TABLE events
   ADD FOREIGN KEY (partition_key, aggregate_id) REFERENCES aggregates (events_partition_key, aggregate_id)
           ON UPDATE CASCADE ON DELETE RESTRICT;

data/db/sequent_schema_tables.sql

@@ -25,6 +25,12 @@ CREATE TABLE aggregates (
     created_at timestamp with time zone NOT NULL DEFAULT NOW()
 ) PARTITION BY RANGE (aggregate_id);
 
+CREATE TABLE aggregate_unique_keys (
+    aggregate_id uuid NOT NULL,
+    scope text NOT NULL,
+    key jsonb NOT NULL
+);
+
 CREATE TABLE events (
   aggregate_id uuid NOT NULL,
   partition_key text NOT NULL DEFAULT '',

data/lib/sequent/core/aggregate_root.rb

@@ -3,6 +3,7 @@
 require 'base64'
 require_relative 'helpers/message_handler'
 require_relative 'helpers/autoset_attributes'
+require_relative 'helpers/unique_keys'
 require_relative 'stream_record'
 require_relative 'aggregate_roots'
 
@@ -37,6 +38,7 @@ module Sequent
     class AggregateRoot
       include Helpers::MessageHandler
       include Helpers::AutosetAttributes
+      include Helpers::UniqueKeys
       include SnapshotConfiguration
       extend ActiveSupport::DescendantsTracker
 
@@ -104,6 +106,7 @@ module Sequent
           aggregate_id: id,
           events_partition_key: events_partition_key,
           snapshot_outdated_at: snapshot_outdated? ? Time.now : nil,
+          unique_keys:,
         )
       end
 

data/lib/sequent/core/event_store.rb

@@ -9,6 +9,9 @@ require_relative 'snapshot_store'
 
 module Sequent
   module Core
+    class AggregateKeyNotUniqueError < RuntimeError
+    end
+
     class EventStore
       include Helpers::PgsqlHelpers
       include SnapshotStore
@@ -175,6 +178,29 @@ module Sequent
         record&.event_stream
       end
 
+      def position_mark
+        connection.exec_query('SELECT pg_current_snapshot()::text AS mark')[0]['mark']
+      end
+
+      def load_events_since_marked_position(mark)
+        events = connection.execute(
+          Sequent.configuration.event_record_class
+            .where(<<~SQL, {mark:})
+              xact_id >= pg_snapshot_xmin(CAST(:mark AS pg_snapshot))::text::bigint
+                AND NOT pg_visible_in_snapshot(xact_id::text::xid8, CAST(:mark AS pg_snapshot))
+            SQL
+            .select('*, pg_current_snapshot()::text AS mark')
+            .to_sql,
+        ).to_a
+
+        return [[], mark] if events.empty?
+
+        [
+          events.map { |hash| deserialize_event(hash) },
+          events[0]['mark'],
+        ]
+      end
+
       def permanently_delete_event_stream(aggregate_id)
         permanently_delete_event_streams([aggregate_id])
       end
@@ -250,8 +276,12 @@ module Sequent
             Sequent::Core::Oj.dump(events),
           ],
         )
-      rescue ActiveRecord::RecordNotUnique
-        raise OptimisticLockingError
+      rescue ActiveRecord::RecordNotUnique => e
+        if e.message =~ /duplicate unique key value for aggregate/
+          raise AggregateKeyNotUniqueError, e.message
+        else
+          raise OptimisticLockingError
+        end
       end
 
       def convert_timestamp(timestamp)

data/lib/sequent/core/helpers/unique_keys.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Sequent
+  module Core
+    module Helpers
+      # Some aggregates represent a unique external entity (e.g. a
+      # user's email address or login name) and this uniqueness needs
+      # to be enforced. For each unique key the returned object should
+      # have an entry where the key of the entry describes the scope
+      # of the constraint (e.g. `user_email` or `login_name`) and the
+      # value represents the unique value. Values can be any JSON
+      # value (string, object, array, etc). Note that uniqueness is
+      # enforced across all aggregate types if the same scope is used.
+      #
+      # An `AggregateKeyNotUniqueError` is raised if a unique
+      # constrained is violated when committing the events to the
+      # database.
+      module UniqueKeys
+        module ClassMethods
+          attr_reader :unique_key_definitions
+
+          # Defines a unique key for your aggregate. The first
+          # parameter is the scope of the unique constraints, followed
+          # by a list of attributes or keywords with blocks to produce
+          # the value that needs to be unique.
+          #
+          # `nil` valued keys are ignored when enforcing uniqueness.
+          #
+          # Example usage:
+          #
+          # ```
+          # unique_key :user_email, email: ->{ self.email&.downcase }
+          # ```
+          def unique_key(scope, *attributes, **kwargs)
+            fail ArgumentError, "'#{scope}' is not a symbol" unless scope.is_a?(Symbol)
+            fail ArgumentError, 'attributes must be symbols' unless attributes.all? { |attr| attr.is_a?(Symbol) }
+
+            @unique_key_definitions ||= {}
+
+            fail ArgumentError, "duplicate scope '#{scope}'" if @unique_key_definitions.include?(scope)
+
+            @unique_key_definitions[scope] = attributes.to_h do |attr|
+              [attr, -> { send(attr) }]
+            end.merge(
+              kwargs.transform_values do |attr|
+                attr.is_a?(Symbol) ? -> { send(attr) } : attr
+              end,
+            ) do |key|
+              fail ArgumentError, "duplicate attribute '#{key}'"
+            end
+          end
+        end
+
+        # Returns the unique keys for the current instance based on
+        # the `unique_key` defintions. You can also override it if you
+        # need more compicated logic.
+        #
+        # Example return value:
+        #
+        # ```
+        # {
+        #   user_email: { email: 'bob@example.com' }
+        # }
+        # ```
+        def unique_keys
+          return {} if self.class.unique_key_definitions.nil?
+
+          self.class.unique_key_definitions
+            &.transform_values do |attributes|
+              attributes.transform_values { |block| instance_exec(&block) }.compact
+            end
+            &.delete_if { |_, value| value.empty? }
+        end
+
+        def self.included(host_class)
+          host_class.extend(ClassMethods)
+        end
+      end
+    end
+  end
+end

data/lib/sequent/core/stream_record.rb

@@ -4,12 +4,28 @@ require 'active_record'
 
 module Sequent
   module Core
-    EventStream = Data.define(:aggregate_type, :aggregate_id, :events_partition_key, :snapshot_outdated_at) do
-      def initialize(aggregate_type:, aggregate_id:, events_partition_key: '', snapshot_outdated_at: nil)
+    EventStream = Data.define(
+      :aggregate_type,
+      :aggregate_id,
+      :events_partition_key,
+      :snapshot_outdated_at,
+      :unique_keys,
+    ) do
+      def initialize(aggregate_type:, aggregate_id:, events_partition_key: '', snapshot_outdated_at: nil,
+                     unique_keys: {})
         super
       end
     end
 
+    class AggregateUniqueKey < Sequent::ApplicationRecord
+      self.primary_key = %i[aggregate_id scope]
+      self.table_name = 'aggregate_unique_keys'
+
+      validates_presence_of :aggregate_id, :scope, :key
+
+      belongs_to :stream_record, foreign_key: :aggregate_id, primary_key: :aggregate_id
+    end
+
     class StreamRecord < Sequent::ApplicationRecord
       self.primary_key = %i[aggregate_id]
       self.table_name = 'stream_records'
@@ -18,12 +34,14 @@ module Sequent
       validates_presence_of :aggregate_type, :aggregate_id
 
       has_many :event_records, foreign_key: :aggregate_id, primary_key: :aggregate_id
+      has_many :aggregate_unique_keys, foreign_key: :aggregate_id, primary_key: :aggregate_id
 
       def event_stream
         EventStream.new(
           aggregate_type:,
           aggregate_id:,
           events_partition_key:,
+          unique_keys: aggregate_unique_keys.to_h { |key| [key.scope.to_sym, key.key] },
         )
       end
 

data/lib/sequent/test/command_handler_helpers.rb

@@ -2,6 +2,7 @@
 
 require 'thread_safe'
 require 'sequent/core/event_store'
+require 'rspec'
 
 module Sequent
   module Test
@@ -14,7 +15,22 @@ module Sequent
     # when_command PayInvoiceCommand.new(args)
     # then_events InvoicePaidEvent.new(args)
     #
-    # Example for Rspec config
+    # Given events are applied against the Aggregate so need to represent a correct
+    # sequence of events.
+    #
+    # When a command is executed all generated events are captured and can be
+    # retrieved using `stored_events` or tested using `then_events`.
+    #
+    # The `then_events` expects one class, expected event, or RSpec
+    # matcher for each generated event, in the same order.  Example
+    # for Rspec config. When a class is passed, only the type of the
+    # generated event is tested. When an expected event is passed only
+    # the *payload* is compared using the `have_same_payload_as`
+    # matcher defined by this module (`aggregate_id`,
+    # `sequence_number`, and `created_at` are *not* compared). When an
+    # RSpec matcher is passed the actual event is matched against this
+    # matcher, so you can use `eq` or `have_attributes` to do more
+    # specific matching.
     #
     # RSpec.configure do |config|
     #   config.include Sequent::Test::CommandHandlerHelpers
@@ -39,12 +55,11 @@ module Sequent
     # end
     module CommandHandlerHelpers
       class FakeEventStore
-        extend Forwardable
-
         def initialize
           @event_streams = {}
           @all_events = {}
           @stored_events = []
+          @unique_keys = {}
         end
 
         def load_events(aggregate_id)
@@ -65,11 +80,18 @@ module Sequent
           @event_streams[aggregate_id]
         end
 
-        def stored_events
-          deserialize_events(@stored_events)
-        end
-
         def commit_events(_, streams_with_events)
+          keys = @unique_keys.dup.delete_if do |_key, aggregate_id|
+            streams_with_events.any? { |stream, _| aggregate_id == stream.aggregate_id }
+          end
+          @unique_keys = keys.merge(
+            *streams_with_events.map do |stream, _|
+              stream.unique_keys.to_h { |scope, key| [[scope, key], stream.aggregate_id] }
+            end,
+          ) do |_key, id_1, id_2|
+            fail Sequent::Core::AggregateKeyNotUniqueError if id_1 != id_2
+          end
+
           streams_with_events.each do |event_stream, events|
             serialized = serialize_events(events)
             @event_streams[event_stream.aggregate_id] = event_stream
@@ -84,11 +106,6 @@ module Sequent
           Sequent.configuration.event_publisher.publish_events(events)
         end
 
-        def given_events(events)
-          commit_events(nil, to_event_streams(events))
-          @stored_events = []
-        end
-
         def stream_exists?(aggregate_id)
           @event_streams.key?(aggregate_id)
         end
@@ -97,38 +114,16 @@ module Sequent
           @event_streams[aggregate_id].present?
         end
 
-        private
-
-        def to_event_streams(events)
-          # Specs use a simple list of given events.
-          # We need a mapping from StreamRecord to the associated events for the event store.
-          streams_by_aggregate_id = {}
-          events.map do |event|
-            event_stream = streams_by_aggregate_id.fetch(event.aggregate_id) do |aggregate_id|
-              streams_by_aggregate_id[aggregate_id] =
-                find_event_stream(aggregate_id) ||
-                begin
-                  aggregate_type = aggregate_type_for_event(event)
-                  unless aggregate_type
-                    fail <<~EOS
-                      Cannot find aggregate type associated with creation event #{event}, did you include an event handler in your aggregate for this event?
-                    EOS
-                  end
-
-                  Sequent::Core::EventStream.new(aggregate_type: aggregate_type.name, aggregate_id: aggregate_id)
-                end
-            end
-            [event_stream, [event]]
-          end
+        def position_mark
+          @stored_events.length
         end
 
-        def aggregate_type_for_event(event)
-          @event_to_aggregate_type ||= ThreadSafe::Cache.new
-          @event_to_aggregate_type.fetch_or_store(event.class) do |klass|
-            Sequent::Core::AggregateRoot.descendants.find { |x| x.message_mapping.key?(klass) }
-          end
+        def load_events_since_marked_position(mark)
+          [deserialize_events(@stored_events[mark..]), position_mark]
         end
 
+        private
+
         def serialize_events(events)
           events.map { |event| [event.class.name, Sequent::Core::Oj.dump(event)] }
         end
@@ -140,41 +135,78 @@ module Sequent
         end
       end
 
+      RSpec::Matchers.define :have_same_payload_as do |expected|
+        match do |actual|
+          actual_hash = Sequent::Core::Oj.strict_load(Sequent::Core::Oj.dump(actual.payload))
+          expected_hash = Sequent::Core::Oj.strict_load(Sequent::Core::Oj.dump(expected.payload))
+          values_match? expected_hash, actual_hash
+        end
+
+        description do
+          expected.to_s
+        end
+
+        diffable
+      end
+
       def given_events(*events)
-        Sequent.configuration.event_store.given_events(events.flatten(1))
+        Sequent.configuration.event_store.commit_events(
+          Sequent::Core::BaseCommand.new,
+          to_event_streams(events.flatten(1)),
+        )
       end
 
       def when_command(command)
+        @helpers_events_position_mark = Sequent.configuration.event_store.position_mark
         Sequent.configuration.command_service.execute_commands command
       end
 
       def then_events(*expected_events)
-        expected_classes = expected_events.flatten(1).map { |event| event.instance_of?(Class) ? event : event.class }
-        expect(Sequent.configuration.event_store.stored_events.map(&:class)).to eq(expected_classes)
-
-        Sequent
-          .configuration
-          .event_store
-          .stored_events
-          .zip(expected_events.flatten(1))
-          .each_with_index do |(actual, expected), index|
-            next if expected.instance_of?(Class)
-
-            actual_hash = Sequent::Core::Oj.strict_load(Sequent::Core::Oj.dump(actual.payload))
-            expected_hash = Sequent::Core::Oj.strict_load(Sequent::Core::Oj.dump(expected.payload))
-            next unless expected
-
-            # rubocop:disable Layout/LineLength
-            expect(actual_hash)
-              .to eq(expected_hash),
-                  "#{index + 1}th Event of type #{actual.class} not equal\nexpected: #{expected_hash.inspect}\n     got: #{actual_hash.inspect}"
-            # rubocop:enable Layout/LineLength
+        matchers = expected_events.flatten(1).map do |expected|
+          if expected.is_a?(Sequent::Core::Event)
+            have_same_payload_as(expected)
+          else
+            expected
           end
+        end
+
+        expect(stored_events).to match(matchers)
       end
 
       def then_no_events
         then_events
       end
+
+      def stored_events
+        Sequent.configuration.event_store.load_events_since_marked_position(@helpers_events_position_mark)[0]
+      end
+
+      private
+
+      def to_event_streams(uncommitted_events)
+        # Specs use a simple list of given events.
+        # We need a mapping from StreamRecord to the associated events for the event store.
+        uncommitted_events.group_by(&:aggregate_id).map do |aggregate_id, new_events|
+          _, existing_events = Sequent.configuration.event_store.load_events(aggregate_id) || [nil, []]
+          all_events = existing_events + new_events
+          aggregate_type = aggregate_type_for_event(all_events[0])
+          unless aggregate_type
+            fail <<~EOS
+              Cannot find aggregate type associated with creation event #{all_events[0]}, did you include an event handler in your aggregate for this event?
+            EOS
+          end
+
+          aggregate = aggregate_type.load_from_history(nil, all_events)
+          [aggregate.event_stream, new_events]
+        end
+      end
+
+      def aggregate_type_for_event(event)
+        @helpers_event_to_aggregate_type ||= ThreadSafe::Cache.new
+        @helpers_event_to_aggregate_type.fetch_or_store(event.class) do |klass|
+          Sequent::Core::AggregateRoot.descendants.find { |x| x.message_mapping.key?(klass) }
+        end
+      end
     end
   end
 end

data/lib/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Sequent
-  VERSION = '8.0.2'
+  VERSION = '8.1.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sequent
 version: !ruby/object:Gem::Version
-  version: 8.0.2
+  version: 8.1.0
 platform: ruby
 authors:
 - Lars Vonk
@@ -12,7 +12,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-01-10 00:00:00.000000000 Z
+date: 1980-01-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -437,6 +437,7 @@ files:
 - lib/sequent/core/helpers/string_validator.rb
 - lib/sequent/core/helpers/time_validator.rb
 - lib/sequent/core/helpers/type_conversion_support.rb
+- lib/sequent/core/helpers/unique_keys.rb
 - lib/sequent/core/helpers/uuid_helper.rb
 - lib/sequent/core/helpers/value_validators.rb
 - lib/sequent/core/middleware/chain.rb
@@ -545,7 +546,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.16
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: Event sourcing framework for Ruby