tigerbeetle 0.0.34 → 0.0.37

data/ext/tb_client/tigerbeetle/src/clients/docs_samples.zig

@@ -0,0 +1,157 @@
+const Sample = @import("./docs_types.zig").Sample;
+
+pub const samples = [_]Sample{
+    .{
+        .proper_name = "Basic",
+        .directory = "basic",
+        .short_description = "Create two accounts and transfer an amount between them.",
+        .long_description =
+        \\## 1. Create accounts
+        \\
+        \\This project starts by creating two accounts (`1` and `2`).
+        \\
+        \\## 2. Create a transfer
+        \\
+        \\Then it transfers `10` of an amount from account `1` to
+        \\account `2`.
+        \\
+        \\## 3. Fetch and validate account balances
+        \\
+        \\Then it fetches both accounts, checks they both exist, and
+        \\checks that **account `1`** has:
+        \\ * `debits_posted = 10`
+        \\ * and `credits_posted = 0`
+        \\
+        \\And that **account `2`** has:
+        \\ * `debits_posted= 0`
+        \\ * and `credits_posted = 10`
+        ,
+    },
+    .{
+        .proper_name = "Two-Phase Transfer",
+        .directory = "two-phase",
+        .short_description =
+        \\Create two accounts and start a pending transfer between
+        \\them, then post the transfer.
+        ,
+        .long_description =
+        \\## 1. Create accounts
+        \\
+        \\This project starts by creating two accounts (`1` and `2`).
+        \\
+        \\## 2. Create pending transfer
+        \\
+        \\Then it begins a
+        \\pending transfer of `500` of an amount from account `1` to
+        \\account `2`.
+        \\
+        \\## 3. Fetch and validate pending account balances
+        \\
+        \\Then it fetches both accounts and validates that **account `1`** has:
+        \\ * `debits_posted = 0`
+        \\ * `credits_posted = 0`
+        \\ * `debits_pending = 500`
+        \\ * and `credits_pending = 0`
+        \\
+        \\And that **account `2`** has:
+        \\ * `debits_posted = 0`
+        \\ * `credits_posted = 0`
+        \\ * `debits_pending = 0`
+        \\ * and `credits_pending = 500`
+        \\
+        \\(This is because a pending
+        \\transfer only affects **pending** credits and debits on accounts,
+        \\not **posted** credits and debits.)
+        \\
+        \\## 4. Post pending transfer
+        \\
+        \\Then it creates a second transfer that marks the first
+        \\transfer as posted.
+        \\
+        \\## 5. Fetch and validate transfers
+        \\
+        \\Then it fetches both transfers, validates
+        \\that the two transfers exist, validates that the first
+        \\transfer had (and still has) a `pending` flag, and validates
+        \\that the second transfer had (and still has) a
+        \\`post_pending_transfer` flag.
+        \\
+        \\## 6. Fetch and validate final account balances
+        \\
+        \\Finally, it fetches both accounts, validates that both exist,
+        \\and checks that credits and debits for both accounts are now
+        \\*posted*, not pending.
+        \\
+        \\Specifically, that **account `1`** has:
+        \\ * `debits_posted = 500`
+        \\ * `credits_posted = 0`
+        \\ * `debits_pending = 0`
+        \\ * and `credits_pending = 0`
+        \\
+        \\And that **account `2`** has:
+        \\ * `debits_posted = 0`
+        \\ * `credits_posted = 500`
+        \\ * `debits_pending = 0`
+        \\ * and `credits_pending = 0`
+        ,
+    },
+    .{
+        .proper_name = "Many Two-Phase Transfers",
+        .directory = "two-phase-many",
+        .short_description =
+        \\Create two accounts and start a number of pending transfers
+        \\between them, posting and voiding alternating transfers.
+        ,
+        .long_description =
+        \\## 1. Create accounts
+        \\
+        \\This project starts by creating two accounts (`1` and `2`).
+        \\
+        \\## 2. Create pending transfers
+        \\
+        \\Then it begins 5 pending transfers of amounts `100` to
+        \\`500`, incrementing by `100` for each transfer.
+        \\
+        \\## 3. Fetch and validate pending account balances
+        \\
+        \\Then it fetches both accounts and validates that **account `1`** has:
+        \\ * `debits_posted = 0`
+        \\ * `credits_posted = 0`
+        \\ * `debits_pending = 1500`
+        \\ * and `credits_pending = 0`
+        \\
+        \\And that **account `2`** has:
+        \\ * `debits_posted = 0`
+        \\ * `credits_posted = 0`
+        \\ * `debits_pending = 0`
+        \\ * and `credits_pending = 1500`
+        \\
+        \\(This is because a pending transfer only affects **pending**
+        \\credits and debits on accounts, not **posted** credits and
+        \\debits.)
+        \\
+        \\## 4. Post and void alternating transfers
+        \\
+        \\Then it alternatively posts and voids each transfer,
+        \\checking account balances after each transfer.
+        \\
+        \\## 6. Fetch and validate final account balances
+        \\
+        \\Finally, it fetches both accounts, validates that both exist,
+        \\and checks that credits and debits for both accounts are now
+        \\solely *posted*, not pending.
+        \\
+        \\Specifically, that **account `1`** has:
+        \\ * `debits_posted = 900`
+        \\ * `credits_posted = 0`
+        \\ * `debits_pending = 0`
+        \\ * and `credits_pending = 0`
+        \\
+        \\And that **account `2`** has:
+        \\ * `debits_posted = 0`
+        \\ * `credits_posted = 900`
+        \\ * `debits_pending = 0`
+        \\ * and `credits_pending = 0`
+        ,
+    },
+};

data/ext/tb_client/tigerbeetle/src/clients/docs_types.zig

@@ -0,0 +1,90 @@
+// The purpose of these types is to help in reading this doc, not
+// because the types matter.
+const String = []const u8;
+
+// All Code variables are potentially tested and run in CI.
+const Code = []const u8;
+
+// All Markdown strings are never tested and run in CI.
+const Markdown = []const u8;
+
+pub const Docs = struct {
+    // Name of the directory (relative to /src/clients)
+    directory: String,
+
+    // Package name (i.e. tigerbeetle-go, tigerbeetle-node, etc.)
+    name: String,
+
+    // Name for syntax highlighting (i.e. javascript for node, go for go, etc.)
+    markdown_name: String,
+
+    // File extension without dot (i.e. js, go, etc.)
+    extension: String,
+
+    // For the title of the page on the docs site.
+    proper_name: String,
+
+    // Introduction to the client. Links to docs or build badges or
+    // whatnot.
+    description: Markdown,
+
+    // Any libraries or languages and their required versions for
+    // using, not necessarily hacking on, this client.
+    prerequisites: Markdown,
+
+    // If you need an additional project file like pom.xml or
+    // package.json. Leave blank if not needed.
+    project_file_name: String,
+    // The actual contents of the file. Leave blank if not needed.
+    project_file: Code,
+
+    // If you need to override the default name of test.${extension}
+    // such as when file names have meaning (i.e. Java).
+    test_file_name: String,
+
+    // Any setup needed for a project before compiling and running
+    // such as `go mod init myProject && go mod tidy` or `npm install
+    // tigerbeetle-node`.
+    install_commands: Code,
+
+    // Commands for building and running code.
+    run_commands: Code,
+
+    // If you want to include links to examples.
+    examples: Markdown,
+
+    client_object_documentation: Markdown,
+
+    create_accounts_documentation: Markdown,
+
+    create_accounts_errors_documentation: Markdown,
+
+    account_flags_documentation: Markdown,
+
+    create_transfers_documentation: Markdown,
+
+    create_transfers_errors_documentation: Markdown,
+
+    // Good example of using batches to create transfers.
+    // Bad example of not using batches well to create transfers.
+
+    transfer_flags_documentation: Markdown,
+
+    // Optional prefix if test code must be in a certain directory
+    // (e.g. Java and `src/main/java`).
+    test_source_path: String,
+};
+
+pub const Sample = struct {
+    // Capitalized name of the sample program
+    proper_name: String,
+
+    // e.g. `basic`, `two-phase`, etc.
+    directory: String,
+
+    // For use in the language primary README
+    short_description: String,
+
+    // For use as the introduction on the individual sample README
+    long_description: String,
+};

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

@@ -0,0 +1,203 @@
+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("TigerBeetle.sln"));
+
+    try shell.exec_zig("build clients:dotnet -Drelease", .{});
+    try shell.exec_zig("build -Drelease", .{});
+
+    try shell.exec("dotnet restore", .{});
+    try shell.exec("dotnet format --no-restore --verify-no-changes", .{});
+
+    // Unit tests.
+    try shell.exec("dotnet build --no-restore  --configuration Release", .{});
+    // Disable coverage on CI, as it is flaky, see
+    // <https://github.com/coverlet-coverage/coverlet/issues/865>
+    try shell.exec(
+        \\dotnet test --no-restore
+        \\    --logger:{logger}
+        \\    /p:CollectCoverage=false
+        \\    /p:Threshold={threshold}
+        \\    /p:ThresholdType={threshold_type}
+    , .{
+        // Dotnet wants quotes inside the argument.
+        .logger = "\"console;verbosity=detailed\"",
+        .threshold = "\"95,85,95\"",
+        .threshold_type = "\"line,branch,method\"",
+    });
+
+    // Integration tests.
+    inline for (.{ "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("dotnet run", .{});
+    }
+
+    // Container smoke tests.
+    if (builtin.target.os.tag == .linux) {
+        // Here, we want to check that our package does not break horrible on upstream containers
+        // due to missing runtime dependencies, mismatched glibc ABI and similar issues.
+        //
+        // We don't necessary want to be able to _build_ code inside such a container, we only
+        // need to check that pre-built code runs successfully. So, build a package on host,
+        // mount it inside the container and smoke test.
+        //
+        // We run an sh script inside a container, because it is trivial. If it grows larger,
+        // we should consider running a proper zig program inside.
+        try shell.exec("dotnet pack --configuration Release", .{});
+
+        const image_tags = .{
+            "8.0", "8.0-alpine",
+        };
+
+        inline for (image_tags) |image_tag| {
+            const image = "mcr.microsoft.com/dotnet/sdk:" ++ image_tag;
+            log.info("testing docker image: '{s}'", .{image});
+
+            for (0..5) |attempt| {
+                if (attempt > 0) std.time.sleep(1 * std.time.ns_per_min);
+                if (shell.exec("docker image pull {image}", .{ .image = image })) {
+                    break;
+                } else |_| {}
+            }
+
+            try shell.exec(
+                \\docker run
+                \\--security-opt seccomp=unconfined
+                \\--volume ./TigerBeetle/bin/Release:/host
+                \\{image}
+                \\sh
+                \\-c {script}
+            , .{
+                .image = image,
+                .script =
+                \\set -ex
+                \\mkdir test-project && cd test-project
+                \\dotnet nuget add source /host
+                \\dotnet new console
+                \\dotnet add package tigerbeetle --source /host > /dev/null
+                \\cat <<EOF > Program.cs
+                \\using System;
+                \\using TigerBeetle;
+                \\public class Program {
+                \\  public static void Main() {
+                \\    new Client(UInt128.Zero, new [] {"3001"}).Dispose();
+                \\    Console.WriteLine("SUCCESS");
+                \\  }
+                \\}
+                \\EOF
+                \\dotnet run
+                ,
+            });
+        }
+    }
+}
+
+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("dotnet new console", .{});
+
+    // NuGet may take a few minutes to make the new package available for download.
+    for (0..9) |_| {
+        if (try nuget_install(shell, .{ .version = options.version }) == .ok) break;
+        log.warn("waiting for 5 minutes for the {s} version to appear in nuget.org", .{
+            options.version,
+        });
+        std.time.sleep(5 * std.time.ns_per_min);
+    } else {
+        switch (try nuget_install(shell, .{ .version = options.version })) {
+            .ok => {},
+            .retry => |err| {
+                log.err("package is not available in nuget.org", .{});
+                return err;
+            },
+        }
+    }
+
+    try Shell.copy_path(
+        shell.project_root,
+        "src/clients/dotnet/samples/basic/Program.cs",
+        shell.cwd,
+        "Program.cs",
+    );
+    try shell.exec("dotnet run", .{});
+}
+
+fn nuget_install(shell: *Shell, options: struct {
+    version: []const u8,
+}) !union(enum) { ok, retry: anyerror } {
+    const command: []const u8 = "dotnet add package tigerbeetle --version {version}";
+    if (shell.exec(command, options)) {
+        return .ok;
+    } else |err| {
+        const exec_result = try shell.exec_raw(command, options);
+        switch (exec_result.term) {
+            .Exited => |code| if (code == 0) return .ok,
+            else => {},
+        }
+
+        // Error message:
+        // NU1102: Unable to find package tigerbeetle with version (>= {version}).
+        const package_missing = std.mem.indexOf(
+            u8,
+            exec_result.stdout,
+            "NU1102",
+        ) != null;
+        if (package_missing) return .{ .retry = err };
+        return err;
+    }
+}
+
+pub fn release_published_latest(shell: *Shell) ![]const u8 {
+    const DotnetSearch = struct {
+        const SearchResult = struct {
+            const Packages = struct {
+                id: []const u8,
+                latestVersion: []const u8,
+            };
+            packages: []Packages,
+        };
+        searchResult: []SearchResult,
+    };
+
+    const output = try shell.exec_stdout("dotnet package search tigerbeetle --format json", .{});
+    const dotnet_search_results = try std.json.parseFromSliceLeaky(
+        DotnetSearch,
+        shell.arena.allocator(),
+        output,
+        .{ .ignore_unknown_fields = true },
+    );
+
+    assert(dotnet_search_results.searchResult.len == 1);
+    assert(dotnet_search_results.searchResult[0].packages.len == 1);
+
+    assert(std.mem.eql(u8, dotnet_search_results.searchResult[0].packages[0].id, "tigerbeetle"));
+
+    return dotnet_search_results.searchResult[0].packages[0].latestVersion;
+}

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

@@ -0,0 +1,79 @@
+const Docs = @import("../docs_types.zig").Docs;
+
+pub const DotnetDocs = Docs{
+    .directory = "dotnet",
+
+    .markdown_name = "cs",
+    .extension = "cs",
+    .proper_name = ".NET",
+
+    .test_source_path = "",
+
+    .name = "tigerbeetle-dotnet",
+    .description =
+    \\The TigerBeetle client for .NET.
+    ,
+
+    .prerequisites =
+    \\* .NET >= 8.0.
+    \\
+    \\And if you do not already have NuGet.org as a package
+    \\source, make sure to add it:
+    \\
+    \\```console
+    \\dotnet nuget add source https://api.nuget.org/v3/index.json -n nuget.org
+    \\```
+    ,
+
+    .project_file_name = "",
+    .project_file = "",
+
+    .test_file_name = "Program",
+
+    .install_commands =
+    \\dotnet new console
+    \\dotnet add package tigerbeetle
+    ,
+    .run_commands = "dotnet run",
+
+    .examples = "",
+
+    .client_object_documentation = "",
+    .create_accounts_documentation =
+    \\The `UInt128` fields like `ID`, `UserData128`, `Amount` and
+    \\account balances have a few extension methods to make it easier
+    \\to convert 128-bit little-endian unsigned integers between
+    \\`BigInteger`, `byte[]`, and `Guid`.
+    \\
+    \\See the class [UInt128Extensions](/src/clients/dotnet/TigerBeetle/UInt128Extensions.cs)
+    \\for more details.
+    ,
+
+    .account_flags_documentation =
+    \\To toggle behavior for an account, combine enum values stored in the
+    \\`AccountFlags` object with bitwise-or:
+    \\
+    \\* `AccountFlags.None`
+    \\* `AccountFlags.Linked`
+    \\* `AccountFlags.DebitsMustNotExceedCredits`
+    \\* `AccountFlags.CreditsMustNotExceedDebits`
+    \\* `AccountFlags.History`
+    ,
+
+    .create_accounts_errors_documentation = "",
+
+    .create_transfers_documentation = "",
+
+    .create_transfers_errors_documentation = "",
+
+    .transfer_flags_documentation =
+    \\To toggle behavior for an account, combine enum values stored in the
+    \\`TransferFlags` object with bitwise-or:
+    \\
+    \\* `TransferFlags.None`
+    \\* `TransferFlags.Linked`
+    \\* `TransferFlags.Pending`
+    \\* `TransferFlags.PostPendingTransfer`
+    \\* `TransferFlags.VoidPendingTransfer`
+    ,
+};