zig-healthchecks

A Zig client library for the Healthchecks.io ping API, for signaling that a scheduled job started, finished, or failed. It works against the hosted service and against a self-hosted instance, since the base URL is whatever you pass in.

The API documentation, generated from the doc comments, is published at https://jeff.jcollie.page/zig-healthchecks/.

Requirements

Zig 0.17.0 or later. The only dependency is zig-uuid, fetched by the Zig build system; non-Zig tooling comes from the Nix flake.

For Zig 0.16, use the zig-0.16 branch or the v0.1.0 tag.

Using it as a library

Add it to your build.zig.zon:

zig fetch --save git+https://git.jcollie.dev/jeff/zig-healthchecks.git

and wire the module up in build.zig:

const healthchecks_dep = b.dependency("healthchecks", .{
    .target = target,
    .optimize = optimize,
});

exe.root_module.addImport("healthchecks", healthchecks_dep.module("healthchecks"));

A client owns the HTTP connection and the allocator; a check is identified by its UUID, and each run of that check gets its own run ID so that overlapping runs stay distinguishable in the Healthchecks UI:

const hc = @import("healthchecks");

var client: hc.Client = try .init(io, gpa, "https://hc-ping.com/");
defer client.deinit();

var check = client.check(check_uuid);
var run = check.run();

_ = try run.start(null);
// ...do the work...
_ = try run.success(null);

Run carries one method per ping the API understands — start, success, fail, log, and exitStatus for reporting a process exit code. Each takes an optional payload, which is sent as the body of a POST when present and omitted in favor of a GET when it is null, and each returns the std.http.Status the server answered with.

Using the executable

The bundled healthchecks binary pings a check directly:

zig build run -- https://hc-ping.com/ <check-uuid>

Development

Everything the project needs is in the Nix devshell:

nix develop
zig build test
zig build check        # compile everything without running it
reuse lint
zig fmt --exclude zig-pkg --check .

zig build docs writes the API documentation to zig-out/docs, and zig build docs-serve serves it at http://127.0.0.1:8000/ (pick another port with -Ddocs-port=N). It has to be served rather than opened as a file, because the viewer fetches main.wasm and sources.tar at runtime and a browser refuses those from a file:// page.

The flake also packages the project, nix build .#zig-healthchecks, which builds offline from build.zig.zon.nix: a Nix expression for every Zig dependency, generated from build.zig.zon by zon2nix. Regenerate it whenever a dependency changes:

nix develop -c zon2nix --17 --nix=build.zig.zon.nix build.zig.zon

The same dependency set is .#zig-deps, and handing it to an ordinary build keeps Zig from fetching anything itself, which is what the workflow does:

zig build test --system "$(nix build --no-link --print-out-paths .#zig-deps)"

Where this lives

The canonical repository is on Forgejo, mirrored to Tangled, and seeded on Radicle:

git clone https://git.jcollie.dev/jeff/zig-healthchecks.git

• Forgejo — https://git.jcollie.dev/jeff/zig-healthchecks
• Tangled — https://tangled.org/jcollie.dev/zig-healthchecks
• Radicle — rad:zk6FntxLJT8j1WoAPDcFWQibtZiv

A Radicle repository is findable only by its ID, so to seed or clone it from the network:

rad clone rad:zk6FntxLJT8j1WoAPDcFWQibtZiv

License

MIT — see LICENSES/MIT.txt. The project follows the REUSE specification, so every file carries its own copyright and licensing information and reuse lint passes.