standard_ledger 0.2.0

data/lib/standard_ledger/projector.rb

@@ -0,0 +1,361 @@
+require "active_support/concern"
+require "active_support/core_ext/class/attribute"
+
+module StandardLedger
+  # Adds the `projects_onto` DSL to an Entry class. Each `projects_onto`
+  # declaration registers a single (target_association, mode, projector)
+  # tuple; multi-target fan-out is two declarations.
+  #
+  # @example block form
+  #   class VoucherRecord < ApplicationRecord
+  #     include StandardLedger::Entry
+  #     include StandardLedger::Projector
+  #
+  #     ledger_entry kind: :action, idempotency_key: :serial_no, scope: :organisation_id
+  #
+  #     projects_onto :voucher_scheme, mode: :inline do
+  #       on(:grant)    { |scheme, _| scheme.increment(:granted_vouchers_count) }
+  #       on(:redeem)   { |scheme, _| scheme.increment(:redeemed_vouchers_count) }
+  #       on(:consume)  { |scheme, _| scheme.increment(:consumed_vouchers_count) }
+  #       on(:clawback) { |scheme, _| scheme.increment(:clawed_back_vouchers_count) }
+  #     end
+  #   end
+  #
+  # @example class form
+  #   projects_onto :order, mode: :async, via: Orders::FulfillableProjector
+  module Projector
+    extend ActiveSupport::Concern
+
+    # Captures the per-projection configuration declared by `projects_onto`.
+    # Stored on the entry class so `StandardLedger.post` and
+    # `StandardLedger.rebuild!` can iterate over them at runtime.
+    #
+    # `:view` and `:refresh_options` are populated only for `:matview`-mode
+    # projections; they're `nil` for every other mode.
+    Definition = Struct.new(
+      :target_association, :mode, :projector_class, :handlers, :guard, :lock, :permissive,
+      :recompute_sql, :view, :refresh_options, :options,
+      keyword_init: true
+    )
+
+    class_methods do
+      # Declare a projection from this entry onto a single target.
+      #
+      # @param target_association [Symbol] the `belongs_to` association name on
+      #   this entry pointing at the projection target.
+      # @param mode [Symbol] one of `:inline`, `:async`, `:sql`, `:trigger`,
+      #   `:matview`. See the design doc §5.3 for selection guidance.
+      # @param via [Class, nil] optional `Projection` subclass; required for
+      #   `:async`/`:trigger`/`:sql` modes when the projector is non-trivial,
+      #   optional for `:inline` when a block is given.
+      # @param if [Proc, nil] optional guard; the projection is skipped when
+      #   the proc (evaluated in the entry's instance context) returns false.
+      # @param lock [Symbol, nil] `:pessimistic` to wrap inline updates in
+      #   `target.with_lock { ... }`. Default: `nil` (optimistic).
+      # @param permissive [Boolean] when true, an entry with a kind not
+      #   handled by `on(:kind)` is silently skipped instead of raising
+      #   `UnhandledKind`. Default: false.
+      # @param view [String, Symbol, nil] for `mode: :matview` only — the name
+      #   of the host-owned materialized view. Required when mode is
+      #   `:matview`; ignored otherwise.
+      # @param refresh [Hash, nil] for `mode: :matview` only — refresh
+      #   metadata, e.g. `{ every: 5.minutes, concurrently: true }`. The
+      #   gem records this on the Definition for hosts to read when wiring
+      #   their scheduler; the gem does NOT auto-schedule.
+      # @yield optional block-DSL form: register per-kind handlers via
+      #   `on(:kind) { |target, entry| ... }`. Not allowed for `mode: :matview`.
+      # @return [Definition] the registered projection.
+      def projects_onto(target_association, mode:, via: nil, if: nil, lock: nil, permissive: false, view: nil, refresh: nil, **options, &block)
+        guard = binding.local_variable_get(:if) # `if:` is a reserved keyword
+
+        if mode == :sql
+          if via
+            raise ArgumentError,
+                  "projects_onto :#{target_association} got `via:` with mode: :sql; " \
+                  "`:sql` mode's contract is the recompute SQL itself, declared via `recompute \"...\"` " \
+                  "in the block — use a different mode if you want a `via:` projector class"
+          end
+
+          unless lock.nil?
+            raise ArgumentError,
+                  "projects_onto :#{target_association} got `lock:` with mode: :sql; " \
+                  "`lock:` is not supported by :sql mode — recompute SQL doesn't dispatch through " \
+                  "with_lock; use :inline mode if you need pessimistic locking"
+          end
+
+          if permissive
+            raise ArgumentError,
+                  "projects_onto :#{target_association} got `permissive:` with mode: :sql; " \
+                  "`permissive:` is not supported by :sql mode — recompute SQL doesn't dispatch " \
+                  "through per-kind handlers; use :inline mode if you need permissive dispatch"
+          end
+
+          unless block
+            raise ArgumentError,
+                  "projects_onto :#{target_association} requires a block with `recompute \"...\"` for mode: :sql"
+          end
+
+          dsl = SqlDsl.new
+          dsl.instance_eval(&block)
+
+          if dsl.recompute_sql.nil?
+            raise ArgumentError,
+                  "projects_onto :#{target_association} block is empty; mode: :sql requires a `recompute \"...\"` clause"
+          end
+
+          unless dsl.recompute_sql.include?(":target_id")
+            raise ArgumentError,
+                  "projects_onto :#{target_association} recompute SQL must include the `:target_id` placeholder; " \
+                  "it's bound to the entry's foreign key for this projection's target"
+          end
+
+          definition = Definition.new(
+            target_association: target_association,
+            mode: mode,
+            projector_class: nil,
+            handlers: {},
+            guard: guard,
+            lock: lock,
+            permissive: permissive,
+            recompute_sql: dsl.recompute_sql,
+            view: nil,
+            refresh_options: nil,
+            options: options
+          )
+
+          self.standard_ledger_projections = standard_ledger_projections + [ definition ]
+          install_mode_callbacks_for(definition)
+          return definition
+        end
+
+        if mode == :matview
+          if block
+            raise ArgumentError,
+                  "projects_onto :#{target_association} mode: :matview does not accept a block; " \
+                  "matview projections have no per-kind handlers — they refresh on a schedule"
+          end
+
+          if view.nil?
+            raise ArgumentError,
+                  "projects_onto :#{target_association} mode: :matview requires `view: \"name\"` " \
+                  "(the materialized view name to refresh)"
+          end
+
+          definition = Definition.new(
+            target_association: target_association,
+            mode: mode,
+            projector_class: nil,
+            handlers: {},
+            guard: guard,
+            lock: lock,
+            permissive: permissive,
+            recompute_sql: nil,
+            view: view.to_s,
+            refresh_options: refresh || {},
+            options: options
+          )
+
+          self.standard_ledger_projections = standard_ledger_projections + [ definition ]
+          install_mode_callbacks_for(definition)
+          return definition
+        end
+
+        if block && via
+          raise ArgumentError,
+                "projects_onto :#{target_association} got both a block and `via:`; the two forms are mutually exclusive"
+        end
+
+        unless block || via
+          raise ArgumentError,
+                "projects_onto :#{target_association} requires either a block of `on(:kind) { ... }` handlers or `via: ProjectorClass`"
+        end
+
+        if via && permissive
+          raise ArgumentError,
+                "projects_onto :#{target_association} got `permissive: true` with `via:`; " \
+                "`permissive:` is only meaningful with the block form, where it falls back " \
+                "to the `:_` wildcard handler when no specific-kind handler matches. Class " \
+                "form (`via: ProjectorClass`) runs `apply(target, entry)` unconditionally, " \
+                "so there's nothing to be permissive about."
+        end
+
+        handlers = {}
+        if block
+          dsl = HandlerDsl.new
+          dsl.instance_eval(&block)
+          handlers = dsl.handlers
+
+          if handlers.empty?
+            raise ArgumentError,
+                  "projects_onto :#{target_association} block is empty; at least one `on(:kind) { ... }` handler is required"
+          end
+        end
+
+        definition = Definition.new(
+          target_association: target_association,
+          mode: mode,
+          projector_class: via,
+          handlers: handlers,
+          guard: guard,
+          lock: lock,
+          permissive: permissive,
+          recompute_sql: nil,
+          view: nil,
+          refresh_options: nil,
+          options: options
+        )
+
+        self.standard_ledger_projections = standard_ledger_projections + [ definition ]
+        install_mode_callbacks_for(definition)
+        definition
+      end
+
+      # Delegate per-mode callback installation to the matching strategy
+      # class. Keeps `Modes::*` from reaching into `Projector`'s internals
+      # — each strategy gets a chance to wire up `after_create`,
+      # `after_create_commit`, or whatever lifecycle hook it needs the first
+      # time a projection of its mode is registered on this class.
+      #
+      # @param definition [Definition]
+      # @return [void]
+      def install_mode_callbacks_for(definition)
+        case definition.mode
+        when :inline
+          StandardLedger::Modes::Inline.install!(self)
+        when :sql
+          StandardLedger::Modes::Sql.install!(self)
+        when :matview
+          StandardLedger::Modes::Matview.install!(self)
+        end
+      end
+
+      # Filter the registered projections by mode. Used by the per-mode
+      # strategy classes (`Modes::Inline`, `Modes::Async`, ...) to discover
+      # which projections they own for a given entry class.
+      #
+      # @param mode [Symbol] one of `:inline`, `:async`, `:sql`, `:trigger`,
+      #   `:matview`.
+      # @return [Array<Definition>] the matching definitions, in declared order.
+      def standard_ledger_projections_for(mode)
+        standard_ledger_projections.select { |definition| definition.mode == mode }
+      end
+    end
+
+    included do
+      class_attribute :standard_ledger_projections, instance_writer: false
+      self.standard_ledger_projections = []
+    end
+
+    # Apply a single projection definition to this entry. Resolves the
+    # target association, evaluates the optional `if:` guard, looks up the
+    # per-kind handler (or falls back to the projector class), and invokes
+    # it.
+    #
+    # `lock:` is interpreted by the mode strategies (`Modes::Inline`, ...)
+    # — not here. The inline strategy needs the lock to span both the
+    # handler invocation *and* the coalesced `target.save!`, so it wraps
+    # an entire per-target group rather than a single `apply_projection!`
+    # call. See `Modes::Inline#call` for the lock-spans-save guarantee.
+    #
+    # The mode strategies call this method; hosts typically do not call it
+    # directly.
+    #
+    # @param definition [Definition] one of the entry class's registered
+    #   projections.
+    # @return [Boolean] `true` when the handler (or projector class) ran;
+    #   `false` when the projection short-circuited (guard returned false,
+    #   target was nil, or permissive mode found no matching handler).
+    # @raise [StandardLedger::Error] when the entry's kind column is nil.
+    # @raise [StandardLedger::UnhandledKind] when no handler matches and
+    #   `permissive: false`.
+    def apply_projection!(definition)
+      if definition.mode == :sql
+        raise Error,
+              "apply_projection! is not supported for mode: :sql; " \
+              "the recompute SQL runs through `Modes::Sql#call` directly with no per-kind dispatch"
+      end
+
+      return false if definition.guard && !instance_exec(&definition.guard)
+
+      target = public_send(definition.target_association)
+      return false if target.nil?
+
+      if definition.projector_class
+        definition.projector_class.new.apply(target, self)
+        return true
+      end
+
+      kind = resolve_kind!
+      handler = definition.handlers[kind.to_sym]
+
+      if handler.nil?
+        if definition.permissive
+          handler = definition.handlers[:_]
+          return false if handler.nil?
+        else
+          raise UnhandledKind,
+                "#{self.class.name} has no handler for kind=#{kind.inspect} on projection :#{definition.target_association}"
+        end
+      end
+
+      handler.call(target, self)
+      true
+    end
+
+    private
+
+    def resolve_kind!
+      unless self.class.respond_to?(:standard_ledger_entry_config)
+        raise Error,
+              "#{self.class.name} includes Projector but not Entry; " \
+              "`ledger_entry` must be called before apply_projection! can dispatch"
+      end
+
+      kind_column = self.class.standard_ledger_entry_config&.[](:kind) || :kind
+      kind = public_send(kind_column)
+      if kind.nil?
+        raise Error,
+              "#{self.class.name} entry has nil kind (column #{kind_column.inspect}); cannot dispatch projection"
+      end
+      kind
+    end
+
+    # Internal collector for the block-DSL form. Captures `on(:kind)` calls
+    # into a hash keyed by kind. Wildcard `on(:_)` is reserved as a catch-all
+    # — its handler runs only when no specific-kind handler matched.
+    class HandlerDsl
+      attr_reader :handlers
+
+      def initialize
+        @handlers = {}
+      end
+
+      def on(kind, &block)
+        raise ArgumentError, "on(:#{kind}) requires a block" unless block
+        @handlers[kind.to_sym] = block
+      end
+    end
+
+    # Internal collector for the `:sql`-mode block-DSL form. Captures the
+    # `recompute "..."` clause's SQL string. Unlike `HandlerDsl` there are
+    # no per-kind handlers — the recompute SQL is the entire contract: it
+    # must be expressible as a single statement with `:target_id` bound
+    # from the entry's foreign key, and it serves both the after-create
+    # path and `StandardLedger.rebuild!`.
+    class SqlDsl
+      attr_reader :recompute_sql
+
+      def recompute(sql)
+        unless sql.is_a?(String)
+          raise ArgumentError, "recompute requires a SQL string; got #{sql.class}"
+        end
+        unless @recompute_sql.nil?
+          raise ArgumentError,
+                "recompute called more than once in the same projects_onto block; " \
+                ":sql mode supports exactly one recompute clause per projection"
+        end
+        @recompute_sql = sql
+      end
+    end
+  end
+end

data/lib/standard_ledger/result.rb

@@ -0,0 +1,51 @@
+module StandardLedger
+  # The gem's default result type, returned by `StandardLedger.post` and
+  # `StandardLedger.rebuild!` when the host has not configured an adapter
+  # for its own Result class.
+  #
+  # Hosts with their own Result type (e.g. `ApplicationOperation::Result`)
+  # register a translator via `StandardLedger.config.result_adapter` so the
+  # gem returns the host's type instead — see `Config#result_adapter`.
+  class Result
+    attr_reader :value, :errors, :entry, :projections
+
+    # @param success [Boolean]
+    # @param value [Object, nil] typically the persisted entry, or whatever the
+    #   host operation wishes to surface.
+    # @param errors [Array<String>] human-readable error messages.
+    # @param entry [ActiveRecord::Base, nil] the persisted entry record.
+    # @param idempotent [Boolean] true when the create was a no-op because an
+    #   existing row already satisfied the idempotency key.
+    # @param projections [Hash] split by mode: `{ inline: [...], async: [...], matview: [...] }`.
+    def initialize(success:, value: nil, errors: [], entry: nil, idempotent: false, projections: {})
+      @success = success
+      @value = value
+      @errors = errors
+      @entry = entry
+      @idempotent = idempotent
+      @projections = projections
+    end
+
+    def success?
+      @success
+    end
+
+    def failure?
+      !@success
+    end
+
+    def idempotent?
+      @idempotent
+    end
+
+    # Build a successful result. Convenience for `StandardLedger.post` and
+    # internal callers; not intended as the host's primary construction path.
+    def self.success(entry:, idempotent: false, projections: {})
+      new(success: true, value: entry, entry: entry, idempotent: idempotent, projections: projections)
+    end
+
+    def self.failure(errors:, entry: nil, projections: {})
+      new(success: false, errors: Array(errors), entry: entry, projections: projections)
+    end
+  end
+end

data/lib/standard_ledger/rspec/helpers.rb

@@ -0,0 +1,15 @@
+module StandardLedger
+  module RSpec
+    # Convenience methods auto-included into every RSpec example group when
+    # the host loads `require "standard_ledger/rspec"`. The actual override
+    # map lives on `StandardLedger` itself so non-RSpec callers (e.g. a
+    # background job spec running outside RSpec) can use the same API.
+    module Helpers
+      # Forwards to `StandardLedger.with_modes` so specs can write
+      # `with_modes(...) { ... }` instead of the fully-qualified form.
+      def with_modes(overrides, &block)
+        StandardLedger.with_modes(overrides, &block)
+      end
+    end
+  end
+end

data/lib/standard_ledger/rspec/matchers.rb

@@ -0,0 +1,148 @@
+require "rspec/expectations"
+require "active_support/notifications"
+
+# `post_ledger_entry` — assert that a block of code wrote a ledger entry.
+#
+#   expect {
+#     Vouchers::IssueOperation.call(scheme: scheme, profile: profile)
+#   }.to post_ledger_entry(VoucherRecord)
+#
+#   expect {
+#     Vouchers::IssueOperation.call(scheme: scheme, profile: profile)
+#   }.to post_ledger_entry(VoucherRecord).with(kind: :grant)
+#
+#   expect {
+#     Vouchers::IssueOperation.call(scheme: scheme, profile: profile)
+#   }.to post_ledger_entry(VoucherRecord).with(
+#     kind:    :grant,
+#     targets: { voucher_scheme: scheme },
+#     attrs:   { serial_no: "v-123" }
+#   )
+#
+#   expect { ... }.to_not post_ledger_entry(VoucherRecord)
+#
+# The matcher subscribes to `<namespace>.entry.created` for the duration of
+# the block, captures every fired event, and asserts that at least one event
+# matched the expected class (and, when chained, the expected `kind`,
+# `targets`, and `attrs`). The notification namespace is read from
+# `StandardLedger.config.notification_namespace`, so a host that customised
+# the namespace before the block runs is honored automatically.
+RSpec::Matchers.define :post_ledger_entry do |entry_class|
+  supports_block_expectations
+
+  chain :with do |options = {}|
+    @expected_kind    = options[:kind]    if options.key?(:kind)
+    @expected_targets = options[:targets] if options.key?(:targets)
+    @expected_attrs   = options[:attrs]   if options.key?(:attrs)
+  end
+
+  match do |block|
+    @expected_class = entry_class
+    @captured_events = capture_entry_created_events(&block)
+
+    @captured_events.any? { |payload| event_matches?(payload) }
+  end
+
+  match_when_negated do |block|
+    @expected_class = entry_class
+    @captured_events = capture_entry_created_events(&block)
+
+    @captured_events.none? { |payload| event_matches?(payload) }
+  end
+
+  failure_message do
+    if @captured_events.empty?
+      "expected block to post a #{@expected_class} ledger entry, but no " \
+        "`#{notification_event_name}` events fired"
+    else
+      "expected block to post a #{@expected_class} ledger entry " \
+        "#{describe_expectations}, but got: #{describe_captured_events}"
+    end
+  end
+
+  failure_message_when_negated do
+    matched = @captured_events.select { |payload| event_matches?(payload) }
+    "expected block not to post a #{@expected_class} ledger entry " \
+      "#{describe_expectations}, but #{matched.size} matching event(s) fired: " \
+      "#{describe_captured_events(matched)}"
+  end
+
+  # ----------------------------------------------------------------------
+  # Helpers
+  # ----------------------------------------------------------------------
+
+  def capture_entry_created_events(&block)
+    events = []
+    name = notification_event_name
+    subscriber = ActiveSupport::Notifications.subscribe(name) do |*args|
+      events << ActiveSupport::Notifications::Event.new(*args).payload
+    end
+
+    begin
+      block.call
+    ensure
+      ActiveSupport::Notifications.unsubscribe(subscriber) if subscriber
+    end
+
+    events
+  end
+
+  def notification_event_name
+    "#{StandardLedger.config.notification_namespace}.entry.created"
+  end
+
+  def event_matches?(payload)
+    entry = payload[:entry]
+    return false unless entry.is_a?(@expected_class)
+
+    if defined?(@expected_kind)
+      return false unless kind_matches?(payload[:kind], @expected_kind)
+    end
+
+    if defined?(@expected_targets)
+      return false unless hash_includes?(payload[:targets] || {}, @expected_targets)
+    end
+
+    if defined?(@expected_attrs)
+      return false unless attrs_match?(entry, @expected_attrs)
+    end
+
+    true
+  end
+
+  # `kind` arrives in the payload as whatever the entry stored — usually a
+  # string, since that's what a string column reads back as. Allow specs to
+  # pass either symbol or string and compare loosely.
+  def kind_matches?(actual, expected)
+    actual.to_s == expected.to_s
+  end
+
+  def hash_includes?(actual, expected)
+    expected.all? { |key, value| actual[key] == value }
+  end
+
+  def attrs_match?(entry, expected)
+    expected.all? do |key, value|
+      next false unless entry.respond_to?(key)
+
+      entry.public_send(key) == value
+    end
+  end
+
+  def describe_expectations
+    parts = []
+    parts << "with kind: #{@expected_kind.inspect}"      if defined?(@expected_kind)
+    parts << "targets: #{@expected_targets.inspect}"     if defined?(@expected_targets)
+    parts << "attrs: #{@expected_attrs.inspect}"         if defined?(@expected_attrs)
+    parts.empty? ? "" : "(#{parts.join(', ')})"
+  end
+
+  def describe_captured_events(events = @captured_events)
+    return "(none)" if events.empty?
+
+    events.map { |payload|
+      "<#{payload[:entry].class}: kind=#{payload[:kind].inspect}, " \
+        "targets=#{(payload[:targets] || {}).keys.inspect}>"
+    }.join(", ")
+  end
+end

data/lib/standard_ledger/rspec.rb

@@ -0,0 +1,44 @@
+require "rspec/core"
+require "rspec/expectations"
+
+require "standard_ledger"
+require "standard_ledger/rspec/matchers"
+require "standard_ledger/rspec/helpers"
+
+# Opt-in test support for host apps. Hosts add this require to their
+# `spec/rails_helper.rb` (or equivalent):
+#
+#   require "standard_ledger/rspec"
+#
+# Loading this file:
+#
+# - Registers a `before(:each)` hook that calls
+#   `StandardLedger.reset_mode_overrides!` so the thread-local `with_modes`
+#   override map doesn't leak between examples. We deliberately do *not* call
+#   the full `reset!` here: hosts often configure the gem from a Rails
+#   initializer (`StandardLedger.configure { |c| c.result_adapter = ... }`),
+#   and wiping `@config` between examples would silently undo that
+#   configuration for every spec. The reset is wired via `RSpec.configure`
+#   rather than a custom shared context so it applies to every example group
+#   automatically.
+# - Defines the `post_ledger_entry` matcher (see
+#   `StandardLedger::RSpec::Matchers`) for assertions of the form
+#   `expect { ... }.to post_ledger_entry(EntryClass).with(kind: ...)`.
+# - Includes `StandardLedger::RSpec::Helpers` into every example group so
+#   specs can call `with_modes(...)` directly without the module prefix.
+#
+# We intentionally avoid touching subscribers, AR connections, or any host
+# state — the gem only owns its own configuration. Hosts that need additional
+# cleanup wire their own hooks alongside this one.
+module StandardLedger
+  module RSpec
+  end
+end
+
+::RSpec.configure do |config|
+  config.before(:each) do
+    StandardLedger.reset_mode_overrides!
+  end
+
+  config.include StandardLedger::RSpec::Helpers
+end

data/lib/standard_ledger/version.rb

@@ -0,0 +1,3 @@
+module StandardLedger
+  VERSION = "0.2.0"
+end