tigerbeetle 0.0.34 → 0.0.37

data/ext/tb_client/tigerbeetle/src/clients/rust/rust_bindings.zig

@@ -0,0 +1,305 @@
+const std = @import("std");
+const vsr = @import("vsr");
+const exports = vsr.tb_client.exports;
+const assert = std.debug.assert;
+
+const type_mappings = .{
+    .{ exports.tb_account_flags, "TB_ACCOUNT_FLAGS" },
+    .{ exports.tb_account_t, "tb_account_t" },
+    .{ exports.tb_transfer_flags, "TB_TRANSFER_FLAGS" },
+    .{ exports.tb_transfer_t, "tb_transfer_t" },
+    .{ exports.tb_create_account_result, "TB_CREATE_ACCOUNT_RESULT" },
+    .{ exports.tb_create_transfer_result, "TB_CREATE_TRANSFER_RESULT" },
+    .{ exports.tb_create_accounts_result_t, "tb_create_accounts_result_t" },
+    .{ exports.tb_create_transfers_result_t, "tb_create_transfers_result_t" },
+    .{ exports.tb_account_filter_t, "tb_account_filter_t" },
+    .{ exports.tb_account_filter_flags, "TB_ACCOUNT_FILTER_FLAGS" },
+    .{ exports.tb_account_balance_t, "tb_account_balance_t" },
+    .{ exports.tb_query_filter_t, "tb_query_filter_t" },
+    .{ exports.tb_query_filter_flags, "TB_QUERY_FILTER_FLAGS" },
+    .{
+        exports.tb_client_t, "tb_client_t",
+        \\// Opaque struct serving as a handle for the client instance.
+        \\// This struct must be "pinned" (not copyable or movable), as its address must remain stable
+        \\// throughout the lifetime of the client instance.
+    },
+    .{
+        exports.tb_packet_t, "tb_packet_t",
+        \\// Struct containing the state of a request submitted through the client.
+        \\// This struct must be "pinned" (not copyable or movable), as its address must remain stable
+        \\// throughout the lifetime of the request.
+    },
+    .{ exports.tb_operation, "TB_OPERATION" },
+    .{ exports.tb_packet_status, "TB_PACKET_STATUS" },
+    .{ exports.tb_init_status, "TB_INIT_STATUS" },
+    .{ exports.tb_client_status, "TB_CLIENT_STATUS" },
+    .{ exports.tb_register_log_callback_status, "TB_REGISTER_LOG_CALLBACK_STATUS" },
+    .{ exports.tb_log_level, "TB_LOG_LEVEL" },
+};
+
+fn resolve_rust_type(comptime Type: type) []const u8 {
+    switch (@typeInfo(Type)) {
+        .array => |info| return resolve_rust_type(info.child),
+        .@"enum" => |info| return resolve_rust_type(info.tag_type),
+        .@"struct" => return resolve_rust_type(std.meta.Int(.unsigned, @bitSizeOf(Type))),
+        .bool => return "u8", // todo "bool"
+        .int => |info| {
+            assert(info.signedness == .unsigned);
+            return switch (info.bits) {
+                8 => "u8",
+                16 => "u16",
+                32 => "u32",
+                64 => "u64",
+                128 => "u128",
+                else => @compileError("invalid int type"),
+            };
+        },
+        .optional => |info| switch (@typeInfo(info.child)) {
+            .pointer => return resolve_rust_type(info.child),
+            else => @compileError("Unsupported optional type: " ++ @typeName(Type)),
+        },
+        .pointer => |info| {
+            assert(info.size != .slice);
+            assert(!info.is_allowzero);
+
+            inline for (type_mappings) |type_mapping| {
+                const ZigType = type_mapping[0];
+                const c_name = type_mapping[1];
+
+                if (info.child == ZigType) {
+                    return "*mut " ++ c_name;
+                }
+            }
+
+            return comptime "*mut " ++ resolve_rust_type(info.child);
+        },
+        .void, .@"opaque" => return "::std::os::raw::c_void",
+        else => @compileError("Unhandled type: " ++ @typeName(Type)),
+    }
+}
+
+fn to_uppercase(comptime input: []const u8) [input.len]u8 {
+    comptime var output: [input.len]u8 = undefined;
+    inline for (&output, 0..) |*char, i| {
+        char.* = input[i];
+        char.* -= 32 * @as(u8, @intFromBool(char.* >= 'a' and char.* <= 'z'));
+    }
+    return output;
+}
+
+fn emit_enum(
+    buffer: *std.ArrayList(u8),
+    comptime Type: type,
+    comptime type_info: anytype,
+    comptime rust_name: []const u8,
+    comptime skip_fields: []const []const u8,
+) !void {
+    var suffix_pos = std.mem.lastIndexOf(u8, rust_name, "_").?;
+    if (std.mem.count(u8, rust_name, "_") == 1) suffix_pos = rust_name.len;
+
+    const backing_type = switch (@typeInfo(Type)) {
+        .@"struct" => |s| s.backing_integer.?,
+        .@"enum" => |e| e.tag_type,
+        else => @panic("unexpected"),
+    };
+    const rust_backing_type_str = switch (@typeInfo(backing_type)) {
+        .int => |i| brk: {
+            break :brk switch (i.bits) {
+                32 => switch (i.signedness) {
+                    .unsigned => "u32",
+                    .signed => "i32",
+                },
+                16 => "u16",
+                8 => "u8",
+                else => @panic("unexpected"),
+            };
+        },
+        else => @panic("unexpected"),
+    };
+
+    try buffer.writer().print("pub type {s} = {s};\n", .{ rust_name, rust_backing_type_str });
+
+    inline for (type_info.fields, 0..) |field, i| {
+        if (comptime std.mem.startsWith(u8, field.name, "deprecated_")) continue;
+        comptime var skip = false;
+        inline for (skip_fields) |sf| {
+            skip = skip or comptime std.mem.eql(u8, sf, field.name);
+        }
+
+        if (!skip) {
+            const field_name = to_uppercase(field.name);
+            if (@typeInfo(Type) == .@"enum") {
+                try buffer.writer().print("pub const {s}_{s}_{s}: {s} = {};\n", .{
+                    rust_name,
+                    rust_name[0..suffix_pos],
+                    @as([]const u8, &field_name),
+                    rust_name,
+                    @intFromEnum(@field(Type, field.name)),
+                });
+            } else {
+                // Packed structs.
+                try buffer.writer().print("pub const {s}_{s}_{s}: {s} = 1 << {};\n", .{
+                    rust_name,
+                    rust_name[0..suffix_pos],
+                    @as([]const u8, &field_name),
+                    rust_name,
+                    i,
+                });
+            }
+        }
+    }
+
+    try buffer.writer().print("\n", .{});
+}
+
+fn emit_struct(
+    buffer: *std.ArrayList(u8),
+    comptime type_info: anytype,
+    comptime rust_name: []const u8,
+) !void {
+    try buffer.writer().print("#[repr(C)]\n", .{});
+    try buffer.writer().print("#[derive(Debug, Copy, Clone)]\n", .{});
+    try buffer.writer().print("pub struct {s} {{\n", .{rust_name});
+
+    inline for (type_info.fields) |field| {
+        switch (@typeInfo(field.type)) {
+            .array => |array| {
+                try buffer.writer().print("    pub {s}: [{s}; {}]", .{
+                    field.name,
+                    resolve_rust_type(field.type),
+                    array.len,
+                });
+            },
+            else => {
+                try buffer.writer().print("    pub {s}: {s}", .{
+                    field.name,
+                    resolve_rust_type(field.type),
+                });
+            },
+        }
+
+        try buffer.writer().print(",\n", .{});
+    }
+
+    try buffer.writer().print("}}\n\n", .{});
+}
+
+pub fn main() !void {
+    var arena = std.heap.ArenaAllocator.init(std.heap.page_allocator);
+    defer arena.deinit();
+    const allocator = arena.allocator();
+
+    var buffer = std.ArrayList(u8).init(allocator);
+    try buffer.writer().print(
+        \\ //////////////////////////////////////////////////////////
+        \\ // This file was auto-generated by tb_client_header.zig //
+        \\ //              Do not manually modify.                 //
+        \\ //////////////////////////////////////////////////////////
+        \\
+        \\
+    , .{});
+
+    inline for (type_mappings) |type_mapping| {
+        const ZigType = type_mapping[0];
+        const rust_name = type_mapping[1];
+        if (type_mapping.len == 3) {
+            const comments: []const u8 = type_mapping[2];
+            try buffer.writer().print(comments, .{});
+            try buffer.writer().print("\n", .{});
+        }
+
+        switch (@typeInfo(ZigType)) {
+            .@"struct" => |info| switch (info.layout) {
+                .auto => @compileError("Invalid C struct type: " ++ @typeName(ZigType)),
+                .@"packed" => try emit_enum(&buffer, ZigType, info, rust_name, &.{"padding"}),
+                .@"extern" => try emit_struct(&buffer, info, rust_name),
+            },
+            .@"enum" => |info| {
+                try emit_enum(&buffer, ZigType, info, rust_name, &.{});
+            },
+            else => try buffer.writer().print("pub type {s} = {s};\n\n", .{
+                rust_name,
+                resolve_rust_type(ZigType),
+            }),
+        }
+    }
+
+    try buffer.writer().print(
+        \\extern "C" {{
+        \\    // Initialize a new TigerBeetle client which connects to the addresses provided and
+        \\    // completes submitted packets by invoking the callback with the given context.
+        \\    pub fn tb_client_init(
+        \\        client_out: *mut tb_client_t,
+        \\        // 128-bit unsigned integer represented as a 16-byte little-endian array.
+        \\        cluster_id: *const [u8; 16],
+        \\        address_ptr: *const ::std::os::raw::c_char,
+        \\        address_len: u32,
+        \\        completion_ctx: usize,
+        \\        completion_callback: ::std::option::Option<
+        \\            unsafe extern "C" fn(
+        \\                arg1: usize,
+        \\                arg3: *mut tb_packet_t,
+        \\                arg4: u64,
+        \\                arg5: *const u8,
+        \\                arg6: u32,
+        \\            ),
+        \\        >,
+        \\    ) -> TB_INIT_STATUS;
+        \\
+        \\    // Initialize a new TigerBeetle client which echos back any data submitted.
+        \\    pub fn tb_client_init_echo(
+        \\        client_out: *mut tb_client_t,
+        \\        // 128-bit unsigned integer represented as a 16-byte little-endian array.
+        \\        cluster_id: *const [u8; 16],
+        \\        address_ptr: *const ::std::os::raw::c_char,
+        \\        address_len: u32,
+        \\        completion_ctx: usize,
+        \\        completion_callback: ::std::option::Option<
+        \\            unsafe extern "C" fn(
+        \\                arg1: usize,
+        \\                arg3: *mut tb_packet_t,
+        \\                arg4: u64,
+        \\                arg5: *const u8,
+        \\                arg6: u32,
+        \\            ),
+        \\        >,
+        \\    ) -> TB_INIT_STATUS;
+        \\
+        \\    // Retrieve the callback context initially passed into `tb_client_init` or
+        \\    // `tb_client_init_echo`.
+        \\    pub fn tb_client_completion_context(
+        \\        client: *mut tb_client_t,
+        \\        completion_ctx_out: *mut usize,
+        \\    ) -> TB_CLIENT_STATUS;
+        \\
+        \\    // Submit a packet with its operation, data, and data_size fields set.
+        \\    // Once completed, `on_completion` will be invoked with `on_completion_ctx` and the given
+        \\    // packet on the `tb_client` thread (separate from caller's thread).
+        \\    pub fn tb_client_submit(
+        \\        client: *mut tb_client_t,
+        \\        packet: *mut tb_packet_t,
+        \\    ) -> TB_CLIENT_STATUS;
+        \\
+        \\    // Closes the client, causing any previously submitted packets to be completed with
+        \\    // `TB_PACKET_CLIENT_SHUTDOWN` before freeing any allocated client resources from init.
+        \\    // It is undefined behavior to use any functions on the client once deinit is called.
+        \\    pub fn tb_client_deinit(
+        \\        client: *mut tb_client_t,
+        \\    ) -> TB_CLIENT_STATUS;
+        \\
+        \\    // Registers or unregisters the application log callback.
+        \\    pub fn register_log_callback(
+        \\        callback: ::std::option::Option<
+        \\            unsafe extern "C" fn(
+        \\                TB_LOG_LEVEL,
+        \\                *const u8,
+        \\                u32,
+        \\            ),
+        \\        >,
+        \\        debug: bool,
+        \\    ) -> TB_REGISTER_LOG_CALLBACK_STATUS;
+        \\}}
+    , .{});
+
+    try std.io.getStdOut().writeAll(buffer.items);
+}

data/ext/tb_client/tigerbeetle/src/config.zig

@@ -0,0 +1,296 @@
+//! Raw configuration values.
+//!
+//! Code which needs these values should use `constants.zig` instead.
+//! Configuration values are set from a combination of:
+//! - default values
+//! - `root.tigerbeetle_config`
+//! - `@import("tigerbeetle_options")`
+
+const builtin = @import("builtin");
+const std = @import("std");
+const stdx = @import("stdx");
+const assert = std.debug.assert;
+
+const root = @import("root");
+
+const KiB = stdx.KiB;
+const MiB = stdx.MiB;
+const GiB = stdx.GiB;
+const TiB = stdx.TiB;
+
+const BuildOptions = struct {
+    config_verify: bool,
+    git_commit: ?[40]u8,
+    release: []const u8,
+    release_client_min: []const u8,
+};
+
+// Allow setting build-time config either via `build.zig` `Options`, or via a struct in the root
+// file.
+const build_options: BuildOptions = blk: {
+    const vsr_options =
+        if (@hasDecl(root, "vsr_options"))
+            root.vsr_options
+        else
+            @import("vsr_options");
+
+    // Both the root file and Zig's `addOptions` expose the struct as identical structurally,
+    // but a different type from a nominal typing perspective.
+    var result: BuildOptions = undefined;
+    for (std.meta.fields(BuildOptions)) |field| {
+        @field(result, field.name) = launder_type(
+            field.type,
+            @field(vsr_options, field.name),
+        );
+    }
+    break :blk result;
+};
+
+fn launder_type(comptime T: type, comptime value: anytype) T {
+    if (T == bool or
+        T == []const u8 or
+        T == ?[]const u8 or
+        T == ?[40]u8)
+    {
+        return value;
+    }
+    if (@typeInfo(T) == .@"enum") {
+        assert(@typeInfo(@TypeOf(value)) == .@"enum" or @typeInfo(@TypeOf(value)) == .enum_literal);
+        return @field(T, @tagName(value));
+    }
+    unreachable;
+}
+
+const vsr = @import("vsr.zig");
+const sector_size = @import("constants.zig").sector_size;
+
+pub const Config = struct {
+    pub const Cluster = ConfigCluster;
+    pub const Process = ConfigProcess;
+
+    cluster: ConfigCluster,
+    process: ConfigProcess,
+
+    /// Returns true if the configuration is intended for "production".
+    /// Intended solely for extra sanity-checks: all meaningful decisions should be driven by
+    /// specific fields of the config.
+    pub fn is_production(config: *const Config) bool {
+        return config.cluster.journal_slot_count > ConfigCluster.journal_slot_count_min;
+    }
+};
+
+/// Configurations which are tunable per-replica (or per-client).
+/// - Replica configs need not equal each other.
+/// - Client configs need not equal each other.
+/// - Client configs need not equal replica configs.
+/// - Replica configs can change between restarts.
+///
+/// Fields are documented within constants.zig.
+// TODO: Some of these could be runtime parameters (e.g. grid_scrubber_cycle_ms).
+const ConfigProcess = struct {
+    log_level: std.log.Level = .info,
+    verify: bool,
+    release: vsr.Release = vsr.Release.minimum,
+    release_client_min: vsr.Release = vsr.Release.minimum,
+    git_commit: ?[40]u8 = null,
+    port: u16 = 3001,
+    address: []const u8 = "127.0.0.1",
+    storage_size_limit_default: u64 = 16 * TiB,
+    storage_size_limit_max: u64 = 64 * TiB,
+    memory_size_max_default: u64 = GiB,
+    cache_accounts_size_default: u64,
+    cache_transfers_size_default: u64,
+    cache_transfers_pending_size_default: u64,
+    client_request_queue_max: u32 = 2,
+    lsm_manifest_node_size: u64 = 16 * KiB,
+    connection_delay_min_ms: u64 = 50,
+    connection_delay_max_ms: u64 = 1000,
+    tcp_backlog: u31 = 64,
+    tcp_rcvbuf: c_int = 4 * MiB,
+    tcp_keepalive: bool = true,
+    tcp_keepidle: c_int = 5,
+    tcp_keepintvl: c_int = 4,
+    tcp_keepcnt: c_int = 3,
+    tcp_nodelay: bool = true,
+    direct_io: bool,
+    journal_iops_read_max: u32 = 8,
+    journal_iops_write_max: u32 = 32,
+    client_replies_iops_read_max: u32 = 1,
+    client_replies_iops_write_max: u32 = 2,
+    client_request_completion_warn_ms: u64 = 200,
+    tick_ms: u63 = 10,
+    rtt_ms: u64 = 300,
+    rtt_max_ms: u64 = 1000 * 60,
+    rtt_multiple: u8 = 2,
+    backoff_min_ms: u64 = 10,
+    backoff_max_ms: u64 = 10000,
+    clock_offset_tolerance_max_ms: u64 = 10000,
+    clock_epoch_max_ms: u64 = 60000,
+    clock_synchronization_window_min_ms: u64 = 2000,
+    clock_synchronization_window_max_ms: u64 = 20000,
+    grid_iops_read_max: u64 = 32,
+    grid_iops_write_max: u64 = 32,
+    grid_cache_size_default: u64 = GiB,
+    grid_repair_request_max: u32 = 4,
+    grid_repair_reads_max: u32 = 4,
+    grid_missing_blocks_max: u32 = 30,
+    grid_missing_tables_max: u32 = 6,
+    grid_scrubber_reads_max: u32 = 1,
+    grid_scrubber_cycle_ms: u64 = std.time.ms_per_day * 180,
+    grid_scrubber_interval_ms_min: u64 = std.time.ms_per_s / 20,
+    grid_scrubber_interval_ms_max: u64 = std.time.ms_per_s * 10,
+    multiversion_binary_platform_size_max: u64 = 64 * MiB,
+    multiversion_poll_interval_ms: u64 = 1000,
+};
+
+/// Configurations which are tunable per-cluster.
+/// - All replicas within a cluster must have the same configuration.
+/// - Replicas must reuse the same configuration when the binary is upgraded — they do not change
+///   over the cluster lifetime.
+/// - The storage formats generated by different ConfigClusters are incompatible.
+///
+/// Fields are documented within constants.zig.
+const ConfigCluster = struct {
+    cache_line_size: comptime_int = 64,
+    clients_max: u32,
+    pipeline_prepare_queue_max: u32 = 8,
+    view_change_headers_suffix_max: u32 = 8 + 1,
+    quorum_replication_max: u8 = 3,
+    journal_slot_count: u32 = 1024,
+    message_size_max: u32 = 1 * MiB,
+    superblock_copies: comptime_int = 4,
+    block_size: comptime_int = 512 * KiB,
+    lsm_levels: u6 = 7,
+    lsm_growth_factor: u32 = 8,
+    lsm_compaction_ops: comptime_int = 32,
+    lsm_snapshots_max: u32 = 32,
+    lsm_manifest_compact_extra_blocks: comptime_int = 1,
+    lsm_table_coalescing_threshold_percent: comptime_int = 50,
+    vsr_releases_max: u32 = 64,
+
+    /// Minimal value.
+    // TODO(batiati): Maybe this constant should be derived from `grid_iops_read_max`,
+    // since each scan can read from `lsm_levels` in parallel.
+    lsm_scans_max: comptime_int = 6,
+
+    /// The WAL requires at least two sectors of redundant headers — otherwise we could lose them
+    /// all to a single torn write. A replica needs at least one valid redundant header to
+    /// determine an (untrusted) maximum op in recover_torn_prepare(), without which it cannot
+    /// truncate a torn prepare.
+    pub const journal_slot_count_min = 2 * @divExact(sector_size, @sizeOf(vsr.Header));
+
+    pub const clients_max_min = 1;
+
+    /// The smallest possible message_size_max (for use in the simulator to improve performance).
+    /// The message body must have room for pipeline_prepare_queue_max headers in the DVC.
+    pub fn message_size_max_min(clients_max: u32) u32 {
+        return @max(
+            sector_size,
+            std.mem.alignForward(
+                u32,
+                @sizeOf(vsr.Header) + clients_max * @sizeOf(vsr.Header),
+                sector_size,
+            ),
+        );
+    }
+
+    /// Fingerprint of the cluster-wide configuration.
+    /// It is used to assert that all cluster members share the same config.
+    pub fn checksum(comptime config: ConfigCluster) u128 {
+        @setEvalBranchQuota(10_000);
+        comptime var config_bytes: []const u8 = &.{};
+        comptime for (std.meta.fields(ConfigCluster)) |field| {
+            const value = @field(config, field.name);
+            const value_64 = @as(u64, value);
+            assert(builtin.target.cpu.arch.endian() == .little);
+            config_bytes = config_bytes ++ std.mem.asBytes(&value_64);
+        };
+        return vsr.checksum(config_bytes);
+    }
+};
+
+pub const ConfigBase = enum {
+    production,
+    test_min,
+    default,
+};
+
+pub const configs = struct {
+    /// A good default config for production.
+    pub const default_production = Config{
+        .process = .{
+            .direct_io = true,
+            .cache_accounts_size_default = @sizeOf(vsr.tigerbeetle.Account) * MiB,
+            .cache_transfers_size_default = 0,
+            .cache_transfers_pending_size_default = 0,
+            .verify = true,
+        },
+        .cluster = .{
+            .clients_max = 64,
+        },
+    };
+
+    /// Minimal test configuration — small WAL, small grid block size, etc.
+    /// Not suitable for production, but good for testing code that would be otherwise hard to
+    /// reach.
+    pub const test_min = Config{
+        .process = .{
+            .storage_size_limit_default = 1 * GiB,
+            .storage_size_limit_max = 1 * GiB,
+            .direct_io = false,
+            .cache_accounts_size_default = @sizeOf(vsr.tigerbeetle.Account) * 256,
+            .cache_transfers_size_default = 0,
+            .cache_transfers_pending_size_default = 0,
+            .journal_iops_read_max = 3,
+            .journal_iops_write_max = 2,
+            .grid_repair_request_max = 4,
+            .grid_repair_reads_max = 4,
+            .grid_missing_blocks_max = 3,
+            .grid_missing_tables_max = 2,
+            .grid_scrubber_reads_max = 2,
+            .grid_scrubber_cycle_ms = std.time.ms_per_hour,
+            .verify = true,
+        },
+        .cluster = .{
+            .clients_max = 4 + 3,
+            .pipeline_prepare_queue_max = 4,
+            .view_change_headers_suffix_max = 4 + 1,
+            .journal_slot_count = Config.Cluster.journal_slot_count_min,
+            .message_size_max = Config.Cluster.message_size_max_min(4),
+
+            .block_size = sector_size,
+            .lsm_compaction_ops = 4,
+            .lsm_growth_factor = 4,
+            // (This is higher than the production default value because the block size is smaller.)
+            .lsm_manifest_compact_extra_blocks = 5,
+            // (We need to fuzz more scans merge than in production.)
+            .lsm_scans_max = 12,
+        },
+    };
+
+    pub const current = current: {
+        var base = if (@hasDecl(root, "tigerbeetle_config"))
+            root.tigerbeetle_config
+        else if (builtin.is_test)
+            test_min
+        else
+            default_production;
+
+        const release = vsr.ReleaseTriple.parse(build_options.release) catch {
+            @compileError("invalid release version");
+        };
+
+        const release_client_min = vsr.ReleaseTriple.parse(build_options.release_client_min) catch {
+            @compileError("invalid release_client_min version");
+        };
+
+        base.process.release = vsr.Release.from(release);
+        base.process.release_client_min = vsr.Release.from(release_client_min);
+        base.process.git_commit = build_options.git_commit;
+        base.process.verify = build_options.config_verify;
+
+        assert(base.process.release.value >= base.process.release_client_min.value);
+
+        break :current base;
+    };
+};