funes-rails 0.2.1 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a51269f6bd4892236215ca7de5afd23bff48c49ca57a379cc7595cc4ef1ef0a8
-  data.tar.gz: 57f27dbd3f84933ed3245e1c77892850f45ed3d2b05aaa7cdf74720f91428ef0
+  metadata.gz: fa21a99408ee10d9f9b17e06af87f2f51d099fd593fadec8672c71b15110a53e
+  data.tar.gz: 893a107d52489ffc4e7680f558dbe8dfce0c8bdf88ad05bd4a704efd0eeb97ce
 SHA512:
-  metadata.gz: 11c9e49708f8631a8eae80fe1c1d5df8d647492e0fcad51ec859f7488cb5b96ed8c0ef1a180378470968b406645665cb908b383271c6dc816c41a6edd01834a6
-  data.tar.gz: 5fa9fd8a1ee99d31bb930e9b5f6bf951a26681548d71e0e7f971f0c63c6b31f49dc4c183b0757ed5f9c12bfbd8a155d8599da6b86b20cf82b69e31bd1d1ff0bd
+  metadata.gz: eddd2d0d5c46fe75338a095098a5391eb3aa81b29196f4fd352458ba6e6efc75673959ac59b1b40c555ec1a2f8914524503f718017845f636b030577578dc3f6
+  data.tar.gz: c57f6bb79093b02c19abc8c5246bb741c4cf23d16c24dc2e1857e7941457e02ddd4a2e83441b767302bf6c4322bb88a087703bf2480031ac0bc7aa5e86470607

data/README.md

@@ -103,12 +103,22 @@ Funes gives you fine-grained control over when and how projections run:
 
 Guides and full API documentation are available at [docs.funes.org](https://docs.funes.org).
 
+## Performance
+
+Precise benchmarks are notoriously hard to pin down: workloads vary, and absolute numbers depend heavily on hardware, configuration, and the shape of the data. So treat the figures we publish as directional rather than definitive.
+
+That said, our measurements consistently show that the complexity of event stream operations stays **sub-linear, comfortably within `O(n)`** as the log grows — which is an important property for medium/long-lived streams.
+
+You can browse the latest measurements and join the conversation in the [Performance Measurements](https://github.com/funes-org/funes/discussions/categories/performance-measurements) discussions.
+
 ## Compatibility
 
-- **Ruby:** 3.1, 3.2, 3.3, 3.4
-- **Rails:** 7.1, 7.2, 8.0, 8.1
+Funes supports the following runtimes:
+
+- **Ruby** 3.1 or newer
+- **Rails** 7.2 or newer
 
-Rails 8.0+ requires Ruby 3.2 or higher.
+If you're on Rails 8.0 or above, you'll need Ruby 3.2 or newer — that's a Rails 8 requirement, not a Funes one.
 
 ## License
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/app/event_streams/funes/event_stream.rb

@@ -230,33 +230,72 @@ module Funes
     #     # Race condition detected, retry logic here
     #   end
     def append(new_event, at: nil)
-      return new_event unless new_event.valid?
-
-      occurred_at = resolve_proper_occurred_at(new_event, at)
-
-      if consistency_projection.present?
-        materialization = compute_projection_with_new_event(consistency_projection, new_event, occurred_at)
-        transfer_interpretation_errors(new_event)
-        return new_event if materialization.invalid? || new_event.invalid?
-      end
-
-      ActiveRecord::Base.transaction do
-        begin
-          @instance_new_events << new_event.persist!(@idx, incremented_version, at: occurred_at)
-          run_transactional_projections
-        rescue ActiveRecord::RecordNotUnique
-          new_event._event_entry = nil
-          new_event.errors.add(:base, I18n.t("funes.events.racing_condition_on_insert"))
-          raise ActiveRecord::Rollback
-        rescue ActiveRecord::StatementInvalid, ActiveRecord::RecordInvalid => e
-          new_event._event_entry = nil
-          raise e
-        end
-      end
-
-      schedule_async_projections unless new_event.errors.any?
+      do_append(new_event, at: at, raise_on_failure: false)
+    end
 
-      new_event
+    # Append a new event to the stream, raising on any failure.
+    #
+    # Behaves like {#append}, but raises `ActiveRecord::RecordInvalid` whenever the event cannot be
+    # persisted — mirroring the relationship between `ActiveRecord::Base#save` and `#save!`. Because
+    # a real exception is raised, any enclosing `ActiveRecord::Base.transaction` block rolls back,
+    # which is what you want when you need host-managed transactional control around `append`.
+    #
+    # The failed event is always queryable after the rescue: `event.persisted?` returns false and
+    # `event.errors` is populated (for event-level failures such as validation, consistency
+    # rejection, or version conflict).
+    #
+    # Failure modes:
+    # - Event's own validation fails → raises `ActiveRecord::RecordInvalid` with the event as `record`.
+    # - Consistency projection rejects the event → raises `ActiveRecord::RecordInvalid` with the
+    #   event as `record` (state / interpretation errors transferred to the event).
+    # - Version conflict (race condition on insert) → raises `ActiveRecord::RecordInvalid` with the
+    #   event as `record` and a racing-condition message on `event.errors[:base]`.
+    # - A transactional projection's persistence fails → the original
+    #   `ActiveRecord::StatementInvalid` / `ActiveRecord::RecordInvalid` is re-raised untouched (its
+    #   `record` is the projection's materialization model, not the event). `event.persisted?` is
+    #   still false after the rescue.
+    #
+    # Async projections are only enqueued when `append!` returns successfully. When `append!` is
+    # nested inside a user-opened `ActiveRecord::Base.transaction` that later rolls back, Rails'
+    # `enqueue_after_transaction_commit` discards the deferred enqueue so no job runs.
+    #
+    # @param [Funes::Event] new_event The event to append to the stream.
+    # @param [Time, Date, nil] at See {#append}.
+    # @return [Funes::Event] The persisted event.
+    # @raise [ActiveRecord::RecordInvalid] When the event cannot be persisted. `e.record` is the
+    #   failed event (for event-level failures) or a projection materialization model (for
+    #   projection validation failures).
+    # @raise [ActiveRecord::StatementInvalid] When a transactional projection fails with a database
+    #   constraint violation.
+    # @raise [Funes::ConflictingActualTimeError] See {#append}.
+    # @raise [Funes::MissingActualTimeAttributeError] See {#append}.
+    #
+    # @example Host-managed transaction with a sibling AR update
+    #   event = SomeEvent.new(some: "value")
+    #   begin
+    #     ActiveRecord::Base.transaction do
+    #       some_model.update!(some: "value")
+    #       SomeEventStream.for(stream_id).append!(event)
+    #     end
+    #   rescue ActiveRecord::RecordInvalid
+    #     event.persisted?  # => false
+    #     event.errors.any? # => true
+    #   end
+    #
+    # @example Two appends in a single transaction — either both commit or neither does
+    #   event_1 = SomeEvent.new(some: "value")
+    #   event_2 = OtherEvent.new(some: "value")
+    #   begin
+    #     ActiveRecord::Base.transaction do
+    #       SomeEventStream.for(stream_id).append!(event_1)
+    #       OtherEventStream.for(other_stream_id).append!(event_2)
+    #     end
+    #   rescue ActiveRecord::RecordInvalid
+    #     event_1.persisted? # => false
+    #     event_2.persisted? # => false
+    #   end
+    def append!(new_event, at: nil)
+      do_append(new_event, at: at, raise_on_failure: true)
     end
 
     # @!visibility private
@@ -291,12 +330,19 @@ module Funes
     # include those where `occurred_at <= at` before projection. When `as_of:` is provided,
     # it overrides the stream's record-time boundary, filtering events in Ruby by `created_at`.
     #
+    # Mirrors `ActiveRecord::Base.find`: if there are no events to replay — either because the
+    # stream has no events at all or because `as_of:` / `at:` filtering leaves none in scope —
+    # raises {ActiveRecord::RecordNotFound}. In a Rails controller, this lets the host app's
+    # middleware render a 404 automatically, without any rescue wiring.
+    #
     # @param projection_class [Class<Funes::Projection>] The projection class to use.
     # @param [Time, nil] as_of Optional record-time override. When provided, only events with
     #   `created_at <= as_of` are considered, overriding the stream's own `@as_of`.
     # @param [Time, nil] at Optional actual-time reference. When provided, only events with
     #   `occurred_at <= at` are included in the projection.
     # @return [Object] The materialized state as defined by the projection's materialization model.
+    # @raise [ActiveRecord::RecordNotFound] when the filtered event list is empty — either
+    #   because the stream has no events or because `as_of:` / `at:` excludes them all.
     #
     # @example Project current state
     #   stream = OrderEventStream.for("order-123")
@@ -313,9 +359,36 @@ module Funes
     #   snapshot = stream.projected_with(SalaryProjection,
     #                                    as_of: Time.new(2025, 3, 1),
     #                                    at: Time.new(2025, 2, 20))
+    #
+    # @example Automatic 404 in a Rails controller
+    #   class OrdersController < ApplicationController
+    #     def show
+    #       stream = OrderEventStream.for(params[:id])
+    #       @order = stream.projected_with(OrderSummaryProjection)
+    #     end
+    #   end
+    #   # If no events exist for params[:id], Rails renders its 404 page automatically.
     def projected_with(projection_class, as_of: nil, at: nil)
       source_events = as_of ? filter_by_record_time(events, as_of) : events
       target_events = at ? filter_by_actual_time(source_events, at) : source_events
+
+      if target_events.empty?
+        materialization_model = projection_class.instance_variable_get(:@materialization_model)
+        model_name = materialization_model&.name
+        Rails.logger.info(
+          "[Funes] projected_with found no events for " \
+          "#{self.class.name} idx=#{idx.inspect} " \
+          "projection=#{projection_class.name} " \
+          "as_of=#{as_of.inspect} at=#{at.inspect}"
+        )
+        raise ActiveRecord::RecordNotFound.new(
+          "Couldn't find #{model_name} for #{self.class.name} #{idx.inspect}",
+          model_name,
+          "idx",
+          idx
+        )
+      end
+
       projection_class.process_events(target_events, at: at)
     end
 
@@ -338,6 +411,46 @@ module Funes
     end
 
     private
+      def do_append(new_event, at:, raise_on_failure:)
+        unless new_event.valid?
+          raise ActiveRecord::RecordInvalid.new(new_event) if raise_on_failure
+          return new_event
+        end
+
+        occurred_at = resolve_proper_occurred_at(new_event, at)
+
+        if consistency_projection.present?
+          materialization = compute_projection_with_new_event(consistency_projection, new_event, occurred_at)
+          transfer_interpretation_errors(new_event)
+          if materialization.invalid? || new_event.invalid?
+            raise ActiveRecord::RecordInvalid.new(new_event) if raise_on_failure
+            return new_event
+          end
+        end
+
+        ActiveRecord::Base.transaction do
+          begin
+            @instance_new_events << new_event.persist!(@idx, incremented_version, at: occurred_at)
+            ActiveRecord::Base.connection.current_transaction.after_rollback do
+              new_event._event_entry = nil
+            end
+            run_transactional_projections
+          rescue ActiveRecord::RecordNotUnique
+            new_event._event_entry = nil
+            new_event.errors.add(:base, I18n.t("funes.events.racing_condition_on_insert"))
+            raise ActiveRecord::RecordInvalid.new(new_event) if raise_on_failure
+            raise ActiveRecord::Rollback
+          rescue ActiveRecord::StatementInvalid, ActiveRecord::RecordInvalid => e
+            new_event._event_entry = nil
+            raise e
+          end
+        end
+
+        schedule_async_projections unless new_event.errors.any?
+
+        new_event
+      end
+
       def run_transactional_projections
         transactional_projections.each do |projection_class|
           Funes::PersistProjectionJob.perform_now(self, projection_class, last_event_creation_date,

data/app/jobs/funes/persist_projection_job.rb

@@ -1,5 +1,7 @@
 module Funes
   class PersistProjectionJob < ApplicationJob
+    self.enqueue_after_transaction_commit = true
+
     def perform(event_stream, projection_class, as_of = nil, at = nil)
       events = as_of ? event_stream.events.select { |e| e.created_at <= as_of } : event_stream.events
       projection_class.materialize!(events, event_stream.idx, at: at)

data/app/projections/funes/projection.rb

@@ -1,5 +1,6 @@
 require "funes/unknown_event"
 require "funes/unknown_materialization_model"
+require "funes/invalid_materialization_state"
 
 module Funes
   # Projections perform the necessary pattern-matching to compute and aggregate the interpretations that the system
@@ -122,6 +123,31 @@ module Funes
         @materialization_model = active_record_or_model
       end
 
+      # Registers an instance method on the materialization model that owns the persistence step,
+      # replacing the framework's default upsert.
+      #
+      # When set, the named method is invoked on the in-memory state after all interpretations have
+      # run and +idx+ has been assigned. The method takes no arguments and is expected to raise on
+      # failure. The framework still calls +state.valid?+ and raises
+      # +Funes::InvalidMaterializationState+ before delegating, so the custom method only runs
+      # against valid state.
+      #
+      # Declaring +persist_materialization_model_with+ also lifts the requirement that the
+      # materialization model be an +ActiveRecord::Base+ subclass: a plain +ActiveModel+ class is
+      # enough as long as it exposes +assign_attributes+, +attributes+, +valid?+ and +errors+.
+      #
+      # @param [Symbol] method_name The instance method on the materialization model that performs the write.
+      # @return [void]
+      #
+      # @example Persisting a projection to a JSON file
+      #   class YourProjection < Funes::Projection
+      #     materialization_model YourMaterializationModel
+      #     persist_materialization_model_with :save_to_object_storage!
+      #   end
+      def persist_materialization_model_with(method_name)
+        @persist_method = method_name
+      end
+
       # It changes the sensibility of the projection about events that it doesn't know how to interpret
       #
       # By default, a projection ignores events that it doesn't have interpretations for. This method informs the
@@ -142,7 +168,8 @@ module Funes
       def process_events(events_collection, at: nil, consistency: false)
         new(self.instance_variable_get(:@interpretations),
             self.instance_variable_get(:@materialization_model),
-            self.instance_variable_get(:@throws_on_unknown_events))
+            self.instance_variable_get(:@throws_on_unknown_events),
+            self.instance_variable_get(:@persist_method))
           .process_events(events_collection, at: at, consistency: consistency)
       end
 
@@ -150,13 +177,14 @@ module Funes
       def materialize!(events_collection, idx, at: nil)
         new(self.instance_variable_get(:@interpretations),
             self.instance_variable_get(:@materialization_model),
-            self.instance_variable_get(:@throws_on_unknown_events))
+            self.instance_variable_get(:@throws_on_unknown_events),
+            self.instance_variable_get(:@persist_method))
           .materialize!(events_collection, idx, at: at)
       end
     end
 
     # @!visibility private
-    def initialize(interpretations, materialization_model, throws_on_unknown_events)
+    def initialize(interpretations, materialization_model, throws_on_unknown_events, persist_method = nil)
       @interpretations = interpretations
       @materialization_model = materialization_model
       raise Funes::UnknownMaterializationModel,
@@ -164,6 +192,7 @@ module Funes
 
 
       @throws_on_unknown_events = throws_on_unknown_events
+      @persist_method = persist_method
     end
 
     # @!visibility private
@@ -191,13 +220,13 @@ module Funes
     # @!visibility private
     def materialize!(events_collection, idx, at: nil)
       state = process_events(events_collection, at: at)
-      materialized_model_instance = materialized_model_instance_based_on(state)
-      if materialization_model_is_persistable?
+      if persistable?
         state.assign_attributes(idx:)
         persist_based_on!(state)
+        return state if @persist_method
       end
 
-      materialized_model_instance
+      materialized_model_instance_based_on(state)
     end
 
     private
@@ -213,13 +242,23 @@ module Funes
         @materialization_model.new(state.attributes)
       end
 
-      def materialization_model_is_persistable?
-        @materialization_model.present? && @materialization_model <= ActiveRecord::Base
+      def persistable?
+        return false unless @materialization_model.present?
+        return true if @persist_method
+        @materialization_model <= ActiveRecord::Base
       end
 
       def persist_based_on!(state)
-        raise ActiveRecord::RecordInvalid.new(state) unless state.valid?
-        @materialization_model.upsert(state.attributes, unique_by: :idx)
+        unless state.valid?
+          raise Funes::InvalidMaterializationState.new(state) if @persist_method
+          raise ActiveRecord::RecordInvalid.new(state)
+        end
+
+        if @persist_method
+          state.public_send(@persist_method)
+        else
+          @materialization_model.upsert(state.attributes, unique_by: :idx)
+        end
       end
 
       def warn_about_ineffective_errors(event)

data/lib/funes/invalid_materialization_state.rb

@@ -0,0 +1,31 @@
+module Funes
+  # Raised when a projection configured with `persist_materialization_model_with` produces an
+  # invalid materialization state.
+  #
+  # When a projection declares a custom persistence method via `persist_materialization_model_with`,
+  # Funes still validates the materialization (via `state.valid?`) before delegating the write.
+  # If validation fails, this exception is raised and the custom persist method is *not* invoked.
+  #
+  # The failed materialization is exposed via `#record`, mirroring the ergonomics of
+  # `ActiveRecord::RecordInvalid` — but without coupling the custom-persist path to ActiveRecord.
+  # Like any unrescued exception, it propagates out of `materialize!` and rolls back any enclosing
+  # `ActiveRecord::Base.transaction`, which is the desired behaviour for transactional projections.
+  #
+  # @example Handling an invalid materialization state
+  #   begin
+  #     YourProjection.materialize!(events, "some-id", at: Time.current)
+  #   rescue Funes::InvalidMaterializationState => e
+  #     Rails.logger.error "Invalid materialization: #{e.message}"
+  #     e.record.errors.full_messages # the validation errors on the materialization
+  #   end
+  #
+  # @see Funes::Projection.persist_materialization_model_with
+  class InvalidMaterializationState < StandardError
+    attr_reader :record
+
+    def initialize(record)
+      @record = record
+      super("Invalid materialization state: #{record.errors.full_messages.to_sentence}")
+    end
+  end
+end

data/lib/funes/version.rb

@@ -1,3 +1,3 @@
 module Funes
-  VERSION = "0.2.1"
+  VERSION = "0.2.3"
 end

data/lib/funes.rb

@@ -5,6 +5,7 @@ require "funes/event_metainformation_builder"
 require "funes/invalid_event_metainformation"
 require "funes/conflicting_actual_time_error"
 require "funes/missing_actual_time_attribute_error"
+require "funes/invalid_materialization_state"
 require "funes/engine"
 
 # Funes is an event sourcing framework for Ruby on Rails.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: funes-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.3
 platform: ruby
 authors:
 - Vinícius Almeida da Silva
@@ -15,28 +15,34 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '7.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '7.2'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "<"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '5.26'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "<"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '5.26'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6'
 - !ruby/object:Gem::Dependency
   name: database_cleaner-active_record
   requirement: !ruby/object:Gem::Requirement
@@ -210,6 +216,7 @@ files:
 - lib/funes/event_metainformation_builder.rb
 - lib/funes/inspection.rb
 - lib/funes/invalid_event_metainformation.rb
+- lib/funes/invalid_materialization_state.rb
 - lib/funes/missing_actual_time_attribute_error.rb
 - lib/funes/unknown_event.rb
 - lib/funes/unknown_materialization_model.rb