undertow 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b2c91ae2e1c3eafff3e52438ca4a8c2e2856fd83c2c1097708d3e7f2ed457be
-  data.tar.gz: 385394ce28a3034f17d4e89d3d00528931f38c44a180b338c5bfb43c83b4877b
+  metadata.gz: 4f841e4e433bebfa87d5086cdf621af5ede70a74754a98031645aa6181fcc8eb
+  data.tar.gz: b138e06bb8e54eaf5c40223fc07d08b6148bdbeefc7c9cfb8512b4b23c3a7d7b
 SHA512:
-  metadata.gz: 57614c035d133873d7f3c9b881bc6c59de51c0f2add8bc860eb059f955bdd4cc7a57576e99df1085576db5b64fbdfd7c6b4376136093b46ed259e2e70dc3f87b
-  data.tar.gz: 20cca40fdfe6459d18b264050ce5db678d6d94e537d3bd19a7fbe3a61fb5b7e32bb13bd859a88d263f20d8df4473cc178d6796470d609add092d66ca60229da9
+  metadata.gz: 4d31057a9a903b49a76208fbbeca609aa43ae43dcde2bd3dc98b142118f2694bc648cf1a4ee44958a7c52c1bbd9e3a85fc160c67105748096efadd6e7fb101d0
+  data.tar.gz: ef556acc038295b60fb3083fd3c79f70537f57d773f8ec10d0ead41b7c37019cdda3e20e035e2d0c407b1a5a4bc220562dcb4bd1beb471b596f9466777e2f8e4

data/lib/undertow/dsl.rb

@@ -5,14 +5,14 @@ module Undertow
   # that calls these methods automatically registers itself with Undertow and
   # gets Trackable behavior wired in at boot, no include needed.
   #
-  #   class Activity < ApplicationRecord
-  #     undertow_on_drain ->(model_name, ids, deleted_ids) { ActivityReindexJob.perform_later(ids, deleted_ids) }
-  #     undertow_skip     %w[lock_version searchkick_reindexing]
+  #   class Post < ApplicationRecord
+  #     undertow_on_drain ->(model_name, ids, deleted_ids) { PostSyncJob.perform_later(ids, deleted_ids) }
+  #     undertow_skip     %w[view_count updated_at]
   #
-  #     undertow_depends_on :provider, foreign_key: :provider_id, watched_columns: %w[approved mobile]
-  #     undertow_depends_on :location_series,
-  #                         resolver:        ->(ls) { Activity.where(series_id: ls.series_id) },
-  #                         watched_columns: %w[location_id hidden]
+  #     undertow_depends_on :author, foreign_key: :author_id, watched_columns: %w[name bio]
+  #     undertow_depends_on :tag,
+  #                         resolver:        ->(tag) { Post.joins(:post_tags).where(post_tags: { tag_id: tag.id }) },
+  #                         watched_columns: %w[name slug]
   #   end
   #
   module DSL
@@ -21,19 +21,27 @@ module Undertow
       _undertow_ensure_trackable!
     end
 
+    # Suppress self-tracking when these root-model columns are the only changes.
+    # Accepts strings or symbols; blanks are ignored.
     def undertow_skip(columns)
-      _undertow_config.skip_columns = columns
+      _undertow_config.skip_columns = Array(columns).map(&:to_s).reject(&:blank?).uniq
       _undertow_ensure_trackable!
     end
 
+    # Track invalidations from an upstream association.
+    # `watched_columns` accepts strings or symbols; blanks are ignored.
+    # Empty/nil means no watched-column filter.
     def undertow_depends_on(association, foreign_key: nil, resolver: nil, watched_columns: nil)
       raise ArgumentError, 'provide exactly one of foreign_key: or resolver:' unless foreign_key.nil? ^ resolver.nil?
 
+      normalized_watched = Array(watched_columns).map(&:to_s).
+        reject(&:blank?).uniq.presence
+
       _undertow_config.dependencies << {
          association: association,
          foreign_key: foreign_key,
          resolver: resolver,
-         watched_columns: watched_columns
+         watched_columns: normalized_watched
       }.freeze
       _undertow_ensure_trackable!
     end

data/lib/undertow/trackable.rb

@@ -4,8 +4,9 @@ module Undertow
   # ActiveRecord concern mixed in automatically when a model uses the Undertow DSL
   # (undertow_on_drain, undertow_skip, undertow_depends_on). Never included manually.
   #
-  # Provides class-level callback registration and the skip_columns guard.
-  # Callbacks are wired at boot by the Railtie after all models are loaded.
+  # Provides class-level callback registration and dependency push handlers, plus
+  # instance-level self-tracking handlers. Callbacks are wired at boot by the Railtie
+  # after all models are loaded.
   module Trackable
     extend ActiveSupport::Concern
 
@@ -30,86 +31,117 @@ module Undertow
         (config.dependencies || []).each { |dep| _register_dep_callbacks!(dep) }
       end
 
+      def _push_undertow_pending(ids)
+        Buffer.push_pending(name, ids)
+      end
+
+      def _push_undertow_deleted(ids)
+        Buffer.push_deleted(name, ids)
+      end
+
+      # Enqueues records into the pending buffer without going through AR
+      # callbacks. Use this to replay a batch through the drain handler without
+      # triggering other model lifecycle callbacks, e.g. from a console or a
+      # data migration.
+      #
+      #   Post.undertow_requeue(Post.where(author_id: 123))
+      #   Post.undertow_requeue([136543, 136544])
+      #   Post.undertow_requeue  # all records
+      def undertow_requeue(scope_or_ids = :all)
+        ids = case scope_or_ids
+              when :all                   then pluck(:id)
+              when ActiveRecord::Relation then scope_or_ids.pluck(:id)
+              else                             Array(scope_or_ids)
+              end
+        _push_undertow_pending(ids)
+      end
+
+      def _push_dep_pending(record, dep)
+        ids = _dep_ids_for(record, dep)
+        _push_undertow_pending(ids) if ids.any?
+      end
+
+      def _push_dep_updated(record, dep)
+        watched = dep[:watched_columns]
+        # Two non-obvious cases where after_commit on :update fires:
+        #   - no-op save: saved_changes is {}, suppressed when watched_columns is configured
+        #   - touch (e.g. belongs_to touch: true): saved_changes contains only updated_at,
+        #     suppressed only when watched_columns is configured and updated_at is not in it
+        return if watched && (record.saved_changes.keys & watched).none?
+
+        _push_dep_pending(record, dep)
+      end
+
       private
 
       def _register_self_callbacks!
-        after_commit  :_push_self_pending, on: %i[create update]
+        after_commit  :_push_self_created, on: :create
+        after_commit  :_push_self_updated, on: :update
         after_destroy :_push_self_deleted
-        after_restore :_push_self_pending if respond_to?(:after_restore)
+        after_restore :_push_self_restored if respond_to?(:after_restore)
       end
 
       def _register_dep_callbacks!(dep)
         dep_class = _resolve_dep_class(dep)
-        return unless dep_class
-
         root_class = self
-        watched    = dep[:watched_columns].presence # [] treated same as nil, watch all
-
-        resolver = dep[:resolver] || begin
-          fk = dep[:foreign_key]
-          ->(record) { root_class.where(fk => record.id) }
-        end
 
-        push_pending = ->(record) {
-          ids = resolver.call(record).pluck(:id)
-          next unless ids.any?
+        dep_class.after_commit(on: :create) { root_class._push_dep_pending(self, dep) }
+        dep_class.after_commit(on: :update) { root_class._push_dep_updated(self, dep) }
 
-          root_class._push_undertow_pending(ids)
-        }
+        # Soft-delete gems fire run_callbacks(:destroy), triggering after_destroy, but
+        # mark the record deleted via update_columns (bypassing after_commit),
+        # so the create/update callbacks above never double-fire on a soft delete.
+        dep_class.after_destroy { root_class._push_dep_pending(self, dep) }
 
-        # Skip create/update callback when watched_columns is set and none changed.
-        # Note: saved_changes is empty when touched via belongs_to touch: true (bypasses
-        # dirty tracking), that correctly falls through to skip here.
-        dep_class.after_commit on: %i[create update] do
-          next if watched && (saved_changes.keys & watched).none?
-
-          push_pending.call(self)
-        end
-
-        # Dep destroyed, reindex surviving root records. SoftDeletable calls
-        # run_callbacks(:destroy), which fires after_destroy, but update_columns does NOT
-        # trigger after_commit, so scoping after_commit to [:create, :update] above
-        # ensures destroy commits don't double-fire.
-        dep_class.after_destroy { push_pending.call(self) }
-
-        # Dep restored, after_restore is the only hook that fires because restore!
-        # uses update_columns, bypassing after_commit.
-        if dep_class.respond_to?(:after_restore)
-          dep_class.after_restore { push_pending.call(self) }
-        end
+        # Soft-delete restores use update_columns to unmark the record, bypassing
+        # after_commit. after_restore is the only hook that fires for restores.
+        dep_class.after_restore { root_class._push_dep_pending(self, dep) } if dep_class.respond_to?(:after_restore)
       end
 
       def _resolve_dep_class(dep)
-        if dep[:resolver]
+        reflect_on_association(dep[:association])&.klass ||
           dep[:association].to_s.classify.constantize
+      end
+
+      def _dep_ids_for(record, dep)
+        if dep[:resolver]
+          dep[:resolver].call(record).pluck(:id)
         else
-          reflect_on_association(dep[:association])&.klass ||
-            dep[:association].to_s.classify.constantize
+          where(dep[:foreign_key] => record.id).pluck(:id)
         end
       end
+    end
 
-      public
-
-      def _push_undertow_pending(ids)
-        Buffer.push_pending(name, ids)
-      end
+    private
 
-      def _push_undertow_deleted(ids)
-        Buffer.push_deleted(name, ids)
-      end
+    def _push_self_created
+      _enqueue_self_pending
     end
 
-    private
+    def _push_self_updated
+      return unless _self_update_requires_invalidation?
 
-    def _push_self_pending
-      ignored = self.class._undertow_ignored_columns
-      return if ignored.any? && saved_changes.any? && (saved_changes.keys - ignored).empty?
+      _enqueue_self_pending
+    end
 
-      self.class._push_undertow_pending([id])
+    def _push_self_restored
+      _enqueue_self_pending
     end
 
     def _push_self_deleted
       self.class._push_undertow_deleted([id])
     end
+
+    def _enqueue_self_pending
+      self.class._push_undertow_pending([id])
+    end
+
+    def _self_update_requires_invalidation?
+      changed = saved_changes.keys
+      return false if changed.empty?
+
+      ignored = self.class._undertow_ignored_columns
+      (changed - ignored).any?
+    end
   end
 end

data/lib/undertow/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Undertow
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: undertow
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Nathan Allen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-06 00:00:00.000000000 Z
+date: 2026-07-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord