resilient_reads 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e7c0878b6b094bf3bad43d07eb6ee29d7dd27aa49aa50ea125a5d760fb3669e
-  data.tar.gz: 5a04bbd5b53d6aab8bfcf713e27a520f0c82bca1274e48271d737a2a79319bb8
+  metadata.gz: 4bbb75d50de2bb59656b1f4e944a3187c01c16c36fb02a21c30a7c3dc7eee953
+  data.tar.gz: 6474b24d88c87626dc7d35a2b080ea06d603d0a4071733122e73273cd2143404
 SHA512:
-  metadata.gz: 76042b2aa715011260f54d32e8960a224b95a95a69cb3d53ea41c72512751189ed06af05cd9cf584c6358883688e23d22cf4661cf43e9572a7e97a95db808a1e
-  data.tar.gz: 1871f6426fff9338da34e3142f633c5107fff4045fa7c770fd74a32e5c534c700972d6c876e2d26e5ae42440896e0d8ab840b68cd2875f91a5003eecf40b135f
+  metadata.gz: a6c3241dd6d5a240262da022d8f53a5946d54d15c1efb1d47e3d23fb645db3d4d58ebcd5713ace5700e0d733a1171188692f3ffe00819fa79d7a43bed6260f4c
+  data.tar.gz: 82e30dc4fcbffa079390b60fa4e2f35cfb68025ea7fc88a33896ce5aed3faabc1b094d52cd558c017e7de3fc64bb017b41c6217fdb0709295a0a1b9946db4331

data/.idea/.gitignore

@@ -0,0 +1,10 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Editor-based HTTP Client requests
+/httpRequests/
+# Ignored default folder with query files
+/queries/
+# Datasource local storage ignored files
+/dataSources/
+/dataSources.local.xml

data/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/resilient_reads.iml" filepath="$PROJECT_DIR$/.idea/resilient_reads.iml" />
+    </modules>
+  </component>
+</project>

data/.idea/resilient_reads.iml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="RUBY_MODULE" version="4">
+  <component name="ModuleRunConfigurationManager">
+    <shared />
+  </component>
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$">
+      <sourceFolder url="file://$MODULE_DIR$/features" isTestSource="true" />
+      <sourceFolder url="file://$MODULE_DIR$/spec" isTestSource="true" />
+      <sourceFolder url="file://$MODULE_DIR$/test" isTestSource="true" />
+    </content>
+    <orderEntry type="jdk" jdkName="RVM: ruby-3.4.2" jdkType="RUBY_SDK" />
+    <orderEntry type="sourceFolder" forTests="false" />
+    <orderEntry type="library" scope="PROVIDED" name="bundler (v2.7.2, RVM: ruby-3.4.2) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="minitest (v5.25.4, RVM: ruby-3.4.2) [gem]" level="application" />
+    <orderEntry type="library" scope="PROVIDED" name="rake (v13.3.1, RVM: ruby-3.4.2) [gem]" level="application" />
+  </component>
+</module>

data/.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="$PROJECT_DIR$" vcs="Git" />
+  </component>
+</project>

data/lib/resilient_reads/active_job_extension.rb

@@ -0,0 +1,21 @@
+module ResilientReads
+  # Mix into ActiveJob::Base to provide a class-level +distribute_reads+
+  # macro that wraps the entire +perform+ in a distribute_reads block.
+  #
+  #   class ReportJob < ApplicationJob
+  #     distribute_reads
+  #     def perform; ... end
+  #   end
+  #
+  module ActiveJobExtension
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def distribute_reads(**options)
+        around_perform do |_job, block|
+          ResilientReads.run(**options, &block)
+        end
+      end
+    end
+  end
+end

data/lib/resilient_reads/adapter_patch.rb

@@ -0,0 +1,147 @@
+module ResilientReads
+  # Prepended onto the database adapter (e.g. PostgreSQLAdapter, Mysql2Adapter, TrilogyAdapter).
+  # Intercepts raw_execute and routes SELECT queries to a healthy replica
+  # when inside a distribute_reads block.  Writes always pass through to
+  # the primary connection.
+  #
+  # Uses *args/**kwargs to stay compatible across Rails versions:
+  #   Rails 7.1/7.2: raw_execute(sql, name, async:, allow_retry:, materialize_transactions:)
+  #   Rails 8.0+:    raw_execute(sql, name, binds, prepare:, async:, allow_retry:, materialize_transactions:, batch:)
+  module AdapterPatch
+    # Query names that should never be routed to a replica. These are
+    # schema introspection or internal bookkeeping queries that run during
+    # model loading and connection setup.
+    SKIP_NAMES = Set.new(%w[SCHEMA EXPLAIN]).freeze
+
+    def raw_execute(sql, *args, **kwargs)
+      ctx = Thread.current[:resilient_reads_context]
+      name = args.first
+
+      if ctx &&
+         ctx[:distributing] &&
+         !ctx[:on_replica] &&
+         !ctx[:routing] &&
+         !skip_replica_routing?(sql, name) &&
+         open_transactions.zero?
+
+        execute_on_replica(sql, ctx, *args, **kwargs)
+      else
+        if ctx && ctx[:distributing] && write_query?(sql)
+          ResilientReads.log_query("primary", sql, name, reason: "write query")
+        end
+        super(sql, *args, **kwargs)
+      end
+    end
+
+    private
+
+    # Schema queries, internal queries, and queries without a name
+    # (connection setup, etc.) should always hit the primary.
+    def skip_replica_routing?(sql, name)
+      return true if name.nil? || name == ""
+      return true if SKIP_NAMES.include?(name)
+      return true if write_query?(sql)
+      false
+    end
+
+    def execute_on_replica(sql, ctx, *args, **kwargs)
+      # Ensure the primary adapter is connected and its type_map is
+      # initialized.  After raw_execute returns the replica's PG::Result,
+      # the caller (cast_result) invokes get_oid_type on *self* (primary)
+      # to resolve column OIDs.  If all prior reads were routed to replicas,
+      # the primary connection was never materialized — leaving @type_map
+      # nil and causing: NoMethodError: undefined method `key?' for nil.
+      connect! unless type_map
+
+      replica = ResilientReads.replica_pool.next_healthy
+
+      unless replica
+        ResilientReads.log_query("primary", sql, args.first, reason: "no healthy replicas")
+        return execute_on_primary(sql, ctx, *args, **kwargs)
+      end
+
+      # Optional lag check — uses cached value to avoid querying on every request.
+      if ResilientReads.config.max_lag
+        lag = replica.cached_lag
+        if lag && lag > ResilientReads.config.max_lag
+          if ResilientReads.config.lag_failover
+            ResilientReads.log_query("primary", sql, args.first, reason: "replica '#{replica.name}' lag #{lag.round(1)}s > max #{ResilientReads.config.max_lag}s")
+            return execute_on_primary(sql, ctx, *args, **kwargs)
+          else
+            raise TooMuchLag, "Replication lag is #{lag.round(1)}s (max #{ResilientReads.config.max_lag}s)"
+          end
+        end
+      end
+
+      # Re-entrancy guard: prevent recursive routing when the replica
+      # connection is being established (its init queries should not
+      # be routed again).
+      ctx[:on_replica] = true
+      ctx[:routing] = true
+      begin
+        ResilientReads.log_query(replica.name, sql, args.first)
+        result = replica.connection.raw_execute(sql, *args, **kwargs)
+        ctx[:routing] = false
+        result
+      rescue ActiveRecord::ConnectionNotEstablished,
+             ActiveRecord::StatementInvalid,
+             ActiveRecord::ConnectionFailed => e
+        ctx[:routing] = false
+        raise unless connection_level_error?(e)
+
+        ResilientReads.replica_pool.mark_unhealthy(replica)
+        ResilientReads.log(:warn, "Replica '#{replica.name}' failed (#{e.class}), trying next")
+
+        # One retry on a different replica
+        retry_replica = ResilientReads.replica_pool.next_healthy
+        if retry_replica
+          begin
+            ctx[:routing] = true
+            ResilientReads.log_query(retry_replica.name, sql, args.first, reason: "retry after '#{replica.name}' failed")
+            result = retry_replica.connection.raw_execute(sql, *args, **kwargs)
+            ctx[:routing] = false
+            return result
+          rescue => retry_err
+            ctx[:routing] = false
+            ResilientReads.replica_pool.mark_unhealthy(retry_replica)
+            ResilientReads.log(:warn, "Retry replica '#{retry_replica.name}' also failed: #{retry_err.message}")
+          end
+        end
+
+        if ResilientReads.config.failover
+          ResilientReads.log_query("primary", sql, args.first, reason: "all replicas exhausted")
+          execute_on_primary(sql, ctx, *args, **kwargs)
+        else
+          raise NoHealthyReplica, "No healthy replicas available and failover is disabled"
+        end
+      ensure
+        ctx[:on_replica] = false
+        ctx[:routing] = false
+        replica&.release_connection rescue nil
+      end
+    end
+
+    def execute_on_primary(sql, ctx, *args, **kwargs)
+      ctx[:distributing] = false
+      raw_execute(sql, *args, **kwargs)
+    ensure
+      ctx[:distributing] = true
+    end
+
+    def connection_level_error?(error)
+      case error
+      when ActiveRecord::ConnectionNotEstablished, ActiveRecord::ConnectionFailed
+        true
+      when ActiveRecord::StatementInvalid
+        cause = error.cause
+        cause.is_a?(PG::Error) ||
+          cause.is_a?(IOError) ||
+          (defined?(PG::ConnectionBad) && cause.is_a?(PG::ConnectionBad)) ||
+          (defined?(Trilogy::Error) && cause.is_a?(Trilogy::Error)) ||
+          (defined?(Mysql2::Error) && cause.is_a?(Mysql2::Error))
+      else
+        false
+      end
+    end
+  end
+end

data/lib/resilient_reads/configuration.rb

@@ -0,0 +1,90 @@
+module ResilientReads
+  class Configuration
+    # When true, all reads are distributed to replicas by default (via middleware).
+    attr_accessor :by_default
+
+    # When true, ActiveRecord::Relation returned from distribute_reads blocks
+    # are automatically loaded to ensure execution on the replica.
+    attr_accessor :eager_load
+
+    # Load balancing strategy: :round_robin or :random
+    attr_accessor :balancing_strategy
+
+    # Seconds between background health checks on replicas.
+    attr_accessor :health_check_interval
+
+    # Maximum acceptable replication lag in seconds. nil = no check.
+    attr_accessor :max_lag
+
+    # Seconds to cache the lag check result per replica. Prevents querying
+    # the replica for lag on every single read. Default: 5.
+    attr_accessor :lag_check_interval
+
+    # When true and max_lag is set, queries fall back to primary instead of raising.
+    attr_accessor :lag_failover
+
+    # When true, queries fall back to primary if no healthy replicas are available.
+    # When false, raises ResilientReads::NoHealthyReplica.
+    attr_accessor :failover
+
+    # Logger instance. Defaults to Rails.logger when available.
+    attr_accessor :logger
+
+    # When true, logs which connection (primary / replica name) handled each
+    # query routed through the adapter patch.
+    # Set to false to silence per-query routing logs.
+    attr_accessor :log_query_routing
+
+    # Log level for per-query routing messages. Defaults to :info so messages
+    # appear in standard Rails development/production logs.
+    # Set to :debug if the output is too noisy.
+    attr_accessor :log_query_level
+
+    # Explicit list of replica database config names (symbols).
+    # Example: [:replica, :replica2, :replica3]
+    # When nil, replicas are auto-detected from database.yml.
+    attr_accessor :replicas
+
+    # When true and replicas is nil, auto-detect replica configs from database.yml.
+    attr_accessor :auto_detect_replicas
+
+    # Regex pattern for auto-detecting replica config names.
+    # Only configs matching this pattern AND having replica: true are used.
+    attr_accessor :replica_pattern
+
+    # Seconds to keep using primary after a write (read-your-own-write protection).
+    attr_accessor :primary_delay
+
+    # Hash of default options for distribute_reads blocks.
+    attr_accessor :default_options
+
+    # When true, caches SQL pattern-matching results (write_query? /
+    # skip_replica_routing?) in an in-memory LRU cache so the regex
+    # doesn't run on every identical query string.
+    attr_accessor :query_cache_enabled
+
+    # Maximum number of entries in the SQL pattern cache.
+    attr_accessor :query_cache_max_size
+
+    def initialize
+      @by_default = false
+      @eager_load = false
+      @balancing_strategy = :round_robin
+      @health_check_interval = 30
+      @max_lag = nil
+      @lag_check_interval = 5
+      @lag_failover = false
+      @failover = true
+      @logger = nil
+      @log_query_routing = true
+      @log_query_level = :info
+      @replicas = nil
+      @auto_detect_replicas = true
+      @replica_pattern = /\Areplica\d*\z/
+      @primary_delay = 2
+      @default_options = {}
+      @query_cache_enabled = true
+      @query_cache_max_size = 10_000
+    end
+  end
+end

data/lib/resilient_reads/health_checker.rb

@@ -0,0 +1,57 @@
+module ResilientReads
+  # Background thread that periodically verifies replica reachability.
+  # Unhealthy replicas are re-checked so they can be restored to the pool
+  # once they recover.
+  class HealthChecker
+    def initialize(replica_pool, interval:)
+      @replica_pool = replica_pool
+      @interval = interval
+      @thread = nil
+      @running = false
+    end
+
+    def start
+      return if @replica_pool.empty?
+
+      # Prevent duplicate threads — stop any existing thread first.
+      stop if @running || @thread&.alive?
+
+      @running = true
+      @thread = Thread.new { run_loop }
+      @thread.name = "resilient_reads_health"
+      @thread.abort_on_exception = false
+      @thread.report_on_exception = false
+    end
+
+    def stop
+      @running = false
+      @thread&.wakeup rescue nil
+      @thread&.join(5) rescue nil
+      @thread = nil
+    end
+
+    def running?
+      @running && @thread&.alive?
+    end
+
+    private
+
+    def run_loop
+      while @running
+        sleep @interval
+        check_all
+      end
+    rescue => e
+      ResilientReads.log(:error, "Health checker crashed: #{e.message}")
+      retry if @running
+    end
+
+    def check_all
+      @replica_pool.each do |replica|
+        replica.check_health!
+      end
+    rescue => e
+      ResilientReads.log(:error, "Health check cycle error: #{e.message}")
+    end
+  end
+end

data/lib/resilient_reads/lag_checker.rb

@@ -0,0 +1,73 @@
+module ResilientReads
+  module LagChecker
+    # Returns the replication lag in seconds for a replica.
+    # Supports PostgreSQL and MySQL/MariaDB.
+    # Returns 0 when the replica is fully caught up, nil on error.
+    def self.lag_for(replica)
+      conn = replica.connection
+      adapter_name = conn.adapter_name.downcase
+
+      if adapter_name.include?("postgresql")
+        lag_for_postgresql(conn)
+      elsif adapter_name.include?("mysql") || adapter_name.include?("trilogy")
+        lag_for_mysql(conn)
+      else
+        ResilientReads.log(:debug, "Lag check not supported for adapter '#{adapter_name}'")
+        nil
+      end
+    rescue => e
+      ResilientReads.log(:debug, "Lag check failed for '#{replica.name}': #{e.message}")
+      nil
+    ensure
+      replica.release_connection rescue nil
+    end
+
+    # Convenience: check replication lag using the default reading connection.
+    def self.replication_lag
+      replica = ResilientReads.replica_pool.next_healthy
+      return nil unless replica
+
+      lag_for(replica)
+    end
+
+    private
+
+    def self.lag_for_postgresql(conn)
+      result = conn.execute(<<~SQL)
+        SELECT CASE
+          WHEN pg_last_wal_receive_lsn() IS NULL THEN NULL
+          WHEN pg_last_wal_receive_lsn() = pg_last_wal_replay_lsn() THEN 0
+          ELSE EXTRACT(EPOCH FROM now() - pg_last_xact_replay_timestamp())::float
+        END AS lag
+      SQL
+      lag = result.first&.fetch("lag", nil)
+      lag&.to_f
+    end
+
+    def self.lag_for_mysql(conn)
+      result = conn.execute("SHOW SLAVE STATUS")
+      # MySQL 8.0.22+ uses SHOW REPLICA STATUS
+      result = conn.execute("SHOW REPLICA STATUS") if result.respond_to?(:count) && result.count == 0
+
+      row = if result.respond_to?(:first)
+              result.first
+      elsif result.respond_to?(:to_a)
+              result.to_a.first
+      end
+
+      return nil unless row
+
+      # Seconds_Behind_Master / Seconds_Behind_Source (MySQL 8.0.22+)
+      lag = if row.is_a?(Hash)
+              row["Seconds_Behind_Master"] || row["Seconds_Behind_Source"]
+      elsif row.respond_to?(:[])
+              row["Seconds_Behind_Master"] || row["Seconds_Behind_Source"]
+      end
+
+      lag&.to_f
+    rescue => e
+      ResilientReads.log(:debug, "MySQL lag check failed: #{e.message}")
+      nil
+    end
+  end
+end

data/lib/resilient_reads/middleware.rb

@@ -0,0 +1,59 @@
+module ResilientReads
+  # Rack middleware that automatically wraps GET/HEAD requests in a
+  # distribute_reads context.  Respects the "read your own write"
+  # delay: after a mutating request, subsequent reads stay on primary
+  # for +primary_delay+ seconds.
+  class Middleware
+    WRITE_METHODS = %w[POST PUT PATCH DELETE].freeze
+    COOKIE_NAME   = "_resilient_reads_last_write".freeze
+
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      return @app.call(env) unless ResilientReads.config.by_default
+      return @app.call(env) if ResilientReads.replica_pool.empty?
+
+      request = Rack::Request.new(env)
+
+      if write_request?(request)
+        status, headers, body = @app.call(env)
+        set_last_write_cookie(headers)
+        [ status, headers, body ]
+      elsif recent_write?(request)
+        # Within the primary_delay window — skip replica routing.
+        @app.call(env)
+      else
+        ResilientReads.run { @app.call(env) }
+      end
+    end
+
+    private
+
+    def write_request?(request)
+      WRITE_METHODS.include?(request.request_method)
+    end
+
+    def recent_write?(request)
+      cookie = request.cookies[COOKIE_NAME]
+      return false unless cookie
+
+      last_write = cookie.to_f
+      (Time.now.to_f - last_write) < ResilientReads.config.primary_delay
+    rescue
+      false
+    end
+
+    def set_last_write_cookie(headers)
+      Rack::Utils.set_cookie_header!(
+        headers,
+        COOKIE_NAME,
+        value: Time.now.to_f.to_s,
+        path: "/",
+        httponly: true,
+        same_site: :lax
+      )
+    end
+  end
+end

data/lib/resilient_reads/query_cache.rb

@@ -0,0 +1,85 @@
+require "digest"
+
+module ResilientReads
+  # Caches SQL pattern-matching results (read vs write classification) so
+  # the regex does not need to run on every identical query string.
+  #
+  # Mirrors the caching concept from active_record_proxy_adapters but is
+  # simpler — we only cache the boolean result of +write_query?+ and
+  # +skip_replica_routing?+ keyed by the SQL string.
+  #
+  # Thread-safe via a Mutex around the internal Hash. Uses an LRU eviction
+  # strategy when the cache exceeds +max_size+.
+  class QueryCache
+    DEFAULT_MAX_SIZE = 10_000
+
+    attr_reader :max_size, :key_prefix
+
+    def initialize(max_size: DEFAULT_MAX_SIZE, key_prefix: "rr_")
+      @max_size = max_size
+      @key_prefix = key_prefix
+      @store = {}
+      @mutex = Mutex.new
+      @hits = 0
+      @misses = 0
+    end
+
+    # Fetch a cached value or compute it from the block.
+    # The block receives the SQL and should return the value to cache.
+    #
+    #   cache.fetch(sql) { |s| ResilientReads.write_query?(s) }
+    #
+    def fetch(sql)
+      key = cache_key(sql)
+
+      @mutex.synchronize do
+        if @store.key?(key)
+          @hits += 1
+          # Move to end (most recently used)
+          value = @store.delete(key)
+          @store[key] = value
+          return value
+        end
+      end
+
+      value = yield(sql)
+
+      @mutex.synchronize do
+        @misses += 1
+        @store[key] = value
+        evict! if @store.size > @max_size
+      end
+
+      value
+    end
+
+    def size
+      @mutex.synchronize { @store.size }
+    end
+
+    def stats
+      @mutex.synchronize { { hits: @hits, misses: @misses, size: @store.size } }
+    end
+
+    def clear!
+      @mutex.synchronize do
+        @store.clear
+        @hits = 0
+        @misses = 0
+      end
+    end
+
+    private
+
+    def cache_key(sql)
+      "#{@key_prefix}#{Digest::SHA2.hexdigest(sql)}"
+    end
+
+    # Evict the oldest 25% of entries when over capacity.
+    def evict!
+      evict_count = @store.size / 4
+      evict_count = 1 if evict_count < 1
+      evict_count.times { @store.shift }
+    end
+  end
+end

data/lib/resilient_reads/railtie.rb

@@ -0,0 +1,42 @@
+module ResilientReads
+  class Railtie < Rails::Railtie
+    initializer "resilient_reads.configure_logger" do
+      ResilientReads.config.logger ||= Rails.logger
+    end
+
+    # Set up replica pools and patch the adapter after AR is ready.
+    initializer "resilient_reads.setup", after: "active_record.initialize_database" do
+      ActiveSupport.on_load(:active_record) do
+        ResilientReads.setup_replicas!
+        ResilientReads.patch_adapter!
+        ResilientReads.start_health_checker!
+      end
+    end
+
+    # Insert middleware for by_default mode.
+    initializer "resilient_reads.middleware" do |app|
+      app.middleware.insert_before 0, ResilientReads::Middleware
+    end
+
+    # Restart health checker after Puma/Unicorn forks.
+    config.after_initialize do
+      if defined?(::Puma) || defined?(::Unicorn)
+        ActiveSupport.on_load(:active_record) do
+          if ActiveRecord::Base.respond_to?(:connection_pool)
+            at_exit { ResilientReads.stop_health_checker! }
+          end
+        end
+      end
+
+      if defined?(::Puma)
+        Puma::Plugin.create do
+          def start(launcher)
+            launcher.events.on_booted do
+              ResilientReads.restart_health_checker!
+            end
+          end
+        end rescue nil
+      end
+    end
+  end
+end

data/lib/resilient_reads/replica.rb

@@ -0,0 +1,100 @@
+module ResilientReads
+  class Replica
+    attr_reader :name, :connection_class
+
+    def initialize(name, connection_class)
+      @name = name.to_s
+      @connection_class = connection_class
+      @healthy = true
+      @failure_count = 0
+      @last_check_at = nil
+      @last_lag = nil
+      @last_lag_check_at = nil
+      @mutex = Mutex.new
+    end
+
+    def healthy?
+      @mutex.synchronize { @healthy }
+    end
+
+    def mark_healthy!
+      @mutex.synchronize do
+        was_unhealthy = !@healthy
+        @healthy = true
+        @failure_count = 0
+        @last_check_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        ResilientReads.log(:info, "Replica '#{@name}' recovered") if was_unhealthy
+      end
+    end
+
+    def mark_unhealthy!
+      @mutex.synchronize do
+        was_healthy = @healthy
+        @healthy = false
+        @failure_count += 1
+        @last_check_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        ResilientReads.log(:warn, "Replica '#{@name}' marked unhealthy (failure ##{@failure_count})") if was_healthy
+      end
+    end
+
+    def failure_count
+      @mutex.synchronize { @failure_count }
+    end
+
+    # Returns the cached lag value if still fresh, otherwise queries the
+    # replica for the current replication lag.  The TTL is controlled by
+    # +ResilientReads.config.lag_check_interval+ (default 5 s).
+    def cached_lag
+      now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      ttl = ResilientReads.config.lag_check_interval
+
+      @mutex.synchronize do
+        if @last_lag_check_at && (now - @last_lag_check_at) < ttl
+          return @last_lag
+        end
+      end
+
+      lag = LagChecker.lag_for(self)
+
+      @mutex.synchronize do
+        @last_lag = lag
+        @last_lag_check_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      lag
+    end
+
+    # Invalidate the cached lag so the next call to +cached_lag+ re-queries.
+    def invalidate_lag_cache!
+      @mutex.synchronize do
+        @last_lag_check_at = nil
+        @last_lag = nil
+      end
+    end
+
+    def connection
+      @connection_class.connection
+    end
+
+    def connection_pool
+      @connection_class.connection_pool
+    end
+
+    def release_connection
+      @connection_class.connection_pool.release_connection
+    end
+
+    # Verify the replica is reachable. Returns true/false and updates health.
+    def check_health!
+      @connection_class.connection.execute("SELECT 1")
+      mark_healthy!
+      true
+    rescue => e
+      mark_unhealthy!
+      ResilientReads.log(:debug, "Health check failed for '#{@name}': #{e.message}")
+      false
+    ensure
+      release_connection rescue nil
+    end
+  end
+end

data/lib/resilient_reads/replica_pool.rb

@@ -0,0 +1,69 @@
+module ResilientReads
+  class ReplicaPool
+    attr_reader :replicas
+
+    def initialize
+      @replicas = []
+      @mutex = Mutex.new
+      @rr_index = 0
+    end
+
+    def add(replica)
+      @mutex.synchronize { @replicas << replica }
+    end
+
+    def size
+      @replicas.size
+    end
+
+    def empty?
+      @replicas.empty?
+    end
+
+    # Select the next healthy replica using the configured strategy.
+    # Returns nil when no healthy replica is available.
+    def next_healthy
+      @mutex.synchronize do
+        healthy = @replicas.select(&:healthy?)
+        return nil if healthy.empty?
+
+        case ResilientReads.config.balancing_strategy
+        when :round_robin
+          idx = @rr_index % healthy.size
+          @rr_index += 1
+          healthy[idx]
+        when :random
+          healthy.sample
+        else
+          healthy.first
+        end
+      end
+    end
+
+    def any_healthy?
+      @replicas.any?(&:healthy?)
+    end
+
+    def healthy_count
+      @replicas.count(&:healthy?)
+    end
+
+    def mark_unhealthy(replica)
+      replica.mark_unhealthy!
+    end
+
+    def check_all_health!
+      @replicas.each(&:check_health!)
+    end
+
+    def release_all_connections
+      @replicas.each do |r|
+        r.release_connection rescue nil
+      end
+    end
+
+    def each(&block)
+      @replicas.each(&block)
+    end
+  end
+end

data/lib/resilient_reads/version.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module ResilientReads
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/lib/resilient_reads.rb

@@ -1,8 +1,321 @@
-# frozen_string_literal: true
+require "active_support"
+require "active_record"
 
 require_relative "resilient_reads/version"
+require_relative "resilient_reads/configuration"
+require_relative "resilient_reads/replica"
+require_relative "resilient_reads/replica_pool"
+require_relative "resilient_reads/health_checker"
+require_relative "resilient_reads/lag_checker"
+require_relative "resilient_reads/query_cache"
+require_relative "resilient_reads/adapter_patch"
+require_relative "resilient_reads/middleware"
+require_relative "resilient_reads/active_job_extension"
 
 module ResilientReads
-  class Error < StandardError; end
-  # Your code goes here...
+  class TooMuchLag < StandardError; end
+  class NoHealthyReplica < StandardError; end
+
+  # SQL patterns that indicate a write operation (PostgreSQL + MySQL/MariaDB).
+  WRITE_PATTERN = /\A\s*(INSERT|UPDATE|DELETE|CREATE|ALTER|DROP|TRUNCATE|GRANT|REVOKE|LOCK\s+TABLE|SET\s|BEGIN|COMMIT|ROLLBACK|SAVEPOINT|RELEASE|COPY\s|REPLACE\s|LOAD\s+DATA|CALL\s)/i
+
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+    end
+
+    def replica_pool
+      @replica_pool ||= ReplicaPool.new
+    end
+
+    def health_checker
+      @health_checker
+    end
+
+    # -------------------------------------------------------------------
+    # Core entry point — wraps a block so read queries go to a replica.
+    # -------------------------------------------------------------------
+    def run(**options, &block)
+      opts = config.default_options.merge(options)
+
+      # Explicit primary override
+      if opts[:primary]
+        return block.call
+      end
+
+      # No replicas configured — just run on primary.
+      if replica_pool.empty? || !replica_pool.any_healthy?
+        if opts.fetch(:failover, config.failover)
+          return block.call
+        else
+          raise NoHealthyReplica, "No healthy replicas available"
+        end
+      end
+
+      prev_ctx = Thread.current[:resilient_reads_context]
+      Thread.current[:resilient_reads_context] = {
+        distributing: true,
+        on_replica: false,
+        routing: false,
+        options: opts
+      }
+
+      begin
+        result = block.call
+        if config.eager_load && result.is_a?(ActiveRecord::Relation) && !result.loaded?
+          result = result.load
+        end
+        result
+      ensure
+        Thread.current[:resilient_reads_context] = prev_ctx
+        replica_pool.release_all_connections
+      end
+    end
+
+    # Are we currently inside a distribute_reads block?
+    def distributing?
+      ctx = Thread.current[:resilient_reads_context]
+      ctx && ctx[:distributing]
+    end
+
+    # Convenience: get current replication lag (seconds).
+    def replication_lag
+      LagChecker.replication_lag
+    end
+
+    def query_cache
+      @query_cache ||= QueryCache.new(
+        max_size: config.query_cache_max_size
+      )
+    end
+
+    def write_query?(sql)
+      if config.query_cache_enabled
+        query_cache.fetch(sql) { |s| WRITE_PATTERN.match?(s) }
+      else
+        WRITE_PATTERN.match?(sql)
+      end
+    end
+
+    # Clear cached SQL pattern results.
+    def bust_query_cache!
+      @query_cache&.clear!
+    end
+
+    def log(level, message)
+      logger = config.logger
+      return unless logger
+
+      logger.public_send(level, "[ResilientReads] #{message}")
+    rescue
+      # Never let logging break query flow.
+    end
+
+    # Per-query routing log.  Only emits when config.log_query_routing is true.
+    # Uses config.log_query_level (default :info) so messages are visible in
+    # standard Rails development/production logs.
+    #
+    # Output example:
+    #   [ResilientReads] → replica 'replica1' | User Load | SELECT "users".* …
+    #   [ResilientReads] → primary (write query) | User Create | INSERT INTO …
+    def log_query(connection_name, sql, query_name = nil, reason: nil)
+      return unless config.log_query_routing
+
+      logger = config.logger
+      return unless logger
+
+      label = if connection_name == "primary"
+                reason ? "primary (#{reason})" : "primary"
+      else
+                reason ? "replica '#{connection_name}' (#{reason})" : "replica '#{connection_name}'"
+      end
+
+      truncated_sql = sql.length > 120 ? "#{sql[0, 120]}…" : sql
+      parts = [ "[ResilientReads] → #{label}" ]
+      parts << query_name if query_name && !query_name.empty?
+      parts << truncated_sql.gsub(/\s+/, " ").strip
+      logger.public_send(config.log_query_level, parts.join(" | "))
+    rescue
+      # Never let logging break query flow.
+    end
+
+    # ---------------------------------------------------------------
+    # Setup helpers (called from Railtie or manually in non-Rails apps)
+    # ---------------------------------------------------------------
+
+    def setup_replicas!
+      names = replica_config_names
+
+      if names.empty?
+        log(:info, "No replica configs detected (pattern: #{config.replica_pattern.inspect}). All reads will use primary.")
+        return
+      end
+
+      names.each do |name|
+        klass = build_replica_class(name)
+        replica = Replica.new(name, klass)
+        replica_pool.add(replica)
+      end
+
+      # Initial health probe — failures are non-fatal.
+      replica_pool.each do |r|
+        r.check_health!
+      rescue => e
+        log(:warn, "Initial health check for '#{r.name}' failed: #{e.message}")
+      end
+
+      log(:info, "Configured #{replica_pool.size} replica(s): #{names.join(', ')} " \
+                 "(#{replica_pool.healthy_count} healthy)")
+    end
+
+    def patch_adapter!
+      patched = []
+      if defined?(ActiveRecord::ConnectionAdapters::PostgreSQLAdapter)
+        ActiveRecord::ConnectionAdapters::PostgreSQLAdapter.prepend(AdapterPatch)
+        patched << "PostgreSQLAdapter"
+      end
+      if defined?(ActiveRecord::ConnectionAdapters::Mysql2Adapter)
+        ActiveRecord::ConnectionAdapters::Mysql2Adapter.prepend(AdapterPatch)
+        patched << "Mysql2Adapter"
+      end
+      if defined?(ActiveRecord::ConnectionAdapters::TrilogyAdapter)
+        ActiveRecord::ConnectionAdapters::TrilogyAdapter.prepend(AdapterPatch)
+        patched << "TrilogyAdapter"
+      end
+
+      log(:debug, "Patched adapters: #{patched.join(', ')}") if patched.any?
+    end
+
+    def start_health_checker!
+      return if replica_pool.empty?
+
+      @health_checker = HealthChecker.new(
+        replica_pool,
+        interval: config.health_check_interval
+      )
+      @health_checker.start
+    end
+
+    def stop_health_checker!
+      @health_checker&.stop
+    end
+
+    def restart_health_checker!
+      stop_health_checker!
+      start_health_checker!
+    end
+
+    private
+
+    def replica_config_names
+      if config.replicas
+        Array(config.replicas).map(&:to_sym)
+      elsif config.auto_detect_replicas
+        detect_replicas
+      else
+        []
+      end
+    end
+
+    def detect_replicas
+      env = defined?(Rails) ? Rails.env : ENV.fetch("RAILS_ENV", "development")
+      # include_hidden: true is required because Rails hides replica configs
+      # by default (they have database_tasks: false).
+      configs = ActiveRecord::Base.configurations.configs_for(env_name: env, include_hidden: true)
+      detected = configs.select { |c| c.replica? && c.name.to_s.match?(config.replica_pattern) }
+                        .map { |c| c.name.to_sym }
+      log(:debug, "detect_replicas: found #{configs.size} configs, #{detected.size} matched replica pattern")
+      detected
+    end
+
+    # Creates an abstract AR class with its own connection pool pointing
+    # at the given replica database config.  This avoids touching the
+    # main ApplicationRecord pool.
+    def build_replica_class(name)
+      klass = Class.new(ActiveRecord::Base) do
+        self.abstract_class = true
+      end
+      class_name = "ReplicaConnection#{name.to_s.camelize}"
+      const_set(class_name, klass) unless const_defined?(class_name)
+
+      begin
+        klass.establish_connection(name)
+      rescue => e
+        log(:warn, "Could not establish connection for replica '#{name}': #{e.message}")
+      end
+
+      klass
+    end
+  end
+end
+
+# -----------------------------------------------------------------------
+# Global helper — available everywhere just like the original gem.
+# -----------------------------------------------------------------------
+module ResilientReadsGlobal
+  def distribute_reads(**options, &block)
+    ResilientReads.run(**options, &block)
+  end
+
+  def resilient_reads(**options, &block)
+    ResilientReads.run(**options, &block)
+  end
+end
+
+Object.include ResilientReadsGlobal
+
+# Backward-compatible constant so existing initializers using
+# DistributeReads.eager_load = true etc. still work.
+module DistributeReads
+  class TooMuchLag < ResilientReads::TooMuchLag; end
+
+  class << self
+    def eager_load=(val)
+      ResilientReads.config.eager_load = val
+    end
+
+    def eager_load
+      ResilientReads.config.eager_load
+    end
+
+    def by_default=(val)
+      ResilientReads.config.by_default = val
+    end
+
+    def by_default
+      ResilientReads.config.by_default
+    end
+
+    def default_options=(val)
+      ResilientReads.config.default_options = val
+    end
+
+    def default_options
+      ResilientReads.config.default_options
+    end
+
+    def logger=(val)
+      ResilientReads.config.logger = val
+    end
+
+    def logger
+      ResilientReads.config.logger
+    end
+
+    def replication_lag
+      ResilientReads.replication_lag
+    end
+  end
 end
+
+# ActiveJob integration
+ActiveSupport.on_load(:active_job) do
+  include ResilientReads::ActiveJobExtension
+end
+
+# Railtie auto-loads when Rails is present.
+require_relative "resilient_reads/railtie" if defined?(Rails::Railtie)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: resilient_reads
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Jamie Puckett
@@ -17,11 +17,25 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".idea/.gitignore"
+- ".idea/modules.xml"
+- ".idea/resilient_reads.iml"
+- ".idea/vcs.xml"
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
 - Rakefile
 - lib/resilient_reads.rb
+- lib/resilient_reads/active_job_extension.rb
+- lib/resilient_reads/adapter_patch.rb
+- lib/resilient_reads/configuration.rb
+- lib/resilient_reads/health_checker.rb
+- lib/resilient_reads/lag_checker.rb
+- lib/resilient_reads/middleware.rb
+- lib/resilient_reads/query_cache.rb
+- lib/resilient_reads/railtie.rb
+- lib/resilient_reads/replica.rb
+- lib/resilient_reads/replica_pool.rb
 - lib/resilient_reads/version.rb
 - sig/resilient_reads.rbs
 homepage: https://github.com/chronicaust/resilient_reads