funes-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b28b73445f6209c360034c351b80e0677356b42c14834908e9598a6b6f7edd02
+  data.tar.gz: 7587dfa95f04e2e2a1b0eb505c19f0433541b2c46fa49e83471dee1386fec79b
+SHA512:
+  metadata.gz: 828e4c5762de480e79f264124d12e7d4792ffc4856c3941dc4e757b8ebc9a31e0e645af98113a127df5f0d22f38398fe6a3c1e50511a9e59cd7e59b9cf05d8fd
+  data.tar.gz: 9feb8d0618335d5d1eb23027d5ec50cea4b91753b016bfe0b2cea3ba3567dfe43303f8173c07f06857b62e0aaa71ba3da33ba625bf5b4a35afb655a649b18254

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Vinícius Almeida da Silva
+
+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,180 @@
+# Funes
+
+Event sourcing for Ruby on Rails — append-only events as your source of truth, with flexible projections for reads.
+
+## Event Sourcing?
+
+Traditional Rails apps update state in place. You `update!` a record and the previous value is gone. Event sourcing takes a different approach: store *what happened* as immutable events, then derive current state by replaying them.
+
+This gives you:
+
+- **Complete audit trail** — every state change is recorded, forever
+- **Temporal queries** — "what was the balance on December 1st?"
+- **Multiple read models** — same events, different projections for different use cases
+- **Safer refactoring** — rebuild any projection from the event log
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "funes-rails"
+```
+
+Run the installation:
+
+```bash
+$ bin/bundle install
+$ bin/rails generate funes:install
+$ bin/rails db:migrate
+```
+
+## Three-Tier Consistency Model
+
+Funes gives you fine-grained control over when and how projections run:
+
+| Tier                      | When it runs                 | Use case                                        |
+|:--------------------------|:-----------------------------|:------------------------------------------------|
+| Consistency Projection    | Before event is persisted    | Validate business rules against resulting state |
+| Transactional Projections | Same DB transaction as event | Critical read models needing strong consistency |
+| Async Projections         | Background job (ActiveJob)   | Reports, analytics, non-critical read models    |
+
+### Consistency Projection
+
+Runs before the event is saved. If the resulting state is invalid, the event is rejected:
+
+```ruby
+class InventoryEventStream < Funes::EventStream
+  consistency_projection InventorySnapshotProjection
+end
+
+class InventorySnapshot
+  include ActiveModel::Model
+  include ActiveModel::Attributes
+
+  attribute :quantity_on_hand, :integer, default: 0
+
+  validates :quantity_on_hand, numericality: { greater_than_or_equal_to: 0 }
+end
+```
+
+Now if someone tries to ship more than available:
+
+```ruby
+
+event = stream.append!(Inventory::ItemShipped.new(quantity: 9999))
+event.valid? # => false
+event.errors[:quantity_on_hand] # => ["must be greater than or equal to 0"]
+```
+
+The event is never persisted. Your invariants are protected.
+
+### Transactional Projections
+
+Update read models in the same database transaction. If anything fails, everything rolls back:
+
+```ruby
+add_transactional_projection InventoryLedgerProjection
+```
+
+### Async Projections
+
+Schedule background jobs with full ActiveJob options:
+
+```ruby
+add_async_projection ReportingProjection, queue: :low, wait: 5.minutes
+add_async_projection AnalyticsProjection, wait_until: Date.tomorrow.midnight
+```
+
+#### Controlling the `as_of` Timestamp
+
+By default, async projections use the creation time of the last event. You can customize this behavior:
+
+```ruby
+# Use job execution time instead of event time
+add_async_projection RealtimeProjection, as_of: :job_time
+
+# Custom logic with a proc
+add_async_projection EndOfDayProjection,
+  as_of: ->(last_event) { last_event.created_at.beginning_of_day }
+```
+
+Available `as_of` strategies:
+- `:last_event_time` (default) — Uses the creation time of the last event
+- `:job_time` — Uses `Time.current` when the job executes
+- `Proc/Lambda` — Custom logic that receives the last event and returns a `Time` object
+
+## Temporal Queries
+
+Every event is timestamped. Query your stream at any point in time:
+
+### Current state
+```ruby
+stream = InventoryEventStream.for("sku-12345")
+stream.events # => all events
+```
+
+### State as of last month
+```ruby
+stream = InventoryEventStream.for("sku-12345", 1.month.ago)
+stream.events # => events up to that timestamp
+```
+
+Projections receive the as_of parameter, so you can build point-in-time snapshots:
+
+```ruby
+# in your projection
+interpretation_for(Inventory::ItemReceived) do |state, event, as_of|
+  # as_of is available if you need temporal logic
+  state.quantity_on_hand += event.quantity
+  state
+end
+```
+
+## Concurrency
+
+Funes uses optimistic concurrency control. Each event in a stream gets an incrementing version number with a unique constraint on (idx, version).
+
+If two processes try to append to the same stream simultaneously, one succeeds and the other gets a validation error — no locks, no blocking:
+
+```ruby
+event = stream.append!(SomeEvent.new)
+unless event.valid?
+  event.errors[:version] # => ["has already been taken"]
+  # Reload and retry your business logic
+end
+```
+
+## Testing
+
+Funes provides helpers for testing projections in isolation:
+
+```ruby
+class InventorySnapshotProjectionTest < ActiveSupport::TestCase
+  include Funes::ProjectionTestHelper
+
+  test "receiving items increases quantity on hand" do
+    initial_state = InventorySnapshot.new(quantity_on_hand: 10)
+    event = Inventory::ItemReceived.new(quantity: 5, unit_cost: 9.99)
+
+    result = interpret_event_based_on(InventorySnapshotProjection, event, initial_state)
+
+    assert_equal 15, result.quantity_on_hand
+  end
+end
+```
+
+## Strict Mode
+
+By default, projections ignore events they don't have interpretations for. Enable strict mode to catch missing handlers:
+
+```ruby
+class StrictProjection < Funes::Projection
+  raise_on_unknown_events
+
+  # Now forgetting to handle an event type raises Funes::UnknownEvent
+end
+```
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,135 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"
+
+namespace :docs do
+  desc "Generate YARD documentation for current version"
+  task :generate do
+    require_relative "lib/funes/version"
+    version = Funes::VERSION
+    output_dir = "docs/v#{version}"
+
+    puts "Generating documentation for version #{version}..."
+    system("yard doc --output-dir #{output_dir}") || abort("Failed to generate documentation")
+
+    # Copy assets to root docs directory
+    FileUtils.mkdir_p("docs")
+    %w[css js].each do |asset_dir|
+      if Dir.exist?("#{output_dir}/#{asset_dir}")
+        FileUtils.cp_r("#{output_dir}/#{asset_dir}", "docs/#{asset_dir}")
+      end
+    end
+
+    puts "Documentation generated in #{output_dir}/"
+    Rake::Task["docs:build_index"].invoke
+  end
+
+  desc "Build version selector index page"
+  task :build_index do
+    versions = Dir.glob("docs/v*").map { |d| File.basename(d) }.sort.reverse
+
+    if versions.empty?
+      puts "No versions found. Run 'rake docs:generate' first."
+      exit 1
+    end
+
+    latest_version = versions.first
+
+    html = <<~HTML
+      <!DOCTYPE html>
+      <html>
+      <head>
+        <meta charset="utf-8">
+        <title>Funes Documentation</title>
+        <link rel="stylesheet" href="css/style.css">
+        <style>
+          body {
+            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+            max-width: 800px;
+            margin: 50px auto;
+            padding: 20px;
+            line-height: 1.6;
+          }
+          h1 {
+            color: #333;
+            border-bottom: 2px solid #0066cc;
+            padding-bottom: 10px;
+          }
+          .version-list {
+            list-style: none;
+            padding: 0;
+          }
+          .version-list li {
+            margin: 10px 0;
+            padding: 15px;
+            background: #f5f5f5;
+            border-radius: 5px;
+          }
+          .version-list a {
+            text-decoration: none;
+            color: #0066cc;
+            font-size: 18px;
+            font-weight: 500;
+          }
+          .version-list a:hover {
+            text-decoration: underline;
+          }
+          .latest-badge {
+            background: #0066cc;
+            color: white;
+            padding: 3px 8px;
+            border-radius: 3px;
+            font-size: 12px;
+            margin-left: 10px;
+          }
+          .description {
+            color: #666;
+            margin-top: 20px;
+          }
+        </style>
+      </head>
+      <body>
+        <h1>Funes Documentation</h1>
+        <p class="description">Event Sourcing for Rails - Select a version to view documentation</p>
+
+        <ul class="version-list">
+    HTML
+
+    versions.each do |version|
+      is_latest = version == latest_version
+      badge = is_latest ? '<span class="latest-badge">latest</span>' : ''
+      html += "      <li><a href=\"#{version}/index.html\">#{version}#{badge}</a></li>\n"
+    end
+
+    html += <<~HTML
+        </ul>
+
+        <p class="description">
+          <a href="https://github.com/funes-org/funes">View on GitHub</a> |
+          <a href="https://funes.org/">Official Website</a>
+        </p>
+      </body>
+      </html>
+    HTML
+
+    File.write("docs/index.html", html)
+    puts "Version index page created at docs/index.html"
+  end
+
+  desc "List all documented versions"
+  task :list do
+    versions = Dir.glob("docs/v*").map { |d| File.basename(d) }.sort.reverse
+
+    if versions.empty?
+      puts "No versions documented yet."
+    else
+      puts "Documented versions:"
+      versions.each { |v| puts "  - #{v}" }
+    end
+  end
+end

data/app/assets/stylesheets/funes/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

data/app/controllers/funes/application_controller.rb

@@ -0,0 +1,4 @@
+module Funes
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/event_streams/funes/event_stream.rb

@@ -0,0 +1,274 @@
+module Funes
+  # EventStream manages the append-only sequence of events for a specific entity.
+  # Each stream is identified by an `idx` (entity identifier) and provides methods for appending
+  # events and configuring how projections are triggered.
+  #
+  # EventStreams implement a three-tier consistency model:
+  #
+  # - **Consistency Projection:** Validates business rules before persisting the event. If invalid, the event is rejected.
+  # - **Transactional Projections:** Execute synchronously in the same database transaction as the event.
+  # - **Async Projections:** Execute asynchronously via ActiveJob after the event is committed.
+  #
+  # ## Temporal Queries
+  #
+  # EventStreams support temporal queries through the `as_of` parameter. When an EventStream is created
+  # with a specific timestamp, only events created before or at that timestamp are included, enabling
+  # point-in-time state reconstruction.
+  #
+  # ## Concurrency Control
+  #
+  # EventStreams use optimistic concurrency control with version numbers. Each event gets an incrementing
+  # version number with a unique constraint on `(idx, version)`, preventing race conditions when multiple
+  # processes append to the same stream simultaneously.
+  #
+  # @example Define an event stream with projections
+  #   class OrderEventStream < Funes::EventStream
+  #     consistency_projection OrderValidationProjection
+  #     add_transactional_projection OrderSnapshotProjection
+  #     add_async_projection OrderReportProjection, queue: :reports
+  #   end
+  #
+  # @example Append events to a stream
+  #   stream = OrderEventStream.for("order-123")
+  #   event = stream.append!(Order::Placed.new(total: 99.99))
+  #
+  #   if event.valid?
+  #     puts "Event persisted with version #{event.version}"
+  #   else
+  #     puts "Event rejected: #{event.errors.full_messages}"
+  #   end
+  #
+  # @example Temporal query - get stream state as of a specific time
+  #   stream = OrderEventStream.for("order-123", 1.month.ago)
+  #   stream.events # => only events up to 1 month ago
+  class EventStream
+    class << self
+      # Register a consistency projection that validates business rules before persisting events.
+      #
+      # The consistency projection runs before the event is saved. If the resulting state is invalid,
+      # the event is rejected and not persisted to the database.
+      #
+      # @param [Class<Funes::Projection>] projection The projection class that will validate the state.
+      # @return [void]
+      #
+      # @example
+      #   class InventoryEventStream < Funes::EventStream
+      #     consistency_projection InventoryValidationProjection
+      #   end
+      def consistency_projection(projection)
+        @consistency_projection = projection
+      end
+
+      # Register a transactional projection that executes synchronously in the same database transaction.
+      #
+      # Transactional projections run after the event is persisted but within the same database transaction.
+      # If a transactional projection fails, the entire transaction (including the event) is rolled back.
+      #
+      # @param [Class<Funes::Projection>] projection The projection class to execute transactionally.
+      # @return [void]
+      #
+      # @example
+      #   class OrderEventStream < Funes::EventStream
+      #     add_transactional_projection OrderSnapshotProjection
+      #   end
+      def add_transactional_projection(projection)
+        @transactional_projections ||= []
+        @transactional_projections << projection
+      end
+
+      # Register an async projection that executes in a background job after the event is committed.
+      #
+      # Async projections are scheduled via ActiveJob after the event transaction commits. You can
+      # pass any ActiveJob options (queue, wait, wait_until, priority, etc.) to control job scheduling.
+      #
+      # The `as_of` parameter controls the timestamp used when the projection job executes:
+      # - `:last_event_time` (default) - Uses the creation time of the last event
+      # - `:job_time` - Uses Time.current when the job executes
+      # - Proc/Lambda - Custom logic that receives the last event and returns a Time object
+      #
+      # @param [Class<Funes::Projection>] projection The projection class to execute asynchronously.
+      # @param [Symbol, Proc] as_of Strategy for determining the as_of timestamp (:last_event_time, :job_time, or Proc).
+      # @param [Hash] options ActiveJob options for scheduling (queue, wait, wait_until, priority, etc.).
+      # @return [void]
+      #
+      # @example Schedule with custom queue
+      #   class OrderEventStream < Funes::EventStream
+      #     add_async_projection OrderReportProjection, queue: :reports
+      #   end
+      #
+      # @example Schedule with delay
+      #   class OrderEventStream < Funes::EventStream
+      #     add_async_projection AnalyticsProjection, wait: 5.minutes
+      #   end
+      #
+      # @example Use job execution time instead of event time
+      #   class OrderEventStream < Funes::EventStream
+      #     add_async_projection RealtimeProjection, as_of: :job_time
+      #   end
+      #
+      # @example Custom as_of logic with proc
+      #   class OrderEventStream < Funes::EventStream
+      #     add_async_projection EndOfDayProjection, as_of: ->(last_event) { last_event.created_at.beginning_of_day }
+      #   end
+      def add_async_projection(projection, as_of: :last_event_time, **options)
+        @async_projections ||= []
+        @async_projections << { class: projection, as_of_strategy: as_of, options: options }
+      end
+
+      # Create a new EventStream instance for the given entity identifier.
+      #
+      # @param [String] idx The entity identifier.
+      # @param [Time, nil] as_of Optional timestamp for temporal queries. If provided, only events
+      #   created before or at this timestamp will be included. Defaults to Time.current.
+      # @return [Funes::EventStream] A new EventStream instance.
+      #
+      # @example Current state
+      #   stream = OrderEventStream.for("order-123")
+      #
+      # @example State as of a specific time
+      #   stream = OrderEventStream.for("order-123", 1.month.ago)
+      def for(idx, as_of = nil)
+        new(idx, as_of)
+      end
+    end
+
+    # @!attribute [r] idx
+    #   @return [String] The entity identifier for this event stream.
+    attr_reader :idx
+
+    # Append a new event to the stream.
+    #
+    # This method validates the event, runs the consistency projection (if configured), persists the event
+    # with an incremented version number, and triggers transactional and async projections.
+    #
+    # @param [Funes::Event] new_event The event to append to the stream.
+    # @return [Funes::Event] The event object (check `valid?` to see if it was persisted).
+    #
+    # @example Successful append
+    #   event = stream.append!(Order::Placed.new(total: 99.99))
+    #   if event.valid?
+    #     puts "Event persisted with version #{event.version}"
+    #   end
+    #
+    # @example Handling validation failure
+    #   event = stream.append!(InvalidEvent.new)
+    #   unless event.valid?
+    #     puts "Event rejected: #{event.errors.full_messages}"
+    #   end
+    #
+    # @example Handling concurrency conflict
+    #   event = stream.append!(SomeEvent.new)
+    #   if event.errors[:base].present?
+    #     # Race condition detected, retry logic here
+    #   end
+    def append!(new_event)
+      return new_event unless new_event.valid?
+      return new_event if consistency_projection.present? &&
+                          compute_projection_with_new_event(consistency_projection, new_event).invalid?
+      begin
+        @instance_new_events << new_event.persist!(@idx, incremented_version)
+      rescue ActiveRecord::RecordNotUnique
+        new_event.errors.add(:base, I18n.t("funes.events.racing_condition_on_insert"))
+      end
+
+      run_transactional_projections
+      schedule_async_projections
+
+      new_event
+    end
+
+    # @!visibility private
+    def initialize(entity_id, as_of = nil)
+      @idx = entity_id
+      @instance_new_events = []
+      @as_of = as_of ? as_of : Time.current
+    end
+
+    # Get all events in the stream as event instances.
+    #
+    # Returns both previously persisted events (up to `as_of` timestamp) and any new events
+    # appended in this session.
+    #
+    # @return [Array<Funes::Event>] Array of event instances.
+    #
+    # @example
+    #   stream = OrderEventStream.for("order-123")
+    #   stream.events.each do |event|
+    #     puts "#{event.class.name} at #{event.created_at}"
+    #   end
+    def events
+      (previous_events + @instance_new_events).map(&:to_klass_instance)
+    end
+
+    private
+      def run_transactional_projections
+        transactional_projections.each do |projection_class|
+          Funes::PersistProjectionJob.perform_now(@idx, projection_class, last_event_creation_date)
+        end
+      end
+
+      def schedule_async_projections
+        async_projections.each do |projection|
+          as_of = resolve_as_of_strategy(projection[:as_of_strategy])
+          Funes::PersistProjectionJob.set(projection[:options]).perform_later(@idx, projection[:class], as_of)
+        end
+      end
+
+      def previous_events
+        @previous_events ||= Funes::EventEntry
+                               .where(idx: @idx, created_at: ..@as_of)
+                               .order("created_at")
+      end
+
+      def last_event_creation_date
+        (@instance_new_events.last || previous_events.last).created_at
+      end
+
+      def resolve_as_of_strategy(strategy)
+        last_event = @instance_new_events.last || previous_events.last
+
+        case strategy
+        when :last_event_time
+          last_event.created_at
+        when :job_time
+          nil  # Job will use Time.current
+        when Proc
+          result = strategy.call(last_event)
+          unless result.is_a?(Time)
+            raise ArgumentError, "Proc must return a Time object, got #{result.class}. " \
+                                 "Use :job_time symbol for job execution time behavior."
+          end
+          result
+        else
+          raise ArgumentError, "Invalid as_of strategy: #{strategy.inspect}. " \
+                               "Expected :last_event_time, :job_time, or a Proc"
+        end
+      end
+
+      def incremented_version
+        (@instance_new_events.last&.version || previous_events.last&.version || 0) + 1
+      end
+
+      def compute_projection_with_new_event(projection_class, new_event)
+        materialization = projection_class.process_events(events + [ new_event ], @as_of)
+        unless materialization.valid?
+          new_event.event_errors = new_event.errors
+          new_event.adjacent_state_errors = materialization.errors
+        end
+
+        materialization
+      end
+
+      def consistency_projection
+        self.class.instance_variable_get(:@consistency_projection) || nil
+      end
+
+      def transactional_projections
+        self.class.instance_variable_get(:@transactional_projections) || []
+      end
+
+      def async_projections
+        self.class.instance_variable_get(:@async_projections) || []
+      end
+  end
+end

data/app/helpers/funes/application_helper.rb

@@ -0,0 +1,4 @@
+module Funes
+  module ApplicationHelper
+  end
+end