tigerbeetle-node 0.5.1 → 0.8.0

package/src/tigerbeetle/src/tigerbeetle.zig

@@ -6,18 +6,18 @@ pub const config = @import("config.zig");
 
 pub const Account = packed struct {
     id: u128,
-    /// Opaque third-party identifier to link this account (many-to-one) to an external entity:
+    /// Opaque third-party identifier to link this account (many-to-one) to an external entity.
     user_data: u128,
-    /// Reserved for accounting policy primitives:
+    /// Reserved for accounting policy primitives.
     reserved: [48]u8,
-    unit: u16,
-    /// A chart of accounts code describing the type of account (e.g. clearing, settlement):
+    ledger: u32,
+    /// A chart of accounts code describing the type of account (e.g. clearing, settlement).
     code: u16,
     flags: AccountFlags,
-    debits_reserved: u64,
-    debits_accepted: u64,
-    credits_reserved: u64,
-    credits_accepted: u64,
+    debits_pending: u64,
+    debits_posted: u64,
+    credits_pending: u64,
+    credits_posted: u64,
     timestamp: u64 = 0,
 
     comptime {
@@ -26,12 +26,12 @@ pub const Account = packed struct {
 
     pub fn debits_exceed_credits(self: *const Account, amount: u64) bool {
         return (self.flags.debits_must_not_exceed_credits and
-            self.debits_reserved + self.debits_accepted + amount > self.credits_accepted);
+            self.debits_pending + self.debits_posted + amount > self.credits_posted);
     }
 
     pub fn credits_exceed_debits(self: *const Account, amount: u64) bool {
         return (self.flags.credits_must_not_exceed_debits and
-            self.credits_reserved + self.credits_accepted + amount > self.debits_accepted);
+            self.credits_pending + self.credits_posted + amount > self.debits_posted);
     }
 };
 
@@ -49,10 +49,10 @@ pub const AccountFlags = packed struct {
     linked: bool = false,
     debits_must_not_exceed_credits: bool = false,
     credits_must_not_exceed_debits: bool = false,
-    padding: u29 = 0,
+    padding: u13 = 0,
 
     comptime {
-        assert(@sizeOf(AccountFlags) == @sizeOf(u32));
+        assert(@sizeOf(AccountFlags) == @sizeOf(u16));
     }
 };
 
@@ -60,13 +60,16 @@ pub const Transfer = packed struct {
     id: u128,
     debit_account_id: u128,
     credit_account_id: u128,
-    /// Opaque third-party identifier to link this transfer (many-to-one) to an external entity:
+    /// Opaque third-party identifier to link this transfer (many-to-one) to an external entity.
     user_data: u128,
-    /// Reserved for accounting policy primitives:
-    reserved: [32]u8,
+    /// Reserved for accounting policy primitives.
+    reserved: u128,
+    /// If this transfer will post or void a pending transfer, the id of that pending transfer.
+    pending_id: u128,
     timeout: u64,
-    /// A chart of accounts code describing the reason for the transfer (e.g. deposit, settlement):
-    code: u32,
+    ledger: u32,
+    /// A chart of accounts code describing the reason for the transfer (e.g. deposit, settlement).
+    code: u16,
     flags: TransferFlags,
     amount: u64,
     timestamp: u64 = 0,
@@ -78,102 +81,113 @@ pub const Transfer = packed struct {
 
 pub const TransferFlags = packed struct {
     linked: bool = false,
-    two_phase_commit: bool = false,
-    condition: bool = false,
-    padding: u29 = 0,
+    pending: bool = false,
+    post_pending_transfer: bool = false,
+    void_pending_transfer: bool = false,
+    padding: u12 = 0,
 
     comptime {
-        assert(@sizeOf(TransferFlags) == @sizeOf(u32));
+        assert(@sizeOf(TransferFlags) == @sizeOf(u16));
     }
 };
 
-pub const Commit = packed struct {
-    id: u128,
-    /// Reserved for accounting policy primitives:
-    reserved: [32]u8,
-    /// A chart of accounts code describing the reason for the accept/reject:
-    code: u32,
-    flags: CommitFlags,
-    timestamp: u64 = 0,
+pub const CreateAccountResult = enum(u32) {
+    ok,
+    linked_event_failed,
 
-    comptime {
-        assert(@sizeOf(Commit) == 64);
-    }
-};
+    reserved_flag,
+    reserved_field,
 
-pub const CommitFlags = packed struct {
-    linked: bool = false,
-    reject: bool = false,
-    preimage: bool = false,
-    padding: u29 = 0,
+    id_must_not_be_zero,
+    ledger_must_not_be_zero,
+    code_must_not_be_zero,
 
-    comptime {
-        assert(@sizeOf(CommitFlags) == @sizeOf(u32));
-    }
-};
+    mutually_exclusive_flags,
+
+    overflows_debits,
+    overflows_credits,
 
-pub const CreateAccountResult = enum(u32) {
-    ok,
-    linked_event_failed,
-    exists,
-    exists_with_different_user_data,
-    exists_with_different_reserved_field,
-    exists_with_different_unit,
-    exists_with_different_code,
-    exists_with_different_flags,
     exceeds_credits,
     exceeds_debits,
-    reserved_field,
-    reserved_flag_padding,
+
+    exists_with_different_flags,
+    exists_with_different_user_data,
+    exists_with_different_ledger,
+    exists_with_different_code,
+    exists_with_different_debits_pending,
+    exists_with_different_debits_posted,
+    exists_with_different_credits_pending,
+    exists_with_different_credits_posted,
+    exists,
 };
 
 pub const CreateTransferResult = enum(u32) {
     ok,
     linked_event_failed,
-    exists,
+
+    reserved_flag,
+    reserved_field,
+
+    id_must_not_be_zero,
+    debit_account_id_must_not_be_zero,
+    credit_account_id_must_not_be_zero,
+    accounts_must_be_different,
+
+    pending_id_must_be_zero,
+    pending_transfer_must_timeout,
+
+    ledger_must_not_be_zero,
+    code_must_not_be_zero,
+    amount_must_not_be_zero,
+
+    debit_account_not_found,
+    credit_account_not_found,
+
+    accounts_must_have_the_same_ledger,
+    transfer_must_have_the_same_ledger_as_accounts,
+
+    exists_with_different_flags,
     exists_with_different_debit_account_id,
     exists_with_different_credit_account_id,
     exists_with_different_user_data,
-    exists_with_different_reserved_field,
+    exists_with_different_pending_id,
+    exists_with_different_timeout,
     exists_with_different_code,
     exists_with_different_amount,
-    exists_with_different_timeout,
-    exists_with_different_flags,
-    exists_and_already_committed_and_accepted,
-    exists_and_already_committed_and_rejected,
-    reserved_field,
-    reserved_flag_padding,
-    debit_account_not_found,
-    credit_account_not_found,
-    accounts_are_the_same,
-    accounts_have_different_units,
-    amount_is_zero,
-    exceeds_credits,
-    exceeds_debits,
-    two_phase_commit_must_timeout,
-    timeout_reserved_for_two_phase_commit,
-};
+    exists,
+
+    overflows_debits_pending,
+    overflows_credits_pending,
+    overflows_debits_posted,
+    overflows_credits_posted,
+    overflows_debits,
+    overflows_credits,
 
-pub const CommitTransferResult = enum(u32) {
-    ok,
-    linked_event_failed,
-    reserved_field,
-    reserved_flag_padding,
-    transfer_not_found,
-    transfer_not_two_phase_commit,
-    transfer_expired,
-    already_committed,
-    already_committed_but_accepted,
-    already_committed_but_rejected,
-    debit_account_not_found,
-    credit_account_not_found,
-    debit_amount_was_not_reserved,
-    credit_amount_was_not_reserved,
     exceeds_credits,
     exceeds_debits,
-    condition_requires_preimage,
-    preimage_requires_condition,
-    preimage_invalid,
+
+    cannot_post_and_void_pending_transfer,
+    pending_transfer_cannot_post_or_void_another,
+    timeout_reserved_for_pending_transfer,
+
+    pending_id_must_not_be_zero,
+    pending_id_must_be_different,
+
+    pending_transfer_not_found,
+    pending_transfer_not_pending,
+
+    pending_transfer_has_different_debit_account_id,
+    pending_transfer_has_different_credit_account_id,
+    pending_transfer_has_different_ledger,
+    pending_transfer_has_different_code,
+
+    exceeds_pending_transfer_amount,
+    pending_transfer_has_different_amount,
+
+    pending_transfer_already_posted,
+    pending_transfer_already_voided,
+
+    pending_transfer_expired,
 };
 
 pub const CreateAccountsResult = packed struct {
@@ -194,22 +208,15 @@ pub const CreateTransfersResult = packed struct {
     }
 };
 
-pub const CommitTransfersResult = packed struct {
-    index: u32,
-    result: CommitTransferResult,
-
-    comptime {
-        assert(@sizeOf(CommitTransfersResult) == 8);
-    }
-};
-
 comptime {
-    if (builtin.target.os.tag != .linux and !builtin.target.isDarwin()) {
-        @compileError("linux or macos required for io");
+    const target = builtin.target;
+
+    if (target.os.tag != .linux and !target.isDarwin() and target.os.tag != .windows) {
+        @compileError("linux, windows or macos is required for io");
     }
 
     // We require little-endian architectures everywhere for efficient network deserialization:
-    if (builtin.target.cpu.arch.endian() != .Little) {
+    if (target.cpu.arch.endian() != .Little) {
         @compileError("big-endian systems not supported");
     }
 }

package/src/tigerbeetle/src/time.zig

@@ -1,9 +1,12 @@
 const std = @import("std");
 const builtin = @import("builtin");
-const assert = std.debug.assert;
-const is_darwin = builtin.target.isDarwin();
 const config = @import("./config.zig");
 
+const os = std.os;
+const assert = std.debug.assert;
+const is_darwin = builtin.target.os.tag.isDarwin();
+const is_windows = builtin.target.os.tag == .windows;
+
 pub const Time = struct {
     const Self = @This();
 
@@ -19,19 +22,44 @@ pub const Time = struct {
     /// system administrator manually changes the clock.
     pub fn monotonic(self: *Self) u64 {
         const m = blk: {
+            // Uses QueryPerformanceCounter() on windows due to it being the highest precision timer
+            // available while also accounting for time spent suspended by default:
+            // https://docs.microsoft.com/en-us/windows/win32/api/realtimeapiset/nf-realtimeapiset-queryunbiasedinterrupttime#remarks
+            if (is_windows) {
+                // QPF need not be globally cached either as it ends up being a load from read-only
+                // memory mapped to all processed by the kernel called KUSER_SHARED_DATA (See "QpcFrequency")
+                // https://docs.microsoft.com/en-us/windows-hardware/drivers/ddi/ntddk/ns-ntddk-kuser_shared_data
+                // https://www.geoffchappell.com/studies/windows/km/ntoskrnl/inc/api/ntexapi_x/kuser_shared_data/index.htm
+                const qpc = os.windows.QueryPerformanceCounter();
+                const qpf = os.windows.QueryPerformanceFrequency();
+
+                // 10Mhz (1 qpc tick every 100ns) is a common QPF on modern systems.
+                // We can optimize towards this by converting to ns via a single multiply.
+                // https://github.com/microsoft/STL/blob/785143a0c73f030238ef618890fd4d6ae2b3a3a0/stl/inc/chrono#L694-L701
+                const common_qpf = 10_000_000;
+                if (qpf == common_qpf) break :blk qpc * (std.time.ns_per_s / common_qpf);
+
+                // Convert qpc to nanos using fixed point to avoid expensive extra divs and overflow.
+                const scale = (std.time.ns_per_s << 32) / qpf;
+                break :blk @truncate(u64, (@as(u96, qpc) * scale) >> 32);
+            }
+
             // Uses mach_continuous_time() instead of mach_absolute_time() as it counts while suspended.
             // https://developer.apple.com/documentation/kernel/1646199-mach_continuous_time
             // https://opensource.apple.com/source/Libc/Libc-1158.1.2/gen/clock_gettime.c.auto.html
             if (is_darwin) {
                 const darwin = struct {
-                    const mach_timebase_info_t = std.os.darwin.mach_timebase_info_data;
-                    extern "c" fn mach_timebase_info(info: *mach_timebase_info_t) std.os.darwin.kern_return_t;
+                    const mach_timebase_info_t = os.darwin.mach_timebase_info_data;
+                    extern "c" fn mach_timebase_info(info: *mach_timebase_info_t) os.darwin.kern_return_t;
                     extern "c" fn mach_continuous_time() u64;
                 };
 
-                const now = darwin.mach_continuous_time();
+                // mach_timebase_info() called through libc already does global caching for us
+                // https://opensource.apple.com/source/xnu/xnu-7195.81.3/libsyscall/wrappers/mach_timebase_info.c.auto.html
                 var info: darwin.mach_timebase_info_t = undefined;
                 if (darwin.mach_timebase_info(&info) != 0) @panic("mach_timebase_info() failed");
+
+                const now = darwin.mach_continuous_time();
                 return (now * info.numer) / info.denom;
             }
 
@@ -40,8 +68,8 @@ pub const Time = struct {
             // CLOCK_BOOTTIME is the same as CLOCK_MONOTONIC but includes elapsed time during a suspend.
             // For more detail and why CLOCK_MONOTONIC_RAW is even worse than CLOCK_MONOTONIC,
             // see https://github.com/ziglang/zig/pull/933#discussion_r656021295.
-            var ts: std.os.timespec = undefined;
-            std.os.clock_gettime(std.os.CLOCK.BOOTTIME, &ts) catch @panic("CLOCK_BOOTTIME required");
+            var ts: os.timespec = undefined;
+            os.clock_gettime(os.CLOCK.BOOTTIME, &ts) catch @panic("CLOCK_BOOTTIME required");
             break :blk @intCast(u64, ts.tv_sec) * std.time.ns_per_s + @intCast(u64, ts.tv_nsec);
         };
 
@@ -54,11 +82,30 @@ pub const Time = struct {
     /// A timestamp to measure real (i.e. wall clock) time, meaningful across systems, and reboots.
     /// This clock is affected by discontinuous jumps in the system time.
     pub fn realtime(_: *Self) i64 {
-        // macos has supported clock_gettime() since 10.12:
-        // https://opensource.apple.com/source/Libc/Libc-1158.1.2/gen/clock_gettime.3.auto.html
+        if (is_windows) {
+            const kernel32 = struct {
+                extern "kernel32" fn GetSystemTimePreciseAsFileTime(
+                    lpFileTime: *os.windows.FILETIME,
+                ) callconv(os.windows.WINAPI) void;
+            };
+
+            var ft: os.windows.FILETIME = undefined;
+            kernel32.GetSystemTimePreciseAsFileTime(&ft);
+            const ft64 = (@as(u64, ft.dwHighDateTime) << 32) | ft.dwLowDateTime;
+
+            // FileTime is in units of 100 nanoseconds
+            // and uses the NTFS/Windows epoch of 1601-01-01 instead of Unix Epoch 1970-01-01.
+            const epoch_adjust = std.time.epoch.windows * (std.time.ns_per_s / 100);
+            return (@bitCast(i64, ft64) + epoch_adjust) * 100;
+        }
+
+        if (is_darwin) {
+            // macos has supported clock_gettime() since 10.12:
+            // https://opensource.apple.com/source/Libc/Libc-1158.1.2/gen/clock_gettime.3.auto.html
+        }
 
-        var ts: std.os.timespec = undefined;
-        std.os.clock_gettime(std.os.CLOCK.REALTIME, &ts) catch unreachable;
+        var ts: os.timespec = undefined;
+        os.clock_gettime(os.CLOCK.REALTIME, &ts) catch unreachable;
         return @as(i64, ts.tv_sec) * std.time.ns_per_s + ts.tv_nsec;
     }
 

package/src/tigerbeetle/src/vsr/client.zig

@@ -7,7 +7,8 @@ const vsr = @import("../vsr.zig");
 const Header = vsr.Header;
 
 const RingBuffer = @import("../ring_buffer.zig").RingBuffer;
-const Message = @import("../message_pool.zig").MessagePool.Message;
+const message_pool = @import("../message_pool.zig");
+const Message = message_pool.MessagePool.Message;
 
 const log = std.log.scoped(.client);
 
@@ -66,8 +67,7 @@ pub fn Client(comptime StateMachine: type, comptime MessageBus: type) type {
 
         /// A client is allowed at most one inflight request at a time at the protocol layer.
         /// We therefore queue any further concurrent requests made by the application layer.
-        /// We must leave one message free to receive with.
-        request_queue: RingBuffer(Request, config.message_bus_messages_max - 1) = .{},
+        request_queue: RingBuffer(Request, config.client_request_queue_max) = .{},
 
         /// The number of ticks without a reply before the client resends the inflight request.
         /// Dynamically adjusted as a function of recent request round-trip time.
@@ -188,25 +188,25 @@ pub fn Client(comptime StateMachine: type, comptime MessageBus: type) type {
                 @tagName(operation),
             });
 
+            if (self.request_queue.full()) {
+                callback(user_data, operation, error.TooManyOutstandingRequests);
+                return;
+            }
+
             const was_empty = self.request_queue.empty();
 
-            self.request_queue.push(.{
+            self.request_queue.push_assume_capacity(.{
                 .user_data = user_data,
                 .callback = callback,
                 .message = message.ref(),
-            }) catch |err| switch (err) {
-                error.NoSpaceLeft => {
-                    callback(user_data, operation, error.TooManyOutstandingRequests);
-                    return;
-                },
-            };
+            });
 
             // If the queue was empty, then there is no request inflight and we must send this one:
             if (was_empty) self.send_request_for_the_first_time(message);
         }
 
         /// Acquires a message from the message bus if one is available.
-        pub fn get_message(self: *Self) ?*Message {
+        pub fn get_message(self: *Self) *Message {
             return self.message_bus.get_message();
         }
 
@@ -383,12 +383,12 @@ pub fn Client(comptime StateMachine: type, comptime MessageBus: type) type {
         }
 
         /// The caller owns the returned message, if any, which has exactly 1 reference.
-        fn create_message_from_header(self: *Self, header: Header) ?*Message {
+        fn create_message_from_header(self: *Self, header: Header) *Message {
             assert(header.client == self.id);
             assert(header.cluster == self.cluster);
             assert(header.size == @sizeOf(Header));
 
-            const message = self.message_bus.pool.get_header_only_message() orelse return null;
+            const message = self.message_bus.pool.get_message();
             defer self.message_bus.unref(message);
 
             message.header.* = header;
@@ -402,8 +402,7 @@ pub fn Client(comptime StateMachine: type, comptime MessageBus: type) type {
         fn register(self: *Self) void {
             if (self.request_number > 0) return;
 
-            var message = self.message_bus.get_message() orelse
-                @panic("register: no message available to register a session with the cluster");
+            const message = self.message_bus.get_message();
             defer self.message_bus.unref(message);
 
             // We will set parent, context, view and checksums only when sending for the first time:
@@ -422,37 +421,24 @@ pub fn Client(comptime StateMachine: type, comptime MessageBus: type) type {
 
             assert(self.request_queue.empty());
 
-            self.request_queue.push(.{
+            self.request_queue.push_assume_capacity(.{
                 .user_data = 0,
                 .callback = undefined,
                 .message = message.ref(),
-            }) catch |err| switch (err) {
-                error.NoSpaceLeft => unreachable, // This is the first request.
-            };
+            });
 
             self.send_request_for_the_first_time(message);
         }
 
         fn send_header_to_replica(self: *Self, replica: u8, header: Header) void {
-            const message = self.create_message_from_header(header) orelse {
-                log.err("{}: no header-only message available, dropping message to replica {}", .{
-                    self.id,
-                    replica,
-                });
-                return;
-            };
+            const message = self.create_message_from_header(header);
             defer self.message_bus.unref(message);
 
             self.send_message_to_replica(replica, message);
         }
 
         fn send_header_to_replicas(self: *Self, header: Header) void {
-            const message = self.create_message_from_header(header) orelse {
-                log.err("{}: no header-only message available, dropping message to replicas", .{
-                    self.id,
-                });
-                return;
-            };
+            const message = self.create_message_from_header(header);
             defer self.message_bus.unref(message);
 
             var replica: u8 = 0;

package/src/tigerbeetle/src/vsr/clock.zig

@@ -744,7 +744,7 @@ test "fuzz test" {
     const allocator = &arena_allocator.allocator;
     const ticks_max: u64 = 1_000_000;
     const clock_count: u8 = 3;
-    const SystemTime = @import("../time.zig").Time;
+    const SystemTime = @import("../test/time.zig").Time;
     var system_time = SystemTime{};
     var seed = @intCast(u64, system_time.realtime());
     var min_sync_error: u64 = 1_000_000_000;

package/src/tigerbeetle/src/vsr/journal.zig

@@ -510,11 +510,7 @@ pub fn Journal(comptime Replica: type, comptime Storage: type) type {
             const physical_size = vsr.sector_ceil(exact.size);
             assert(physical_size >= exact.size);
 
-            const message = replica.message_bus.get_message() orelse {
-                self.read_prepare_log(op, checksum, "no message available");
-                callback(replica, null, null);
-                return;
-            };
+            const message = replica.message_bus.get_message();
             defer replica.message_bus.unref(message);
 
             // Skip the disk read if the header is all we need:
@@ -658,7 +654,7 @@ pub fn Journal(comptime Replica: type, comptime Storage: type) type {
             }
             assert(offset < self.size_headers);
 
-            const message = replica.message_bus.get_message() orelse unreachable;
+            const message = replica.message_bus.get_message();
             defer replica.message_bus.unref(message);
 
             // We use the count of reads executing to know when both versions have finished reading: