nusadb 0.1.0

data/lib/nusadb/protocol.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+module NusaDB
+  # Low-level Nusa Wire Protocol codec (docs/wire-protocol.md, PROTOCOL_VERSION 1.1).
+  #
+  # A frame is [type:u8][len:u32][payload]; len is the total including the 5-byte header.
+  # Big-endian throughout; strings are [len:u32][utf8 bytes], not null-terminated.
+  module Protocol
+    MAGIC = 0x4E55_5341 # "NUSA"
+    MAJOR = 1
+    # Request minor 1 to receive the typed RowDescription (per-column type tags). A 1.0 server
+    # ignores it and answers with the classic untyped form, which the driver still handles.
+    MINOR = 1
+    HEADER_LEN = 5
+    MAX_FRAME_LEN = 256 * 1024 * 1024
+    SCRAM_MECHANISM = 'SCRAM-SHA-256'
+
+    # Frontend type bytes.
+    T_STARTUP = 'S'.ord
+    T_QUERY = 'Q'.ord
+    T_PARSE = 'P'.ord
+    T_BIND = 'B'.ord
+    T_DESCRIBE = 'D'.ord
+    T_EXECUTE = 'E'.ord
+    T_SYNC = 'Y'.ord
+    T_SASL_INITIAL = 'p'.ord
+    T_SASL_RESPONSE = 'r'.ord
+    T_TERMINATE = 'X'.ord
+    T_COPY_DATA = 'd'.ord # COPY ... FROM STDIN data chunk (§12.1)
+    T_COPY_DONE = 'c'.ord # end of the client's COPY data stream
+    T_COPY_FAIL = 'f'.ord # abort the in-progress COPY: [message:Str]
+
+    # Backend type bytes.
+    B_AUTH = 'R'.ord
+    B_BACKEND_KEY = 'K'.ord
+    B_READY = 'Z'.ord
+    B_COMMAND_COMPLETE = 'C'.ord
+    B_ERROR = 'E'.ord
+    B_ROW_DESCRIPTION = 'T'.ord
+    B_ROW_DESCRIPTION_TYPED = 'y'.ord # protocol 1.1 (typed columns)
+    B_DATA_ROW = 'D'.ord
+    B_COPY_IN = 'G'.ord   # CopyInResponse (§12.1)
+    B_COPY_OUT = 'H'.ord  # CopyOutResponse (§12.2)
+    B_COPY_DATA = 'd'.ord # a COPY data chunk
+    B_COPY_DONE = 'c'.ord # end of the COPY data stream
+    B_NOTIFICATION = 'A'.ord # async LISTEN/NOTIFY: [pid:u32][channel:str][payload:str]
+
+    # Column type tags carried by RowDescriptionTyped (protocol 1.1, wire-protocol.md §9.2). Maps the
+    # 1-byte tag to a canonical type name; an unknown/0x00 tag is UNKNOWN (treated as text).
+    TYPE_TAGS = {
+      0x00 => 'UNKNOWN', 0x01 => 'BOOL', 0x02 => 'INT', 0x03 => 'FLOAT', 0x04 => 'NUMERIC',
+      0x05 => 'TEXT', 0x06 => 'BYTES', 0x07 => 'DATE', 0x08 => 'TIME', 0x09 => 'TIMETZ',
+      0x0A => 'TIMESTAMP', 0x0B => 'TIMESTAMPTZ', 0x0C => 'INTERVAL', 0x0D => 'UUID',
+      0x0E => 'JSON', 0x0F => 'ARRAY', 0x10 => 'VECTOR'
+    }.freeze
+
+    # Canonical type name for a RowDescriptionTyped type tag (UNKNOWN if unrecognised).
+    def self.type_name(tag)
+      TYPE_TAGS.fetch(tag, 'UNKNOWN')
+    end
+
+    # Auth sub-codes.
+    AUTH_OK = 0
+    AUTH_SASL = 10
+    AUTH_SASL_CONTINUE = 11
+    AUTH_SASL_FINAL = 12
+
+    module_function
+
+    def u16(value)
+      [value].pack('n')
+    end
+
+    def u32(value)
+      [value].pack('N')
+    end
+
+    def str(value)
+      bytes = value.to_s.dup.force_encoding(Encoding::BINARY)
+      u32(bytes.bytesize) + bytes
+    end
+
+    # Encode a Fields list: [count:u16] then per field present byte + optional [len][bytes].
+    def fields(values)
+      out = u16(values.length)
+      values.each do |v|
+        if v.nil?
+          out += "\x00".b
+        else
+          v = v.dup.force_encoding(Encoding::BINARY)
+          out += "\x01".b + u32(v.bytesize) + v
+        end
+      end
+      out
+    end
+
+    def frame(type, payload)
+      total = payload.bytesize + HEADER_LEN
+      (type.chr + u32(total) + payload).force_encoding(Encoding::BINARY)
+    end
+
+    def startup(user, database)
+      payload = u32(MAGIC) + u16(MAJOR) + u16(MINOR) + str(user) + str(database)
+      frame(T_STARTUP, payload)
+    end
+
+    def query(sql)
+      frame(T_QUERY, str(sql))
+    end
+
+    def parse(name, sql)
+      frame(T_PARSE, str(name) + str(sql) + u16(0))
+    end
+
+    def bind(portal, statement, values)
+      frame(T_BIND, str(portal) + str(statement) + fields(values) + u16(0))
+    end
+
+    def describe_portal(name)
+      frame(T_DESCRIBE, 'P'.b + str(name))
+    end
+
+    def execute(portal, max_rows = 0)
+      frame(T_EXECUTE, str(portal) + u32(max_rows))
+    end
+
+    def sync
+      frame(T_SYNC, ''.b)
+    end
+
+    def terminate
+      frame(T_TERMINATE, ''.b)
+    end
+
+    def sasl_initial(mechanism, data)
+      frame(T_SASL_INITIAL, str(mechanism) + u32(data.bytesize) + data)
+    end
+
+    def sasl_response(data)
+      frame(T_SASL_RESPONSE, data)
+    end
+
+    def copy_data(data)
+      frame(T_COPY_DATA, data)
+    end
+
+    def copy_done
+      frame(T_COPY_DONE, ''.b)
+    end
+
+    def copy_fail(message)
+      frame(T_COPY_FAIL, str(message))
+    end
+  end
+
+  # Reads the protocol's primitive encodings from a payload buffer.
+  class Reader
+    def initialize(buf)
+      @buf = buf
+      @pos = 0
+    end
+
+    def u8
+      v = @buf.getbyte(@pos)
+      @pos += 1
+      v
+    end
+
+    def u16
+      v = @buf.byteslice(@pos, 2).unpack1('n')
+      @pos += 2
+      v
+    end
+
+    def u32
+      v = @buf.byteslice(@pos, 4).unpack1('N')
+      @pos += 4
+      v
+    end
+
+    def str
+      n = u32
+      s = @buf.byteslice(@pos, n)
+      @pos += n
+      s.force_encoding(Encoding::UTF_8)
+    end
+
+    def rest
+      s = @buf.byteslice(@pos, @buf.bytesize - @pos)
+      @pos = @buf.bytesize
+      s
+    end
+
+    # Decode a Fields list; a nil entry is SQL NULL.
+    def fields
+      n = u16
+      out = []
+      n.times do
+        if u8.zero?
+          out << nil
+        else
+          len = u32
+          out << @buf.byteslice(@pos, len)
+          @pos += len
+        end
+      end
+      out
+    end
+  end
+end

data/lib/nusadb/scram.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'securerandom'
+
+module NusaDB
+  # Client-side SCRAM-SHA-256 (RFC 5802 / RFC 7677), docs/wire-protocol.md §7.2.
+  # Uses Ruby's bundled OpenSSL / SecureRandom — no gems.
+  #
+  # Base64 goes through Array#pack / String#unpack1 rather than the `base64` library, which
+  # `strict_encode64` / `strict_decode64` are themselves thin wrappers over ("m0" is strict:
+  # no line breaks, and decoding rejects malformed input with ArgumentError). Ruby 3.4 demoted
+  # `base64` from a default gem to a bundled one, so `require 'base64'` raises LoadError under
+  # Bundler unless the app declares it — which every Rails app using the ActiveRecord adapter
+  # would have to. The core methods keep the gem genuinely dependency-free.
+  class Scram
+    GS2_HEADER = 'n,,'
+    CHANNEL_BINDING = [GS2_HEADER].pack('m0')
+
+    attr_reader :client_first_bare, :full_client_first
+
+    def initialize(user)
+      nonce = [SecureRandom.random_bytes(18)].pack('m0')
+      @client_first_bare = "n=#{user},r=#{nonce}"
+      @full_client_first = GS2_HEADER + @client_first_bare
+      @expected_signature = ''
+    end
+
+    def client_final(password, server_first)
+      combined_nonce = nil
+      salt = nil
+      iterations = 0
+      server_first.split(',').each do |field|
+        key, _, value = field.partition('=')
+        next if value.nil? || key.empty?
+
+        case key
+        when 'r' then combined_nonce = value
+        when 's' then salt = value.unpack1('m0')
+        when 'i' then iterations = value.to_i
+        end
+      end
+      if combined_nonce.nil? || salt.nil? || iterations <= 0
+        raise NusaError.new('nusadb: malformed server-first message', '08P01')
+      end
+
+      salted = OpenSSL::PKCS5.pbkdf2_hmac(password, salt, iterations, 32, OpenSSL::Digest::SHA256.new)
+      client_key = hmac(salted, 'Client Key')
+      stored_key = OpenSSL::Digest::SHA256.digest(client_key)
+
+      without_proof = "c=#{CHANNEL_BINDING},r=#{combined_nonce}"
+      auth_message = "#{@client_first_bare},#{server_first},#{without_proof}"
+      client_sig = hmac(stored_key, auth_message)
+      proof = xor(client_key, client_sig)
+      final = "#{without_proof},p=#{[proof].pack('m0')}"
+
+      server_key = hmac(salted, 'Server Key')
+      @expected_signature = [hmac(server_key, auth_message)].pack('m0')
+      final
+    end
+
+    def verify_server_final(server_final)
+      got = ''
+      server_final.split(',').each do |field|
+        got = field[2..] if field.start_with?('v=')
+      end
+      OpenSSL.fixed_length_secure_compare(got, @expected_signature)
+    rescue ArgumentError
+      false # lengths differ
+    end
+
+    private
+
+    def hmac(key, msg)
+      OpenSSL::HMAC.digest('SHA256', key, msg)
+    end
+
+    def xor(a, b)
+      a.bytes.zip(b.bytes).map { |x, y| x ^ y }.pack('C*')
+    end
+  end
+end

data/lib/nusadb.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative 'nusadb/protocol'
+require_relative 'nusadb/scram'
+require_relative 'nusadb/connection'
+
+# NusaDB — pure-Ruby client for the Nusa Wire Protocol (PROTOCOL_VERSION 1.1).
+#
+# Example:
+#
+#   conn = NusaDB.connect(host: '127.0.0.1', port: 5678, user: 'nusa-root', database: 'nusadb')
+#   conn.query('CREATE TABLE t (id INT NOT NULL, name TEXT)')
+#   conn.execute('INSERT INTO t VALUES ($1, $2)', [1, 'alice'])
+#   conn.query('SELECT id, name FROM t WHERE id = $1', [1]).each { |row| p row }
+#   conn.close
+module NusaDB
+  VERSION = '0.1.0'
+
+  # Open a connection (see Connection#initialize for options).
+  def self.connect(**options)
+    Connection.new(**options)
+  end
+end

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: nusadb
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- NusaDB Authors
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-14 00:00:00.000000000 Z
+dependencies: []
+description: A pure-Ruby driver that speaks the Nusa Wire Protocol directly over a
+  socket.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/active_record/connection_adapters/nusadb_adapter.rb
+- lib/nusadb.rb
+- lib/nusadb/connection.rb
+- lib/nusadb/protocol.rb
+- lib/nusadb/scram.rb
+homepage: https://github.com/nusadb/ruby
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://github.com/nusadb/ruby
+  source_code_uri: https://github.com/nusadb/ruby
+  bug_tracker_uri: https://github.com/nusadb/ruby/issues
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.27
+signing_key:
+specification_version: 4
+summary: Pure-Ruby client for NusaDB (Nusa Wire Protocol)
+test_files: []