feat(body_deps): add static analyser classifying body refs

Configure-time analysis pass that categorises a compiled module by
how it references the request body:

  - no_body_refs:  policy never touches input.body
  - prefix_only:   policy reads specific body sub-paths
  - full_tree:     policy reads input.body whole or iterates over a
                   body-rooted ref (full body must be buffered)

Conservative classifier: when uncertain, returns full_tree.

Tests cover header-only, body-leaf, bare body, body iteration, and
the bare 'body' shorthand (no input prefix). prefix_count returns
the number of distinct body sub-paths so callers can size buffers
accordingly.

Streaming evaluation (per docs/proposals/streaming-evaluation.md)
needs the body-aware callback path landing first. This analyser is
the configure-time piece; it ships independently and the proxy-wasm
shim can call it in a follow-up to skip proxy_on_request_body when
the policy doesn't need the body.

ci.yml gains a test-unit job (parity with feat/string-builtins,
feat/composite-ref-iteration, etc.).

Author: kanywst

src/body_deps.zig

@@ -0,0 +1,184 @@
+//! Static analysis of body dependencies in a compiled policy.
+//!
+//! Walks the AST once, classifying how the policy references the
+//! request body. The proxy-wasm shim uses the result to decide
+//! whether to skip `proxy_on_request_body` entirely (no body refs),
+//! buffer until specific paths resolve (prefix-only), or buffer the
+//! whole body up to `max_body_bytes` (full-tree).
+//!
+//! Streaming evaluation itself (per `docs/proposals/streaming-evaluation.md`)
+//! depends on the body-aware callback path landing first; this
+//! analyser is the configure-time piece that ships independently.
+
+const std = @import("std");
+const ast = @import("ast.zig");
+
+pub const Class = enum {
+    /// Policy does not reference `input.body` anywhere.
+    no_body_refs,
+    /// Policy references body sub-paths (e.g. `input.body.amount`).
+    /// A streaming evaluator can decide as soon as those resolve.
+    prefix_only,
+    /// Policy references `input.body` as a whole or iterates over
+    /// the body's contents. The full body must be buffered.
+    full_tree,
+};
+
+pub const BodyDeps = struct {
+    class: Class,
+    /// Number of distinct body sub-paths referenced when
+    /// `class == .prefix_only`. Always 0 for the other classes.
+    prefix_count: usize,
+};
+
+/// Classify body usage of every rule reachable in `module`.
+/// Conservative: when in doubt, returns `.full_tree`.
+pub fn analyze(module: ast.Module) BodyDeps {
+    var st = State{};
+    for (module.rules) |rule| {
+        for (rule.body) |expr| visit(&st, expr);
+        if (rule.value) |v| visit(&st, v);
+    }
+    return st.finalize();
+}
+
+const State = struct {
+    refs_whole: bool = false,
+    prefix_count: usize = 0,
+
+    fn finalize(self: State) BodyDeps {
+        if (self.refs_whole) return .{ .class = .full_tree, .prefix_count = 0 };
+        if (self.prefix_count == 0) return .{ .class = .no_body_refs, .prefix_count = 0 };
+        return .{ .class = .prefix_only, .prefix_count = self.prefix_count };
+    }
+};
+
+fn visit(st: *State, expr: *const ast.Expr) void {
+    switch (expr.*) {
+        .value => {},
+        .ref => |path| visitRef(st, path),
+        .compare => |c| {
+            visit(st, c.left);
+            visit(st, c.right);
+        },
+        .not => |inner| visit(st, inner),
+        .some, .every => |it| {
+            visit(st, it.source);
+            visit(st, it.body);
+            // Iterating over a ref into the body is full-tree:
+            // the iterator needs the entire collection. The source
+            // visit above marks the path; we promote to whole if
+            // the source is itself an `input.body...` ref.
+            if (it.source.* == .ref) {
+                if (refTouchesBody(it.source.ref)) st.refs_whole = true;
+            }
+        },
+        .call => |c| for (c.args) |arg| visit(st, arg),
+    }
+}
+
+fn visitRef(st: *State, path: []const []const u8) void {
+    if (!refTouchesBody(path)) return;
+
+    // `input.body` (or just `body`) by itself = whole-tree dependency.
+    // Body sub-paths (input.body.amount, body.user) = prefix-only.
+    const body_index = bodySegmentIndex(path) orelse return;
+    if (body_index + 1 >= path.len) {
+        st.refs_whole = true;
+    } else {
+        st.prefix_count += 1;
+    }
+}
+
+fn refTouchesBody(path: []const []const u8) bool {
+    return bodySegmentIndex(path) != null;
+}
+
+/// Locate the `body` segment inside an input ref. Accepts both
+/// `["input", "body", ...]` and the shorthand `["body", ...]`.
+fn bodySegmentIndex(path: []const []const u8) ?usize {
+    if (path.len == 0) return null;
+    if (std.mem.eql(u8, path[0], "body")) return 0;
+    if (path.len >= 2 and std.mem.eql(u8, path[0], "input") and std.mem.eql(u8, path[1], "body")) {
+        return 1;
+    }
+    return null;
+}
+
+const testing = std.testing;
+const json = @import("json.zig");
+
+fn classify(src: []const u8) !Class {
+    var arena = std.heap.ArenaAllocator.init(testing.allocator);
+    defer arena.deinit();
+    const node = try json.parse(arena.allocator(), src);
+    const module = try ast.buildModule(arena.allocator(), node);
+    return analyze(module).class;
+}
+
+test "analyze: no body refs -> no_body_refs" {
+    const policy =
+        "{\"type\":\"eq\"," ++
+        "\"left\":{\"type\":\"ref\",\"path\":[\"input\",\"method\"]}," ++
+        "\"right\":{\"type\":\"value\",\"value\":\"GET\"}}";
+    try testing.expectEqual(Class.no_body_refs, try classify(policy));
+}
+
+test "analyze: input.body.amount -> prefix_only" {
+    const policy =
+        "{\"type\":\"gt\"," ++
+        "\"left\":{\"type\":\"ref\",\"path\":[\"input\",\"body\",\"amount\"]}," ++
+        "\"right\":{\"type\":\"value\",\"value\":100}}";
+    try testing.expectEqual(Class.prefix_only, try classify(policy));
+}
+
+test "analyze: bare input.body -> full_tree" {
+    const policy =
+        "{\"type\":\"neq\"," ++
+        "\"left\":{\"type\":\"ref\",\"path\":[\"input\",\"body\"]}," ++
+        "\"right\":{\"type\":\"value\",\"value\":null}}";
+    try testing.expectEqual(Class.full_tree, try classify(policy));
+}
+
+test "analyze: iterate input.body.items -> full_tree" {
+    const policy =
+        "{\"type\":\"every\",\"var\":\"item\"," ++
+        "\"source\":{\"type\":\"ref\",\"path\":[\"input\",\"body\",\"items\"]}," ++
+        "\"body\":{\"type\":\"value\",\"value\":true}}";
+    try testing.expectEqual(Class.full_tree, try classify(policy));
+}
+
+test "analyze: prefix_count counts distinct body refs" {
+    const policy =
+        "{\"type\":\"module\",\"rules\":[" ++
+        "{\"type\":\"rule\",\"name\":\"allow\",\"body\":[" ++
+        "{\"type\":\"eq\"," ++
+        "\"left\":{\"type\":\"ref\",\"path\":[\"input\",\"body\",\"action\"]}," ++
+        "\"right\":{\"type\":\"value\",\"value\":\"submit\"}}," ++
+        "{\"type\":\"gt\"," ++
+        "\"left\":{\"type\":\"ref\",\"path\":[\"input\",\"body\",\"amount\"]}," ++
+        "\"right\":{\"type\":\"value\",\"value\":0}}]}]}";
+    var arena = std.heap.ArenaAllocator.init(testing.allocator);
+    defer arena.deinit();
+    const node = try json.parse(arena.allocator(), policy);
+    const module = try ast.buildModule(arena.allocator(), node);
+    const deps = analyze(module);
+    try testing.expectEqual(Class.prefix_only, deps.class);
+    try testing.expectEqual(@as(usize, 2), deps.prefix_count);
+}
+
+test "analyze: body shorthand path (no input prefix) detected" {
+    const policy =
+        "{\"type\":\"eq\"," ++
+        "\"left\":{\"type\":\"ref\",\"path\":[\"body\",\"x\"]}," ++
+        "\"right\":{\"type\":\"value\",\"value\":1}}";
+    try testing.expectEqual(Class.prefix_only, try classify(policy));
+}
+
+test "analyze: call with body arg -> prefix_only" {
+    const policy =
+        "{\"type\":\"call\",\"name\":\"startswith\",\"args\":[" ++
+        "{\"type\":\"ref\",\"path\":[\"input\",\"body\",\"action\"]}," ++
+        "{\"type\":\"value\",\"value\":\"approve_\"}]}";
+    try testing.expectEqual(Class.prefix_only, try classify(policy));
+}

src/root.zig

@@ -7,6 +7,7 @@
 //! `main.zig`.
 
 pub const ast = @import("ast.zig");
+pub const body_deps = @import("body_deps.zig");
 pub const builtins = @import("builtins.zig");
 pub const eval = @import("eval.zig");
 pub const json = @import("json.zig");
@@ -24,6 +25,7 @@ test {
     const testing = @import("std").testing;
     testing.refAllDecls(@This());
     _ = ast;
+    _ = body_deps;
     _ = builtins;
     _ = eval;
     _ = json;