standard_ledger 0.5.1 → 0.7.0

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_ledger
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.7.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -37,20 +37,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '8.0'
-- !ruby/object:Gem::Dependency
-  name: activejob
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '8.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '8.0'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
@@ -65,20 +51,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '8.0'
-- !ruby/object:Gem::Dependency
-  name: concurrent-ruby
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.3'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.3'
 - !ruby/object:Gem::Dependency
   name: brakeman
   requirement: !ruby/object:Gem::Requirement
@@ -121,12 +93,11 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: StandardLedger captures the recurring 'append-only entry → N projection
-  updates' pattern as a declarative DSL on host ActiveRecord models. Supports five
-  projection modes — :inline, :async, :sql, :matview, :trigger — plus a deterministic
-  rebuild path from the entry log, ad-hoc materialized view refresh, and a doctor
-  rake task that verifies host-owned trigger presence. Enforces idempotency-by-unique-index
-  and immutability at the entry level.
+description: 'StandardLedger marks ActiveRecord models as immutable, append-only journal
+  entries with idempotency-by-unique-index, provides a StandardLedger.post helper
+  that returns a Result (optionally the host''s own Result type), a Projection base
+  class for host-side projectors, and StandardLedger.refresh! for host-owned PostgreSQL
+  materialized views (including concurrently: :auto).'
 email:
 - code@jaryl.dev
 executables: []
@@ -141,25 +112,15 @@ files:
 - lib/generators/standard_ledger/install/templates/initializer.rb.tt
 - lib/standard_ledger.rb
 - lib/standard_ledger/config.rb
-- lib/standard_ledger/engine.rb
 - lib/standard_ledger/entry.rb
 - lib/standard_ledger/errors.rb
 - lib/standard_ledger/event_emitter.rb
-- lib/standard_ledger/jobs/matview_refresh_job.rb
-- lib/standard_ledger/jobs/projection_job.rb
-- lib/standard_ledger/modes/async.rb
-- lib/standard_ledger/modes/inline.rb
-- lib/standard_ledger/modes/matview.rb
-- lib/standard_ledger/modes/sql.rb
-- lib/standard_ledger/modes/trigger.rb
+- lib/standard_ledger/matview.rb
 - lib/standard_ledger/projection.rb
-- lib/standard_ledger/projector.rb
 - lib/standard_ledger/result.rb
 - lib/standard_ledger/rspec.rb
-- lib/standard_ledger/rspec/helpers.rb
 - lib/standard_ledger/rspec/matchers.rb
 - lib/standard_ledger/version.rb
-- lib/tasks/standard_ledger.rake
 homepage: https://github.com/rarebit-one/standard_ledger
 licenses:
 - MIT
@@ -184,6 +145,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.3
 specification_version: 4
-summary: Immutable journal entries with declarative aggregate projections for Rails
-  apps.
+summary: Immutable, append-only journal entries and materialized-view refresh for
+  Rails apps.
 test_files: []

data/lib/standard_ledger/engine.rb

@@ -1,28 +0,0 @@
-module StandardLedger
-  # Boot hook for Rails apps. The engine registers no routes and provides no
-  # tables — its only role is to ensure the gem's notification subscribers
-  # (if any are registered by the host) are wired up after the host's
-  # initializers have finished running.
-  #
-  # We hook `after: :load_config_initializers` so any host-side
-  # `StandardLedger.configure` block in `config/initializers/*` has finished
-  # before subscribers are attached.
-  class Engine < ::Rails::Engine
-    isolate_namespace StandardLedger
-
-    initializer "standard_ledger.notifications", after: :load_config_initializers do
-      # Notification wiring lands here in a follow-up PR. Today this is a
-      # no-op — the gem emits events but ships no internal subscribers. On
-      # Rails 8.1+ events go through `Rails.event.notify`, so hosts subscribe
-      # with `Rails.event.subscribe`; on older Rails they fall back to
-      # ActiveSupport::Notifications (see StandardLedger::EventEmitter).
-    end
-
-    # Engines auto-discover `lib/tasks/*.rake` in most Rails versions, but
-    # we register explicitly for defence-in-depth. Hosts get
-    # `standard_ledger:doctor` available under `bin/rails -T standard_ledger`.
-    rake_tasks do
-      load File.expand_path("../tasks/standard_ledger.rake", __dir__)
-    end
-  end
-end

data/lib/standard_ledger/jobs/matview_refresh_job.rb

@@ -1,28 +0,0 @@
-require "active_job"
-
-module StandardLedger
-  # Thin ActiveJob wrapper that delegates to `StandardLedger.refresh!`. Hosts
-  # point their scheduler (SolidQueue Recurring Tasks, sidekiq-cron, etc.) at
-  # this job class with the view name as the argument. The gem deliberately
-  # does not auto-schedule — schedule cadence and backend selection is a host
-  # concern (the host's scheduler config has the wider context: queue routing,
-  # recurring task DSL, etc.).
-  #
-  # The job runs on ActiveJob's `:default` queue. Hosts running high-frequency
-  # refreshes (e.g. every minute) on a shared `:default` queue may want to
-  # isolate matview refreshes onto a dedicated queue so a slow refresh doesn't
-  # starve other latency-sensitive jobs — subclass and override `queue_as`
-  # (e.g. `queue_as :standard_ledger`) and point the scheduler at the
-  # subclass.
-  #
-  # @example SolidQueue Recurring Tasks (config/recurring.yml)
-  #   refresh_user_prompt_inventories:
-  #     class: StandardLedger::MatviewRefreshJob
-  #     args: ["user_prompt_inventories", { concurrently: true }]
-  #     schedule: "every 5 minutes"
-  class MatviewRefreshJob < ::ActiveJob::Base
-    def perform(view_name, concurrently: nil)
-      StandardLedger.refresh!(view_name, concurrently: concurrently)
-    end
-  end
-end

data/lib/standard_ledger/jobs/projection_job.rb

@@ -1,94 +0,0 @@
-require "active_job"
-
-module StandardLedger
-  # ActiveJob class that runs a single `:async`-mode projection after the
-  # entry's outer transaction has committed. Enqueued by
-  # `StandardLedger::Modes::Async` from an `after_create_commit` callback.
-  #
-  # The job resolves the projection definition by `target_association` (the
-  # only stable handle — the Definition struct doesn't serialize cleanly
-  # through ActiveJob), looks up the target via the entry's `belongs_to`
-  # setter, and runs `target.with_lock { projector_class.new.apply(target,
-  # entry) }`. The projector must be class-form (`via: ProjectorClass`) and
-  # should recompute the aggregate from the log inside `apply` for retry
-  # safety — async projections can run more than once when the job retries.
-  #
-  # Retries are configurable per-projection via subclassing this job and
-  # overriding `retry_on`, or globally via `Config#default_async_retries`
-  # (default 3). When retries are exhausted, ActiveJob's dead-letter behavior
-  # takes over — the job still emits `<prefix>.projection.failed` on every
-  # attempt so subscribers see the full retry history.
-  #
-  # Notification payloads include `attempt:` (drawn from ActiveJob's
-  # `executions` accessor — 1 on first attempt, increments per retry) so
-  # subscribers can distinguish first-try success from retry-success.
-  class ProjectionJob < ::ActiveJob::Base
-    # Hand-rolled retry path so the attempt cap reads
-    # `Config#default_async_retries` at perform time. ActiveJob's
-    # `retry_on attempts:` requires a constant Integer (or `:unlimited`)
-    # and is captured at class-definition time — that's incompatible with
-    # the gem's pattern of letting hosts reconfigure `default_async_retries`
-    # in their initializer (or specs flipping it temporarily). We rescue
-    # `StandardError` and re-enqueue manually until the cap is reached.
-    rescue_from(StandardError) do |error|
-      attempts = StandardLedger.config.default_async_retries
-      if executions < attempts
-        # Compute a polynomial backoff inline. Mirrors ActiveJob's
-        # `:polynomially_longer` algorithm (`executions**4 + 2`) without
-        # depending on its private `determine_delay` API.
-        delay = (executions**4) + 2
-        retry_job(wait: delay, error: error)
-      else
-        raise error
-      end
-    end
-
-    # Discard programmer errors immediately — they're deterministic and
-    # retrying just burns the budget. `StandardLedger::Error` is raised by
-    # `#perform` on missing/renamed projection definitions and similar
-    # bookkeeping mistakes; the next attempt would raise the same error.
-    # Declared AFTER the `rescue_from(StandardError)` block above because
-    # `ActiveSupport::Rescuable` searches handlers from the most-recently-
-    # registered first — so this more-specific `StandardLedger::Error`
-    # handler wins over the catch-all retry path for its matching errors.
-    discard_on StandardLedger::Error
-
-    def perform(entry, target_association)
-      definition = entry.class.standard_ledger_projections.find { |d|
-        d.mode == :async && d.target_association == target_association.to_sym
-      }
-      if definition.nil?
-        raise StandardLedger::Error,
-              "no :async projection #{target_association.inspect} on #{entry.class.name}"
-      end
-
-      target = entry.public_send(definition.target_association)
-      return if target.nil?
-
-      prefix = StandardLedger.config.notification_namespace
-      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-
-      begin
-        target.with_lock do
-          definition.projector_class.new.apply(target, entry)
-        end
-      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: :async, error: e, duration_ms: duration_ms,
-          attempt: executions
-        )
-        raise
-      end
-
-      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: :async, duration_ms: duration_ms, attempt: executions
-      )
-    end
-  end
-end

data/lib/standard_ledger/modes/async.rb

@@ -1,141 +0,0 @@
-module StandardLedger
-  module Modes
-    # `:async` mode: applies the projection in a background job enqueued
-    # from the entry's `after_create_commit` callback. The job runs after
-    # the outer transaction has committed, so the entry is durable before
-    # the projection runs — and a job failure does NOT roll back the entry.
-    #
-    # Used when the projection is too expensive or stateful for the entry's
-    # transaction (jsonb rebuild, multi-row aggregate). The canonical
-    # example is nutripod's `Order#payable_balance` / `Order#fulfillable_balance`
-    # jsonb columns, which need to be recomputed from every PaymentRecord /
-    # FulfillmentRecord against the order — work that's safe to defer past
-    # the originating transaction.
-    #
-    # Class-form only: `:async` projections must declare `via: ProjectorClass`,
-    # whose `apply(target, entry)` should recompute from the log inside
-    # `with_lock` rather than apply a delta. Block-form per-kind handlers
-    # aren't safe under retry — incrementing a counter twice on retry is a
-    # silent data corruption bug — so block-form is rejected at registration
-    # time (see `Projector#projects_onto`).
-    #
-    # The strategy installs an `after_create_commit` callback once per entry
-    # class. The callback walks every `:async`-mode projection registered on
-    # the class and enqueues `StandardLedger::ProjectionJob` per (entry,
-    # projection) pair, honoring the optional `if:` guard.
-    #
-    # ## with_modes interop
-    #
-    # `StandardLedger.with_modes(EntryClass => :inline) { ... }` forces async
-    # projections to run synchronously inside the block — useful in unit
-    # specs that want end-to-end coverage without standing up a job runner.
-    # Inline-override mode skips the enqueue and runs `target.with_lock {
-    # projector.apply(target, entry) }` directly. The override is read in
-    # `#call`; specs can capture the empty job queue via `have_enqueued_job`
-    # / `perform_enqueued_jobs` and still observe the projection's effects.
-    class Async
-      # Install the `after_create_commit` callback on `entry_class` exactly
-      # once. Subsequent calls (e.g. when a second `:async` projection is
-      # added later in the class body) are no-ops — the same callback
-      # handles all `:async` 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_commit` hook available). `:async` mode requires
-      #   AR transactional callbacks; non-AR entry classes can't dispatch
-      #   the post-commit enqueue.
-      def self.install!(entry_class)
-        return if entry_class.instance_variable_get(:@_standard_ledger_async_installed)
-
-        unless entry_class.respond_to?(:after_create_commit)
-          raise ArgumentError,
-                "Modes::Async requires an ActiveRecord-backed entry class on " \
-                "#{entry_class.name || entry_class.inspect} — the entry class must inherit " \
-                "from ActiveRecord::Base. Use :inline mode for plain-Ruby entry classes."
-        end
-
-        entry_class.after_create_commit { StandardLedger::Modes::Async.new.call(self) }
-        entry_class.instance_variable_set(:@_standard_ledger_async_installed, true)
-      end
-
-      # Enqueue `ProjectionJob` for every `:async` projection registered on
-      # the entry's class. Called from the `after_create_commit` callback
-      # installed by `.install!`.
-      #
-      # Honors the optional `if:` guard (skips enqueue when guard returns
-      # false) and `StandardLedger.mode_override_for(entry_class)` (when set
-      # to `:inline`, runs the projection synchronously inside `with_lock`
-      # instead of enqueueing).
-      #
-      # A nil target at enqueue time skips silently — the entry's FK was
-      # unset for this projection's association, so there's nothing to
-      # project onto. (The job has its own nil-target guard; this short-
-      # circuit just avoids the wasted enqueue.)
-      #
-      # @param entry [ActiveRecord::Base] the just-committed entry.
-      # @return [void]
-      def call(entry)
-        definitions = async_definitions_for(entry.class)
-        return if definitions.empty?
-
-        override = StandardLedger.mode_override_for(entry.class)
-
-        definitions.each do |definition|
-          next if definition.guard && !entry.instance_exec(&definition.guard)
-
-          if override == :inline
-            run_inline(entry, definition)
-          else
-            target = entry.public_send(definition.target_association)
-            next if target.nil?
-
-            job_class = StandardLedger.config.default_async_job || StandardLedger::ProjectionJob
-            job_class.perform_later(entry, definition.target_association.to_s)
-          end
-        end
-      end
-
-      private
-
-      def async_definitions_for(entry_class)
-        return [] unless entry_class.respond_to?(:standard_ledger_projections_for)
-
-        entry_class.standard_ledger_projections_for(:async)
-      end
-
-      # `with_modes(EntryClass => :inline)` short-circuit: run the projector
-      # synchronously inside `with_lock`, mirroring the job's behavior
-      # without the enqueue. Skips silently when the target is nil so the
-      # nil-FK contract matches the enqueue path.
-      def run_inline(entry, definition)
-        target = entry.public_send(definition.target_association)
-        return if target.nil?
-
-        prefix = StandardLedger.config.notification_namespace
-        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-
-        begin
-          target.with_lock do
-            definition.projector_class.new.apply(target, entry)
-          end
-        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: :async, error: e, duration_ms: duration_ms, attempt: 1
-          )
-          raise
-        end
-
-        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: :async, duration_ms: duration_ms, attempt: 1
-        )
-      end
-    end
-  end
-end

data/lib/standard_ledger/modes/inline.rb

@@ -1,180 +0,0 @@
-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