Swoop

Swoop 是面向 Zig 服务的单机压测框架。使用 Zig 定义 HTTP/1.1、WebSocket 和自定义 TCP 协议场景，生成原生可执行文件；不依赖脚本运行时。

它适合需要高性能、可复现且可审计的协议和业务压测：场景、负载模型、断言和阈值都在同一份 Zig 源码中编译和审查。

能力

• HTTP/1.1 与 HTTPS：连接复用、请求体、响应检查、受限 body/JSON 读取。
• WebSocket：连接、收发、超时与显式重连。
• 自定义 TCP：受计量的 Reader/Writer，可直接配合 Talon framing。
• 负载：闭环虚拟用户（VU）和开环固定到达率，支持阶段、warm-up 与阈值。
• 证据：默认 text 结果便于终端阅读；可选 JSON 包含请求、延迟、错误、负载交付、发生器饱和与阈值结论。

当前范围是单机 HTTP/1.1、WebSocket 与 raw TCP；不提供 HTTP/2、HTTP/3、分布式 agent 或云控制面。

环境

• Zig 0.16.0
• 首次构建需联网获取 talon 和 zio；GitHub 地址、固定提交和校验值见 build.zig.zon。

快速运行

完整的 HTTP、WebSocket 和 TCP 示例客户端位于 bench/，可直接构建并运行：

zig build benchmarks -Doptimize=ReleaseFast

目标程序和客户端参数见 bench/README.md。协议 target 只监听回环地址，客户端可连接调用者指定的主机。

编写场景

场景是一个带 options 和 run 的 Zig 类型。所有需要统计的操作应放入 vu.transaction；函数返回错误即记为失败。

const std = @import("std");
const swoop = @import("swoop");

const Scenario = struct {
    pub const options: swoop.Options = .{
        .plan = .{ .stages = &.{.{ .closed_vus = .{
            .name = "steady",
            .vus = 32,
            .duration = .fromSeconds(30),
        } }} },
        .thresholds = &.{
            .{ .latency_p99_us = .{ .less_than = 200_000 } },
            .{ .error_rate = .{ .less_than = 0.01 } },
        },
    };

    pub fn run(vu: *swoop.Vu) !void {
        try vu.transaction("health", struct {
            fn call(v: *swoop.Vu) !void {
                var response = try v.http.getUrl("http://127.0.0.1:8080/health");
                defer response.deinit();
                try v.check.status(&response, 200);
                _ = try response.finish();
            }
        }.call, .{});
    }
};

pub fn main(init: std.process.Init) !u8 {
    return swoop.runScenarioMain(Scenario, init);
}

WebSocket 使用 swoop.ws.connect、sendText、receive；自定义 TCP 使用 swoop.tcp.connect 返回的受计量 stream。两者同样由 vu.transaction 包裹。

场景默认输出参考 wrk 的 text 摘要，包括请求总数、延迟分布、RPS、吞吐、逐阶段负载模型与配置、负载交付、阈值和最终结论。需要机器读取的固定 schema 时指定 JSON：

zig build run-checkout -- --format json

也可在场景的 swoop.Options 中设置 .output_format = .json；命令行 --format 会覆盖该默认值。

刚接触压测或需要理解实现时，请从概念学习路径开始；其中区分了压测通用术语、当前已实现的 swoop 约定和未来规划。

下游项目可通过 addScenario 建立场景可执行文件：

const swoop_build = @import("swoop");

_ = swoop_build.addScenario(b, .{
    .swoop_module = swoop_dep.module("swoop"),
    .name = "checkout",
    .root_source_file = b.path("scenarios/checkout.zig"),
    .target = target,
    .optimize = optimize,
});

可审计性

• HTTP 不跟随重定向，也不进行透明重试，避免将负载转移到未批准的目标或掩盖请求尝试。
• 开环报告区分计划、实际、迟到和丢弃的启动；发生器饱和不会被当作成功交付。
• 延迟、错误样本、响应体、消息和指标标签都有固定上限；阈值失败在完整报告写出后以状态码 2 退出。

验证

zig build test
zig build

可直接运行的 Zig benchmark workload 见 bench/README.md。