acta 0.2.0

data/lib/acta/projection_managed.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Acta
+  # Marks an ActiveRecord model as projection-managed: its rows are
+  # maintained by an Acta::Projection from the event log, so writes from
+  # anywhere else (controllers, console, rake tasks, callbacks on other
+  # models) bypass the log and break Acta.rebuild!'s determinism.
+  #
+  # Opt in with `acta_managed!` on the AR class:
+  #
+  #   class Trail < ApplicationRecord
+  #     acta_managed!   # raise on out-of-band writes
+  #   end
+  #
+  #   class TrailAlias < ApplicationRecord
+  #     acta_managed! on_violation: :warn   # warn instead, for incremental migration
+  #   end
+  #
+  # Inside an `Acta::Projection` `on EventClass do |e| ... end` block (or
+  # during `Acta.rebuild!`'s truncate phase), `Acta::Projection.applying?`
+  # is true and writes are allowed. Outside, they raise
+  # `Acta::ProjectionWriteError` (or warn if so configured).
+  #
+  # Tests, migrations, and one-off backfills can wrap intentional
+  # out-of-band writes in `Acta::Projection.applying! { ... }` to bypass
+  # the safety net explicitly.
+  module ProjectionManaged
+    extend ActiveSupport::Concern
+
+    GUARDED_CLASS_METHODS = %i[
+      update_all
+      delete_all
+      insert
+      insert!
+      insert_all
+      insert_all!
+      upsert
+      upsert_all
+    ].freeze
+
+    GUARDED_INSTANCE_METHODS = %i[
+      update_columns
+      update_column
+    ].freeze
+
+    VALID_VIOLATION_ACTIONS = %i[ raise warn ].freeze
+
+    class_methods do
+      def acta_managed!(on_violation: :raise)
+        unless VALID_VIOLATION_ACTIONS.include?(on_violation)
+          raise ArgumentError,
+                "acta_managed! on_violation must be one of #{VALID_VIOLATION_ACTIONS.inspect}, got #{on_violation.inspect}"
+        end
+
+        @acta_on_violation = on_violation
+
+        before_save     :_acta_assert_projection_applying!
+        before_destroy  :_acta_assert_projection_applying!
+
+        singleton_class.prepend(ClassWriteGuards)
+      end
+
+      def acta_managed?
+        !@acta_on_violation.nil?
+      end
+
+      def acta_on_violation
+        @acta_on_violation
+      end
+    end
+
+    module ClassWriteGuards
+      ProjectionManaged::GUARDED_CLASS_METHODS.each do |method|
+        define_method(method) do |*args, **kwargs, &block|
+          ProjectionManaged.assert_projection_applying!(self, method)
+          super(*args, **kwargs, &block)
+        end
+      end
+    end
+
+    GUARDED_INSTANCE_METHODS.each do |method|
+      define_method(method) do |*args, **kwargs, &block|
+        ProjectionManaged.assert_projection_applying!(self.class, method)
+        super(*args, **kwargs, &block)
+      end
+    end
+
+    def self.assert_projection_applying!(model_class, write_method)
+      return if Acta::Projection.applying?
+
+      action = model_class.acta_on_violation
+      case action
+      when :raise
+        raise Acta::ProjectionWriteError.new(model_class:, write_method:)
+      when :warn
+        warn "[acta] #{Acta::ProjectionWriteError.new(model_class:, write_method:).message}"
+      end
+    end
+
+    private
+
+    def _acta_assert_projection_applying!
+      ProjectionManaged.assert_projection_applying!(self.class, :save)
+    end
+  end
+end

data/lib/acta/railtie.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module Acta
+  # Forces projection / handler / reactor classes to load at boot, so they can
+  # register themselves with Acta before the first event is emitted.
+  #
+  # Without this, Zeitwerk lazy-loads them on first reference. A projection that
+  # nothing has touched yet is silently unsubscribed — emits succeed, the event
+  # row is written, but the projection never runs and the read model goes stale.
+  # No error, no warning. See https://github.com/whoojemaflip/acta/issues/7.
+  #
+  # Configurable via `config.acta.{projection,handler,reactor}_paths` if your app
+  # puts subscribers somewhere other than the conventional `app/projections`,
+  # `app/handlers`, `app/reactors`. Set a path list to `[]` to opt out.
+  class Railtie < ::Rails::Railtie
+    DEFAULT_PROJECTION_PATHS = %w[app/projections].freeze
+    DEFAULT_HANDLER_PATHS    = %w[app/handlers].freeze
+    DEFAULT_REACTOR_PATHS    = %w[app/reactors].freeze
+
+    config.acta = ActiveSupport::OrderedOptions.new
+
+    initializer "acta.subscriber_path_defaults" do |app|
+      cfg = app.config.acta
+      cfg.projection_paths = DEFAULT_PROJECTION_PATHS.dup if cfg.projection_paths.nil?
+      cfg.handler_paths    = DEFAULT_HANDLER_PATHS.dup    if cfg.handler_paths.nil?
+      cfg.reactor_paths    = DEFAULT_REACTOR_PATHS.dup    if cfg.reactor_paths.nil?
+    end
+
+    initializer "acta.eager_load_subscribers" do |app|
+      app.config.to_prepare do
+        Acta::Railtie.eager_load_subscribers!(app)
+      end
+    end
+
+    def self.eager_load_subscribers!(app)
+      subscriber_paths(app).each { |path| eager_load_path(path) }
+    end
+
+    def self.subscriber_paths(app)
+      cfg = app.config.acta
+      relative = [ *cfg.projection_paths, *cfg.handler_paths, *cfg.reactor_paths ].compact.uniq
+      relative.map { |path| app.root.join(path).to_s }.select { |path| Dir.exist?(path) }
+    end
+
+    def self.eager_load_path(path)
+      if rails_zeitwerk_loader_for(path)&.respond_to?(:eager_load_dir)
+        rails_zeitwerk_loader_for(path).eager_load_dir(path)
+      else
+        Dir.glob(File.join(path, "**/*.rb")).sort.each { |file| require file }
+      end
+    end
+
+    def self.rails_zeitwerk_loader_for(path)
+      return nil unless defined?(::Rails) && ::Rails.respond_to?(:autoloaders)
+
+      autoloaders = ::Rails.autoloaders
+      [ autoloaders.main, autoloaders.once ].compact.find do |loader|
+        loader.respond_to?(:dirs) && loader.dirs.any? { |dir| path == dir || path.start_with?("#{dir}/") }
+      end
+    end
+    private_class_method :rails_zeitwerk_loader_for
+  end
+end

data/lib/acta/reactor.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Acta
+  class Reactor < Handler
+    class << self
+      def sync!
+        @sync = true
+      end
+
+      def sync?
+        @sync == true
+      end
+    end
+  end
+end

data/lib/acta/reactor_job.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "active_job"
+
+module Acta
+  class ReactorJob < ActiveJob::Base
+    def perform(event_uuid:, reactor_class:, event_class:)
+      event = Acta.events.find_by_uuid(event_uuid)
+      return unless event
+
+      reactor = Object.const_get(reactor_class)
+      ev_class = Object.const_get(event_class)
+
+      Acta.handlers[ev_class]
+        .select { |r| r[:handler_class] == reactor && r[:kind] == :reactor }
+        .each { |r| r[:block].call(event) }
+    end
+  end
+end

data/lib/acta/record.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "active_record"
+
+module Acta
+  class Record < ActiveRecord::Base
+    self.table_name = "events"
+    self.inheritance_column = nil
+  end
+end

data/lib/acta/schema.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Acta
+  module Schema
+    TABLE_NAME = :events
+
+    def self.install(connection, table_name: TABLE_NAME)
+      adapter = Acta::Adapters.for(connection)
+      adapter.install_schema(connection, table_name:)
+    end
+  end
+end

data/lib/acta/serializable.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Acta
+  module Serializable
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def acta_serialize(except: nil, only: nil)
+        raise ArgumentError, "acta_serialize: pass only one of except: or only:" if except && only
+
+        @acta_serialize_options = {
+          except: except&.map(&:to_s),
+          only: only&.map(&:to_s)
+        }
+      end
+
+      def acta_serialize_options
+        @acta_serialize_options ||= { except: nil, only: nil }
+      end
+
+      def from_acta_hash(hash)
+        return nil if hash.nil?
+
+        known = column_names
+        filtered = hash.each_with_object({}) do |(key, value), acc|
+          name = key.to_s
+          acc[name.to_sym] = value if known.include?(name)
+        end
+        new(**filtered)
+      end
+    end
+
+    def to_acta_hash
+      opts = self.class.acta_serialize_options
+      hash = attributes
+
+      if opts[:only]
+        hash.slice(*opts[:only])
+      elsif opts[:except]
+        hash.except(*opts[:except])
+      else
+        hash
+      end
+    end
+  end
+end

data/lib/acta/testing/dsl.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Acta
+  module Testing
+    module DSL
+      # Seed prior events. Anything emitted inside the block is treated as
+      # pre-existing history; the baseline is set after the block runs so
+      # subsequent assertions only see events from the 'when' phase.
+      def given_events(&block)
+        block.call if block
+        @_acta_baseline_count = Acta::Record.count
+      end
+
+      # Invoke a command instance and capture what it emitted.
+      def when_command(command)
+        @_acta_baseline_count ||= Acta::Record.count
+        command.call
+        @_acta_emitted_events = Acta.events.all.drop(@_acta_baseline_count)
+        @_acta_matched_events = []
+      end
+
+      # Evaluate a block that emits events, capturing them for assertions.
+      def when_event(&block)
+        @_acta_baseline_count ||= Acta::Record.count
+        block.call
+        @_acta_emitted_events = Acta.events.all.drop(@_acta_baseline_count)
+        @_acta_matched_events = []
+      end
+
+      # Assert that at least one of the captured events matches the class
+      # and attributes. Marks the matched event so `then_emitted_nothing_else`
+      # can verify the remainder.
+      def then_emitted(event_class, **attributes)
+        @_acta_matched_events ||= []
+        event = @_acta_emitted_events.find do |e|
+          e.is_a?(event_class) &&
+            attributes.all? { |k, v| e.public_send(k) == v } &&
+            !@_acta_matched_events.include?(e)
+        end
+
+        emitted_classes = @_acta_emitted_events.map(&:class).inspect
+        expect(event).not_to(
+          be_nil,
+          "expected emission of #{event_class} matching #{attributes.inspect}, but emitted: #{emitted_classes}"
+        )
+
+        @_acta_matched_events << event
+      end
+
+      # Assert no emissions remain unmatched.
+      def then_emitted_nothing_else
+        @_acta_matched_events ||= []
+        remaining = @_acta_emitted_events - @_acta_matched_events
+        expect(remaining).to(
+          be_empty,
+          "expected no further emissions, but also emitted: #{remaining.map(&:class).inspect}"
+        )
+      end
+
+      # Run the block with a different Acta::Current.actor, restoring the
+      # previous actor afterward (even if the block raises). Useful for
+      # asserting an emit attributes the right user when the surrounding
+      # spec's default actor would otherwise overwrite it.
+      def with_actor(**attributes)
+        previous = Acta::Current.actor
+        Acta::Current.actor = Acta::Actor.new(**attributes)
+        yield
+      ensure
+        Acta::Current.actor = previous
+      end
+
+      # Assert that running Acta.rebuild! twice produces the same projected
+      # state. The block returns a snapshot of the relevant state (whatever
+      # the app considers authoritative for this projection).
+      def ensure_replay_deterministic(&snapshot)
+        Acta.rebuild!
+        first = snapshot.call
+        Acta.rebuild!
+        second = snapshot.call
+
+        expect(second).to(
+          eq(first),
+          "replay is not deterministic\n" \
+          "first pass:  #{first.inspect}\n" \
+          "second pass: #{second.inspect}"
+        )
+      end
+    end
+  end
+end

data/lib/acta/testing/matchers.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "rspec/expectations"
+
+RSpec::Matchers.define :emit do |event_class|
+  supports_block_expectations
+
+  match do |block|
+    before_count = Acta::Record.count
+    block.call
+    @actual_events = Acta.events.all.drop(before_count)
+
+    matching = @actual_events.select { |event| event.is_a?(event_class) }
+
+    if @expected_attributes
+      @matching_event = matching.find do |event|
+        @expected_attributes.all? { |k, v| event.public_send(k) == v }
+      end
+      !@matching_event.nil?
+    else
+      !matching.empty?
+    end
+  end
+
+  chain :with do |attributes|
+    @expected_attributes = attributes
+  end
+
+  failure_message do
+    detail = if @expected_attributes
+               "#{event_class} with attributes #{@expected_attributes.inspect}"
+    else
+               event_class.to_s
+    end
+    "expected block to emit #{detail}, but emitted: #{@actual_events.map(&:class).inspect}"
+  end
+
+  failure_message_when_negated do
+    "expected block not to emit #{event_class}, but emitted: #{@actual_events.map(&:class).inspect}"
+  end
+end
+
+RSpec::Matchers.define :emit_events do |expected_classes|
+  supports_block_expectations
+
+  match do |block|
+    before_count = Acta::Record.count
+    block.call
+    @actual_events = Acta.events.all.drop(before_count)
+    @actual_classes = @actual_events.map(&:class)
+
+    @actual_classes == expected_classes
+  end
+
+  failure_message do
+    "expected block to emit events #{expected_classes.inspect} in order, but emitted: #{@actual_classes.inspect}"
+  end
+end
+
+RSpec::Matchers.define :emit_any_events do
+  supports_block_expectations
+
+  match do |block|
+    before_count = Acta::Record.count
+    block.call
+    @actual_events = Acta.events.all.drop(before_count)
+    !@actual_events.empty?
+  end
+
+  failure_message do
+    "expected block to emit events, but emitted none"
+  end
+
+  failure_message_when_negated do
+    "expected block not to emit events, but emitted: #{@actual_events.map(&:class).inspect}"
+  end
+end

data/lib/acta/testing.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "active_job"
+
+module Acta
+  module Testing
+    DEFAULT_ACTOR_ATTRIBUTES = { type: "system", id: "rspec", source: "test" }.freeze
+
+    module_function
+
+    # Runs the given block with ActiveJob's :inline adapter, so async
+    # reactors run synchronously in the caller's thread. Restores the
+    # original adapter when the block returns (or raises).
+    def test_mode
+      original = ActiveJob::Base.queue_adapter
+      ActiveJob::Base.queue_adapter = :inline
+      yield
+    ensure
+      ActiveJob::Base.queue_adapter = original
+    end
+
+    # Configures RSpec to set Acta::Current.actor before every example, so
+    # specs that emit (directly or via a command) don't trip Acta::MissingActor.
+    # Resets Acta::Current after each example so state doesn't leak.
+    #
+    #   # spec/rails_helper.rb
+    #   require "acta/testing"
+    #   RSpec.configure do |config|
+    #     Acta::Testing.default_actor!(config)
+    #   end
+    #
+    # Override the default actor's attributes per project:
+    #
+    #   Acta::Testing.default_actor!(config, type: "user", id: "test-user-1", source: "spec")
+    #
+    # Individual specs can still override Acta::Current.actor inline (or
+    # use Acta::Testing::DSL#with_actor for a scoped override).
+    def default_actor!(config, **attributes)
+      attrs = DEFAULT_ACTOR_ATTRIBUTES.merge(attributes)
+
+      config.before(:each) do
+        Acta::Current.actor = Acta::Actor.new(**attrs)
+      end
+
+      config.after(:each) do
+        Acta::Current.reset
+      end
+    end
+  end
+end

data/lib/acta/types/encrypted_string.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "active_model/type"
+require "zlib"
+require "active_record/encryption"
+
+module Acta
+  module Types
+    # Per-attribute opt-in encryption for event payloads. Declare with
+    # `attribute :token, :encrypted_string` (or pass an instance directly).
+    #
+    # Encryption uses Rails' built-in ActiveRecord::Encryption — the same
+    # primary/deterministic/derivation keys configured for AR-encrypted
+    # columns. Configure once via `bin/rails db:encryption:init` and
+    # Rails credentials; key rotation works the same way (append a new
+    # primary, keep old keys for decryption).
+    #
+    # In-memory values are always plaintext: `event.token` returns the
+    # raw secret. The encrypted form only appears in the serialized
+    # payload that's written to the events table.
+    class EncryptedString < ActiveModel::Type::Value
+      def initialize(deterministic: false)
+        super()
+        @deterministic = deterministic
+      end
+
+      def cast(value)
+        return nil if value.nil?
+
+        value.to_s
+      end
+
+      def serialize(value)
+        return nil if value.nil?
+
+        encryptor.encrypt(value.to_s, **encrypt_options)
+      end
+
+      def deserialize(value)
+        return nil if value.nil?
+
+        str = value.to_s
+        return str unless encryptor.encrypted?(str)
+
+        encryptor.decrypt(str)
+      end
+
+      private
+
+      def encryptor
+        ActiveRecord::Encryption.encryptor
+      end
+
+      def encrypt_options
+        return {} unless @deterministic
+
+        { key_provider: ActiveRecord::Encryption.deterministic_key_provider }
+      end
+    end
+  end
+end
+
+ActiveModel::Type.register(:encrypted_string, Acta::Types::EncryptedString)

data/lib/acta/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Acta
+  VERSION = "0.2.0"
+end

data/lib/acta/web/engine.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+require "action_dispatch" # isolate_namespace references ActionDispatch::Routing
+
+module Acta
+  module Web
+    class Engine < ::Rails::Engine
+      engine_name "acta_web"
+      isolate_namespace Acta::Web
+    end
+  end
+end

data/lib/acta/web/events_query.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Acta
+  module Web
+    # Builds the filtered Acta::Record scope that drives the event log
+    # admin UI. Extracted from EventsController so it can be unit-tested
+    # without a Rails-app fixture, and reused if other admin surfaces want
+    # the same filter semantics.
+    #
+    # All filter values are user-supplied. String LIKE values are passed
+    # through ActiveRecord::Base.sanitize_sql_like to neutralise %/_
+    # wildcards in user input.
+    class EventsQuery
+      # Names of params accepted; used by callers to build current-filter
+      # views and by tests to check the param surface.
+      FILTER_KEYS = %i[event_type stream_type actor_id stream_key q].freeze
+
+      def initialize(params = {})
+        @event_type  = presence(params[:event_type])
+        @stream_type = presence(params[:stream_type])
+        @actor_id    = presence(params[:actor_id])
+        @stream_key  = presence(params[:stream_key])
+        @q           = presence(params[:q])
+      end
+
+      # Returns an unloaded ActiveRecord::Relation over Acta::Record with
+      # the configured filters applied. Caller is responsible for ordering,
+      # offset, limit, and any further scope chaining.
+      def scope
+        scope = Acta::Record.all
+        scope = scope.where(event_type: @event_type)   if @event_type
+        scope = scope.where(stream_type: @stream_type) if @stream_type
+        scope = scope.where(actor_id: @actor_id)       if @actor_id
+        scope = apply_stream_key(scope)                if @stream_key
+        scope = apply_q(scope)                         if @q
+        scope
+      end
+
+      # Returns only the filters that are actually present, with symbol keys.
+      # Useful to build filter-chip UIs.
+      def active_filters
+        {
+          event_type: @event_type,
+          stream_type: @stream_type,
+          actor_id: @actor_id,
+          stream_key: @stream_key,
+          q: @q
+        }.compact
+      end
+
+      private
+
+      def presence(value)
+        return nil if value.nil?
+
+        s = value.to_s
+        s.empty? ? nil : s
+      end
+
+      # ActiveRecord::Base.sanitize_sql_like escapes %, _, and \ by prefixing
+      # with \. The LIKE clause must declare ESCAPE '\\' for those escapes to
+      # take effect — otherwise the sanitized backslash is treated as a
+      # literal character and user-supplied wildcards continue to match.
+      LIKE_ESCAPE = "\\".freeze
+
+      def apply_stream_key(scope)
+        sanitized = ActiveRecord::Base.sanitize_sql_like(@stream_key)
+        scope.where("stream_key LIKE ? ESCAPE ?", "%#{sanitized}%", LIKE_ESCAPE)
+      end
+
+      def apply_q(scope)
+        sanitized = ActiveRecord::Base.sanitize_sql_like(@q)
+        like = "%#{sanitized}%"
+        scope.where(
+          "(event_type LIKE :q ESCAPE :e OR stream_type LIKE :q ESCAPE :e OR stream_key LIKE :q ESCAPE :e OR actor_id LIKE :q ESCAPE :e OR source LIKE :q ESCAPE :e)",
+          q: like, e: LIKE_ESCAPE,
+        )
+      end
+    end
+  end
+end