standard_ledger 0.5.1 → 0.6.0

data/lib/standard_ledger/config.rb

@@ -5,30 +5,19 @@ module StandardLedger
   #
   # @see StandardLedger.configure
   class Config
-    # The ActiveJob class used by `:async` mode projections. Defaults to
-    # `StandardLedger::ProjectionJob`. Hosts can supply their own job class
-    # (e.g. for custom queue routing or per-projection telemetry) via
-    # `c.default_async_job = Orders::FulfillableProjectionJob`.
-    attr_accessor :default_async_job
-
-    # Total attempts (including the first) for an `:async` projection before
-    # the failure is propagated. Default: 3 (one initial run + two retries).
-    # Matches ActiveJob's `retry_on attempts:` semantics.
-    attr_accessor :default_async_retries
-
-    # Scheduler backend for `:matview` refresh jobs. One of
-    # `:solid_queue`, `:sidekiq_cron`, `:custom`. Default: `:solid_queue`
-    # (matches all four consuming apps).
-    attr_accessor :scheduler
-
-    # Default refresh strategy for `:matview` projections. Either
-    # `:concurrent` (REFRESH MATERIALIZED VIEW CONCURRENTLY — requires a
-    # unique index on the view) or `:blocking`. Default: `:concurrent`.
+    # Default for `StandardLedger.refresh!` calls that omit `concurrently:`.
+    # One of:
+    #
+    # - `:concurrent` (default) — `REFRESH MATERIALIZED VIEW CONCURRENTLY`;
+    #   requires a populated view with a unique index, outside a transaction.
+    # - `:blocking` — plain `REFRESH MATERIALIZED VIEW`.
+    # - `:auto` — concurrent when possible, plain otherwise (see
+    #   `StandardLedger.refresh!`).
     attr_accessor :matview_refresh_strategy
 
     # Optional: the host application's Result class. When set together with
-    # `result_adapter`, `StandardLedger.post` returns instances of this class
-    # instead of `StandardLedger::Result`.
+    # `result_adapter`, `StandardLedger.post` and `StandardLedger.refresh!`
+    # return instances of this class instead of `StandardLedger::Result`.
     attr_accessor :result_class
 
     # Optional: a callable that translates the gem's result fields into the
@@ -37,17 +26,13 @@ module StandardLedger
     # Required when `result_class` is set.
     attr_accessor :result_adapter
 
-    # Prefix for `ActiveSupport::Notifications` events emitted by the gem.
-    # Default: `"standard_ledger"`. Events:
-    # `<prefix>.entry.created`, `<prefix>.projection.applied`,
-    # `<prefix>.projection.failed`, `<prefix>.projection.refreshed`,
-    # `<prefix>.projection.rebuilt`.
+    # Prefix for events emitted by the gem (via `Rails.event` on Rails 8.1+,
+    # `ActiveSupport::Notifications` otherwise). Default: `"standard_ledger"`.
+    # Events: `<prefix>.entry.created`, `<prefix>.projection.refreshed`,
+    # `<prefix>.projection.failed`.
     attr_accessor :notification_namespace
 
     def initialize
-      @default_async_job        = nil   # resolved lazily to avoid loading the job constant before Rails boots
-      @default_async_retries    = 3
-      @scheduler                = :solid_queue
       @matview_refresh_strategy = :concurrent
       @result_class             = nil
       @result_adapter           = nil

data/lib/standard_ledger/entry.rb

@@ -2,16 +2,16 @@ require "active_support/concern"
 
 module StandardLedger
   # Marks an ActiveRecord model as a ledger entry: an immutable, append-only
-  # row that may project onto one or more aggregate targets.
+  # journal row.
   #
   # Including this concern installs:
   #   - the `ledger_entry` class macro (declares immutability + idempotency)
   #   - read-only behavior post-creation (when `immutable: true`, the default)
   #   - idempotency-by-unique-index (when `idempotency_key:` is non-nil)
   #
-  # Projection registration happens via the separate `Projector` concern —
-  # the two are decoupled so that an entry can be marked immutable without
-  # also opting into projections, and vice versa.
+  # Aggregates derived from entries are the host's concern — a plain
+  # `StandardLedger::Projection` subclass or a materialized view refreshed via
+  # `StandardLedger.refresh!`.
   #
   # @example
   #   class VoucherRecord < ApplicationRecord
@@ -26,8 +26,7 @@ module StandardLedger
 
     class_methods do
       # Declare the entry's contract. Stores the configuration on the class
-      # for later inspection by `StandardLedger.post`, `Projection.rebuild!`,
-      # and the `standard_ledger:doctor` rake task.
+      # for later inspection by `StandardLedger.post` and host specs.
       #
       # @param kind [Symbol] the column holding the entry's kind/action
       #   discriminator. Defaults to `:kind`.
@@ -285,10 +284,7 @@ module StandardLedger
     # typical 1–2 belongs_to entry, that's negligible. If profiling on a
     # high-cardinality entry shows this matters, capture targets earlier
     # (e.g. in `before_create`) and stash them on the instance — deferred
-    # to a future PR. Notably, an inline-mode caller has already resolved
-    # these targets by the time `after_commit` runs, so the SELECTs would
-    # only happen for entries with belongs_to associations that are *not*
-    # registered as projection targets.
+    # to a future PR.
     #
     # @return [Hash{Symbol => ActiveRecord::Base}]
     def standard_ledger_targets

data/lib/standard_ledger/errors.rb

@@ -1,16 +1,9 @@
 module StandardLedger
   class Error < StandardError; end
 
-  # Raised at registration time when a `projects_onto` block declares an
-  # `on(:kind)` for a kind that the entry's enum/set does not include, or
-  # when an entry is posted with a kind that no projection has registered
-  # a handler for. Use `permissive: true` on the projection to opt out.
-  class UnhandledKind < Error; end
-
-  # Raised by `StandardLedger.rebuild!` when the projector does not implement
-  # `rebuild` and is therefore not replayable from the entry log. Delta-based
-  # projectors (e.g. `increment_counter`-flavored) typically raise this
-  # because they cannot be reconstructed without summing the full log.
+  # Raised by `StandardLedger::Projection#rebuild` when a projector subclass
+  # does not override it — i.e. the projector cannot be recomputed from the
+  # entry log.
   class NotRebuildable < Error; end
 
   # Raised at boot when an Entry declares `idempotency_key:` but no matching
@@ -18,26 +11,13 @@ module StandardLedger
   # admitting duplicates at runtime.
   class MissingIdempotencyIndex < Error; end
 
-  # Raised by `StandardLedger.post` when the inline portion of fan-out
-  # succeeded but enqueuing one or more async projections failed. The entry
-  # itself is durable; callers may choose to roll back or accept-and-log.
-  class PartialFailure < Error
-    attr_reader :enqueued, :failed
-
-    def initialize(enqueued:, failed:)
-      @enqueued = enqueued
-      @failed = failed
-      super("Enqueued #{enqueued.size} projections; #{failed.size} failed to enqueue")
-    end
-  end
-
   # Raised when `StandardLedger.refresh!(view, concurrently: true)` is called
   # inside an open transaction. PostgreSQL rejects
   # `REFRESH MATERIALIZED VIEW CONCURRENTLY` inside transaction blocks; the
   # gem catches this at the boundary so the failure is a clear,
   # gem-attributable error instead of a raw `PG::ActiveSqlTransaction`.
-  # Callers wanting read-your-write semantics inside an operation should
-  # wrap the call in `connection.add_transaction_record { ... }` to defer
-  # to after-commit, or move the refresh outside the transaction block.
+  # Pass `concurrently: :auto` to fall back to a plain refresh instead, move
+  # the refresh outside the transaction, or defer it with
+  # `connection.add_transaction_record { ... }`.
   class RefreshInsideTransaction < Error; end
 end

data/lib/standard_ledger/event_emitter.rb

@@ -15,8 +15,8 @@ module StandardLedger
 
     # Emit a single event. Both backends are best-effort: any exception raised
     # by a subscriber is swallowed so ledger observability never takes down a
-    # host's request path (the projection has already either succeeded or
-    # been rolled back by the time we emit).
+    # host's request path (the entry is already committed, or the refresh
+    # already ran, by the time we emit).
     def emit(event_name, payload)
       if (bus = rails_event_bus)
         bus.notify(event_name, **payload)

data/lib/standard_ledger/matview.rb

@@ -0,0 +1,162 @@
+require "active_support/core_ext/string/filters"
+
+module StandardLedger
+  # Materialized-view refresh primitive behind `StandardLedger.refresh!`.
+  # The host creates and owns the view (via a `scenic` or hand-rolled
+  # migration) and schedules refreshes itself; this module only issues the
+  # `REFRESH MATERIALIZED VIEW` SQL, decides whether `CONCURRENTLY` is safe
+  # when asked to (`concurrently: :auto`), and emits notifications.
+  #
+  # PostgreSQL only.
+  #
+  # @api private — call `StandardLedger.refresh!` instead.
+  module Matview
+    IDENTIFIER = /\A[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)?\z/
+
+    # `REFRESH ... CONCURRENTLY` needs a populated view and at least one
+    # valid UNIQUE index that uses only column names and covers all rows (no
+    # expressions, no WHERE clause). `to_regclass` returns NULL for a
+    # missing relation, so a missing view yields no row.
+    CONCURRENCY_PROBE_SQL = <<~SQL.squish.freeze
+      SELECT c.relispopulated AS populated,
+             EXISTS (
+               SELECT 1 FROM pg_index i
+               WHERE i.indrelid = c.oid
+                 AND i.indisunique
+                 AND i.indisvalid
+                 AND i.indpred IS NULL
+                 AND i.indexprs IS NULL
+             ) AS unique_index
+      FROM pg_class c
+      WHERE c.oid = to_regclass(?) AND c.relkind = 'm'
+    SQL
+
+    class << self
+      # Resolve a requested `concurrently` value (`true`, `false`, `:auto`)
+      # to the Boolean actually used for the refresh.
+      #
+      # @return [Boolean]
+      def resolve_concurrently(view_name, requested)
+        return requested unless requested == :auto
+
+        validate_view_name!(view_name)
+        concurrent_refresh_possible?(view_name)
+      end
+
+      # Issue `REFRESH MATERIALIZED VIEW [CONCURRENTLY] <view_name>` and emit
+      # `<prefix>.projection.refreshed` on success, or
+      # `<prefix>.projection.failed` before re-raising on SQL failure.
+      #
+      # The view name is validated against a SQL-identifier regex at the
+      # boundary as defence in depth — a careless host could pass through a
+      # config value or other untrusted string.
+      #
+      # @param view_name [String, Symbol] bare or `schema.view` identifier.
+      # @param concurrently [Boolean]
+      # @return [void]
+      # @raise [ArgumentError] when `view_name` is not a valid SQL identifier.
+      # @raise [StandardLedger::RefreshInsideTransaction] for a concurrent
+      #   refresh inside an open transaction.
+      def refresh!(view_name, concurrently:)
+        validate_view_name!(view_name)
+        check_transaction_state!(view_name, concurrently: concurrently)
+
+        prefix = StandardLedger.config.notification_namespace
+        sql = build_refresh_sql(view_name, concurrently: concurrently)
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        begin
+          connection.execute(sql)
+        rescue StandardError => e
+          StandardLedger::EventEmitter.emit(
+            "#{prefix}.projection.failed",
+            view: view_name.to_s, concurrently: concurrently, mode: :matview, error: e
+          )
+          raise
+        end
+
+        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
+        )
+      end
+
+      private
+
+      def connection
+        ActiveRecord::Base.connection
+      end
+
+      # Bare identifier OR exactly one `schema.view` qualification. Names
+      # containing semicolons, quotes, comment markers, whitespace, trailing
+      # dots or extra qualification are rejected before any SQL is issued.
+      def validate_view_name!(view_name)
+        return if view_name.to_s.match?(IDENTIFIER)
+
+        raise ArgumentError,
+              "view_name must be a valid SQL identifier; got #{view_name.inspect}"
+      end
+
+      # `view_name` has already passed `validate_view_name!`. It is left
+      # unquoted on purpose: quoting would make the name case-sensitive and
+      # change which relation a mixed-case name resolves to.
+      def build_refresh_sql(view_name, concurrently:)
+        if concurrently
+          "REFRESH MATERIALIZED VIEW CONCURRENTLY #{view_name}"
+        else
+          "REFRESH MATERIALIZED VIEW #{view_name}"
+        end
+      end
+
+      # Postgres rejects `REFRESH MATERIALIZED VIEW CONCURRENTLY` inside a
+      # transaction block; catch it at the gem boundary so the failure is
+      # attributable instead of a raw `PG::ActiveSqlTransaction`. The plain
+      # form is allowed inside transactions, so only the concurrent path is
+      # guarded.
+      def check_transaction_state!(view_name, concurrently:)
+        return unless concurrently
+        return unless connection.transaction_open?
+
+        raise StandardLedger::RefreshInsideTransaction,
+              "StandardLedger.refresh!(#{view_name.inspect}) cannot run inside a transaction with " \
+              "concurrently: true — Postgres rejects `REFRESH MATERIALIZED VIEW CONCURRENTLY` inside " \
+              "transaction blocks. Move the call outside the transaction, defer it via " \
+              "`connection.add_transaction_record { ... }`, or pass `concurrently: :auto`."
+      end
+
+      # `:auto` decision. A missing view returns false so the plain refresh
+      # raises Postgres's own "relation does not exist" error. A failing probe
+      # is reported (handled) and degrades to a plain refresh, which is
+      # always valid.
+      def concurrent_refresh_possible?(view_name)
+        return false if connection.transaction_open?
+
+        row = connection.select_one(
+          ActiveRecord::Base.sanitize_sql_array([ CONCURRENCY_PROBE_SQL, view_name.to_s ]),
+          "StandardLedger refresh probe"
+        )
+        return false if row.nil?
+
+        boolean(row["populated"]) && boolean(row["unique_index"])
+      rescue StandardError => e
+        report_error(e, view: view_name.to_s)
+        false
+      end
+
+      def boolean(value)
+        ActiveModel::Type::Boolean.new.cast(value) == true
+      end
+
+      def report_error(error, context)
+        reporter =
+          if defined?(::Rails) && ::Rails.respond_to?(:error)
+            ::Rails.error
+          elsif ActiveSupport.respond_to?(:error_reporter)
+            ActiveSupport.error_reporter
+          end
+        reporter&.report(error, handled: true, severity: :warning, context: context, source: "standard_ledger")
+      end
+    end
+  end
+end

data/lib/standard_ledger/projection.rb

@@ -1,39 +1,32 @@
 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.
+  # Optional base class for host-side projector objects: plain Ruby classes
+  # that update an aggregate from ledger entries. The gem does not invoke
+  # projectors itself (the declarative `projects_onto` engine was removed in
+  # 0.6.0) — the host calls `apply` / `rebuild` from its own operations.
+  # Subclassing gives a shared shape and sensible failures for unimplemented
+  # methods.
   #
   # @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
-  #       )
+  #   class Validations::ProfileProjector < StandardLedger::Projection
+  #     def apply(profile, validation)
+  #       profile.increment!(:successful_loans_count) if validation.successful?
   #     end
   #
-  #     # Called by Projection.rebuild! to recompute from the full log.
-  #     def rebuild(order)
-  #       apply(order, nil)
+  #     def rebuild(profile)
+  #       profile.update!(successful_loans_count: profile.validations.successful.count)
   #     end
   #   end
+  #
+  #   Validations::ProfileProjector.new.apply(profile, validation)
   class Projection
-    # Apply a single entry's effect to the target. Called inside the
-    # transactional or async boundary of the chosen mode.
+    # Apply a single entry's effect to the target.
     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`.
+    # Recompute the target from the full entry log. Projectors that cannot
+    # be rebuilt (e.g. delta-only ones) leave this unimplemented and it
+    # raises `StandardLedger::NotRebuildable`.
     def rebuild(_target)
       raise NotRebuildable, "#{self.class}#rebuild not implemented; this projector cannot be rebuilt from the entry log"
     end

data/lib/standard_ledger/result.rb

@@ -1,6 +1,6 @@
 module StandardLedger
   # The gem's default result type, returned by `StandardLedger.post` and
-  # `StandardLedger.rebuild!` when the host has not configured an adapter
+  # `StandardLedger.refresh!` when the host has not configured an adapter
   # for its own Result class.
   #
   # Hosts with their own Result type (e.g. `ApplicationOperation::Result`)
@@ -16,7 +16,7 @@ module StandardLedger
     # @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: [...] }`.
+    # @param projections [Hash] `{}` for `post`; `{ refreshed: [{ view:, concurrently: }] }` for `refresh!`.
     def initialize(success:, value: nil, errors: [], entry: nil, idempotent: false, projections: {})
       @success = success
       @value = value

data/lib/standard_ledger/rspec.rb

@@ -3,42 +3,20 @@ 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:
+# Loading this file defines the `post_ledger_entry` matcher for assertions of
+# the form `expect { ... }.to post_ledger_entry(EntryClass).with(kind: ...)`.
 #
-# - 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.
+# It registers no hooks: the gem keeps no per-example state (the thread-local
+# `with_modes` overrides it used to reset were removed in 0.6.0), and it never
+# touches the host's `Config`, so an initializer-configured `result_adapter`
+# survives across examples.
 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

@@ -1,3 +1,3 @@
 module StandardLedger
-  VERSION = "0.5.1"
+  VERSION = "0.6.0"
 end