standard_ledger 0.2.0 → 0.4.0

data/lib/standard_ledger.rb

@@ -14,7 +14,10 @@ require "standard_ledger/projector"
 require "standard_ledger/modes/inline"
 require "standard_ledger/modes/sql"
 require "standard_ledger/modes/matview"
+require "standard_ledger/modes/trigger"
+require "standard_ledger/modes/async"
 require "standard_ledger/jobs/matview_refresh_job"
+require "standard_ledger/jobs/projection_job"
 require "standard_ledger/engine" if defined?(::Rails::Engine)
 
 # StandardLedger captures the recurring "immutable journal entry → N
@@ -197,9 +200,18 @@ module StandardLedger
     #   refresh *is* rebuild. Postgres has no partial-refresh primitive,
     #   so `target:` / `target_class:` scope arguments are ignored for
     #   `:matview` projections and the full view is always refreshed.
-    # - `:async`, `:sql`, `:trigger` modes are not yet supported by
-    #   `rebuild!`; they raise `StandardLedger::Error`. Each lands with
-    #   its mode's own PR.
+    # - `:sql` and `:trigger` projections rebuild by running their
+    #   recorded rebuild SQL with `:target_id` bound to each target's
+    #   id. For `:trigger`, the database trigger fires on entry INSERT;
+    #   `rebuild!` runs the same logical recompute against each target
+    #   the log references. The gem does NOT verify or recreate the
+    #   trigger here — `standard_ledger:doctor` is the deploy-time
+    #   check for trigger presence.
+    # - `:async` projections rebuild via the same per-target semantics as
+    #   `:inline` (delegates to `definition.projector_class.new.rebuild(target)`).
+    #   The mode difference is only in the after-create path (in-transaction
+    #   vs. post-commit job), not in the rebuild path, which always runs
+    #   synchronously.
     #
     # Atomicity: each (target, projection) pair runs in its own
     # transaction. A failure mid-loop is **not** rolled back — earlier
@@ -281,7 +293,7 @@ module StandardLedger
         validate_rebuildable_projector!(entry_class, definition)
 
         each_rebuild_target(entry_class, definition, target: target, batch_size: batch_size) do |t|
-          if definition.mode == :sql
+          if definition.mode == :sql || definition.mode == :trigger
             rebuild_one_sql(entry_class, definition, t)
           else
             rebuild_one(entry_class, definition, t)
@@ -420,13 +432,21 @@ module StandardLedger
       reflection.klass
     end
 
-    # Refuse to rebuild for modes that don't yet implement the
-    # log-replay path. `:inline`, `:sql`, and `:matview` are the supported
-    # modes today; `:async` and `:trigger` land with their own mode PRs.
+    # All five projection modes (`:inline`, `:async`, `:sql`, `:matview`,
+    # `:trigger`) implement a log-replay path through this method.
+    #
+    # `:async` and `:inline` share the same per-target rebuild semantics —
+    # both delegate to `definition.projector_class.new.rebuild(target)`.
+    # The difference between the two modes is only in the after-create
+    # path (in-transaction vs. post-commit job), not in the rebuild path,
+    # which always runs synchronously.
     def validate_rebuildable_mode!(entry_class, definition)
       return if definition.mode == :inline
+      return if definition.mode == :async
+      return if definition.mode == :manual
       return if definition.mode == :sql
       return if definition.mode == :matview
+      return if definition.mode == :trigger
 
       raise StandardLedger::Error,
             "rebuild! does not yet support mode: #{definition.mode.inspect} " \
@@ -463,10 +483,12 @@ module StandardLedger
     # rebuildable should extract a `Projection` subclass and implement
     # `rebuild(target)`.
     def validate_rebuildable_projector!(entry_class, definition)
-      # `:sql` mode carries its rebuild path in the recompute SQL itself —
-      # no projector class is required (and `via:` is rejected at
-      # registration). Skip the class-form preflight checks below.
+      # `:sql` and `:trigger` modes carry their rebuild path in the
+      # recompute / rebuild SQL itself — no projector class is required
+      # (and `via:` is rejected at registration). Skip the class-form
+      # preflight checks below.
       return if definition.mode == :sql
+      return if definition.mode == :trigger
 
       if definition.projector_class.nil?
         raise StandardLedger::NotRebuildable,
@@ -535,11 +557,12 @@ module StandardLedger
       )
     end
 
-    # `:sql` mode rebuild path: run the same recompute SQL the
-    # `after_create` callback runs, just bound to this target's id rather
-    # than the entry's foreign key. The recompute SQL is the entire
-    # contract for `:sql` projections — there's no projector class to
-    # invoke; the after-create and rebuild paths share one statement.
+    # `:sql` / `:trigger` mode rebuild path: run the recorded recompute
+    # SQL bound to this target's id. For `:sql` mode this is the same
+    # statement the `after_create` callback runs; for `:trigger` mode
+    # it's the rebuild SQL the host registered (the database trigger
+    # itself owns the after-INSERT path). Either way there's no
+    # projector class to invoke — the SQL is the entire contract.
     def rebuild_one_sql(entry_class, definition, target)
       target.class.transaction do
         sql = ActiveRecord::Base.sanitize_sql_array([ definition.recompute_sql, { target_id: target.id } ])

data/lib/tasks/standard_ledger.rake

@@ -0,0 +1,60 @@
+namespace :standard_ledger do
+  # PostgreSQL-only: queries `pg_trigger` directly. The only mode that
+  # registers a trigger today is `:trigger`, and the only adopter is
+  # nutripod-web (Postgres). SQLite has no comparable per-statement
+  # trigger introspection that makes sense for this gem's contract — if
+  # a non-Postgres host adopts `:trigger` mode in the future, they'll
+  # need to extend this task with a connection-adapter dispatch. The
+  # task is loud about its Postgres assumption: a `pg_trigger` query
+  # against a non-Postgres connection will raise, which is preferable
+  # to silently passing.
+  desc "Verify that every :trigger projection's trigger exists in the database (Postgres-only)"
+  task doctor: :environment do
+    require "standard_ledger"
+
+    # Discover entry classes by walking ActiveRecord descendants for
+    # ones that include `StandardLedger::Projector` and have at least
+    # one `:trigger` projection registered. The host's eager loading
+    # (Rails default in production / when explicitly invoked in dev)
+    # ensures all entry classes are loaded before this iterates.
+    entry_classes = ActiveRecord::Base.descendants.select { |klass|
+      klass.respond_to?(:standard_ledger_projections) &&
+        klass.standard_ledger_projections.any? { |d| d.mode == :trigger }
+    }
+
+    missing = []
+    entry_classes.each do |klass|
+      klass.standard_ledger_projections_for(:trigger).each do |definition|
+        # `pg_trigger.tgname` is the trigger's name as known to Postgres,
+        # but trigger names are scoped per-table — two tables can each
+        # have a trigger called e.g. `update_counts`. Join `pg_trigger`
+        # to `pg_class` and filter by the entry class's table name so the
+        # doctor reports presence on the *correct* table, not "anywhere
+        # in the schema". Use `klass.connection` (rather than
+        # `ActiveRecord::Base.connection`) so multi-DB setups query the
+        # connection that owns the entry class's table.
+        result = klass.connection.exec_query(
+          "SELECT 1 FROM pg_trigger t " \
+          "JOIN pg_class c ON c.oid = t.tgrelid " \
+          "WHERE t.tgname = $1 AND c.relname = $2 " \
+          "LIMIT 1",
+          "standard_ledger:doctor",
+          [ definition.trigger_name, klass.table_name ]
+        )
+        if result.rows.empty?
+          missing << "  #{klass.name}##{definition.target_association}: trigger #{definition.trigger_name.inspect} not found"
+        end
+      end
+    end
+
+    if missing.empty?
+      puts "All :trigger projections have their triggers present."
+    else
+      warn "Missing triggers detected:"
+      missing.each { |line| warn line }
+      warn ""
+      warn "Run the migration that creates the trigger, or check that the trigger name in `projects_onto` matches the actual trigger name in the schema."
+      exit 1
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_ledger
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -122,10 +122,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 inline,
-  sql, and matview projection modes (async and trigger modes land in subsequent releases);
-  enforces idempotency-by-unique-index; and provides a deterministic rebuild path
-  from the entry log.
+  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.
 email:
 - code@jaryl.dev
 executables: []
@@ -145,9 +146,12 @@ files:
 - 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/projection.rb
 - lib/standard_ledger/projector.rb
 - lib/standard_ledger/result.rb
@@ -155,6 +159,7 @@ files:
 - 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