Benchmarks

The monorepo ships an HTTP load-testing harness at benchmarks/http/ that exercises a deployed (or local) ZBSearch Edge Worker end to end: generate a corpus, ingest it, then drive k6 scenarios against the REST API.

Prerequisites

• k6 - on macOS: brew install k6
• A target Worker: either wrangler dev locally or a deployed Worker URL
• For offline ingest (default): the builder CLI built (pnpm --filter @zbsearch/edge-index-builder build) and R2 credentials in deploy/cloudflare/.env

The harness

All k6 scenarios read BASE_URL (required), API_KEY, and INDEX_ID (default loadtest) from the environment.

Quick run against wrangler dev

Start the local Worker in one terminal:

wrangler dev --config deploy/cloudflare/wrangler.toml

Then run the full flow with a 10k-document corpus, ingesting through the API (local Wrangler emulates R2, so the offline builder import does not apply):

cd benchmarks/http
./run.sh 10000 --local --via-api

--local defaults BASE_URL to http://127.0.0.1:8787 and API_KEY to dev-key.

Run against a deployed Worker

Set credentials and let run.sh use the offline builder import (fastest for large corpora):

export BASE_URL=https://your-worker.workers.dev
export API_KEY=your_api_key
source deploy/cloudflare/.env   # R2 credentials for the builder CLI

cd benchmarks/http
./run.sh 100000

Or ingest through the API instead:

./run.sh 100000 --via-api

Step by step (without run.sh)

cd benchmarks/http

# 1. Generate the corpus (seeded; safe to re-run)
node generate-corpus.mjs --docs 100000 --out data/corpus-100k.jsonl

# 2a. Ingest offline via the builder CLI (builds snapshot, uploads to R2)
node ingest.mjs --corpus data/corpus-100k.jsonl --index loadtest

# 2b. ...or via the API
node ingest.mjs --via-api --corpus data/corpus-100k.jsonl \
  --base-url "$BASE_URL" --api-key "$API_KEY" --batch-size 100 --concurrency 4

# 3. Run any scenario directly
k6 run --summary-export results/search-$(date +%Y%m%dT%H%M%SZ).json k6/search.js

Useful scenario env vars: WARMUP=true (short 30s search run), ABORT_ON_THRESHOLD=true, WRITE_RATE / WRITE_DURATION / BATCH_SIZE (write), COLD_DURATION (coldstart).

Results

run.sh and the examples above write timestamped k6 JSON summaries to benchmarks/http/results/.

Baseline results (local, July 2026)

Measured with wrangler dev on an Apple Silicon laptop against the generated corpus (~1.3 KB/doc snapshots, text-heavy documents). Read these as relative, not absolute: local runs are a single process (no isolate fan-out), wrangler dev does not enforce the 128 MB isolate memory limit, and local R2/Cache behavior differs from production. Re-run against a deployed Worker for authoritative numbers.

Key takeaways:

• A warm isolate cache serves searches in single-digit to tens of ms; the versioned snapshot key means rebuilds invalidate it automatically.
• The snapshot must fit the isolate cache budget. A snapshot larger than SNAPSHOT_CACHE_MAX_BYTES is not degraded - it is an outage. Size the budget so your largest index fits with headroom, and remember production isolates are capped at 128 MB total.
• Past that ceiling, shard. Sharded indexes split a logical index across physical shards whose snapshots each fit the cache budget - this is the supported way to scale beyond a monolithic snapshot, rather than raising SNAPSHOT_CACHE_MAX_BYTES toward the isolate limit.
• Dirty searches re-index the whole index per request. Keep pendingOps near zero on large indexes: lower REBUILD_THRESHOLD_OPS, run the external builder frequently, and prefer bulk import over API writes.
• Snapshot size is corpus-dependent; measure your own with GET /v1/indexes/:id/status (indexSizeBytes) before choosing tiers.

Baseline results (deployed, July 2026)

Measured against a production Worker on the Workers Paid plan (k6 over a residential connection - latencies include internet RTT):

Warm single-request latency is ~180-450 ms end to end depending on shard count; engine time is tens of ms - the rest is network RTT and per-shard meta.json reads from R2 (see the cost calculator for what those reads cost at scale).

Why 100k docs needs the ShardSearch Durable Object: a group search that fans out in-process must hold every shard snapshot in one isolate - 8× 16.5 MB = 132 MB > the 128 MB limit, which produced 15-22 s latencies and OOM 503s. Routing each shard search to its own DO gives every shard a private isolate whose snapshot cache stays warm across requests. Two loopback alternatives do not work: fetching your own workers.dev hostname is rejected at the edge, and a same-worker service binding runs in the same isolate, sharing the memory limit.

CI workflow

A manual-dispatch workflow at deploy/github-actions/zbsearch-loadtest.yml runs any single scenario from GitHub Actions. Copy it to .github/workflows/ in your deployment repo, then add repository secrets:

Dispatch it from Actions -> Loadtest -> Run workflow, picking the scenario (search, write, mixed, or coldstart) and the target index_id (must already exist and be ingested). The k6 JSON summary is uploaded as a build artifact (30-day retention).