pinot-client 1.1.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f2e2377c6f9af1cb73b472bd5b7c9ad2bfa512ec0594c67d3298c884bee5f0a
-  data.tar.gz: 608b9a1f070dd22d71a793ad1e4817dcdbe4100b14e3aa4033e71643fc2de9a8
+  metadata.gz: f6d0692d6f1de1178eb0c27cb2f69e3f6575362b1163e58032538b2b003e13cb
+  data.tar.gz: d9ee2eb20b541cfe54ad640b223425ed16697e869b031349d021ef89c8bab5af
 SHA512:
-  metadata.gz: bd247b8088c5be2b20d78e95e0cc16effd8b8c24e136810101f5a136d630dcbca002127ace5ea56f98a9c9308a0d7ae42c20d16a32d9ebba8ad3f11656ceff08
-  data.tar.gz: 02ecaf1df43b2117a2ad86cf481ec241412668c3e96a49fc046e2a730fd92e6d44edad99f34f9ab68eac44d457cd88d5acda636226241ab7bbe82206ae99ea0c
+  metadata.gz: d66f070cd740df59a8351724b954b902633052e0a94c0cffcc377cba887329709955b0c93075f5f90ea820abe453aa716b4f6eae80600ce90015eda669c33dd0
+  data.tar.gz: '03345279b3e4ae8621fa75a4222dce2988cf61255663b659c7307296a9506680f29f804938ec1b5d28326bf15e4e5c4cf5984e71233b2e0fcf255f6123f0fa36'

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
@@ -124,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,7 +11,8 @@ module Pinot
 
   class ClientConfig
     attr_accessor :broker_list, :http_timeout, :extra_http_header,
-                  :use_multistage_engine, :controller_config, :logger, :tls_config
+                  :use_multistage_engine, :controller_config, :logger, :tls_config,
+                  :grpc_config
 
     def initialize(
       broker_list: [],
@@ -20,7 +21,8 @@ module Pinot
       use_multistage_engine: false,
       controller_config: nil,
       logger: nil,
-      tls_config: nil
+      tls_config: nil,
+      grpc_config: nil
     )
       @broker_list = broker_list
       @http_timeout = http_timeout
@@ -29,6 +31,7 @@ module Pinot
       @controller_config = controller_config
       @logger = logger
       @tls_config = tls_config
+      @grpc_config = grpc_config
     end
   end
 end

data/lib/pinot/connection_factory.rb

@@ -12,6 +12,21 @@ module Pinot
   end
 
   def self.from_config(config, http_client: nil)
+    if config.grpc_config
+      transport = GrpcTransport.new(config.grpc_config)
+      selector  = SimpleBrokerSelector.new(config.grpc_config.broker_list)
+
+      conn = Connection.new(
+        transport: transport,
+        broker_selector: selector,
+        use_multistage_engine: config.use_multistage_engine || false,
+        logger: config.logger
+      )
+
+      selector.init
+      return conn
+    end
+
     inner = http_client || HttpClient.new(timeout: config.http_timeout, tls_config: config.tls_config)
 
     transport = JsonHttpTransport.new(

data/lib/pinot/grpc_config.rb

@@ -0,0 +1,15 @@
+module Pinot
+  class GrpcConfig
+    attr_accessor :broker_list,       # Array<String> of "host:port" (no scheme)
+                  :tls_config,        # Pinot::TlsConfig or nil
+                  :extra_metadata,    # Hash — extra gRPC metadata headers
+                  :timeout            # seconds (Integer/Float), nil = no timeout
+
+    def initialize(broker_list: [], tls_config: nil, extra_metadata: {}, timeout: nil)
+      @broker_list    = broker_list
+      @tls_config     = tls_config
+      @extra_metadata = extra_metadata
+      @timeout        = timeout
+    end
+  end
+end

data/lib/pinot/grpc_transport.rb

@@ -0,0 +1,76 @@
+begin
+  require "grpc"
+  require_relative "proto/broker_service_pb"
+  require_relative "proto/broker_service_services_pb"
+rescue LoadError
+  raise LoadError, "The 'grpc' gem is required to use Pinot::GrpcTransport. Add it to your Gemfile: gem \"grpc\""
+end
+require_relative "grpc_config"
+require_relative "response"
+
+module Pinot
+  class GrpcTransport
+    def initialize(grpc_config)
+      @config = grpc_config
+    end
+
+    # Returns Pinot::BrokerResponse
+    def execute(broker_address, request)
+      stub = build_stub(broker_address)
+      grpc_request = build_request(request)
+      call_opts = build_call_opts
+
+      grpc_response = stub.submit(grpc_request, **call_opts)
+      BrokerResponse.from_json(grpc_response.payload)
+    rescue GRPC::BadStatus => e
+      raise TransportError, "gRPC error #{e.code}: #{e.details}"
+    end
+
+    private
+
+    def build_stub(broker_address)
+      creds = if @config.tls_config
+                build_ssl_credentials
+              else
+                :this_channel_is_insecure
+              end
+      Pinot::Broker::Grpc::PinotClientGrpcBrokerService::Stub.new(
+        broker_address, creds
+      )
+    end
+
+    def build_request(request)
+      meta = {}
+      query_opts = build_query_options(request)
+      meta["queryOptions"] = query_opts unless query_opts.empty?
+      meta["traceEnabled"] = "true" if request.trace
+      meta.merge!(@config.extra_metadata)
+
+      Pinot::Broker::Grpc::BrokerRequest.new(
+        sql:      request.query,
+        metadata: meta
+      )
+    end
+
+    def build_query_options(request)
+      parts = ["groupByMode=sql", "responseFormat=sql"]
+      parts << "useMultistageEngine=true" if request.use_multistage_engine
+      parts.join(";")
+    end
+
+    def build_call_opts
+      opts = {}
+      opts[:deadline] = Time.now + @config.timeout if @config.timeout
+      opts[:metadata] = @config.extra_metadata unless @config.extra_metadata.empty?
+      opts
+    end
+
+    def build_ssl_credentials
+      tls = @config.tls_config
+      root_certs = tls.ca_cert_file ? File.read(tls.ca_cert_file) : nil
+      private_key = tls.client_key_file ? File.read(tls.client_key_file) : nil
+      cert_chain  = tls.client_cert_file ? File.read(tls.client_cert_file) : nil
+      GRPC::Core::ChannelCredentials.new(root_certs, private_key, cert_chain)
+    end
+  end
+end

data/lib/pinot/proto/broker_service.proto

@@ -0,0 +1,16 @@
+syntax = "proto3";
+package pinot.broker.grpc;
+
+message BrokerRequest {
+  string sql = 1;
+  map<string, string> metadata = 2;
+}
+
+message BrokerResponse {
+  int32 result_row_size = 1;
+  bytes payload = 2;
+}
+
+service PinotClientGrpcBrokerService {
+  rpc Submit(BrokerRequest) returns (BrokerResponse);
+}

data/lib/pinot/proto/broker_service_pb.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: broker_service.proto
+
+require 'google/protobuf'
+
+
+descriptor_data = "\n\x14\x62roker_service.proto\x12\x11pinot.broker.grpc\"\x8f\x01\n\rBrokerRequest\x12\x0b\n\x03sql\x18\x01 \x01(\t\x12@\n\x08metadata\x18\x02 \x03(\x0b\x32..pinot.broker.grpc.BrokerRequest.MetadataEntry\x1a/\n\rMetadataEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\t:\x02\x38\x01\":\n\x0e\x42rokerResponse\x12\x17\n\x0fresult_row_size\x18\x01 \x01(\x05\x12\x0f\n\x07payload\x18\x02 \x01(\x0c\x32m\n\x1cPinotClientGrpcBrokerService\x12M\n\x06Submit\x12 .pinot.broker.grpc.BrokerRequest\x1a!.pinot.broker.grpc.BrokerResponseb\x06proto3"
+
+pool = ::Google::Protobuf::DescriptorPool.generated_pool
+pool.add_serialized_file(descriptor_data)
+
+module Pinot
+  module Broker
+    module Grpc
+      BrokerRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("pinot.broker.grpc.BrokerRequest").msgclass
+      BrokerResponse = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("pinot.broker.grpc.BrokerResponse").msgclass
+    end
+  end
+end

data/lib/pinot/proto/broker_service_services_pb.rb

@@ -0,0 +1,26 @@
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# Source: broker_service.proto for package 'pinot.broker.grpc'
+
+require 'grpc'
+require_relative 'broker_service_pb'
+
+module Pinot
+  module Broker
+    module Grpc
+      module PinotClientGrpcBrokerService
+        class Service
+
+          include ::GRPC::GenericService
+
+          self.marshal_class_method = :encode
+          self.unmarshal_class_method = :decode
+          self.service_name = 'pinot.broker.grpc.PinotClientGrpcBrokerService'
+
+          rpc :Submit, ::Pinot::Broker::Grpc::BrokerRequest, ::Pinot::Broker::Grpc::BrokerResponse
+        end
+
+        Stub = Service.rpc_stub_class
+      end
+    end
+  end
+end

data/lib/pinot/version.rb

@@ -1,3 +1,3 @@
 module Pinot
-  VERSION = "1.1.0"
+  VERSION = "1.3.0"
 end

data/lib/pinot.rb

@@ -20,3 +20,10 @@ require_relative "pinot/transport"
 require_relative "pinot/connection"
 require_relative "pinot/prepared_statement"
 require_relative "pinot/connection_factory"
+
+begin
+  require_relative "pinot/grpc_transport"
+  require_relative "pinot/grpc_config"
+rescue LoadError
+  # grpc gem not available; GrpcTransport disabled
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pinot-client
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Xiang Fu
@@ -82,8 +82,13 @@ files:
 - lib/pinot/controller_based_broker_selector.rb
 - lib/pinot/controller_response.rb
 - lib/pinot/errors.rb
+- lib/pinot/grpc_config.rb
+- lib/pinot/grpc_transport.rb
 - lib/pinot/logger.rb
 - lib/pinot/prepared_statement.rb
+- lib/pinot/proto/broker_service.proto
+- lib/pinot/proto/broker_service_pb.rb
+- lib/pinot/proto/broker_service_services_pb.rb
 - lib/pinot/request.rb
 - lib/pinot/response.rb
 - lib/pinot/simple_broker_selector.rb