questdb 0.1.0-arm64-darwin

data/lib/questdb/client.rb

@@ -0,0 +1,308 @@
+# frozen_string_literal: true
+
+#      ___                  _   ____  ____
+#     / _ \ _   _  ___  ___| |_|  _ \| __ )
+#    | | | | | | |/ _ \/ __| __| | | |  _ \
+#    | |_| | |_| |  __/\__ \ |_| |_| | |_) |
+#     \__\_\\__,_|\___||___/\__|____/|____/
+#
+#   Copyright (c) 2014-2019 Appsicle
+#   Copyright (c) 2019-2026 QuestDB
+#
+#   Licensed under the Apache License, Version 2.0 (the "License");
+#   you may not use this file except in compliance with the License.
+#   You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS,
+#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#   See the License for the specific language governing permissions and
+#   limitations under the License.
+#
+require "thread"
+require "weakref"
+
+module QuestDB
+  class Client
+    EMPTY_HASH = {}.freeze
+    private_constant :EMPTY_HASH
+    DEFAULT_EVENT_INBOX_CAPACITY = 64
+    EventInbox = QuestDB.const_get(:EventInbox, false)
+    private_constant :EventInbox
+
+    def self.from_conf(conf, connection_listener: nil, error_handler: nil,
+                       connection_event_inbox_capacity: DEFAULT_EVENT_INBOX_CAPACITY,
+                       error_event_inbox_capacity: DEFAULT_EVENT_INBOX_CAPACITY, **settings)
+      configuration, effective = Config.build(conf, settings: settings)
+      new(configuration, effective_settings: effective,
+          connection_listener: connection_listener, error_handler: error_handler,
+          connection_event_inbox_capacity: connection_event_inbox_capacity,
+          error_event_inbox_capacity: error_event_inbox_capacity)
+    end
+
+    def self.from_env(**settings)
+      conf = ENV["QDB_CLIENT_CONF"]
+      raise Ingress::IngressError.new("QDB_CLIENT_CONF is not set", code: :config_error) unless conf && !conf.empty?
+      from_conf(conf, **settings)
+    end
+
+    def self.dispatcher_proc(owner, native, kind, handler, inbox)
+      method = kind == :connection ? :next_connection_event : :next_error_event
+      converter = kind == :connection ? ConnectionEvent : SenderError
+      proc do
+        Thread.current.name = "questdb-#{kind}-events" if Thread.current.respond_to?(:name=)
+        loop do
+          break unless owner.weakref_alive?
+          values = native.public_send(method, false)
+          unless values
+            break if native.closed?
+            sleep(0.01)
+            next
+          end
+          event = converter.from_native(values)
+          inbox.push(event)
+          begin
+            handler.call(event)
+          rescue Exception => error # callbacks are diagnostics and must not poison dispatch
+            Kernel.warn("QuestDB #{kind} callback failed: #{error.class}: #{error.message}")
+          end
+        end
+      end
+    end
+    private_class_method :dispatcher_proc
+
+    def initialize(configuration, effective_settings: nil, connection_listener: nil, error_handler: nil,
+                   connection_event_inbox_capacity: DEFAULT_EVENT_INBOX_CAPACITY,
+                   error_event_inbox_capacity: DEFAULT_EVENT_INBOX_CAPACITY)
+      configuration = String(configuration).dup.freeze
+      validate_qwp!(configuration)
+      validate_handler!(connection_listener, "connection_listener")
+      validate_handler!(error_handler, "error_handler")
+      connection_capacity = validate_capacity!(connection_event_inbox_capacity, "connection_event_inbox_capacity")
+      error_capacity = validate_capacity!(error_event_inbox_capacity, "error_event_inbox_capacity")
+      parsed_settings = effective_settings || Config.parse(configuration)
+      @auto_flush = parse_auto_flush(parsed_settings)
+      @mutex = Mutex.new
+      @native = Ingress::Native::Client.new(
+        configuration, !connection_listener.nil?, connection_capacity,
+        !error_handler.nil?, error_capacity
+      )
+      @closed = false
+      @connection_inbox = connection_listener && EventInbox.new(connection_capacity)
+      @error_inbox = error_handler && EventInbox.new(error_capacity)
+      @dispatcher_threads = []
+      start_dispatcher(:connection, connection_listener, @connection_inbox) if connection_listener
+      start_dispatcher(:error, error_handler, @error_inbox) if error_handler
+    end
+
+    def sender
+      pooled = @mutex.synchronize do
+        ensure_open!
+        PooledSender.new(self, @native.borrow_sender, auto_flush: @auto_flush)
+      end
+      return pooled unless block_given?
+
+      begin
+        result = yield pooled
+        pooled.close
+        result
+      rescue Exception
+        pooled.close(flush: false)
+        raise
+      end
+    end
+
+    def reader
+      pooled = @mutex.synchronize do
+        ensure_open!
+        PooledReader.new(self, @native.borrow_reader)
+      end
+      return pooled unless block_given?
+
+      begin
+        yield pooled
+      ensure
+        pooled.close unless pooled.closed?
+      end
+    end
+
+    def query(sql, binds: nil, reset_symbol_dict: true)
+      pooled = reader
+      begin
+        result = pooled.query(sql, binds: binds, reset_symbol_dict: reset_symbol_dict)
+        result.send(:close_reader_on_close!)
+      rescue Exception
+        pooled.close unless pooled.closed?
+        raise
+      end
+      return result unless block_given?
+
+      begin
+        yield result
+      ensure
+        result.close
+        pooled.close unless pooled.closed?
+      end
+    end
+
+    # Write homogeneous Ruby columns over a pooled direct QWP connection.
+    # Unlike row ingestion this is a checked, non-store-and-forward commit:
+    # all batches are pipelined and committed at the requested ACK boundary.
+    def ingest_columns(table, columns:, symbols: EMPTY_HASH, at:, max_rows_per_batch: 16_384, ack: :ok)
+      prepared = DirectIngestion.prepare(
+        table,
+        columns: columns,
+        symbols: symbols,
+        at: at,
+        max_rows_per_batch: max_rows_per_batch,
+        ack: ack
+      )
+      @mutex.synchronize { ensure_open! }
+      return self if prepared[4].zero?
+
+      @native.ingest_columns(*prepared)
+      self
+    end
+    alias write_columns ingest_columns
+
+    def execute(sql, binds: nil)
+      reader { |pooled| pooled.execute(sql, binds: binds) }
+      nil
+    end
+
+    def server_info
+      reader { |pooled| return pooled.server_info }
+    end
+
+    def reap_idle
+      @mutex.synchronize do
+        ensure_open!
+        @native.reap_idle
+      end
+    end
+
+    # Nonblocking copies of values sent to the configured callback. These are
+    # independent of callback execution and use the same bounded/drop-oldest
+    # capacity policy.
+    def poll_connection_event = @connection_inbox&.poll
+    def poll_error = @error_inbox&.poll
+
+    def connection_events_delivered = counter(:connection_events_delivered, @connection_inbox)
+    def connection_events_dropped = counter(:connection_events_dropped, @connection_inbox, :dropped)
+    def error_events_delivered = counter(:error_events_delivered, @error_inbox)
+    def error_events_dropped = counter(:error_events_dropped, @error_inbox, :dropped)
+    def active_leases = (@closed ? 0 : @native.active_leases)
+    alias active_senders active_leases
+    def closed? = @closed || @native.closed?
+
+    def close
+      threads = nil
+      @mutex.synchronize do
+        return self if closed?
+        count = @native.active_leases
+        if count.positive?
+          raise Ingress::IngressError.new("cannot close client while #{count} pooled lease#{'s' unless count == 1} are active", code: :invalid_api_call)
+        end
+        @native.close
+        @closed = true
+        threads = @dispatcher_threads
+        @dispatcher_threads = []
+      end
+      current = Thread.current
+      threads.each { |thread| thread.join unless thread.equal?(current) }
+      self
+    end
+
+    def open
+      raise ArgumentError, "a block is required" unless block_given?
+      begin
+        yield self
+      ensure
+        close
+      end
+    end
+
+    def inspect = "#<#{self.class} closed=#{closed?}>"
+    def initialize_copy(*) = raise(TypeError, "QuestDB clients cannot be copied")
+
+    protected
+
+    def sender_released(_sender)
+      # Native lease accounting is authoritative and survives GC safely.
+      nil
+    end
+
+    private
+
+    def start_dispatcher(kind, handler, inbox)
+      thread = Thread.new(&self.class.send(:dispatcher_proc, WeakRef.new(self), @native, kind, handler, inbox))
+      thread.report_on_exception = false if thread.respond_to?(:report_on_exception=)
+      @dispatcher_threads << thread
+    end
+
+    def counter(method, inbox, ruby_counter = :delivered)
+      @mutex.synchronize do
+        ensure_open!
+        @native.public_send(method) + (inbox&.public_send(ruby_counter) || 0)
+      end
+    end
+
+    def ensure_open!
+      raise Ingress::IngressError.new("client is closed", code: :invalid_api_call) if closed?
+    end
+
+    def validate_handler!(handler, name)
+      return if handler.nil? || handler.respond_to?(:call)
+      raise TypeError, "#{name} must respond to #call"
+    end
+
+    def validate_capacity!(value, name)
+      capacity = Integer(value)
+      raise ArgumentError, "#{name} must be nonnegative" if capacity.negative?
+      capacity
+    rescue ArgumentError, TypeError
+      raise ArgumentError, "#{name} must be a nonnegative integer"
+    end
+
+    def validate_qwp!(conf)
+      return if conf.start_with?("ws::", "wss::")
+      raise Ingress::IngressError.new("QuestDB::Client accepts only ws:: or wss:: QWP configurations", code: :config_error)
+    end
+
+    def parse_auto_flush(settings)
+      enabled = switch(settings.fetch("auto_flush", "on"), "auto_flush")
+      rows = threshold(settings.fetch("auto_flush_rows", "1000"), "auto_flush_rows")
+      interval = threshold(settings.fetch("auto_flush_interval", "100"), "auto_flush_interval")
+      if settings.key?("auto_flush_bytes")
+        bytes = threshold(settings["auto_flush_bytes"], "auto_flush_bytes")
+        dynamic = false
+      else
+        bytes = nil
+        dynamic = true
+      end
+      unless enabled
+        rows = bytes = interval = nil
+        dynamic = false
+      end
+      if enabled && !dynamic && [rows, bytes, interval].none?
+        raise ArgumentError, "auto_flush cannot be enabled when every threshold is off"
+      end
+      { rows: rows, bytes: bytes, interval: interval, dynamic_bytes: dynamic }.freeze
+    end
+
+    def threshold(value, name)
+      return nil if %w[off false].include?(value.to_s)
+      number = Integer(value)
+      raise ArgumentError, "#{name} must be positive or off" unless number.positive?
+      number
+    end
+
+    def switch(value, name)
+      return true if %w[on true].include?(value.to_s)
+      return false if %w[off false].include?(value.to_s)
+      raise ArgumentError, "#{name} must be on or off"
+    end
+  end
+end

data/lib/questdb/column_vector.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+#      ___                  _   ____  ____
+#     / _ \ _   _  ___  ___| |_|  _ \| __ )
+#    | | | | | | |/ _ \/ __| __| | | |  _ \
+#    | |_| | |_| |  __/\__ \ |_| |_| | |_) |
+#     \__\_\\__,_|\___||___/\__|____/|____/
+#
+#   Copyright (c) 2014-2019 Appsicle
+#   Copyright (c) 2019-2026 QuestDB
+#
+#   Licensed under the Apache License, Version 2.0 (the "License");
+#   you may not use this file except in compliance with the License.
+#   You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS,
+#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#   See the License for the specific language governing permissions and
+#   limitations under the License.
+#
+
+module QuestDB
+  # An explicit, immutable type descriptor for direct columnar ingestion.
+  # Use this when an Array is ambiguous (notably an all-nil column) or when a
+  # narrower QuestDB type than the conservative inferred type is required.
+  class ColumnVector
+    KINDS = %i[
+      byte short int long float double boolean varchar binary uuid long256 ipv4
+      timestamp timestamp_nanos date char geohash decimal64 decimal128 decimal256
+      double_array
+    ].freeze
+
+    attr_reader :kind, :values, :scale, :precision_bits, :shape
+
+    def initialize(kind, values, scale: nil, precision_bits: nil, shape: nil)
+      @kind = kind.to_sym
+      raise ArgumentError, "unsupported column kind #{@kind.inspect}" unless KINDS.include?(@kind)
+      raise TypeError, "values must be an Array" unless values.is_a?(Array)
+
+      @values = values.map { |value| immutable_copy(value) }.freeze
+      @scale = scale.nil? ? nil : Integer(scale)
+      @precision_bits = precision_bits.nil? ? nil : Integer(precision_bits)
+      @shape = shape&.map { |dimension| Integer(dimension) }&.freeze
+      validate_metadata!
+      freeze
+    end
+
+    KINDS.each do |kind|
+      define_singleton_method(kind) do |values, **metadata|
+        new(kind, values, **metadata)
+      end
+    end
+
+    private
+
+    def immutable_copy(value)
+      case value
+      when String then value.dup.freeze
+      when Array then value.map { |item| immutable_copy(item) }.freeze
+      else value
+      end
+    end
+
+    def validate_metadata!
+      if %i[decimal64 decimal128 decimal256].include?(kind)
+        raise ArgumentError, "#{kind} requires scale:" if scale.nil?
+        cap = { decimal64: 18, decimal128: 38, decimal256: 76 }.fetch(kind)
+        raise RangeError, "#{kind} scale must be between 0 and #{cap}" unless scale.between?(0, cap)
+      elsif !scale.nil?
+        raise ArgumentError, "scale: is only valid for decimal columns"
+      end
+
+      if kind == :geohash
+        raise ArgumentError, "geohash requires precision_bits:" if precision_bits.nil?
+        raise RangeError, "geohash precision must be between 1 and 60 bits" unless precision_bits.between?(1, 60)
+      elsif !precision_bits.nil?
+        raise ArgumentError, "precision_bits: is only valid for geohash columns"
+      end
+
+      if kind == :double_array
+        raise ArgumentError, "double_array requires shape:" unless shape
+        raise RangeError, "double_array shape must have 1..32 positive dimensions" unless shape.length.between?(1, 32) && shape.all?(&:positive?)
+      elsif shape
+        raise ArgumentError, "shape: is only valid for double_array columns"
+      end
+    end
+  end
+end

data/lib/questdb/config.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+#      ___                  _   ____  ____
+#     / _ \ _   _  ___  ___| |_|  _ \| __ )
+#    | | | | | | |/ _ \/ __| __| | | |  _ \
+#    | |_| | |_| |  __/\__ \ |_| |_| | |_) |
+#     \__\_\\__,_|\___||___/\__|____/|____/
+#
+#   Copyright (c) 2014-2019 Appsicle
+#   Copyright (c) 2019-2026 QuestDB
+#
+#   Licensed under the Apache License, Version 2.0 (the "License");
+#   you may not use this file except in compliance with the License.
+#   You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS,
+#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#   See the License for the specific language governing permissions and
+#   limitations under the License.
+#
+
+module QuestDB
+  module Config
+    WRAPPER_KEYS = %w[auto_flush auto_flush_rows auto_flush_bytes auto_flush_interval].freeze
+    STANDALONE_WRAPPER_KEYS = (WRAPPER_KEYS + %w[init_buf_size]).freeze
+    module_function
+
+    def build(conf = nil, host: nil, port: nil, tls: nil, settings: {})
+      if (conf.nil?) == (host.nil?)
+        raise ArgumentError, "provide either a QWP configuration string or host:, but not both"
+      end
+
+      settings = settings.transform_keys(&:to_sym)
+      settings.each_key do |key|
+        raise ArgumentError, "invalid setting #{key.inspect}" unless key.to_s.match?(/\A[a-z_][a-z0-9_]*\z/)
+      end
+
+      if conf
+        raise ArgumentError, "port: and tls: require host:" unless port.nil? && tls.nil?
+        conf = String(conf)
+        schema, separator, rest = conf.partition("::")
+        raise Ingress::IngressError.new("configuration must start with ws:: or wss::", code: :config_error) unless separator == "::" && %w[ws wss].include?(schema)
+        parts = split_parts(rest)
+        keys = parts.filter_map do |part|
+          key, value = part.split("=", 2)
+          key if value && key.match?(/\A[a-z_][a-z0-9_]*\z/)
+        end
+        duplicate_in_conf = keys.tally.select { |_key, count| count > 1 }.keys
+        unless duplicate_in_conf.empty?
+          raise Ingress::IngressError.new("duplicate configuration keys: #{duplicate_in_conf.join(', ')}", code: :config_error)
+        end
+        values = parse(conf)
+        duplicates = settings.keys.select { |key| values.key?(key.to_s) }
+        raise ArgumentError, "settings already present in configuration: #{duplicates.join(', ')}" unless duplicates.empty?
+        effective = values.merge(settings.to_h { |key, value| [key.to_s, setting_value(value, key)] })
+        native_parts = parts.reject do |part|
+          key, value = part.split("=", 2)
+          value && WRAPPER_KEYS.include?(key)
+        end
+        keyword_parts = settings.reject { |key, _| WRAPPER_KEYS.include?(key.to_s) }
+                                .map { |key, value| "#{key}=#{encode(value, key)};" }.join
+        rebuilt = native_parts.map do |part|
+          key, value = part.split("=", 2)
+          value ? "#{key}=#{encode(value)};" : "#{encode(part)};"
+        end.join
+        ["#{schema}::#{keyword_parts}#{rebuilt}", effective]
+      else
+        host = normalize_host(host)
+        port = port.nil? ? 9000 : Integer(port)
+        raise RangeError, "port must be between 1 and 65535" unless port.between?(1, 65_535)
+        raise TypeError, "tls must be true, false, or nil" unless tls.nil? || tls == true || tls == false
+        schema = tls ? "wss" : "ws"
+        endpoint = "#{host}:#{port}"
+        effective = { "addr" => endpoint }.merge(settings.to_h { |key, value| [key.to_s, setting_value(value, key)] })
+        native = effective.reject { |key, _| WRAPPER_KEYS.include?(key) }
+        built = "#{schema}::#{native.map { |key, value| "#{key}=#{encode(value, key.to_sym)};" }.join}"
+        [built, effective]
+      end
+    end
+
+    def parse(conf)
+      _schema, separator, body = String(conf).partition("::")
+      return {} unless separator == "::"
+      result = {}
+      split_parts(body).each do |part|
+        next if part.empty?
+        key, value = part.split("=", 2)
+        next unless value && key.match?(/\A[a-z_][a-z0-9_]*\z/)
+        result[key] = value
+      end
+      result
+    end
+
+    def split_parts(body)
+      parts = []
+      current = +""
+      index = 0
+      while index < body.length
+        if body.getbyte(index) == 59 # ;
+          if body.getbyte(index + 1) == 59
+            current << ";"
+            index += 2
+          else
+            parts << current
+            current = +""
+            index += 1
+          end
+        else
+          current << body[index]
+          index += 1
+        end
+      end
+      parts << current unless current.empty?
+      parts
+    end
+
+    def setting_value(value, key = nil)
+      if key&.to_sym == :tls_verify && value == false
+        "unsafe_off"
+      elsif value == true
+        "on"
+      elsif value == false
+        "off"
+      else
+        value.to_s
+      end
+    end
+
+    def encode(value, key = nil)
+      value = if key == :tls_verify && value == false
+                "unsafe_off"
+              elsif value == true
+                "on"
+              elsif value == false
+                "off"
+              else
+                value.to_s
+              end
+      raise ArgumentError, "configuration values cannot contain control characters" if value.match?(/[[:cntrl:]]/)
+      value.gsub(";", ";;")
+    end
+
+    def normalize_host(value)
+      host = String(value)
+      raise ArgumentError, "host must not be empty" if host.empty?
+      if host.start_with?("[")
+        raise ArgumentError, "invalid bracketed IPv6 host" unless host.end_with?("]")
+        host
+      elsif host.count(":") >= 2
+        "[#{host}]"
+      elsif host.include?(":")
+        raise ArgumentError, "host must not include a port; use port:"
+      else
+        host
+      end
+    end
+  end
+end

data/lib/questdb/connection_event.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+#      ___                  _   ____  ____
+#     / _ \ _   _  ___  ___| |_|  _ \| __ )
+#    | | | | | | |/ _ \/ __| __| | | |  _ \
+#    | |_| | |_| |  __/\__ \ |_| |_| | |_) |
+#     \__\_\\__,_|\___||___/\__|____/|____/
+#
+#   Copyright (c) 2014-2019 Appsicle
+#   Copyright (c) 2019-2026 QuestDB
+#
+#   Licensed under the Apache License, Version 2.0 (the "License");
+#   you may not use this file except in compliance with the License.
+#   You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS,
+#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#   See the License for the specific language governing permissions and
+#   limitations under the License.
+#
+
+module QuestDB
+  # Immutable snapshot of one pool connection-lifecycle transition.
+  class ConnectionEvent
+    ATTRIBUTES = %i[
+      kind host port previous_host previous_port attempt_number cause_code
+      cause_message timestamp_millis
+    ].freeze
+    attr_reader(*ATTRIBUTES)
+
+    def initialize(kind:, host:, port:, previous_host:, previous_port:, attempt_number:,
+                   cause_code:, cause_message:, timestamp_millis:)
+      @kind = kind.to_sym
+      @host = frozen_string(host)
+      @port = frozen_string(port)
+      @previous_host = frozen_string(previous_host)
+      @previous_port = frozen_string(previous_port)
+      @attempt_number = attempt_number.nil? ? nil : Integer(attempt_number)
+      @cause_code = cause_code&.to_sym
+      @cause_message = frozen_string(cause_message)
+      @timestamp_millis = Integer(timestamp_millis)
+      freeze
+    end
+
+    def self.from_native(values)
+      new(kind: values[0], host: values[1], port: values[2], previous_host: values[3],
+          previous_port: values[4], attempt_number: values[5], cause_code: values[6],
+          cause_message: values[7], timestamp_millis: values[8])
+    end
+
+    private
+
+    def frozen_string(value)
+      value.nil? ? nil : String(value).dup.freeze
+    end
+  end
+end