tigerbeetle 0.0.40 → 0.17.9

data/src/tigerbeetle/bindings.rb

@@ -0,0 +1,355 @@
+########################################################
+## This file was auto-generated by ruby_bindings.zig ##
+##              Do not manually modify.              ##
+########################################################
+
+module TigerBeetle
+  module AccountFlags
+    NONE = 0
+    LINKED = 1 << 0
+    DEBITS_MUST_NOT_EXCEED_CREDITS = 1 << 1
+    CREDITS_MUST_NOT_EXCEED_DEBITS = 1 << 2
+    HISTORY = 1 << 3
+    IMPORTED = 1 << 4
+    CLOSED = 1 << 5
+  end
+
+  module TransferFlags
+    NONE = 0
+    LINKED = 1 << 0
+    PENDING = 1 << 1
+    POST_PENDING_TRANSFER = 1 << 2
+    VOID_PENDING_TRANSFER = 1 << 3
+    BALANCING_DEBIT = 1 << 4
+    BALANCING_CREDIT = 1 << 5
+    CLOSING_DEBIT = 1 << 6
+    CLOSING_CREDIT = 1 << 7
+    IMPORTED = 1 << 8
+  end
+
+  module AccountFilterFlags
+    NONE = 0
+    DEBITS = 1 << 0
+    CREDITS = 1 << 1
+    REVERSED = 1 << 2
+  end
+
+  module QueryFilterFlags
+    NONE = 0
+    REVERSED = 1 << 0
+  end
+
+  module Operation
+    LOOKUP_ACCOUNTS = 140
+    LOOKUP_TRANSFERS = 141
+    GET_ACCOUNT_TRANSFERS = 142
+    GET_ACCOUNT_BALANCES = 143
+    QUERY_ACCOUNTS = 144
+    QUERY_TRANSFERS = 145
+    CREATE_ACCOUNTS = 146
+    CREATE_TRANSFERS = 147
+  end
+
+  module CreateAccountStatus
+    CREATED = 4294967295
+    LINKED_EVENT_FAILED = 1
+    LINKED_EVENT_CHAIN_OPEN = 2
+    IMPORTED_EVENT_EXPECTED = 22
+    IMPORTED_EVENT_NOT_EXPECTED = 23
+    TIMESTAMP_MUST_BE_ZERO = 3
+    IMPORTED_EVENT_TIMESTAMP_OUT_OF_RANGE = 24
+    IMPORTED_EVENT_TIMESTAMP_MUST_NOT_ADVANCE = 25
+    RESERVED_FIELD = 4
+    RESERVED_FLAG = 5
+    ID_MUST_NOT_BE_ZERO = 6
+    ID_MUST_NOT_BE_INT_MAX = 7
+    EXISTS_WITH_DIFFERENT_FLAGS = 15
+    EXISTS_WITH_DIFFERENT_USER_DATA_128 = 16
+    EXISTS_WITH_DIFFERENT_USER_DATA_64 = 17
+    EXISTS_WITH_DIFFERENT_USER_DATA_32 = 18
+    EXISTS_WITH_DIFFERENT_LEDGER = 19
+    EXISTS_WITH_DIFFERENT_CODE = 20
+    EXISTS = 21
+    FLAGS_ARE_MUTUALLY_EXCLUSIVE = 8
+    DEBITS_PENDING_MUST_BE_ZERO = 9
+    DEBITS_POSTED_MUST_BE_ZERO = 10
+    CREDITS_PENDING_MUST_BE_ZERO = 11
+    CREDITS_POSTED_MUST_BE_ZERO = 12
+    LEDGER_MUST_NOT_BE_ZERO = 13
+    CODE_MUST_NOT_BE_ZERO = 14
+    IMPORTED_EVENT_TIMESTAMP_MUST_NOT_REGRESS = 26
+  end
+
+  module CreateTransferStatus
+    CREATED = 4294967295
+    LINKED_EVENT_FAILED = 1
+    LINKED_EVENT_CHAIN_OPEN = 2
+    IMPORTED_EVENT_EXPECTED = 56
+    IMPORTED_EVENT_NOT_EXPECTED = 57
+    TIMESTAMP_MUST_BE_ZERO = 3
+    IMPORTED_EVENT_TIMESTAMP_OUT_OF_RANGE = 58
+    IMPORTED_EVENT_TIMESTAMP_MUST_NOT_ADVANCE = 59
+    RESERVED_FLAG = 4
+    ID_MUST_NOT_BE_ZERO = 5
+    ID_MUST_NOT_BE_INT_MAX = 6
+    EXISTS_WITH_DIFFERENT_FLAGS = 36
+    EXISTS_WITH_DIFFERENT_PENDING_ID = 40
+    EXISTS_WITH_DIFFERENT_TIMEOUT = 44
+    EXISTS_WITH_DIFFERENT_DEBIT_ACCOUNT_ID = 37
+    EXISTS_WITH_DIFFERENT_CREDIT_ACCOUNT_ID = 38
+    EXISTS_WITH_DIFFERENT_AMOUNT = 39
+    EXISTS_WITH_DIFFERENT_USER_DATA_128 = 41
+    EXISTS_WITH_DIFFERENT_USER_DATA_64 = 42
+    EXISTS_WITH_DIFFERENT_USER_DATA_32 = 43
+    EXISTS_WITH_DIFFERENT_LEDGER = 67
+    EXISTS_WITH_DIFFERENT_CODE = 45
+    EXISTS = 46
+    ID_ALREADY_FAILED = 68
+    FLAGS_ARE_MUTUALLY_EXCLUSIVE = 7
+    DEBIT_ACCOUNT_ID_MUST_NOT_BE_ZERO = 8
+    DEBIT_ACCOUNT_ID_MUST_NOT_BE_INT_MAX = 9
+    CREDIT_ACCOUNT_ID_MUST_NOT_BE_ZERO = 10
+    CREDIT_ACCOUNT_ID_MUST_NOT_BE_INT_MAX = 11
+    ACCOUNTS_MUST_BE_DIFFERENT = 12
+    PENDING_ID_MUST_BE_ZERO = 13
+    PENDING_ID_MUST_NOT_BE_ZERO = 14
+    PENDING_ID_MUST_NOT_BE_INT_MAX = 15
+    PENDING_ID_MUST_BE_DIFFERENT = 16
+    TIMEOUT_RESERVED_FOR_PENDING_TRANSFER = 17
+    CLOSING_TRANSFER_MUST_BE_PENDING = 64
+    LEDGER_MUST_NOT_BE_ZERO = 19
+    CODE_MUST_NOT_BE_ZERO = 20
+    DEBIT_ACCOUNT_NOT_FOUND = 21
+    CREDIT_ACCOUNT_NOT_FOUND = 22
+    ACCOUNTS_MUST_HAVE_THE_SAME_LEDGER = 23
+    TRANSFER_MUST_HAVE_THE_SAME_LEDGER_AS_ACCOUNTS = 24
+    PENDING_TRANSFER_NOT_FOUND = 25
+    PENDING_TRANSFER_NOT_PENDING = 26
+    PENDING_TRANSFER_HAS_DIFFERENT_DEBIT_ACCOUNT_ID = 27
+    PENDING_TRANSFER_HAS_DIFFERENT_CREDIT_ACCOUNT_ID = 28
+    PENDING_TRANSFER_HAS_DIFFERENT_LEDGER = 29
+    PENDING_TRANSFER_HAS_DIFFERENT_CODE = 30
+    EXCEEDS_PENDING_TRANSFER_AMOUNT = 31
+    PENDING_TRANSFER_HAS_DIFFERENT_AMOUNT = 32
+    PENDING_TRANSFER_ALREADY_POSTED = 33
+    PENDING_TRANSFER_ALREADY_VOIDED = 34
+    PENDING_TRANSFER_EXPIRED = 35
+    IMPORTED_EVENT_TIMESTAMP_MUST_NOT_REGRESS = 60
+    IMPORTED_EVENT_TIMESTAMP_MUST_POSTDATE_DEBIT_ACCOUNT = 61
+    IMPORTED_EVENT_TIMESTAMP_MUST_POSTDATE_CREDIT_ACCOUNT = 62
+    IMPORTED_EVENT_TIMEOUT_MUST_BE_ZERO = 63
+    DEBIT_ACCOUNT_ALREADY_CLOSED = 65
+    CREDIT_ACCOUNT_ALREADY_CLOSED = 66
+    OVERFLOWS_DEBITS_PENDING = 47
+    OVERFLOWS_CREDITS_PENDING = 48
+    OVERFLOWS_DEBITS_POSTED = 49
+    OVERFLOWS_CREDITS_POSTED = 50
+    OVERFLOWS_DEBITS = 51
+    OVERFLOWS_CREDITS = 52
+    OVERFLOWS_TIMEOUT = 53
+    EXCEEDS_CREDITS = 54
+    EXCEEDS_DEBITS = 55
+  end
+
+  class Account
+    attr_accessor :id
+    attr_accessor :debits_pending
+    attr_accessor :debits_posted
+    attr_accessor :credits_pending
+    attr_accessor :credits_posted
+    attr_accessor :user_data_128
+    attr_accessor :user_data_64
+    attr_accessor :user_data_32
+    attr_accessor :ledger
+    attr_accessor :code
+    attr_accessor :flags
+    attr_accessor :timestamp
+
+    def initialize(
+      id: 0,
+      debits_pending: 0,
+      debits_posted: 0,
+      credits_pending: 0,
+      credits_posted: 0,
+      user_data_128: 0,
+      user_data_64: 0,
+      user_data_32: 0,
+      ledger: 0,
+      code: 0,
+      flags: AccountFlags::NONE,
+      timestamp: 0
+    )
+      @id = id
+      @debits_pending = debits_pending
+      @debits_posted = debits_posted
+      @credits_pending = credits_pending
+      @credits_posted = credits_posted
+      @user_data_128 = user_data_128
+      @user_data_64 = user_data_64
+      @user_data_32 = user_data_32
+      @ledger = ledger
+      @code = code
+      @flags = flags
+      @timestamp = timestamp
+    end
+  end
+
+  class Transfer
+    attr_accessor :id
+    attr_accessor :debit_account_id
+    attr_accessor :credit_account_id
+    attr_accessor :amount
+    attr_accessor :pending_id
+    attr_accessor :user_data_128
+    attr_accessor :user_data_64
+    attr_accessor :user_data_32
+    attr_accessor :timeout
+    attr_accessor :ledger
+    attr_accessor :code
+    attr_accessor :flags
+    attr_accessor :timestamp
+
+    def initialize(
+      id: 0,
+      debit_account_id: 0,
+      credit_account_id: 0,
+      amount: 0,
+      pending_id: 0,
+      user_data_128: 0,
+      user_data_64: 0,
+      user_data_32: 0,
+      timeout: 0,
+      ledger: 0,
+      code: 0,
+      flags: TransferFlags::NONE,
+      timestamp: 0
+    )
+      @id = id
+      @debit_account_id = debit_account_id
+      @credit_account_id = credit_account_id
+      @amount = amount
+      @pending_id = pending_id
+      @user_data_128 = user_data_128
+      @user_data_64 = user_data_64
+      @user_data_32 = user_data_32
+      @timeout = timeout
+      @ledger = ledger
+      @code = code
+      @flags = flags
+      @timestamp = timestamp
+    end
+  end
+
+  class AccountFilter
+    attr_accessor :account_id
+    attr_accessor :user_data_128
+    attr_accessor :user_data_64
+    attr_accessor :user_data_32
+    attr_accessor :code
+    attr_accessor :timestamp_min
+    attr_accessor :timestamp_max
+    attr_accessor :limit
+    attr_accessor :flags
+
+    def initialize(
+      account_id: 0,
+      user_data_128: 0,
+      user_data_64: 0,
+      user_data_32: 0,
+      code: 0,
+      timestamp_min: 0,
+      timestamp_max: 0,
+      limit: 0,
+      flags: AccountFilterFlags::NONE
+    )
+      @account_id = account_id
+      @user_data_128 = user_data_128
+      @user_data_64 = user_data_64
+      @user_data_32 = user_data_32
+      @code = code
+      @timestamp_min = timestamp_min
+      @timestamp_max = timestamp_max
+      @limit = limit
+      @flags = flags
+    end
+  end
+
+  class QueryFilter
+    attr_accessor :user_data_128
+    attr_accessor :user_data_64
+    attr_accessor :user_data_32
+    attr_accessor :ledger
+    attr_accessor :code
+    attr_accessor :timestamp_min
+    attr_accessor :timestamp_max
+    attr_accessor :limit
+    attr_accessor :flags
+
+    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: 0,
+      flags: QueryFilterFlags::NONE
+    )
+      @user_data_128 = user_data_128
+      @user_data_64 = user_data_64
+      @user_data_32 = user_data_32
+      @ledger = ledger
+      @code = code
+      @timestamp_min = timestamp_min
+      @timestamp_max = timestamp_max
+      @limit = limit
+      @flags = flags
+    end
+  end
+
+  class AccountBalance
+    attr_reader :debits_pending
+    attr_reader :debits_posted
+    attr_reader :credits_pending
+    attr_reader :credits_posted
+    attr_reader :timestamp
+
+    def initialize
+      @debits_pending = 0
+      @debits_posted = 0
+      @credits_pending = 0
+      @credits_posted = 0
+      @timestamp = 0
+    end
+  end
+
+  class CreateAccountResult
+    attr_reader :timestamp
+    attr_reader :status
+    attr_reader :status_name
+
+    def initialize
+      @timestamp = 0
+      @status = 0
+    end
+
+    def to_s =
+      "#<#{self.class} timestamp=#{@timestamp} status_name=#{@status_name}>"
+  end
+
+  class CreateTransferResult
+    attr_reader :timestamp
+    attr_reader :status
+    attr_reader :status_name
+
+    def initialize
+      @timestamp = 0
+      @status = 0
+    end
+
+    def to_s =
+      "#<#{self.class} timestamp=#{@timestamp} status_name=#{@status_name}>"
+  end
+
+end

data/src/tigerbeetle/client.rb

@@ -0,0 +1,129 @@
+module TigerBeetle
+  # TigerBeetle client.
+  #
+  # A client can be shared by concurrent threads and fibers for request methods.
+  # Public request methods are synchronous and return after the request
+  # completes. When a fiber scheduler is active, waiting for a response yields
+  # to the scheduler.
+  #
+  # Prefer {.open} for lifecycle management so the client is closed once after
+  # concurrent work completes. Instantiate multiple clients when connecting to
+  # more than one TigerBeetle cluster.
+  class Client
+    Client::COMPLETION_DISPATCHER = CompletionDispatcher.new
+    private_constant :COMPLETION_DISPATCHER
+
+    # Opens a client for the duration of the block and closes it before
+    # returning.
+    #
+    # Yields the open client and returns the block return value.
+    def self.open(cluster_id:, replica_addresses:)
+      client = new(cluster_id: cluster_id, replica_addresses: replica_addresses)
+      yield client
+    ensure
+      client&.close
+    end
+
+    # Initializes a TigerBeetle client.
+    #
+    # @raise [TigerBeetle::InitError] if the native client cannot be
+    #   initialized.
+    def initialize(cluster_id:, replica_addresses:)
+      @native = NativeClient.new(cluster_id, replica_addresses, COMPLETION_DISPATCHER.write_fileno)
+      @closed = false
+    end
+
+    # Closes the client. This method waits for all in-flight requests to finish.
+    #
+    # @raise [TigerBeetle::ClientClosedError] if the client is already closed.
+    def close
+      raise ClientClosedError, "client is already closed" if closed?
+
+      @closed = true
+      @native.close
+    end
+
+    # Returns whether the client has been closed.
+    def closed?
+      @closed
+    end
+
+    # Submits a batch of new accounts to be created.
+    #
+    # The returned array contains one {TigerBeetle::CreateAccountResult} for
+    # each submitted account.
+    #
+    # @raise [TigerBeetle::PacketError] if the entire request fails.
+    # @raise [TigerBeetle::ClientClosedError] if the client is closed.
+    def create_accounts(accounts) = native_submit(Operation::CREATE_ACCOUNTS, accounts)
+
+    # Submits a batch of new transfers to be created.
+    #
+    # The returned array contains one {TigerBeetle::CreateTransferResult} for
+    # each submitted transfer.
+    #
+    # @raise [TigerBeetle::PacketError] if the entire request fails.
+    # @raise [TigerBeetle::ClientClosedError] if the client is closed.
+    def create_transfers(transfers) = native_submit(Operation::CREATE_TRANSFERS, transfers)
+
+    # Looks up a batch of accounts.
+    #
+    # The returned array contains all accounts found. Accounts not found are
+    # omitted.
+    #
+    # @raise [TigerBeetle::PacketError] if the entire request fails.
+    # @raise [TigerBeetle::ClientClosedError] if the client is closed.
+    def lookup_accounts(ids) = native_submit(Operation::LOOKUP_ACCOUNTS, ids)
+
+    # Looks up a batch of transfers.
+    #
+    # The returned array contains all transfers found. Transfers not found are
+    # omitted.
+    #
+    # @raise [TigerBeetle::PacketError] if the entire request fails.
+    # @raise [TigerBeetle::ClientClosedError] if the client is closed.
+    def lookup_transfers(ids) = native_submit(Operation::LOOKUP_TRANSFERS, ids)
+
+    # Fetches transfers from a given account.
+    #
+    # Returns transfers that match the query parameters.
+    # @raise [TigerBeetle::PacketError] if the entire request fails.
+    # @raise [TigerBeetle::ClientClosedError] if the client is closed.
+    def get_account_transfers(filter) = native_submit(Operation::GET_ACCOUNT_TRANSFERS, [filter])
+
+    # Fetches balance history from a given account.
+    #
+    # Returns balances that match the query parameters.
+    # @raise [TigerBeetle::PacketError] if the entire request fails.
+    # @raise [TigerBeetle::ClientClosedError] if the client is closed.
+    def get_account_balances(filter) = native_submit(Operation::GET_ACCOUNT_BALANCES, [filter])
+
+    # Queries accounts.
+    #
+    # Returns accounts that match the query parameters.
+    # @raise [TigerBeetle::PacketError] if the entire request fails.
+    # @raise [TigerBeetle::ClientClosedError] if the client is closed.
+    def query_accounts(filter) = native_submit(Operation::QUERY_ACCOUNTS, [filter])
+
+    # Queries transfers.
+    #
+    # Returns transfers that match the query parameters.
+    # @raise [TigerBeetle::PacketError] if the entire request fails.
+    # @raise [TigerBeetle::ClientClosedError] if the client is closed.
+    def query_transfers(filter) = native_submit(Operation::QUERY_TRANSFERS, [filter])
+
+    private
+
+    def native_submit(operation, payload)
+      raise ClientClosedError if closed?
+
+      req = COMPLETION_DISPATCHER.submit_and_wait_for(@native, operation, payload)
+
+      status, result = req.result
+      raise ClientClosedError if status == PACKET_CLIENT_SHUTDOWN
+      raise PacketError, status unless status == PACKET_OK
+
+      result
+    end
+  end
+end

data/src/tigerbeetle/completion_dispatcher.rb

@@ -0,0 +1,108 @@
+module TigerBeetle
+  class CompletionDispatcher
+    COMPLETION_ID_BYTES = 8
+
+    class Completion
+      def initialize
+        @mutex = Mutex.new
+        @condition = ConditionVariable.new
+        @done = false
+      end
+
+      def done?
+        @done
+      end
+
+      def wait
+        @mutex.synchronize { @condition.wait(@mutex) until done? }
+      end
+
+      def complete
+        @mutex.synchronize do
+          @done = true
+          @condition.broadcast
+        end
+      end
+    end
+
+    def initialize
+      @read_io, @write_io = IO.pipe
+      @pending = {}
+      @completed_ids = {}
+      @cancelled_ids = {}
+      @mutex = Mutex.new
+      @thread = Thread.new { dispatch_completions }
+    end
+
+    def write_fileno
+      @write_io.fileno
+    end
+
+    def completion_for(request_id)
+      completion = Completion.new
+      completion.complete if register(request_id, completion)
+      completion
+    end
+
+    def submit_and_wait_for(native, operation, payload)
+      request = native.submit(operation, payload)
+      completion = completion_for(request.id)
+      completion.wait
+      request
+    ensure
+      unregister(request.id, completion) if request
+    end
+
+    def unregister(request_id, completion)
+      @mutex.synchronize do
+        @pending.delete(request_id)
+        @completed_ids.delete(request_id)
+        @cancelled_ids[request_id] = true unless completion&.done?
+      end
+    end
+
+    private
+
+    def register(request_id, completion)
+      @mutex.synchronize do
+        if @completed_ids.delete(request_id)
+          true
+        else
+          @pending[request_id] = completion
+          false
+        end
+      end
+    end
+
+    def dispatch_completions
+      loop do
+        request_id = read_completion_id
+        completion = @mutex.synchronize do
+          completion = @pending[request_id]
+          if completion
+            completion
+          elsif @cancelled_ids.delete(request_id)
+            nil
+          else
+            @completed_ids[request_id] = true
+            nil
+          end
+        end
+
+        completion&.complete
+      end
+
+    rescue IOError, ClientClosedError
+      nil
+    end
+
+    def read_completion_id
+      bytes = @read_io.read(COMPLETION_ID_BYTES)
+      raise ClientClosedError unless bytes
+
+      bytes.unpack1("Q")
+    end
+  end
+
+  private_constant :CompletionDispatcher
+end

data/src/tigerbeetle/id.rb

@@ -0,0 +1,40 @@
+require "securerandom"
+
+module TigerBeetle
+  class ID
+    RANDOM_MAX = 2 ** 80
+    TIMESTAMP_MAX = 2 ** 48
+
+    def initialize
+      @last_ms = Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond)
+      @random = next_random
+    end
+
+    def generate
+      ms = Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond)
+      if ms <= @last_ms
+        ms = @last_ms
+      else
+        @last_ms = ms
+        @random = next_random
+      end
+
+      @random += 1
+      if @random >= RANDOM_MAX
+        @last_ms += 1
+        raise "Timestamp bits overflow on monotonic increment" if @last_ms >= TIMESTAMP_MAX
+        @random = 0
+      end
+
+      (@last_ms << 80) | @random
+    end
+
+    private
+
+    def next_random
+      # See: https://docs.ruby-lang.org/en/4.0/language/packed_data_rdoc.html#label-For+Integers
+      lo, hi = SecureRandom.bytes(10).unpack("Q<S<")
+      lo | (hi << 64)
+    end
+  end
+end

data/src/tigerbeetle/tb.rb

@@ -0,0 +1,3 @@
+require "tigerbeetle"
+
+TB = TigerBeetle

data/src/tigerbeetle/version.rb

@@ -0,0 +1,3 @@
+module TigerBeetle
+  VERSION = "0.17.9"
+end

data/src/tigerbeetle.rb

@@ -0,0 +1,39 @@
+require_relative "tigerbeetle/version"
+require_relative "tigerbeetle/bindings"
+require_relative "tigerbeetle/id"
+require_relative "tigerbeetle/completion_dispatcher"
+require_relative "tigerbeetle/client"
+
+native_extension = "tigerbeetle/tigerbeetle"
+
+# Since we ship a fat binary gem, enable the bundled DLL path before loading the extension.
+if Gem.win_platform?
+  dll_path = File.expand_path("ext/tigerbeetle/lib/x86_64-windows", __dir__)
+
+  begin
+    require "ruby_installer/runtime"
+    RubyInstaller::Runtime.add_dll_directory(dll_path) do
+      require native_extension
+    end
+  rescue LoadError
+    old_path = ENV["PATH"]
+    ENV["PATH"] = "#{dll_path};#{old_path}"
+    require native_extension
+  ensure
+    ENV["PATH"] = old_path if defined?(old_path)
+  end
+else
+  require native_extension
+end
+
+module TigerBeetle
+  private_constant :NativeClient
+  private_constant :Request
+
+  @id_generator = ID.new
+
+  # Generates a 128-bit, time-based, monotonically increasing ID.
+  def self.id
+    @id_generator.generate
+  end
+end