perf

Overview ¶

Load test: throughput and tail latency for one gateway instance under a concurrency sweep. Where bench/latency_test.go answers "how much latency does fold add?" (sequential, budget-enforced, CI-gated), this answers "how many requests per second does one instance sustain, and at what p99?" — the numbers an enterprise buyer asks for.

Topology: three processes, so the load generator, the gateway, and the upstream never share a scheduler. The gateway is the REAL production entry — the built ./cmd/fold binary with a config file — not a test-harness assembly.

driver (this process) ──▶ fold binary ──▶ fixture upstream (child)

Each stage runs both DIRECT (driver → upstream) and FOLD (driver → gateway → upstream) so the upstream's own ceiling is visible: fold's RPS can never exceed direct's, and the gap between them is the honest cost.

The driver models real MCP clients: each "connection" is an official-SDK client session (initialize once, then sequential calls), because fold's client side is session-keyed — there is no stateless one-shot POST to hammer, and a load test should measure what a real client experiences.

Knobs (environment):

FOLD_LOAD_MODE         "namespaced" (body parse + name rewrite — the
                       multi-upstream enterprise path, default) or
                       "passthrough" (single-upstream path)
FOLD_LOAD_CONNECTIONS  comma-separated sweep (default "8,64,256")
FOLD_LOAD_DURATION     seconds per measured stage (default 10)
FOLD_LOAD_WARMUP       seconds of unmeasured warmup per stage (default 3)
FOLD_LOAD_SCENARIOS    comma-separated: tools/call,tools/list (default both;
                       note tools/list through fold rides the list cache)
FOLD_LOAD_UPSTREAMS    fixture upstreams to federate (default 1). The
                       tools/list path fans out to every one of them,
                       merges, filters, namespaces, and paginates, so its
                       cost scales with this and with FOLD_LOAD_TOOLS —
                       a size-1 federation does not exercise any of it.
FOLD_LOAD_TOOLS        tools each fixture upstream exposes (default 1)
FOLD_LOAD_JSON         path to write full results as JSON
FOLD_LOAD_FOLD_URL     bench an already-running gateway at this /mcp URL
                       instead of spawning the topology (pair with
                       FOLD_LOAD_DIRECT_URL to keep the direct baseline;
                       omit it to run the fold stages alone)
FOLD_LOAD_DIRECT_URL   /mcp URL for the direct baseline when
                       FOLD_LOAD_FOLD_URL is set

Run from the repo root: `make loadtest` or `go run ./tools/perf`.