standard_ledger 0.5.0 → 0.6.0

data/lib/standard_ledger/modes/matview.rb

@@ -1,146 +0,0 @@
-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)
-        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)
-
-        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 and RefreshInsideTransaction from
-        # the boundary check should propagate without firing the failed
-        # notification — the SQL was never issued.
-        raise if e.is_a?(ArgumentError) || e.is_a?(StandardLedger::RefreshInsideTransaction)
-
-        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)
-        # Bare identifier OR exactly one schema-qualified `schema.view` part.
-        # The previous shape `\A[a-zA-Z_][a-zA-Z0-9_.]*\z` allowed trailing
-        # dots (`reporting.`) and unlimited qualification (`a.b.c.d`); both
-        # would round-trip to a Postgres syntax error at `connection.execute`
-        # time rather than the gem boundary.
-        return if view_name.to_s.match?(/\A[a-zA-Z_][a-zA-Z0-9_]*(\.[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!
-
-      # Reject `refresh!` calls issued from inside an open transaction when
-      # `concurrently: true`. Postgres rejects
-      # `REFRESH MATERIALIZED VIEW CONCURRENTLY` inside a transaction block
-      # (and would otherwise raise `PG::ActiveSqlTransaction` mid-call); we
-      # catch it at the gem boundary so the failure is attributable.
-      #
-      # The non-concurrent (`concurrently: false`) form *is* permitted inside
-      # a transaction by Postgres, so we only guard the concurrent path.
-      #
-      # Use `connection.add_transaction_record { … }` to defer to after-commit
-      # if you need read-your-write semantics from inside a transactional
-      # operation; otherwise, move the refresh outside the transaction.
-      def self.check_transaction_state!(view_name, concurrently:)
-        return unless concurrently
-        return unless ActiveRecord::Base.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, or defer it via " \
-              "`connection.add_transaction_record { ... }` for after-commit execution."
-      end
-      private_class_method :check_transaction_state!
-
-      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

@@ -1,132 +0,0 @@
-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/modes/trigger.rb

@@ -1,50 +0,0 @@
-module StandardLedger
-  module Modes
-    # `:trigger` mode: the host owns a database trigger (created in a Rails
-    # migration) that updates the projection target's columns on every
-    # entry INSERT. The gem records the trigger's name and the equivalent
-    # rebuild SQL, but does **not** create or manage the trigger itself —
-    # giving a Ruby DSL the power to install/replace triggers is a deploy
-    # footgun (silent re-creation on `db:schema:load` against a non-empty
-    # DB), and triggers are versioned by `db/schema.rb` like any other DDL.
-    #
-    # Two consumers read the recorded metadata:
-    #
-    # - `StandardLedger.rebuild!` runs the rebuild SQL when invoked,
-    #   binding `:target_id` to each target the log references. The same
-    #   recompute path as `:sql` mode — the only difference is that the
-    #   after-create application is performed by the database trigger
-    #   rather than a Ruby callback.
-    # - The `standard_ledger:doctor` rake task verifies that the named
-    #   trigger exists in the connected schema. Migration drift (a missing
-    #   or renamed trigger) is caught at deploy time, not at runtime.
-    #
-    # Unlike `:inline` and `:sql`, this strategy does NOT install an
-    # `after_create` callback — the trigger fires from the database. The
-    # `install!` no-op only marks the entry class as having at least one
-    # `:trigger` projection registered (mirrors the `Modes::Matview` shape).
-    #
-    # See `standard_ledger-design.md` §5.3.4 for the full contract.
-    class Trigger
-      # Mark the entry class as having at least one `:trigger` projection
-      # registered. The actual trigger metadata lives on the entry class's
-      # `standard_ledger_projections` array; this method exists only to
-      # mirror the `Modes::*.install!` shape so `Projector#install_mode_callbacks_for`
-      # can dispatch uniformly across modes.
-      #
-      # No `after_create` callback is installed — the trigger runs in the
-      # database, not Ruby. Idempotent across multiple `:trigger`
-      # projections on the same entry class.
-      #
-      # @param entry_class [Class] the host entry class (unused — kept for
-      #   parity with the other strategy classes).
-      # @return [void]
-      def self.install!(_entry_class)
-        # Intentionally empty: trigger projections fire from the DB, so
-        # there's no Ruby-side callback to wire. The DSL has already
-        # captured `trigger_name` and `recompute_sql` on the Definition;
-        # `rebuild!` and the `doctor` rake task consume those directly.
-      end
-    end
-  end
-end