standard_ledger 0.2.0

data/lib/standard_ledger/modes/inline.rb

@@ -0,0 +1,180 @@
+module StandardLedger
+  module Modes
+    # `:inline` mode: applies the projection inside the entry's `after_create`
+    # callback, which fires while the host's outer transaction is still open.
+    # If the host's transaction rolls back, the projection rolls back too.
+    #
+    # This is the default for delta-based counter updates. For complex
+    # projectors (jsonb shape, multi-row aggregates), use `:async` instead.
+    #
+    # The strategy is invoked from a single `after_create` callback installed
+    # once per entry class (see `.install!`). The callback walks every
+    # `:inline`-mode projection registered on the class and runs each via
+    # `entry.apply_projection!(definition)`.
+    #
+    # ## Multi-counter coalescing
+    #
+    # A single host might register four `on(:grant)`/`on(:redeem)`/... handlers
+    # against the same target, each calling `target.increment(:some_count)`.
+    # ActiveRecord's `#increment` (vs. `#increment!`) only mutates the
+    # in-memory attribute — no SQL is issued — so the strategy persists with
+    # a single `target.save!` per (entry, target) pair after all handlers for
+    # that target have run. This collapses N handlers into one UPDATE.
+    #
+    # Definitions targeting different associations get their own
+    # apply-then-save cycle, executed in the order the projections were
+    # declared.
+    #
+    # ## Lock semantics
+    #
+    # When any projection in a per-target group declares `lock: :pessimistic`,
+    # the strategy wraps the **entire** apply-then-save cycle for that target
+    # in `target.with_lock { ... }`. The lock spans both handler invocation
+    # and the coalesced `save!`, so concurrent posts to the same target
+    # serialize end-to-end — closing the lost-update window that an
+    # inner-only lock would leave open between the lock release and the save.
+    # See `standard_ledger-design.md` §5.3.1.
+    class Inline
+      # Install the `after_create` callback on `entry_class` exactly once.
+      # Subsequent calls (e.g. when a second `:inline` projection is added
+      # later in the class body) are no-ops — the same callback handles all
+      # `:inline` projections registered on the class.
+      #
+      # @param entry_class [Class] the host entry class.
+      # @return [void]
+      # @raise [ArgumentError] when `entry_class` is not ActiveRecord-backed
+      #   (no `after_create` hook available). `:inline` mode requires AR
+      #   transactional callbacks; non-AR entry classes must use a different
+      #   mode (or refrain from declaring `:inline` projections).
+      def self.install!(entry_class)
+        return if entry_class.instance_variable_get(:@_standard_ledger_inline_installed)
+
+        unless entry_class.respond_to?(:after_create)
+          raise ArgumentError,
+                "#{entry_class.name || entry_class.inspect} cannot use mode: :inline " \
+                "because it does not respond to `after_create`. `:inline` mode requires " \
+                "an ActiveRecord-backed entry class — use `:async` (or another mode) for " \
+                "non-AR includers."
+        end
+
+        entry_class.after_create { StandardLedger::Modes::Inline.new.call(self) }
+        entry_class.instance_variable_set(:@_standard_ledger_inline_installed, true)
+      end
+
+      # Apply every `:inline` projection registered on the entry's class.
+      # Called from the `after_create` callback installed by `.install!`.
+      #
+      # Projections targeting the same association coalesce: all handlers
+      # for that target run, then the target is saved once. Different
+      # targets get their own apply+save cycle, in declared order. When any
+      # definition in a per-target group sets `lock: :pessimistic`, the
+      # cycle (apply + save) is wrapped in `target.with_lock`.
+      #
+      # Records the names of projections that actually ran (after `if:`
+      # guards filter) on the entry instance under
+      # `@_standard_ledger_applied_projections`, so `StandardLedger.post`
+      # can surface an accurate `result.projections[:inline]`.
+      #
+      # Any projector exception escapes — the entry's transaction rolls
+      # back along with every counter mutation that ran before the failure.
+      # The `standard_ledger.projection.failed` notification fires before
+      # the re-raise so subscribers see the failed projection in payload.
+      #
+      # @param entry [ActiveRecord::Base] the just-created entry.
+      # @return [void]
+      def call(entry)
+        definitions = inline_definitions_for(entry.class)
+        return if definitions.empty?
+
+        applied = []
+        entry.instance_variable_set(:@_standard_ledger_applied_projections, applied)
+
+        # group_by preserves insertion order on Ruby >= 1.9, so declared
+        # projection order is preserved across targets. Within a target
+        # group, handlers run in declared order as well.
+        definitions.group_by(&:target_association).each_value do |group|
+          target = entry.public_send(group.first.target_association)
+          locked = group.any? { |definition| definition.lock == :pessimistic }
+
+          run_group = lambda do
+            group.each do |definition|
+              ran = instrument_projection(entry, target, definition) do
+                entry.apply_projection!(definition)
+              end
+              applied << definition.target_association if ran && !applied.include?(definition.target_association)
+            end
+
+            # Coalesce: if any handler called `target.increment(col)` (which
+            # mutates in-memory only), persist the accumulated changes with a
+            # single UPDATE. Skipped when the target is nil (apply_projection!
+            # short-circuits) or when no handler dirtied the record. The
+            # `target` here always responds to AR's `changed?`/`save!` because
+            # it's resolved from a `belongs_to` reflection.
+            target.save! if target && target.changed?
+          end
+
+          if locked && target.respond_to?(:with_lock)
+            target.with_lock(&run_group)
+          else
+            run_group.call
+          end
+        end
+      end
+
+      private
+
+      def inline_definitions_for(entry_class)
+        return [] unless entry_class.respond_to?(:standard_ledger_projections_for)
+
+        entry_class.standard_ledger_projections_for(:inline)
+      end
+
+      # Wrap each handler invocation so subscribers see exactly one
+      # `applied` event per projection on success or one `failed` event on
+      # raise. Two distinct events (rather than letting `instrument`
+      # package success-or-failure into a single event) because the design
+      # splits the two outcomes — see §5.7.
+      #
+      # When the wrapped `apply_projection!` short-circuits (returns false
+      # because of a guard, nil target, or no-handler permissive miss), no
+      # `applied` event fires — there's no work to report. The exception
+      # path always fires `failed` so observability of failures isn't
+      # contingent on guard logic.
+      #
+      # The exception is re-raised so the entry's transaction rolls back —
+      # the notification's payload carries the error for observers
+      # regardless of whether the listener swallows or re-raises.
+      #
+      # @return [Boolean] the truthy/falsy result of the wrapped block —
+      #   used by the caller to decide whether to record this projection
+      #   in the entry's `applied` list.
+      def instrument_projection(entry, target, definition)
+        prefix = StandardLedger.config.notification_namespace
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        ran =
+          begin
+            yield
+          rescue StandardError => e
+            duration_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000.0
+            StandardLedger::EventEmitter.emit(
+              "#{prefix}.projection.failed",
+              entry: entry, target: target, projection: definition.target_association,
+              mode: :inline, error: e, duration_ms: duration_ms
+            )
+            raise
+          end
+
+        return false unless ran
+
+        duration_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000.0
+        StandardLedger::EventEmitter.emit(
+          "#{prefix}.projection.applied",
+          entry: entry, target: target, projection: definition.target_association,
+          mode: :inline, duration_ms: duration_ms
+        )
+        true
+      end
+    end
+  end
+end

data/lib/standard_ledger/modes/matview.rb

@@ -0,0 +1,115 @@
+module StandardLedger
+  module Modes
+    # `:matview` mode: backs the projection with a host-owned PostgreSQL
+    # materialized view. The host creates and owns the view (via a migration —
+    # `scenic` or hand-rolled SQL); the gem owns the refresh schedule and the
+    # ad-hoc refresh API.
+    #
+    # Unlike `:inline`, this strategy does NOT install a per-entry callback —
+    # matview projections are scheduled, not entry-driven. The strategy's job
+    # is to (a) record the matview registration on the entry class so callers
+    # can enumerate `:matview` projections (used by `StandardLedger.rebuild!`
+    # and the host's scheduler wiring), and (b) provide the `#refresh!`
+    # primitive that issues the actual `REFRESH MATERIALIZED VIEW` SQL.
+    #
+    # Hosts wire their scheduler (SolidQueue Recurring Tasks, sidekiq-cron,
+    # etc.) at `StandardLedger::MatviewRefreshJob` to drive scheduled
+    # refreshes. Ad-hoc refreshes go through `StandardLedger.refresh!` for
+    # read-your-write semantics after a critical write.
+    #
+    # See `standard_ledger-design.md` §5.3.5 for the full contract.
+    class Matview
+      # Mark the entry class as having at least one `:matview` projection
+      # registered. The actual matview definition lives on the entry class's
+      # `standard_ledger_projections` array; this method exists only to
+      # mirror the `Modes::Inline.install!` shape and to mark the class so
+      # repeated registrations are recognised as idempotent installs.
+      #
+      # Idempotent — multiple `:matview` projections on the same entry class
+      # do not cause double registration. Unlike `:inline`, no `after_create`
+      # callback is installed.
+      #
+      # @param entry_class [Class] the host entry class.
+      # @return [void]
+      def self.install!(entry_class)
+        return if entry_class.instance_variable_get(:@_standard_ledger_matview_installed)
+
+        entry_class.instance_variable_set(:@_standard_ledger_matview_installed, true)
+      end
+
+      # Issue `REFRESH MATERIALIZED VIEW [CONCURRENTLY] <view_name>` against
+      # the active connection and emit the standard `<prefix>.projection.refreshed`
+      # notification on success (or `<prefix>.projection.failed` on raise,
+      # before re-raising). The view name is validated against a SQL-identifier
+      # regex at the boundary as a defence-in-depth check — the value normally
+      # comes from a `view:` DSL keyword in source code, but a careless host
+      # could pass through a config value or other untrusted string. Anything
+      # that isn't a bare or schema-qualified identifier raises.
+      #
+      # The default `:concurrent` strategy (and `concurrently: true` per-call)
+      # requires a unique index on the matview — Postgres rejects
+      # `REFRESH MATERIALIZED VIEW CONCURRENTLY` otherwise. Hosts who haven't
+      # added one should pass `concurrently: false` or set
+      # `Config#matview_refresh_strategy = :blocking`.
+      #
+      # @param view_name [String, Symbol] the materialized view to refresh.
+      #   Must match `/\A[a-zA-Z_][a-zA-Z0-9_.]*\z/` so a single dot is
+      #   permitted for `schema.view` qualified names.
+      # @param concurrently [Boolean] when true, adds `CONCURRENTLY` (which
+      #   requires a unique index on the view).
+      # @return [void]
+      # @raise [ArgumentError] when `view_name` is not a valid SQL identifier.
+      # @raise [StandardError] anything the connection raises while running
+      #   the SQL — re-raised after the `failed` event fires.
+      def self.refresh!(view_name, concurrently:)
+        validate_view_name!(view_name)
+
+        prefix = StandardLedger.config.notification_namespace
+        sql = build_refresh_sql(view_name, concurrently: concurrently)
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        ActiveRecord::Base.connection.execute(sql)
+
+        duration_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000.0
+        StandardLedger::EventEmitter.emit(
+          "#{prefix}.projection.refreshed",
+          view: view_name.to_s, concurrently: concurrently, duration_ms: duration_ms
+        )
+      rescue StandardError => e
+        # ArgumentError from the validator should propagate without firing
+        # the failed notification — the SQL was never issued.
+        raise if e.is_a?(ArgumentError)
+
+        StandardLedger::EventEmitter.emit(
+          "#{prefix}.projection.failed",
+          view: view_name.to_s, concurrently: concurrently, mode: :matview, error: e
+        )
+        raise
+      end
+
+      # Reject anything that isn't a bare or schema-qualified SQL identifier
+      # — the matching regex allows a leading letter/underscore followed by
+      # alphanumerics, underscores, or a single dot for `schema.view`. Names
+      # containing semicolons, quotes, comment markers (`--`), whitespace, or
+      # other punctuation are rejected at the `refresh!` boundary so SQL
+      # injection isn't possible even when a host carelessly pipes a config
+      # value into the call.
+      def self.validate_view_name!(view_name)
+        return if view_name.to_s.match?(/\A[a-zA-Z_][a-zA-Z0-9_.]*\z/)
+
+        raise ArgumentError,
+              "view_name must be a valid SQL identifier; got #{view_name.inspect}"
+      end
+      private_class_method :validate_view_name!
+
+      def self.build_refresh_sql(view_name, concurrently:)
+        if concurrently
+          "REFRESH MATERIALIZED VIEW CONCURRENTLY #{view_name}"
+        else
+          "REFRESH MATERIALIZED VIEW #{view_name}"
+        end
+      end
+      private_class_method :build_refresh_sql
+    end
+  end
+end

data/lib/standard_ledger/modes/sql.rb

@@ -0,0 +1,132 @@
+module StandardLedger
+  module Modes
+    # `:sql` mode: applies the projection by running a single recompute
+    # `UPDATE` against the target table, inside the entry's `after_create`
+    # callback. The recompute SQL is supplied via the block-DSL's
+    # `recompute "..."` clause; the `:target_id` placeholder is bound to
+    # the foreign-key value the entry holds for the target association.
+    #
+    # Lower-overhead than `:inline` for projections expressible as
+    # `UPDATE target SET col = (SELECT aggregate(...) FROM entries WHERE
+    # ...)` — there's no Ruby-side handler invocation, no per-counter
+    # in-memory mutation, and no AR object load. Naturally rebuildable:
+    # `StandardLedger.rebuild!` runs the same statement against each
+    # target the log references, so the `after_create` and `rebuild!`
+    # paths share the same recompute SQL.
+    #
+    # Like `:inline`, this fires from `after_create` (in the entry's
+    # transaction), so failures roll the entry back alongside the
+    # projection. The notification payload's `:target` field is `nil` for
+    # `:sql` mode — loading the target object would defeat the point of
+    # the mode (it's meant to avoid Ruby-side reads). Subscribers get
+    # `entry`, the projection definition, and the timing.
+    class Sql
+      # Install the `after_create` callback on `entry_class` exactly once.
+      # Subsequent calls (e.g. when a second `:sql` projection is added
+      # later in the class body) are no-ops — the same callback handles
+      # all `:sql` projections registered on the class.
+      #
+      # @param entry_class [Class] the host entry class.
+      # @return [void]
+      # @raise [ArgumentError] when `entry_class` is not ActiveRecord-backed
+      #   (no `after_create` hook available). `:sql` mode requires an
+      #   AR-backed entry class — the recompute SQL runs through
+      #   `entry.class.connection.exec_update`.
+      def self.install!(entry_class)
+        return if entry_class.instance_variable_get(:@_standard_ledger_sql_installed)
+
+        unless entry_class.respond_to?(:after_create)
+          raise ArgumentError,
+                "#{entry_class.name || entry_class.inspect} cannot use mode: :sql " \
+                "because it does not respond to `after_create`. `:sql` mode requires " \
+                "an ActiveRecord-backed entry class."
+        end
+
+        entry_class.after_create { StandardLedger::Modes::Sql.new.call(self) }
+        entry_class.instance_variable_set(:@_standard_ledger_sql_installed, true)
+      end
+
+      # Apply every `:sql` projection registered on the entry's class.
+      # Called from the `after_create` callback installed by `.install!`.
+      #
+      # For each definition: resolve the target's foreign key from the
+      # entry, evaluate the optional `if:` guard, and run the recompute
+      # SQL with `:target_id` bound to the FK value.
+      #
+      # A nil FK (target unset for this entry) is silently skipped — the
+      # entry simply doesn't project onto a target this round. A guard
+      # returning false is also silently skipped.
+      #
+      # Any exception raised by the SQL escapes — the entry's transaction
+      # rolls back with the projection. The
+      # `<prefix>.projection.failed` notification fires before the
+      # re-raise so subscribers see the failure.
+      #
+      # @param entry [ActiveRecord::Base] the just-created entry.
+      # @return [void]
+      def call(entry)
+        definitions = sql_definitions_for(entry.class)
+        return if definitions.empty?
+
+        definitions.each do |definition|
+          next if definition.guard && !entry.instance_exec(&definition.guard)
+
+          target_id = resolve_target_id(entry, definition)
+          next if target_id.nil?
+
+          run_recompute_sql(entry, definition, target_id)
+        end
+      end
+
+      private
+
+      def sql_definitions_for(entry_class)
+        return [] unless entry_class.respond_to?(:standard_ledger_projections_for)
+
+        entry_class.standard_ledger_projections_for(:sql)
+      end
+
+      # Pull the FK value off the entry without loading the target. The
+      # reflection's `foreign_key` is the column name (e.g.
+      # `"voucher_scheme_id"`); reading it via `public_send` avoids
+      # triggering an AR association load.
+      def resolve_target_id(entry, definition)
+        reflection = entry.class.reflect_on_association(definition.target_association)
+        return nil if reflection.nil?
+
+        entry.public_send(reflection.foreign_key)
+      end
+
+      # Run the recompute statement, instrumenting success and failure
+      # symmetrically with the inline mode's two-event split. The target
+      # is intentionally `nil` in the payload — loading it would defeat
+      # the mode's "no Ruby-side reads" contract; subscribers that want
+      # the target should reload it themselves from the
+      # `definition.target_association` + the entry.
+      def run_recompute_sql(entry, definition, target_id)
+        prefix = StandardLedger.config.notification_namespace
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        begin
+          sql = ActiveRecord::Base.sanitize_sql_array([ definition.recompute_sql, { target_id: target_id } ])
+          entry.class.connection.exec_update(sql)
+        rescue StandardError => e
+          duration_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000.0
+          StandardLedger::EventEmitter.emit(
+            "#{prefix}.projection.failed",
+            entry: entry, target: nil, projection: definition.target_association,
+            mode: :sql, error: e, duration_ms: duration_ms
+          )
+          raise
+        end
+
+        duration_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000.0
+        StandardLedger::EventEmitter.emit(
+          "#{prefix}.projection.applied",
+          entry: entry, target: nil, projection: definition.target_association,
+          mode: :sql, duration_ms: duration_ms
+        )
+      end
+    end
+  end
+end

data/lib/standard_ledger/projection.rb

@@ -0,0 +1,41 @@
+module StandardLedger
+  # Base class for projector classes registered via
+  # `projects_onto :target, via: ProjectorClass`. Subclasses implement
+  # `apply` (and optionally `rebuild`) to mutate the target based on a new
+  # entry.
+  #
+  # For projections expressible as block DSL (counter increments, simple
+  # delta updates), prefer the block form on `Projector#projects_onto`
+  # instead — extracting a class is for non-trivial projectors.
+  #
+  # @example
+  #   class Orders::FulfillableProjector < StandardLedger::Projection
+  #     # Called inside the async job, with target locked.
+  #     def apply(order, _entry)
+  #       order.update!(
+  #         fulfillable_balance: order.fulfillment_records.group(:key).sum(:amount),
+  #         fulfillable_status:  order.fulfillment_records.group(:key).sum(:amount).values.all?(&:zero?) ? :fulfilled : :pending
+  #       )
+  #     end
+  #
+  #     # Called by Projection.rebuild! to recompute from the full log.
+  #     def rebuild(order)
+  #       apply(order, nil)
+  #     end
+  #   end
+  class Projection
+    # Apply a single entry's effect to the target. Called inside the
+    # transactional or async boundary of the chosen mode.
+    def apply(_target, _entry)
+      raise NotImplementedError, "#{self.class}#apply must be implemented"
+    end
+
+    # Recompute the target's projection from the full entry log. Called by
+    # `StandardLedger.rebuild!`. Projectors that cannot be rebuilt (e.g.
+    # delta-only `increment_counter` flavored ones) should raise
+    # `StandardLedger::NotRebuildable`.
+    def rebuild(_target)
+      raise NotRebuildable, "#{self.class}#rebuild not implemented; this projector cannot be rebuilt from the entry log"
+    end
+  end
+end