milestone 8: web server, rest api, sse, auth, metrics and static assets

2026-08-02 00:54:13 +02:00
parent a8092bb1b9
commit 5253c47303
59 changed files with 19640 additions and 150 deletions
@@ -0,0 +1,361 @@
+//! `/api/rules` — the per-group allow and block rules.
+//!
+//! A rule names its group by row id, not by name: the API identifies every
+//! resource by id, and a `group_id` no group holds is then the foreign-key
+//! violation it is (409) rather than a lookup that quietly writes nothing.
+//!
+//! `kind` and `action` travel as the words the database stores (`exact` /
+//! `wildcard`, `allow` / `block`), so one vocabulary describes a rule in the
+//! config file, in the database and on the wire.
+//!
+//! Rules take effect live: the write is followed by the reload seam, and the
+//! next query is matched against the new snapshot (ruling 12).
+
+const std = @import("std");
+const Allocator = std.mem.Allocator;
+
+const http_util = @import("../http_util.zig");
+const model = @import("../../config/model.zig");
+const mutations = @import("mutations.zig");
+const rules_repo = @import("../../storage/repositories/rules_repo.zig");
+const server = @import("../server.zig");
+
+const Failure = mutations.Failure;
+const Request = http_util.Request;
+const HandlerError = http_util.HandlerError;
+
+const group_conflict = "that group does not exist";
+
+const Body = struct {
+    group_id: i64,
+    pattern: []const u8,
+    kind: []const u8,
+    action: []const u8,
+};
+
+const Created = union(enum) { id: i64, fail: Failure };
+
+/// A body's `kind` and `action` decoded, or the 400 that says which word was
+/// not understood.
+fn toInput(body: Body) union(enum) { input: rules_repo.RuleInput, fail: Failure } {
+    const kind = model.RuleKind.fromDb(body.kind) orelse
+        return .{ .fail = .{ .invalid = "kind must be 'exact' or 'wildcard'" } };
+    const action = model.RuleAction.fromDb(body.action) orelse
+        return .{ .fail = .{ .invalid = "action must be 'allow' or 'block'" } };
+    return .{ .input = .{
+        .group_id = body.group_id,
+        .pattern = body.pattern,
+        .kind = kind,
+        .action = action,
+    } };
+}
+
+// ---------------------------------------------------------------------------
+// decisions
+// ---------------------------------------------------------------------------
+
+pub fn applyCreate(
+    state: *server.WebState,
+    io: std.Io,
+    arena: Allocator,
+    item: rules_repo.RuleInput,
+) error{OutOfMemory}!Created {
+    const database = switch (mutations.configDb(state)) {
+        .database => |value| value,
+        .fail => |failure| return .{ .fail = failure },
+    };
+    if (try mutations.checkRule(arena, item.pattern, item.kind)) |problem| {
+        return .{ .fail = .{ .invalid = problem } };
+    }
+
+    state.config_lock.lockUncancelable(io);
+    const inserted = rules_repo.insertRuleRow(database, item, mutations.nowSeconds(io));
+    state.config_lock.unlock(io);
+
+    const id = inserted catch |err| return .{ .fail = mutations.dbFailure(err, group_conflict) };
+    if (mutations.reload(state, io)) |failure| return .{ .fail = failure };
+    return .{ .id = id };
+}
+
+pub fn applyUpdate(
+    state: *server.WebState,
+    io: std.Io,
+    arena: Allocator,
+    id: i64,
+    item: rules_repo.RuleInput,
+) error{OutOfMemory}!?Failure {
+    const database = switch (mutations.configDb(state)) {
+        .database => |value| value,
+        .fail => |failure| return failure,
+    };
+    if (try mutations.checkRule(arena, item.pattern, item.kind)) |problem| {
+        return .{ .invalid = problem };
+    }
+
+    state.config_lock.lockUncancelable(io);
+    const written = rules_repo.updateRule(database, id, item);
+    state.config_lock.unlock(io);
+
+    written catch |err| return mutations.dbFailure(err, group_conflict);
+    return mutations.reload(state, io);
+}
+
+pub fn applyDelete(state: *server.WebState, io: std.Io, id: i64) ?Failure {
+    const database = switch (mutations.configDb(state)) {
+        .database => |value| value,
+        .fail => |failure| return failure,
+    };
+
+    state.config_lock.lockUncancelable(io);
+    const written = rules_repo.deleteRule(database, id);
+    state.config_lock.unlock(io);
+
+    written catch |err| return mutations.dbFailure(err, group_conflict);
+    return mutations.reload(state, io);
+}
+
+// ---------------------------------------------------------------------------
+// routes
+// ---------------------------------------------------------------------------
+
+/// The wire shape of a rule: the row with its enums spelled the way the
+/// database spells them.
+const RuleView = struct {
+    id: i64,
+    group_id: i64,
+    group: []const u8,
+    pattern: []const u8,
+    kind: []const u8,
+    action: []const u8,
+    created_at: i64,
+
+    fn from(row: rules_repo.RuleRow) RuleView {
+        return .{
+            .id = row.id,
+            .group_id = row.group_id,
+            .group = row.group,
+            .pattern = row.pattern,
+            .kind = row.kind.toDb(),
+            .action = row.action.toDb(),
+            .created_at = row.created_at,
+        };
+    }
+};
+
+pub fn list(state: *server.WebState, io: std.Io, request: *Request) HandlerError!void {
+    _ = io;
+    const database = switch (mutations.configDb(state)) {
+        .database => |value| value,
+        .fail => |failure| return mutations.respondFailure(request, failure, "listing rules"),
+    };
+
+    const rows = rules_repo.listRuleRows(database, request.arena) catch |err|
+        return mutations.respondFailure(request, .{ .internal = err }, "listing rules");
+
+    const views = try request.arena.alloc(RuleView, rows.items.len);
+    for (views, rows.items) |*view, row| view.* = .from(row);
+
+    return http_util.respondJson(request, .ok, .{ .rules = views }, &.{});
+}
+
+pub fn get(state: *server.WebState, io: std.Io, request: *Request) HandlerError!void {
+    _ = io;
+    const database = switch (mutations.configDb(state)) {
+        .database => |value| value,
+        .fail => |failure| return mutations.respondFailure(request, failure, "reading a rule"),
+    };
+
+    const row = rules_repo.getRule(database, request.arena, request.id.?) catch |err|
+        return mutations.respondFailure(request, .{ .internal = err }, "reading a rule");
+    const found = row orelse return mutations.respondFailure(request, .not_found, "");
+
+    return http_util.respondJson(request, .ok, RuleView.from(found), &.{});
+}
+
+pub fn create(state: *server.WebState, io: std.Io, request: *Request) HandlerError!void {
+    const parsed = http_util.parseBody(Body, request) catch |err|
+        return mutations.respondBadBody(request, err);
+    const item = switch (toInput(parsed.value)) {
+        .fail => |failure| return mutations.respondFailure(request, failure, "creating a rule"),
+        .input => |value| value,
+    };
+
+    return switch (try applyCreate(state, io, request.arena, item)) {
+        .fail => |failure| mutations.respondFailure(request, failure, "creating a rule"),
+        .id => |id| http_util.respondJson(request, .created, .{
+            .id = id,
+            .group_id = item.group_id,
+            .pattern = item.pattern,
+            .kind = item.kind.toDb(),
+            .action = item.action.toDb(),
+        }, &.{}),
+    };
+}
+
+pub fn update(state: *server.WebState, io: std.Io, request: *Request) HandlerError!void {
+    const parsed = http_util.parseBody(Body, request) catch |err|
+        return mutations.respondBadBody(request, err);
+    const item = switch (toInput(parsed.value)) {
+        .fail => |failure| return mutations.respondFailure(request, failure, "updating a rule"),
+        .input => |value| value,
+    };
+    const id = request.id.?;
+
+    if (try applyUpdate(state, io, request.arena, id, item)) |failure| {
+        return mutations.respondFailure(request, failure, "updating a rule");
+    }
+    return http_util.respondJson(request, .ok, .{
+        .id = id,
+        .group_id = item.group_id,
+        .pattern = item.pattern,
+        .kind = item.kind.toDb(),
+        .action = item.action.toDb(),
+    }, &.{});
+}
+
+pub fn remove(state: *server.WebState, io: std.Io, request: *Request) HandlerError!void {
+    if (applyDelete(state, io, request.id.?)) |failure| {
+        return mutations.respondFailure(request, failure, "deleting a rule");
+    }
+    return http_util.respondEmpty(request, .no_content);
+}
+
+// ---------------------------------------------------------------------------
+// tests
+// ---------------------------------------------------------------------------
+
+const testing = std.testing;
+
+const block_ads: rules_repo.RuleInput = .{
+    .group_id = 1,
+    .pattern = "ads.example",
+    .kind = .exact,
+    .action = .block,
+};
+
+test "a created rule is stored with the clock's created_at and reloads" {
+    var bench: mutations.Bench = undefined;
+    try bench.init(testing.allocator);
+    defer bench.deinit(testing.allocator);
+
+    const created = try applyCreate(&bench.state, bench.io(), bench.arena(), block_ads);
+    try testing.expectEqual(@as(usize, 1), bench.reloads);
+
+    const row = (try rules_repo.getRule(&bench.database, bench.arena(), created.id)).?;
+    try testing.expectEqualStrings("ads.example", row.pattern);
+    try testing.expectEqual(model.RuleAction.block, row.action);
+    try testing.expectEqualStrings("default", row.group);
+    try testing.expect(row.created_at > 0);
+}
+
+test "a pattern the validator refuses never reaches the database" {
+    var bench: mutations.Bench = undefined;
+    try bench.init(testing.allocator);
+    defer bench.deinit(testing.allocator);
+
+    const starred = try applyCreate(&bench.state, bench.io(), bench.arena(), .{
+        .group_id = 1,
+        .pattern = "ads.*.example",
+        .kind = .exact,
+        .action = .block,
+    });
+    try testing.expect(starred.fail == .invalid);
+
+    const starless = try applyCreate(&bench.state, bench.io(), bench.arena(), .{
+        .group_id = 1,
+        .pattern = "ads.example",
+        .kind = .wildcard,
+        .action = .allow,
+    });
+    try testing.expect(starless.fail == .invalid);
+
+    try testing.expectEqual(@as(i64, 0), try bench.queryInt("SELECT count(*) FROM rules"));
+    try testing.expectEqual(@as(usize, 0), bench.reloads);
+}
+
+test "a group id no group holds is a conflict" {
+    var bench: mutations.Bench = undefined;
+    try bench.init(testing.allocator);
+    defer bench.deinit(testing.allocator);
+
+    const created = try applyCreate(&bench.state, bench.io(), bench.arena(), .{
+        .group_id = 404,
+        .pattern = "ads.example",
+        .kind = .exact,
+        .action = .block,
+    });
+    try testing.expectEqualStrings(group_conflict, created.fail.conflict);
+    try testing.expectEqual(@as(usize, 0), bench.reloads);
+}
+
+test "an edited rule keeps its created_at" {
+    var bench: mutations.Bench = undefined;
+    try bench.init(testing.allocator);
+    defer bench.deinit(testing.allocator);
+
+    const created = try applyCreate(&bench.state, bench.io(), bench.arena(), block_ads);
+    const before = (try rules_repo.getRule(&bench.database, bench.arena(), created.id)).?.created_at;
+
+    const failure = try applyUpdate(&bench.state, bench.io(), bench.arena(), created.id, .{
+        .group_id = 1,
+        .pattern = "*.ads.example",
+        .kind = .wildcard,
+        .action = .allow,
+    });
+    try testing.expectEqual(@as(?Failure, null), failure);
+
+    const row = (try rules_repo.getRule(&bench.database, bench.arena(), created.id)).?;
+    try testing.expectEqualStrings("*.ads.example", row.pattern);
+    try testing.expectEqual(model.RuleKind.wildcard, row.kind);
+    try testing.expectEqual(before, row.created_at);
+    try testing.expectEqual(@as(usize, 2), bench.reloads);
+}
+
+test "an id no rule holds is a 404 on both update and delete" {
+    var bench: mutations.Bench = undefined;
+    try bench.init(testing.allocator);
+    defer bench.deinit(testing.allocator);
+
+    try testing.expectEqual(
+        Failure.not_found,
+        (try applyUpdate(&bench.state, bench.io(), bench.arena(), 999, block_ads)).?,
+    );
+    try testing.expectEqual(Failure.not_found, applyDelete(&bench.state, bench.io(), 999).?);
+    try testing.expectEqual(@as(usize, 0), bench.reloads);
+}
+
+test "a deleted rule is gone and the change is announced" {
+    var bench: mutations.Bench = undefined;
+    try bench.init(testing.allocator);
+    defer bench.deinit(testing.allocator);
+
+    const created = try applyCreate(&bench.state, bench.io(), bench.arena(), block_ads);
+    try testing.expectEqual(@as(?Failure, null), applyDelete(&bench.state, bench.io(), created.id));
+    try testing.expectEqual(@as(i64, 0), try bench.queryInt("SELECT count(*) FROM rules"));
+    try testing.expectEqual(@as(usize, 2), bench.reloads);
+}
+
+test "an unknown kind or action is a 400 before anything is written" {
+    try testing.expect(toInput(.{
+        .group_id = 1,
+        .pattern = "ads.example",
+        .kind = "regex",
+        .action = "block",
+    }).fail == .invalid);
+
+    try testing.expect(toInput(.{
+        .group_id = 1,
+        .pattern = "ads.example",
+        .kind = "exact",
+        .action = "drop",
+    }).fail == .invalid);
+
+    const good = toInput(.{
+        .group_id = 1,
+        .pattern = "ads.example",
+        .kind = "wildcard",
+        .action = "allow",
+    });
+    try testing.expectEqual(model.RuleKind.wildcard, good.input.kind);
+    try testing.expectEqual(model.RuleAction.allow, good.input.action);
+}