|
| 1 | +<!-- |
| 2 | +SPDX-License-Identifier: Apache-2.0 |
| 3 | +SPDX-FileCopyrightText: Copyright the Vortex contributors |
| 4 | +--> |
| 5 | + |
| 6 | +# Benchmark Server Architecture |
| 7 | + |
| 8 | +The benchmark website is optimized around a materialized latest-100 read path. |
| 9 | +DuckDB is the source of truth, but normal landing-page and group-open |
| 10 | +hydration does not run SQL, serialize JSON, or compress responses per request. |
| 11 | + |
| 12 | +## Hot Read Path |
| 13 | + |
| 14 | +On startup the server builds a `ReadGeneration` from one DuckDB snapshot. That |
| 15 | +generation contains precomputed JSON artifacts for: |
| 16 | + |
| 17 | +- `/api/groups` |
| 18 | +- default `/api/chart/{slug}` latest-100 payloads |
| 19 | +- default `/api/group/{slug}` latest-100 compatibility payloads |
| 20 | +- versioned group shard payloads under |
| 21 | + `/api/artifacts/{generation}/groups/{group_slug}/shards/{index}` |
| 22 | + |
| 23 | +Each artifact is stored in memory as identity, gzip, and brotli bytes. Request |
| 24 | +handlers negotiate `Accept-Encoding` and serve those bytes directly with |
| 25 | +`ETag`, `Vary: Accept-Encoding`, `Content-Length`, and cache headers. |
| 26 | + |
| 27 | +## Page Hydration |
| 28 | + |
| 29 | +The landing page and `/group/{slug}` render group metadata plus chart shells, |
| 30 | +not inline chart payloads. Each group carries the active read generation, shard |
| 31 | +count, and shard URL prefix. `chart-init.js` fetches shard 0 on intent or group |
| 32 | +open so charts paint quickly, then queues the remaining latest-100 shards with |
| 33 | +bounded per-tab concurrency. |
| 34 | + |
| 35 | +Latest-100 chart payloads include additive `history` metadata: |
| 36 | + |
| 37 | +- `total_commits`: full x-axis length for the chart |
| 38 | +- `start_index`: where this payload starts in the full x-axis |
| 39 | +- `loaded_commits`: number of loaded commits |
| 40 | +- `complete`: whether the payload covers the full x-axis |
| 41 | + |
| 42 | +The client normalizes incomplete latest-100 payloads onto the full virtual |
| 43 | +x-axis. Older unloaded commits are represented by blank labels and null series |
| 44 | +values, so the range strip, zoom limits, and slider bounds behave as if the |
| 45 | +whole history is present without fabricating data. |
| 46 | + |
| 47 | +## Full-History Warmup |
| 48 | + |
| 49 | +Opening a group queues `/api/chart/{slug}?n=all` for that group's charts in a |
| 50 | +separate low-concurrency priority queue. A later-opened group gets higher |
| 51 | +priority than queued work for older groups. If the user pans or zooms into an |
| 52 | +unloaded virtual range before warmup finishes, that chart's queued full-history |
| 53 | +request is promoted. In-flight requests are not cancelled. |
| 54 | + |
| 55 | +When the full payload arrives, the client replaces the virtual latest-100 |
| 56 | +payload in place and preserves the current x-range when possible. |
| 57 | + |
| 58 | +## Fallback Paths |
| 59 | + |
| 60 | +`?n=all` and non-default `?n=` windows still use the DB-backed fallback path. |
| 61 | +Those reads go through `QueryCache` single-flight entries and the DB read |
| 62 | +semaphore so cold or unusual requests do not stampede DuckDB. Ingest writes do |
| 63 | +not consume read permits. |
| 64 | + |
| 65 | +## Ingest And Rebuild |
| 66 | + |
| 67 | +Successful ingest invalidates `QueryCache` and schedules a read-model rebuild. |
| 68 | +The active generation remains live while rebuilding. Repeated rebuild requests |
| 69 | +coalesce, and a failed rebuild keeps serving the old generation. The server |
| 70 | +keeps the active generation plus the most recent previous generation so already |
| 71 | +loaded pages can continue resolving immutable shard URLs across a swap. |
| 72 | + |
| 73 | +## Main Files |
| 74 | + |
| 75 | +- `src/read_model.rs`: materialized generation and encoded artifact serving |
| 76 | +- `src/api/mod.rs`: API routing between materialized artifacts and fallbacks |
| 77 | +- `src/api/charts.rs`: chart DTO construction and `history` metadata |
| 78 | +- `src/html/mod.rs`, `src/html/landing.rs`: shell/shard HTML rendering |
| 79 | +- `static/chart-init.js`: virtual-axis normalization, shard hydration, and |
| 80 | + full-history priority warmup |
| 81 | +- `src/query_cache.rs`: single-flight fallback cache |
| 82 | +- `src/db.rs`: DuckDB connection cloning and read backpressure |
0 commit comments