Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions crates/fake-app/src/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -111,8 +111,8 @@ async fn run(args: Args) -> Result<(), String> {

let mut bots: Vec<Bot> = (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),
})
Expand Down
23 changes: 21 additions & 2 deletions crates/server/src/presence.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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<Instant>,
}

#[derive(Debug)]
Expand Down Expand Up @@ -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);
Expand Down Expand Up @@ -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()))
Expand Down Expand Up @@ -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();
Expand Down
53 changes: 51 additions & 2 deletions crates/server/src/protocol.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -172,6 +174,7 @@ pub enum AppMsg {
Leave {
rider: String,
},
Ping,
}

#[derive(Debug, Clone, PartialEq)]
Expand Down Expand Up @@ -263,6 +266,10 @@ pub enum ServerMsg {
rider: Option<String>,
fatal: bool,
},
Pong {
#[serde(rename = "ref", skip_serializing_if = "Option::is_none")]
ref_: Option<String>,
},
}

impl From<ProtoError> for ServerMsg {
Expand Down Expand Up @@ -360,6 +367,7 @@ fn parse_body(obj: &Map<String, Value>) -> Result<AppMsg, ProtoError> {
"leave" => Ok(AppMsg::Leave {
rider: rider_field(obj)?,
}),
"ping" => Ok(AppMsg::Ping),
other => Err(ProtoError::new(
ErrorCode::UnknownType,
format!("unknown type {:?}", truncate(other)),
Expand Down Expand Up @@ -458,12 +466,53 @@ fn name_field(obj: &Map<String, Value>) -> Result<String, ProtoError> {
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<f64, ProtoError> {
Expand Down
39 changes: 24 additions & 15 deletions crates/server/src/ws.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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<String>) -> 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());
Expand Down Expand Up @@ -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,
});
Expand All @@ -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) => {
Expand Down
8 changes: 7 additions & 1 deletion crates/server/tests/protocol_examples.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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(),
},
Expand Down Expand Up @@ -151,6 +151,12 @@ fn server_messages_match_examples() {
fatal: false,
},
);
check(
"pong.json",
ServerMsg::Pong {
ref_: Some("hb-17".into()),
},
);
}

#[test]
Expand Down
30 changes: 29 additions & 1 deletion crates/server/tests/ws.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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());
}
Expand Down Expand Up @@ -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;
Expand Down
93 changes: 93 additions & 0 deletions docs/2026-11-07-feedback-from-openradlr.md
Original file line number Diff line number Diff line change
@@ -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`.
Loading