bzync-nextsql 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f8ea5d62b319951e5324da7495acd2b082dc3c05945b9c7cd8810f81ab204ed
-  data.tar.gz: 773874cbee89f62cea0754249800a087f8de553e79a90c7f0d5d6e85026f0a39
+  metadata.gz: 0146d77d1a64f774c074a7675c2c10be3cb9c00b65e1e60fead33c7baf5d4b48
+  data.tar.gz: 6490a676adbdc20b430a45eebd356d155d5f882ab76aab8b94af4a6302cbe5cf
 SHA512:
-  metadata.gz: 4c6cd6f4f39cd9aceedaaf0a373e8deedbe7a217ea9fdd0e04231bfc28409eeceb8cd84294b776ec1a48d8621fdf797e5007bc4203ff9bec950d95799333c128
-  data.tar.gz: 302b1dcfc03a25f1ac6ef126d99c9a1cfcb0c2c04dbf44414f8e4558e20b9029c8c0c5f2153f4f0de4326ff8ccb421944970ddb25412822d6cfc01887296050b
+  metadata.gz: 6d7e2921ed7f87454c6d65893d06178a9f776dc451b04e0258005f8a7d210f870f4fc9fc94e6cf9ad69a650b43a58b0bc22814844772ab96c7e968b31181bf06
+  data.tar.gz: 7cc3a24342dbaacb69cb828c6fc7214b618dce91eb6ca4c832019d681e5f7915da4c5f8456039805189fe4eaeb80f9ce5cbec231a912014ff5d18cb78b9d6042

data/README.md

@@ -31,7 +31,23 @@ end
 Plaintext connections are allowed only on loopback. For an HA cluster with
 follower-read routing, use `NextSQL.connect_cluster`.
 
+### Connection Pooling & Statement Caching
+
+```ruby
+pool = NextSQL.create_pool(cfg, min_size: 2, max_size: 10, statement_cache_size: 50)
+begin
+  pool.with do |conn|
+    res = conn.exec("SELECT * FROM users WHERE status = $1", ["active"])
+  end
+ensure
+  pool.close
+end
+```
+
+Parameterized queries automatically reuse cached server-side prepared statements via LRU eviction policy.
+
 - Full driver docs: <https://nextsql.bzync.com/docs/drivers>
 - Wire protocol: <https://github.com/bzync/nextsql/blob/master/docs/protocol.md>
+- Client-side field encryption: <https://nextsql.bzync.com/docs/client-encryption>
 
 MIT licensed.

data/lib/nextsql/client.rb

@@ -6,9 +6,11 @@
 
 require "socket"
 require "openssl"
+require "ipaddr"
 
 require_relative "protocol"
 require_relative "errors"
+require_relative "field_encryption"
 
 module NextSQL
   # TLS options for a remote connection. +ca+ is PEM text/bytes; omit both
@@ -23,12 +25,14 @@ module NextSQL
   end
 
   Config = Struct.new(:address, :nodes, :database, :realm, :user, :password, :key, :key_version, :tls,
-                       :insecure_no_tls, :read_consistency, :max_staleness_ms, :timeout, keyword_init: true) do
+                       :insecure_no_tls, :read_consistency, :max_staleness_ms, :timeout, :field_keys,
+                       :statement_cache_size, keyword_init: true) do
     def initialize(**kwargs)
       defaults = {
         address: "", nodes: [], database: "", realm: "", user: "", password: "",
         key: nil, key_version: 1, tls: nil, insecure_no_tls: false,
-        read_consistency: Protocol::READ_STRONG, max_staleness_ms: 0, timeout: 60.0
+        read_consistency: Protocol::READ_STRONG, max_staleness_ms: 0, timeout: 60.0,
+        field_keys: nil, statement_cache_size: 50
       }
       super(defaults.merge(kwargs))
     end
@@ -40,7 +44,6 @@ module NextSQL
   # from multiple threads/fibers — open one Connection per worker, or use
   # +Cluster+ which pools one connection per node.
   class Connection
-    LOOPBACK_RE = /\A127\.\d{1,3}\.\d{1,3}\.\d{1,3}\z/.freeze
     CONNECT_TIMEOUT = 10.0
 
     class << self
@@ -73,9 +76,12 @@ module NextSQL
         host, = split_host_port(addr, allow_bare: true)
         host = host.strip.downcase
         return true if host == "localhost"
-        return true if %w[::1 0:0:0:0:0:0:0:1].include?(host)
 
-        LOOPBACK_RE.match?(host)
+        begin
+          IPAddr.new(host).loopback?
+        rescue IPAddr::Error
+          false
+        end
       end
 
       def validate_config!(cfg)
@@ -92,6 +98,7 @@ module NextSQL
           raise Error.new("invalid_argument", "plaintext is only allowed on loopback")
         end
         raise Error.new("invalid_argument", "user is required") if cfg.user.to_s.empty?
+        raise Error.new("invalid_argument", "statement_cache_size must be >= 0") if cfg.statement_cache_size && cfg.statement_cache_size < 0
       end
 
       LEADING_WS_RE = /\A[ \t\r\n(]+/.freeze
@@ -172,6 +179,8 @@ module NextSQL
       @sock = self.class.dial(cfg)
       @secret = "".b
       @busy = false
+      @statement_cache_size = cfg.statement_cache_size || 0
+      @stmt_cache = {}
       begin
         handshake
         set_read_consistency(cfg.read_consistency, cfg.max_staleness_ms) if cfg.read_consistency != Protocol::READ_STRONG
@@ -200,6 +209,30 @@ module NextSQL
       st
     end
 
+    def encrypt_field(table, column, field_type, value)
+      raise Error.new("invalid_argument", "field_keys is required for client encryption") unless @cfg.field_keys
+
+      FieldEncryption.encrypt(@cfg.field_keys, @cfg.database.to_s.empty? ? "default" : @cfg.database, table, column, field_type, value)
+    end
+
+    def decrypt_field(table, column, expected_type, ciphertext)
+      raise Error.new("invalid_argument", "field_keys is required for client encryption") unless @cfg.field_keys
+
+      FieldEncryption.decrypt(@cfg.field_keys, @cfg.database.to_s.empty? ? "default" : @cfg.database, table, column, expected_type, ciphertext)
+    end
+
+    def encrypt_field_deterministic(table, column, field_type, value)
+      raise Error.new("invalid_argument", "field_keys is required for client encryption") unless @cfg.field_keys
+
+      FieldEncryption.encrypt_deterministic(@cfg.field_keys, @cfg.database.to_s.empty? ? "default" : @cfg.database, table, column, field_type, value)
+    end
+
+    def decrypt_field_deterministic(table, column, expected_type, ciphertext)
+      raise Error.new("invalid_argument", "field_keys is required for client encryption") unless @cfg.field_keys
+
+      FieldEncryption.decrypt_deterministic(@cfg.field_keys, @cfg.database.to_s.empty? ? "default" : @cfg.database, table, column, expected_type, ciphertext)
+    end
+
     def exec(sql, params = [])
       query(sql, params).collect
     end
@@ -208,6 +241,29 @@ module NextSQL
       raise Error.new("unavailable", "connection closed") if @sock.nil?
       raise Error.new("conflict", "connection is busy") if @busy
 
+      if !params.empty? && @statement_cache_size > 0
+        stmt_id = @stmt_cache.delete(sql)
+        if stmt_id.nil?
+          stmt_id = prepare_id(sql)
+          if @stmt_cache.size >= @statement_cache_size
+            _evicted_sql, evicted_id = @stmt_cache.shift
+            begin
+              close_statement(evicted_id)
+            rescue StandardError
+              nil
+            end
+          end
+        end
+        @stmt_cache[sql] = stmt_id
+
+        begin
+          return execute_prepared(stmt_id, params)
+        rescue StandardError
+          @stmt_cache.delete(sql)
+          raise
+        end
+      end
+
       @busy = true
       begin
         write_frame(Protocol::TYPE_QUERY, Protocol.encode_query(sql, params))
@@ -238,7 +294,7 @@ module NextSQL
       end
     end
 
-    def prepare(sql)
+    def prepare_id(sql)
       raise Error.new("conflict", "connection is busy") if @busy
 
       write_frame(Protocol::TYPE_PREPARE, Protocol.u32bytes(sql.b, Protocol::MAX_SQL))
@@ -248,7 +304,11 @@ module NextSQL
 
       stmt_id = Protocol.u32(payload, 0)
       expect_ready
-      Statement.new(self, stmt_id)
+      stmt_id
+    end
+
+    def prepare(sql)
+      Statement.new(self, prepare_id(sql))
     end
 
     def execute_prepared(stmt_id, params)
@@ -297,6 +357,17 @@ module NextSQL
     def close
       return if @sock.nil?
 
+      if @stmt_cache
+        @stmt_cache.each_value do |stmt_id|
+          begin
+            close_statement(stmt_id)
+          rescue StandardError
+            nil
+          end
+        end
+        @stmt_cache.clear
+      end
+
       begin
         write_frame(Protocol::TYPE_TERMINATE, "")
       rescue Error
@@ -369,12 +440,17 @@ module NextSQL
 
     def handshake
       cfg = @cfg
-      write_frame(Protocol::TYPE_HELLO, Protocol.encode_hello(Protocol::VERSION, 0, "\x00" * 8, cfg.database, cfg.user, cfg.realm))
+      write_frame(Protocol::TYPE_HELLO,
+                  Protocol.encode_hello(Protocol::VERSION, Protocol::FLAG_PUBLIC_ERROR_CODES, "\x00" * 8,
+                                        cfg.database, cfg.user, cfg.realm))
       typ, payload = read_frame
       raise unexpected(typ, payload) if typ != Protocol::TYPE_HELLO_OK
 
-      _version, auth_method, secret = Protocol.decode_hello_ok(payload)
+      _version, auth_method, secret, flags = Protocol.decode_hello_ok(payload)
       @secret = secret
+      # Diagnostic only: decode_error reads the field whenever it is present,
+      # so nothing depends on this having been echoed.
+      @public_error_codes = (flags & Protocol::FLAG_PUBLIC_ERROR_CODES) != 0
       write_frame(Protocol::TYPE_AUTH, Protocol.u16str(cfg.password))
       typ, payload = read_frame
       raise unexpected(typ, payload) if typ != Protocol::TYPE_AUTH_OK

data/lib/nextsql/errors.rb

@@ -10,8 +10,16 @@ module NextSQL
   class Error < StandardError
     attr_reader :error_code
 
-    def initialize(error_code, message = "")
+    # +public_code+ is the stable ERR_* name from docs/error-codes.md. It is
+    # set only on an error received over a connection that negotiated the
+    # public taxonomy, and is "" otherwise -- for a local error, or an older
+    # server. +error_code+ always carries the legacy class, so retry logic
+    # keeps reading that and nothing should require +public_code+.
+    attr_reader :public_code
+
+    def initialize(error_code, message = "", public_code = "")
       @error_code = error_code
+      @public_code = public_code
       super(message.empty? ? error_code : message)
     end
   end