pinot-client 1.0.2 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1859bffb975457a69f7eb417283f2e4671c5f53b1f7e12b9509ea0704f89c74f
-  data.tar.gz: ed8f59fe262df5a4a1133b8dfcac0765066c20528d6f7c9e2fd0326524bf0999
+  metadata.gz: 8307d3d291be0af45b13a63512bd9f7d2f10d1c4db6383edd72b9ab5bb7c1e03
+  data.tar.gz: c74a5865da644b9edf2db66cfcc79eb6021e8ac06a872ab7e2d2528448ea1ea2
 SHA512:
-  metadata.gz: 9e64c60e9cff0130ae77c31fe7898223d9dfe4c95015fb6a40e8a54b1afb3de601c1b58fbde3940e132c07365ebd19cbf56e35746a50d15e3b76913a187111d5
-  data.tar.gz: 0653ae3c8241944ceaa4fc982c45e277ca057c4a938754c4b5873d1cf75257c720cd8adeeabb0315ca2401e2268270bad3fc394f9ae6eebab868fdfa8f257490
+  metadata.gz: ae76f79806e4a0eef9f18f7ea7253a2ad4aba9f098bdf389e91b5cb1e2463d1e5637f158984523ceb9e99de0da293f541e37c36ac322d877d78c0be024ff6883
+  data.tar.gz: 034d035acefa3616c6f4892f22bd6cfc9569e43ffa5189930b96efc6a232a0e0fe11795a96e4546be6d7577425da3e590afab42223730ae682d86abb868d16e5

data/README.md

@@ -67,7 +67,7 @@ client = Pinot.from_controller("localhost:9000")
 ```ruby
 config = Pinot::ClientConfig.new(
   broker_list:           ["localhost:8000"],
-  http_timeout:          10,          # seconds
+  http_timeout:          10,          # seconds — sets open_timeout, read_timeout, and write_timeout on the underlying Net::HTTP connection
   extra_http_header:     { "Authorization" => "Bearer <token>" },
   use_multistage_engine: false,
   controller_config: Pinot::ControllerConfig.new(
@@ -79,6 +79,38 @@ config = Pinot::ClientConfig.new(
 client = Pinot.from_config(config)
 ```
 
+### With TLS
+
+```ruby
+tls = Pinot::TlsConfig.new(
+  ca_cert_file:        "/path/to/ca.pem",
+  client_cert_file:    "/path/to/client.crt",
+  client_key_file:     "/path/to/client.key",
+  insecure_skip_verify: false   # set true to skip cert verification
+)
+config = Pinot::ClientConfig.new(
+  broker_list: ["https://pinot-broker.example.com:8000"],
+  tls_config:  tls
+)
+client = Pinot.from_config(config)
+```
+
+## Logging
+
+By default the client logs warnings to stdout. Configure a custom logger globally or per-client:
+
+```ruby
+# Global logger
+Pinot::Logging.logger = Logger.new("pinot.log", level: Logger::DEBUG)
+
+# Per-client logger via ClientConfig
+config = Pinot::ClientConfig.new(
+  broker_list: ["localhost:8000"],
+  logger: Logger.new($stdout, level: Logger::INFO)
+)
+client = Pinot.from_config(config)
+```
+
 ## Executing Queries
 
 ### Simple SQL
@@ -106,6 +138,16 @@ client.use_multistage_engine = true
 resp = client.execute_sql("baseballStats", "SELECT teamID, count(*) FROM baseballStats GROUP BY teamID")
 ```
 
+Or enable it upfront via `ClientConfig`:
+
+```ruby
+config = Pinot::ClientConfig.new(
+  broker_list:           ["localhost:8000"],
+  use_multistage_engine: true
+)
+client = Pinot.from_config(config)
+```
+
 ### Trace
 
 ```ruby
@@ -114,6 +156,32 @@ resp = client.execute_sql("baseballStats", "SELECT count(*) FROM baseballStats")
 client.close_trace
 ```
 
+## Error Handling
+
+All errors raised by the client inherit from `Pinot::Error < StandardError`:
+
+| Class | Raised when |
+|-------|-------------|
+| `Pinot::BrokerNotFoundError` | No broker available (empty list or all offline) |
+| `Pinot::TableNotFoundError` | Named table not found in broker map |
+| `Pinot::TransportError` | Non-200 HTTP response from broker |
+| `Pinot::PreparedStatementClosedError` | Operation on a closed prepared statement |
+| `Pinot::ConfigurationError` | Invalid config (bad URL scheme, missing broker source) |
+
+Example:
+
+```ruby
+begin
+  resp = client.execute_sql("myTable", "SELECT * FROM myTable")
+rescue Pinot::TableNotFoundError => e
+  puts "Table missing: #{e.message}"
+rescue Pinot::TransportError => e
+  puts "Broker error: #{e.message}"
+rescue Pinot::Error => e
+  puts "Pinot error: #{e.message}"
+end
+```
+
 ## Reading Results
 
 `execute_sql` returns a `Pinot::BrokerResponse`. Results are in `result_table`:

data/lib/pinot/config.rb

@@ -11,20 +11,24 @@ module Pinot
 
   class ClientConfig
     attr_accessor :broker_list, :http_timeout, :extra_http_header,
-                  :use_multistage_engine, :controller_config
+                  :use_multistage_engine, :controller_config, :logger, :tls_config
 
     def initialize(
       broker_list: [],
       http_timeout: nil,
       extra_http_header: {},
       use_multistage_engine: false,
-      controller_config: nil
+      controller_config: nil,
+      logger: nil,
+      tls_config: nil
     )
       @broker_list = broker_list
       @http_timeout = http_timeout
       @extra_http_header = extra_http_header
       @use_multistage_engine = use_multistage_engine
       @controller_config = controller_config
+      @logger = logger
+      @tls_config = tls_config
     end
   end
 end

data/lib/pinot/connection.rb

@@ -2,11 +2,12 @@ require "bigdecimal"
 
 module Pinot
   class Connection
-    def initialize(transport:, broker_selector:, use_multistage_engine: false)
+    def initialize(transport:, broker_selector:, use_multistage_engine: false, logger: nil)
       @transport = transport
       @broker_selector = broker_selector
       @use_multistage_engine = use_multistage_engine
       @trace = false
+      @logger = logger
     end
 
     def use_multistage_engine=(val)
@@ -22,6 +23,7 @@ module Pinot
     end
 
     def execute_sql(table, query)
+      logger.debug "Executing SQL on table=#{table}: #{query}"
       broker = @broker_selector.select_broker(table)
       @transport.execute(broker, build_request(query))
     rescue => e
@@ -87,6 +89,10 @@ module Pinot
 
     private
 
+    def logger
+      @logger || Pinot::Logging.logger
+    end
+
     def build_request(query)
       Request.new("sql", query, @trace, @use_multistage_engine)
     end

data/lib/pinot/connection_factory.rb

@@ -12,20 +12,22 @@ module Pinot
   end
 
   def self.from_config(config, http_client: nil)
-    inner = http_client || HttpClient.new(timeout: config.http_timeout)
+    inner = http_client || HttpClient.new(timeout: config.http_timeout, tls_config: config.tls_config)
 
     transport = JsonHttpTransport.new(
       http_client: inner,
-      extra_headers: config.extra_http_header || {}
+      extra_headers: config.extra_http_header || {},
+      logger: config.logger
     )
 
     selector = build_selector(config, inner)
-    raise ArgumentError, "must specify broker_list or controller_config" unless selector
+    raise ConfigurationError, "must specify broker_list or controller_config" unless selector
 
     conn = Connection.new(
       transport: transport,
       broker_selector: selector,
-      use_multistage_engine: config.use_multistage_engine || false
+      use_multistage_engine: config.use_multistage_engine || false,
+      logger: config.logger
     )
 
     selector.init
@@ -36,7 +38,7 @@ module Pinot
     if config.broker_list && !config.broker_list.empty?
       SimpleBrokerSelector.new(config.broker_list)
     elsif config.controller_config
-      ControllerBasedBrokerSelector.new(config.controller_config, http_client)
+      ControllerBasedBrokerSelector.new(config.controller_config, http_client, logger: config.logger)
     end
   end
   private_class_method :build_selector

data/lib/pinot/controller_based_broker_selector.rb

@@ -7,16 +7,18 @@ module Pinot
     CONTROLLER_API_PATH = "/v2/brokers/tables?state=ONLINE"
     DEFAULT_UPDATE_FREQ_MS = 1000
 
-    def initialize(config, http_client = nil)
+    def initialize(config, http_client = nil, logger: nil)
       super()
       @config = config
       @internal_http = http_client || HttpClient.new
+      @logger = logger
     end
 
     def init
       @config.update_freq_ms ||= DEFAULT_UPDATE_FREQ_MS
       @controller_url = build_controller_url(@config.controller_address)
       fetch_and_update
+      logger.info "ControllerBasedBrokerSelector initialized with #{@all_broker_list.size} brokers"
       start_background_refresh
       nil
     end
@@ -26,7 +28,7 @@ module Pinot
       if addr.include?("://")
         scheme = addr.split("://").first
         unless %w[http https].include?(scheme)
-          raise "unsupported controller URL scheme: #{scheme}"
+          raise ConfigurationError, "unsupported controller URL scheme: #{scheme}"
         end
         addr.chomp("/") + CONTROLLER_API_PATH
       else
@@ -43,20 +45,24 @@ module Pinot
       resp = @internal_http.get(@controller_url, headers: headers)
 
       unless resp.code.to_i == 200
-        raise "controller API returned HTTP status code #{resp.code}"
+        raise TransportError, "controller API returned HTTP status code #{resp.code}"
       end
 
       body = resp.body
       begin
         raw = JSON.parse(body)
       rescue JSON::ParserError => e
-        raise "error decoding controller API response: #{e.message}"
+        raise ConfigurationError, "error decoding controller API response: #{e.message}"
       end
 
       cr = ControllerResponse.new(raw)
       update_broker_data(cr.extract_broker_list, cr.extract_table_to_broker_map)
     end
 
+    def logger
+      @logger || Pinot::Logging.logger
+    end
+
     def start_background_refresh
       interval = @config.update_freq_ms / 1000.0
       Thread.new do
@@ -65,7 +71,7 @@ module Pinot
           begin
             fetch_and_update
           rescue => e
-            warn "Pinot: error refreshing broker data: #{e.message}"
+            logger.warn "Pinot controller refresh failed: #{e.message}"
           end
         end
       end

data/lib/pinot/errors.rb

@@ -0,0 +1,8 @@
+module Pinot
+  class Error < StandardError; end
+  class BrokerNotFoundError < Error; end
+  class TableNotFoundError < Error; end
+  class TransportError < Error; end
+  class PreparedStatementClosedError < Error; end
+  class ConfigurationError < Error; end
+end

data/lib/pinot/logger.rb

@@ -0,0 +1,17 @@
+require "logger"
+
+module Pinot
+  module Logging
+    def self.logger
+      @logger ||= begin
+        l = Logger.new($stdout)
+        l.level = Logger::WARN
+        l
+      end
+    end
+
+    def self.logger=(logger)
+      @logger = logger
+    end
+  end
+end

data/lib/pinot/prepared_statement.rb

@@ -51,7 +51,7 @@ module Pinot
 
     def set(index, value)
       @mutex.synchronize do
-        raise "prepared statement is closed" if @closed
+        raise PreparedStatementClosedError, "prepared statement is closed" if @closed
         unless index >= 1 && index <= @param_count
           raise "parameter index #{index} is out of range [1, #{@param_count}]"
         end
@@ -62,7 +62,7 @@ module Pinot
 
     def execute
       @mutex.synchronize do
-        raise "prepared statement is closed" if @closed
+        raise PreparedStatementClosedError, "prepared statement is closed" if @closed
         @parameters.each_with_index do |p, i|
           raise "parameter at index #{i + 1} is not set" if p.nil?
         end
@@ -76,7 +76,7 @@ module Pinot
     end
 
     def execute_with_params(*params)
-      @mutex.synchronize { raise "prepared statement is closed" if @closed }
+      @mutex.synchronize { raise PreparedStatementClosedError, "prepared statement is closed" if @closed }
       if params.length != @param_count
         raise "expected #{@param_count} parameters, got #{params.length}"
       end
@@ -90,7 +90,7 @@ module Pinot
 
     def clear_parameters
       @mutex.synchronize do
-        raise "prepared statement is closed" if @closed
+        raise PreparedStatementClosedError, "prepared statement is closed" if @closed
         @parameters.fill(nil)
       end
       nil

data/lib/pinot/simple_broker_selector.rb

@@ -7,11 +7,11 @@ module Pinot
     end
 
     def init
-      raise "no pre-configured broker lists" if @broker_list.empty?
+      raise BrokerNotFoundError, "no pre-configured broker lists" if @broker_list.empty?
     end
 
     def select_broker(_table)
-      raise "no pre-configured broker lists" if @broker_list.empty?
+      raise BrokerNotFoundError, "no pre-configured broker lists" if @broker_list.empty?
       @broker_list.sample
     end
   end

data/lib/pinot/table_aware_broker_selector.rb

@@ -19,12 +19,12 @@ module Pinot
       table_name = extract_table_name(table.to_s)
       @mutex.synchronize do
         if table_name.empty?
-          raise "no available broker" if @all_broker_list.empty?
+          raise BrokerNotFoundError, "no available broker" if @all_broker_list.empty?
           return @all_broker_list.sample
         end
         brokers = @table_broker_map[table_name]
-        raise "unable to find table: #{table}" unless brokers
-        raise "no available broker for table: #{table}" if brokers.empty?
+        raise TableNotFoundError, "unable to find table: #{table}" unless brokers
+        raise BrokerNotFoundError, "no available broker for table: #{table}" if brokers.empty?
         brokers.sample
       end
     end

data/lib/pinot/tls_config.rb

@@ -0,0 +1,15 @@
+module Pinot
+  class TlsConfig
+    attr_accessor :ca_cert_file,        # path to CA cert PEM file (String, optional)
+                  :client_cert_file,    # path to client cert PEM file (String, optional)
+                  :client_key_file,     # path to client key PEM file (String, optional)
+                  :insecure_skip_verify # boolean, skip server cert verification (default: false)
+
+    def initialize(ca_cert_file: nil, client_cert_file: nil, client_key_file: nil, insecure_skip_verify: false)
+      @ca_cert_file = ca_cert_file
+      @client_cert_file = client_cert_file
+      @client_key_file = client_key_file
+      @insecure_skip_verify = insecure_skip_verify
+    end
+  end
+end

data/lib/pinot/transport.rb

@@ -2,38 +2,104 @@ require "net/http"
 require "uri"
 require "json"
 require "securerandom"
+require "openssl"
 
 module Pinot
   class HttpClient
-    def initialize(timeout: nil)
+    MAX_POOL_SIZE = 5
+    KEEP_ALIVE_TIMEOUT = 30
+
+    def initialize(timeout: nil, tls_config: nil)
       @timeout = timeout
+      @tls_config = tls_config
+      @pool = {}
+      @pool_mutex = Mutex.new
     end
 
     def post(url, body:, headers: {})
       uri = URI.parse(url)
-      http = Net::HTTP.new(uri.host, uri.port)
-      http.use_ssl = uri.scheme == "https"
-      if @timeout
-        http.open_timeout = @timeout
-        http.read_timeout = @timeout
+      with_connection(url) do |http|
+        req = Net::HTTP::Post.new(uri.request_uri)
+        headers.each { |k, v| req[k] = v }
+        req.body = body
+        http.request(req)
       end
-      req = Net::HTTP::Post.new(uri.request_uri)
-      headers.each { |k, v| req[k] = v }
-      req.body = body
-      http.request(req)
     end
 
     def get(url, headers: {})
       uri = URI.parse(url)
+      with_connection(url) do |http|
+        req = Net::HTTP::Get.new(uri.request_uri)
+        headers.each { |k, v| req[k] = v }
+        http.request(req)
+      end
+    end
+
+    private
+
+    def with_connection(url)
+      uri = URI.parse(url)
+      key = "#{uri.host}:#{uri.port}"
+      http = checkout(key, uri)
+      begin
+        result = yield http
+        checkin(key, http)
+        result
+      rescue => e
+        http.finish rescue nil
+        raise e
+      end
+    end
+
+    def checkout(key, uri)
+      @pool_mutex.synchronize { @pool[key]&.pop } || new_connection(uri)
+    end
+
+    def checkin(key, http)
+      @pool_mutex.synchronize do
+        pool_for_key = @pool[key] ||= []
+        if pool_for_key.size < MAX_POOL_SIZE
+          pool_for_key.push(http)
+        else
+          http.finish rescue nil
+        end
+      end
+    end
+
+    def new_connection(uri)
       http = Net::HTTP.new(uri.host, uri.port)
-      http.use_ssl = uri.scheme == "https"
+      configure_ssl(http, uri)
       if @timeout
         http.open_timeout = @timeout
         http.read_timeout = @timeout
+        http.write_timeout = @timeout
+      end
+      http.start
+      http
+    end
+
+    def configure_ssl(http, uri)
+      if uri.scheme == "https"
+        http.use_ssl = true
+        if @tls_config
+          if @tls_config.ca_cert_file
+            store = OpenSSL::X509::Store.new
+            store.add_file(@tls_config.ca_cert_file)
+            http.cert_store = store
+          end
+          if @tls_config.client_cert_file && @tls_config.client_key_file
+            http.cert = OpenSSL::X509::Certificate.new(File.read(@tls_config.client_cert_file))
+            http.key = OpenSSL::PKey.read(File.read(@tls_config.client_key_file))
+          end
+          if @tls_config.insecure_skip_verify
+            http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+          else
+            http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+          end
+        end
+      else
+        http.use_ssl = false
       end
-      req = Net::HTTP::Get.new(uri.request_uri)
-      headers.each { |k, v| req[k] = v }
-      http.request(req)
     end
   end
 
@@ -42,13 +108,16 @@ module Pinot
       "Content-Type" => "application/json; charset=utf-8"
     }.freeze
 
-    def initialize(http_client:, extra_headers: {}, timeout_ms: nil)
+    def initialize(http_client:, extra_headers: {}, timeout_ms: nil, logger: nil)
       @http_client = http_client
       @extra_headers = extra_headers
       @timeout_ms = timeout_ms
+      @logger = logger
     end
 
     def execute(broker_address, request)
+      logger.debug "Pinot query to #{broker_address}: #{request.query}"
+
       url = build_url(broker_address, request.query_format)
       body = build_body(request)
       headers = DEFAULT_HEADERS
@@ -58,7 +127,8 @@ module Pinot
       resp = @http_client.post(url, body: body, headers: headers)
 
       unless resp.code.to_i == 200
-        raise "http exception with HTTP status code #{resp.code}"
+        logger.error "Pinot broker returned HTTP #{resp.code}"
+        raise TransportError, "http exception with HTTP status code #{resp.code}"
       end
 
       begin
@@ -70,6 +140,10 @@ module Pinot
 
     private
 
+    def logger
+      @logger || Pinot::Logging.logger
+    end
+
     def build_url(broker_address, query_format)
       base = if broker_address.start_with?("http://", "https://")
                broker_address

data/lib/pinot/version.rb

@@ -1,3 +1,3 @@
 module Pinot
-  VERSION = "1.0.2"
+  VERSION = "1.2.0"
 end

data/lib/pinot.rb

@@ -4,8 +4,11 @@ require "json"
 require "bigdecimal"
 require "securerandom"
 
+require_relative "pinot/errors"
 require_relative "pinot/version"
+require_relative "pinot/logger"
 require_relative "pinot/config"
+require_relative "pinot/tls_config"
 require_relative "pinot/request"
 require_relative "pinot/response"
 require_relative "pinot/broker_selector"

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: pinot-client
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.2.0
 platform: ruby
 authors:
 - Xiang Fu
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-18 00:00:00.000000000 Z
+date: 2026-04-19 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -67,11 +81,14 @@ files:
 - lib/pinot/connection_factory.rb
 - lib/pinot/controller_based_broker_selector.rb
 - lib/pinot/controller_response.rb
+- lib/pinot/errors.rb
+- lib/pinot/logger.rb
 - lib/pinot/prepared_statement.rb
 - lib/pinot/request.rb
 - lib/pinot/response.rb
 - lib/pinot/simple_broker_selector.rb
 - lib/pinot/table_aware_broker_selector.rb
+- lib/pinot/tls_config.rb
 - lib/pinot/transport.rb
 - lib/pinot/version.rb
 homepage: https://github.com/startreedata/ruby-pinot-client