milestone 20: declarative configuration for iac

src/web/router.zig

@@ -37,12 +37,20 @@ pub const Auth = enum { open, session };
 /// monitoring endpoints so a Prometheus scrape can never be throttled.
 pub const RateLimit = enum { counted, exempt };
 
+/// What a route does to the configuration, and therefore whether file
+/// authority may allow it (milestone-20 ruling 7). `config_write` changes the
+/// declarative state the managed file owns; `runtime_action` changes runtime
+/// state the file never declares; `read` changes nothing.
+pub const Policy = enum { read, config_write, runtime_action };
+
 pub const RouteInfo = struct {
     method: http.Method,
     /// Segments separated by `/`, with at most one `{id}` capture, which must
     /// be a positive integer row id.
     pattern: []const u8,
     auth: Auth,
+    /// No default: a new route states its class or does not compile.
+    policy: Policy,
     handler: HandlerFn,
     rate_limit: RateLimit = .counted,
 };
@@ -158,6 +166,17 @@ pub fn dispatch(
         return http_util.respondError(request, .unauthorized, "authentication required");
     }
 
+    // Milestone-20 ruling 7, and it runs *after* the auth check on purpose:
+    // rejecting before authenticating would tell an anonymous caller which
+    // routes exist. An unauthenticated request to a protected route answers
+    // 401 in both authority modes.
+    if (found.route.policy == .config_write) {
+        switch (state.authority) {
+            .database => {},
+            .managed_file => |path| return http_util.respondManagedByFile(request, path),
+        }
+    }
+
     return found.route.handler(state, io, request);
 }
 
@@ -196,13 +215,14 @@ fn noopHandler(
 }
 
 const test_table = [_]RouteInfo{
-    .{ .method = .GET, .pattern = "/api/health", .auth = .open, .handler = noopHandler, .rate_limit = .exempt },
-    .{ .method = .GET, .pattern = "/api/groups", .auth = .session, .handler = noopHandler },
-    .{ .method = .POST, .pattern = "/api/groups", .auth = .session, .handler = noopHandler },
-    .{ .method = .GET, .pattern = "/api/groups/{id}", .auth = .session, .handler = noopHandler },
-    .{ .method = .PUT, .pattern = "/api/groups/{id}", .auth = .session, .handler = noopHandler },
-    .{ .method = .DELETE, .pattern = "/api/groups/{id}", .auth = .session, .handler = noopHandler },
-    .{ .method = .PUT, .pattern = "/api/groups/{id}/sources", .auth = .session, .handler = noopHandler },
+    .{ .method = .GET, .pattern = "/api/health", .auth = .open, .policy = .read, .handler = noopHandler, .rate_limit = .exempt },
+    .{ .method = .GET, .pattern = "/api/groups", .auth = .session, .policy = .read, .handler = noopHandler },
+    .{ .method = .POST, .pattern = "/api/groups", .auth = .session, .policy = .config_write, .handler = noopHandler },
+    .{ .method = .GET, .pattern = "/api/groups/{id}", .auth = .session, .policy = .read, .handler = noopHandler },
+    .{ .method = .PUT, .pattern = "/api/groups/{id}", .auth = .session, .policy = .config_write, .handler = noopHandler },
+    .{ .method = .DELETE, .pattern = "/api/groups/{id}", .auth = .session, .policy = .config_write, .handler = noopHandler },
+    .{ .method = .PUT, .pattern = "/api/groups/{id}/sources", .auth = .session, .policy = .config_write, .handler = noopHandler },
+    .{ .method = .POST, .pattern = "/api/pause", .auth = .session, .policy = .runtime_action, .handler = noopHandler },
 };
 
 fn matchPath(method: http.Method, path: []const u8) Match {
@@ -263,6 +283,34 @@ test "the allow header lists every method the path accepts" {
     try testing.expectEqualStrings("GET, PUT, DELETE", formatAllow(&test_table, item.segments(), &buf));
 }
 
+test "matching carries the class the table declares, per route and not per prefix" {
+    const cases = [_]struct { method: http.Method, path: []const u8, policy: Policy }{
+        .{ .method = .GET, .path = "/api/groups", .policy = .read },
+        .{ .method = .GET, .path = "/api/groups/7", .policy = .read },
+        .{ .method = .POST, .path = "/api/groups", .policy = .config_write },
+        .{ .method = .PUT, .path = "/api/groups/7", .policy = .config_write },
+        .{ .method = .DELETE, .path = "/api/groups/7", .policy = .config_write },
+        .{ .method = .PUT, .path = "/api/groups/7/sources", .policy = .config_write },
+        // Same prefix, different class: the column is per route.
+        .{ .method = .POST, .path = "/api/pause", .policy = .runtime_action },
+    };
+    for (cases) |case| {
+        try testing.expectEqual(case.policy, matchPath(case.method, case.path).found.route.policy);
+    }
+}
+
+test "the shipped route table classifies /api/blocklists by route, not by prefix" {
+    var refresh: ?Policy = null;
+    var create: ?Policy = null;
+    for (routes) |route| {
+        if (route.method != .POST) continue;
+        if (std.mem.eql(u8, route.pattern, "/api/blocklists/update")) refresh = route.policy;
+        if (std.mem.eql(u8, route.pattern, "/api/blocklists")) create = route.policy;
+    }
+    try testing.expectEqual(Policy.runtime_action, refresh.?);
+    try testing.expectEqual(Policy.config_write, create.?);
+}
+
 test "the shipped route table is the one the router matches against" {
     try testing.expectEqual(routes_table.table.ptr, routes.ptr);
     try testing.expectEqual(routes_table.table.len, routes.len);