acta 0.2.0 → 0.3.0

data/docs/event_driven_pub_sub.md

@@ -0,0 +1,258 @@
+# Event-driven pub/sub
+
+The simplest useful shape for an Acta app: one domain event, multiple
+independent subscribers, no event sourcing. The event is the
+publication; reactors are the subscribers; the events table is your
+audit log for free.
+
+## The scenario
+
+A user signs up. As a result, several independent things should
+happen:
+
+- A welcome email is sent.
+- An analytics service is pinged.
+- The signup is recorded in an audit log.
+
+These concerns have different owners, change at different rates, and
+fail in different ways. Coupling them in the controller (or worse, in
+an `after_create_commit` callback on the `User` model) means every
+new concern requires editing the same file, and a flaky third-party
+analytics call can roll back the user creation.
+
+With Acta:
+
+```ruby
+# app/events/user_signed_up.rb
+class UserSignedUp < Acta::Event
+  stream :user, key: :user_id
+
+  attribute :user_id, :string
+  attribute :email, :string
+  attribute :referral_code, :string
+
+  validates :user_id, :email, presence: true
+end
+```
+
+The signup path creates the AR record and emits the event in the
+same transaction:
+
+```ruby
+# app/controllers/registrations_controller.rb
+class RegistrationsController < ApplicationController
+  def create
+    ApplicationRecord.transaction do
+      user = User.create!(user_params)
+
+      Acta.emit(UserSignedUp.new(
+        user_id:       user.id,
+        email:         user.email,
+        referral_code: params[:referral_code]
+      ))
+    end
+
+    redirect_to dashboard_path
+  end
+end
+```
+
+The explicit `transaction` block is the load-bearing detail. `Acta.emit`
+opens its own inner transaction (with `requires_new: true`), which
+becomes a savepoint inside the outer one — so either the user row
+*and* the event row commit together, or neither does. Without the
+outer transaction these would be two independent commits, and a
+process crash or event validation error between them would leave
+you with a user who has no audit trail, no welcome email, and no
+analytics ping.
+
+That's it for the publisher. Each subscriber lives in its own file,
+declares what it cares about, and ignores everything else.
+
+## Subscribers
+
+```ruby
+# app/reactors/welcome_email_reactor.rb
+class WelcomeEmailReactor < Acta::Reactor
+  on UserSignedUp do |event|
+    UserMailer.welcome(event.user_id).deliver_later
+  end
+end
+```
+
+```ruby
+# app/reactors/analytics_reactor.rb
+class AnalyticsReactor < Acta::Reactor
+  on UserSignedUp do |event|
+    AnalyticsClient.track(
+      user_id: event.user_id,
+      event:   "signup",
+      props:   { referral_code: event.referral_code }
+    )
+  end
+end
+```
+
+The audit log subscriber doesn't exist as code — Acta writes every
+emitted event to the `events` table by default. Browse it at `/acta`
+(see the [Acta::Web engine][acta-web]) or query directly via
+`Acta.events`.
+
+[acta-web]: ../README.md#acta-web
+
+## What just happened
+
+Each reactor runs **after** the database commit that wrote the event,
+**asynchronously** by default (via ActiveJob). So:
+
+- Because the controller wraps both writes in
+  `ApplicationRecord.transaction`, the user row and the event row
+  commit together. If either raises, neither is persisted — no
+  welcome email to a user that doesn't exist.
+- Each reactor enqueues its own job. The welcome email and the
+  analytics ping run in parallel, isolated from each other.
+- A failing analytics call doesn't roll back the signup, doesn't
+  block the email, doesn't surface to the user. ActiveJob's retry
+  semantics apply per-reactor.
+- New subscribers are additive. To send a referral credit when a
+  signup uses a code, write a third reactor — no change to the
+  controller, the event, or the existing reactors.
+
+### A subtle caveat about reactor enqueue timing
+
+Reactors are dispatched after Acta's inner savepoint releases but
+*before* the outer transaction commits. Whether that opens a
+"reactor fired but the user write rolled back" window depends on
+your ActiveJob queue adapter:
+
+- **DB-backed queues** (Solid Queue, GoodJob, Que) — the enqueue is
+  a row insert that participates in the outer transaction. A
+  rollback un-enqueues the job. Atomic.
+- **Redis-backed queues** (Sidekiq) — the enqueue hits Redis
+  immediately and survives a rollback. Small window where the email
+  goes out but the user doesn't exist. Rails 7.2+ exposes
+  `enqueue_after_transaction_commit` to opt into deferred enqueue,
+  which closes the window.
+- **Sync reactors** (`sync!`) — run inline during dispatch. Side
+  effects (email sent, third-party API called) happen before the
+  outer commits and can't be undone by a rollback. Reach for
+  `sync!` only when the side effect is itself a DB write inside the
+  same transaction, or when "fired but rolled back" is acceptable.
+
+On the Rails 8.x + Solid Queue default stack, the right behaviour
+falls out without extra configuration.
+
+## Synchronous when you need it
+
+For tests and the rare side effect that must happen inside the same
+request, opt a reactor into sync mode:
+
+```ruby
+class CreateBillingAccountReactor < Acta::Reactor
+  sync!
+
+  on UserSignedUp do |event|
+    BillingAccount.create!(user_id: event.user_id, plan: "free")
+  end
+end
+```
+
+Sync reactors run **after-commit but in the caller's thread**. They
+still don't block the DB transaction (so they can't roll the signup
+back), but they do block the response. Reach for this when the
+follow-up state must exist before the next user action — and only
+then.
+
+## Testing
+
+Reactor tests usually just want to assert that a side effect was
+triggered. Use the matchers:
+
+```ruby
+require "acta/testing"
+require "acta/testing/matchers"
+
+RSpec.describe RegistrationsController do
+  it "publishes UserSignedUp on successful signup" do
+    expect {
+      post :create, params: { user: { email: "alice@example.com" } }
+    }.to emit(UserSignedUp).with(email: "alice@example.com")
+  end
+end
+```
+
+For the reactor itself, run it inline so the side effect actually
+fires:
+
+```ruby
+RSpec.describe WelcomeEmailReactor do
+  it "sends the welcome email" do
+    Acta::Testing.test_mode do
+      Acta.emit(UserSignedUp.new(user_id: "u_1", email: "alice@example.com"))
+    end
+
+    expect(UserMailer.deliveries.last.to).to eq([ "alice@example.com" ])
+  end
+end
+```
+
+`Acta::Testing.test_mode` runs reactors inline for the duration of
+the block, regardless of the `sync!` declaration on the class. It
+keeps reactor tests synchronous without committing the whole reactor
+to sync mode in production.
+
+## When this isn't the right shape
+
+This pattern works when the AR records (`User`, `BillingAccount`) are
+the source of truth and the events are notifications about state
+changes happening elsewhere. It does **not** make the event log the
+authoritative source of state — `User.create!` happens before any
+event is emitted, and dropping the events table doesn't recreate
+users on the next `Acta.rebuild!`.
+
+When you want the events to *be* the source of truth — when
+`Acta.rebuild!` should reproduce the projected state from the log
+alone — reach for projections instead. See the [event sourcing][es]
+pattern.
+
+[es]: ../README.md#4-project-state-event-sourced
+
+## Compared to the alternatives
+
+| | AR callbacks | `ActiveSupport::Notifications` | [Wisper][wisper] | Acta event-driven |
+|---|---|---|---|---|
+| Persistence | None | None | None | Yes — full payload, actor, timestamps |
+| Async by default | No (in tx) | No (in caller) | No (in caller); async via wisper-sidekiq | Yes (ActiveJob) |
+| Failure isolation | No (rolls back tx) | Sometimes | Subscriber errors propagate to publisher | Yes (per-reactor jobs) |
+| Replay-able | No | No | No | Yes (the events are still there) |
+| Payload typing | AR attributes | Untyped hash | Untyped args | ActiveModel-typed attributes with validations |
+| Subscriber discovery | Reading the model file | Grep the codebase for `subscribe` | Subscriber registration code | `app/reactors/` directory |
+| Test ergonomics | Stubs all the way down | Subscribe a block in spec | wisper-rspec matchers | Built-in matchers + `test_mode` |
+
+[wisper]: https://github.com/krisleech/wisper
+
+`ActiveSupport::Notifications` is the in-process, ephemeral cousin —
+fire-and-forget, no persistence, ideal for instrumentation (metrics,
+traces, logs) but a poor fit for domain events that other parts of
+the system need to react to.
+
+**Wisper** is the long-standing prior art for Rails domain pub/sub —
+publish a symbol-named event, subscribers register interest, the
+gem dispatches. It's at v3.0.0 (May 2024) with light ongoing
+maintenance; not abandoned, not actively developed either. Reach for
+Wisper when you want to decouple callbacks without buying into
+event sourcing or a persistent log: subscriptions are dynamic,
+events are untyped (any args you want), and the runtime is
+process-local. Acta differs in three load-bearing ways: events are
+**typed classes** with validated payload schemas (so a typo in a
+field name is a class-load error, not a runtime nil); subscribers
+are **after-commit + async** by default (so a flaky external API
+call doesn't roll back the publisher's transaction); and every
+publication is **persisted** in the events table (so you have an
+audit log, can replay history, and can survive a process restart
+mid-flight on a notification).
+
+The honest summary: AS::Notifications for instrumentation, Wisper
+for lightweight in-process pub/sub without persistence, Acta when
+the publication itself needs to be durable and the subscribers are
+fan-out side effects you want isolated from the request path.

data/gemfiles/rails_7_2.gemfile

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gem "activejob",     "~> 7.2.0"
+gem "activemodel",   "~> 7.2.0"
+gem "activerecord",  "~> 7.2.0"
+gem "activesupport", "~> 7.2.0"
+gem "railties",      "~> 7.2.0"
+
+group :development, :test do
+  gem "irb"
+  gem "pg", "~> 1.5"
+  gem "rake", "~> 13.0"
+  gem "rspec", "~> 3.13"
+  gem "rubocop-rails-omakase", require: false
+  gem "sqlite3", "~> 2.0"
+end
+
+gemspec path: ".."

data/gemfiles/rails_8_0.gemfile

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gem "activejob",     "~> 8.0.0"
+gem "activemodel",   "~> 8.0.0"
+gem "activerecord",  "~> 8.0.0"
+gem "activesupport", "~> 8.0.0"
+gem "railties",      "~> 8.0.0"
+
+group :development, :test do
+  gem "irb"
+  gem "pg", "~> 1.5"
+  gem "rake", "~> 13.0"
+  gem "rspec", "~> 3.13"
+  gem "rubocop-rails-omakase", require: false
+  gem "sqlite3", "~> 2.0"
+end
+
+gemspec path: ".."

data/gemfiles/rails_8_1.gemfile

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gem "activejob",     "~> 8.1.0"
+gem "activemodel",   "~> 8.1.0"
+gem "activerecord",  "~> 8.1.0"
+gem "activesupport", "~> 8.1.0"
+gem "railties",      "~> 8.1.0"
+
+group :development, :test do
+  gem "irb"
+  gem "pg", "~> 1.5"
+  gem "rake", "~> 13.0"
+  gem "rspec", "~> 3.13"
+  gem "rubocop-rails-omakase", require: false
+  gem "sqlite3", "~> 2.0"
+end
+
+gemspec path: ".."

data/lib/acta/model.rb

@@ -2,8 +2,8 @@
 
 require "active_model"
 require "active_model/attributes"
-require_relative "model_type"
-require_relative "array_type"
+require_relative "types/model"
+require_relative "types/array"
 
 module Acta
   class Model
@@ -11,15 +11,15 @@ module Acta
     include ActiveModel::Attributes
 
     # Accept:
-    # - a class as a type (Acta::Model / Acta::Serializable) — wrapped in ModelType
-    # - array_of: Class or array_of: :symbol — wrapped in ArrayType
+    # - a class as a type (Acta::Model / Acta::Serializable) — wrapped in Acta::Types::Model
+    # - array_of: Class or array_of: :symbol — wrapped in Acta::Types::Array
     # - standard symbol types (:string, :integer, ...) — forwarded to AM
     def self.attribute(name, type = nil, array_of: nil, **options)
       if array_of
         element = element_type_for(array_of)
-        type = Acta::ArrayType.new(element)
+        type = Acta::Types::Array.new(element)
       elsif type.is_a?(Class)
-        type = Acta::ModelType.new(type)
+        type = Acta::Types::Model.new(type)
       end
 
       if type.nil?
@@ -31,7 +31,7 @@ module Acta
 
     def self.element_type_for(target)
       case target
-      when Class then Acta::ModelType.new(target)
+      when Class then Acta::Types::Model.new(target)
       when Symbol then ActiveModel::Type.lookup(target)
       else target
       end

data/lib/acta/reactor.rb

@@ -10,6 +10,28 @@ module Acta
       def sync?
         @sync == true
       end
+
+      # Declares the ActiveJob queue name to enqueue this reactor's job on.
+      # Read by Acta's dispatcher when the reactor is async (the default);
+      # ignored for `sync!` reactors. With no per-class declaration, the
+      # global `Acta.reactor_queue` setting applies; if that's also unset,
+      # ActiveJob's `:default` queue is used.
+      #
+      #   class WelcomeEmailReactor < Acta::Reactor
+      #     queue_as :fast
+      #     on UserSignedUp do |event|
+      #       UserMailer.welcome(event.user_id).deliver_later
+      #     end
+      #   end
+      def queue_as(name)
+        @queue_name = name
+      end
+
+      def queue_name
+        return @queue_name if defined?(@queue_name)
+
+        Acta.reactor_queue
+      end
     end
   end
 end

data/lib/acta/testing.rb

@@ -6,6 +6,26 @@ module Acta
   module Testing
     DEFAULT_ACTOR_ATTRIBUTES = { type: "system", id: "rspec", source: "test" }.freeze
 
+    # Wraps writes to `acta_managed!` AR models so the projection-write guard
+    # accepts them. Useful for fixtures, factories, and ad-hoc setup that
+    # needs to bypass the command + event + projection chain.
+    #
+    #   # spec/rails_helper.rb
+    #   require "acta/testing"
+    #   RSpec.configure do |config|
+    #     Acta::Testing.projection_writes_helper!(config)
+    #   end
+    #
+    #   # in any spec:
+    #   with_projection_writes do
+    #     Trail.create!(name: "Crank It Up", zone: zone)
+    #   end
+    module ProjectionWritesHelpers
+      def with_projection_writes(&block)
+        Acta::Projection.applying!(&block)
+      end
+    end
+
     module_function
 
     # Runs the given block with ActiveJob's :inline adapter, so async
@@ -46,5 +66,18 @@ module Acta
         Acta::Current.reset
       end
     end
+
+    # Includes `with_projection_writes` into every RSpec example. The helper
+    # forwards to `Acta::Projection.applying!`, so blocks under it pass the
+    # `acta_managed!` write guard. See ProjectionWritesHelpers.
+    #
+    #   # spec/rails_helper.rb
+    #   require "acta/testing"
+    #   RSpec.configure do |config|
+    #     Acta::Testing.projection_writes_helper!(config)
+    #   end
+    def projection_writes_helper!(config)
+      config.include(ProjectionWritesHelpers)
+    end
   end
 end

data/lib/acta/types/array.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "active_model/type"
+
+module Acta
+  module Types
+    # Wraps any other Acta type as a list-of-element type. Used internally
+    # by `attribute :foo, array_of: Class` (or `array_of: :symbol`); not
+    # constructed directly by consumers.
+    class Array < ActiveModel::Type::Value
+      def initialize(element_type)
+        super()
+        @element_type = element_type
+      end
+
+      def cast(value)
+        return nil if value.nil?
+
+        Kernel.Array(value).map { |el| @element_type.cast(el) }
+      end
+
+      def serialize(value)
+        return nil if value.nil?
+
+        value.map { |el| @element_type.serialize(el) }
+      end
+
+      def deserialize(value)
+        return nil if value.nil?
+
+        value.map { |el| @element_type.deserialize(el) }
+      end
+    end
+  end
+end

data/lib/acta/types/model.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "active_model/type"
+
+module Acta
+  module Types
+    # Wraps an Acta::Model subclass (or any class with `to_acta_hash` /
+    # `from_acta_hash`, e.g. AR classes that include Acta::Serializable)
+    # so it can be used as an `attribute` type on another Acta::Model.
+    # The wrapping is automatic — `attribute :location, GeoPoint` invokes
+    # this internally; consumers don't construct it directly.
+    class Model < ActiveModel::Type::Value
+      def initialize(wrapped_class)
+        super()
+        @wrapped_class = wrapped_class
+      end
+
+      def cast(value)
+        case value
+        when nil then nil
+        when @wrapped_class then value
+        when Hash then @wrapped_class.from_acta_hash(value)
+        else
+          raise ArgumentError, "Cannot cast #{value.class} (#{value.inspect}) to #{@wrapped_class}"
+        end
+      end
+
+      def serialize(value)
+        return nil if value.nil?
+
+        value.to_acta_hash
+      end
+
+      def deserialize(value)
+        cast(value)
+      end
+    end
+  end
+end

data/lib/acta/version.rb

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

data/lib/acta.rb

@@ -26,6 +26,18 @@ ActiveSupport.on_load(:active_record) do
 end
 
 module Acta
+  # Global default for `Acta::Reactor` ActiveJob queue. Per-class
+  # `queue_as :foo` declarations on a Reactor override this. Apps with
+  # queue priority discipline typically set this to e.g. `:fast` in an
+  # initializer; left nil, ActiveJob's `:default` queue is used.
+  class << self
+    attr_writer :reactor_queue
+  end
+
+  def self.reactor_queue
+    @reactor_queue
+  end
+
   def self.adapter
     @adapter ||= Adapters.for(Record.connection)
   end
@@ -117,7 +129,10 @@ module Acta
         event:,
         reactor_class: registration[:handler_class]
       ) do
-        ReactorJob.perform_later(
+        job = ReactorJob
+        queue = registration[:handler_class].queue_name
+        job = job.set(queue: queue) if queue
+        job.perform_later(
           event_uuid: event.uuid,
           reactor_class: registration[:handler_class].name,
           event_class: event.class.name

data/lib/generators/acta/install/install_generator.rb

@@ -1,22 +1,22 @@
 # frozen_string_literal: true
 
 require "rails/generators"
-require "rails/generators/migration"
 require "rails/generators/active_record"
+require "rails/generators/active_record/migration"
 
 module Acta
   module Generators
     class InstallGenerator < Rails::Generators::Base
-      include Rails::Generators::Migration
+      include ActiveRecord::Generators::Migration
 
       source_root File.expand_path("templates", __dir__)
 
-      def self.next_migration_number(path)
-        ActiveRecord::Generators::Base.next_migration_number(path)
-      end
+      class_option :database, type: :string, aliases: %i[--db],
+                   desc: "The database for the events migration. By default, the current environment's primary database is used."
 
       def create_migration_file
-        migration_template "create_acta_events.rb.tt", "db/migrate/create_acta_events.rb"
+        migration_template "create_acta_events.rb.tt",
+                           File.join(db_migrate_path, "create_acta_events.rb")
       end
     end
   end