pinot-client 1.6.0 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ea9db0f69b7fb8d963190553d6a92201f4d63d5d6a07a975f862d00e43aa30a
-  data.tar.gz: c3b968737e6b7650c57bb79ef42153eb6870df22521939f885e5332fe4a2b7eb
+  metadata.gz: 819824203883477127807cc1a86d8535f7721883dfaec85423c5b333dd453b6e
+  data.tar.gz: dff26b09b035ad4d217a63b2b661677d4b47922760f2f140a6cda942d9383a20
 SHA512:
-  metadata.gz: b5809f8a9245ff2b13cd6a487499aff37ad9f879d4c5537570f61b1c34da6fe702817bb3ced5d6c812f8b38b9283bafb1bb3a16f2ae1f9279436e9cf86f274ae
-  data.tar.gz: 78c2573048ced129a60d9186092acba394456304cc343f1fca56cce1fa0bc8e3417c8748b3bd50a97f6dcd5f05f32caaf2c0f2a12e153e5685876e06aa033f31
+  metadata.gz: 606903f919bd310a8b1c208206db2c4ac25b5522ee26079435966f95f171573b0800266970ca3643c29528f506cf2a2c392b7161f7f2c3a174c313732a53721e
+  data.tar.gz: bc99e8c6ba493de6a534009e557915f9e72a57298129837750c49d8e1026dc8785822b079c63d05c42842a5b800930c44ac415bdf487e622fe1518f5cbbbf867

data/README.md

@@ -62,6 +62,30 @@ The client periodically polls the controller's `/v2/brokers/tables` API and auto
 client = Pinot.from_controller("localhost:9000")
 ```
 
+### Via gRPC
+
+Requires the `grpc` gem (`gem "grpc", "~> 1.65"` in your Gemfile).
+
+```ruby
+grpc_config = Pinot::GrpcConfig.new(
+  broker_list: ["localhost:8090"],
+  timeout:     10,
+  extra_metadata: { "Authorization" => "Bearer <token>" }
+)
+config = Pinot::ClientConfig.new(grpc_config: grpc_config)
+client = Pinot.from_config(config)
+```
+
+### From ZooKeeper (dynamic broker discovery)
+
+Requires the `zk` gem (`gem "zk"` in your Gemfile). Watches `/EXTERNALVIEW/brokerResource` and automatically picks up broker changes.
+
+```ruby
+zk_config = Pinot::ZookeeperConfig.new(zk_path: "localhost:2181")
+config = Pinot::ClientConfig.new(zookeeper_config: zk_config)
+client = Pinot.from_config(config)
+```
+
 ### From a `ClientConfig`
 
 ```ruby
@@ -79,6 +103,8 @@ config = Pinot::ClientConfig.new(
 client = Pinot.from_config(config)
 ```
 
+`validate!` raises `Pinot::ConfigurationError` early if the config is invalid.
+
 ### With TLS
 
 ```ruby
@@ -111,6 +137,20 @@ config = Pinot::ClientConfig.new(
 client = Pinot.from_config(config)
 ```
 
+## Instrumentation
+
+Hook into every query execution for metrics, tracing, or alerting:
+
+```ruby
+Pinot::Instrumentation.on_query = lambda do |event|
+  puts "#{event[:table]} #{event[:query][0..50]} " \
+       "#{event[:duration_ms].round(1)}ms " \
+       "success=#{event[:success]}"
+end
+```
+
+The event hash contains: `:table`, `:query`, `:duration_ms` (Float), `:success` (Boolean), `:error` (Exception or nil).
+
 ## Executing Queries
 
 ### Simple SQL
@@ -148,6 +188,19 @@ config = Pinot::ClientConfig.new(
 client = Pinot.from_config(config)
 ```
 
+### Per-request timeout
+
+```ruby
+# Global default via config
+config = Pinot::ClientConfig.new(
+  broker_list:      ["localhost:8000"],
+  query_timeout_ms: 5000
+)
+
+# One-off override per query
+resp = client.execute_sql_with_timeout("myTable", "SELECT * FROM myTable", 3000)
+```
+
 ### Trace
 
 ```ruby
@@ -182,6 +235,19 @@ rescue Pinot::Error => e
 end
 ```
 
+## Retry
+
+Configure automatic retry with exponential backoff for transient errors (connection reset, timeout, HTTP 503):
+
+```ruby
+config = Pinot::ClientConfig.new(
+  broker_list:       ["localhost:8000"],
+  max_retries:       3,
+  retry_interval_ms: 200   # base interval; doubles each attempt (200ms, 400ms, 800ms)
+)
+client = Pinot.from_config(config)
+```
+
 ## Reading Results
 
 `execute_sql` returns a `Pinot::BrokerResponse`. Results are in `result_table`:

data/lib/pinot/config.rb

@@ -22,7 +22,9 @@ module Pinot
   class ClientConfig
     attr_accessor :broker_list, :http_timeout, :query_timeout_ms, :extra_http_header,
                   :use_multistage_engine, :controller_config, :logger, :tls_config,
-                  :grpc_config, :zookeeper_config, :query_timeout_ms
+                  :grpc_config, :zookeeper_config,
+                  :max_retries,      # Integer, default 0 (no retry)
+                  :retry_interval_ms # Integer ms base interval, default 200
 
     def initialize(
       broker_list: [],
@@ -35,7 +37,8 @@ module Pinot
       tls_config: nil,
       grpc_config: nil,
       zookeeper_config: nil,
-      query_timeout_ms: nil
+      max_retries: 0,
+      retry_interval_ms: 200
     )
       @broker_list = broker_list
       @http_timeout = http_timeout
@@ -48,6 +51,8 @@ module Pinot
       @grpc_config = grpc_config
       @zookeeper_config = zookeeper_config
       @query_timeout_ms = query_timeout_ms
+      @max_retries = max_retries
+      @retry_interval_ms = retry_interval_ms
     end
 
     def validate!

data/lib/pinot/connection_factory.rb

@@ -37,7 +37,9 @@ module Pinot
       transport = JsonHttpTransport.new(
         http_client: inner,
         extra_headers: config.extra_http_header || {},
-        logger: config.logger
+        logger: config.logger,
+        max_retries: config.max_retries || 0,
+        retry_interval_ms: config.retry_interval_ms || 200
       )
 
       return Connection.new(
@@ -53,7 +55,9 @@ module Pinot
     transport = JsonHttpTransport.new(
       http_client: inner,
       extra_headers: config.extra_http_header || {},
-      logger: config.logger
+      logger: config.logger,
+      max_retries: config.max_retries || 0,
+      retry_interval_ms: config.retry_interval_ms || 200
     )
 
     selector = build_selector(config, inner)

data/lib/pinot/transport.rb

@@ -108,33 +108,60 @@ module Pinot
       "Content-Type" => "application/json; charset=utf-8"
     }.freeze
 
-    def initialize(http_client:, extra_headers: {}, timeout_ms: nil, logger: nil)
+    RETRYABLE_ERRORS = [
+      Errno::ECONNRESET, Errno::ECONNREFUSED, Errno::ETIMEDOUT,
+      Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout
+    ].freeze
+
+    def initialize(http_client:, extra_headers: {}, timeout_ms: nil, logger: nil,
+                   max_retries: 0, retry_interval_ms: 200)
       @http_client = http_client
       @extra_headers = extra_headers
       @timeout_ms = timeout_ms
       @logger = logger
+      @max_retries = max_retries
+      @retry_interval_ms = retry_interval_ms
     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
-        .merge(@extra_headers)
-        .merge("X-Correlation-Id" => SecureRandom.uuid)
+      attempts = 0
+      max_attempts = (@max_retries || 0) + 1
 
-      resp = @http_client.post(url, body: body, headers: headers)
+      begin
+        attempts += 1
 
-      unless resp.code.to_i == 200
-        logger.error "Pinot broker returned HTTP #{resp.code}"
-        raise TransportError, "http exception with HTTP status code #{resp.code}"
-      end
+        url = build_url(broker_address, request.query_format)
+        body = build_body(request)
+        headers = DEFAULT_HEADERS
+          .merge(@extra_headers)
+          .merge("X-Correlation-Id" => SecureRandom.uuid)
 
-      begin
-        BrokerResponse.from_json(resp.body)
-      rescue JSON::ParserError => e
-        raise e.message
+        resp = @http_client.post(url, body: body, headers: headers)
+
+        if resp.code == "503"
+          logger.error "Pinot broker returned HTTP #{resp.code}"
+          raise TransportError, "http exception with HTTP status code #{resp.code}"
+        end
+
+        unless resp.code.to_i == 200
+          logger.error "Pinot broker returned HTTP #{resp.code}"
+          raise TransportError, "http exception with HTTP status code #{resp.code}"
+        end
+
+        begin
+          BrokerResponse.from_json(resp.body)
+        rescue JSON::ParserError => e
+          raise e.message
+        end
+      rescue TransportError, *RETRYABLE_ERRORS => e
+        if attempts < max_attempts
+          sleep_ms = (@retry_interval_ms || 200) * (2 ** (attempts - 1))
+          sleep(sleep_ms / 1000.0)
+          retry
+        end
+        raise
       end
     end
 

data/lib/pinot/version.rb

@@ -1,3 +1,3 @@
 module Pinot
-  VERSION = "1.6.0"
+  VERSION = "1.8.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pinot-client
 version: !ruby/object:Gem::Version
-  version: 1.6.0
+  version: 1.8.0
 platform: ruby
 authors:
 - Xiang Fu