tricoredb 0.1.0

data/lib/tricoredb/errors.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module TriCoreDB
+  # The code a not-leader refusal carries in `diagnostics.error_code`.
+  NOT_LEADER = "not_leader"
+
+  # Base class for every failure raised by this gem.
+  #
+  # Branch on {#code}, never on the message: the message is prose the server is
+  # free to reword, the code is contract.
+  class Error < StandardError
+    # @return [String, nil] the machine-readable reason, when the server sent one
+    attr_reader :code
+    # @return [String, nil] a `host:port` of the current leader, only alongside `not_leader`
+    attr_reader :leader_hint
+
+    # @param message [String, nil]
+    # @param code [String, nil]
+    # @param leader_hint [String, nil]
+    def initialize(message = nil, code: nil, leader_hint: nil)
+      super(message)
+      @code = code
+      @leader_hint = leader_hint
+    end
+
+    # Whether the request was right but reached a node that is not the leader.
+    #
+    # The driver never follows {#leader_hint} on its own: the address may not be
+    # reachable from this client, a new connection must authenticate again, and
+    # an open session transaction cannot move to another node at all.
+    #
+    # @return [Boolean]
+    def redirect?
+      code == NOT_LEADER
+    end
+  end
+
+  # The server refused the credentials (an AUTH_OK frame with `ok: false`).
+  class AuthError < Error; end
+
+  # The byte stream can no longer be trusted: a bad header, an oversized frame,
+  # an unexpected tag, or a refused handshake. The connection is closed.
+  class ProtocolError < Error; end
+
+  # The socket failed or was closed. The connection is unusable.
+  class ConnectionError < Error; end
+
+  # No reply arrived within the connection's `read_timeout`. The connection is
+  # closed, because the late reply would otherwise be read as the answer to the
+  # next request.
+  class ReadTimeout < ConnectionError; end
+
+  # The server processed the request and did not complete it: a RESPONSE whose
+  # status is not `ok`, or an ERROR frame answering a request.
+  class ServerError < Error
+    # @return [String, nil] `error` or `not_implemented` for a RESPONSE; nil for an ERROR frame
+    attr_reader :status
+    # @return [Response, nil] the full response, for its diagnostics
+    attr_reader :response
+
+    def initialize(message = nil, code: nil, leader_hint: nil, status: nil, response: nil, frame: false)
+      super(message, code: code, leader_hint: leader_hint)
+      @status = status
+      @response = response
+      @frame = frame
+    end
+
+    # @return [Boolean] true when the refusal arrived as an ERROR frame rather than a RESPONSE
+    def frame?
+      @frame
+    end
+  end
+
+  # The server did not grant a capability this call needs. Raised before
+  # anything is sent.
+  class FeatureNotGranted < Error
+    # @return [String] the feature name, e.g. `SERVER_PARAMS`
+    attr_reader :feature
+
+    def initialize(feature, message)
+      super(message)
+      @feature = feature
+    end
+  end
+
+  # A SQL parameter this driver will not encode. Raised before anything is sent.
+  class ParameterError < Error
+    # @return [Integer] the 1-based parameter position
+    attr_reader :index
+
+    def initialize(index, message)
+      super("parameter ##{index}: #{message}")
+      @index = index
+    end
+  end
+
+  # {Pool#with} waited longer than its checkout timeout.
+  class PoolTimeout < Error; end
+end

data/lib/tricoredb/frame.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "json"
+
+module TriCoreDB
+  # The native frame format: `version:u8 | tag:u8 | payload_len:u32be | payload`.
+  module Frame
+    # The frame format version this driver writes.
+    VERSION = 1
+    # The highest frame format version this driver can read.
+    MAX_SUPPORTED_VERSION = 1
+    HEADER_SIZE = 6
+    # Ceiling for REQUEST and RESPONSE payloads.
+    MAX_DATA_PAYLOAD = 16 * 1024 * 1024
+    # Ceiling for every other frame.
+    MAX_CONTROL_PAYLOAD = 64 * 1024
+
+    HELLO = 0
+    AUTH = 1
+    REQUEST = 2
+    RESPONSE = 3
+    PING = 4
+    PONG = 5
+    ERROR = 6
+    CLOSE = 7
+    HELLO_OK = 8
+    AUTH_OK = 9
+    BYE = 10
+    CANCEL = 11
+    CANCEL_OK = 12
+
+    NAMES = {
+      HELLO => "HELLO", AUTH => "AUTH", REQUEST => "REQUEST", RESPONSE => "RESPONSE",
+      PING => "PING", PONG => "PONG", ERROR => "ERROR", CLOSE => "CLOSE",
+      HELLO_OK => "HELLO_OK", AUTH_OK => "AUTH_OK", BYE => "BYE",
+      CANCEL => "CANCEL", CANCEL_OK => "CANCEL_OK"
+    }.freeze
+
+    module_function
+
+    # @param tag [Integer]
+    # @return [Integer] the payload ceiling for that tag; an unknown tag gets the tighter one
+    def max_payload_for(tag)
+      tag == REQUEST || tag == RESPONSE ? MAX_DATA_PAYLOAD : MAX_CONTROL_PAYLOAD
+    end
+
+    # @param tag [Integer]
+    # @return [String]
+    def name(tag)
+      NAMES.fetch(tag) { "tag #{tag}" }
+    end
+
+    # Encode one frame.
+    #
+    # @param tag [Integer]
+    # @param payload [Object, nil] JSON-serialisable; nil sends an empty payload
+    # @return [String] binary frame bytes
+    # @raise [ProtocolError] when the payload exceeds the ceiling for its tag
+    def encode(tag, payload)
+      body = payload.nil? ? "".b : JSON.generate(payload).b
+      limit = max_payload_for(tag)
+      if body.bytesize > limit
+        raise ProtocolError.new(
+          "refusing to send a #{body.bytesize}-byte #{name(tag)} payload; the protocol caps it at #{limit} bytes",
+          code: "frame_too_large"
+        )
+      end
+      [VERSION, tag, body.bytesize].pack("CCN") + body
+    end
+
+    # Decode and validate a six-byte header before any payload byte is read.
+    #
+    # @param header [String] exactly {HEADER_SIZE} bytes
+    # @return [Array(Integer, Integer)] `[tag, payload_length]`
+    # @raise [ProtocolError]
+    def decode_header(header)
+      raise ProtocolError, "short frame header (#{header.bytesize} bytes)" if header.bytesize != HEADER_SIZE
+
+      version, tag, length = header.unpack("CCN")
+      if version > MAX_SUPPORTED_VERSION
+        raise ProtocolError.new(
+          "frame header version #{version} is newer than this driver can read (max #{MAX_SUPPORTED_VERSION})",
+          code: "frame_version"
+        )
+      end
+      limit = max_payload_for(tag)
+      if length > limit
+        raise ProtocolError.new(
+          "#{name(tag)} frame declares a #{length}-byte payload, above the #{limit}-byte limit; refusing to buffer it",
+          code: "frame_too_large"
+        )
+      end
+      [tag, length]
+    end
+
+    # @param body [String]
+    # @return [Object, nil] the parsed JSON, or nil for an empty payload
+    def decode_body(body)
+      return nil if body.empty?
+
+      JSON.parse(body.dup.force_encoding(Encoding::UTF_8))
+    rescue JSON::ParserError => e
+      raise ProtocolError, "frame payload is not valid JSON: #{e.message}"
+    end
+  end
+end

data/lib/tricoredb/params.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "time"
+
+begin
+  require "bigdecimal"
+rescue LoadError
+  # bigdecimal is a bundled gem from Ruby 3.4; without it, BigDecimal values simply cannot occur.
+end
+
+module TriCoreDB
+  # Explicit marker for bytes bound to a BLOB column, whatever the String's encoding.
+  #
+  # @example
+  #   db.execute("INSERT INTO files VALUES (?, ?)", [1, TriCoreDB::Binary.new(File.binread("a.png"))])
+  class Binary
+    # @return [String] the bytes, as a binary (ASCII-8BIT) String
+    attr_reader :bytes
+
+    # @param bytes [String, Array<Integer>]
+    def initialize(bytes)
+      @bytes = bytes.is_a?(Array) ? bytes.pack("C*") : String(bytes).b
+      @bytes.freeze
+    end
+
+    # @return [String] the `0x…` hex text a BLOB column parses
+    def to_param
+      "0x#{@bytes.unpack1('H*')}"
+    end
+
+    def ==(other)
+      other.is_a?(Binary) && other.bytes == bytes
+    end
+    alias eql? ==
+
+    def hash
+      bytes.hash
+    end
+  end
+
+  # @param bytes [String, Array<Integer>]
+  # @return [Binary]
+  def self.binary(bytes)
+    Binary.new(bytes)
+  end
+
+  # Conversion of Ruby values to server-side SQL parameters.
+  #
+  # The wire carries JSON scalars only. The mapping:
+  #
+  # - `nil`, `true`, `false` as themselves
+  # - `Integer` as an exact JSON number, Bignum included (the server refuses anything outside i64 by name)
+  # - `Float` as a JSON number; NaN and infinities are refused
+  # - `String` in **binary encoding (ASCII-8BIT)** as `0x` + hex, for a BLOB column
+  # - any other `String` as UTF-8 text; invalid UTF-8 is refused
+  # - {Binary} as `0x` + hex, whatever the String's encoding was
+  # - `BigDecimal` as plain decimal text with no exponent (`to_s("F")`); non-finite values are refused
+  # - `Time` as ISO-8601 with microseconds; `Date`/`DateTime` as ISO-8601
+  #
+  # Everything else is refused by name rather than sent through `to_s`.
+  module Params
+    module_function
+
+    # @param params [Array]
+    # @return [Array] wire values
+    def encode_all(params)
+      raise ArgumentError, "SQL parameters must be an Array, got #{params.class}" unless params.is_a?(Array)
+
+      params.each_with_index.map { |value, i| encode(value, i + 1) }
+    end
+
+    # @param value [Object]
+    # @param index [Integer] 1-based position, for the error message
+    # @return [nil, true, false, Integer, Float, String]
+    def encode(value, index = 1)
+      case value
+      when nil, true, false, Integer
+        value
+      when Float
+        raise ParameterError.new(index, "#{value} is not a finite number and has no SQL value") unless value.finite?
+
+        value
+      when Binary
+        value.to_param
+      when String
+        encode_string(value, index)
+      when Time
+        value.iso8601(6)
+      else
+        encode_other(value, index)
+      end
+    end
+
+    def encode_string(value, index)
+      return "0x#{value.unpack1('H*')}" if value.encoding == Encoding::BINARY
+
+      text = value.encoding == Encoding::UTF_8 ? value : value.encode(Encoding::UTF_8)
+      raise ParameterError.new(index, "string is not valid UTF-8; mark bytes with TriCoreDB::Binary or String#b") unless text.valid_encoding?
+
+      text
+    rescue EncodingError => e
+      raise ParameterError.new(index, "string cannot be converted to UTF-8 (#{e.message})")
+    end
+
+    def encode_other(value, index)
+      if defined?(::BigDecimal) && value.is_a?(::BigDecimal)
+        raise ParameterError.new(index, "BigDecimal #{value} is not finite and has no SQL value") unless value.finite?
+
+        return value.to_s("F")
+      end
+      return value.iso8601 if defined?(::Date) && value.is_a?(::Date)
+
+      raise ParameterError.new(
+        index,
+        "no SQL parameter form for #{value.class}. Convert it explicitly (a String, Integer, Float, " \
+        "BigDecimal, Time, TriCoreDB::Binary, true/false or nil)"
+      )
+    end
+    private_class_method :encode_string, :encode_other
+  end
+end

data/lib/tricoredb/pool.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module TriCoreDB
+  # A thread-safe pool of connections.
+  #
+  # A connection is lent to exactly one block at a time. Connections are
+  # created lazily up to `size`.
+  #
+  # A session transaction is bound to its connection, so a connection is never
+  # returned mid-transaction: a block that raises with one open has it rolled
+  # back, and a block that returns with one open has it rolled back and raises.
+  #
+  # @example
+  #   pool = TriCoreDB::Pool.new(size: 8, host: "db", port: 8427, user: "app", secret: ENV["TRICORE_SECRET"])
+  #   pool.with { |db| db.query("SELECT 1") }
+  #   pool.close
+  class Pool
+    # @return [Integer]
+    attr_reader :size
+
+    # @param size [Integer] maximum connections
+    # @param checkout_timeout [Numeric] seconds {#with} waits for a free connection
+    # @param connect_options [Hash] passed to {Client.connect}, `tls:` included
+    def initialize(size: 8, checkout_timeout: 10, **connect_options)
+      raise ArgumentError, "pool size must be >= 1" if size < 1
+
+      @size = size
+      @checkout_timeout = checkout_timeout
+      @connect_options = connect_options
+      @idle = []
+      @created = 0
+      @waiting = 0
+      @closed = false
+      @lock = Mutex.new
+      @available = ConditionVariable.new
+    end
+
+    # Borrow a connection for the duration of the block.
+    #
+    # @yieldparam db [Client]
+    # @return [Object] the block's value
+    # @raise [PoolTimeout] when none frees up within the timeout
+    def with(timeout: @checkout_timeout)
+      raise ArgumentError, "Pool#with needs a block" unless block_given?
+
+      client = checkout(timeout)
+      broken = false
+      begin
+        begin
+          result = yield client
+        rescue Exception => e # rubocop:disable Lint/RescueException
+          if client.closed? || stream_broken?(e)
+            broken = true
+          elsif client.in_transaction?
+            broken = !abandon_transaction(client)
+          end
+          raise
+        end
+        if client.in_transaction?
+          broken = !abandon_transaction(client)
+          raise Error, "the block returned with a session transaction still open on the pooled connection; it " \
+                       "has been rolled back rather than returned to the pool. Commit or roll back inside the " \
+                       "block, or use db.transaction { }"
+        end
+        result
+      ensure
+        checkin(client, broken)
+      end
+    end
+
+    # @return [Hash{Symbol => Integer}]
+    def stats
+      @lock.synchronize do
+        { size: @size, created: @created, idle: @idle.size, in_use: @created - @idle.size, waiting: @waiting }
+      end
+    end
+
+    # Close idle connections and refuse further checkouts. Connections in use are
+    # closed when they are returned.
+    def close
+      idle = @lock.synchronize do
+        @closed = true
+        @available.broadcast
+        list = @idle.dup
+        @idle.clear
+        @created -= list.size
+        list
+      end
+      idle.each(&:close)
+      nil
+    end
+
+    private
+
+    def stream_broken?(error)
+      case error
+      when ConnectionError, ProtocolError then true
+      when ServerError then error.frame?
+      else false
+      end
+    end
+
+    def abandon_transaction(client)
+      client.rollback
+      true
+    rescue StandardError
+      false
+    end
+
+    def checkout(timeout)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+      @lock.synchronize do
+        loop do
+          raise Error, "pool is closed" if @closed
+
+          return @idle.pop unless @idle.empty?
+
+          if @created < @size
+            @created += 1
+            break
+          end
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          raise PoolTimeout, "no pooled connection available within #{timeout}s (size=#{@size})" if remaining <= 0
+
+          @waiting += 1
+          begin
+            @available.wait(@lock, remaining)
+          ensure
+            @waiting -= 1
+          end
+        end
+      end
+      begin
+        Client.connect(**@connect_options)
+      rescue Exception # rubocop:disable Lint/RescueException
+        @lock.synchronize do
+          @created -= 1
+          @available.signal
+        end
+        raise
+      end
+    end
+
+    def checkin(client, broken)
+      discard = @lock.synchronize do
+        if broken || @closed || client.closed? || client.in_transaction?
+          @created -= 1
+          @available.signal
+          true
+        else
+          @idle.push(client)
+          @available.signal
+          false
+        end
+      end
+      client.close if discard
+    end
+  end
+end

data/lib/tricoredb/response.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "json"
+
+module TriCoreDB
+  # A SQL result set. Every cell is the server's text rendering of the value.
+  class Rows
+    include Enumerable
+
+    # @return [Array<String>]
+    attr_reader :columns
+    # @return [Array<Array<String, nil>>]
+    attr_reader :rows
+
+    def initialize(columns, rows)
+      @columns = columns
+      @rows = rows
+    end
+
+    def each(&block)
+      return enum_for(:each) unless block
+
+      @rows.each(&block)
+    end
+
+    # @return [Integer]
+    def size
+      @rows.size
+    end
+    alias length size
+
+    # @return [Array<Hash{String => String}>] rows keyed by column name
+    def to_hashes
+      @rows.map { |r| @columns.zip(r).to_h }
+    end
+  end
+
+  # One entry of a cache stream.
+  StreamEntry = Struct.new(:id, :fields) do
+    # @return [Hash{String => String}] fields decoded as UTF-8, for the all-text case
+    def text
+      fields.to_h { |f, v| [f.dup.force_encoding(Encoding::UTF_8), v.dup.force_encoding(Encoding::UTF_8)] }
+    end
+  end
+
+  # A server RESPONSE: typed data plus how it was produced.
+  class Response
+    # @return [String]
+    attr_reader :request_id
+    # @return [String] `ok`, `error` or `not_implemented`
+    attr_reader :status
+    # @return [Object] the externally tagged ResponseData (`"Empty"`, `{"Json" => ...}`, ...)
+    attr_reader :data
+    # @return [Hash]
+    attr_reader :diagnostics
+
+    # @param raw [Hash] the decoded RESPONSE payload
+    def initialize(raw)
+      raw = {} unless raw.is_a?(Hash)
+      @request_id = raw["request_id"].to_s
+      @status = raw["status"] || "error"
+      @data = raw["data"]
+      @diagnostics = raw["diagnostics"].is_a?(Hash) ? raw["diagnostics"] : {}
+    end
+
+    def ok?
+      @status == "ok"
+    end
+
+    # @return [Array<String>] non-fatal warnings; a partially applied broadcast reports here while still `ok`
+    def warnings
+      @diagnostics["warnings"] || []
+    end
+
+    # @return [String, nil]
+    def error_code
+      @diagnostics["error_code"]
+    end
+
+    # @return [String, nil]
+    def leader_hint
+      @diagnostics["leader_hint"]
+    end
+
+    def redirect?
+      error_code == NOT_LEADER
+    end
+
+    # @return [Integer, nil] `rows_affected` from a SQL write, when the server reported it
+    def rows_affected
+      json = arm("Json")
+      json.is_a?(Hash) && json["rows_affected"].is_a?(Integer) ? json["rows_affected"] : nil
+    end
+
+    # Whether the data carries the named arm (`Json`, `Rows`, ...). A `null` value still counts.
+    def arm?(name)
+      @data.is_a?(Hash) && @data.key?(name)
+    end
+
+    # @return [Object, nil]
+    def arm(name)
+      @data.is_a?(Hash) ? @data[name] : nil
+    end
+
+    # @return [String] the kind of data, for messages
+    def kind
+      @data.is_a?(Hash) ? (@data.keys.first || "{}") : @data.inspect
+    end
+
+    # Build the error for a response that is not `ok`.
+    #
+    # @param txn_open [Boolean] whether a session transaction was open on the connection
+    # @return [ServerError]
+    def to_error(txn_open = false)
+      text = arm("Message") || (arm?("Json") ? JSON.generate(arm("Json")) : nil) || "request failed"
+      message = "#{text} (server status: #{@status})"
+      if redirect?
+        message += if leader_hint
+                     " [not_leader: the leader serves clients at `#{leader_hint}`. This driver does not follow " \
+                     "the hint on its own; send the request there."
+                   else
+                     " [not_leader: there is no leader address to name (an election is in progress, or the " \
+                     "leader has no address configured). Wait and try again."
+                   end
+        message += " The open session transaction is over: it cannot continue on another node." if txn_open
+        message += "]"
+      end
+      ServerError.new(message, code: error_code, leader_hint: leader_hint, status: @status, response: self)
+    end
+  end
+end