questdb 0.1.0-aarch64-linux-gnu

data/lib/questdb/sender.rb

@@ -0,0 +1,436 @@
+# 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 "weakref"
+
+module QuestDB
+  # A connection-level QWP/WebSocket sender. Prefer Client#sender for pooled
+  # production ingestion; standalone senders are useful for manual progress
+  # and explicit buffer control.
+  class Sender
+    PROTOCOLS = %i[ws wss].freeze
+    ACK_LEVELS = { ok: 0, durable: 1 }.freeze
+    EMPTY_HASH = {}.freeze
+    private_constant :EMPTY_HASH
+
+    attr_reader :protocol, :init_buf_size, :auto_flush_rows, :auto_flush_bytes, :auto_flush_interval
+
+    def initialize(protocol:, host:, port: nil, connection_listener: nil, error_handler: nil,
+                   connection_event_inbox_capacity: 64, error_event_inbox_capacity: 64, **settings)
+      @protocol = protocol.to_sym
+      raise ArgumentError, "protocol must be :ws or :wss" unless PROTOCOLS.include?(@protocol)
+      host = Config.normalize_host(host)
+      port = Integer(port || 9000)
+      raise RangeError, "port must be between 1 and 65535" unless port.between?(1, 65_535)
+      validate_setting_keys!(settings)
+      effective = { "addr" => "#{host}:#{port}" }.merge(
+        settings.to_h { |key, value| [key.to_s, Config.setting_value(value, key)] }
+      )
+      native = effective.reject { |key, _| Config::STANDALONE_WRAPPER_KEYS.include?(key) }
+      @configuration = "#{@protocol}::#{native.map { |key, value| "#{key}=#{Config.encode(value, key.to_sym)};" }.join}".freeze
+      setup_wrapper(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_conf(conf, connection_listener: nil, error_handler: nil,
+                       connection_event_inbox_capacity: 64, error_event_inbox_capacity: 64, **overrides)
+      configuration, effective, protocol = merge_conf(conf, overrides)
+      object = allocate
+      object.send(:initialize_from_conf, configuration, effective, protocol,
+                  connection_listener: connection_listener, error_handler: error_handler,
+                  connection_event_inbox_capacity: connection_event_inbox_capacity,
+                  error_event_inbox_capacity: error_event_inbox_capacity)
+      object
+    end
+
+    def self.from_env(**overrides)
+      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, **overrides)
+    end
+
+    def establish
+      ensure_thread!
+      raise Ingress::IngressError.new("standalone sender is closed", code: :invalid_api_call) if @closed
+      return self if @native
+      @native = Ingress::Native::StandaloneSender.new(
+        @configuration, !@connection_listener.nil?, @connection_event_inbox_capacity,
+        !@error_handler.nil?, @error_event_inbox_capacity
+      )
+      @buffer = Ingress::Buffer.send(:from_native, @native.new_buffer(@init_buf_size))
+      @batch_started = nil
+      start_dispatcher(:connection, @connection_listener, @connection_inbox) if @connection_listener
+      start_dispatcher(:error, @error_handler, @error_inbox) if @error_handler
+      self
+    end
+
+    def open
+      raise ArgumentError, "a block is required" unless block_given?
+      establish
+      begin
+        result = yield self
+        close
+        result
+      rescue Exception
+        close(flush: false, drain: false)
+        raise
+      end
+    end
+
+    def new_buffer
+      ensure_open!
+      Ingress::Buffer.send(:from_native, @native.new_buffer(@init_buf_size))
+    end
+
+    def row(table, symbols: EMPTY_HASH, columns: EMPTY_HASH, at:)
+      ensure_open!
+      appended = @buffer.__send__(:append, table, symbols, columns, at)
+      return self unless appended
+      @batch_started ||= monotonic
+      flush if should_auto_flush?
+      self
+    end
+
+    # One-off poolless direct columnar load using this sender's auth/TLS
+    # configuration. It uses a separate connection and has no ordering
+    # relationship with the buffered row stream.
+    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
+      )
+      ensure_ws!
+      return self if prepared[4].zero?
+      @native.ingest_columns(@configuration, *prepared)
+      self
+    end
+    alias write_columns ingest_columns
+
+    def row_count = (@buffer&.row_count || 0)
+    alias length row_count
+    def empty? = row_count.zero?
+    def closed? = @closed || (@native && @native.closed?)
+    def established? = !@native.nil? && !closed?
+    def auto_flush? = @auto_flush_enabled
+    alias auto_flush auto_flush?
+
+    def flush(buffer: nil, clear: true, wait: false, ack: :ok)
+      ensure_open!
+      target = buffer || @buffer
+      raise TypeError, "buffer must be a QuestDB QWP buffer" unless target.is_a?(Ingress::Buffer)
+      raise ArgumentError, "clear: false requires an explicit buffer" if target.equal?(@buffer) && !clear
+      level = normalize_ack(ack)
+      raise ArgumentError, "ack: :durable requires wait: true" if level == ACK_LEVELS[:durable] && !wait
+      return self if target.empty? && !wait
+      @native.flush(target.send(:native), !clear)
+      @native.wait(level, 0) if wait
+      @batch_started = nil if target.equal?(@buffer) && target.empty?
+      self
+    end
+
+    def wait(timeout_millis: 0, ack: :ok)
+      ensure_ws!
+      @native.wait(normalize_ack(ack), non_negative_integer(timeout_millis, "timeout_millis"))
+      self
+    end
+
+    def flush_and_get_fsn
+      ensure_ws!
+      value = @native.flush_fsn(@buffer.send(:native), false)
+      @batch_started = nil if @buffer.empty?
+      value
+    end
+
+    def flush_and_keep_and_get_fsn(buffer = nil)
+      ensure_ws!
+      target = buffer || @buffer
+      @native.flush_fsn(target.send(:native), true)
+    end
+
+    def published_fsn = (ensure_ws!; @native.published_fsn)
+    def acked_fsn = (ensure_ws!; @native.acked_fsn)
+
+    def await_acked_fsn(fsn, timeout_millis: 0)
+      ensure_ws!
+      target = non_negative_integer(fsn, "fsn")
+      current = @native.acked_fsn
+      return true if current && current >= target
+      begin
+        @native.wait(ACK_LEVELS[:ok], non_negative_integer(timeout_millis, "timeout_millis"))
+      rescue Ingress::IngressError => error
+        raise unless error.code == :failover_retry
+      end
+      current = @native.acked_fsn
+      !!(current && current >= target)
+    end
+
+    def drive_once = (ensure_ws!; @native.drive_once)
+
+    def close_drain
+      ensure_ws!
+      @native.close_drain
+      self
+    end
+
+    def poll_error
+      ensure_ws!
+      values = @native.poll_error
+      values && SenderError.from_native(values)
+    end
+
+    def poll_connection_event = @connection_inbox&.poll
+    def poll_callback_error = @error_inbox&.poll
+
+    def error_events_delivered
+      ensure_ws!
+      @native.error_events_delivered + (@error_inbox&.delivered || 0)
+    end
+
+    def error_events_dropped
+      ensure_ws!
+      @native.error_events_dropped + (@error_inbox&.dropped || 0)
+    end
+
+    def connection_events_delivered
+      ensure_open!
+      @native.connection_events_delivered + (@connection_inbox&.delivered || 0)
+    end
+
+    def connection_events_dropped
+      ensure_open!
+      @native.connection_events_dropped + (@connection_inbox&.dropped || 0)
+    end
+
+    def close(flush: true, wait: false, drain: nil)
+      return self if @closed
+      ensure_thread!
+      drain = flush if drain.nil?
+      begin
+        if @native && flush && @buffer && !@buffer.empty?
+          self.flush(wait: wait)
+        elsif @native && wait
+          self.wait
+        end
+      ensure
+        primary = $!
+        @buffer&.clear
+        begin
+          @native&.close(!!drain)
+        rescue Exception
+          raise unless primary
+        ensure
+          @closed = true
+          threads = @dispatcher_threads
+          @dispatcher_threads = []
+          current = Thread.current
+          threads.each { |thread| thread.join unless thread.equal?(current) }
+        end
+      end
+      self
+    end
+
+    def initialize_copy(*) = raise(TypeError, "QuestDB standalone senders cannot be copied")
+
+    class << self
+      private
+
+      def 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-standalone-#{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
+              Kernel.warn("QuestDB standalone #{kind} callback failed: #{error.class}: #{error.message}")
+            end
+          end
+        end
+      end
+
+      def merge_conf(conf, overrides)
+        conf = String(conf)
+        schema, separator, rest = conf.partition("::")
+        protocol = schema.to_sym
+        unless separator == "::" && PROTOCOLS.include?(protocol)
+          raise Ingress::IngressError.new("configuration must start with ws:: or wss::", code: :config_error)
+        end
+        overrides = overrides.transform_keys(&:to_sym)
+        overrides.each_key do |key|
+          raise ArgumentError, "invalid setting #{key.inspect}" unless key.to_s.match?(/\A[a-z_][a-z0-9_]*\z/)
+        end
+        parts = Config.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
+        duplicates = keys.tally.select { |_key, count| count > 1 }.keys
+        unless duplicates.empty?
+          raise Ingress::IngressError.new("duplicate configuration keys: #{duplicates.join(', ')}", code: :config_error)
+        end
+        values = Config.parse(conf)
+        conflicts = overrides.keys.select { |key| values.key?(key.to_s) }
+        raise ArgumentError, "settings already present in configuration: #{conflicts.join(', ')}" unless conflicts.empty?
+        effective = values.merge(overrides.to_h { |key, value| [key.to_s, Config.setting_value(value, key)] })
+        native_parts = parts.reject { |part| Config::STANDALONE_WRAPPER_KEYS.include?(part.split("=", 2).first) }
+        keyword_parts = overrides.reject { |key, _| Config::STANDALONE_WRAPPER_KEYS.include?(key.to_s) }
+                                 .map { |key, value| "#{key}=#{Config.encode(value, key)};" }.join
+        rebuilt = native_parts.map do |part|
+          key, value = part.split("=", 2)
+          value ? "#{key}=#{Config.encode(value)};" : "#{Config.encode(part)};"
+        end.join
+        ["#{schema}::#{keyword_parts}#{rebuilt}".freeze, effective, protocol]
+      end
+    end
+
+    private
+
+    def initialize_from_conf(configuration, effective, protocol, connection_listener:, error_handler:,
+                             connection_event_inbox_capacity:, error_event_inbox_capacity:)
+      @configuration = configuration
+      @protocol = protocol
+      setup_wrapper(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 setup_wrapper(settings, connection_listener:, error_handler:,
+                      connection_event_inbox_capacity:, error_event_inbox_capacity:)
+      @owner_thread = Thread.current
+      validate_handler!(connection_listener, "connection_listener")
+      validate_handler!(error_handler, "error_handler")
+      @connection_event_inbox_capacity = validate_capacity!(connection_event_inbox_capacity, "connection_event_inbox_capacity")
+      @error_event_inbox_capacity = validate_capacity!(error_event_inbox_capacity, "error_event_inbox_capacity")
+      @connection_listener = connection_listener
+      @error_handler = error_handler
+      @connection_inbox = connection_listener && EventInbox.new(@connection_event_inbox_capacity)
+      @error_inbox = error_handler && EventInbox.new(@error_event_inbox_capacity)
+      @dispatcher_threads = []
+      @native = @buffer = nil
+      @closed = false
+      @init_buf_size = Integer(settings.fetch("init_buf_size", 65_536))
+      raise ArgumentError, "init_buf_size must be nonnegative" if @init_buf_size.negative?
+      raise RangeError, "init_buf_size exceeds 100 MiB" if @init_buf_size > Ingress::Buffer::MAX_PREALLOCATE_BYTES
+      @auto_flush_rows = threshold(settings.fetch("auto_flush_rows", 600), "auto_flush_rows")
+      @auto_flush_bytes = settings.key?("auto_flush_bytes") ? threshold(settings["auto_flush_bytes"], "auto_flush_bytes") : nil
+      @auto_flush_interval = threshold(settings.fetch("auto_flush_interval", 1_000), "auto_flush_interval")
+      enabled = if settings.key?("auto_flush")
+                  switch(settings["auto_flush"], "auto_flush")
+                else
+                  [@auto_flush_rows, @auto_flush_bytes, @auto_flush_interval].any?
+                end
+      unless enabled
+        @auto_flush_rows = @auto_flush_bytes = @auto_flush_interval = nil
+      end
+      if enabled && [@auto_flush_rows, @auto_flush_bytes, @auto_flush_interval].none?
+        raise ArgumentError, "auto_flush cannot be enabled when every threshold is off"
+      end
+      @auto_flush_enabled = enabled
+      @batch_started = nil
+    end
+
+    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 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 ensure_thread!
+      return if Thread.current.equal?(@owner_thread)
+      raise Ingress::IngressError.new("standalone sender must be used on its creating thread", code: :invalid_api_call)
+    end
+
+    def ensure_open!
+      ensure_thread!
+      raise Ingress::IngressError.new("standalone sender is not established", code: :invalid_api_call) unless established?
+    end
+
+    def ensure_ws!
+      ensure_open!
+      true
+    end
+
+    def normalize_ack(value)
+      value = value.to_sym if value.respond_to?(:to_sym)
+      ACK_LEVELS.fetch(value) { raise ArgumentError, "ack must be :ok or :durable" }
+    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
+
+    def validate_setting_keys!(settings)
+      settings.each_key do |key|
+        raise ArgumentError, "invalid setting #{key.inspect}" unless key.to_s.match?(/\A[a-z_][a-z0-9_]*\z/)
+      end
+    end
+
+    def non_negative_integer(value, name)
+      value = Integer(value)
+      raise ArgumentError, "#{name} must be nonnegative" if value.negative?
+      value
+    end
+
+    def should_auto_flush?
+      return false unless @batch_started
+      return true if @auto_flush_rows && row_count >= @auto_flush_rows
+      return true if @auto_flush_bytes && @buffer.bytesize >= @auto_flush_bytes
+      @auto_flush_interval && monotonic - @batch_started >= @auto_flush_interval
+    end
+
+    def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
+  end
+end

data/lib/questdb/sender_error.rb

@@ -0,0 +1,49 @@
+# 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
+  class SenderError
+    ATTRIBUTES = %i[category applied_policy status message message_sequence from_fsn to_fsn].freeze
+    attr_reader(*ATTRIBUTES)
+
+    def initialize(category:, applied_policy:, status:, message:, message_sequence:, from_fsn:, to_fsn:)
+      @category = category.to_sym
+      @applied_policy = applied_policy.to_sym
+      @status = status
+      @message = String(message).dup.freeze
+      @message_sequence = message_sequence
+      @from_fsn = Integer(from_fsn)
+      @to_fsn = Integer(to_fsn)
+      freeze
+    end
+
+    def terminal? = applied_policy == :terminal
+    def retriable? = %i[retriable retriable_other].include?(applied_policy)
+
+    def self.from_native(values)
+      new(category: values[0], applied_policy: values[1], status: values[2],
+          message: values[3], message_sequence: values[4], from_fsn: values[5], to_fsn: values[6])
+    end
+  end
+end

data/lib/questdb/types.rb

@@ -0,0 +1,198 @@
+# 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 "ipaddr"
+
+module QuestDB
+  class DateMillis
+    attr_reader :value
+    def initialize(value)
+      @value = Integer(value)
+      raise RangeError, "date milliseconds are outside signed 64-bit range" unless @value.between?(-(1 << 63), (1 << 63) - 1)
+      freeze
+    end
+    def to_time = Time.at(Rational(value, 1_000)).utc
+    def ==(other) = other.is_a?(DateMillis) && value == other.value
+  end
+
+  class Char
+    attr_reader :value
+    def initialize(value)
+      value = value.ord if value.is_a?(String) && value.length == 1
+      @value = Integer(value)
+      raise RangeError, "CHAR must be one UTF-16 code unit" unless @value.between?(0, 0xffff)
+      freeze
+    end
+    def to_s
+      return "\uFFFD" if value.between?(0xd800, 0xdfff)
+      [value].pack("U")
+    end
+    def ==(other) = other.is_a?(Char) && value == other.value
+  end
+
+  class UUID
+    PATTERN = /\A([0-9a-fA-F]{8})-([0-9a-fA-F]{4})-([0-9a-fA-F]{4})-([0-9a-fA-F]{4})-([0-9a-fA-F]{12})\z/
+    attr_reader :bytes
+    def initialize(value)
+      if value.is_a?(UUID)
+        @bytes = value.bytes
+      else
+        match = PATTERN.match(String(value)) or raise ArgumentError, "invalid UUID"
+        @bytes = match.captures.join.then { |hex| [hex].pack("H*") }.freeze
+      end
+      freeze
+    end
+    def self.from_bytes(value)
+      bytes = String(value).b
+      raise ArgumentError, "UUID requires exactly 16 bytes" unless bytes.bytesize == 16
+      allocate.tap { |uuid| uuid.instance_variable_set(:@bytes, bytes.dup.freeze); uuid.freeze }
+    end
+    def to_s
+      hex = bytes.unpack1("H*")
+      "#{hex[0, 8]}-#{hex[8, 4]}-#{hex[12, 4]}-#{hex[16, 4]}-#{hex[20, 12]}"
+    end
+    alias inspect to_s
+    def ==(other) = other.is_a?(UUID) && bytes == other.bytes
+  end
+
+  class Binary
+    attr_reader :bytes
+    def initialize(bytes)
+      @bytes = String(bytes).b.dup.freeze
+      freeze
+    end
+    def ==(other) = other.is_a?(Binary) && bytes == other.bytes
+  end
+
+  class IPv4
+    attr_reader :value
+    def initialize(value)
+      @value = case value
+               when IPv4 then value.value
+               when IPAddr
+                 raise ArgumentError, "IPv4 value must not be IPv6" unless value.ipv4?
+                 value.to_i
+               when String
+                 address = IPAddr.new(value)
+                 raise ArgumentError, "IPv4 value must not be IPv6" unless address.ipv4?
+                 address.to_i
+               else Integer(value)
+               end
+      raise RangeError, "IPv4 value must fit unsigned 32-bit" unless @value.between?(0, 0xffff_ffff)
+      freeze
+    end
+    def to_s = [24, 16, 8, 0].map { |shift| (value >> shift) & 0xff }.join(".")
+    def to_ipaddr = IPAddr.new(value, Socket::AF_INET)
+    def ==(other) = other.is_a?(IPv4) && value == other.value
+  end
+
+  class Geohash
+    attr_reader :value, :precision_bits
+    def self.from_native(value, precision_bits) = new(value, precision_bits: precision_bits)
+    def initialize(value, precision_bits:)
+      @value = Integer(value)
+      @precision_bits = Integer(precision_bits)
+      raise RangeError, "geohash precision must be between 1 and 60 bits" unless @precision_bits.between?(1, 60)
+      raise RangeError, "geohash value exceeds its precision" unless @value.between?(0, (1 << @precision_bits) - 1)
+      freeze
+    end
+    def ==(other) = other.is_a?(Geohash) && value == other.value && precision_bits == other.precision_bits
+  end
+
+  class Long256
+    LIMIT = 1 << 256
+    attr_reader :value
+    def initialize(value)
+      @value = Integer(value)
+      raise RangeError, "LONG256 must be between 0 and 2^256-1" unless @value.between?(0, LIMIT - 1)
+      freeze
+    end
+    def bytes = [value.to_s(16).rjust(64, "0")].pack("H*").reverse
+    def self.from_bytes(bytes)
+      bytes = String(bytes).b
+      raise ArgumentError, "LONG256 requires 32 bytes" unless bytes.bytesize == 32
+      new(bytes.reverse.unpack1("H*").to_i(16))
+    end
+    def ==(other) = other.is_a?(Long256) && value == other.value
+  end
+
+  class DecimalValue
+    attr_reader :mantissa, :scale
+    def self.from_native(mantissa, scale) = new(mantissa, scale: scale)
+    def initialize(mantissa, scale:)
+      @mantissa = Integer(mantissa)
+      @scale = Integer(scale)
+      raise RangeError, "decimal scale must fit signed 8-bit" unless @scale.between?(-128, 127)
+      freeze
+    end
+    def self.from_bigdecimal(value)
+      sign, digits, _base, exponent = value.split
+      mantissa = (sign < 0 ? -1 : 1) * digits.to_i
+      scale = digits.length - exponent
+      while scale.positive? && (mantissa % 10).zero?
+        mantissa /= 10
+        scale -= 1
+      end
+      new(mantissa, scale: scale)
+    end
+    def self.from_twos_complement(bytes, scale)
+      bytes = String(bytes).b
+      bits = bytes.bytesize * 8
+      unsigned = bytes.reverse.unpack1("H*").to_i(16)
+      unsigned -= 1 << bits if (unsigned & (1 << (bits - 1))) != 0
+      new(unsigned, scale: scale)
+    end
+    def to_d = BigDecimal(mantissa) * (BigDecimal(10) ** -scale)
+    def to_s = to_d.to_s("F")
+    def ==(other) = other.is_a?(DecimalValue) && mantissa == other.mantissa && scale == other.scale
+  end
+
+  class TypedNull
+    KINDS = %i[boolean byte short int long float double symbol timestamp date uuid long256 geohash varchar timestamp_nanos decimal64 decimal128 decimal256 char binary ipv4].freeze
+    attr_reader :kind, :scale, :precision_bits
+    def initialize(kind, scale: nil, precision_bits: nil)
+      @kind = kind.to_sym
+      raise ArgumentError, "unsupported typed NULL kind #{@kind.inspect}" unless KINDS.include?(@kind)
+      @scale = scale.nil? ? nil : Integer(scale)
+      @precision_bits = precision_bits.nil? ? nil : Integer(precision_bits)
+      if %i[decimal64 decimal128 decimal256].include?(@kind)
+        @scale ||= 0
+        raise RangeError, "decimal scale must fit signed 8-bit" unless @scale.between?(-128, 127)
+      end
+      if @kind == :geohash
+        raise ArgumentError, "geohash NULL requires precision_bits:" unless @precision_bits
+        raise RangeError, "geohash precision must be between 1 and 60 bits" unless @precision_bits.between?(1, 60)
+      end
+      freeze
+    end
+  end
+
+  class OpaqueValue
+    attr_reader :kind, :bytes
+    def initialize(kind, bytes = nil)
+      @kind = kind
+      @bytes = bytes&.b&.dup&.freeze
+      freeze
+    end
+  end
+end