tigerbeetle-node 0.3.3 → 0.5.0

package/src/tigerbeetle/src/test/storage.zig

@@ -0,0 +1,375 @@
+const std = @import("std");
+const assert = std.debug.assert;
+const math = std.math;
+const mem = std.mem;
+
+const config = @import("../config.zig");
+const vsr = @import("../vsr.zig");
+
+const log = std.log.scoped(.storage);
+
+// TODOs:
+// less than a majority of replicas may have corruption
+// have an option to enable/disable the following corruption types:
+// bitrot
+// misdirected read/write
+// corrupt sector
+// latent sector error
+// - emulate by zeroing sector, as this is how we handle this in the real Storage implementation
+// - likely that surrounding sectors also corrupt
+// - likely that stuff written at the same time is also corrupt even if written to a far away sector
+pub const Storage = struct {
+    /// Options for fault injection during fuzz testing
+    pub const Options = struct {
+        /// Seed for the storage PRNG
+        seed: u64,
+
+        /// Minimum number of ticks it may take to read data.
+        read_latency_min: u64,
+        /// Average number of ticks it may take to read data. Must be >= read_latency_min.
+        read_latency_mean: u64,
+        /// Minimum number of ticks it may take to write data.
+        write_latency_min: u64,
+        /// Average number of ticks it may take to write data. Must be >= write_latency_min.
+        write_latency_mean: u64,
+
+        /// Chance out of 100 that a read will return incorrect data, if the target memory is within
+        /// the faulty area of this replica.
+        read_fault_probability: u8,
+        /// Chance out of 100 that a read will return incorrect data, if the target memory is within
+        /// the faulty area of this replica.
+        write_fault_probability: u8,
+    };
+
+    /// See usage in Journal.write_sectors() for details.
+    /// TODO: allow testing in both modes.
+    pub const synchronicity: enum {
+        always_synchronous,
+        always_asynchronous,
+    } = .always_asynchronous;
+
+    pub const Read = struct {
+        callback: fn (read: *Storage.Read) void,
+        buffer: []u8,
+        offset: u64,
+        /// Tick at which this read is considered "completed" and the callback should be called.
+        done_at_tick: u64,
+
+        fn less_than(storage: *Read, other: *Read) math.Order {
+            return math.order(storage.done_at_tick, other.done_at_tick);
+        }
+    };
+
+    pub const Write = struct {
+        callback: fn (write: *Storage.Write) void,
+        buffer: []const u8,
+        offset: u64,
+        /// Tick at which this write is considered "completed" and the callback should be called.
+        done_at_tick: u64,
+
+        fn less_than(storage: *Write, other: *Write) math.Order {
+            return math.order(storage.done_at_tick, other.done_at_tick);
+        }
+    };
+
+    /// Faulty areas are always sized to message_size_max
+    /// If the faulty areas of all replicas are superimposed, the padding between them is always message_size_max.
+    /// For a single replica, the padding between faulty areas depends on the number of other replicas.
+    pub const FaultyAreas = struct {
+        first_offset: u64,
+        period: u64,
+    };
+
+    memory: []align(config.sector_size) u8,
+    size: u64,
+
+    options: Options,
+    replica_index: u8,
+    prng: std.rand.DefaultPrng,
+
+    // We can't allow storage faults for the same message in a majority of
+    // the replicas as that would make recovery impossible. Instead, we only
+    // allow faults in certian areas which differ between replicas.
+    faulty_areas: FaultyAreas,
+
+    reads: std.PriorityQueue(*Storage.Read),
+    writes: std.PriorityQueue(*Storage.Write),
+
+    ticks: u64 = 0,
+
+    pub fn init(
+        allocator: *mem.Allocator,
+        size: u64,
+        options: Storage.Options,
+        replica_index: u8,
+        faulty_areas: FaultyAreas,
+    ) !Storage {
+        assert(options.write_latency_mean >= options.write_latency_min);
+        assert(options.read_latency_mean >= options.read_latency_min);
+
+        const memory = try allocator.allocAdvanced(u8, config.sector_size, size, .exact);
+        errdefer allocator.free(memory);
+        // TODO: random data
+        mem.set(u8, memory, 0);
+
+        var reads = std.PriorityQueue(*Storage.Read).init(allocator, Storage.Read.less_than);
+        errdefer reads.deinit();
+        try reads.ensureCapacity(config.io_depth_read);
+
+        var writes = std.PriorityQueue(*Storage.Write).init(allocator, Storage.Write.less_than);
+        errdefer writes.deinit();
+        try writes.ensureCapacity(config.io_depth_write);
+
+        return Storage{
+            .memory = memory,
+            .size = size,
+            .options = options,
+            .replica_index = replica_index,
+            .prng = std.rand.DefaultPrng.init(options.seed),
+            .faulty_areas = faulty_areas,
+            .reads = reads,
+            .writes = writes,
+        };
+    }
+
+    /// Cancel any currently in progress reads/writes but leave the stored data untouched.
+    pub fn reset(storage: *Storage) void {
+        storage.reads.len = 0;
+        storage.writes.len = 0;
+    }
+
+    pub fn deinit(storage: *Storage, allocator: *mem.Allocator) void {
+        allocator.free(storage.memory);
+        storage.reads.deinit();
+        storage.writes.deinit();
+    }
+
+    pub fn tick(storage: *Storage) void {
+        storage.ticks += 1;
+
+        while (storage.reads.peek()) |read| {
+            if (read.done_at_tick > storage.ticks) break;
+            _ = storage.reads.remove();
+            storage.read_sectors_finish(read);
+        }
+
+        while (storage.writes.peek()) |write| {
+            if (write.done_at_tick > storage.ticks) break;
+            _ = storage.writes.remove();
+            storage.write_sectors_finish(write);
+        }
+    }
+
+    pub fn read_sectors(
+        storage: *Storage,
+        callback: fn (read: *Storage.Read) void,
+        read: *Storage.Read,
+        buffer: []u8,
+        offset: u64,
+    ) void {
+        storage.assert_bounds_and_alignment(buffer, offset);
+
+        read.* = .{
+            .callback = callback,
+            .buffer = buffer,
+            .offset = offset,
+            .done_at_tick = storage.ticks + storage.read_latency(),
+        };
+
+        // We ensure the capacity is sufficient for config.io_depth_read in init()
+        storage.reads.add(read) catch unreachable;
+    }
+
+    fn read_sectors_finish(storage: *Storage, read: *Storage.Read) void {
+        const faulty = storage.faulty_sectors(read.offset, read.buffer.len);
+        if (faulty.len > 0 and storage.x_in_100(storage.options.read_fault_probability)) {
+            // Randomly corrupt one of the faulty sectors the read targeted
+            // TODO: inject more realistic and varied storage faults as described above.
+            const sector_count = @divExact(faulty.len, config.sector_size);
+            const faulty_sector = storage.prng.random.uintLessThan(u64, sector_count);
+            const faulty_sector_offset = faulty_sector * config.sector_size;
+            const faulty_sector_bytes = faulty[faulty_sector_offset..][0..config.sector_size];
+
+            log.info("corrupting sector at offset {} during read by replica {}", .{
+                faulty_sector_offset,
+                storage.replica_index,
+            });
+
+            storage.prng.random.bytes(faulty_sector_bytes);
+        }
+
+        mem.copy(u8, read.buffer, storage.memory[read.offset..][0..read.buffer.len]);
+        read.callback(read);
+    }
+
+    pub fn write_sectors(
+        storage: *Storage,
+        callback: fn (write: *Storage.Write) void,
+        write: *Storage.Write,
+        buffer: []const u8,
+        offset: u64,
+    ) void {
+        storage.assert_bounds_and_alignment(buffer, offset);
+
+        write.* = .{
+            .callback = callback,
+            .buffer = buffer,
+            .offset = offset,
+            .done_at_tick = storage.ticks + storage.write_latency(),
+        };
+
+        // We ensure the capacity is sufficient for config.io_depth_write in init()
+        storage.writes.add(write) catch unreachable;
+    }
+
+    fn write_sectors_finish(storage: *Storage, write: *Storage.Write) void {
+        mem.copy(u8, storage.memory[write.offset..][0..write.buffer.len], write.buffer);
+
+        const faulty = storage.faulty_sectors(write.offset, write.buffer.len);
+        if (faulty.len > 0 and storage.x_in_100(storage.options.write_fault_probability)) {
+            // Randomly corrupt one of the faulty sectors the write targeted
+            // TODO: inject more realistic and varied storage faults as described above.
+            const sector_count = @divExact(faulty.len, config.sector_size);
+            const faulty_sector = storage.prng.random.uintLessThan(u64, sector_count);
+            const faulty_sector_offset = faulty_sector * config.sector_size;
+            const faulty_sector_bytes = faulty[faulty_sector_offset..][0..config.sector_size];
+
+            log.info("corrupting sector at offset {} during write by replica {}", .{
+                faulty_sector_offset,
+                storage.replica_index,
+            });
+
+            storage.prng.random.bytes(faulty_sector_bytes);
+        }
+
+        write.callback(write);
+    }
+
+    fn assert_bounds_and_alignment(storage: *Storage, buffer: []const u8, offset: u64) void {
+        assert(buffer.len > 0);
+        assert(offset + buffer.len <= storage.size);
+
+        // Ensure that the read or write is aligned correctly for Direct I/O:
+        // If this is not the case, the underlying syscall will return EINVAL.
+        assert(@mod(@ptrToInt(buffer.ptr), config.sector_size) == 0);
+        assert(@mod(buffer.len, config.sector_size) == 0);
+        assert(@mod(offset, config.sector_size) == 0);
+    }
+
+    fn read_latency(storage: *Storage) u64 {
+        return storage.latency(storage.options.read_latency_min, storage.options.read_latency_mean);
+    }
+
+    fn write_latency(storage: *Storage) u64 {
+        return storage.latency(storage.options.write_latency_min, storage.options.write_latency_mean);
+    }
+
+    fn latency(storage: *Storage, min: u64, mean: u64) u64 {
+        return min + @floatToInt(u64, @intToFloat(f64, mean - min) * storage.prng.random.floatExp(f64));
+    }
+
+    /// Return true with probability x/100.
+    fn x_in_100(storage: *Storage, x: u8) bool {
+        assert(x <= 100);
+        return x > storage.prng.random.uintLessThan(u8, 100);
+    }
+
+    /// The return value is a slice into the provided out array.
+    pub fn generate_faulty_areas(
+        prng: *std.rand.Random,
+        size: u64,
+        replica_count: u8,
+        out: *[config.replicas_max]FaultyAreas,
+    ) []FaultyAreas {
+        comptime assert(config.message_size_max % config.sector_size == 0);
+        const message_size_max = config.message_size_max;
+
+        // We need to ensure there is message_size_max fault-free padding
+        // between faulty areas of memory so that a single message
+        // cannot straddle the corruptable areas of a majority of replicas.
+        comptime assert(config.replicas_max == 6);
+        switch (replica_count) {
+            1 => {
+                // If there is only one replica in the cluster, storage faults are not recoverable.
+                out[0] = .{ .first_offset = size, .period = 1 };
+            },
+            2 => {
+                //  0123456789
+                // 0X   X   X
+                // 1  X   X   X
+                out[0] = .{ .first_offset = 0 * message_size_max, .period = 4 * message_size_max };
+                out[1] = .{ .first_offset = 2 * message_size_max, .period = 4 * message_size_max };
+            },
+            3 => {
+                //  0123456789
+                // 0X     X
+                // 1  X     X
+                // 2    X     X
+                out[0] = .{ .first_offset = 0 * message_size_max, .period = 6 * message_size_max };
+                out[1] = .{ .first_offset = 2 * message_size_max, .period = 6 * message_size_max };
+                out[2] = .{ .first_offset = 4 * message_size_max, .period = 6 * message_size_max };
+            },
+            4 => {
+                //  0123456789
+                // 0X   X   X
+                // 1X   X   X
+                // 2  X   X   X
+                // 3  X   X   X
+                out[0] = .{ .first_offset = 0 * message_size_max, .period = 4 * message_size_max };
+                out[1] = .{ .first_offset = 0 * message_size_max, .period = 4 * message_size_max };
+                out[2] = .{ .first_offset = 2 * message_size_max, .period = 4 * message_size_max };
+                out[3] = .{ .first_offset = 2 * message_size_max, .period = 4 * message_size_max };
+            },
+            5 => {
+                //  0123456789
+                // 0X     X
+                // 1X     X
+                // 2  X     X
+                // 3  X     X
+                // 4    X     X
+                out[0] = .{ .first_offset = 0 * message_size_max, .period = 6 * message_size_max };
+                out[1] = .{ .first_offset = 0 * message_size_max, .period = 6 * message_size_max };
+                out[2] = .{ .first_offset = 2 * message_size_max, .period = 6 * message_size_max };
+                out[3] = .{ .first_offset = 2 * message_size_max, .period = 6 * message_size_max };
+                out[4] = .{ .first_offset = 4 * message_size_max, .period = 6 * message_size_max };
+            },
+            6 => {
+                //  0123456789
+                // 0X     X
+                // 1X     X
+                // 2  X     X
+                // 3  X     X
+                // 4    X     X
+                // 5    X     X
+                out[0] = .{ .first_offset = 0 * message_size_max, .period = 6 * message_size_max };
+                out[1] = .{ .first_offset = 0 * message_size_max, .period = 6 * message_size_max };
+                out[2] = .{ .first_offset = 2 * message_size_max, .period = 6 * message_size_max };
+                out[3] = .{ .first_offset = 2 * message_size_max, .period = 6 * message_size_max };
+                out[4] = .{ .first_offset = 4 * message_size_max, .period = 6 * message_size_max };
+                out[5] = .{ .first_offset = 4 * message_size_max, .period = 6 * message_size_max };
+            },
+            else => unreachable,
+        }
+
+        prng.shuffle(FaultyAreas, out[0..replica_count]);
+        return out[0..replica_count];
+    }
+
+    /// Given an offest and size of a read/write, returns a slice into storage.memory of any
+    /// faulty sectors touched by the read/write
+    fn faulty_sectors(storage: *Storage, offset: u64, size: u64) []align(config.sector_size) u8 {
+        assert(size <= config.message_size_max);
+        const message_size_max = config.message_size_max;
+        const period = storage.faulty_areas.period;
+
+        const faulty_offset = storage.faulty_areas.first_offset + (offset / period) * period;
+
+        const start = std.math.max(offset, faulty_offset);
+        const end = std.math.min(offset + size, faulty_offset + message_size_max);
+
+        // The read/write does not touch any faulty sectors
+        if (start >= end) return &[0]u8{};
+
+        return storage.memory[start..end];
+    }
+};

package/src/tigerbeetle/src/test/time.zig

@@ -0,0 +1,84 @@
+const std = @import("std");
+const assert = std.debug.assert;
+
+pub const OffsetType = enum {
+    linear,
+    periodic,
+    step,
+    non_ideal,
+};
+
+pub const Time = struct {
+    const Self = @This();
+
+    /// The duration of a single tick in nanoseconds.
+    resolution: u64,
+
+    offset_type: OffsetType,
+
+    /// Co-efficients to scale the offset according to the `offset_type`.
+    /// Linear offset is described as A * x + B: A is the drift per tick and B the initial offset.
+    /// Periodic is described as A * sin(x * pi / B): A controls the amplitude and B the period in
+    /// terms of ticks.
+    /// Step function represents a discontinuous jump in the wall-clock time. B is the period in
+    /// which the jumps occur. A is the amplitude of the step.
+    /// Non-ideal is similar to periodic except the phase is adjusted using a random number taken
+    /// from a normal distribution with mean=0, stddev=10. Finally, a random offset (up to
+    /// offset_coefficientC) is added to the result.
+    offset_coefficient_A: i64,
+    offset_coefficient_B: i64,
+    offset_coefficient_C: u32 = 0,
+
+    prng: std.rand.DefaultPrng = std.rand.DefaultPrng.init(0),
+
+    /// The number of ticks elapsed since initialization.
+    ticks: u64 = 0,
+
+    /// The instant in time chosen as the origin of this time source.
+    epoch: i64 = 0,
+
+    pub fn monotonic(self: *Self) u64 {
+        return self.ticks * self.resolution;
+    }
+
+    pub fn realtime(self: *Self) i64 {
+        return self.epoch + @intCast(i64, self.monotonic()) - self.offset(self.ticks);
+    }
+
+    pub fn offset(self: *Self, ticks: u64) i64 {
+        switch (self.offset_type) {
+            .linear => {
+                const drift_per_tick = self.offset_coefficient_A;
+                return @intCast(i64, ticks) * drift_per_tick + @intCast(
+                    i64,
+                    self.offset_coefficient_B,
+                );
+            },
+            .periodic => {
+                const unscaled = std.math.sin(@intToFloat(f64, ticks) * 2 * std.math.pi /
+                    @intToFloat(f64, self.offset_coefficient_B));
+                const scaled = @intToFloat(f64, self.offset_coefficient_A) * unscaled;
+                return @floatToInt(i64, std.math.floor(scaled));
+            },
+            .step => {
+                return if (ticks > self.offset_coefficient_B) self.offset_coefficient_A else 0;
+            },
+            .non_ideal => {
+                const phase: f64 = @intToFloat(f64, ticks) * 2 * std.math.pi /
+                    (@intToFloat(f64, self.offset_coefficient_B) + self.prng.random.floatNorm(f64) * 10);
+                const unscaled = std.math.sin(phase);
+                const scaled = @intToFloat(f64, self.offset_coefficient_A) * unscaled;
+                return @floatToInt(i64, std.math.floor(scaled)) +
+                    self.prng.random.intRangeAtMost(
+                    i64,
+                    -@intCast(i64, self.offset_coefficient_C),
+                    self.offset_coefficient_C,
+                );
+            },
+        }
+    }
+
+    pub fn tick(self: *Self) void {
+        self.ticks += 1;
+    }
+};

package/src/tigerbeetle/src/tigerbeetle.zig

@@ -249,7 +249,6 @@ pub const CommitTransferResult = packed enum(u32) {
     transfer_not_found,
     transfer_not_two_phase_commit,
     transfer_expired,
-    already_auto_committed,
     already_committed,
     already_committed_but_accepted,
     already_committed_but_rejected,
@@ -325,10 +324,14 @@ pub const CommitTransfersResult = packed struct {
 };
 
 comptime {
-    if (std.Target.current.os.tag != .linux) @compileError("linux required for io_uring");
+    const target = std.Target.current;
+
+    if (target.os.tag != .linux and !target.isDarwin()) {
+        @compileError("linux or macos required for io");
+    }
 
     // We require little-endian architectures everywhere for efficient network deserialization:
-    if (std.Target.current.cpu.arch.endian() != std.builtin.Endian.Little) {
+    if (target.cpu.arch.endian() != std.builtin.Endian.Little) {
         @compileError("big-endian systems not supported");
     }
 }

package/src/tigerbeetle/src/time.zig

@@ -0,0 +1,65 @@
+const std = @import("std");
+const assert = std.debug.assert;
+const is_darwin = std.Target.current.isDarwin();
+const config = @import("./config.zig");
+
+pub const Time = struct {
+    const Self = @This();
+
+    /// Hardware and/or software bugs can mean that the monotonic clock may regress.
+    /// One example (of many): https://bugzilla.redhat.com/show_bug.cgi?id=448449
+    /// We crash the process for safety if this ever happens, to protect against infinite loops.
+    /// It's better to crash and come back with a valid monotonic clock than get stuck forever.
+    monotonic_guard: u64 = 0,
+
+    /// A timestamp to measure elapsed time, meaningful only on the same system, not across reboots.
+    /// Always use a monotonic timestamp if the goal is to measure elapsed time.
+    /// This clock is not affected by discontinuous jumps in the system time, for example if the
+    /// system administrator manually changes the clock.
+    pub fn monotonic(self: *Self) u64 {
+        const m = blk: {
+            // 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;
+                    extern "c" fn mach_continuous_time() u64;
+                };
+
+                const now = darwin.mach_continuous_time();
+                var info: darwin.mach_timebase_info_t = undefined;
+                if (darwin.mach_timebase_info(&info) != 0) @panic("mach_timebase_info() failed");
+                return (now * info.numer) / info.denom;
+            }
+
+            // The true monotonic clock on Linux is not in fact CLOCK_MONOTONIC:
+            // CLOCK_MONOTONIC excludes elapsed time while the system is suspended (e.g. VM migration).
+            // 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");
+            break :blk @intCast(u64, ts.tv_sec) * std.time.ns_per_s + @intCast(u64, ts.tv_nsec);
+        };
+
+        // "Oops!...I Did It Again"
+        if (m < self.monotonic_guard) @panic("a hardware/kernel bug regressed the monotonic clock");
+        self.monotonic_guard = m;
+        return m;
+    }
+
+    /// 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: *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
+
+        var ts: std.os.timespec = undefined;
+        std.os.clock_gettime(std.os.CLOCK_REALTIME, &ts) catch unreachable;
+        return @as(i64, ts.tv_sec) * std.time.ns_per_s + ts.tv_nsec;
+    }
+
+    pub fn tick(self: *Self) void {}
+};

package/src/tigerbeetle/src/unit_tests.zig

@@ -0,0 +1,14 @@
+test {
+    _ = @import("vsr.zig");
+    _ = @import("vsr/journal.zig");
+    _ = @import("vsr/marzullo.zig");
+    // TODO: clean up logging of clock test and enable it here.
+    //_ = @import("vsr/clock.zig");
+
+    _ = @import("state_machine.zig");
+
+    _ = @import("fifo.zig");
+    _ = @import("ring_buffer.zig");
+
+    _ = @import("io.zig");
+}