forest_admin_datasource_rpc 1.18.2 → 1.18.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 408060dae4c5ff5ea54d063e1c0d9e00c61299806f232b0c70b3e8ee533acb7f
-  data.tar.gz: c3dac277d3c2e37574d2ef067f26e2df5807c70496f8253d837ee9081fbd3b89
+  metadata.gz: cdab147ee5d5c1c698dcd25bccc78e68a2ad409c434ebad08b8cea0cfe93823d
+  data.tar.gz: cddbc35424d5d8da9b8f09387179f6cdc86178a7eabb23186ddd344ae09b7702
 SHA512:
-  metadata.gz: 39d5502d29295524ca2fa6809b79e36b8d9854d299d5382d1108eece9489a45c3679d50b3e0feaa41127939727f9fcdf3155ae69809a67517e03e8e60b550c28
-  data.tar.gz: f47c91585c2418645336a4fa89d7b22ec4f91e8600c81c882a5aa09c7340a7c4c30ac81fcfcd5e22e09ec2379be24d634e064064973cd28141bee74ee99278f1
+  metadata.gz: bad1d8cd543c58a22fe51b9cde4c681e44ab63872c51d24cacbd3229d0132185e7c9072f6dadfa7427a234dbd41174bf78ccbf4c8ef70bf0bf2644b0c2ff4021
+  data.tar.gz: b5f0c559d3f87aa73d3de3ff02058f0c9fe5383e5d0ad4c11296a7756a6577151193ca6e195900836e4b03ed8cb662d829f995860fbc60de21c4d607cb8872c2

data/lib/forest_admin_datasource_rpc/Utils/rpc_client.rb

@@ -32,6 +32,8 @@ module ForestAdminDatasourceRpc
 
       HTTP_NOT_MODIFIED = 304
       NotModified = Class.new
+      DEFAULT_TIMEOUT = 30 # seconds
+      DEFAULT_OPEN_TIMEOUT = 10 # seconds
 
       def initialize(api_url, auth_secret)
         @api_url = api_url
@@ -63,6 +65,8 @@ module ForestAdminDatasourceRpc
           faraday.response :json, parser_options: { symbolize_names: symbolize_keys }
           faraday.adapter Faraday.default_adapter
           faraday.ssl.verify = !ForestAdminAgent::Facades::Container.cache(:debug)
+          faraday.options.timeout = DEFAULT_TIMEOUT
+          faraday.options.open_timeout = DEFAULT_OPEN_TIMEOUT
         end
 
         timestamp = Time.now.utc.iso8601(3)

data/lib/forest_admin_datasource_rpc/Utils/schema_polling_client.rb

@@ -1,54 +1,50 @@
 require 'openssl'
 require 'json'
 require 'time'
+require 'digest'
 
 module ForestAdminDatasourceRpc
   module Utils
     class SchemaPollingClient
-      attr_reader :closed
+      attr_reader :closed, :current_schema, :client_id
 
-      DEFAULT_POLLING_INTERVAL = 600 # seconds (10 minutes)
-      MIN_POLLING_INTERVAL = 1 # seconds (minimum safe interval)
-      MAX_POLLING_INTERVAL = 3600 # seconds (1 hour max)
+      DEFAULT_POLLING_INTERVAL = 600
+      MIN_POLLING_INTERVAL = 1
+      MAX_POLLING_INTERVAL = 3600
 
-      def initialize(uri, auth_secret, options = {}, &on_schema_change)
+      def initialize(uri, auth_secret, polling_interval: DEFAULT_POLLING_INTERVAL, introspection_schema: nil,
+                     &on_schema_change)
         @uri = uri
         @auth_secret = auth_secret
-        @polling_interval = options[:polling_interval] || DEFAULT_POLLING_INTERVAL
+        @polling_interval = polling_interval
         @on_schema_change = on_schema_change
         @closed = false
+        @introspection_schema = introspection_schema
+        @current_schema = nil
         @cached_etag = nil
-        @polling_thread = nil
-        @mutex = Mutex.new
         @connection_attempts = 0
+        @initial_sync_completed = false
+        @client_id = uri
 
-        # Validate polling interval
         validate_polling_interval!
 
-        # RPC client for schema fetching with ETag support
         @rpc_client = RpcClient.new(@uri, @auth_secret)
       end
 
-      def start
-        return if @closed
+      def start?
+        return false if @closed
 
-        @mutex.synchronize do
-          return if @polling_thread&.alive?
-
-          @polling_thread = Thread.new do
-            polling_loop
-          rescue StandardError => e
-            ForestAdminAgent::Facades::Container.logger&.log(
-              'Error',
-              "[Schema Polling] Unexpected error in polling loop: #{e.class} - #{e.message}"
-            )
-          end
-        end
+        ForestAdminAgent::Facades::Container.logger&.log('Info', "Getting schema from RPC agent on #{@uri}.")
+        fetch_initial_schema_sync
+
+        # Register with the shared pool
+        SchemaPollingPool.instance.register?(@client_id, self)
 
         ForestAdminAgent::Facades::Container.logger&.log(
           'Info',
-          "[Schema Polling] Polling started (interval: #{@polling_interval}s)"
+          "[Schema Polling] Registered with pool (interval: #{@polling_interval}s, client: #{@client_id})"
         )
+        true
       end
 
       def stop
@@ -57,46 +53,11 @@ module ForestAdminDatasourceRpc
         @closed = true
         ForestAdminAgent::Facades::Container.logger&.log('Debug', '[Schema Polling] Stopping polling')
 
-        @mutex.synchronize do
-          if @polling_thread&.alive?
-            @polling_thread.kill
-            @polling_thread = nil
-          end
-        end
+        SchemaPollingPool.instance.unregister?(@client_id)
 
         ForestAdminAgent::Facades::Container.logger&.log('Debug', '[Schema Polling] Polling stopped')
       end
 
-      private
-
-      def polling_loop
-        ForestAdminAgent::Facades::Container.logger&.log(
-          'Debug',
-          "[Schema Polling] Starting polling loop (interval: #{@polling_interval}s)"
-        )
-
-        loop do
-          break if @closed
-
-          begin
-            check_schema
-          rescue StandardError => e
-            handle_error(e)
-          end
-
-          # Sleep with interrupt check (check every second for early termination)
-          ForestAdminAgent::Facades::Container.logger&.log(
-            'Debug',
-            "[Schema Polling] Waiting #{@polling_interval}s before next check (current ETag: #{@cached_etag || "none"})"
-          )
-          remaining = @polling_interval
-          while remaining.positive? && !@closed
-            sleep([remaining, 1].min)
-            remaining -= 1
-          end
-        end
-      end
-
       def check_schema
         @connection_attempts += 1
         log_checking_schema
@@ -111,11 +72,65 @@ module ForestAdminDatasourceRpc
         log_unexpected_error(e)
       end
 
-      def handle_error(error)
-        ForestAdminAgent::Facades::Container.logger&.log(
-          'Error',
-          "[Schema Polling] Error during schema check: #{error.class} - #{error.message}"
-        )
+      private
+
+      def compute_etag(schema)
+        return nil if schema.nil?
+
+        Digest::SHA1.hexdigest(schema.to_json)
+      end
+
+      def fetch_initial_schema_sync
+        # If we have an introspection schema, send its ETag to avoid re-downloading unchanged schema
+        introspection_etag = compute_etag(@introspection_schema) if @introspection_schema
+        result = @rpc_client.fetch_schema('/forest/rpc-schema', if_none_match: introspection_etag)
+
+        if result == RpcClient::NotModified
+          # Schema unchanged from introspection - use introspection
+          @current_schema = @introspection_schema
+          @cached_etag = introspection_etag
+          @initial_sync_completed = true
+          ForestAdminAgent::Facades::Container.logger&.log(
+            'Info',
+            "[Schema Polling] RPC schema unchanged (HTTP 304), using introspection (ETag: #{@cached_etag})"
+          )
+        else
+          # New schema from RPC
+          @current_schema = result.body
+          @cached_etag = result.etag || compute_etag(@current_schema)
+          @initial_sync_completed = true
+          ForestAdminAgent::Facades::Container.logger&.log(
+            'Debug',
+            "[Schema Polling] Initial schema fetched successfully (ETag: #{@cached_etag})"
+          )
+        end
+
+        @introspection_schema = nil
+      rescue Faraday::ConnectionFailed, Faraday::TimeoutError,
+             ForestAdminAgent::Http::Exceptions::AuthenticationOpenIdClient, StandardError => e
+        handle_initial_fetch_error(e)
+      end
+
+      def handle_initial_fetch_error(error)
+        if @introspection_schema
+          # Fallback to introspection schema - don't crash
+          @current_schema = @introspection_schema
+          @cached_etag = compute_etag(@current_schema)
+          @introspection_schema = nil
+          @initial_sync_completed = true
+          ForestAdminAgent::Facades::Container.logger&.log(
+            'Warn',
+            "RPC agent at #{@uri} is unreachable (#{error.class}: #{error.message}), " \
+            "using provided introspection schema (ETag: #{@cached_etag})"
+          )
+        else
+          # No introspection - re-raise to crash
+          ForestAdminAgent::Facades::Container.logger&.log(
+            'Error',
+            "Failed to get schema from RPC agent at #{@uri}: #{error.class} - #{error.message}"
+          )
+          raise error
+        end
       end
 
       def trigger_schema_change_callback(schema)
@@ -162,22 +177,27 @@ module ForestAdminDatasourceRpc
       end
 
       def handle_schema_changed(result)
-        new_etag = result.etag
-        @cached_etag.nil? ? handle_initial_schema(new_etag) : handle_schema_update(result.body, new_etag)
-        @connection_attempts = 0
-      end
+        new_schema = result.body
+        new_etag = result.etag || compute_etag(new_schema)
 
-      def handle_initial_schema(etag)
-        @cached_etag = etag
-        ForestAdminAgent::Facades::Container.logger&.log(
-          'Debug',
-          "[Schema Polling] Initial schema loaded successfully (ETag: #{etag})"
-        )
+        if @initial_sync_completed
+          handle_schema_update(new_schema, new_etag)
+        else
+          @cached_etag = new_etag
+          @current_schema = new_schema
+          @initial_sync_completed = true
+          ForestAdminAgent::Facades::Container.logger&.log(
+            'Info',
+            "[Schema Polling] Initial sync completed successfully (ETag: #{new_etag})"
+          )
+        end
+        @connection_attempts = 0
       end
 
       def handle_schema_update(schema, etag)
         old_etag = @cached_etag
         @cached_etag = etag
+        @current_schema = schema
         msg = "[Schema Polling] Schema changed detected (old ETag: #{old_etag}, new ETag: #{etag}), " \
               'triggering reload callback'
         ForestAdminAgent::Facades::Container.logger&.log('Info', msg)

data/lib/forest_admin_datasource_rpc/Utils/schema_polling_pool.rb

@@ -0,0 +1,286 @@
+require 'singleton'
+
+module ForestAdminDatasourceRpc
+  module Utils
+    # Thread pool manager for RPC schema polling.
+    # Uses a single scheduler thread that dispatches polling tasks to a bounded
+    # pool of worker threads, preventing thread exhaustion when many RPC slaves
+    # are configured.
+    #
+    # Design principles:
+    # - Minimal mutex hold times to avoid blocking HTTP request threads
+    # - Workers yield control frequently to prevent GIL starvation
+    # - Non-blocking queue operations where possible
+    class SchemaPollingPool
+      include Singleton
+
+      DEFAULT_MAX_THREADS = 5
+      MIN_THREADS = 1
+      MAX_THREADS = 50
+      SCHEDULER_INTERVAL = 1
+      INITIAL_STAGGER_WINDOW = 30
+
+      attr_reader :max_threads, :configured
+
+      def initialize
+        @mutex = Mutex.new
+        @clients = {}
+        @work_queue = Queue.new
+        @workers = []
+        @running = false
+        @max_threads = DEFAULT_MAX_THREADS
+        @shutdown_requested = false
+        @configured = false
+        @scheduler_thread = nil
+      end
+
+      # Configure the pool before starting. Must be called before any clients register.
+      # @param max_threads [Integer] Maximum number of worker threads (1-20)
+      def configure(max_threads:)
+        @mutex.synchronize do
+          raise 'Cannot configure pool while running' if @running
+
+          validated_max = max_threads.to_i.clamp(MIN_THREADS, MAX_THREADS)
+          @max_threads = validated_max
+          @configured = true
+
+          log('Info', "[SchemaPollingPool] Configured with max_threads: #{@max_threads}")
+        end
+      end
+
+      def register?(client_id, client)
+        should_start = false
+
+        @mutex.synchronize do
+          if @clients.key?(client_id)
+            log('Warn', "[SchemaPollingPool] Client #{client_id} already registered, skipping")
+            return false
+          end
+
+          @clients[client_id] = {
+            client: client,
+            last_poll_at: nil,
+            next_poll_at: calculate_initial_poll_time
+          }
+
+          log('Info', "[SchemaPollingPool] Registered client: #{client_id} (#{@clients.size} total clients)")
+
+          should_start = !@running
+        end
+
+        start_pool if should_start
+
+        true
+      end
+
+      def unregister?(client_id)
+        should_stop = false
+
+        @mutex.synchronize do
+          unless @clients.key?(client_id)
+            log('Debug', "[SchemaPollingPool] Client #{client_id} not found for unregister")
+            return false
+          end
+
+          @clients.delete(client_id)
+          log('Info', "[SchemaPollingPool] Unregistered client: #{client_id} (#{@clients.size} remaining)")
+
+          should_stop = @clients.empty? && @running
+        end
+
+        stop_pool if should_stop
+
+        true
+      end
+
+      def client_count
+        @mutex.synchronize { @clients.size }
+      end
+
+      def running?
+        @mutex.synchronize { @running }
+      end
+
+      def shutdown!
+        @mutex.synchronize do
+          return unless @running
+
+          @shutdown_requested = true
+        end
+
+        stop_pool
+
+        @mutex.synchronize do
+          @clients.clear
+          @shutdown_requested = false
+        end
+      end
+
+      def reset!
+        shutdown!
+        @mutex.synchronize do
+          @max_threads = DEFAULT_MAX_THREADS
+          @configured = false
+        end
+      end
+
+      private
+
+      def start_pool
+        @mutex.synchronize do
+          return if @running
+
+          @running = true
+          @shutdown_requested = false
+
+          thread_count = @clients.size.clamp(MIN_THREADS, @max_threads)
+
+          log('Info',
+              "[SchemaPollingPool] Starting pool with #{thread_count} worker threads for #{@clients.size} clients")
+
+          thread_count.times do |i|
+            @workers << Thread.new { worker_loop(i) }
+          end
+
+          @scheduler_thread = Thread.new { scheduler_loop }
+        end
+      end
+
+      def stop_pool
+        workers_to_join = nil
+        scheduler_to_join = nil
+
+        @mutex.synchronize do
+          return unless @running
+
+          log('Info', '[SchemaPollingPool] Stopping pool...')
+
+          @running = false
+
+          @workers.size.times { @work_queue << nil }
+
+          workers_to_join = @workers.dup
+          scheduler_to_join = @scheduler_thread
+
+          @workers.clear
+          @scheduler_thread = nil
+        end
+
+        workers_to_join&.each { |w| w.join(2) }
+        scheduler_to_join&.join(2)
+
+        @work_queue.clear
+
+        log('Info', '[SchemaPollingPool] Pool stopped')
+      end
+
+      def worker_loop(worker_id)
+        log('Debug', "[SchemaPollingPool] Worker #{worker_id} started")
+
+        loop do
+          task = fetch_next_task
+          break if task.nil?
+
+          process_task(task, worker_id)
+          Thread.pass
+        end
+
+        log('Debug', "[SchemaPollingPool] Worker #{worker_id} stopped")
+      end
+
+      def fetch_next_task
+        @work_queue.pop(true)
+      rescue ThreadError
+        Thread.pass
+        sleep(0.1)
+        retry if @running
+        nil
+      end
+
+      def process_task(task, worker_id)
+        client_id = task[:client_id]
+        execute_poll(client_id)
+      rescue StandardError => e
+        log('Error',
+            "[SchemaPollingPool] Worker #{worker_id} error polling #{client_id}: #{e.class} - #{e.message}")
+      end
+
+      def scheduler_loop
+        log('Debug', '[SchemaPollingPool] Scheduler started')
+
+        while @running
+          sleep_with_check(SCHEDULER_INTERVAL)
+
+          next unless @running
+
+          schedule_due_polls
+        end
+
+        log('Debug', '[SchemaPollingPool] Scheduler stopped')
+      end
+
+      def sleep_with_check(duration)
+        remaining = duration
+        while remaining.positive? && @running
+          sleep_time = [remaining, 1.0].min
+          sleep(sleep_time)
+          remaining -= sleep_time
+          Thread.pass
+        end
+      end
+
+      def schedule_due_polls
+        now = Time.now
+        polls_to_schedule = []
+
+        @mutex.synchronize do
+          @clients.each do |client_id, state|
+            next if state[:next_poll_at].nil?
+            next if now < state[:next_poll_at]
+
+            polls_to_schedule << client_id
+
+            interval = state[:client].instance_variable_get(:@polling_interval) || 600
+            state[:next_poll_at] = now + interval
+          end
+        end
+
+        polls_to_schedule.each do |client_id|
+          @work_queue << { client_id: client_id, scheduled_at: now }
+        end
+      end
+
+      def execute_poll(client_id)
+        client = nil
+        @mutex.synchronize do
+          state = @clients[client_id]
+          client = state[:client] if state
+        end
+
+        return unless client
+        return if client.closed
+
+        log('Debug', "[SchemaPollingPool] Polling client: #{client_id}")
+
+        client.check_schema
+
+        @mutex.synchronize do
+          @clients[client_id][:last_poll_at] = Time.now if @clients[client_id]
+        end
+      end
+
+      def calculate_initial_poll_time
+        # Stagger initial polls to avoid thundering herd
+        Time.now + rand(0.0..INITIAL_STAGGER_WINDOW.to_f)
+      end
+
+      def log(level, message)
+        return unless defined?(ForestAdminAgent::Facades::Container)
+
+        ForestAdminAgent::Facades::Container.logger&.log(level, message)
+      rescue StandardError
+        # Ignore logging errors to prevent cascading failures
+      end
+    end
+  end
+end

data/lib/forest_admin_datasource_rpc/datasource.rb

@@ -25,6 +25,9 @@ module ForestAdminDatasourceRpc
       @live_query_connections = native_query_connections.to_h { |conn| [conn[:name], conn[:name]] }
 
       @schema = { charts: @charts }
+
+      # Register shutdown hook to cleanup schema polling gracefully
+      register_shutdown_hook if @schema_polling_client
     end
 
     def render_chart(caller, name)
@@ -59,15 +62,38 @@ module ForestAdminDatasourceRpc
       @cleaned_up = true
 
       if @schema_polling_client
-        ForestAdminAgent::Facades::Container.logger&.log('Info', '[RPCDatasource] Stopping schema polling...')
+        log_info('[RPCDatasource] Stopping schema polling...')
         @schema_polling_client.stop
-        ForestAdminAgent::Facades::Container.logger&.log('Info', '[RPCDatasource] Schema polling stopped')
+        log_info('[RPCDatasource] Schema polling stopped')
       end
     rescue StandardError => e
-      ForestAdminAgent::Facades::Container.logger&.log(
-        'Error',
-        "[RPCDatasource] Error during cleanup: #{e.class} - #{e.message}"
-      )
+      log_error("[RPCDatasource] Error during cleanup: #{e.class} - #{e.message}")
+    end
+
+    private
+
+    def register_shutdown_hook
+      # Register at_exit hook for graceful shutdown
+      # This ensures schema polling is stopped when the application exits
+      at_exit do
+        cleanup
+      end
+    end
+
+    def log_info(message)
+      return unless defined?(ForestAdminAgent::Facades::Container)
+
+      ForestAdminAgent::Facades::Container.logger&.log('Info', message)
+    rescue StandardError
+      # Silently ignore logging errors during shutdown
+    end
+
+    def log_error(message)
+      return unless defined?(ForestAdminAgent::Facades::Container)
+
+      ForestAdminAgent::Facades::Container.logger&.log('Error', message)
+    rescue StandardError
+      # Silently ignore logging errors during shutdown
     end
   end
 end

data/lib/forest_admin_datasource_rpc/version.rb

@@ -1,3 +1,3 @@
 module ForestAdminDatasourceRpc
-  VERSION = "1.18.2"
+  VERSION = "1.18.3"
 end

data/lib/forest_admin_datasource_rpc.rb

@@ -8,131 +8,61 @@ loader.setup
 module ForestAdminDatasourceRpc
   class Error < StandardError; end
 
-  # Build a RPC datasource with schema polling enabled.
-  #
-  # @param options [Hash] Configuration options
-  # @option options [String] :uri The URI of the RPC agent
-  # @option options [String] :auth_secret The authentication secret (optional, will use cache if not provided)
-  # @option options [Integer] :schema_polling_interval Polling interval in seconds (optional)
-  #   - Default: 600 seconds (10 minutes)
-  #   - Can be overridden with ENV['SCHEMA_POLLING_INTERVAL']
-  #   - Valid range: 1-3600 seconds
-  #   - Priority: options[:schema_polling_interval] > ENV['SCHEMA_POLLING_INTERVAL'] > default
-  #   - Example: SCHEMA_POLLING_INTERVAL=30 for development (30 seconds)
-  # @option options [Hash] :introspection Pre-defined schema introspection for resilient deployment
-  #   - When provided, allows the datasource to start even if the RPC slave is unreachable
-  #   - The introspection will be used as fallback when the slave connection fails
-  #   - Schema polling will still be enabled to pick up changes when the slave becomes available
-  #
-  # @return [ForestAdminDatasourceRpc::Datasource] The configured datasource with schema polling
+  def self.configure_polling_pool(max_threads:)
+    Utils::SchemaPollingPool.instance.configure(max_threads: max_threads)
+  end
+
   def self.build(options)
     uri = options[:uri]
     auth_secret = options[:auth_secret] || ForestAdminAgent::Facades::Container.cache(:auth_secret)
     provided_introspection = options[:introspection]
-    ForestAdminAgent::Facades::Container.logger.log('Info', "Getting schema from RPC agent on #{uri}.")
-
-    schema = nil
-
-    begin
-      rpc_client = Utils::RpcClient.new(uri, auth_secret)
-      response = rpc_client.fetch_schema('/forest/rpc-schema')
-      schema = response.body
-    rescue Faraday::ConnectionFailed => e
-      ForestAdminAgent::Facades::Container.logger.log(
-        'Error',
-        "Connection failed to RPC agent at #{uri}: #{e.message}\n#{e.backtrace.join("\n")}"
-      )
-    rescue Faraday::TimeoutError => e
-      ForestAdminAgent::Facades::Container.logger.log(
-        'Error',
-        "Request timeout to RPC agent at #{uri}: #{e.message}"
-      )
-    rescue ForestAdminAgent::Http::Exceptions::AuthenticationOpenIdClient => e
-      ForestAdminAgent::Facades::Container.logger.log(
-        'Error',
-        "Authentication failed with RPC agent at #{uri}: #{e.message}"
-      )
-    rescue StandardError => e
-      ForestAdminAgent::Facades::Container.logger.log(
-        'Error',
-        "Failed to get schema from RPC agent at #{uri}: #{e.class} - #{e.message}\n#{e.backtrace.join("\n")}"
-      )
-    end
 
-    # Use provided introspection as fallback when slave is unreachable
-    if schema.nil? && provided_introspection
-      ForestAdminAgent::Facades::Container.logger.log(
-        'Warn',
-        "RPC agent at #{uri} is unreachable, using provided introspection for resilient deployment."
-      )
-      options.delete(:introspection)
-      schema = provided_introspection
-    end
-
-    if schema.nil?
-      # return empty datasource for not breaking stack
-      ForestAdminDatasourceToolkit::Datasource.new
-    else
-      # Create schema polling client with configurable polling interval
-      # Priority: options[:schema_polling_interval] > ENV['SCHEMA_POLLING_INTERVAL'] > default (600)
-      polling_interval = if options[:schema_polling_interval]
-                           options[:schema_polling_interval]
-                         elsif ENV['SCHEMA_POLLING_INTERVAL']
-                           ENV['SCHEMA_POLLING_INTERVAL'].to_i
-                         else
-                           600 # 10 minutes by default
-                         end
+    polling_interval = options[:schema_polling_interval_sec] ||
+                       ENV['SCHEMA_POLLING_INTERVAL_SEC']&.to_i ||
+                       600
 
-      polling_options = {
-        polling_interval: polling_interval
-      }
+    # Auto-configure pool with default settings if not already configured
+    ensure_pool_configured
 
-      schema_polling = Utils::SchemaPollingClient.new(uri, auth_secret, polling_options) do
-        # Callback when schema change is detected
+    schema_polling = Utils::SchemaPollingClient.new(
+      uri,
+      auth_secret,
+      polling_interval: polling_interval,
+      introspection_schema: provided_introspection
+    ) do
+      Thread.new do
         logger = ForestAdminAgent::Facades::Container.logger
-        logger.log('Info', '[RPCDatasource] Schema change detected, reloading agent...')
-        ForestAdminAgent::Builder::AgentFactory.instance.reload!
+        logger.log('Info', '[RPCDatasource] Schema change detected, reloading agent in background...')
+        begin
+          ForestAdminAgent::Builder::AgentFactory.instance.reload!
+          logger.log('Info', '[RPCDatasource] Agent reload completed successfully')
+        rescue StandardError => e
+          logger.log('Error', "[RPCDatasource] Agent reload failed: #{e.class} - #{e.message}")
+        end
       end
-      schema_polling.start
-
-      datasource = ForestAdminDatasourceRpc::Datasource.new(options, schema, schema_polling)
+    end
 
-      # Setup cleanup hooks for proper schema polling client shutdown
-      setup_cleanup_hooks(datasource)
+    # Start polling (includes initial synchronous schema fetch)
+    # - Without introspection: crashes if RPC is unreachable
+    # - With introspection: falls back to introspection if RPC is unreachable
+    schema_polling.start?
 
-      datasource
+    schema = schema_polling.current_schema
+    if schema.nil?
+      raise ForestAdminDatasourceToolkit::Exceptions::ForestException,
+            'Fatal: Unable to build RPC datasource - no introspection schema was provided and schema fetch failed'
     end
+
+    ForestAdminDatasourceRpc::Datasource.new(options, schema, schema_polling)
   end
 
-  def self.setup_cleanup_hooks(datasource)
-    # Register cleanup handler for graceful shutdown
-    at_exit do
-      datasource.cleanup
-    rescue StandardError => e
-      # Silently ignore errors during exit cleanup to prevent test pollution
-      warn "[RPCDatasource] Error during at_exit cleanup: #{e.message}" if $VERBOSE
-    end
+  def self.ensure_pool_configured
+    pool = Utils::SchemaPollingPool.instance
+    return if pool.configured
 
-    # Handle SIGINT (Ctrl+C)
-    Signal.trap('INT') do
-      begin
-        ForestAdminAgent::Facades::Container.logger&.log('Info', '[RPCDatasource] Received SIGINT, cleaning up...')
-      rescue StandardError
-        # Logger might not be available
-      end
-      datasource.cleanup
-      exit(0)
-    end
-
-    # Handle SIGTERM (default kill signal)
-    Signal.trap('TERM') do
-      begin
-        ForestAdminAgent::Facades::Container.logger&.log('Info', '[RPCDatasource] Received SIGTERM, cleaning up...')
-      rescue StandardError
-        # Logger might not be available
-      end
-      datasource.cleanup
-      exit(0)
-    end
+    # Auto-configure with default thread count if user hasn't configured
+    pool.configure(max_threads: Utils::SchemaPollingPool::DEFAULT_MAX_THREADS)
   end
+
+  private_class_method :ensure_pool_configured
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: forest_admin_datasource_rpc
 version: !ruby/object:Gem::Version
-  version: 1.18.2
+  version: 1.18.3
 platform: ruby
 authors:
 - Matthieu
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-12-12 00:00:00.000000000 Z
+date: 2025-12-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -126,6 +126,7 @@ files:
 - lib/forest_admin_datasource_rpc.rb
 - lib/forest_admin_datasource_rpc/Utils/rpc_client.rb
 - lib/forest_admin_datasource_rpc/Utils/schema_polling_client.rb
+- lib/forest_admin_datasource_rpc/Utils/schema_polling_pool.rb
 - lib/forest_admin_datasource_rpc/collection.rb
 - lib/forest_admin_datasource_rpc/datasource.rb
 - lib/forest_admin_datasource_rpc/version.rb