Skip to content

v0.2: ping/pong, stricter names, forward-compatible server messages - #2

Merged
RalfLeonFasler merged 1 commit into
mainfrom
protocol-v0.2
Nov 7, 2026
Merged

RalfLeonFasler merged 1 commit into
mainfrom
protocol-v0.2

Conversation

@RalfLeonFasler

Copy link
Copy Markdown
Contributor

Summary

Spec changes from the first app implementation (OpenRadlr, Lethonium/OpenRadlr#37), which tested v0 live against the reference server. welcome.protocol becomes "0.2".

  • Join then update (6.3, 7.6): the state in join does not count towards max_update_hz, so an app may send update right after join. rate_limited does not count towards too_many_errors. Before this, a backend that joined and updated 20+ riders at once was disconnected, and the same thing happened again on every reconnect.
  • Display names (new 6.3.1): names must not contain Cc, Cf, Co, Zl or Zp characters (except U+200D ZERO WIDTH JOINER, which emoji sequences need), or be only whitespace. Receivers must show names as plain text. This keeps out bidi overrides and invisible characters. Both message schemas check the same Unicode 15.0 ranges, which also closes the C1 range (U+0080–009F) the old pattern missed. Tag characters are rejected too, and with them the England/Scotland/Wales flag emoji.
  • Forward compatibility (3.2): apps must ignore server messages with an unknown type, and must accept unknown error.code (acting on fatal) and left.reason values.
  • Dead-server detection (3.5, 6.6, 7.7): new ping message, answered with pong carrying the ref. Browsers can't see WebSocket pings, so apps need an app-level message. An app that has received nothing for 20 s should ping, and may treat the connection as closed after 10 s more. Apps that see WebSocket pings may use a 45 s rule instead.

Examples added: app/ping.json, server/pong.json, app/join-emoji-name.json, and seven invalid names.

Test plan

  • python3 tools/validate.py: every spec JSON block has a matching example, examples match the schemas, and each invalid name fails the schema
  • Reference server implementation and tests in OpenBikeNet/server (PR follows)

🤖 Generated with Claude Code

From the first app implementation (OpenRadlr):
- The state in join does not count towards max_update_hz; rate_limited
  does not count towards too_many_errors.
- Names must not contain Cc, Cf (except ZWJ), Co, Zl or Zp characters or
  be only whitespace; receivers display names as plain text.
- Apps ignore unknown server message types and accept unknown error codes
  and leave reasons.
- New ping/pong messages so apps (also in browsers, which cannot see
  WebSocket pings) can detect a dead server.
- welcome.protocol is now 0.2.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
(cherry picked from commit d0446d5)
@RalfLeonFasler
RalfLeonFasler merged commit e00bdb6 into main Nov 7, 2026
1 check passed
@RalfLeonFasler
RalfLeonFasler deleted the protocol-v0.2 branch November 7, 2026 11:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant