Refactor configuration handling and integrate command-line argument parsing with args.zig

.gitignore

@@ -1,83 +1,15 @@
-# ---> Zig
+zig-cache/
 .zig-cache/
 zig-out/
 
-# ---> JetBrains
-# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider
-# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
+zig-pkg
 
-# User-specific stuff
-.idea/**/workspace.xml
-.idea/**/tasks.xml
-.idea/**/usage.statistics.xml
-.idea/**/dictionaries
-.idea/**/shelf
+build/
+build-*/
+docgen_tmp/
 
-# AWS User-specific
-.idea/**/aws.xml
+.zbscanhelper.zig
 
-# Generated files
-.idea/**/contentModel.xml
-
-# Sensitive or high-churn files
-.idea/**/dataSources/
-.idea/**/dataSources.ids
-.idea/**/dataSources.local.xml
-.idea/**/sqlDataSources.xml
-.idea/**/dynamic.xml
-.idea/**/uiDesigner.xml
-.idea/**/dbnavigator.xml
-
-# Gradle
-.idea/**/gradle.xml
-.idea/**/libraries
-
-# Gradle and Maven with auto-import
-# When using Gradle or Maven with auto-import, you should exclude module files,
-# since they will be recreated, and may cause churn.  Uncomment if using
-# auto-import.
-# .idea/artifacts
-# .idea/compiler.xml
-# .idea/jarRepositories.xml
-# .idea/modules.xml
-# .idea/*.iml
-# .idea/modules
-# *.iml
-# *.ipr
-
-# CMake
-cmake-build-*/
-
-# Mongo Explorer plugin
-.idea/**/mongoSettings.xml
-
-# File-based project format
-*.iws
-
-# IntelliJ
-out/
-
-# mpeltonen/sbt-idea plugin
-.idea_modules/
-
-# JIRA plugin
-atlassian-ide-plugin.xml
-
-# Cursive Clojure plugin
-.idea/replstate.xml
-
-# SonarLint plugin
-.idea/sonarlint/
-
-# Crashlytics plugin (for Android Studio and IntelliJ)
-com_crashlytics_export_strings.xml
-crashlytics.properties
-crashlytics-build.properties
-fabric.properties
-
-# Editor-based Rest Client
-.idea/httpRequests
-
-# Android studio 3.1+ serialized cache file
-.idea/caches/build_file_checksums.ser
+.idea/
 
+config/*.md

build.zig

@@ -0,0 +1,89 @@
+const std = @import("std");
+
+pub fn build(b: *std.Build) void
+{
+    const target   = b.standardTargetOptions(.{});
+    const optimize = b.standardOptimizeOption(.{});
+
+    const version = getGitVersion(b);
+
+    const options = b.addOptions();
+    options.addOption([]const u8, "version", version);
+
+    // deps
+
+    const toml_dep = b.dependency("toml", .{
+        .target   = target,
+        .optimize = optimize,
+    });
+
+    const args_dep = b.dependency("args", .{
+        .target   = target,
+        .optimize = optimize,
+    });
+
+    //
+
+    const mod = b.addModule("zocket", .{
+        .root_source_file = b.path("src/root.zig"),
+        .target           = target,
+    });
+
+    mod.addImport("toml", toml_dep.module("toml"));
+    mod.addImport("args", args_dep.module("args"));
+
+    const exe = b.addExecutable(.{
+        .name        = "zocket",
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("src/main.zig"),
+            .target           = target,
+            .optimize         = optimize,
+            .imports          = &.{
+                .{ .name = "zocket", .module = mod },
+            },
+        }),
+    });
+
+    exe.root_module.addOptions("build_options", options);
+
+    //
+
+    b.installArtifact(exe);
+
+    const run_step = b.step("run", "Run the app");
+    const run_cmd  = b.addRunArtifact(exe);
+
+    run_step.dependOn(&run_cmd.step);
+    run_cmd.step.dependOn(b.getInstallStep());
+
+    if (b.args) |args| {
+        run_cmd.addArgs(args);
+    }
+
+    const mod_tests = b.addTest(.{
+        .root_module = mod,
+    });
+
+    const run_mod_tests = b.addRunArtifact(mod_tests);
+
+    const exe_tests  = b.addTest(.{
+        .root_module = exe.root_module,
+    });
+
+    const run_exe_tests = b.addRunArtifact(exe_tests);
+
+    const test_step = b.step("test", "Run tests");
+    test_step.dependOn(&run_mod_tests.step);
+    test_step.dependOn(&run_exe_tests.step);
+}
+
+fn getGitVersion(b: *std.Build) []const u8
+{
+    const result = b.runAllowFail(
+        &.{ "git", "describe", "--tags", "--always", "--dirty" },
+        undefined,
+        .inherit,
+    ) catch return "0.0.0-unknown";
+
+    return b.dupe(std.mem.trim(u8, result, " \n\r\t"));
+}

build.zig.zon

@@ -0,0 +1,23 @@
+.{
+    .name                = .zocket,
+    .version             = "0.0.0",
+    .fingerprint         = 0x22ea3973fd74773f,
+    .minimum_zig_version = "0.16.0",
+    .dependencies        = .{
+        .toml = .{
+            .url  = "git+https://github.com/sam701/zig-toml?ref=zig-0.16#8685923e32e8b8a795eb2715684236975a70faed",
+            .hash = "toml-0.3.0-bV14BRmKAQAWR0FT0KUKFwVJTImaFhWjSe6HfSMtNZOH",
+        },
+        .args = .{
+            .url  = "https://github.com/muhammad-fiaz/args.zig/archive/refs/tags/0.0.8.tar.gz",
+            .hash = "args-0.0.8-8hzgbsBECgD3C0uPaFNcK9UFTZ210rWU4XIhopR8snoA",
+        },
+    },
+    .paths               = .{
+        "build.zig",
+        "build.zig.zon",
+        "src",
+        "LICENSE",
+        "README.md",
+    },
+}

config/config.toml

@@ -0,0 +1,137 @@
+[node]
+id          = "node-01"
+data_dir    = "/var/lib/zocket"                      # /$data_dir/$id/*
+private_key = "/var/lib/zocket/node-01/identity.key" # ed25519, auto-generated on first run if missing, default = /$data_dir/$id/identity.key
+# DEFAULT ASSUMPTION: ephemeral.
+# A fresh keypair each restart is fine and expected as nothing is persisted to disk on purpose
+# (see mesh.discoverability + mesh.trust below), everything mesh-wide is rediscovered via
+# gossip/broadcast after (re)connecting to a seed peer in mesh.peers.
+# EXCEPTION:
+# If another node pins THIS node by pubkey in its own static mesh.peers[] entry, this
+# key must be persisted (mount on a volume) as a pinned pubkey is a promise of a stable identity,
+# and an ephemeral key breaks that pin on every restart.
+# Only relevant for statically pinned, long-lived "hub" style nodes; auto-enrolled/broadcast-mode peers never need this.
+
+[log]
+level  = "info"   # debug | info | warn | error
+format = "json"   # json | text
+output = "stdout" # stdout | /path/to/file.log
+
+# ----
+
+[listen.client]
+enabled = true
+bind    = "0.0.0.0:8080"
+
+[listen.client.tls]
+enabled = false
+cert    = "/etc/zocket/client.crt"
+key     = "/etc/zocket/client.key"
+
+[listen.client.auth]
+mode = "token" # none | token
+# If mode is set to "token", then the client_id is DERIVED from the matched
+# identity's id below, never self-declared by the client.
+# If mode is set to "none", any client may self-declare their client_id.
+# On collision with an already-connected client_id, the NEW connection is rejected
+# (first-connected wins) to prevent a second client from silently taking over another's routing identity.
+
+[[listen.client.auth.identities]]
+id    = "discord-bot"
+token = "sdfb08zbd98bzbh9r98gh98enb"
+
+[[listen.client.auth.identities]]
+id    = "minecraft-mod"
+token = "sv8sovz987w98ruw9fwbgfubwf"
+
+[listen.client.access_control]
+mode = "allowlist"                  # allowlist | blocklist | disabled
+list = ["10.0.0.0/24", "127.0.0.1"] # IP | CIDR
+
+[listen.client.limits]
+max_message_bytes  = 65536
+max_frame_bytes    = 65536
+idle_timeout_secs  = 300
+ping_interval_secs = 30
+max_missed_pongs   = 2
+max_connections    = 256
+
+[listen.client.limits.rate_limit]
+enabled          = true
+messages_per_sec = 50
+burst            = 100
+
+# ----
+
+[listen.peer]
+enabled = true
+bind    = "0.0.0.0:8181"
+
+[listen.peer.tls]
+enabled             = false
+cert                = "/etc/zocket/peer.crt"
+key                 = "/etc/zocket/peer.key"
+require_client_cert = false
+
+[listen.peer.auth]
+mode = "pubkey" # pubkey
+# Peer links can inject routes and broadcasts mesh-wide, so identity is always cryptographically verified, regardless of access_control.
+# Every connecting peer proves possession of the private key matching a pubkey via a signed nonce challenge - no shared secret ever transits the wire.
+# 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.access_control]
+mode = "allowlist"                  # allowlist | blocklist | disabled
+list = ["10.0.0.0/24", "127.0.0.1"] # IP | CIDR
+
+[listen.peer.limits]
+max_message_bytes  = 1048576
+idle_timeout_secs  = 60
+ping_interval_secs = 15
+
+# ----
+
+[mesh]
+enabled      = true
+topology     = "full"   # full | static-partial | disabled
+routing_mode = "gossip" # gossip | reactive | static
+
+[mesh.discoverability]
+mode = "static" # static | broadcast
+# static:    mesh.peers below is the complete, manually-maintained set of instances.
+# broadcast: mesh.peers is just the initial seed; unknown nodes may connect and prove
+#            possession of a pubkey; they're auto-trusted and gossiped mesh-wide immediately.
+#            listen.peer.access_control is the real gate in this mode; scope it tightly.
+
+[[mesh.peers]]
+id             = "node-02"
+addr           = "10.0.0.2:8181"
+pubkey         = "rijgeb8u845un34tun34tou3nt3ot3untz3otn3to"
+reconnect      = true
+backoff_min_ms = 500
+backoff_max_ms = 30000
+
+[mesh.trust]
+gossip_new_peers = true # propagate newly-enrolled peer identities to the rest of the mesh
+
+[mesh.gossip]
+seen_cache_ttl_secs = 300
+route_ttl_secs      = 0   # 0 = no expiry, rely on explicit ROUTE_REMOVE
+
+[mesh.broadcast]
+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.
+
+# only used if routing_mode = "reactive"
+[mesh.reactive]
+query_ttl_hops      = 4
+query_timeout_ms    = 2000
+negative_cache_secs = 30
+
+# ----
+
+# prometheus format
+[metrics]
+enabled = true
+bind    = "127.0.0.1:9090"

src/config/config.zig

@@ -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);
+}

src/config/models.zig

@@ -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
+};

src/main.zig

@@ -0,0 +1,73 @@
+const zocket = @import("zocket");
+
+const std     = @import("std");
+const builtin = @import("builtin");
+const options = @import("build_options");
+
+
+const args = zocket.deps.args;
+
+pub fn main(init: std.process.Init) !void
+{
+    const io = init.io;
+
+    if (builtin.mode == .Debug)
+    {
+        var arena: std.heap.DebugAllocator(.{}) = .init;
+        defer _ = arena.deinit();
+
+        try run(io, arena.allocator(), "config/config.toml");
+    }
+    else
+    {
+        var arena = std.heap.ArenaAllocator.init(std.heap.smp_allocator);
+        defer arena.deinit();
+        const allocator = arena.allocator();
+
+        var tmpArena       = std.heap.ArenaAllocator.init(std.heap.smp_allocator);
+        const tmpAllocator = tmpArena.allocator();
+
+        var parser = try args.ArgumentParser.init(tmpAllocator, .{
+            .name        = "zocket",
+            .version     = options.version,
+            .description = "A lightweight Zig WebSocket server and mesh routing daemon.",
+        });
+
+        try parser.addOption("path", .{
+            .short = 'p',
+            .help  = "Configuration-File Path (*.toml)",
+        });
+
+        var result = try parser.parseProcess(init);
+
+        const tmpPath = result.getString("path") orelse blk: {
+            const exe = try std.process.executableDirPathAlloc(io, tmpAllocator);
+            break :blk  try std.Io.Dir.path.join(tmpAllocator, &.{ exe, "config/config.toml" });
+        };
+
+        const path = try allocator.dupe(u8, tmpPath);
+
+        tmpArena.deinit();
+
+        try run(io, allocator, path);
+    }
+}
+
+fn run(io: std.Io, allocator: std.mem.Allocator, path: []const u8) !void
+{
+    const parsed = zocket.config.parse(io, allocator, path) catch |err|
+    {
+        const msg: []const u8 = switch (err) {
+            error.FileNotFound => "File not found",
+            error.AccessDenied => "Permission denied reading",
+            else               => "Unexpected error opening",
+        };
+        std.log.err("{s}: '{s}' ({any})\n", .{ msg, path, err });
+        std.process.exit(1);
+    };
+    defer parsed.deinit();
+
+    const configuration = parsed.value;
+
+    std.debug.print("{any}", .{configuration});
+}

src/root.zig

@@ -0,0 +1,10 @@
+pub const deps = struct {
+    pub const args = @import("args");
+};
+
+
+pub const config = @import("config/config.zig");
+
+test {
+    _ = config;
+}