Telemetry server: the hub's votes (POST /hub/vote, GET /hub/votes)

A thumbs-up on a roadmap item at playhorizon.dev/hub: one per browser (a random
id the page keeps), taken back with "up": false, counts cached a minute. Item ids
are checked for shape and capped at 1000 distinct items. Rate limits key their
buckets by a keyed hash of the address (key drawn at start, in memory); no address
is stored. CORS preflight for the website's JSON posts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Ludovic Marie
2026-10-25 15:54:39 +01:00
parent f94b05032b
commit 5d40d6a33e
5 changed files with 388 additions and 6 deletions
+6 -1
View File
@@ -1,6 +1,6 @@
# horizon-telemetry-server
This server receives what players choose to send (performance summaries, crash and bug reports, benchmark uploads: [docs/telemetry.md](../../docs/telemetry.md)) and stores it in one SQLite file. It serves anonymous totals to the website. It also keeps the live player count from the games' anonymous "I'm playing" pings, in memory only. It is one small Rust process, about 7 MB of memory when idle.
This server receives what players choose to send (performance summaries, crash and bug reports, benchmark uploads: [docs/telemetry.md](../../docs/telemetry.md)) and stores it in one SQLite file. It serves anonymous totals to the website. It also keeps the live player count from the games' anonymous "I'm playing" pings, in memory only, and the 👍 players give roadmap items on the hub (playhorizon.dev/hub). It is one small Rust process, about 7 MB of memory when idle.
cargo run --release # in this folder: its own workspace, like the launcher's
PORT=8080 HORIZON_TELEMETRY_DB=/data/telemetry.sqlite3 horizon-telemetry-server
@@ -17,6 +17,8 @@ It runs at **https://telemetry.playhorizon.dev** (`DEFAULT_ENDPOINT` in `crates/
| `GET /v1/benchmarks/summary` | Players' benchmark uploads grouped by GPU, CPU, render distance and game, for the website's Benchmarks page (below). Cached 10 minutes, same `Access-Control-Allow-Origin`. |
| `POST /v1/live` | A game's "I'm playing" ping (JSON, at most 512 bytes). Returns 204. Returns 400 for a bad ping, 413 for one too large, 429 over the address's limit, 503 when it holds `LIVE_MAX_SESSIONS` already. |
| `GET /v1/live` | How many play now, rounded: `playing`, `lan`, `versions`, `platforms`. Made again at most every 15 seconds, with the same `Access-Control-Allow-Origin`. |
| `POST /hub/vote` | `{"item": "<roadmap id>", "voter": "<the browser's random id>", "up": true}`: a 👍 on a roadmap item, one per voter; `"up": false` takes it back. Returns `{"item", "votes"}`. 400 for a bad id, 429 over the address's limit. `OPTIONS` answers the website's preflight. |
| `GET /hub/votes` | `{"votes": {"<item>": n}}`. Made again at most every minute. |
| `GET /healthz` | `ok` |
The totals are grouped per version, OS, GPU vendor and render distance. Each group has its sessions, install-days, hours played, the 14 frame-time buckets summed, and the mean p50 and p99 frame times. Groups with fewer than 5 install-days are left out. The totals also list crash counts per version. Benchmark uploads are published only through the summary below, never one by one.
@@ -56,6 +58,8 @@ The live count is a table in memory: a session ID, when it last pinged, its vers
The day stored is the day the server received an item. The sender's IP address is never written down. The per-address rate limit keeps addresses in memory for an hour at most.
A hub vote is stored as an item ID and the browser's random ID. The hub's rate limits key their buckets by a hash of the address with a key drawn at each start, in memory.
Raw rows are deleted after `HORIZON_TELEMETRY_RETENTION_DAYS` (180). The daily totals stay; they hold no install ID.
## Settings
@@ -73,6 +77,7 @@ All are environment variables:
- `HORIZON_TELEMETRY_LIVE_PER_HOUR` per address, pings and reads (600, bursts of 60: ten players behind one address)
- `HORIZON_TELEMETRY_LIVE_WINDOW_SECONDS` (120)
- `HORIZON_TELEMETRY_LIVE_MAX_SESSIONS` (200 000)
- `HORIZON_TELEMETRY_HUB_PER_HOUR` votes and vote reads per address (120, bursts of 12)
## Hosting
+239
View File
@@ -0,0 +1,239 @@
//! The hub's votes: a 👍 on a roadmap item at playhorizon.dev/hub. roadmap/README.md documents them for Kira and the website.
//!
//! - `POST /hub/vote`: a 👍 on a roadmap item, one per browser (`voter`, a random id the page makes and
//! keeps); `"up": false` takes it back. Answers the item's count.
//! - `GET /hub/votes`: every item's count, cached a minute.
//!
//! Stored: an item id and the browser's random id per vote. Never an IP address: the rate limits key their
//! buckets by a hash of it with a key drawn at start, in memory.
use std::collections::HashMap;
use std::hash::BuildHasher;
use std::sync::Arc;
use std::time::{Duration, Instant};
use axum::extract::{Request, State};
use axum::http::{HeaderValue, StatusCode, header};
use axum::response::Response;
use rusqlite::params;
use serde_json::{Map, Value, json};
use crate::store::Store;
use crate::{App, json_response, peer, take};
pub const SCHEMA: &str = "
CREATE TABLE IF NOT EXISTS hub_votes (item TEXT NOT NULL, voter TEXT NOT NULL, PRIMARY KEY (item, voter)) WITHOUT ROWID;
";
/// Items with votes, at most: a vote for a new id past this is refused (ids are only checked for shape).
const MAX_ITEMS: i64 = 1000;
/// The largest body accepted: a report's fields at their limits, as JSON, fit.
const MAX_BODY: usize = 24 * 1024;
const VOTES_FOR: Duration = Duration::from_secs(60);
/// The hub's buckets: keyed by a keyed hash of the address, never the address itself.
pub type HashedBuckets = HashMap<u64, (f64, Instant)>;
/// A roadmap item id's shape: lowercase words joined by dashes (tools/roadmap.py), at most 48 characters.
pub fn item_id(id: &str) -> bool {
(1..=48).contains(&id.len())
&& !id.starts_with('-')
&& !id.ends_with('-')
&& !id.contains("--")
&& id
.bytes()
.all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'-')
}
/// A voter id's shape: what `crypto.randomUUID()` and similar make.
fn voter_id(id: &str) -> bool {
(16..=64).contains(&id.len())
&& id
.bytes()
.all(|b| b.is_ascii_alphanumeric() || b == b'-' || b == b'_')
}
impl Store {
/// Adds or takes back a vote; the item's count after it. None when the item would be one too many.
pub fn vote(&mut self, item: &str, voter: &str, up: bool) -> rusqlite::Result<Option<i64>> {
let tx = self.db.transaction()?;
if up {
let known = tx
.prepare("SELECT 1 FROM hub_votes WHERE item = ?1 LIMIT 1")?
.exists([item])?;
let items: i64 =
tx.query_row("SELECT count(DISTINCT item) FROM hub_votes", [], |r| {
r.get(0)
})?;
if !known && items >= MAX_ITEMS {
return Ok(None);
}
tx.execute(
"INSERT OR IGNORE INTO hub_votes (item, voter) VALUES (?1, ?2)",
params![item, voter],
)?;
} else {
tx.execute(
"DELETE FROM hub_votes WHERE item = ?1 AND voter = ?2",
params![item, voter],
)?;
}
let count = tx.query_row(
"SELECT count(*) FROM hub_votes WHERE item = ?1",
[item],
|r| r.get(0),
)?;
tx.commit()?;
Ok(Some(count))
}
/// Every item's count.
pub fn votes(&self) -> rusqlite::Result<Map<String, Value>> {
let mut statement = self
.db
.prepare("SELECT item, count(*) FROM hub_votes GROUP BY item ORDER BY item")?;
let rows =
statement.query_map([], |r| Ok((r.get::<_, String>(0)?, r.get::<_, i64>(1)?)))?;
rows.map(|row| row.map(|(item, n)| (item, Value::from(n))))
.collect()
}
}
impl App {
pub(crate) fn hashed(&self, req: &Request) -> u64 {
self.hub_key.hash_one(self.client(req.headers(), peer(req)))
}
/// Takes a token from the address's hub bucket (votes and reads of the counts).
fn allow_hub(&self, req: &Request) -> bool {
take(
&self.hub_buckets,
self.config.hub_per_hour,
self.hashed(req),
)
}
/// The hub's share of `maintain`: idle buckets are forgotten.
pub(crate) fn forget_hub_buckets(&self) {
self.hub_buckets
.lock()
.unwrap_or_else(|e| e.into_inner())
.retain(|_, (_, at)| at.elapsed() < Duration::from_secs(3600));
}
}
/// A JSON answer to the website: its origin may read it, nothing caches it.
pub(crate) fn answer(app: &App, code: StatusCode, body: Value) -> Response {
let mut response = json_response(app, body.to_string(), 0);
*response.status_mut() = code;
response
.headers_mut()
.insert(header::CACHE_CONTROL, HeaderValue::from_static("no-store"));
response
}
pub(crate) fn refuse(app: &App, code: StatusCode, message: &str) -> Response {
answer(app, code, json!({ "error": message }))
}
/// A browser's preflight for the JSON posts: the website may post them.
pub async fn preflight(State(app): State<Arc<App>>) -> Response {
let mut response = answer(&app, StatusCode::NO_CONTENT, Value::Null);
*response.body_mut() = axum::body::Body::empty();
let headers = response.headers_mut();
headers.remove(header::CONTENT_TYPE);
headers.insert(
header::ACCESS_CONTROL_ALLOW_METHODS,
HeaderValue::from_static("POST"),
);
headers.insert(
header::ACCESS_CONTROL_ALLOW_HEADERS,
HeaderValue::from_static("content-type"),
);
headers.insert(
header::ACCESS_CONTROL_MAX_AGE,
HeaderValue::from_static("86400"),
);
response
}
pub(crate) async fn json_body(req: Request) -> Result<Value, &'static str> {
let bytes = axum::body::to_bytes(req.into_body(), MAX_BODY)
.await
.map_err(|_| "too large")?;
serde_json::from_slice(&bytes).map_err(|_| "send JSON")
}
/// `POST /hub/vote` `{"item", "voter", "up"}`: 200 `{"item", "votes"}`.
pub async fn vote(State(app): State<Arc<App>>, req: Request) -> Response {
if !app.allow_hub(&req) {
return refuse(&app, StatusCode::TOO_MANY_REQUESTS, "too many requests");
}
let body = match json_body(req).await {
Ok(body) => body,
Err(e) => return refuse(&app, StatusCode::BAD_REQUEST, e),
};
let item = body["item"].as_str().unwrap_or("");
let voter = body["voter"].as_str().unwrap_or("");
if !item_id(item) || !voter_id(voter) {
return refuse(&app, StatusCode::BAD_REQUEST, "an item id and a voter id");
}
let up = body["up"].as_bool().unwrap_or(true);
let counted = app.store().vote(item, voter, up);
match counted {
Ok(Some(votes)) => {
*app.votes_cache.lock().unwrap_or_else(|e| e.into_inner()) = None;
answer(
&app,
StatusCode::OK,
json!({ "item": item, "votes": votes }),
)
}
Ok(None) => refuse(&app, StatusCode::BAD_REQUEST, "no such item"),
Err(e) => {
eprintln!("horizon-telemetry-server: could not store a vote: {e}");
refuse(&app, StatusCode::SERVICE_UNAVAILABLE, "try again later")
}
}
}
/// `GET /hub/votes`: `{"votes": {"<item>": n}}`, made again at most every minute.
pub async fn votes(State(app): State<Arc<App>>, req: Request) -> Response {
if !app.allow_hub(&req) {
return refuse(&app, StatusCode::TOO_MANY_REQUESTS, "too many requests");
}
let json = {
let mut cache = app.votes_cache.lock().unwrap_or_else(|e| e.into_inner());
match &*cache {
Some((at, json)) if at.elapsed() < VOTES_FOR => json.clone(),
_ => {
let counts = app.store().votes();
match counts {
Ok(counts) => {
let json = json!({ "votes": counts }).to_string();
*cache = Some((Instant::now(), json.clone()));
json
}
Err(e) => {
eprintln!("horizon-telemetry-server: could not read the votes: {e}");
return refuse(&app, StatusCode::SERVICE_UNAVAILABLE, "try again later");
}
}
}
}
};
json_response(&app, json, VOTES_FOR.as_secs())
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn ids_are_checked_for_shape() {
assert!(item_id("smooth-frames") && item_id("v2"));
for bad in ["", "-a", "a-", "a--b", "Smooth", "a b", &"a".repeat(49)] {
assert!(!item_id(bad), "{bad}");
}
assert!(voter_id("0b7c3c9e-3f0a-4d8e-9a39-4c1f5a6b7d21") && !voter_id("short"));
}
}
+25 -4
View File
@@ -7,6 +7,7 @@
//! least 3 installs only (`summary`), cached; the website's Benchmarks page reads it.
//! - `POST /v1/live`: a game's anonymous "I'm playing" ping (`live`, in memory only).
//! - `GET /v1/live`: how many play now, rounded, cached briefly.
//! - `POST /hub/vote`, `GET /hub/votes`: the hub's 👍 on roadmap items (`hub`).
//! - `GET /healthz`.
//!
//! Abuse limits: a token bucket per IP address (kept in memory for an hour, never stored), a
@@ -15,6 +16,7 @@
//! rows expire after `retention_days`; the daily totals stay. One small process and one SQLite
//! file: see `README.md` for running it.
use std::collections::HashMap;
use std::hash::{Hash, RandomState};
use std::net::{IpAddr, SocketAddr};
use std::sync::{Arc, Mutex};
use std::time::{Duration, Instant};
@@ -27,6 +29,7 @@ use axum::routing::{delete, get, post};
use horizon_telemetry::batch;
pub mod classes;
pub mod hub;
pub mod live;
pub mod store;
pub mod summary;
@@ -56,6 +59,8 @@ pub struct Config {
pub live_window: Duration,
/// Sessions the live count holds at most; a new one past that is refused.
pub live_max_sessions: usize,
/// The hub's votes and reads of their counts an IP address may make an hour.
pub hub_per_hour: f64,
}
impl Default for Config {
@@ -70,6 +75,7 @@ impl Default for Config {
live_per_hour: 600.0,
live_window: horizon_telemetry::live::WINDOW,
live_max_sessions: 200_000,
hub_per_hour: 120.0,
}
}
}
@@ -77,7 +83,7 @@ impl Default for Config {
impl Config {
/// The defaults, with `HORIZON_TELEMETRY_RETENTION_DAYS`, `…_MIN_INSTALL_DAYS`,
/// `…_REQUESTS_PER_HOUR`, `…_ITEMS_PER_DAY`, `…_TRUST_PROXY` (1), `…_ALLOW_ORIGIN`,
/// `…_LIVE_PER_HOUR`, `…_LIVE_WINDOW_SECONDS` and `…_LIVE_MAX_SESSIONS`.
/// `…_LIVE_PER_HOUR`, `…_LIVE_WINDOW_SECONDS`, `…_LIVE_MAX_SESSIONS` and `…_HUB_PER_HOUR`.
pub fn from_env() -> Self {
let var = |k: &str| std::env::var(format!("HORIZON_TELEMETRY_{k}")).ok();
let d = Self::default();
@@ -105,6 +111,9 @@ impl Config {
live_max_sessions: var("LIVE_MAX_SESSIONS")
.and_then(|v| v.parse().ok())
.unwrap_or(d.live_max_sessions),
hub_per_hour: var("HUB_PER_HOUR")
.and_then(|v| v.parse().ok())
.unwrap_or(d.hub_per_hour),
}
}
}
@@ -126,6 +135,12 @@ pub struct App {
summary_cache: Mutex<Option<(Instant, String)>>,
/// Today, in days since 1970 (a test moves it).
today: Box<dyn Fn() -> u32 + Send + Sync>,
/// The key the hub's buckets hash addresses with, drawn at start and never stored.
hub_key: RandomState,
/// The hub's votes and vote counts, per hashed address.
hub_buckets: Mutex<hub::HashedBuckets>,
/// `GET /hub/votes`'s answer and when it was made.
votes_cache: Mutex<Option<(Instant, String)>>,
}
type Buckets = HashMap<IpAddr, (f64, Instant)>;
@@ -157,6 +172,9 @@ impl App {
cache: Mutex::default(),
summary_cache: Mutex::default(),
today,
hub_key: RandomState::new(),
hub_buckets: Mutex::default(),
votes_cache: Mutex::default(),
})
}
@@ -221,6 +239,7 @@ impl App {
pub fn maintain(&self) -> rusqlite::Result<usize> {
let oldest = (self.today)().saturating_sub(self.config.retention_days);
let removed = self.store().expire(oldest)?;
self.forget_hub_buckets();
for buckets in [&self.buckets, &self.live_buckets] {
buckets
.lock()
@@ -235,14 +254,14 @@ impl App {
}
}
/// Takes a token for `ip` from its bucket in `buckets` (`per_hour`, bursts of a tenth of it);
/// Takes a token for `key` from its bucket in `buckets` (`per_hour`, bursts of a tenth of it);
/// false when it has none left.
fn take(buckets: &Mutex<Buckets>, per_hour: f64, ip: IpAddr) -> bool {
fn take<K: Hash + Eq>(buckets: &Mutex<HashMap<K, (f64, Instant)>>, per_hour: f64, key: K) -> bool {
let rate = per_hour / 3600.0;
let burst = (per_hour / 10.0).max(1.0);
let mut buckets = buckets.lock().unwrap_or_else(|e| e.into_inner());
let now = Instant::now();
let (tokens, at) = buckets.entry(ip).or_insert((burst, now));
let (tokens, at) = buckets.entry(key).or_insert((burst, now));
*tokens = (*tokens + now.duration_since(*at).as_secs_f64() * rate).min(burst);
*at = now;
if *tokens < 1.0 {
@@ -482,6 +501,8 @@ pub fn router(app: Arc<App>) -> Router {
.route("/v1/installs/{id}", delete(forget))
.route("/v1/aggregate", get(aggregate))
.route("/v1/benchmarks/summary", get(benchmarks))
.route("/hub/vote", post(hub::vote).options(hub::preflight))
.route("/hub/votes", get(hub::votes))
.route("/healthz", get(|| async { "ok" }))
.with_state(app)
}
+2 -1
View File
@@ -123,13 +123,14 @@ pub fn gpu_vendor(gpu: &str) -> &'static str {
}
pub struct Store {
db: Connection,
pub(crate) db: Connection,
}
impl Store {
pub fn open(path: &str) -> rusqlite::Result<Self> {
let mut db = Connection::open(path)?;
db.execute_batch(SCHEMA)?;
db.execute_batch(crate::hub::SCHEMA)?;
migrate(&mut db)?;
Ok(Self { db })
}
@@ -0,0 +1,116 @@
//! The hub's votes through the HTTP interface.
use std::sync::Arc;
use axum::body::Body;
use axum::http::{Request, StatusCode};
use horizon_telemetry_server::store::Store;
use horizon_telemetry_server::{App, Config, router};
use http_body_util::BodyExt;
use serde_json::{Value, json};
use tower::ServiceExt;
const DAY: u32 = 20_741;
const VOTER: &str = "0b7c3c9e-3f0a-4d8e-9a39-4c1f5a6b7d21";
struct Hub {
app: Arc<App>,
}
fn hub(config: Config) -> Hub {
let app = App::with_clock(Store::open(":memory:").unwrap(), config, Box::new(|| DAY));
Hub { app }
}
fn config() -> Config {
Config::default()
}
impl Hub {
async fn send(&self, req: Request<Body>) -> (StatusCode, Value) {
let res = router(self.app.clone()).oneshot(req).await.unwrap();
let code = res.status();
let body = res.into_body().collect().await.unwrap().to_bytes();
(code, serde_json::from_slice(&body).unwrap_or(Value::Null))
}
async fn post(&self, path: &str, body: Value) -> (StatusCode, Value) {
self.send(
Request::post(path)
.header("content-type", "application/json")
.body(Body::from(body.to_string()))
.unwrap(),
)
.await
}
async fn get(&self, path: &str) -> (StatusCode, Value) {
self.send(Request::get(path).body(Body::empty()).unwrap())
.await
}
}
#[tokio::test]
async fn votes_count_once_per_browser_and_can_be_taken_back() {
let hub = hub(config());
let vote = |up: bool, voter: &str| json!({ "item": "smooth-frames", "voter": voter, "up": up });
assert_eq!(
hub.post("/hub/vote", vote(true, VOTER)).await,
(
StatusCode::OK,
json!({ "item": "smooth-frames", "votes": 1 })
)
);
assert_eq!(
hub.post("/hub/vote", vote(true, VOTER)).await.1["votes"],
1,
"a second vote changes nothing"
);
let other = "f".repeat(32);
assert_eq!(
hub.post("/hub/vote", vote(true, &other)).await.1["votes"],
2
);
assert_eq!(
hub.get("/hub/votes").await,
(StatusCode::OK, json!({ "votes": { "smooth-frames": 2 } }))
);
assert_eq!(
hub.post("/hub/vote", vote(false, VOTER)).await.1["votes"],
1
);
assert_eq!(
hub.get("/hub/votes").await.1["votes"]["smooth-frames"],
1,
"a vote drops the cached counts"
);
for bad in [
json!({ "item": "Not An Id", "voter": VOTER }),
json!({ "item": "a", "voter": "short" }),
json!([]),
] {
assert_eq!(hub.post("/hub/vote", bad).await.0, StatusCode::BAD_REQUEST);
}
}
#[tokio::test]
async fn the_website_may_post_from_the_browser() {
let hub = hub(config());
let res = router(hub.app.clone())
.oneshot(
Request::options("/hub/vote")
.header("origin", "https://playhorizon.dev")
.header("access-control-request-method", "POST")
.body(Body::empty())
.unwrap(),
)
.await
.unwrap();
assert_eq!(res.status(), StatusCode::NO_CONTENT);
let header = |name: &str| res.headers()[name].to_str().unwrap().to_owned();
assert_eq!(
header("access-control-allow-origin"),
"https://playhorizon.dev"
);
assert_eq!(header("access-control-allow-methods"), "POST");
assert_eq!(header("access-control-allow-headers"), "content-type");
}