tigerbeetle 0.0.34 → 0.0.37

data/ext/tb_client/tigerbeetle/src/clients/java/src/jni_thread_cleaner.zig

@@ -0,0 +1,190 @@
+const std = @import("std");
+const builtin = @import("builtin");
+const jni = @import("jni.zig");
+
+const log = std.log.scoped(.tb_client_jni);
+const assert = std.debug.assert;
+
+/// Helper for managing the `AttachCurrentThread`/`DetachCurrentThread` lifecycle
+/// when the JNI layer is unaware of when the native thread exits.
+/// https://developer.android.com/training/articles/perf-jni#threads
+pub const JNIThreadCleaner = struct {
+    var tls_key: ?tls.Key = null;
+    var create_key_once = std.once(create_key);
+
+    /// This function calls `AttachCurrentThreadAsDaemon` to attach the current native thread to
+    /// the JVM as a daemon thread. It also registers a callback to call `DetachCurrentThread`
+    /// when the thread exits (e.g., when the client is closed or evicted).
+    pub fn attach_current_thread_with_cleanup(jvm: *jni.JavaVM) *jni.JNIEnv {
+        // Create the tls key once per JVM.
+        create_key_once.call();
+
+        // Set the JVM handler to the thread-local storage slot for each time a native
+        // thread is started.
+        tls.set_key(tls_key.?, jvm);
+
+        return attach_current_thread(jvm);
+    }
+
+    /// Create the thread-local storage key and the corresponding destructor callback.
+    /// Note: We don't need to delete the key because the JNI module cannot be unloaded,
+    /// so it will always be available for the duration of the JVM process.
+    fn create_key() void {
+        assert(tls_key == null);
+        tls_key = tls.create_key(&destructor_callback);
+    }
+
+    // Will be called by the OS with the JVM handler when the thread finalizes.
+    fn destructor_callback(jvm: *anyopaque) callconv(.c) void {
+        assert(tls_key != null);
+        detach_current_thread(@ptrCast(jvm));
+    }
+
+    fn attach_current_thread(jvm: *jni.JavaVM) *jni.JNIEnv {
+        var env: *jni.JNIEnv = undefined;
+        const jni_result = jvm.attach_current_thread_as_daemon(&env, null);
+        if (jni_result != .ok) {
+            const message = "Unexpected result calling JavaVM.AttachCurrentThreadAsDaemon";
+            log.err(
+                message ++ "; Error = {} ({s})",
+                .{ @intFromEnum(jni_result), @tagName(jni_result) },
+            );
+            @panic("JNI: " ++ message);
+        }
+
+        return env;
+    }
+
+    fn detach_current_thread(jvm: *jni.JavaVM) void {
+        const jni_result = jvm.detach_current_thread();
+        if (jni_result != .ok) {
+            const message = "Unexpected result calling JavaVM.DetachCurrentThread";
+            log.err(
+                message ++ "; Error = {} ({s})",
+                .{ @intFromEnum(jni_result), @tagName(jni_result) },
+            );
+            @panic("JNI: " ++ message);
+        }
+    }
+
+    /// Thread-local storage abstraction,
+    /// based on `pthread_key_create` for Linux/MacOS and `FlsAlloc` for Windows.
+    const tls = switch (builtin.os.tag) {
+        .linux, .macos => struct {
+            const Key = std.c.pthread_key_t;
+
+            fn create_key(destructor: ?*const fn (value: *anyopaque) callconv(.c) void) Key {
+                var key: Key = undefined;
+                const ret = std.c.pthread_key_create(&key, destructor);
+                if (ret != .SUCCESS) {
+                    const message = "Unexpected result calling pthread_key_create";
+                    log.err(message ++ "; Error = {} ({s})", .{
+                        @intFromEnum(ret),
+                        @tagName(ret),
+                    });
+                    @panic("JNI: " ++ message);
+                }
+
+                return key;
+            }
+
+            fn set_key(key: Key, value: *anyopaque) void {
+                const ret = std.c.pthread_setspecific(key, value);
+                if (ret != 0) {
+                    const message = "Unexpected result calling pthread_setspecific";
+                    log.err(message ++ "; Error = {}", .{ret});
+                    @panic("JNI: " ++ message);
+                }
+            }
+        },
+        .windows => struct {
+            const windows = struct {
+                const FLS_OUT_OF_INDEXES: std.os.windows.DWORD = 0xffffffff;
+                // https://learn.microsoft.com/en-us/windows/win32/api/fibersapi/nf-fibersapi-flsalloc
+                extern "kernel32" fn FlsAlloc(
+                    ?*const fn (value: *anyopaque) callconv(.c) void,
+                ) callconv(.c) std.os.windows.DWORD;
+                // https://learn.microsoft.com/en-us/windows/win32/api/fibersapi/nf-fibersapi-flssetvalue
+                extern "kernel32" fn FlsSetValue(
+                    std.os.windows.DWORD,
+                    *anyopaque,
+                ) callconv(.c) std.os.windows.BOOL;
+            };
+
+            const Key = std.os.windows.DWORD;
+
+            fn create_key(destructor: ?*const fn (value: *anyopaque) callconv(.c) void) Key {
+                const key = windows.FlsAlloc(destructor);
+                if (key == windows.FLS_OUT_OF_INDEXES) {
+                    const message = "Unexpected result calling FlsAlloc";
+                    log.err(message ++ "; Error = {}", .{key});
+                    @panic("JNI: " ++ message);
+                }
+
+                return key;
+            }
+
+            fn set_key(key: Key, value: *anyopaque) void {
+                const ret = windows.FlsSetValue(key, value);
+                if (ret == std.os.windows.FALSE) {
+                    const message = "Unexpected result calling FlsSetValue";
+                    log.err(message ++ "; Error = {}", .{ret});
+                    @panic("JNI: " ++ message);
+                }
+            }
+        },
+        else => unreachable,
+    };
+};
+
+test "JNIThreadCleaner:tls" {
+    const tls = JNIThreadCleaner.tls;
+    const TestContext = struct {
+        const TestContext = @This();
+
+        var tls_key: ?tls.Key = null;
+        var event: std.Thread.ResetEvent = .{};
+
+        counter: std.atomic.Value(u32),
+
+        fn init() TestContext {
+            if (tls_key == null) {
+                tls_key = tls.create_key(&destructor_callback);
+            }
+
+            return .{
+                .counter = std.atomic.Value(u32).init(0),
+            };
+        }
+
+        fn thread_main(self: *TestContext) void {
+            tls.set_key(tls_key.?, self);
+            event.wait();
+        }
+
+        fn destructor_callback(tls_value: *anyopaque) callconv(.c) void {
+            assert(tls_key != null);
+
+            const self: *TestContext = @ptrCast(@alignCast(tls_value));
+            _ = self.counter.fetchAdd(1, .monotonic);
+        }
+    };
+
+    var context = TestContext.init();
+    var threads: [10]std.Thread = undefined;
+    for (&threads) |*thread| {
+        thread.* = try std.Thread.spawn(.{}, TestContext.thread_main, .{&context});
+    }
+
+    // Assert that the callback only fires when the thread finishes.
+    try std.testing.expect(context.counter.load(.monotonic) == 0);
+
+    // Signal all threads to complete and wait for them.
+    TestContext.event.set();
+    for (&threads) |*thread| {
+        thread.join();
+    }
+
+    // Assert that all callbacks have fired.
+    try std.testing.expect(context.counter.load(.monotonic) == threads.len);
+}

data/ext/tb_client/tigerbeetle/src/clients/node/ci.zig

@@ -0,0 +1,104 @@
+const std = @import("std");
+const builtin = @import("builtin");
+const log = std.log;
+const assert = std.debug.assert;
+
+const Shell = @import("../../shell.zig");
+const TmpTigerBeetle = @import("../../testing/tmp_tigerbeetle.zig");
+
+pub fn tests(shell: *Shell, gpa: std.mem.Allocator) !void {
+    assert(shell.file_exists("package.json"));
+
+    try shell.exec_zig("build clients:node -Drelease", .{});
+
+    // Integration tests.
+
+    // We need to build the tigerbeetle-node library manually for samples/testers to work.
+    try shell.exec("npm install", .{});
+
+    for ([_][]const u8{ "test", "benchmark" }) |tester| {
+        log.info("testing {s}s", .{tester});
+
+        var tmp_beetle = try TmpTigerBeetle.init(gpa, .{
+            .development = true,
+        });
+        defer tmp_beetle.deinit(gpa);
+        errdefer tmp_beetle.log_stderr();
+
+        try shell.env.put("TB_ADDRESS", tmp_beetle.port_str);
+        try shell.exec("node ./dist/{tester}", .{ .tester = tester });
+    }
+
+    inline for ([_][]const u8{ "basic", "two-phase", "two-phase-many", "walkthrough" }) |sample| {
+        log.info("testing sample '{s}'", .{sample});
+
+        try shell.pushd("./samples/" ++ sample);
+        defer shell.popd();
+
+        var tmp_beetle = try TmpTigerBeetle.init(gpa, .{
+            .development = true,
+        });
+        defer tmp_beetle.deinit(gpa);
+        errdefer tmp_beetle.log_stderr();
+
+        try shell.env.put("TB_ADDRESS", tmp_beetle.port_str);
+        try shell.exec("npm install", .{});
+        try shell.exec("node main.js", .{});
+    }
+
+    // Container smoke tests.
+    if (builtin.target.os.tag == .linux) {
+        try shell.exec("npm pack --quiet", .{});
+
+        for ([_][]const u8{ "node:18", "node:18-alpine" }) |image| {
+            log.info("testing docker image: '{s}'", .{image});
+
+            try shell.exec(
+                \\docker run
+                \\--security-opt seccomp=unconfined
+                \\--volume ./:/host
+                \\{image}
+                \\sh
+                \\-c {script}
+            , .{
+                .image = image,
+                .script =
+                \\set -ex
+                \\mkdir test-project && cd test-project
+                \\npm install /host/tigerbeetle-node-*.tgz
+                \\node -e 'require("tigerbeetle-node"); console.log("SUCCESS!")'
+                ,
+            });
+        }
+    }
+}
+
+pub fn validate_release(shell: *Shell, gpa: std.mem.Allocator, options: struct {
+    version: []const u8,
+    tigerbeetle: []const u8,
+}) !void {
+    var tmp_beetle = try TmpTigerBeetle.init(gpa, .{
+        .development = true,
+        .prebuilt = options.tigerbeetle,
+    });
+    defer tmp_beetle.deinit(gpa);
+    errdefer tmp_beetle.log_stderr();
+
+    try shell.env.put("TB_ADDRESS", tmp_beetle.port_str);
+
+    try shell.exec("npm install tigerbeetle-node@{version}", .{
+        .version = options.version,
+    });
+
+    try Shell.copy_path(
+        shell.project_root,
+        "src/clients/node/samples/basic/main.js",
+        shell.cwd,
+        "main.js",
+    );
+    try shell.exec("node main.js", .{});
+}
+
+pub fn release_published_latest(shell: *Shell) ![]const u8 {
+    return try shell.exec_stdout("npm view tigerbeetle-node version", .{});
+}

data/ext/tb_client/tigerbeetle/src/clients/node/docs.zig

@@ -0,0 +1,75 @@
+const Docs = @import("../docs_types.zig").Docs;
+
+pub const NodeDocs = Docs{
+    .directory = "node",
+
+    .markdown_name = "javascript",
+    .extension = "js",
+    .proper_name = "Node.js",
+
+    .test_source_path = "",
+
+    .name = "tigerbeetle-node",
+    .description =
+    \\The TigerBeetle client for Node.js.
+    ,
+    .prerequisites =
+    \\* Node.js >= `18`
+    ,
+
+    .project_file = "",
+    .project_file_name = "",
+    .test_file_name = "main",
+
+    .install_commands = "npm install --save-exact tigerbeetle-node",
+    .run_commands = "node main.js",
+
+    .examples =
+    \\### Sidenote: `BigInt`
+    \\TigerBeetle uses 64-bit integers for many fields while JavaScript's
+    \\builtin `Number` maximum value is `2^53-1`. The `n` suffix in JavaScript
+    \\means the value is a `BigInt`. This is useful for literal numbers. If
+    \\you already have a `Number` variable though, you can call the `BigInt`
+    \\constructor to get a `BigInt` from it. For example, `1n` is the same as
+    \\`BigInt(1)`.
+    ,
+
+    .client_object_documentation = "",
+    .create_accounts_documentation = "",
+    .account_flags_documentation =
+    \\To toggle behavior for an account, combine enum values stored in the
+    \\`AccountFlags` object (in TypeScript it is an actual enum) with
+    \\bitwise-or:
+    \\
+    \\* `AccountFlags.linked`
+    \\* `AccountFlags.debits_must_not_exceed_credits`
+    \\* `AccountFlags.credits_must_not_exceed_credits`
+    \\* `AccountFlags.history`
+    \\
+    ,
+
+    .create_accounts_errors_documentation =
+    \\To handle errors you can either 1) exactly match error codes returned
+    \\from `client.createAccounts` with enum values in the
+    \\`CreateAccountError` object, or you can 2) look up the error code in
+    \\the `CreateAccountError` object for a human-readable string.
+    ,
+    .create_transfers_documentation = "",
+    .create_transfers_errors_documentation =
+    \\To handle errors you can either 1) exactly match error codes returned
+    \\from `client.createTransfers` with enum values in the
+    \\`CreateTransferError` object, or you can 2) look up the error code in
+    \\the `CreateTransferError` object for a human-readable string.
+    ,
+
+    .transfer_flags_documentation =
+    \\To toggle behavior for a transfer, combine enum values stored in the
+    \\`TransferFlags` object (in TypeScript it is an actual enum) with
+    \\bitwise-or:
+    \\
+    \\* `TransferFlags.linked`
+    \\* `TransferFlags.pending`
+    \\* `TransferFlags.post_pending_transfer`
+    \\* `TransferFlags.void_pending_transfer`
+    ,
+};