tigerbeetle 0.0.40 → 0.17.8

data/docs/migration.md

@@ -0,0 +1,201 @@
+# TigerBeetle gem migration guide
+
+Between 0.0.x and 0.x.y the TigerBeetle gem changed from a third-party client
+developed by [Anthony D](https://github.com/antstorm) to an official client
+maintained by TigerBeetle. Thank you, Anthony!
+
+While the overall API remains similar, some changes were made to provide an
+experience that's more consistent with the official clients for other languages.
+
+- [Client changes](#client-changes)
+  - [Connecting](#connecting)
+  - [Callback API](#callback-api)
+  - [Splat parameters](#splat-parameters)
+  - [Flag handling](#flag-handling)
+  - [Returned objects](#returned-objects)
+  - [Exception classes](#exception-classes)
+  - [Logging](#logging)
+  - [`TB` top-level alias](#tb-top-level-alias)
+- [Licensing](#licensing)
+
+## Client changes
+
+### Connecting
+
+The `TigerBeetle.connect` method has been removed and `TigerBeetle::Client.new`
+no longer provides default arguments.
+
+```rb
+# Before
+client = TigerBeetle.connect # using default cluster_id (0) and address (127.0.0.1:3000)
+
+# After
+client = TigerBeetle::Client.new(cluster_id: 0, replica_addresses: "127.0.0.1:3000")
+```
+
+The preferred way to manage the client's lifecycle is `TigerBeetle::Client.open`,
+which will automatically close the connection when it is no longer needed:
+
+```rb
+replica_addresses = ENV.fetch("TB_ADDRESS", "3000")
+
+TigerBeetle::Client.open(cluster_id: 0, replica_addresses:) do |client|
+  # Use the client.
+end
+```
+
+When manually managing the client's lifecycle, `client.close` replaces the old
+`client.deinit`.
+
+See ["Creating a Client"](../README.md#creating-a-client) for details.
+
+### Callback API
+
+The callback-based async API has been removed. `TigerBeetle::Client` is now
+fiber-scheduler aware and works with the [`async`](https://github.com/socketry/async)
+gem out of the box.
+
+```rb
+# Before
+client.lookup_accounts(100) do |result|
+  result # [#<struct TigerBeetle::Account id=100, ... >]
+end
+
+# After
+semaphore = Async::Semaphore.new(16)
+
+account_batches = [...] # set up account batches
+
+TigerBeetle::Client.open(cluster_id: 0, replica_addresses: "3000") do |client|
+  Async do
+    account_batches
+      .map { |batch| semaphore.async { client.create_accounts(batch) } }
+      .each(&:wait)
+  end
+end
+```
+
+### Splat parameters
+
+All methods that previously took splat parameters now require explicit arrays:
+
+```rb
+# Before
+account_1, account_2 = client.lookup_accounts(100, 101)
+
+# After
+account_1, account_2 = client.lookup_accounts([100, 101])
+```
+
+### Flag handling
+
+All flags are now explicit numeric constants combined with `|`, not symbol arrays.
+
+```rb
+# Before
+filter = TigerBeetle::AccountFilter.new(
+  account_id: 100,
+  limit: 10,
+  flags: [:DEBITS, :CREDITS]
+)
+
+transfers = client.get_account_transfers(filter)
+
+# After
+filter = TigerBeetle::AccountFilter.new(
+  account_id: 100,
+  limit: 10,
+  flags: TigerBeetle::AccountFilterFlags::DEBITS |
+    TigerBeetle::AccountFilterFlags::CREDITS
+)
+
+transfers = client.get_account_transfers(filter)
+```
+
+### Timestamp attributes
+
+All timestamp attributes have changed type from `Time` to `Integer` representing
+nanoseconds since UNIX epoch.
+
+```rb
+# Before
+account.timestamp
+# => 2026-06-22 11:49:05 1382929/2097152 +0100
+
+# After
+account.timestamp
+# => 1782125345659431936
+```
+
+Affected attributes:
+
+```
+TigerBeetle::Account#timestamp
+TigerBeetle::AccountBalance#timestamp
+TigerBeetle::AccountFilter#timestamp_min
+TigerBeetle::AccountFilter#timestamp_max
+TigerBeetle::QueryFilter#timestamp_min
+TigerBeetle::QueryFilter#timestamp_max
+TigerBeetle::Transfer#timestamp
+```
+
+### Returned objects
+
+Returned objects have changed from `FFI::Struct`/`Struct`-style objects to
+regular Ruby classes, so `[]` no longer works for accessing fields.
+
+```rb
+# Before
+account[:debits_posted]
+
+# After
+account.debits_posted
+```
+
+The return types of create operations also changed from two-element arrays to
+result objects:
+
+```rb
+# Before
+index, status = result
+
+# After
+result.timestamp
+result.status
+```
+
+### Exception classes
+
+There was a change to the exception classes raised by the gem.
+
+```rb
+# Before
+StandardError
+  TigerBeetle::Error
+    TigerBeetle::ClientError
+
+# After
+StandardError
+  TigerBeetle::InitError
+  TigerBeetle::ClientClosedError
+  TigerBeetle::PacketError
+```
+
+### Logging
+
+The `client.logger=` API has been removed. Any logging should happen in the
+surrounding application code.
+
+### `TB` top-level alias
+
+The new gem provides a top-level `TB` alias which can be enabled as follows:
+
+```rb
+require "tigerbeetle/tb"
+
+account = TB::Account.new(id: TB.id, ledger: 1, code: 1)
+```
+
+## Licensing
+
+No licensing changes have been made. The gem remains under the [Apache License, Version 2.0](../LICENSE).

data/sig/tigerbeetle.rbs

@@ -0,0 +1,271 @@
+########################################################
+## This file was auto-generated by ruby_bindings.zig ##
+##              Do not manually modify.              ##
+########################################################
+
+module TigerBeetle
+  VERSION: String
+
+  def self.id: () -> Integer
+
+  class InitError < StandardError
+  end
+
+  class ClientClosedError < StandardError
+  end
+
+  class PacketError < StandardError
+  end
+
+  class Client
+    def self.open: (cluster_id: Integer, replica_addresses: String) { (Client) -> untyped } -> untyped
+
+    def initialize: (cluster_id: Integer, replica_addresses: String) -> void
+    def close: () -> nil
+    def closed?: () -> bool
+
+    def create_accounts: (Array[Account]) -> Array[CreateAccountResult]
+    def create_transfers: (Array[Transfer]) -> Array[CreateTransferResult]
+    def lookup_accounts: (Array[Integer]) -> Array[Account]
+    def lookup_transfers: (Array[Integer]) -> Array[Transfer]
+    def get_account_transfers: (AccountFilter) -> Array[Transfer]
+    def get_account_balances: (AccountFilter) -> Array[AccountBalance]
+    def query_accounts: (QueryFilter) -> Array[Account]
+    def query_transfers: (QueryFilter) -> Array[Transfer]
+  end
+
+  module AccountFlags
+    NONE: Integer
+    LINKED: Integer
+    DEBITS_MUST_NOT_EXCEED_CREDITS: Integer
+    CREDITS_MUST_NOT_EXCEED_DEBITS: Integer
+    HISTORY: Integer
+    IMPORTED: Integer
+    CLOSED: Integer
+  end
+
+  module TransferFlags
+    NONE: Integer
+    LINKED: Integer
+    PENDING: Integer
+    POST_PENDING_TRANSFER: Integer
+    VOID_PENDING_TRANSFER: Integer
+    BALANCING_DEBIT: Integer
+    BALANCING_CREDIT: Integer
+    CLOSING_DEBIT: Integer
+    CLOSING_CREDIT: Integer
+    IMPORTED: Integer
+  end
+
+  module AccountFilterFlags
+    NONE: Integer
+    DEBITS: Integer
+    CREDITS: Integer
+    REVERSED: Integer
+  end
+
+  module QueryFilterFlags
+    NONE: Integer
+    REVERSED: Integer
+  end
+
+  module Operation
+    LOOKUP_ACCOUNTS: Integer
+    LOOKUP_TRANSFERS: Integer
+    GET_ACCOUNT_TRANSFERS: Integer
+    GET_ACCOUNT_BALANCES: Integer
+    QUERY_ACCOUNTS: Integer
+    QUERY_TRANSFERS: Integer
+    CREATE_ACCOUNTS: Integer
+    CREATE_TRANSFERS: Integer
+  end
+
+  module CreateAccountStatus
+    CREATED: Integer
+    LINKED_EVENT_FAILED: Integer
+    LINKED_EVENT_CHAIN_OPEN: Integer
+    IMPORTED_EVENT_EXPECTED: Integer
+    IMPORTED_EVENT_NOT_EXPECTED: Integer
+    TIMESTAMP_MUST_BE_ZERO: Integer
+    IMPORTED_EVENT_TIMESTAMP_OUT_OF_RANGE: Integer
+    IMPORTED_EVENT_TIMESTAMP_MUST_NOT_ADVANCE: Integer
+    RESERVED_FIELD: Integer
+    RESERVED_FLAG: Integer
+    ID_MUST_NOT_BE_ZERO: Integer
+    ID_MUST_NOT_BE_INT_MAX: Integer
+    EXISTS_WITH_DIFFERENT_FLAGS: Integer
+    EXISTS_WITH_DIFFERENT_USER_DATA_128: Integer
+    EXISTS_WITH_DIFFERENT_USER_DATA_64: Integer
+    EXISTS_WITH_DIFFERENT_USER_DATA_32: Integer
+    EXISTS_WITH_DIFFERENT_LEDGER: Integer
+    EXISTS_WITH_DIFFERENT_CODE: Integer
+    EXISTS: Integer
+    FLAGS_ARE_MUTUALLY_EXCLUSIVE: Integer
+    DEBITS_PENDING_MUST_BE_ZERO: Integer
+    DEBITS_POSTED_MUST_BE_ZERO: Integer
+    CREDITS_PENDING_MUST_BE_ZERO: Integer
+    CREDITS_POSTED_MUST_BE_ZERO: Integer
+    LEDGER_MUST_NOT_BE_ZERO: Integer
+    CODE_MUST_NOT_BE_ZERO: Integer
+    IMPORTED_EVENT_TIMESTAMP_MUST_NOT_REGRESS: Integer
+  end
+
+  module CreateTransferStatus
+    CREATED: Integer
+    LINKED_EVENT_FAILED: Integer
+    LINKED_EVENT_CHAIN_OPEN: Integer
+    IMPORTED_EVENT_EXPECTED: Integer
+    IMPORTED_EVENT_NOT_EXPECTED: Integer
+    TIMESTAMP_MUST_BE_ZERO: Integer
+    IMPORTED_EVENT_TIMESTAMP_OUT_OF_RANGE: Integer
+    IMPORTED_EVENT_TIMESTAMP_MUST_NOT_ADVANCE: Integer
+    RESERVED_FLAG: Integer
+    ID_MUST_NOT_BE_ZERO: Integer
+    ID_MUST_NOT_BE_INT_MAX: Integer
+    EXISTS_WITH_DIFFERENT_FLAGS: Integer
+    EXISTS_WITH_DIFFERENT_PENDING_ID: Integer
+    EXISTS_WITH_DIFFERENT_TIMEOUT: Integer
+    EXISTS_WITH_DIFFERENT_DEBIT_ACCOUNT_ID: Integer
+    EXISTS_WITH_DIFFERENT_CREDIT_ACCOUNT_ID: Integer
+    EXISTS_WITH_DIFFERENT_AMOUNT: Integer
+    EXISTS_WITH_DIFFERENT_USER_DATA_128: Integer
+    EXISTS_WITH_DIFFERENT_USER_DATA_64: Integer
+    EXISTS_WITH_DIFFERENT_USER_DATA_32: Integer
+    EXISTS_WITH_DIFFERENT_LEDGER: Integer
+    EXISTS_WITH_DIFFERENT_CODE: Integer
+    EXISTS: Integer
+    ID_ALREADY_FAILED: Integer
+    FLAGS_ARE_MUTUALLY_EXCLUSIVE: Integer
+    DEBIT_ACCOUNT_ID_MUST_NOT_BE_ZERO: Integer
+    DEBIT_ACCOUNT_ID_MUST_NOT_BE_INT_MAX: Integer
+    CREDIT_ACCOUNT_ID_MUST_NOT_BE_ZERO: Integer
+    CREDIT_ACCOUNT_ID_MUST_NOT_BE_INT_MAX: Integer
+    ACCOUNTS_MUST_BE_DIFFERENT: Integer
+    PENDING_ID_MUST_BE_ZERO: Integer
+    PENDING_ID_MUST_NOT_BE_ZERO: Integer
+    PENDING_ID_MUST_NOT_BE_INT_MAX: Integer
+    PENDING_ID_MUST_BE_DIFFERENT: Integer
+    TIMEOUT_RESERVED_FOR_PENDING_TRANSFER: Integer
+    CLOSING_TRANSFER_MUST_BE_PENDING: Integer
+    LEDGER_MUST_NOT_BE_ZERO: Integer
+    CODE_MUST_NOT_BE_ZERO: Integer
+    DEBIT_ACCOUNT_NOT_FOUND: Integer
+    CREDIT_ACCOUNT_NOT_FOUND: Integer
+    ACCOUNTS_MUST_HAVE_THE_SAME_LEDGER: Integer
+    TRANSFER_MUST_HAVE_THE_SAME_LEDGER_AS_ACCOUNTS: Integer
+    PENDING_TRANSFER_NOT_FOUND: Integer
+    PENDING_TRANSFER_NOT_PENDING: Integer
+    PENDING_TRANSFER_HAS_DIFFERENT_DEBIT_ACCOUNT_ID: Integer
+    PENDING_TRANSFER_HAS_DIFFERENT_CREDIT_ACCOUNT_ID: Integer
+    PENDING_TRANSFER_HAS_DIFFERENT_LEDGER: Integer
+    PENDING_TRANSFER_HAS_DIFFERENT_CODE: Integer
+    EXCEEDS_PENDING_TRANSFER_AMOUNT: Integer
+    PENDING_TRANSFER_HAS_DIFFERENT_AMOUNT: Integer
+    PENDING_TRANSFER_ALREADY_POSTED: Integer
+    PENDING_TRANSFER_ALREADY_VOIDED: Integer
+    PENDING_TRANSFER_EXPIRED: Integer
+    IMPORTED_EVENT_TIMESTAMP_MUST_NOT_REGRESS: Integer
+    IMPORTED_EVENT_TIMESTAMP_MUST_POSTDATE_DEBIT_ACCOUNT: Integer
+    IMPORTED_EVENT_TIMESTAMP_MUST_POSTDATE_CREDIT_ACCOUNT: Integer
+    IMPORTED_EVENT_TIMEOUT_MUST_BE_ZERO: Integer
+    DEBIT_ACCOUNT_ALREADY_CLOSED: Integer
+    CREDIT_ACCOUNT_ALREADY_CLOSED: Integer
+    OVERFLOWS_DEBITS_PENDING: Integer
+    OVERFLOWS_CREDITS_PENDING: Integer
+    OVERFLOWS_DEBITS_POSTED: Integer
+    OVERFLOWS_CREDITS_POSTED: Integer
+    OVERFLOWS_DEBITS: Integer
+    OVERFLOWS_CREDITS: Integer
+    OVERFLOWS_TIMEOUT: Integer
+    EXCEEDS_CREDITS: Integer
+    EXCEEDS_DEBITS: Integer
+  end
+
+  class Account
+    attr_accessor id: Integer
+    attr_accessor debits_pending: Integer
+    attr_accessor debits_posted: Integer
+    attr_accessor credits_pending: Integer
+    attr_accessor credits_posted: Integer
+    attr_accessor user_data_128: Integer
+    attr_accessor user_data_64: Integer
+    attr_accessor user_data_32: Integer
+    attr_accessor ledger: Integer
+    attr_accessor code: Integer
+    attr_accessor flags: Integer
+    attr_accessor timestamp: Integer
+
+    def initialize: (?id: Integer, ?debits_pending: Integer, ?debits_posted: Integer, ?credits_pending: Integer, ?credits_posted: Integer, ?user_data_128: Integer, ?user_data_64: Integer, ?user_data_32: Integer, ?ledger: Integer, ?code: Integer, ?flags: Integer, ?timestamp: Integer) -> void
+  end
+
+  class Transfer
+    attr_accessor id: Integer
+    attr_accessor debit_account_id: Integer
+    attr_accessor credit_account_id: Integer
+    attr_accessor amount: Integer
+    attr_accessor pending_id: Integer
+    attr_accessor user_data_128: Integer
+    attr_accessor user_data_64: Integer
+    attr_accessor user_data_32: Integer
+    attr_accessor timeout: Integer
+    attr_accessor ledger: Integer
+    attr_accessor code: Integer
+    attr_accessor flags: Integer
+    attr_accessor timestamp: Integer
+
+    def initialize: (?id: Integer, ?debit_account_id: Integer, ?credit_account_id: Integer, ?amount: Integer, ?pending_id: Integer, ?user_data_128: Integer, ?user_data_64: Integer, ?user_data_32: Integer, ?timeout: Integer, ?ledger: Integer, ?code: Integer, ?flags: Integer, ?timestamp: Integer) -> void
+  end
+
+  class AccountFilter
+    attr_accessor account_id: Integer
+    attr_accessor user_data_128: Integer
+    attr_accessor user_data_64: Integer
+    attr_accessor user_data_32: Integer
+    attr_accessor code: Integer
+    attr_accessor timestamp_min: Integer
+    attr_accessor timestamp_max: Integer
+    attr_accessor limit: Integer
+    attr_accessor flags: Integer
+
+    def initialize: (?account_id: Integer, ?user_data_128: Integer, ?user_data_64: Integer, ?user_data_32: Integer, ?code: Integer, ?timestamp_min: Integer, ?timestamp_max: Integer, ?limit: Integer, ?flags: Integer) -> void
+  end
+
+  class QueryFilter
+    attr_accessor user_data_128: Integer
+    attr_accessor user_data_64: Integer
+    attr_accessor user_data_32: Integer
+    attr_accessor ledger: Integer
+    attr_accessor code: Integer
+    attr_accessor timestamp_min: Integer
+    attr_accessor timestamp_max: Integer
+    attr_accessor limit: Integer
+    attr_accessor flags: Integer
+
+    def initialize: (?user_data_128: Integer, ?user_data_64: Integer, ?user_data_32: Integer, ?ledger: Integer, ?code: Integer, ?timestamp_min: Integer, ?timestamp_max: Integer, ?limit: Integer, ?flags: Integer) -> void
+  end
+
+  class AccountBalance
+    attr_reader debits_pending: Integer
+    attr_reader debits_posted: Integer
+    attr_reader credits_pending: Integer
+    attr_reader credits_posted: Integer
+    attr_reader timestamp: Integer
+
+    def initialize: () -> void
+  end
+
+  class CreateAccountResult
+    attr_reader timestamp: Integer
+    attr_reader status: Integer
+
+    def initialize: () -> void
+  end
+
+  class CreateTransferResult
+    attr_reader timestamp: Integer
+    attr_reader status: Integer
+
+    def initialize: () -> void
+  end
+
+end

data/src/ext/tigerbeetle/extconf.rb

@@ -0,0 +1,47 @@
+require "mkmf"
+require "rbconfig"
+
+arch = RbConfig::CONFIG["target_cpu"]
+target_os = RbConfig::CONFIG["target_os"]
+
+platform_arch =
+  case arch
+  when "x64", "x86_64"
+    "x86_64"
+  when "arm64", "aarch64"
+    "aarch64"
+  else
+    raise "Unsupported architecture #{arch.inspect}"
+  end
+
+platform_os =
+  case target_os
+  when /linux/
+    host_os = RbConfig::CONFIG["host_os"]
+
+    if host_os.include?("musl") || target_os.include?("musl")
+      "linux-musl"
+    else
+      "linux-gnu*"
+    end
+  when /darwin/
+    "macos"
+  when /mingw|mswin/
+    raise "Unsupported Windows architecture #{arch.inspect}" unless platform_arch == "x86_64"
+
+    "windows"
+  else
+    raise "Unsupported operating system #{target_os.inspect}"
+  end
+
+platform = "#{platform_arch}-#{platform_os}"
+
+platform_dir = Dir.glob(File.join(__dir__, "lib", platform)).first
+raise "No prebuilt libtb_client found for #{arch}-#{target_os}" unless platform_dir
+
+$DLDFLAGS << " -Wl,-rpath,#{platform_dir}" if target_os.match?(/darwin/)
+
+dir_config("tb_client", __dir__, platform_dir)
+have_library("tb_client") or raise("libtb_client not found")
+
+create_makefile("tigerbeetle/tigerbeetle")