diff --git a/crates/fake-app/src/main.rs b/crates/fake-app/src/main.rs index 0015ffd..ed66a0c 100644 --- a/crates/fake-app/src/main.rs +++ b/crates/fake-app/src/main.rs @@ -111,8 +111,8 @@ async fn run(args: Args) -> Result<(), String> { let mut bots: Vec = (0..args.riders) .map(|i| Bot { - id: format!("bot-{}", i + 1), - name: format!("Bot {}", i + 1), + id: format!("fake-{}", i + 1), + name: format!("Fake {}", i + 1), lap: 0, distance: args.length * f64::from(i) / f64::from(args.riders), }) diff --git a/crates/server/src/presence.rs b/crates/server/src/presence.rs index 0c843d0..9f8105c 100644 --- a/crates/server/src/presence.rs +++ b/crates/server/src/presence.rs @@ -36,8 +36,10 @@ struct Rider { room: String, name: String, state: RiderState, - /// When the last state was accepted. + /// When the last state was accepted, by `join` or `update`. Drives the timeout. last: Instant, + /// When the last `update` was accepted. Drives the rate limit; a join does not count (spec 6.3). + last_update: Option, } #[derive(Debug)] @@ -156,6 +158,7 @@ impl Presence { name: join.name, state: join.state, last: now, + last_update: None, }; self.next_rider += 1; let joined = view(&c.app, &rider); @@ -207,11 +210,14 @@ impl Presence { continue; } } - if now.saturating_duration_since(r.last) < min_interval { + if r.last_update + .is_some_and(|t| now.saturating_duration_since(t) < min_interval) + { errors.push(fail(ErrorCode::RateLimited, "updates are coming too fast".to_string())); continue; } r.last = now; + r.last_update = Some(now); r.state = e.state.clone(); accepted .entry((r.route.clone(), r.room.clone())) @@ -742,6 +748,19 @@ mod tests { assert_eq!(d.len(), 1); } + #[test] + fn update_right_after_join_is_accepted() { + let mut p = presence(); + let t0 = Instant::now(); + p.connect(1, app("app-one")); + p.connect(2, app("app-two")); + p.subscribe(2, V, P).unwrap(); + p.join(1, join_msg("u-1", "A"), t0).unwrap(); + let (d, errs) = p.update(1, vec![entry("u-1", 1.0)], t0); + assert!(errs.is_empty(), "{errs:?}"); + assert_eq!(d.len(), 1); + } + #[test] fn timeout_after_rider_timeout_s() { let mut p = presence(); diff --git a/crates/server/src/protocol.rs b/crates/server/src/protocol.rs index db9eeeb..d1947d6 100644 --- a/crates/server/src/protocol.rs +++ b/crates/server/src/protocol.rs @@ -8,6 +8,8 @@ use serde::Serialize; use serde_json::{Map, Value}; pub const DEFAULT_ROOM: &str = "public"; +/// The minor version of v0 this server implements, sent in `welcome`. +pub const PROTOCOL_VERSION: &str = "0.2"; const MAX_REF: usize = 64; const MAX_RIDER: usize = 64; @@ -172,6 +174,7 @@ pub enum AppMsg { Leave { rider: String, }, + Ping, } #[derive(Debug, Clone, PartialEq)] @@ -263,6 +266,10 @@ pub enum ServerMsg { rider: Option, fatal: bool, }, + Pong { + #[serde(rename = "ref", skip_serializing_if = "Option::is_none")] + ref_: Option, + }, } impl From for ServerMsg { @@ -360,6 +367,7 @@ fn parse_body(obj: &Map) -> Result { "leave" => Ok(AppMsg::Leave { rider: rider_field(obj)?, }), + "ping" => Ok(AppMsg::Ping), other => Err(ProtoError::new( ErrorCode::UnknownType, format!("unknown type {:?}", truncate(other)), @@ -458,12 +466,53 @@ fn name_field(obj: &Map) -> Result { if len == 0 || len > MAX_NAME { return Err(invalid_value("name must be 1 to 32 characters")); } - if name.chars().any(char::is_control) { - return Err(invalid_value("name must not contain control characters")); + if name.chars().any(is_forbidden_in_name) { + return Err(invalid_value( + "name must not contain control, format, private-use or separator characters", + )); + } + if name.chars().all(char::is_whitespace) { + return Err(invalid_value("name must not be only whitespace")); } Ok(name.to_string()) } +/// Unicode general categories Cc, Cf, Co, Zl and Zp (Unicode 15.0), except U+200D ZERO WIDTH +/// JOINER, which emoji sequences need (spec 6.3.1). The same ranges as the `name` pattern in the +/// message schemas. +fn is_forbidden_in_name(c: char) -> bool { + matches!( + u32::from(c), + 0x0000..=0x001F + | 0x007F..=0x009F + | 0x00AD + | 0x0600..=0x0605 + | 0x061C + | 0x06DD + | 0x070F + | 0x0890..=0x0891 + | 0x08E2 + | 0x180E + | 0x200B..=0x200C + | 0x200E..=0x200F + | 0x2028..=0x202E + | 0x2060..=0x2064 + | 0x2066..=0x206F + | 0xE000..=0xF8FF + | 0xFEFF + | 0xFFF9..=0xFFFB + | 0x110BD + | 0x110CD + | 0x13430..=0x1343F + | 0x1BCA0..=0x1BCA3 + | 0x1D173..=0x1D17A + | 0xE0001 + | 0xE0020..=0xE007F + | 0xF0000..=0xFFFFD + | 0x100000..=0x10FFFD + ) +} + /// A number that must be a whole number within `min..=max`. A non-number is `invalid_message`, /// a fraction or an out-of-range number is `invalid_value`. fn int_value(v: &Value, key: &str, min: f64, max: f64) -> Result { diff --git a/crates/server/src/ws.rs b/crates/server/src/ws.rs index 79a8884..e715c4e 100644 --- a/crates/server/src/ws.rs +++ b/crates/server/src/ws.rs @@ -25,7 +25,9 @@ use crate::config::Config; use crate::metrics::{today_utc, Metrics}; use crate::presence::{ConnId, Delivery, Presence}; use crate::prometheus::{render, Counters, CONTENT_TYPE}; -use crate::protocol::{parse_app_msg, parse_update_entry, AppInfo, AppMsg, ErrorCode, ProtoError, ServerMsg}; +use crate::protocol::{ + parse_app_msg, parse_update_entry, AppInfo, AppMsg, ErrorCode, ProtoError, ServerMsg, PROTOCOL_VERSION, +}; use crate::routes::Routes; const QUEUE_CAPACITY: usize = 1024; @@ -393,25 +395,28 @@ impl Session { } /// Sends the error to this connection. Returns `Close` if it was fatal, or if it pushed the - /// connection over the error rate (more than 20 non-fatal errors within 10 s). + /// connection over the error rate (more than 20 non-fatal errors within 10 s). `rate_limited` + /// does not count: it is a pacing hint, and a backend with many riders can get one per rider. fn report(&mut self, err: ProtoError, ref_: &Option) -> Flow { let err = err.with_ref(ref_.clone()); if err.code.fatal() { self.fatal(err); return Flow::Close; } - let now = Instant::now(); - self.recent_errors.push_back(now); - while self - .recent_errors - .front() - .is_some_and(|t| now.duration_since(*t) > ERROR_WINDOW) - { - self.recent_errors.pop_front(); - } - if self.recent_errors.len() > MAX_ERRORS_IN_WINDOW { - self.fatal(ProtoError::new(ErrorCode::TooManyErrors, "too many errors").with_ref(ref_.clone())); - return Flow::Close; + if err.code != ErrorCode::RateLimited { + let now = Instant::now(); + self.recent_errors.push_back(now); + while self + .recent_errors + .front() + .is_some_and(|t| now.duration_since(*t) > ERROR_WINDOW) + { + self.recent_errors.pop_front(); + } + if self.recent_errors.len() > MAX_ERRORS_IN_WINDOW { + self.fatal(ProtoError::new(ErrorCode::TooManyErrors, "too many errors").with_ref(ref_.clone())); + return Flow::Close; + } } self.state.counters.error_sent(err.code); self.send_self(err.into()); @@ -481,7 +486,7 @@ impl Session { self.app = Some(info.id.clone()); lock(&state.presence).connect(self.conn, info); self.send_self(ServerMsg::Welcome { - protocol: "0.1", + protocol: PROTOCOL_VERSION, connection: conn_name(self.conn), limits: state.config.limits, }); @@ -502,6 +507,10 @@ impl Session { AppMsg::Join(join) => lock(&state.presence).join(conn, join, now), AppMsg::Leave { rider } => lock(&state.presence).leave(conn, &rider), AppMsg::Update(entries) => return self.update(entries, ref_, now), + AppMsg::Ping => { + self.send_self(ServerMsg::Pong { ref_ }); + return Flow::Continue; + } }; match result { Ok(deliveries) => { diff --git a/crates/server/tests/protocol_examples.rs b/crates/server/tests/protocol_examples.rs index 3945fe6..1a2246f 100644 --- a/crates/server/tests/protocol_examples.rs +++ b/crates/server/tests/protocol_examples.rs @@ -100,7 +100,7 @@ fn server_messages_match_examples() { check( "welcome.json", ServerMsg::Welcome { - protocol: "0.1", + protocol: "0.2", connection: "c9Qe4".into(), limits: Limits::default(), }, @@ -151,6 +151,12 @@ fn server_messages_match_examples() { fatal: false, }, ); + check( + "pong.json", + ServerMsg::Pong { + ref_: Some("hb-17".into()), + }, + ); } #[test] diff --git a/crates/server/tests/ws.rs b/crates/server/tests/ws.rs index 44e6cad..0fa2235 100644 --- a/crates/server/tests/ws.rs +++ b/crates/server/tests/ws.rs @@ -147,7 +147,7 @@ async fn welcome_has_limits() { send(&mut c, json!({"type":"hello","app":{"id":"app-a","version":"1.0"}})).await; let w = recv_json(&mut c).await; assert_eq!(w["type"], "welcome"); - assert_eq!(w["protocol"], "0.1"); + assert_eq!(w["protocol"], "0.2"); assert_eq!(w["connection"], "c1"); assert_eq!(w["limits"], serde_json::to_value(Limits::default()).unwrap()); } @@ -222,6 +222,34 @@ async fn error_carries_ref() { assert_eq!(e["fatal"], false); } +#[tokio::test] +async fn ping_gets_pong() { + let addr = start(test_config()).await; + let mut c = app(addr, "app-a").await; + send(&mut c, json!({"type":"ping","ref":"hb-1"})).await; + assert_eq!(recv_json(&mut c).await, json!({"type":"pong","ref":"hb-1"})); + send(&mut c, json!({"type":"ping"})).await; + assert_eq!(recv_json(&mut c).await, json!({"type":"pong"})); +} + +#[tokio::test] +async fn rate_limited_does_not_count_towards_too_many_errors() { + let mut config = test_config(); + config.limits.max_update_hz = 1; + let addr = start(config).await; + let mut c = app(addr, "app-a").await; + send(&mut c, join_msg("u-1")).await; + // Far more than the 20 errors in 10 s that close a connection. + let entry = json!({"rider":"u-1","lap":0,"distance":1,"speed":1}); + send(&mut c, json!({"type":"update","riders":vec![entry; 30]})).await; + for _ in 0..29 { + let e = recv_json(&mut c).await; + assert_eq!(e["code"], "rate_limited", "{e}"); + } + // Still open. + subscribe(&mut c).await; +} + #[tokio::test] async fn reconnect_gives_new_id() { let addr = start(test_config()).await; diff --git a/docs/2026-11-07-feedback-from-openradlr.md b/docs/2026-11-07-feedback-from-openradlr.md new file mode 100644 index 0000000..e494785 --- /dev/null +++ b/docs/2026-11-07-feedback-from-openradlr.md @@ -0,0 +1,93 @@ +# Feedback from the first app implementation (OpenRadlr) + +Date: 2026-11-07. OpenRadlr implemented protocol v0 against this server (OpenRadlr PR +[#37](https://github.com/Lethonium/OpenRadlr/pull/37), code in `server/crates/server/src/obn/` +there) and tested it live against `make dev` here plus `obn-fake-app`. These are the points it +raised, most important first. All five are resolved; each section ends with what was decided. +The spec changes are protocol v0.2 (`welcome.protocol` is now `"0.2"`). + +Affects: **S** = this server, **P** = the protocol spec (`protocol/spec/v0.md`), **F** = the fake app. + +## 1. A join followed by an update is rate-limited, and that can loop (S, P) + +**What happened:** OpenRadlr sent `join` and, in the same second, an `update` for the new rider. +The server answered `rate_limited`. + +**Cause:** in `crates/server/src/presence.rs` (around line 210) the rate limit compares against +`r.last`, which the join sets. An update within `0.8 / max_update_hz` s of the join is dropped. +The spec doesn't say a join counts as an update; section 3.4 step 4 ("send `join` … then +`update` messages") reads as if join-then-update is fine. + +**Why it matters more than one dropped entry:** `rate_limited` counts towards +`too_many_errors` (`ws.rs`: more than `MAX_ERRORS_IN_WINDOW = 20` errors in 10 s is fatal). An +app that reconnects with 20+ riders and sends join + update for each is disconnected; on +reconnect it joins everyone again and is disconnected again: a loop. A group ride start does the +same. + +**Options:** +- Server: a join does not start the rate-limit clock (lean), and/or `rate_limited` does not count + towards `too_many_errors` (it is a pacing hint, not a misbehaving client). +- Spec: state explicitly whether the join's state counts as the rider's first update for + `max_update_hz`. + +OpenRadlr worked around it (sends only `join` in the frame a rider joins), so it works either way. + +**Decided:** both server options. A join no longer starts the rate-limit clock (it still resets +the timeout), and `rate_limited` does not count towards `too_many_errors`. Spec 6.3 says the join +state does not count towards `max_update_hz`; spec 7.6 says `rate_limited` does not count. + +## 2. Names can carry invisible and bidi characters (S, P) + +The spec forbids only "control characters" (6.3), and `protocol.rs` (~line 461) checks +`char::is_control`, which is Unicode category Cc only. Format characters (Cf) pass: bidi overrides +such as U+202E, zero-width space/joiner, etc. They let one rider disguise or reverse their name in +every other app. + +**Proposal:** spec: names MUST NOT contain Cc or Cf characters (maybe also unassigned / private +use), and receivers MUST display names as plain text, never as markup. Server: reject such names +with `invalid_value`. OpenRadlr now cleans incoming names itself, but every app shouldn't have to +rely on its own filter. + +**Decided:** spec 6.3.1 forbids Cc, Cf, Co, Zl and Zp, except U+200D ZERO WIDTH JOINER (emoji +sequences need it), and names that are only whitespace. Unassigned characters are allowed, since +what is unassigned depends on the Unicode version. Receivers MUST show names as plain text. The +server and both message schemas use the same Unicode 15.0 ranges. Tag characters (U+E0020…) +are rejected too, which also rejects the England/Scotland/Wales flag emoji. + +## 3. Unknown server message types (P) + +3.2 says receivers ignore unknown *fields*, and the server answers an unknown `type` from an app +with an error. Nothing says what an app does with an unknown `type` from the server. Adding +"apps MUST ignore server messages with an unknown `type`" lets v0.x add messages without breaking +older apps. (OpenRadlr already ignores them, logging at debug.) + +**Decided:** spec 3.2, broadened: apps MUST ignore unknown server message types and MUST accept +unknown `error.code` (acting on `fatal`) and `left.reason` values. + +## 4. How an app detects a dead server (P) + +3.5 defines server pings every 15 s and closing on missing pongs, but gives apps no rule for a +server that goes silent (half-open TCP). Suggest one line such as: "An app MAY treat a connection +with no ping for 45 seconds as closed and reconnect." OpenRadlr has no watchdog yet and would +build it on that rule. + +**Decided:** browsers cannot see WebSocket pings, so v0.2 adds an app-level `ping` (spec 6.6) +that the server answers with `pong` (7.7), carrying the `ref`. Spec 3.5: an app that has received +nothing for 20 s SHOULD send `ping` and MAY treat the connection as closed if nothing arrives in +10 s; apps that see WebSocket pings MAY use a 45 s rule instead. A v0.1 server answers `ping` +with `unknown_type`, which also shows it is alive. + +## 5. Fake app riders look like local bots (F) + +`obn-fake-app` names its riders `Bot 1…N`. In OpenRadlr (which also has bots) a fake rider shows +as "Bot 3 · incyclist", which reads like a local bot. Names such as `Fake 1…N`, or taking the +`--app` value into account, would avoid the confusion. + +**Decided:** fake riders are now `Fake 1…N` (rider values `fake-1…N`). + +## Smaller observations (no action needed unless you want) + +- Reconnect means new server IDs and laps from 0 (spec 3.5): other apps see `left` + `joined`. + Fine for v0; a resume token could come later. +- OpenRadlr ignores `welcome.limits` and sends at a fixed 1 Hz, which is within the + recommended limits. Apps sending faster should read `max_update_hz`. diff --git a/protocol b/protocol index a557731..e00bdb6 160000 --- a/protocol +++ b/protocol @@ -1 +1 @@ -Subproject commit a557731beb0c2e364814a7440ae2309b3c631511 +Subproject commit e00bdb671ca66526c452dfc1a3d1cf8c50cc7331