tigerbeetle-node 0.10.0 → 0.11.1

package/src/tigerbeetle/src/c/test.zig

@@ -1 +1,371 @@
-// TODO
+const std = @import("std");
+const assert = std.debug.assert;
+
+const testing = std.testing;
+
+const c = @cImport(@cInclude("tb_client.h"));
+
+const util = @import("../util.zig");
+const config = @import("../config.zig");
+const Packet = @import("tb_client/packet.zig").Packet;
+
+const Mutex = std.Thread.Mutex;
+const Condition = std.Thread.Condition;
+
+fn RequestContextType(comptime request_size_max: comptime_int) type {
+    return struct {
+        const Self = @This();
+
+        completion: *Completion,
+        sent_data: [request_size_max]u8 = undefined,
+        sent_data_size: u32,
+        packet: *Packet = undefined,
+        reply: ?struct {
+            tb_context: usize,
+            tb_client: c.tb_client_t,
+            tb_packet: *c.tb_packet_t,
+            result: ?[request_size_max]u8,
+            result_len: u32,
+        } = null,
+
+        pub fn on_complete(
+            tb_context: usize,
+            tb_client: c.tb_client_t,
+            tb_packet: [*c]c.tb_packet_t,
+            result_ptr: [*c]const u8,
+            result_len: u32,
+        ) callconv(.C) void {
+            var self = @ptrCast(*Self, @alignCast(@alignOf(*Self), tb_packet.*.user_data.?));
+            defer self.completion.complete();
+
+            self.reply = .{
+                .tb_context = tb_context,
+                .tb_client = tb_client,
+                .tb_packet = tb_packet,
+                .result = if (result_ptr != null and result_len > 0) blk: {
+                    // Copy the message's body to the context buffer:
+                    assert(result_len <= request_size_max);
+                    var writable: [request_size_max]u8 = undefined;
+                    const readable = @ptrCast([*]const u8, result_ptr.?);
+                    util.copy_disjoint(.inexact, u8, &writable, readable[0..result_len]);
+                    break :blk writable;
+                } else null,
+                .result_len = result_len,
+            };
+        }
+    };
+}
+
+// Notifies the main thread when all pending requests are completed.
+const Completion = struct {
+    const Self = @This();
+
+    pending: usize,
+    mutex: Mutex = .{},
+    cond: Condition = .{},
+
+    pub fn complete(self: *Self) void {
+        self.mutex.lock();
+        defer self.mutex.unlock();
+
+        assert(self.pending > 0);
+        self.pending -= 1;
+        self.cond.signal();
+    }
+
+    pub fn wait_pending(self: *Self) void {
+        self.mutex.lock();
+        defer self.mutex.unlock();
+
+        while (self.pending > 0)
+            self.cond.wait(&self.mutex);
+    }
+};
+
+// When initialized with tb_client_init_echo, the c_client uses a test context that echoes
+// the data back without creating an actual client or connecting to a cluster.
+//
+// This same test should be implemented by all the target programming languages, asserting that:
+// 1. the c_client api was initialized correctly.
+// 2. the application can submit messages and receive replies through the completion callback.
+// 3. the data marshaling is correct, and exactly the same data sent was received back.
+test "c_client echo" {
+    // Using the create_accounts operation for this test.
+    const RequestContext = RequestContextType(config.message_body_size_max);
+    const create_accounts_operation: u8 = c.TB_OP_CREATE_ACCOUNTS;
+    const event_size = @sizeOf(c.tb_account_t);
+    const event_request_max = @divFloor(config.message_body_size_max, event_size);
+
+    // Initializing an echo client for testing purposes.
+    // We ensure that the retry mechanism is being tested
+    // by allowing more simultaneous packets than "client_request_queue_max".
+    var tb_client: c.tb_client_t = undefined;
+    var tb_packet_list: c.tb_packet_list_t = undefined;
+    const cluster_id = 0;
+    const address = "3000";
+    const packets_count: u32 = config.client_request_queue_max * 2;
+    const tb_context: usize = 42;
+    const result = c.tb_client_init_echo(
+        &tb_client,
+        &tb_packet_list,
+        cluster_id,
+        address,
+        @intCast(u32, address.len),
+        packets_count,
+        tb_context,
+        RequestContext.on_complete,
+    );
+
+    try testing.expectEqual(@as(c_uint, c.TB_STATUS_SUCCESS), result);
+    defer c.tb_client_deinit(tb_client);
+
+    var packet_list = @bitCast(Packet.List, tb_packet_list);
+    var prng = std.rand.DefaultPrng.init(tb_context);
+
+    var requests: []RequestContext = try testing.allocator.alloc(RequestContext, packets_count);
+    defer testing.allocator.free(requests);
+
+    // Repeating the same test multiple times to stress the
+    // cycle of message exhaustion followed by completions.
+    const repetitions_max = 100;
+    var repetition: u32 = 0;
+    while (repetition < repetitions_max) : (repetition += 1) {
+        var completion = Completion{ .pending = packets_count };
+
+        // Submitting some random data to be echoed back:
+        for (requests) |*request| {
+            request.* = .{
+                .completion = &completion,
+                .sent_data_size = prng.random().intRangeAtMost(u32, 1, event_request_max) * event_size,
+            };
+            prng.random().bytes(request.sent_data[0..request.sent_data_size]);
+
+            request.packet = blk: {
+                var packet = packet_list.pop().?;
+                packet.operation = create_accounts_operation;
+                packet.user_data = request;
+                packet.data = &request.sent_data;
+                packet.data_size = request.sent_data_size;
+                packet.next = null;
+                packet.status = .ok;
+                break :blk packet;
+            };
+
+            var list = @bitCast(c.tb_packet_list_t, Packet.List.from(request.packet));
+            c.tb_client_submit(tb_client, &list);
+        }
+
+        // Waiting until the c_client thread has processed all submitted requests:
+        completion.wait_pending();
+
+        // Checking if the received echo matches the data we sent:
+        for (requests) |*request| {
+            defer packet_list.push(Packet.List.from(request.packet));
+
+            try testing.expect(request.reply != null);
+            try testing.expectEqual(tb_context, request.reply.?.tb_context);
+            try testing.expectEqual(tb_client, request.reply.?.tb_client);
+            try testing.expectEqual(c.TB_PACKET_OK, @enumToInt(request.packet.status));
+            try testing.expectEqual(@ptrToInt(request.packet), @ptrToInt(request.reply.?.tb_packet));
+            try testing.expect(request.reply.?.result != null);
+            try testing.expectEqual(request.sent_data_size, request.reply.?.result_len);
+
+            const sent_data = request.sent_data[0..request.sent_data_size];
+            const reply = request.reply.?.result.?[0..request.reply.?.result_len];
+            try testing.expectEqualSlices(u8, sent_data, reply);
+        }
+    }
+}
+
+// Asserts the validation rules associated with the "TB_STATUS" enum.
+test "c_client tb_status" {
+    const assert_status = struct {
+        pub fn action(
+            packets_count: u32,
+            addresses: []const u8,
+            expected_status: c_uint,
+        ) !void {
+            var tb_client: c.tb_client_t = undefined;
+            var tb_packet_list: c.tb_packet_list_t = undefined;
+            const cluster_id = 0;
+            const tb_context: usize = 0;
+            const result = c.tb_client_init_echo(
+                &tb_client,
+                &tb_packet_list,
+                cluster_id,
+                addresses.ptr,
+                @intCast(u32, addresses.len),
+                packets_count,
+                tb_context,
+                RequestContextType(0).on_complete,
+            );
+            defer if (result == c.TB_STATUS_SUCCESS) c.tb_client_deinit(tb_client);
+
+            try testing.expectEqual(expected_status, result);
+        }
+    }.action;
+
+    // Valid addresses and packets count should return TB_STATUS_SUCCESS:
+    try assert_status(0, "3000", c.TB_STATUS_SUCCESS);
+    try assert_status(1, "3000", c.TB_STATUS_SUCCESS);
+    try assert_status(32, "127.0.0.1", c.TB_STATUS_SUCCESS);
+    try assert_status(128, "127.0.0.1:3000", c.TB_STATUS_SUCCESS);
+    try assert_status(512, "3000,3001,3002", c.TB_STATUS_SUCCESS);
+    try assert_status(1024, "127.0.0.1,127.0.0.2,172.0.0.3", c.TB_STATUS_SUCCESS);
+    try assert_status(4096, "127.0.0.1:3000,127.0.0.1:3002,127.0.0.1:3003", c.TB_STATUS_SUCCESS);
+
+    // Invalid or empty address should return "TB_STATUS_ADDRESS_INVALID":
+    try assert_status(1, "invalid", c.TB_STATUS_ADDRESS_INVALID);
+    try assert_status(1, "", c.TB_STATUS_ADDRESS_INVALID);
+
+    // More addresses thant "replicas_max" should return "TB_STATUS_ADDRESS_LIMIT_EXCEEDED":
+    try assert_status(
+        1,
+        ("3000," ** config.replicas_max) ++ "3001",
+        c.TB_STATUS_ADDRESS_LIMIT_EXCEEDED,
+    );
+
+    // Packets count greater than 4096 should return "TB_STATUS_INVALID_PACKETS_COUNT":
+    try assert_status(4097, "3000", c.TB_STATUS_PACKETS_COUNT_INVALID);
+    try assert_status(std.math.maxInt(u32), "3000", c.TB_STATUS_PACKETS_COUNT_INVALID);
+
+    // All other status are not testable.
+}
+
+// Asserts the validation rules associated with the "TB_PACKET_STATUS" enum.
+test "c_client tb_packet_status" {
+    const RequestContext = RequestContextType(config.message_body_size_max);
+
+    var tb_client: c.tb_client_t = undefined;
+    var tb_packet_list: c.tb_packet_list_t = undefined;
+    const cluster_id = 0;
+    const address = "3000";
+    const packets_count = 1;
+    const tb_context: usize = 42;
+    const result = c.tb_client_init_echo(
+        &tb_client,
+        &tb_packet_list,
+        cluster_id,
+        address,
+        @intCast(u32, address.len),
+        packets_count,
+        tb_context,
+        RequestContext.on_complete,
+    );
+
+    try testing.expectEqual(@as(c_uint, c.TB_STATUS_SUCCESS), result);
+    defer c.tb_client_deinit(tb_client);
+
+    const assert_result = struct {
+        // Asserts if the packet's status matches the expected status
+        // for a given operation and request_size.
+        pub fn action(
+            client: c.tb_client_t,
+            packet_list: *Packet.List,
+            operation: u8,
+            request_size: u32,
+            tb_packet_status_expected: c_int,
+        ) !void {
+            var completion = Completion{ .pending = 1 };
+            var request = RequestContext{
+                .completion = &completion,
+                .sent_data_size = request_size,
+            };
+
+            request.packet = blk: {
+                var packet = packet_list.pop().?;
+                packet.operation = operation;
+                packet.user_data = &request;
+                packet.data = &request.sent_data;
+                packet.data_size = request_size;
+                packet.next = null;
+                packet.status = .ok;
+                break :blk packet;
+            };
+            defer packet_list.push(Packet.List.from(request.packet));
+
+            var list = @bitCast(c.tb_packet_list_t, Packet.List.from(request.packet));
+            c.tb_client_submit(client, &list);
+
+            completion.wait_pending();
+
+            try testing.expect(request.reply != null);
+            try testing.expectEqual(tb_context, request.reply.?.tb_context);
+            try testing.expectEqual(client, request.reply.?.tb_client);
+            try testing.expectEqual(@ptrToInt(request.packet), @ptrToInt(request.reply.?.tb_packet));
+            try testing.expectEqual(tb_packet_status_expected, @enumToInt(request.packet.status));
+        }
+    }.action;
+
+    var packet_list = @ptrCast(*Packet.List, &tb_packet_list);
+
+    // Messages larger than config.message_body_size_max should return "too_much_data":
+    try assert_result(
+        tb_client,
+        packet_list,
+        c.TB_OP_CREATE_TRANSFERS,
+        config.message_body_size_max + @sizeOf(c.tb_transfer_t),
+        c.TB_PACKET_TOO_MUCH_DATA,
+    );
+
+    // All reserved and unknown operations should return "invalid_operation":
+    try assert_result(
+        tb_client,
+        packet_list,
+        0,
+        @sizeOf(u128),
+        c.TB_PACKET_INVALID_OPERATION,
+    );
+    try assert_result(
+        tb_client,
+        packet_list,
+        1,
+        @sizeOf(u128),
+        c.TB_PACKET_INVALID_OPERATION,
+    );
+    try assert_result(
+        tb_client,
+        packet_list,
+        2,
+        @sizeOf(u128),
+        c.TB_PACKET_INVALID_OPERATION,
+    );
+    try assert_result(
+        tb_client,
+        packet_list,
+        99,
+        @sizeOf(u128),
+        c.TB_PACKET_INVALID_OPERATION,
+    );
+
+    // Messages length 0 or not a multiple of the event size
+    // should return "invalid_data_size":
+    try assert_result(
+        tb_client,
+        packet_list,
+        c.TB_OP_CREATE_ACCOUNTS,
+        0,
+        c.TB_PACKET_INVALID_DATA_SIZE,
+    );
+    try assert_result(
+        tb_client,
+        packet_list,
+        c.TB_OP_CREATE_TRANSFERS,
+        @sizeOf(c.tb_transfer_t) - 1,
+        c.TB_PACKET_INVALID_DATA_SIZE,
+    );
+    try assert_result(
+        tb_client,
+        packet_list,
+        c.TB_OP_LOOKUP_TRANSFERS,
+        @sizeOf(u128) + 1,
+        c.TB_PACKET_INVALID_DATA_SIZE,
+    );
+    try assert_result(
+        tb_client,
+        packet_list,
+        c.TB_OP_LOOKUP_ACCOUNTS,
+        @sizeOf(u128) * 2.5,
+        c.TB_PACKET_INVALID_DATA_SIZE,
+    );
+}

package/src/tigerbeetle/src/cli.zig

@@ -20,13 +20,17 @@ const usage = fmt.comptimePrint(
     \\
     \\  tigerbeetle start --addresses=<addresses> <path>
     \\
+    \\  tigerbeetle version [--version]
+    \\
     \\Commands:
     \\
-    \\  format  Create a TigerBeetle replica data file at <path>.
-    \\          The --cluster and --replica arguments are required.
-    \\          Each TigerBeetle replica must have its own data file.
+    \\  format   Create a TigerBeetle replica data file at <path>.
+    \\           The --cluster and --replica arguments are required.
+    \\           Each TigerBeetle replica must have its own data file.
+    \\
+    \\  start    Run a TigerBeetle replica from the data file at <path>.
     \\
-    \\  start   Run a TigerBeetle replica from the data file at <path>.
+    \\  version  Print the TigerBeetle build version and the compile-time config values.
     \\
     \\Options:
     \\
@@ -46,6 +50,10 @@ const usage = fmt.comptimePrint(
     \\        Either the IPv4 address or port number (but not both) may be omitted,
     \\        in which case a default of {[default_address]s} or {[default_port]d}
     \\        will be used.
+    \\        "addresses[i]" corresponds to replica "i".
+    \\
+    \\  --verbose
+    \\        Print compile-time configuration along with the build version.
     \\
     \\Examples:
     \\
@@ -59,6 +67,8 @@ const usage = fmt.comptimePrint(
     \\
     \\  tigerbeetle start --addresses=192.168.0.1,192.168.0.2,192.168.0.3 7_0.tigerbeetle
     \\
+    \\  tigerbeetle version --verbose
+    \\
 , .{
     .default_address = config.address,
     .default_port = config.port,
@@ -77,11 +87,15 @@ pub const Command = union(enum) {
         memory: u64,
         path: [:0]const u8,
     },
+    version: struct {
+        verbose: bool,
+    },
 
     pub fn deinit(command: Command, allocator: std.mem.Allocator) void {
         var args_allocated = switch (command) {
             .format => |cmd| cmd.args_allocated,
             .start => |cmd| cmd.args_allocated,
+            .version => return,
         };
 
         for (args_allocated.items) |arg| allocator.free(arg);
@@ -97,6 +111,7 @@ pub fn parse_args(allocator: std.mem.Allocator) !Command {
     var replica: ?[]const u8 = null;
     var addresses: ?[]const u8 = null;
     var memory: ?[]const u8 = null;
+    var verbose: ?bool = null;
 
     var args = try std.process.argsWithAllocator(allocator);
     defer args.deinit();
@@ -110,7 +125,7 @@ pub fn parse_args(allocator: std.mem.Allocator) !Command {
     assert(did_skip);
 
     const raw_command = try (args.next(allocator) orelse
-        fatal("no command provided, expected 'start' or 'format'", .{}));
+        fatal("no command provided, expected 'start', 'format', or 'version'", .{}));
     defer allocator.free(raw_command);
 
     if (mem.eql(u8, raw_command, "-h") or mem.eql(u8, raw_command, "--help")) {
@@ -118,7 +133,7 @@ pub fn parse_args(allocator: std.mem.Allocator) !Command {
         os.exit(0);
     }
     const command = meta.stringToEnum(meta.Tag(Command), raw_command) orelse
-        fatal("unknown command '{s}', expected 'start' or 'format'", .{raw_command});
+        fatal("unknown command '{s}', expected 'start', 'format', or 'version'", .{raw_command});
 
     while (args.next(allocator)) |parsed_arg| {
         const arg = try parsed_arg;
@@ -132,6 +147,8 @@ pub fn parse_args(allocator: std.mem.Allocator) !Command {
             addresses = parse_flag("--addresses", arg);
         } else if (mem.startsWith(u8, arg, "--memory")) {
             memory = parse_flag("--memory", arg);
+        } else if (mem.eql(u8, arg, "--verbose")) {
+            verbose = true;
         } else if (mem.eql(u8, arg, "-h") or mem.eql(u8, arg, "--help")) {
             std.io.getStdOut().writeAll(usage) catch os.exit(1);
             os.exit(0);
@@ -145,9 +162,21 @@ pub fn parse_args(allocator: std.mem.Allocator) !Command {
     }
 
     switch (command) {
+        .version => {
+            if (addresses != null) fatal("--addresses: supported only by 'start' command", .{});
+            if (memory != null) fatal("--memory: supported only by 'start' command", .{});
+            if (cluster != null) fatal("--cluster: supported only by 'format' command", .{});
+            if (replica != null) fatal("--replica: supported only by 'format' command", .{});
+            if (path != null) fatal("unexpected path", .{});
+
+            return Command{
+                .version = .{ .verbose = verbose orelse false },
+            };
+        },
         .format => {
             if (addresses != null) fatal("--addresses: supported only by 'start' command", .{});
             if (memory != null) fatal("--memory: supported only by 'start' command", .{});
+            if (verbose != null) fatal("--verbose: supported only by 'version' command", .{});
 
             return Command{
                 .format = .{
@@ -161,6 +190,7 @@ pub fn parse_args(allocator: std.mem.Allocator) !Command {
         .start => {
             if (cluster != null) fatal("--cluster: supported only by 'format' command", .{});
             if (replica != null) fatal("--replica: supported only by 'format' command", .{});
+            if (verbose != null) fatal("--verbose: supported only by 'version' command", .{});
 
             return Command{
                 .start = .{
@@ -207,7 +237,7 @@ fn parse_cluster(raw_cluster: []const u8) u32 {
 
 /// Parse and allocate the addresses returning a slice into that array.
 fn parse_addresses(allocator: std.mem.Allocator, raw_addresses: []const u8) []net.Address {
-    return vsr.parse_addresses(allocator, raw_addresses) catch |err| switch (err) {
+    return vsr.parse_addresses(allocator, raw_addresses, config.replicas_max) catch |err| switch (err) {
         error.AddressHasTrailingComma => fatal("--addresses: invalid trailing comma", .{}),
         error.AddressLimitExceeded => {
             fatal("--addresses: too many addresses, at most {d} are allowed", .{

package/src/tigerbeetle/src/config.zig

@@ -1,5 +1,7 @@
 const std = @import("std");
 const assert = std.debug.assert;
+const tigerbeetle = @import("tigerbeetle.zig");
+const vsr = @import("vsr.zig");
 
 const Environment = enum {
     development,
@@ -9,8 +11,7 @@ const Environment = enum {
 
 /// Whether development or production:
 pub const deployment_environment: Environment =
-    if (@hasDecl(@import("root"), "deployment_environment")) @import("root").deployment_environment
-    else .development;
+    if (@hasDecl(@import("root"), "deployment_environment")) @import("root").deployment_environment else .development;
 
 /// The maximum log level in increasing order of verbosity (emergency=0, debug=3):
 pub const log_level = 2;
@@ -48,22 +49,22 @@ pub const memory_size_max_default = 1024 * 1024 * 1024;
 
 /// The maximum number of accounts to store in memory:
 /// This impacts the amount of memory allocated at initialization by the server.
-pub const accounts_max = switch (deployment_environment) {
-    .production => 1_000_000,
-    else => 100_000,
+pub const cache_accounts_max = switch (deployment_environment) {
+    .production => 64 * 1024,
+    else => 8 * 1024,
 };
 
 /// The maximum number of transfers to store in memory:
 /// This impacts the amount of memory allocated at initialization by the server.
 /// We allocate more capacity than the number of transfers for a safe hash table load factor.
-pub const transfers_max = switch (deployment_environment) {
-    .production => 100_000_000,
-    else => 1_000_000,
+pub const cache_transfers_max = switch (deployment_environment) {
+    .production => 1024 * 1024,
+    else => 64 * 1024,
 };
 
 /// The maximum number of two-phase transfers to store in memory:
 /// This impacts the amount of memory allocated at initialization by the server.
-pub const transfers_pending_max = transfers_max;
+pub const cache_transfers_pending_max = cache_transfers_max;
 
 /// The maximum number of batch entries in the journal file:
 /// A batch entry may contain many transfers, so this is not a limit on the number of transfers.
@@ -71,7 +72,7 @@ pub const transfers_pending_max = transfers_max;
 /// These header copies enable us to disentangle corruption from crashes and recover accordingly.
 pub const journal_slot_count = switch (deployment_environment) {
     .production => 1024,
-    else => 128,
+    else => 1024,
 };
 
 /// The maximum size of the journal file:
@@ -80,7 +81,7 @@ pub const journal_slot_count = switch (deployment_environment) {
 /// This enables static allocation of disk space so that appends cannot fail with ENOSPC.
 /// This also enables us to detect filesystem inode corruption that would change the journal size.
 // TODO remove this; just allocate a part of the total storage for the journal
-pub const journal_size_max = journal_slot_count * (128 + message_size_max);
+pub const journal_size_max = journal_slot_count * (@sizeOf(vsr.Header) + message_size_max);
 
 /// The maximum number of connections that can be held open by the server at any time:
 pub const connections_max = replicas_max + clients_max;
@@ -94,11 +95,22 @@ pub const connections_max = replicas_max + clients_max;
 /// For a 1 Gbps NIC = 125 MiB/s throughput: 2 MiB / 125 * 1000ms = 16ms for the next request.
 /// This impacts the amount of memory allocated at initialization by the server.
 pub const message_size_max = switch (deployment_environment) {
-    // Use a small message size during the simulator for improved performance.
-    .simulation => sector_size,
-    else => 1 * 1024 * 1024
+    .simulation => message_size_max_min,
+    else => 1 * 1024 * 1024,
 };
 
+pub const message_body_size_max = message_size_max - @sizeOf(vsr.Header);
+
+/// The smallest possible message_size_max (for use in the simulator to improve performance).
+/// The message body must have room for pipeline_max headers in the DVC.
+const message_size_max_min = std.math.max(
+    sector_size,
+    std.mem.alignForward(
+        @sizeOf(vsr.Header) + pipeline_max * @sizeOf(vsr.Header),
+        sector_size,
+    ),
+);
+
 /// The maximum number of Viewstamped Replication prepare messages that can be inflight at a time.
 /// This is immutable once assigned per cluster, as replicas need to know how many operations might
 /// possibly be uncommitted during a view change, and this must be constant for all replicas.
@@ -201,7 +213,6 @@ pub const io_depth_write = 8;
 
 /// The number of redundant copies of the superblock in the superblock storage zone.
 /// This must be either { 4, 6, 8 }, i.e. an even number, for more efficient flexible quorums.
-/// This is further multiplied by two to support copy-on-write across copy sets.
 ///
 /// The superblock contains local state for the replica and therefore cannot be replicated remotely.
 /// Loss of the superblock would represent loss of the replica and so it must be protected.
@@ -227,6 +238,9 @@ pub const superblock_copies = 4;
 pub const size_max = 16 * 1024 * 1024 * 1024 * 1024;
 
 /// The unit of read/write access to LSM manifest and LSM table blocks in the block storage zone.
+///
+/// - A lower block size increases the memory overhead of table metadata, due to smaller/more tables.
+/// - A higher block size increases space amplification due to partially-filled blocks.
 pub const block_size = 64 * 1024;
 
 pub const block_count_max = @divExact(16 * 1024 * 1024 * 1024 * 1024, block_size);
@@ -235,13 +249,22 @@ pub const block_count_max = @divExact(16 * 1024 * 1024 * 1024 * 1024, block_size
 pub const lsm_trees = 30;
 
 /// The number of levels in an LSM tree.
+/// A higher number of levels increases read amplification, as well as total storage capacity.
 pub const lsm_levels = 7;
 
+/// The number of tables at level i (0 ≤ i < lsm_levels) is `pow(lsm_growth_factor, i+1)`.
+/// A higher growth factor increases write amplification (by increasing the number of tables in
+/// level B that overlap a table in level A in a compaction), but decreases read amplification (by
+/// reducing the height of the tree and thus the number of levels that must be probed). Since read
+/// amplification can be optimized more easily (with filters and caching), we target a growth
+/// factor of 8 for lower write amplification rather than the more typical growth factor of 10.
 pub const lsm_growth_factor = 8;
 
 /// The maximum key size for an LSM tree in bytes.
 pub const lsm_key_size_max = 32;
 
+/// The maximum cumulative size of a table — computed as the sum of the size of the index block,
+/// filter blocks, and data blocks.
 pub const lsm_table_size_max = 64 * 1024 * 1024;
 
 /// Size of nodes used by the LSM tree manifest implementation.
@@ -305,10 +328,10 @@ pub const clock_synchronization_window_max_ms = 20000;
 pub const verify = true;
 
 // TODO Move these to a separate "internal computed constants" file.
-pub const journal_size_headers = journal_slot_count * 128; // 128 == @sizeOf(Header)
+pub const journal_size_headers = journal_slot_count * @sizeOf(vsr.Header);
 pub const journal_size_prepares = journal_slot_count * message_size_max;
 
- // TODO Move these into a separate `config_valid.zig` which we import here:
+// TODO Move these into a separate `config_valid.zig` which we import here:
 comptime {
     // vsr.parse_address assumes that config.address/config.port are valid.
     _ = std.net.Address.parseIp4(address, 0) catch unreachable;
@@ -339,10 +362,28 @@ comptime {
 
     // The WAL format requires messages to be a multiple of the sector size.
     assert(message_size_max % sector_size == 0);
+    assert(message_size_max >= @sizeOf(vsr.Header));
     assert(message_size_max >= sector_size);
 
+    assert(superblock_copies % 2 == 0);
+    assert(superblock_copies >= 4);
+    assert(superblock_copies <= 8);
+
+    // ManifestLog serializes the level as a u7.
+    assert(lsm_levels > 0);
+    assert(lsm_levels <= std.math.maxInt(u7));
+
+    assert(block_size % sector_size == 0);
+    assert(lsm_table_size_max % sector_size == 0);
+    assert(lsm_table_size_max % block_size == 0);
+
     // The LSM tree uses half-measures to balance compaction.
     assert(lsm_batch_multiple % 2 == 0);
+
+    // SetAssociativeCache requires a power-of-two cardinality.
+    assert(std.math.isPowerOfTwo(cache_accounts_max));
+    assert(std.math.isPowerOfTwo(cache_transfers_max));
+    assert(std.math.isPowerOfTwo(cache_transfers_pending_max));
 }
 
 pub const is_32_bit = @sizeOf(usize) == 4; // TODO Return a compile error if we are not 32-bit.