@@ -3,7 +3,7 @@ SPDX-License-Identifier: Apache-2.0
33SPDX-FileCopyrightText: Copyright the Vortex contributors
44-->
55
6- # AGENTS.md — ` benchmarks-website/ `
6+ # AGENTS.md - ` benchmarks-website/ `
77
88Read [ ` README.md ` ] ( README.md ) first for the architecture and the v2/v3
99side-by-side situation. Then this file. The root [ ` CLAUDE.md ` ] ( ../CLAUDE.md )
@@ -14,17 +14,34 @@ covers Rust style, test layout, commit conventions.
1414Until the cutover PR lands, the top-level v2 files
1515(` server.js ` , ` src/ ` , ` index.html ` , ` vite.config.js ` , ` package.json ` ,
1616` package-lock.json ` , ` public/ ` , the top-level ` Dockerfile ` ,
17- ` docker-compose.yml ` , ` ec2-init.txt ` ) and the ` benchmarks-website ` service
18- in ` docker-compose.yml ` and the ` publish-benchmarks-website.yml ` workflow
17+ ` docker-compose.yml ` ) and the ` publish-benchmarks-website.yml ` workflow
1918are production. Don't edit them as part of unrelated work.
2019
20+ The v3 deploy lives entirely under ` server/ ` , ` migrate/ ` , and ` ops/ ` .
21+ The operator runbook is [ ` ops/README.md ` ] ( ops/README.md ) .
22+
2123## v3 specifics
2224
2325- ** Wire shapes are a coordinated change.** [ ` server/src/records.rs ` ] ( server/src/records.rs ) ,
2426 [ ` vortex-bench/src/v3.rs ` ] ( ../vortex-bench/src/v3.rs ) , and (until cutover)
2527 [ ` migrate/src/classifier.rs ` ] ( migrate/src/classifier.rs ) must agree.
2628 Bumping a shape means changing all three plus the snapshot fixtures in
27- one commit.
29+ one commit. ` SCHEMA_VERSION ` is the version literal coupled across two
30+ named sites: [ ` server/src/schema.rs ` ] ( server/src/schema.rs ) (source of
31+ truth) and [ ` scripts/post-ingest.py ` ] ( ../scripts/post-ingest.py ) (the
32+ CI ingest wrapper, which hardcodes it as a Python literal). Bump in
33+ lockstep or every CI ingest run 400s. The server-side validation in
34+ ` records.rs ` + ` ingest.rs ` and the echo in ` /health ` all consume the
35+ constant through ` crate::schema ` .
36+ - ** Numeric ` ?n= ` is clamped to 1000; ` ?n=all ` is the uncapped escape
37+ hatch.** HTML routes hydrate from the materialized latest-100 shard
38+ artifact by default; ` ?n=all ` is an explicit opt-in
39+ (chart-init.js's full-history zoom-out hop uses it once, and curl
40+ power users can request it). The numeric ` ?n= ` path is bounded by
41+ ` MAX_NUMERIC_COMMIT_WINDOW ` in [ ` server/src/api/window.rs ` ] ( server/src/api/window.rs )
42+ as a DoS-protection floor against ` curl ...?n=99999999 ` . If you need
43+ full history, use ` ?n=all ` . Do NOT raise the numeric cap or remove it
44+ without thinking about the DoS surface.
2845- ** ` measurement_id ` is server-internal.** Never put it on the wire. It is
2946 a deterministic hash over ` commit_sha ` plus the dim tuple, computed in
3047 [ ` server/src/db.rs ` ] ( server/src/db.rs ) and reused by the migrator via
@@ -35,20 +52,33 @@ are production. Don't edit them as part of unrelated work.
3552- ** Don't reach for WASM.** SSR + a thin hydration script in
3653 [ ` server/static/chart-init.js ` ] ( server/static/chart-init.js ) is the
3754 whole client.
38- - ** Don't re-introduce a server-side commit cap.** ` ?n=all ` is the default
39- for HTML routes; visual downsampling happens client-side via LTTB on the
40- visible commit range only.
41- - ** Don't refetch on every scope change.** The chart fetches its full
42- history once. Pan, zoom, slider, and the range strip rebuild in place
43- via the in-memory LTTB pass on the cached payload. The single exception
44- is the inline-payload zoom-out path: when the user zooms past the first
45- group's inlined ` LANDING_INLINE_N ` window for the first time,
46- ` chart-init.js ` lazy-fetches ` ?n=all ` once and replaces the payload.
55+ - ** v3 ingest is no longer best-effort in CI.** The `Ingest results to v3
56+ server` step in [ ` bench.yml`] ( ../.github/workflows/bench.yml ) ,
57+ [ ` sql-benchmarks.yml ` ] ( ../.github/workflows/sql-benchmarks.yml ) , and
58+ [ ` v3-commit-metadata.yml ` ] ( ../.github/workflows/v3-commit-metadata.yml )
59+ no longer carries ` continue-on-error: true ` . A v3-server outage on a
60+ develop push now fails the bench workflow and triggers the existing
61+ ` incident.io ` alert. The gate is ` vars.V3_INGEST_URL != '' ` so forks
62+ and unconfigured environments are unaffected.
63+ - ** Don't re-introduce a server-side commit cap on ` ?n=all ` .** ` ?n=all `
64+ is the uncapped escape hatch (chart-init.js fetches it once for the
65+ zoom-out path); visual downsampling happens client-side via LTTB on
66+ the visible commit range only. Numeric ` ?n= ` is clamped per the bullet
67+ above. Default fetches from chart-init.js use the materialized
68+ latest-100 shard artifact, not ` ?n=all ` .
69+ - ** Don't refetch on every scope change.** Once a chart's payload is in
70+ memory, pan/zoom/slider/range-strip all rebuild in place via the
71+ in-memory LTTB pass on the cached payload. The single exception is the
72+ latest-100 to full-history zoom-out path: charts initially hydrate from
73+ the materialized latest-100 group shard artifact (served from
74+ ` /api/artifacts/{generation}/groups/{slug}/shards/{i} ` ); when the user
75+ zooms past that window for the first time, ` chart-init.js ` lazy-fetches
76+ ` ?n=all ` once and replaces the latest-100 payload in place.
4777
4878## Footguns we have already hit
4979
5080- ** Reverse predecessor walk in the tooltip.** ` payload.commits[] ` is
51- sorted oldest-first by SQL — ` commits[0] ` is the oldest, ` commits[N-1] `
81+ sorted oldest-first by SQL - ` commits[0] ` is the oldest, ` commits[N-1] `
5282 is the newest. For per-row delta the predecessor of ` commits[idx] ` is
5383 at ` idx - 1 ` . We caught a regression where a "fix" flipped this to
5484 ` idx + 1 ` ; the original walk-backward direction is right.
@@ -62,11 +92,21 @@ are production. Don't edit them as part of unrelated work.
6292## Local dev
6393
6494``` bash
95+ # Public-only run (read API + ingest only, admin routes 404):
6596INGEST_BEARER_TOKEN=dev cargo run -p vortex-bench-server
97+
98+ # With admin endpoints mounted on a separate loopback listener:
99+ INGEST_BEARER_TOKEN=dev ADMIN_BEARER_TOKEN=dev \
100+ cargo run -p vortex-bench-server
101+
66102cargo nextest run -p vortex-bench-server -p vortex-bench-migrate
67103INSTA_UPDATE=auto cargo nextest run -p vortex-bench-server # update snapshots
68104```
69105
106+ For the full env-var contract (admin bind, snapshot dir, extension dir,
107+ logging spec, PaaS ` PORT ` fallback) see [ ` ops/config/vortex-bench.env.example ` ] ( ops/config/vortex-bench.env.example )
108+ and the lib-level ` //! ` doc on [ ` server/src/main.rs ` ] ( server/src/main.rs ) .
109+
70110For the migrator end-to-end against the real S3 dump:
71111
72112``` bash
0 commit comments