tigerbeetle 0.0.1.pre.dev → 0.0.2

data/lib/tigerbeetle/client.rb

@@ -0,0 +1,215 @@
+require 'ffi'
+require 'tb_client'
+require 'tigerbeetle/converters'
+require 'tigerbeetle/account'
+require 'tigerbeetle/account_balance'
+require 'tigerbeetle/account_filter'
+require 'tigerbeetle/atomic_counter'
+require 'tigerbeetle/error'
+require 'tigerbeetle/query_filter'
+require 'tigerbeetle/request'
+require 'tigerbeetle/transfer'
+
+module TigerBeetle
+  class Client
+    def self.next_id
+      @counter ||= AtomicCounter.new
+      @counter.increment
+    end
+
+    def initialize(cluster_id = 0, address = '3000')
+      @inflight_requests = {}
+      # Keep a pointer to prevent proc from getting GCed
+      @callback = Proc.new { |*args| callback(*args) }
+      @client_id = self.class.next_id
+      @client = TBClient::Client.new
+
+      # FFI::MemoryPointer.new(:pointer, 1) # **void
+      cluster_id_ptr = serialize([cluster_id], Converters::UInt128)
+
+      status = TBClient.tb_client_init(
+        @client,
+        cluster_id_ptr,
+        address,
+        address.length,
+        @client_id,
+        &@callback
+      )
+      raise ClientError, "Unable to initialize native client: #{status}" unless status == :SUCCESS
+
+      # Make sure to deinitialize all clients when the process terminates
+      at_exit { deinit }
+    end
+
+    def logger=(logger)
+      @logger = logger
+      @log_callback = @logger ? Proc.new { |*args| log_callback(*args) } : nil
+
+      status = TBClient.tb_client_register_log_callback(@log_callback, true)
+      raise ClientError, "Unable to register logger: #{status}" unless status == :SUCCESS
+    end
+
+    def create_accounts(*accounts, &block)
+      submit_request(
+        :CREATE_ACCOUNTS,
+        accounts,
+        Converters::Account,
+        Converters::CreateAccountsResult,
+        &block
+      )
+    end
+
+    def create_transfers(*transfers, &block)
+      submit_request(
+        :CREATE_TRANSFERS,
+        transfers,
+        Converters::Transfer,
+        Converters::CreateTransfersResult,
+        &block
+      )
+    end
+
+    def lookup_accounts(*account_ids, &block)
+      submit_request(
+        :LOOKUP_ACCOUNTS,
+        account_ids,
+        Converters::UInt128,
+        Converters::Account,
+        &block
+      )
+    end
+
+    def lookup_transfers(*transfer_ids, &block)
+      submit_request(
+        :LOOKUP_TRANSFERS,
+        transfer_ids,
+        Converters::UInt128,
+        Converters::Transfer,
+        &block
+      )
+    end
+
+    def get_account_transfers(filter, &block)
+      submit_request(
+        :GET_ACCOUNT_TRANSFERS,
+        [filter],
+        Converters::AccountFilter,
+        Converters::Transfer,
+        &block
+      )
+    end
+
+    def get_account_balances(filter, &block)
+      submit_request(
+        :GET_ACCOUNT_BALANCES,
+        [filter],
+        Converters::AccountFilter,
+        Converters::AccountBalance,
+        &block
+      )
+    end
+
+    def query_accounts(filter, &block)
+      submit_request(
+        :QUERY_ACCOUNTS,
+        [filter],
+        Converters::QueryFilter,
+        Converters::Account,
+        &block
+      )
+    end
+
+    def query_transfers(filter, &block)
+      submit_request(
+        :QUERY_TRANSFERS,
+        [filter],
+        Converters::QueryFilter,
+        Converters::Transfer,
+        &block
+      )
+    end
+
+    def deinit
+      return unless client
+      return unless inflight_requests.empty?
+
+      TBClient.tb_client_deinit(client)
+      @client = nil
+    end
+
+    private
+
+    attr_reader :context, :client, :inflight_requests, :logger
+
+    def log_callback(level, ptr, length)
+      message = ptr.read_string(length).force_encoding('UTF-8')
+      case level
+      when :ERR then logger.error(message)
+      when :WARN then logger.warn(message)
+      when :INFO then logger.info(message)
+      when :DEBUG then logger.debug(message)
+      end
+    end
+
+    def callback(client_id, packet, timestamp, result_ptr, result_len)
+      request_id = packet[:user_data].read_uint64
+      request = inflight_requests[request_id]
+      result = deserialize(result_ptr, request.converter, result_len)
+      request.block.call(result)
+      inflight_requests.delete(request_id)
+    end
+
+    def submit_request(operation, request, request_converter, response_converter, &block)
+      raise ClientError, 'Client is not connected' unless client
+
+      request_id = self.class.next_id
+      user_data_ptr = FFI::MemoryPointer.new(:uint64, 1)
+      user_data_ptr.write_uint64(request_id)
+
+      data_ptr = serialize(request, request_converter)
+
+      packet = TBClient::Packet.new
+      packet[:user_data] = user_data_ptr
+      packet[:operation] = operation
+      packet[:status] = :OK
+      packet[:data_size] = data_ptr.size
+      packet[:data] = data_ptr
+
+      queue = Queue.new
+      inflight_requests[request_id] = Request.new(packet, response_converter) do |response|
+        if block
+          block.call(response)
+        else
+          queue << response
+        end
+      end
+
+      status = TBClient.tb_client_submit(client, packet)
+      raise ClientError, "Unable to submit request: #{status}" unless status == :OK
+
+      # block until the client return a response
+      queue.pop unless block
+    end
+
+    def serialize(data, converter)
+      data_ptr = FFI::MemoryPointer.new(converter.native_type, data.length, true)
+      data.each_with_index do |value, i|
+        # initialize type at the memory address and write value over it
+        converter.to_native(data_ptr[i], value)
+      end
+
+      data_ptr
+    end
+
+    def deserialize(ptr, converter, length)
+      type = converter.native_type
+      # copy the memory own to retain the data after tb_client has freed its memory
+      own_ptr = FFI::MemoryPointer.new(:char, type.size * length)
+      own_ptr.put_bytes(0, ptr.read_bytes(type.size * length))
+
+      Array.new(length / type.size) do |i|
+        converter.from_native(own_ptr + i * type.size)
+      end
+    end
+  end
+end

data/lib/tigerbeetle/converters/account.rb

@@ -0,0 +1,63 @@
+require 'tb_client'
+require 'tigerbeetle/account'
+require 'tigerbeetle/converters/base'
+require 'tigerbeetle/converters/time'
+require 'tigerbeetle/converters/uint_128'
+
+module TigerBeetle
+  module Converters
+    class Account < Base
+      def self.native_type
+        TBClient::Account
+      end
+
+      def from_native(ptr)
+        c_value = TBClient::Account.new(ptr)
+
+        TigerBeetle::Account.new(
+          id: Converters::UInt128.from_native(c_value[:id].to_ptr),
+          debits_pending: Converters::UInt128.from_native(c_value[:debits_pending].to_ptr),
+          debits_posted: Converters::UInt128.from_native(c_value[:debits_posted].to_ptr),
+          credits_pending: Converters::UInt128.from_native(c_value[:credits_pending].to_ptr),
+          credits_posted: Converters::UInt128.from_native(c_value[:credits_posted].to_ptr),
+          user_data_128: Converters::UInt128.from_native(c_value[:user_data_128].to_ptr),
+          user_data_64: c_value[:user_data_64],
+          user_data_32: c_value[:user_data_32],
+          ledger: c_value[:ledger],
+          code: c_value[:code],
+          flags: c_value[:flags],
+          timestamp: Converters::Time.from_native(ptr + c_value.offset_of(:timestamp))
+        )
+      end
+
+      def to_native(ptr, value)
+        validate_uint!(:id, 128, value.id)
+        validate_uint!(:debits_pending, 128, value.debits_pending)
+        validate_uint!(:debits_posted, 128, value.debits_posted)
+        validate_uint!(:credits_pending, 128, value.credits_pending)
+        validate_uint!(:credits_posted, 128, value.credits_posted)
+        validate_uint!(:user_data_128, 128, value.user_data_128)
+        validate_uint!(:user_data_64, 64, value.user_data_64)
+        validate_uint!(:user_data_32, 32, value.user_data_32)
+        validate_uint!(:ledger, 32, value.ledger)
+        validate_uint!(:code, 16, value.code)
+
+        TBClient::Account.new(ptr).tap do |result|
+          Converters::UInt128.to_native(result[:id].to_ptr, value.id)
+          Converters::UInt128.to_native(result[:debits_pending].to_ptr, value.debits_pending)
+          Converters::UInt128.to_native(result[:debits_posted].to_ptr, value.debits_posted)
+          Converters::UInt128.to_native(result[:credits_pending].to_ptr, value.credits_pending)
+          Converters::UInt128.to_native(result[:credits_posted].to_ptr, value.credits_posted)
+          Converters::UInt128.to_native(result[:user_data_128].to_ptr, value.user_data_128)
+          result[:user_data_64] = value.user_data_64
+          result[:user_data_32] = value.user_data_32
+          result[:reserved] = 0
+          result[:ledger] = value.ledger
+          result[:code] = value.code
+          result[:flags] = value.flags
+          Converters::Time.to_native(ptr + result.offset_of(:timestamp), value.timestamp || 0)
+        end
+      end
+    end
+  end
+end

data/lib/tigerbeetle/converters/account_balance.rb

@@ -0,0 +1,31 @@
+require 'tb_client'
+require 'tigerbeetle/account_balance'
+require 'tigerbeetle/converters/base'
+require 'tigerbeetle/converters/time'
+require 'tigerbeetle/converters/uint_128'
+
+module TigerBeetle
+  module Converters
+    class AccountBalance < Base
+      def self.native_type
+        TBClient::AccountBalance
+      end
+
+      def from_native(ptr)
+        c_value = TBClient::AccountBalance.new(ptr)
+
+        TigerBeetle::AccountBalance.new(
+          debits_pending: Converters::UInt128.from_native(c_value[:debits_pending].to_ptr),
+          debits_posted: Converters::UInt128.from_native(c_value[:debits_posted].to_ptr),
+          credits_pending: Converters::UInt128.from_native(c_value[:credits_pending].to_ptr),
+          credits_posted: Converters::UInt128.from_native(c_value[:credits_posted].to_ptr),
+          timestamp: Converters::Time.from_native(ptr + c_value.offset_of(:timestamp))
+        )
+      end
+
+      def to_native(ptr, value)
+        raise 'Unexpected conversion of AccountBalance to native type'
+      end
+    end
+  end
+end

data/lib/tigerbeetle/converters/account_filter.rb

@@ -0,0 +1,32 @@
+require 'tb_client'
+require 'tigerbeetle/account_filter'
+require 'tigerbeetle/converters/time'
+require 'tigerbeetle/converters/uint_128'
+
+module TigerBeetle
+  module Converters
+    class AccountFilter < Base
+      def self.native_type
+        TBClient::AccountFilter
+      end
+
+      def from_native(ptr)
+        raise 'Unexpected conversion of a native type to AccountFilter'
+      end
+
+      def to_native(ptr, value)
+        TBClient::AccountFilter.new(ptr).tap do |result|
+          Converters::UInt128.to_native(result[:account_id].to_ptr, value.account_id)
+          Converters::UInt128.to_native(result[:user_data_128].to_ptr, value.user_data_128)
+          result[:user_data_64] = value.user_data_64
+          result[:user_data_32] = value.user_data_32
+          result[:code] = value.code
+          Converters::Time.to_native(ptr + result.offset_of(:timestamp_min), value.timestamp_min || 0)
+          Converters::Time.to_native(ptr + result.offset_of(:timestamp_max), value.timestamp_max || 0)
+          result[:limit] = value.limit
+          result[:flags] = value.flags
+        end
+      end
+    end
+  end
+end

data/lib/tigerbeetle/converters/base.rb

@@ -0,0 +1,35 @@
+module TigerBeetle
+  module Converters
+    class Base
+      def self.from_native(ptr)
+        self.new.from_native(ptr)
+      end
+
+      def self.to_native(ptr, value)
+        self.new.to_native(ptr, value)
+      end
+
+      def self.native_type
+        raise NotImplementedError, 'Implement in sublcass'
+      end
+
+      def from_native(ptr)
+        raise NotImplementedError, 'Implement in sublcass'
+      end
+
+      def to_native(ptr, value)
+        raise NotImplementedError, 'Implement in sublcass'
+      end
+
+      private
+
+      def validate_uint!(name, bits, value)
+        if value > 2**bits - 1
+          raise ArgumentError, "#{name} == #{value} is too large to fit in #{bits} bits"
+        elsif value < 0
+          raise ArgumentError, "#{name} == #{value} cannot be negative"
+        end
+      end
+    end
+  end
+end

data/lib/tigerbeetle/converters/create_accounts_result.rb

@@ -0,0 +1,21 @@
+require 'tb_client'
+require 'tigerbeetle/converters/base'
+
+module TigerBeetle
+  module Converters
+    class CreateAccountsResult < Base
+      def self.native_type
+        TBClient::CreateAccountsResult
+      end
+
+      def from_native(ptr)
+        c_value = TBClient::CreateAccountsResult.new(ptr)
+        [c_value[:index], c_value[:result]]
+      end
+
+      def to_native(ptr, value)
+        raise 'Unexpected conversion of CreateAccountsResult to a native type'
+      end
+    end
+  end
+end

data/lib/tigerbeetle/converters/create_transfers_result.rb

@@ -0,0 +1,21 @@
+require 'tb_client'
+require 'tigerbeetle/converters/base'
+
+module TigerBeetle
+  module Converters
+    class CreateTransfersResult < Base
+      def self.native_type
+        TBClient::CreateTransfersResult
+      end
+
+      def from_native(ptr)
+        c_value = TBClient::CreateTransfersResult.new(ptr)
+        [c_value[:index], c_value[:result]]
+      end
+
+      def to_native(ptr, value)
+        raise 'Unexpected conversion of CreateTransfersResult to a native type'
+      end
+    end
+  end
+end

data/lib/tigerbeetle/converters/query_filter.rb

@@ -0,0 +1,33 @@
+require 'tb_client'
+require 'tigerbeetle/query_filter'
+require 'tigerbeetle/converters/base'
+require 'tigerbeetle/converters/time'
+require 'tigerbeetle/converters/uint_128'
+
+module TigerBeetle
+  module Converters
+    class QueryFilter < Base
+      def self.native_type
+        TBClient::QueryFilter
+      end
+
+      def from_native(ptr)
+        raise 'Unexpected conversion of a native type to QueryFilter'
+      end
+
+      def to_native(ptr, value)
+        TBClient::QueryFilter.new(ptr).tap do |result|
+          Converters::UInt128.to_native(result[:user_data_128].to_ptr, value.user_data_128)
+          result[:user_data_64] = value.user_data_64
+          result[:user_data_32] = value.user_data_32
+          result[:code] = value.code
+          result[:ledger] = value.ledger
+          Converters::Time.to_native(ptr + result.offset_of(:timestamp_min), value.timestamp_min || 0)
+          Converters::Time.to_native(ptr + result.offset_of(:timestamp_max), value.timestamp_max || 0)
+          result[:limit] = value.limit
+          result[:flags] = value.flags
+        end
+      end
+    end
+  end
+end

data/lib/tigerbeetle/converters/time.rb

@@ -0,0 +1,23 @@
+require 'ffi'
+require 'tigerbeetle/converters/base'
+
+module TigerBeetle
+  module Converters
+    class Time < Base
+      def self.native_type
+        FFI::Type::UINT64
+      end
+
+      def from_native(ptr)
+        ::Time.at(ptr.read(FFI::Type::UINT64) / 1e9)
+      end
+
+      def to_native(ptr, value)
+        int = (value.to_f * 1e9).to_i
+        validate_uint!(:timestamp, 64, int)
+
+        ptr.write(FFI::Type::UINT64, int)
+      end
+    end
+  end
+end

data/lib/tigerbeetle/converters/transfer.rb

@@ -0,0 +1,64 @@
+require 'tb_client'
+require 'tigerbeetle/transfer'
+require 'tigerbeetle/converters/base'
+require 'tigerbeetle/converters/time'
+require 'tigerbeetle/converters/uint_128'
+
+module TigerBeetle
+  module Converters
+    class Transfer < Base
+      def self.native_type
+        TBClient::Transfer
+      end
+
+      def from_native(ptr)
+        c_value = TBClient::Transfer.new(ptr)
+
+        TigerBeetle::Transfer.new(
+          id: Converters::UInt128.from_native(c_value[:id].to_ptr),
+          debit_account_id: Converters::UInt128.from_native(c_value[:debit_account_id].to_ptr),
+          credit_account_id: Converters::UInt128.from_native(c_value[:credit_account_id].to_ptr),
+          amount: Converters::UInt128.from_native(c_value[:amount].to_ptr),
+          pending_id: Converters::UInt128.from_native(c_value[:pending_id].to_ptr),
+          user_data_128: Converters::UInt128.from_native(c_value[:user_data_128].to_ptr),
+          user_data_64: c_value[:user_data_64],
+          user_data_32: c_value[:user_data_32],
+          timeout: c_value[:timeout],
+          ledger: c_value[:ledger],
+          code: c_value[:code],
+          flags: c_value[:flags],
+          timestamp: Converters::Time.from_native(ptr + c_value.offset_of(:timestamp))
+        )
+      end
+
+      def to_native(ptr, value)
+        validate_uint!(:id, 128, value.id)
+        validate_uint!(:debit_account_id, 128, value.debit_account_id)
+        validate_uint!(:credit_account_id, 128, value.credit_account_id)
+        validate_uint!(:amount, 128, value.amount)
+        validate_uint!(:user_data_128, 128, value.user_data_128)
+        validate_uint!(:user_data_64, 64, value.user_data_64)
+        validate_uint!(:user_data_32, 32, value.user_data_32)
+        validate_uint!(:timeout, 32, value.timeout)
+        validate_uint!(:ledger, 32, value.ledger)
+        validate_uint!(:code, 16, value.code)
+
+        TBClient::Transfer.new(ptr).tap do |result|
+          Converters::UInt128.to_native(result[:id].to_ptr, value.id)
+          Converters::UInt128.to_native(result[:debit_account_id].to_ptr, value.debit_account_id)
+          Converters::UInt128.to_native(result[:credit_account_id].to_ptr, value.credit_account_id)
+          Converters::UInt128.to_native(result[:amount].to_ptr, value.amount)
+          Converters::UInt128.to_native(result[:pending_id].to_ptr, value.pending_id)
+          Converters::UInt128.to_native(result[:user_data_128].to_ptr, value.user_data_128)
+          result[:user_data_64] = value.user_data_64
+          result[:user_data_32] = value.user_data_32
+          result[:timeout] = value.timeout
+          result[:ledger] = value.ledger
+          result[:code] = value.code
+          result[:flags] = value.flags
+          Converters::Time.to_native(ptr + result.offset_of(:timestamp), value.timestamp || 0)
+        end
+      end
+    end
+  end
+end

data/lib/tigerbeetle/converters/uint_128.rb

@@ -0,0 +1,24 @@
+require 'tb_client'
+require 'tigerbeetle/converters/base'
+
+module TigerBeetle
+  module Converters
+    class UInt128 < Base
+      def self.native_type
+        TBClient::UInt128
+      end
+
+      def from_native(ptr)
+        c_value = TBClient::UInt128.new(ptr)
+        c_value[:low] + (c_value[:high] << 64)
+      end
+
+      def to_native(ptr, value)
+        TBClient::UInt128.new(ptr).tap do |result|
+          result[:low] = value % 2**64
+          result[:high] = value >> 64
+        end
+      end
+    end
+  end
+end

data/lib/tigerbeetle/converters.rb

@@ -0,0 +1,12 @@
+require 'tigerbeetle/converters/account'
+require 'tigerbeetle/converters/account_balance'
+require 'tigerbeetle/converters/account_filter'
+require 'tigerbeetle/converters/create_accounts_result'
+require 'tigerbeetle/converters/create_transfers_result'
+require 'tigerbeetle/converters/query_filter'
+require 'tigerbeetle/converters/time'
+require 'tigerbeetle/converters/transfer'
+require 'tigerbeetle/converters/uint_128'
+
+module Converters
+end

data/lib/tigerbeetle/error.rb

@@ -0,0 +1,4 @@
+module TigerBeetle
+  class Error < StandardError; end
+  class ClientError < Error; end
+end

data/lib/tigerbeetle/id.rb

@@ -0,0 +1,30 @@
+require 'securerandom'
+
+module TigerBeetle
+  module ID
+    @last_time_ms = 0
+
+    # Generates a Universally Unique and Sortable Identifier as a 128-bit integer. Based on ULIDs
+    # Inspired by ext/tb_client/tigerbeetle/src/clients/python/src/tigerbeetle/client.py#id
+    def self.generate
+      rnd_bytes = SecureRandom.random_bytes(10)
+      time_ms = (Time.now.to_f * 1000).to_i
+
+      # Ensure time_ms monotonically increases
+      if time_ms <= @last_time_ms
+        time_ms = @last_time_ms
+      else
+        @last_time_ms = time_ms
+      end
+
+      # Convert time_ms integer to 6 bytes (string) in big-endian
+      time_bytes = [time_ms].pack("Q>")[2..7]
+
+      # Combine time and randomness and convert to two 64-bit integers in big-endian
+      integers = (time_bytes + rnd_bytes).unpack("Q>Q>")
+
+      # Re-combine into a single 128-bit integer in big-endian
+      integers[0] << 64 | integers[1]
+    end
+  end
+end

data/lib/tigerbeetle/query_filter.rb

@@ -0,0 +1,31 @@
+module TigerBeetle
+  QUERY_FILTER_PARAMS = %i[
+    user_data_128 user_data_64 user_data_32 ledger code timestamp_min timestamp_max limit flags
+  ]
+
+  QueryFilter = Struct.new(*QUERY_FILTER_PARAMS) do
+    def initialize(
+      user_data_128: 0,
+      user_data_64: 0,
+      user_data_32: 0,
+      ledger: 0,
+      code: 0,
+      timestamp_min: 0,
+      timestamp_max: 0,
+      limit:,
+      flags: []
+    )
+      super(
+        user_data_128,
+        user_data_64,
+        user_data_32,
+        ledger,
+        code,
+        timestamp_min,
+        timestamp_max,
+        limit,
+        flags
+      )
+    end
+  end
+end

data/lib/tigerbeetle/request.rb

@@ -0,0 +1,7 @@
+module TigerBeetle
+  Request = Struct.new(:packet, :converter, :block) do
+    def initialize(packet, converter, &block)
+      super(packet, converter, block)
+    end
+  end
+end