Overlord/zocket
1
1
Fork 0
Code Issues Pull Requests Releases Activity

Add Config structure, TOML parser, and tests for zocket configuration

Browse Source
This commit is contained in:
Overlord
2026-08-01 14:23:07 +02:00
parent aa3b77eeda
commit a7aa1517ca
6 changed files with 274 additions and 125 deletions
Download Patch File Download Diff File Expand all files Collapse all files

139
build.zig
View File

@@ -1,156 +1,65 @@
const std = @import("std");
// Although this function looks imperative, it does not perform the build
// directly and instead it mutates the build graph (`b`) that will be then
// executed by an external runner. The functions in `std.Build` implement a DSL
// for defining build steps and express dependencies between them, allowing the
// build runner to parallelize the build automatically (and the cache system to
// know when a step doesn't need to be re-run).
pub fn build(b: *std.Build) void {
// Standard target options allow the person running `zig build` to choose
// what target to build for. Here we do not override the defaults, which
// means any target is allowed, and the default is native. Other options
// for restricting supported target set are available.
const target = b.standardTargetOptions(.{});
// Standard optimization options allow the person running `zig build` to select
// between Debug, ReleaseSafe, ReleaseFast, and ReleaseSmall. Here we do not
// set a preferred release mode, allowing the user to decide how to optimize.
pub fn build(b: *std.Build) void
{
const target = b.standardTargetOptions(.{});
const optimize = b.standardOptimizeOption(.{});
// It's also possible to define more custom flags to toggle optional features
// of this build script using `b.option()`. All defined flags (including
// target and optimize options) will be listed when running `zig build --help`
// in this directory.
// This creates a module, which represents a collection of source files alongside
// some compilation options, such as optimization mode and linked system libraries.
// Zig modules are the preferred way of making Zig code available to consumers.
// addModule defines a module that we intend to make available for importing
// to our consumers. We must give it a name because a Zig package can expose
// multiple modules and consumers will need to be able to specify which
// module they want to access.
const mod = b.addModule("zocket", .{
// The root source file is the "entry point" of this module. Users of
// this module will only be able to access public declarations contained
// in this file, which means that if you have declarations that you
// intend to expose to consumers that were defined in other files part
// of this module, you will have to make sure to re-export them from
// the root file.
.root_source_file = b.path("src/root.zig"),
// Later on we'll use this module as the root module of a test executable
// which requires us to specify a target.
.target = target,
// deps
const toml_dep = b.dependency("toml", .{
.target = target,
.optimize = optimize,
});
// Here we define an executable. An executable needs to have a root module
// which needs to expose a `main` function. While we could add a main function
// to the module defined above, it's sometimes preferable to split business
// logic and the CLI into two separate modules.
//
// If your goal is to create a Zig library for others to use, consider if
// it might benefit from also exposing a CLI tool. A parser library for a
// data serialization format could also bundle a CLI syntax checker, for example.
//
// If instead your goal is to create an executable, consider if users might
// be interested in also being able to embed the core functionality of your
// program in their own executable in order to avoid the overhead involved in
// subprocessing your CLI tool.
//
// If neither case applies to you, feel free to delete the declaration you
// don't need and to put everything under a single module.
const mod = b.addModule("zocket", .{
.root_source_file = b.path("src/root.zig"),
.target = target,
});
mod.addImport("toml", toml_dep.module("toml"));
const exe = b.addExecutable(.{
.name = "zocket",
.name = "zocket",
.root_module = b.createModule(.{
// b.createModule defines a new module just like b.addModule but,
// unlike b.addModule, it does not expose the module to consumers of
// this package, which is why in this case we don't have to give it a name.
.root_source_file = b.path("src/main.zig"),
// Target and optimization levels must be explicitly wired in when
// defining an executable or library (in the root module), and you
// can also hardcode a specific target for an executable or library
// definition if desireable (e.g. firmware for embedded devices).
.target = target,
.optimize = optimize,
// List of modules available for import in source files part of the
// root module.
.imports = &.{
// Here "zocket" is the name you will use in your source code to
// import this module (e.g. `@import("zocket")`). The name is
// repeated because you are allowed to rename your imports, which
// can be extremely useful in case of collisions (which can happen
// importing modules from different packages).
.target = target,
.optimize = optimize,
.imports = &.{
.{ .name = "zocket", .module = mod },
},
}),
});
// This declares intent for the executable to be installed into the
// install prefix when running `zig build` (i.e. when executing the default
// step). By default the install prefix is `zig-out/` but can be overridden
// by passing `--prefix` or `-p`.
//
b.installArtifact(exe);
// This creates a top level step. Top level steps have a name and can be
// invoked by name when running `zig build` (e.g. `zig build run`).
// This will evaluate the `run` step rather than the default step.
// For a top level step to actually do something, it must depend on other
// steps (e.g. a Run step, as we will see in a moment).
const run_step = b.step("run", "Run the app");
const run_cmd = b.addRunArtifact(exe);
// This creates a RunArtifact step in the build graph. A RunArtifact step
// invokes an executable compiled by Zig. Steps will only be executed by the
// runner if invoked directly by the user (in the case of top level steps)
// or if another step depends on it, so it's up to you to define when and
// how this Run step will be executed. In our case we want to run it when
// the user runs `zig build run`, so we create a dependency link.
const run_cmd = b.addRunArtifact(exe);
run_step.dependOn(&run_cmd.step);
// By making the run step depend on the default step, it will be run from the
// installation directory rather than directly from within the cache directory.
run_cmd.step.dependOn(b.getInstallStep());
// This allows the user to pass arguments to the application in the build
// command itself, like this: `zig build run -- arg1 arg2 etc`
if (b.args) |args| {
run_cmd.addArgs(args);
}
// Creates an executable that will run `test` blocks from the provided module.
// Here `mod` needs to define a target, which is why earlier we made sure to
// set the releative field.
const mod_tests = b.addTest(.{
.root_module = mod,
});
// A run step that will run the test executable.
const run_mod_tests = b.addRunArtifact(mod_tests);
// Creates an executable that will run `test` blocks from the executable's
// root module. Note that test executables only test one module at a time,
// hence why we have to create two separate ones.
const exe_tests = b.addTest(.{
const exe_tests = b.addTest(.{
.root_module = exe.root_module,
});
// A run step that will run the second test executable.
const run_exe_tests = b.addRunArtifact(exe_tests);
// A top level step for running all tests. dependOn can be called multiple
// times and since the two run steps do not depend on one another, this will
// make the two of them run in parallel.
const test_step = b.step("test", "Run tests");
test_step.dependOn(&run_mod_tests.step);
test_step.dependOn(&run_exe_tests.step);
// Just like flags, top level steps are also listed in the `--help` menu.
//
// The Zig build system is entirely implemented in userland, which means
// that it cannot hook into private compiler APIs. All compilation work
// orchestrated by the build system will result in other Zig compiler
// subcommands being invoked with the right flags defined. You can observe
// these invocations when one fails (or you pass a flag to increase
// verbosity) to validate assumptions and diagnose problems.
//
// Lastly, the Zig build system is relatively simple and self-contained,
// and reading its source code will allow you to master it.
}

30
src/config/config.zig Normal file
View File

@@ -0,0 +1,30 @@
const Config = @import("models.zig").Config;
const std = @import("std");
const toml = @import("toml");
pub fn parse(io: std.Io, allocator: std.mem.Allocator, path: []const u8) !toml.Parsed(Config)
{
var parser = toml.Parser(Config).init(allocator);
defer parser.deinit();
return parser.parseFile(io,path);
}
test "parse zocket config"
{
var threaded: std.Io.Threaded = .init(std.testing.allocator, .{});
defer threaded.deinit();
const io = threaded.io();
const allocator = std.testing.allocator;
const parsed = try parse(io, allocator, "zocket/config.toml");
defer parsed.deinit();
const cfg = parsed.value;
try std.testing.expectEqualStrings("node-01", cfg.node.id);
try std.testing.expect(cfg.listen.client.enabled);
try std.testing.expectEqual(@as(usize, 1), cfg.mesh.peers.len);
try std.testing.expectEqualStrings("node-02", cfg.mesh.peers[0].id);
}

209
src/config/models.zig Normal file
View File

@@ -0,0 +1,209 @@
const std = @import("std");
const toml = @import("toml");
//
pub const Config = struct {
node: Node,
log: Log = .{},
listen: Listen = .{},
mesh: Mesh = .{},
metrics: Metrics = .{},
};
//
/// Per-instance identity. Intentionally has no defaults - id/data_dir/private_key
/// are meaningless without a concrete deployment behind them.
pub const Node = struct {
id: []const u8,
data_dir: []const u8,
private_key: []const u8, // ed25519; auto-generated on first run if missing
};
pub const LogLevel = enum {
debug,
info,
warn,
@"error",
};
pub const LogFormat = enum {
json,
text,
};
pub const Log = struct {
level: LogLevel = .info,
format: LogFormat = .json,
output: []const u8 = "stdout", // or "/path/to/file.log"
};
pub const Listen = struct {
client: ListenClient = .{},
peer: ListenPeer = .{},
};
pub const ListenClient = struct {
enabled: bool = true,
bind: []const u8 = "0.0.0.0:8080",
tls: ClientTls = .{},
auth: ClientAuth = .{},
access_control: AccessControl = .{},
limits: ClientLimits = .{},
};
pub const ClientTls = struct {
enabled: bool = false,
cert: []const u8 = "/etc/zocket/client.crt",
key: []const u8 = "/etc/zocket/client.key",
};
pub const ClientAuthMode = enum {
none, // clients self-declare their client_id
token, // client_id is derived from the matched identity below
};
pub const ClientAuth = struct {
mode: ClientAuthMode = .token,
identities: []Identity = &[_]Identity{},
};
/// A single client credential. No defaults as each identity is a distinct
/// (id, token) pair that must be explicitly provisioned.
pub const Identity = struct {
id: []const u8,
token: []const u8,
};
/// Shared by listen.client.access_control and listen.peer.access_control.
pub const AccessControlMode = enum {
allowlist,
blocklist,
disabled,
};
pub const AccessControl = struct {
mode: AccessControlMode = .allowlist,
list: [][]const u8 = &[_][]const u8{}, // IP | CIDR entries
};
pub const ClientLimits = struct {
max_message_bytes: i64 = 65536,
max_frame_bytes: i64 = 65536,
idle_timeout_secs: i64 = 300,
ping_interval_secs: i64 = 30,
max_missed_pongs: i64 = 2,
max_connections: i64 = 256,
rate_limit: RateLimit = .{},
};
pub const RateLimit = struct {
enabled: bool = true,
messages_per_sec: i64 = 50,
burst: i64 = 100,
};
pub const ListenPeer = struct {
enabled: bool = true,
bind: []const u8 = "0.0.0.0:8181",
tls: PeerTls = .{},
auth: PeerAuth = .{},
access_control: AccessControl = .{},
limits: PeerLimits = .{},
};
pub const PeerTls = struct {
enabled: bool = false,
cert: []const u8 = "/etc/zocket/peer.crt",
key: []const u8 = "/etc/zocket/peer.key",
require_client_cert: bool = false,
};
pub const PeerAuthMode = enum {
pubkey, // only supported mode: signed-nonce challenge, never a shared secret
};
pub const PeerAuth = struct {
mode: PeerAuthMode = .pubkey,
};
pub const PeerLimits = struct {
max_message_bytes: i64 = 1048576,
idle_timeout_secs: i64 = 60,
ping_interval_secs: i64 = 15,
};
pub const MeshTopology = enum {
full,
@"static-partial",
disabled,
};
pub const RoutingMode = enum {
gossip,
reactive,
static,
};
pub const Mesh = struct {
enabled: bool = true,
topology: MeshTopology = .full,
routing_mode: RoutingMode = .gossip,
discoverability: Discoverability = .{},
peers: []MeshPeer = &[_]MeshPeer{},
trust: Trust = .{},
gossip: Gossip = .{},
broadcast: Broadcast = .{},
reactive: Reactive = .{},
};
pub const DiscoverabilityMode = enum {
// mesh.peers is the complete, manually-maintained set of instances.
static,
// mesh.peers is just the initial seed; unknown nodes may connect and
// prove possession of a pubkey, then get auto-trusted and gossiped
// mesh-wide. listen.peer.access_control is the real gate in this mode.
broadcast,
};
pub const Discoverability = struct {
mode: DiscoverabilityMode = .static,
};
/// A statically-pinned peer. No defaults for id/addr/pubkey as pinning a
/// peer's identity is the entire point, so these must be explicit.
pub const MeshPeer = struct {
id: []const u8,
addr: []const u8,
pubkey: []const u8,
reconnect: bool = true,
backoff_min_ms: i64 = 500,
backoff_max_ms: i64 = 30000,
};
pub const Trust = struct {
gossip_new_peers: bool = true, // propagate newly-enrolled peer identities mesh-wide
};
pub const Gossip = struct {
seen_cache_ttl_secs: i64 = 300,
route_ttl_secs: i64 = 0, // 0 = no expiry, rely on explicit ROUTE_REMOVE
};
pub const Broadcast = struct {
// Peer-only (target = "*"); never exposed to clients on listen.client.
enabled: bool = true,
};
pub const Reactive = struct {
// Only used when mesh.routing_mode = .reactive.
query_ttl_hops: i64 = 4,
query_timeout_ms: i64 = 2000,
negative_cache_secs: i64 = 30,
};
pub const Metrics = struct {
enabled: bool = true,
bind: []const u8 = "127.0.0.1:9090", // prometheus format
};

5
src/main.zig
View File

@@ -1,8 +1,7 @@
const std = @import("std");
const Io = std.Io;
const zocket = @import("zocket");
const std = @import("std");
pub fn main(init: std.process.Init) !void
{
_ = init;

5
src/root.zig
View File

@@ -1 +1,6 @@
const std = @import("std");
pub const config = @import("config/config.zig");
test {
_ = config;
}

11
zocket/config.toml
View File

@@ -80,11 +80,6 @@ mode = "pubkey" # pubkey
# For a KNOWN node_id, the pubkey must match mesh.peers[].pubkey exactly, or the connection is rejected outright.
# For a claimed node_id that isn't yet known, see mesh.discoverability = "broadcast" below.
[listen.peer.bootstrap]
enabled = false # only consulted when mesh.discoverability.mode = "broadcast"
# a bootstrap token grants ONLY "permission to register one new peer identity" —
# never permission to act as an already-known peer. keep these short-lived / single-use.
[listen.peer.access_control]
mode = "allowlist" # allowlist | blocklist | disabled
list = ["10.0.0.0/24", "127.0.0.1"] # IP | CIDR
@@ -128,13 +123,15 @@ enabled = true
# Broadcasting (target = "*") is peer-only and never exposed to clients on listen.client.
# Floods across peer links using the same seen_cache dedup as gossip route announcements.
[mesh.reactive] # only used if routing_mode = "reactive"
# only used if routing_mode = "reactive"
[mesh.reactive]
query_ttl_hops = 4
query_timeout_ms = 2000
negative_cache_secs = 30
# ----
[metrics] # prometheus format
# prometheus format
[metrics]
enabled = true
bind = "127.0.0.1:9090"