undertow 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 53f9ee409c2585ff551f21884f10e8eec276ee750e6f3c12109280cc79fdd934
+  data.tar.gz: e343c5be340f08b271e5851a91c0a3c5f363ce28357b5deb83657ae5c242f494
+SHA512:
+  metadata.gz: 28d46d6ddfb4e02ef12dcc001295e9f39034708af79ba12761553d61c32fe96d6d64769cdf45c9df8d3276ff19c9de0080b843ff54cc575e94f7a947db545c99
+  data.tar.gz: 49c01b579d3797b755d52c077890753abba9defe3b49ca7e7871564c4ee31627328933a00e0fa0f3e031af16f5e2cb54354516dc277bc87dfc18e68cd464379c

data/lib/undertow/buffer.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Undertow
+  # Low-level Redis SET operations used by Trackable callbacks and DrainJob.
+  # All methods are no-ops when tracking is disabled or Redis is unavailable.
+  module Buffer
+    class << self
+      def push_pending(model_name, ids)
+        return if Undertow.tracking_disabled?
+
+        with_redis do |r|
+          r.sadd(Registry.pending_key(model_name), ids)
+          r.sadd(Registry::MODELS_KEY, model_name)
+        end
+      end
+
+      def push_deleted(model_name, ids)
+        return if Undertow.tracking_disabled?
+
+        with_redis do |r|
+          r.sadd(Registry.deleted_key(model_name), ids)
+          r.sadd(Registry::MODELS_KEY, model_name)
+        end
+      end
+
+      def pop_pending(model_name, count)
+        with_redis { |r| r.spop(Registry.pending_key(model_name), count) } || []
+      end
+
+      def pop_deleted(model_name, count)
+        with_redis { |r| r.spop(Registry.deleted_key(model_name), count) } || []
+      end
+
+      def pending_model_names
+        with_redis { |r| r.smembers(Registry::MODELS_KEY) } || []
+      end
+
+      def deregister_model(model_name)
+        with_redis { |r| r.srem(Registry::MODELS_KEY, model_name) }
+      end
+
+      def reregister_model(model_name)
+        with_redis { |r| r.sadd(Registry::MODELS_KEY, model_name) }
+      end
+
+      def remaining(model_name)
+        with_redis do |r|
+          r.scard(Registry.pending_key(model_name)) +
+          r.scard(Registry.deleted_key(model_name))
+        end || 0
+      end
+
+      def restore_pending(model_name, ids)
+        with_redis { |r| r.sadd(Registry.pending_key(model_name), ids) } if ids.any?
+      end
+
+      def restore_deleted(model_name, ids)
+        with_redis { |r| r.sadd(Registry.deleted_key(model_name), ids) } if ids.any?
+      end
+
+      def pending?
+        with_redis { |r| r.scard(Registry::MODELS_KEY) > 0 } || false
+      end
+
+      # Acquire the distributed drain lock using SET NX. Returns true if the lock
+      # was acquired, false if it was already held. TTL is a safety valve in case
+      # the job process dies before releasing it.
+      def acquire_drain_lock(ttl: 30)
+        lock_key = Undertow.configuration.drain_lock_key
+        return true unless lock_key
+
+        with_redis { |r| r.set(lock_key, '1', nx: true, ex: ttl) } || false
+      end
+
+      # Release the drain lock. Called at the start of DrainJob#perform so the
+      # scheduler can enqueue another job for IDs that arrive while this one runs.
+      def release_drain_lock
+        lock_key = Undertow.configuration.drain_lock_key
+        return unless lock_key
+
+        with_redis { |r| r.del(lock_key) }
+      end
+
+      private
+
+      def with_redis
+        client = Undertow.configuration.redis!
+        if client.respond_to?(:with)
+          client.with { |conn| yield conn }
+        else
+          yield client
+        end
+      rescue Redis::BaseConnectionError, Redis::CommandError => e
+        Rails.logger.error("Undertow: Redis error: #{e.message}") if defined?(Rails)
+        nil
+      end
+    end
+  end
+end

data/lib/undertow/configuration.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Undertow
+  class Configuration
+    # A Redis client or connection pool. Must respond to :sadd, :srem, :smembers,
+    # :spop, :scard, :del. Injected by the host application:
+    #
+    #   Undertow.configure { |c| c.redis = Redis.new(url: ENV['REDIS_URL']) }
+    #
+    attr_accessor :redis
+
+    # Maximum number of IDs to pop from the buffer per drain per model.
+    attr_accessor :max_batch
+
+    # ActiveJob queue to use for DrainJob.
+    attr_accessor :queue_name
+
+    # Redis key used for the distributed drain lock. The scheduler acquires this
+    # lock (SET NX) before enqueueing DrainJob; the job releases it immediately
+    # on start so new work arriving mid-drain gets its own job on the next tick.
+    # Set to nil to disable lock management entirely.
+    attr_accessor :drain_lock_key
+
+    def initialize
+      @max_batch      = 1_000
+      @queue_name     = :undertow
+      @drain_lock_key = 'undertow:drain:lock'
+    end
+
+    def redis!
+      redis or raise 'Undertow.configuration.redis is not set'
+    end
+  end
+end

data/lib/undertow/drain_job.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Undertow
+  # Drains the per-model Redis buffers and delivers batches of dirty IDs to
+  # each model's configured on_drain handler.
+  #
+  # Publishes two ActiveSupport::Notifications events:
+  #   drain.undertow  — after a successful on_drain call ({ model:, ids:, deleted_ids: })
+  #   error.undertow  — when on_drain raises ({ model:, exception: })
+  class DrainJob < ActiveJob::Base
+    queue_as { Undertow.configuration.queue_name }
+
+    def perform
+      # Release the lock before draining so the scheduler can enqueue another job
+      # for IDs that arrive while this one is running.
+      Buffer.release_drain_lock
+
+      model_names = Buffer.pending_model_names
+      return if model_names.empty?
+
+      model_names.each { |name| drain_model(name) }
+    end
+
+    private
+
+    def drain_model(model_name)
+      max = Undertow.configuration.max_batch
+
+      # Deregister before popping — any concurrent push will re-add the model,
+      # preventing the race where srem fires after a concurrent sadd.
+      Buffer.deregister_model(model_name)
+
+      ids         = Buffer.pop_pending(model_name, max)
+      deleted_ids = Buffer.pop_deleted(model_name, max)
+      return if ids.empty? && deleted_ids.empty?
+
+      # If the batch was capped, re-register so the next scheduler tick picks up.
+      Buffer.reregister_model(model_name) if Buffer.remaining(model_name).positive?
+
+      config = Registry[model_name]
+      raise "No Undertow config registered for #{model_name}" unless config
+      raise "#{model_name} is missing undertow_on_drain" unless config.on_drain
+
+      config.on_drain.call(model_name, ids, deleted_ids)
+
+      ActiveSupport::Notifications.instrument('drain.undertow', {
+        model:       model_name,
+        ids:         ids,
+        deleted_ids: deleted_ids
+      })
+    rescue StandardError => e
+      Buffer.restore_pending(model_name, ids)         if ids&.any?
+      Buffer.restore_deleted(model_name, deleted_ids) if deleted_ids&.any?
+      Buffer.reregister_model(model_name)
+      ActiveSupport::Notifications.instrument('error.undertow', { model: model_name, exception: e })
+      Rails.logger.error("[Undertow::DrainJob] #{model_name}: #{e.message}") if defined?(Rails)
+    end
+  end
+end

data/lib/undertow/dsl.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Undertow
+  # Class-level DSL extended onto ActiveRecord::Base by the Railtie. Any model
+  # 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]
+  #
+  #     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]
+  #   end
+  #
+  module DSL
+    def undertow_on_drain(callable)
+      _undertow_config.on_drain = callable
+      _undertow_ensure_trackable!
+    end
+
+    def undertow_skip(columns)
+      _undertow_config.skip_columns = columns
+      _undertow_ensure_trackable!
+    end
+
+    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?
+
+      _undertow_config.dependencies << {
+        association:     association,
+        foreign_key:     foreign_key,
+        resolver:        resolver,
+        watched_columns: watched_columns
+      }.freeze
+      _undertow_ensure_trackable!
+    end
+
+    private
+
+    def _undertow_config
+      Registry.register(name)
+    end
+
+    def _undertow_ensure_trackable!
+      include Undertow::Trackable unless ancestors.include?(Undertow::Trackable)
+    end
+  end
+end

data/lib/undertow/railtie.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Undertow
+  class Railtie < Rails::Railtie
+    # Extend ActiveRecord::Base with the Undertow DSL so any model can call
+    # undertow_on_drain, undertow_skip, and undertow_depends_on in its class body.
+    initializer 'undertow.extend_active_record' do
+      ActiveSupport.on_load(:active_record) { extend Undertow::DSL }
+    end
+
+    # Wire after_commit callbacks onto every registered model and its dependencies
+    # after all models are loaded. Runs on each code reload in development.
+    config.to_prepare do
+      Registry.all.each do |model_name, config|
+        model_name.constantize.register_undertow_callbacks!(config)
+      rescue NameError => e
+        Rails.logger.warn("[Undertow] Could not load #{model_name}: #{e.message}")
+      end
+    end
+  end
+end

data/lib/undertow/registry.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Undertow
+  # Holds the declared dependency configuration for every tracked model.
+  # Populated at class load time via the DSL (undertow_on_drain, undertow_skip,
+  # undertow_depends_on); consumed by the Railtie and DrainJob.
+  module Registry
+    MODELS_KEY = 'undertow:pending:models'
+
+    class ModelConfig
+      attr_reader   :model_name, :dependencies
+      attr_accessor :on_drain, :skip_columns
+
+      def initialize(model_name)
+        @model_name   = model_name
+        @dependencies = []
+        @skip_columns = []
+        @on_drain     = nil
+      end
+    end
+
+    class << self
+      # Returns an existing config or creates a new one for model_name.
+      # Called by each DSL macro the first time it fires on a model.
+      def register(model_name)
+        all[model_name] ||= ModelConfig.new(model_name)
+      end
+
+      def all
+        @all ||= {}
+      end
+
+      def [](model_name)
+        all[model_name]
+      end
+
+      def key?(model_name)
+        all.key?(model_name)
+      end
+
+      def pending_key(model_name) = "undertow:pending:#{model_name}"
+      def deleted_key(model_name) = "undertow:deleted:#{model_name}"
+    end
+  end
+end

data/lib/undertow/trackable.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+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.
+  module Trackable
+    extend ActiveSupport::Concern
+
+    included do
+      # Columns listed here suppress self-tracking when they are the *only*
+      # things that changed — prevents feedback loops from columns updated by
+      # the drain handler itself.
+      class_attribute :_undertow_ignored_columns, default: [], instance_writer: false
+    end
+
+    class_methods do
+      # Called by the Railtie after all models/associations are loaded.
+      # Idempotent — safe to call multiple times (e.g. in reloading environments).
+      def register_undertow_callbacks!(config)
+        return if @_undertow_callbacks_registered
+
+        @_undertow_callbacks_registered = true
+
+        self._undertow_ignored_columns = config.skip_columns
+
+        _register_self_callbacks!
+        (config.dependencies || []).each { |dep| _register_dep_callbacks!(dep) }
+      end
+
+      private
+
+      def _register_self_callbacks!
+        after_commit  :_push_self_pending, on: %i[create update]
+        after_destroy :_push_self_deleted
+        after_restore :_push_self_pending 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?
+
+          root_class._push_undertow_pending(ids)
+        }
+
+        # 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
+      end
+
+      def _resolve_dep_class(dep)
+        if dep[:resolver]
+          dep[:association].to_s.classify.constantize
+        else
+          reflect_on_association(dep[:association])&.klass ||
+            dep[:association].to_s.classify.constantize
+        end
+      end
+
+      public
+
+      def _push_undertow_pending(ids)
+        Buffer.push_pending(name, ids)
+      end
+
+      def _push_undertow_deleted(ids)
+        Buffer.push_deleted(name, ids)
+      end
+    end
+
+    private
+
+    def _push_self_pending
+      ignored = self.class._undertow_ignored_columns
+      return if ignored.any? && saved_changes.any? && (saved_changes.keys - ignored).empty?
+
+      self.class._push_undertow_pending([id])
+    end
+
+    def _push_self_deleted
+      self.class._push_undertow_deleted([id])
+    end
+  end
+end

data/lib/undertow/version.rb

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

data/lib/undertow.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'active_record'
+
+require_relative 'undertow/version'
+require_relative 'undertow/configuration'
+require_relative 'undertow/registry'
+require_relative 'undertow/buffer'
+require_relative 'undertow/dsl'
+require_relative 'undertow/trackable'
+require_relative 'undertow/drain_job'
+require_relative 'undertow/railtie' if defined?(Rails::Railtie)
+
+module Undertow
+  class << self
+    def configure
+      yield configuration
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Suppress all buffer pushes inside the block. Useful in tests and
+    # data migrations where dependency callbacks should not fire.
+    def without_tracking
+      previous = Thread.current[:undertow_disabled]
+      Thread.current[:undertow_disabled] = true
+      yield
+    ensure
+      Thread.current[:undertow_disabled] = previous
+    end
+
+    def tracking_disabled?
+      Thread.current[:undertow_disabled]
+    end
+
+    # Called from the host application's scheduler on each tick. Checks for
+    # pending work, acquires the drain lock, and enqueues DrainJob — no other
+    # wiring required:
+    #
+    #   every(1.second, 'undertow') { Undertow.tick }
+    #
+    def tick
+      return unless Buffer.pending?
+      return unless Buffer.acquire_drain_lock
+
+      DrainJob.perform_later
+    end
+  end
+end

data/undertow.gemspec

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative 'lib/undertow/version'
+
+Gem::Specification.new do |spec|
+  spec.name     = 'undertow'
+  spec.version  = Undertow::VERSION
+  spec.authors  = ['Nathan Allen']
+  spec.email    = ['hello@nallenscott.com']
+  spec.summary  = 'Buffered, dependency-aware change propagation for ActiveRecord models'
+  spec.homepage = 'https://github.com/nallenscott/undertow'
+  spec.license  = 'MIT'
+
+  spec.metadata = {
+    'source_code_uri' => 'https://github.com/nallenscott/undertow',
+    'changelog_uri'   => 'https://github.com/nallenscott/undertow/blob/main/CHANGELOG.md',
+    'bug_tracker_uri' => 'https://github.com/nallenscott/undertow/issues'
+  }
+
+  spec.required_ruby_version = '>= 3.0'
+
+  spec.files = Dir['lib/**/*.rb'] + ['undertow.gemspec']
+
+  spec.add_dependency 'activerecord',  '~> 7.0'
+  spec.add_dependency 'activesupport', '~> 7.0'
+  spec.add_dependency 'activejob',     '~> 7.0'
+  spec.add_dependency 'redis',         '~> 5.0'
+end

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification
+name: undertow
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nathan Allen
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-04-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: activejob
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description:
+email:
+- hello@nallenscott.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/undertow.rb
+- lib/undertow/buffer.rb
+- lib/undertow/configuration.rb
+- lib/undertow/drain_job.rb
+- lib/undertow/dsl.rb
+- lib/undertow/railtie.rb
+- lib/undertow/registry.rb
+- lib/undertow/trackable.rb
+- lib/undertow/version.rb
+- undertow.gemspec
+homepage: https://github.com/nallenscott/undertow
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/nallenscott/undertow
+  changelog_uri: https://github.com/nallenscott/undertow/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/nallenscott/undertow/issues
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Buffered, dependency-aware change propagation for ActiveRecord models
+test_files: []