acta 0.2.0

data/lib/acta/adapters/postgres.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Acta
+  module Adapters
+    class Postgres < Base
+      def uuid_column_type
+        :uuid
+      end
+
+      def json_column_type
+        :jsonb
+      end
+
+      def insert_event(attributes)
+        stream_type = attributes[:stream_type]
+        stream_key = attributes[:stream_key]
+
+        if stream_type && stream_key
+          insert_streamed(attributes, stream_type:, stream_key:)
+        else
+          Acta::Record.create!(**attributes)
+        end
+      end
+
+      def fetch_records
+        Acta::Record.order(:id)
+      end
+
+      private
+
+      def insert_streamed(attributes, stream_type:, stream_key:)
+        Acta::Record.transaction(requires_new: true) do
+          acquire_stream_lock(stream_type, stream_key)
+          sequence = compute_next_sequence(stream_type, stream_key)
+          Acta::Record.create!(**attributes, stream_sequence: sequence)
+        end
+      rescue ActiveRecord::RecordNotUnique => e
+        raise unless stream_conflict?(e)
+
+        actual = current_stream_max(stream_type, stream_key) || 0
+        raise Acta::VersionConflict.new(
+          stream_type:,
+          stream_key:,
+          expected_version: actual + 1,
+          actual_version: actual
+        )
+      end
+
+      def acquire_stream_lock(stream_type, stream_key)
+        key = "#{stream_type}:#{stream_key}"
+        Acta::Record.connection.execute(
+          "SELECT pg_advisory_xact_lock(hashtext(#{ActiveRecord::Base.connection.quote(key)}))"
+        )
+      end
+
+      def compute_next_sequence(stream_type, stream_key)
+        (current_stream_max(stream_type, stream_key) || 0) + 1
+      end
+
+      def current_stream_max(stream_type, stream_key)
+        Acta::Record
+          .where(stream_type:, stream_key:)
+          .maximum(:stream_sequence)
+      end
+
+      def stream_conflict?(error)
+        message = error.message
+        message.include?("stream_sequence") ||
+          message.include?("index_events_on_stream_identity")
+      end
+    end
+  end
+end

data/lib/acta/adapters/sqlite.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Acta
+  module Adapters
+    class SQLite < Base
+      def insert_event(attributes)
+        stream_type = attributes[:stream_type]
+        stream_key = attributes[:stream_key]
+
+        if stream_type && stream_key
+          insert_streamed(attributes, stream_type:, stream_key:)
+        else
+          Acta::Record.create!(**attributes)
+        end
+      end
+
+      def fetch_records
+        Acta::Record.order(:id)
+      end
+
+      private
+
+      def insert_streamed(attributes, stream_type:, stream_key:)
+        sequence = compute_next_sequence(stream_type, stream_key)
+
+        Acta::Record.transaction(requires_new: true) do
+          Acta::Record.create!(**attributes, stream_sequence: sequence)
+        end
+      rescue ActiveRecord::RecordNotUnique => e
+        raise unless stream_conflict?(e)
+
+        actual = current_stream_max(stream_type, stream_key) || 0
+        raise Acta::VersionConflict.new(
+          stream_type:,
+          stream_key:,
+          expected_version: sequence,
+          actual_version: actual
+        )
+      end
+
+      def compute_next_sequence(stream_type, stream_key)
+        (current_stream_max(stream_type, stream_key) || 0) + 1
+      end
+
+      def current_stream_max(stream_type, stream_key)
+        Acta::Record
+          .where(stream_type:, stream_key:)
+          .maximum(:stream_sequence)
+      end
+
+      def stream_conflict?(error)
+        message = error.message
+        message.include?("stream_sequence") ||
+          message.include?("index_events_on_stream_identity")
+      end
+    end
+  end
+end

data/lib/acta/adapters.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "adapters/base"
+require_relative "adapters/sqlite"
+require_relative "adapters/postgres"
+
+module Acta
+  module Adapters
+    def self.for(connection)
+      name = connection.adapter_name.downcase
+      case name
+      when /sqlite/ then SQLite.new
+      when /postgres/, /postgis/ then Postgres.new
+      else
+        raise AdapterError, "No Acta adapter for #{name.inspect}"
+      end
+    end
+  end
+end

data/lib/acta/array_type.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "active_model/type"
+
+module Acta
+  class ArrayType < ActiveModel::Type::Value
+    def initialize(element_type)
+      super()
+      @element_type = element_type
+    end
+
+    def cast(value)
+      return nil if value.nil?
+
+      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

data/lib/acta/command.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Acta
+  class Command < Model
+    class << self
+      alias_method :param, :attribute
+
+      # Instantiate the command with the given params, run it, and return
+      # the command instance. Callers that need to know what the command
+      # emitted read it back off the instance:
+      #
+      #   cmd = CreateOrder.call(customer_id: "c_1")
+      #   cmd.emitted_events                              # => [<OrderCreated …>]
+      #   cmd.emitted_events.find { _1.is_a?(OrderCreated) }.order_id
+      #
+      # Returning the instance keeps the framework honest about
+      # multiplicity — commands can emit zero, one, or many events, and
+      # the caller (who knows the domain) picks what matters. The
+      # framework does not invent a "primary" event.
+      def call(**params)
+        instance = new(**params)
+        instance.call
+        instance
+      end
+    end
+
+    def initialize(**params)
+      super
+      raise InvalidCommand, self unless valid?
+    end
+
+    # Emit an event. Pass `if_version:` to assert the stream's current
+    # high-water mark for optimistic locking — see Acta.version_of.
+    def emit(event, if_version: nil)
+      Acta.emit(event, if_version: if_version)
+      emitted_events << event
+      event
+    end
+
+    # Every event emitted during this command instance's invocation, in
+    # the order `emit` was called. Empty until #call runs; cascading
+    # commands invoked from inside #call produce events in their own
+    # instances, not this one.
+    def emitted_events
+      @emitted_events ||= []
+    end
+  end
+end

data/lib/acta/current.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/current_attributes"
+
+module Acta
+  class Current < ActiveSupport::CurrentAttributes
+    attribute :actor
+  end
+end

data/lib/acta/errors.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Acta
+  class Error < StandardError; end
+
+  class InvalidEvent < Error
+    attr_reader :event
+
+    def initialize(event)
+      @event = event
+      super("Event is invalid: #{event.errors.full_messages.join(', ')}")
+    end
+  end
+
+  class CommandError < Error; end
+
+  class InvalidCommand < CommandError
+    attr_reader :command
+
+    def initialize(command)
+      @command = command
+      super("Command #{command.class} is invalid: #{command.errors.full_messages.join(', ')}")
+    end
+  end
+
+  class ProjectionError < Error
+    attr_reader :event, :projection_class, :original
+
+    def initialize(event:, projection_class:, original:)
+      @event = event
+      @projection_class = projection_class
+      @original = original
+      super("Projection #{projection_class} failed on #{event.event_type}: #{original.message}")
+    end
+  end
+
+  class VersionConflict < Error
+    attr_reader :stream_type, :stream_key, :expected_version, :actual_version
+
+    def initialize(stream_type:, stream_key:, expected_version:, actual_version:)
+      @stream_type = stream_type
+      @stream_key = stream_key
+      @expected_version = expected_version
+      @actual_version = actual_version
+      super(
+        "Version conflict on stream #{stream_type}/#{stream_key}: " \
+        "expected version #{expected_version}, stream is at version #{actual_version}"
+      )
+    end
+  end
+
+  class MissingActor < Error; end
+  class ConfigurationError < Error; end
+  class AdapterError < Error; end
+
+  class UnknownEventType < Error
+    attr_reader :event_type
+
+    def initialize(event_type)
+      @event_type = event_type
+      super("Unknown event type #{event_type.inspect} — class is not loaded")
+    end
+  end
+
+  class ReplayError < Error
+    attr_reader :record, :original
+
+    def initialize(record:, original:)
+      @record = record
+      @original = original
+      super("Replay failed on event id=#{record.id} uuid=#{record.uuid} (#{record.event_type}): #{original.message}")
+    end
+  end
+
+  class TruncateOrderError < Error
+    attr_reader :projections
+
+    def initialize(projections)
+      @projections = projections
+      super(
+        "Cannot determine a safe truncate order for projections #{projections.map(&:name).inspect} — " \
+        "their declared `truncates` classes form a foreign-key cycle. " \
+        "Either break the cycle or have one projection truncate the other's tables itself."
+      )
+    end
+  end
+
+  class ProjectionWriteError < Error
+    attr_reader :model_class, :write_method
+
+    def initialize(model_class:, write_method:)
+      @model_class = model_class
+      @write_method = write_method
+      super(
+        "Direct #{write_method} on #{model_class.name} bypasses the event log. " \
+        "#{model_class.name} is acta_managed! — its rows are owned by an Acta::Projection. " \
+        "Emit an event so the projection can update the row, or wrap intentional " \
+        "out-of-band writes in `Acta::Projection.applying! { ... }` (fixtures, migrations, backfills)."
+      )
+    end
+  end
+end

data/lib/acta/event.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "active_support/core_ext/time"
+
+module Acta
+  class Event < Model
+    attr_accessor :uuid, :occurred_at, :recorded_at, :actor
+
+    ENVELOPE_KEYS = %i[ uuid occurred_at recorded_at actor ].freeze
+
+    def initialize(**attrs)
+      envelope = attrs.slice(*ENVELOPE_KEYS)
+      payload = attrs.except(*ENVELOPE_KEYS)
+
+      @uuid = envelope[:uuid] || SecureRandom.uuid
+      @occurred_at = envelope[:occurred_at] || Time.current
+      @recorded_at = envelope[:recorded_at]
+      @actor = envelope.key?(:actor) ? envelope[:actor] : Acta::Current.actor
+
+      super(**payload)
+
+      raise InvalidEvent, self unless valid?
+    end
+
+    def event_type
+      self.class.event_type
+    end
+
+    def event_version
+      self.class.event_version
+    end
+
+    def payload_hash
+      to_acta_hash
+    end
+
+    def self.event_type
+      name
+    end
+
+    def self.event_version
+      1
+    end
+
+    def self.stream(type, key:)
+      @stream_type = type.to_s
+      @stream_key_attribute = key
+    end
+
+    class << self
+      attr_reader :stream_type, :stream_key_attribute
+    end
+
+    def stream_type
+      self.class.stream_type
+    end
+
+    def stream_key
+      attribute = self.class.stream_key_attribute
+      return nil if attribute.nil?
+
+      public_send(attribute)
+    end
+
+    # Reconstructs an event from a stored record. Routes payload values
+    # through their type's `deserialize` (so encrypted attributes decrypt
+    # back to plaintext) before construction.
+    def self.from_acta_record(envelope:, payload:)
+      types = attribute_types
+      decoded = (payload || {}).each_with_object({}) do |(k, v), acc|
+        key = k.to_s
+        next unless types.key?(key)
+
+        acc[key.to_sym] = types[key].deserialize(v)
+      end
+      new(**envelope, **decoded)
+    end
+  end
+end

data/lib/acta/events_query.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Acta
+  class EventsQuery
+    def initialize(scope)
+      @scope = scope
+    end
+
+    def last
+      hydrate(@scope.last)
+    end
+
+    def first
+      hydrate(@scope.first)
+    end
+
+    def find_by_uuid(uuid)
+      hydrate(@scope.find_by(uuid:))
+    end
+
+    def all
+      @scope.map { |record| hydrate(record) }
+    end
+
+    def count
+      @scope.count
+    end
+
+    def each(&)
+      all.each(&)
+    end
+
+    include Enumerable
+
+    def for_stream(type:, key:)
+      filtered = @scope
+                   .where(stream_type: type.to_s, stream_key: key)
+                   .reorder(:stream_sequence)
+      self.class.new(filtered)
+    end
+
+    private
+
+    def hydrate(record)
+      return nil unless record
+
+      klass = begin
+        Object.const_get(record.event_type)
+      rescue NameError
+        raise Acta::UnknownEventType, record.event_type
+      end
+
+      envelope = {
+        uuid: record.uuid,
+        occurred_at: record.occurred_at,
+        recorded_at: record.recorded_at,
+        actor: build_actor(record)
+      }
+      klass.from_acta_record(envelope:, payload: record.payload || {})
+    end
+
+    def build_actor(record)
+      return nil if record.actor_type.nil?
+
+      Actor.new(
+        type: record.actor_type,
+        id: record.actor_id,
+        source: record.source,
+        metadata: record.metadata || {}
+      )
+    end
+  end
+end

data/lib/acta/handler.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Acta
+  class Handler
+    def self.on(event_class, &block)
+      Acta.subscribe(event_class, self, &block)
+    end
+  end
+end

data/lib/acta/model.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "active_model"
+require "active_model/attributes"
+require_relative "model_type"
+require_relative "array_type"
+
+module Acta
+  class Model
+    include ActiveModel::Model
+    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
+    # - 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)
+      elsif type.is_a?(Class)
+        type = Acta::ModelType.new(type)
+      end
+
+      if type.nil?
+        super(name, **options)
+      else
+        super(name, type, **options)
+      end
+    end
+
+    def self.element_type_for(target)
+      case target
+      when Class then Acta::ModelType.new(target)
+      when Symbol then ActiveModel::Type.lookup(target)
+      else target
+      end
+    end
+    private_class_method :element_type_for
+
+    def to_acta_hash
+      self.class.attribute_types.each_with_object({}) do |(name, type), hash|
+        hash[name] = type.serialize(public_send(name))
+      end
+    end
+
+    def self.from_acta_hash(hash)
+      types = attribute_types
+      filtered = hash.each_with_object({}) do |(k, v), acc|
+        key = k.to_s
+        next unless types.key?(key)
+
+        acc[key.to_sym] = types[key].deserialize(v)
+      end
+      new(**filtered)
+    end
+  end
+end

data/lib/acta/model_type.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "active_model/type"
+
+module Acta
+  class ModelType < 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

data/lib/acta/projection.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Acta
+  class Projection < Handler
+    APPLYING_FLAG = :acta_projection_applying
+
+    def self.inherited(subclass)
+      super
+      Acta.register_projection(subclass)
+    end
+
+    # Declare the AR classes whose rows this projection owns. Acta uses these
+    # declarations both as the default `truncate!` target list and as input to
+    # `Acta.rebuild!`'s cross-projection ordering — projections whose tables
+    # are FK-referenced by another projection's tables run first, so children
+    # are deleted before their parents.
+    #
+    #   class CatalogProjection < Acta::Projection
+    #     truncates Trail, Zone   # within-projection: child first, parent second
+    #
+    #     on ZoneRegistered { |e| Zone.create!(...) }
+    #     on TrailRegistered { |e| Trail.create!(...) }
+    #   end
+    #
+    # Pass classes in safe within-projection order (children before parents);
+    # Acta only orders projections relative to each other via the global FK
+    # graph, not the within-projection list.
+    def self.truncates(*ar_classes)
+      @truncated_classes = ar_classes
+    end
+
+    def self.truncated_classes
+      @truncated_classes ||= []
+    end
+
+    # Default implementation deletes every row in each declared class. Apps
+    # override `truncate!` directly if they need custom teardown logic; in
+    # that case `truncates` still drives FK-based ordering and the override
+    # provides the actual deletion.
+    def self.truncate!
+      truncated_classes.each(&:delete_all)
+    end
+
+    # Mark the current thread as inside projection-side code for the
+    # duration of the block. Acta sets this internally when invoking
+    # projection handlers and during `Acta.rebuild!`'s truncate phase, so
+    # `acta_managed!` AR models know to allow the writes.
+    #
+    # Apps can wrap fixture setup, migrations, or one-off backfill
+    # operations in `Acta::Projection.applying! { ... }` to bypass the
+    # safety net intentionally.
+    def self.applying!
+      previous = Thread.current[APPLYING_FLAG]
+      Thread.current[APPLYING_FLAG] = true
+      yield
+    ensure
+      Thread.current[APPLYING_FLAG] = previous
+    end
+
+    def self.applying?
+      Thread.current[APPLYING_FLAG] == true
+    end
+  end
+end