catdb-client 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fe9866eedd48e0d1f987d21d4a19bfa7d6641602342b4a04d040b81652812730
+  data.tar.gz: 2dab17d31a4bb7b2af026be609c1ef356e59ca7734121d787428c7a33e10d56b
+SHA512:
+  metadata.gz: eeb3e32f7fc9291d2bc3f9cd029e561001d07a1c5741cc0deadc929a6fa82e2f81fea934860efaafebe94644413a766727dcc4c465f09de9028ca4eadea19532
+  data.tar.gz: 5efd05b4895fc865ebf609ce37bede59ad80bd134aa2bb7353dbc1abcf639ffa42372c076ce6f27ac2f5ec89a37cc24b9d15b6d1d74e35e498a0867831119a5a

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dhq_boiler and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,26 @@
+# catdb for Ruby
+
+Use Ruby 3.1 or later. Install the client from RubyGems.org:
+
+```sh
+gem install catdb-client -v 0.1.0
+```
+
+With Bundler, add `gem "catdb-client", "~> 0.1.0"` to your Gemfile and run `bundle install`. Load the client with `require "catdb"`.
+
+```ruby
+require "catdb"
+
+CatDB::Client.connect(token: ENV.fetch("CATDB_TOKEN")) do |client|
+  key = "\xff\x00".b
+  version = client.put_commit(key, "\x01\x02".b)
+  value = client.get_latest(key)
+  p [version, value]
+end
+```
+
+Use the shared token on a trusted local connection. For an account, pass `host:`, `username:`, `password:` and optionally `database:` (default `"main"`) and `ca_file:` (a PEM certificate file). Account connections require TLS 1.3 and verify the hostname and certificate chain. The default address is `127.0.0.1:7400`. The `timeout:` setting is in seconds and defaults to 10.
+
+`get_latest` returns a binary string or `nil` for a missing key. An empty value returns an empty string. `put_commit` and `delete_commit` wait for a durable commit and return its version as a decimal string. For a transaction, use `begin_transaction` or `begin_read`, then `get`, `put`, `delete`, `commit` or `rollback`. One connection serializes requests and owns one transaction. Give independent transactions separate clients. The block form closes the connection on exit.
+
+Use `request(op: "scan_latest", start: "", rows: 20)` for the remaining wire operations, with hex keys and values. A server rejection raises `CatDB::ServerError` with its `code`. A lost reply can leave a mutation's outcome unknown. The client closes the connection and leaves the decision to retry to the application.

data/lib/catdb.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+require "socket"
+require "timeout"
+
+module CatDB
+  class ServerError < StandardError
+    attr_reader :code
+
+    def initialize(code)
+      @code = code
+      super("catdb returned #{code}")
+    end
+  end
+
+  class Client
+    MAX_REQUEST = 1024 * 1024
+    MAX_RESPONSE = 2 * 1024 * 1024 + 8192
+
+    def self.connect(**options)
+      client = new(**options)
+      return client unless block_given?
+
+      begin
+        yield client
+      ensure
+        client.close
+      end
+    end
+
+    def initialize(host: "127.0.0.1", port: 7400, token: nil, username: nil, password: nil,
+                   database: "main", ca_file: nil, timeout: 10)
+      @timeout = Float(timeout)
+      raise ArgumentError, "timeout must be finite and positive" unless @timeout.finite? && @timeout.positive?
+      account = !username.nil?
+      valid = if account
+                username.is_a?(String) && password.is_a?(String) && token.nil?
+              else
+                token.is_a?(String) && password.nil? && database == "main" && ca_file.nil?
+              end
+      raise ArgumentError, "choose a token or a TLS username and password" unless valid
+
+      @lock = Mutex.new
+      connected = false
+      begin
+        Timeout.timeout(@timeout) do
+          @socket = Socket.tcp(host, port, connect_timeout: @timeout)
+          @socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1)
+          if account
+            context = OpenSSL::SSL::SSLContext.new
+            context.set_params
+            context.min_version = OpenSSL::SSL::TLS1_3_VERSION
+            if ca_file
+              trust = OpenSSL::X509::Store.new
+              trust.add_file(ca_file)
+              context.cert_store = trust
+            end
+            tls = OpenSSL::SSL::SSLSocket.new(@socket, context)
+            tls.sync_close = true
+            @socket = tls
+            tls.hostname = host
+            tls.connect
+            tls.post_connection_check(host)
+          end
+        end
+        auth = account ? { op: "auth", version: 2, username: username, password: password, database: database } :
+                         { op: "auth", version: 1, token: token }
+        reply = request(**auth)
+        raise IOError, "unexpected catdb protocol version" unless reply["protocol"] == (account ? 2 : 1)
+        connected = true
+      ensure
+        close unless connected
+      end
+    end
+
+    def request(op:, **fields)
+      body = JSON.generate(fields.merge(op: op)).b
+      raise ArgumentError, "catdb request exceeds 1 MiB" if body.bytesize > MAX_REQUEST
+      @lock.synchronize do
+        socket = @socket
+        raise IOError, "catdb connection is closed" unless socket
+        received = false
+        begin
+          reply = Timeout.timeout(@timeout) do
+            socket.write([body.bytesize].pack("N") + body)
+            size = read_exact(socket, 4).unpack1("N")
+            raise IOError, "invalid catdb response size" unless size.between?(1, MAX_RESPONSE)
+            text = read_exact(socket, size).force_encoding(Encoding::UTF_8)
+            raise IOError, "invalid catdb response encoding" unless text.valid_encoding?
+            JSON.parse(text)
+          end
+          unless reply.is_a?(Hash) && (reply["ok"] == true || (reply["ok"] == false && reply["error"].is_a?(String)))
+            raise IOError, "invalid catdb response"
+          end
+          received = true
+        rescue IOError, SystemCallError, OpenSSL::SSL::SSLError, Timeout::Error, JSON::ParserError => e
+          raise IOError, "catdb response lost or invalid; a submitted mutation may have committed", cause: e
+        ensure
+          close unless received
+        end
+        raise ServerError, reply["error"] unless reply["ok"]
+        reply
+      end
+    end
+
+    def ping = version(op: "ping")
+    def get_latest(key) = read_value("get_latest", key)
+    def put_commit(key, value) = version(op: "put_commit", key: hex(key), value: hex(value))
+    def delete_commit(key) = version(op: "delete_commit", key: hex(key))
+    def begin_transaction = version(op: "begin")
+    def begin_read = version(op: "begin_read")
+    def get(key) = read_value("get", key)
+    def put(key, value) = request(op: "put", key: hex(key), value: hex(value))
+    def delete(key) = request(op: "delete", key: hex(key))
+    def commit = version(op: "commit")
+    def rollback = request(op: "rollback")
+
+    def close
+      socket = @socket
+      @socket = nil
+      socket&.close
+    end
+
+    private
+
+    def hex(bytes)
+      raise TypeError, "expected a binary String" unless bytes.is_a?(String)
+      bytes.unpack1("H*")
+    end
+
+    def read_exact(socket, size)
+      data = socket.read(size)
+      raise EOFError, "catdb connection closed" unless data && data.bytesize == size
+      data
+    end
+
+    def read_value(op, key)
+      reply = request(op: op, key: hex(key))
+      value = reply["value"]
+      return nil if reply.key?("value") && value.nil?
+      return [value].pack("H*") if value.is_a?(String) && value.bytesize.even? && value.match?(/\A[0-9a-fA-F]*\z/)
+      close
+      raise IOError, "invalid catdb value"
+    end
+
+    def version(**operation)
+      number = request(**operation)["version"]
+      return number if number.is_a?(String) && number.match?(/\A(?:0|[1-9][0-9]*)\z/)
+      close
+      raise IOError, "invalid catdb version"
+    end
+  end
+end

metadata

@@ -0,0 +1,45 @@
+--- !ruby/object:Gem::Specification
+name: catdb-client
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- catdb contributors
+bindir: bin
+cert_chain: []
+date: 1970-01-01 00:00:00.000000000 Z
+dependencies: []
+description: Read and write binary keys and values, commit transactions, and connect
+  to catdb with token or TLS account authentication.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/catdb.rb
+homepage: https://github.com/dhq-boiler/catdb
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/dhq-boiler/catdb/tree/clients/ruby/v0.1.0/clients/ruby
+  bug_tracker_uri: https://github.com/dhq-boiler/catdb/issues
+  allowed_push_host: https://rubygems.org
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby client for the catdb TCP service
+test_files: []