diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..d1fc901 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,7 @@ +.git +.github +.env* +**/target +docs +*.md +*.sqlite diff --git a/.env.dev.example b/.env.dev.example new file mode 100644 index 0000000..1f341d6 --- /dev/null +++ b/.env.dev.example @@ -0,0 +1,11 @@ +# Local settings for `make dev`: copy to .env.dev (gitignored) and adjust. +# `make dev` runs cargo on 127.0.0.1:8090; these override its defaults. + +# Where the server stores its usage statistics. +OBN_DB=obn.sqlite + +# Routes from the protocol submodule. +OBN_ROUTES_DIR=protocol/routes + +# Log level (RUST_LOG syntax). +RUST_LOG=info,obn_server=debug diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..57947ac --- /dev/null +++ b/.env.example @@ -0,0 +1,34 @@ +# OpenBikeNet server configuration. Copy to .env (`make setup` does this) and adjust. +# Every value is optional; the defaults below are used when a line is missing. +# After an update, `make setup` (also run by `make up` and `make update`) adds +# settings that are new here to the end of your .env and leaves the rest alone. + +# --- Network ----------------------------------------------------------------- + +# Host interface and port for the WebSocket and the stats endpoint. +# 127.0.0.1 = this machine only. 0.0.0.0 = reachable from the network. +OBN_HTTP_BIND=127.0.0.1 +OBN_HTTP_PORT=8090 + +# Behind a reverse proxy (Caddy, nginx, Traefik): take client IPs from +# X-Forwarded-For (1 or true). Set it to 1 behind the bundled Caddy or your own +# proxy, and only when the proxy is the only way in. 0 = off. +OBN_TRUST_PROXY=0 + +# Log level: error, warn, info, debug, trace (RUST_LOG syntax). +RUST_LOG=info + +# --- HTTPS (bundled Caddy, optional) ----------------------------------------- +# Not needed when your own reverse proxy terminates TLS (see the README). +# For a public server, point a DNS record at it, then enable Caddy: +# +# COMPOSE_PROFILES=tls +# OBN_DOMAIN=net.example.org +# +# Caddy obtains a Let's Encrypt certificate automatically (ports 80 and 443). +# Also set OBN_TRUST_PROXY=1 above. +#COMPOSE_PROFILES=tls +OBN_DOMAIN= + +# --- Build ------------------------------------------------------------------- +OBN_IMAGE_TAG=local diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..47c62ab --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,51 @@ +name: CI + +on: + push: + branches: [main] + pull_request: + +# Read-only token: CI only checks out and tests, and pull requests from forks +# must not get write access. +permissions: + contents: read + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + server: + name: Rust + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + submodules: true + - uses: dtolnay/rust-toolchain@b725eda525362e7cf34af9a7243cac1e3f01a7ec # stable + with: + components: rustfmt, clippy + - uses: Swatinem/rust-cache@d1527c8f67ef9af357290475d4af4b0fab8f12e0 # v2.9.3 + - run: cargo fmt --all -- --check + - run: cargo clippy --workspace --all-targets -- -D warnings + - run: cargo test --workspace + + docker: + name: Docker image + runs-on: ubuntu-latest + needs: [server] + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + submodules: true + - run: docker build -t obn-server:ci --build-arg OBN_BUILD_SHA=${{ github.sha }} . + - name: Smoke test + run: | + docker run -d --name obn -p 18080:8080 obn-server:ci + for i in $(seq 1 30); do + curl -fsS localhost:18080/healthz >/dev/null 2>&1 && break + if [ "$i" -eq 30 ]; then docker logs obn; echo "server did not become healthy"; exit 1; fi + sleep 1 + done + test "$(curl -fsS localhost:18080/v0/stats)" = '{"apps":[]}' + docker stop obn diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..80c7805 --- /dev/null +++ b/.gitignore @@ -0,0 +1,6 @@ +target/ +*.sqlite + +# Local configuration +.env +.env.dev diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..d1af302 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "protocol"] + path = protocol + url = https://github.com/OpenBikeNet/protocol diff --git a/Cargo.lock b/Cargo.lock new file mode 100644 index 0000000..44ac5e8 --- /dev/null +++ b/Cargo.lock @@ -0,0 +1,1128 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +version = 4 + +[[package]] +name = "aho-corasick" +version = "1.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c982642fa9e8606056828ee9a8505737230110bb1099153c79efe865c59d12ba" +dependencies = [ + "memchr", +] + +[[package]] +name = "atomic-waker" +version = "1.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1505bd5d3d116872e7271a6d4e16d81d0c8570876c8de68093a09ac269d8aac0" + +[[package]] +name = "axum" +version = "0.8.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "31b698c5f9a010f6573133b09e0de5408834d0c82f8d7475a89fc1867a71cd90" +dependencies = [ + "axum-core", + "base64", + "bytes", + "form_urlencoded", + "futures-util", + "http", + "http-body", + "http-body-util", + "hyper", + "hyper-util", + "itoa", + "matchit", + "memchr", + "mime", + "percent-encoding", + "pin-project-lite", + "serde_core", + "serde_json", + "serde_path_to_error", + "serde_urlencoded", + "sha1", + "sync_wrapper", + "tokio", + "tokio-tungstenite", + "tower", + "tower-layer", + "tower-service", + "tracing", +] + +[[package]] +name = "axum-core" +version = "0.5.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "08c78f31d7b1291f7ee735c1c6780ccde7785daae9a9206026862dab7d8792d1" +dependencies = [ + "bytes", + "futures-core", + "http", + "http-body", + "http-body-util", + "mime", + "pin-project-lite", + "sync_wrapper", + "tower-layer", + "tower-service", + "tracing", +] + +[[package]] +name = "base64" +version = "0.22.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6" + +[[package]] +name = "bitflags" +version = "2.13.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06" + +[[package]] +name = "block-buffer" +version = "0.10.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71" +dependencies = [ + "generic-array", +] + +[[package]] +name = "bumpalo" +version = "3.20.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649" + +[[package]] +name = "bytes" +version = "1.12.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04" + +[[package]] +name = "cc" +version = "1.11.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4ff2a8126fff0f8c839080d619675a585e61720bb12d2baceae45769fd66f155" +dependencies = [ + "find-msvc-tools", + "shlex", +] + +[[package]] +name = "cfg-if" +version = "1.0.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600" + +[[package]] +name = "cpufeatures" +version = "0.2.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280" +dependencies = [ + "libc", +] + +[[package]] +name = "crypto-common" +version = "0.1.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a" +dependencies = [ + "generic-array", + "typenum", +] + +[[package]] +name = "data-encoding" +version = "2.11.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4583a4551df46e2792f82ceeac45e850d2e2d5debba0b91f102385cda5b11f06" + +[[package]] +name = "deranged" +version = "0.5.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9e9de72ce2ad1f90dc62fa25f0f430ef85eb4b0d8fa0be4f30373bc40a21d28e" + +[[package]] +name = "digest" +version = "0.10.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292" +dependencies = [ + "block-buffer", + "crypto-common", +] + +[[package]] +name = "errno" +version = "0.3.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb" +dependencies = [ + "libc", + "windows-sys", +] + +[[package]] +name = "fallible-iterator" +version = "0.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2acce4a10f12dc2fb14a218589d4f1f62ef011b2d0cc4b3cb1bba8e94da14649" + +[[package]] +name = "fallible-streaming-iterator" +version = "0.1.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7360491ce676a36bf9bb3c56c1aa791658183a54d2744120f27285738d90465a" + +[[package]] +name = "find-msvc-tools" +version = "0.1.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1c66915cc5391097de7a2b0b972e8505aa33c0df401fd3a6811dbdb32881ba48" + +[[package]] +name = "foldhash" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "77ce24cb58228fbb8aa041425bb1050850ac19177686ea6e0f41a70416f56fdb" + +[[package]] +name = "form_urlencoded" +version = "1.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cb4cb245038516f5f85277875cdaa4f7d2c9a0fa0468de06ed190163b1581fcf" +dependencies = [ + "percent-encoding", +] + +[[package]] +name = "futures-core" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "92d699e522242e69e3003b94ecc1f960f3a5e015aa7c5d7486e65ad01dd94f5e" + +[[package]] +name = "futures-sink" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1944426bf7d03f1d14f708785e4b33efd750b36d48a157b836b3efc15ede8e1d" + +[[package]] +name = "futures-task" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cd417de3d1d015fc3bfd2b1ea46dfc7bab72ef86f1cc7cc9c78e728b34a6d1fd" + +[[package]] +name = "futures-util" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0d50a92467f8ba5dd6e3ee5d4bd04d73ab2e4e1c44474a0674821dfce14b79bc" +dependencies = [ + "futures-core", + "futures-sink", + "futures-task", + "pin-project-lite", + "slab", +] + +[[package]] +name = "generic-array" +version = "0.14.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a" +dependencies = [ + "typenum", + "version_check", +] + +[[package]] +name = "getrandom" +version = "0.3.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd" +dependencies = [ + "cfg-if", + "libc", + "r-efi", + "wasip2", +] + +[[package]] +name = "hashbrown" +version = "0.16.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "841d1cc9bed7f9236f321df977030373f4a4163ae1a7dbfe1a51a2c1a51d9100" +dependencies = [ + "foldhash", +] + +[[package]] +name = "hashbrown" +version = "0.17.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a" +dependencies = [ + "foldhash", +] + +[[package]] +name = "hashlink" +version = "0.12.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a596f1b20ed2cc5ecac41a164aaebc7258057060f06c0cf7a2ba3991ee7990fb" +dependencies = [ + "hashbrown 0.17.1", +] + +[[package]] +name = "http" +version = "1.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "918d3568bebf352712bc2ef3d46a8bcf1a75b373be6539de198e9105cbbf9ce0" +dependencies = [ + "bytes", + "itoa", +] + +[[package]] +name = "http-body" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ca2a8f2913ee65f60facd6a5905613afaa448497a0230cc41ce022d93290bc2c" +dependencies = [ + "bytes", + "http", +] + +[[package]] +name = "http-body-util" +version = "0.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "23169fe34a5fbcdd3f3862e78fb9b6fccd5f02a6dc6f732547005d45631ce71c" +dependencies = [ + "bytes", + "futures-core", + "http", + "http-body", + "pin-project-lite", +] + +[[package]] +name = "httparse" +version = "1.10.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6dbf3de79e51f3d586ab4cb9d5c3e2c14aa28ed23d180cf89b4df0454a69cc87" + +[[package]] +name = "httpdate" +version = "1.0.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "df3b46402a9d5adb4c86a0cf463f42e19994e3ee891101b1841f30a545cb49a9" + +[[package]] +name = "hyper" +version = "1.12.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2c3e324da4c95177d6291d4c8730197c0d1822f8a9766814a4a44fa5ab797c9c" +dependencies = [ + "atomic-waker", + "bytes", + "futures-core", + "http", + "http-body", + "httparse", + "httpdate", + "itoa", + "pin-project-lite", + "smallvec", + "tokio", +] + +[[package]] +name = "hyper-util" +version = "0.1.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ddc03d96684f9226b8a787cdb71488417b53ab5ea8fdb1dac946cb9431cc8bff" +dependencies = [ + "bytes", + "http", + "http-body", + "hyper", + "pin-project-lite", + "tokio", + "tower-service", +] + +[[package]] +name = "itoa" +version = "1.0.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682" + +[[package]] +name = "js-sys" +version = "0.3.107" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8dc09d2154098bbf4ef54eab6b117a3c24cbbffe94046b16ee6d6d4510584d3a" +dependencies = [ + "cfg-if", + "wasm-bindgen", +] + +[[package]] +name = "lazy_static" +version = "1.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "20870f649af7073d53e38067b2a84312175d56ea15217e1b15bc83506ec50afb" + +[[package]] +name = "libc" +version = "0.2.191" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a" + +[[package]] +name = "libsqlite3-sys" +version = "0.38.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f1d20bef17f513b9b3004532233187769cd072d790971f4e4da0e346eb6401e8" +dependencies = [ + "cc", + "pkg-config", + "vcpkg", +] + +[[package]] +name = "log" +version = "0.4.35" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5d15f86d12da44cd8d4ec3c73984537eb7f4cadcb9776a575a0a8a05ca11005c" + +[[package]] +name = "matchers" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d1525a2a28c7f4fa0fc98bb91ae755d1e2d1505079e05539e35bc876b5d65ae9" +dependencies = [ + "regex-automata", +] + +[[package]] +name = "matchit" +version = "0.8.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "47e1ffaa40ddd1f3ed91f717a33c8c0ee23fff369e3aa8772b9605cc1d22f4c3" + +[[package]] +name = "memchr" +version = "2.8.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98" + +[[package]] +name = "mime" +version = "0.3.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d5848f5a9e8117cf94f2f90faac24a87ff81600ff8628c1e3deaab572e76bfa1" + +[[package]] +name = "mio" +version = "1.2.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1788edb87fdc09c7e26304471e2f5be8cdefb1b6930d6e3985fc02ff53bf86ee" +dependencies = [ + "libc", + "wasi", + "windows-sys", +] + +[[package]] +name = "nu-ansi-term" +version = "0.50.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7957b9740744892f114936ab4a57b3f487491bbeafaf8083688b16841a4240e5" +dependencies = [ + "windows-sys", +] + +[[package]] +name = "num-conv" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "521739c6d2bac4aa25192232afe6841231376b2b26d4d9fae5ecf8ca5772e441" + +[[package]] +name = "obn-fake-app" +version = "0.1.0" +dependencies = [ + "futures-util", + "serde_json", + "tokio", + "tokio-tungstenite", +] + +[[package]] +name = "obn-server" +version = "0.1.0" +dependencies = [ + "axum", + "futures-util", + "rusqlite", + "serde", + "serde_json", + "time", + "tokio", + "tokio-tungstenite", + "tracing", + "tracing-subscriber", +] + +[[package]] +name = "once_cell" +version = "1.21.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50" + +[[package]] +name = "percent-encoding" +version = "2.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220" + +[[package]] +name = "pin-project-lite" +version = "0.2.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd" + +[[package]] +name = "pkg-config" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f6b464fbc74e149a392436b17d523f769e057cb6877f6a5c4618bc6f11800548" + +[[package]] +name = "powerfmt" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4a6394b9e965e73d0a289ee54f589087e2c676aedf60885baf52c76b771e4958" + +[[package]] +name = "ppv-lite86" +version = "0.2.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "85eae3c4ed2f50dcfe72643da4befc30deadb458a9b590d720cde2f2b1e97da9" +dependencies = [ + "zerocopy", +] + +[[package]] +name = "proc-macro2" +version = "1.0.107" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "quote" +version = "1.0.47" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001" +dependencies = [ + "proc-macro2", +] + +[[package]] +name = "r-efi" +version = "5.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "69cdb34c158ceb288df11e18b4bd39de994f6657d83847bdffdbd7f346754b0f" + +[[package]] +name = "rand" +version = "0.9.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b9ef1d0d795eb7d84685bca4f72f3649f064e6641543d3a8c415898726a57b41" +dependencies = [ + "rand_chacha", + "rand_core", +] + +[[package]] +name = "rand_chacha" +version = "0.9.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d3022b5f1df60f26e1ffddd6c66e8aa15de382ae63b3a0c1bfc0e4d3e3f325cb" +dependencies = [ + "ppv-lite86", + "rand_core", +] + +[[package]] +name = "rand_core" +version = "0.9.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "76afc826de14238e6e8c374ddcc1fa19e374fd8dd986b0d2af0d02377261d83c" +dependencies = [ + "getrandom", +] + +[[package]] +name = "regex-automata" +version = "0.4.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ad8553b9b26413251cbf30e620595c7a41b3887f03da04579c0e6b0d6a06b4b2" +dependencies = [ + "aho-corasick", + "memchr", + "regex-syntax", +] + +[[package]] +name = "regex-syntax" +version = "0.8.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4" + +[[package]] +name = "rsqlite-vfs" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c51c9ae4df8a7fba42103df5c621fa3c37eccf3a3c650879e90fc48b11cc192c" +dependencies = [ + "hashbrown 0.16.1", + "thiserror", +] + +[[package]] +name = "rusqlite" +version = "0.40.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "23f2a97da3e3873c73cb2a2e71b35c40ff95e0b1eefa8d72d8499a6928c3b5b3" +dependencies = [ + "bitflags", + "fallible-iterator", + "fallible-streaming-iterator", + "hashlink", + "libsqlite3-sys", + "smallvec", + "sqlite-wasm-rs", +] + +[[package]] +name = "rustversion" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f" + +[[package]] +name = "ryu" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f" + +[[package]] +name = "serde" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba" +dependencies = [ + "serde_core", + "serde_derive", +] + +[[package]] +name = "serde_core" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48" +dependencies = [ + "serde_derive", +] + +[[package]] +name = "serde_derive" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.9", +] + +[[package]] +name = "serde_json" +version = "1.0.154" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e7e9cc8b1b85264074fbcc02a88680c4096b1e47df8f739dceb03bf482f04bd6" +dependencies = [ + "itoa", + "memchr", + "serde", + "serde_core", + "zmij", +] + +[[package]] +name = "serde_path_to_error" +version = "0.1.20" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "10a9ff822e371bb5403e391ecd83e182e0e77ba7f6fe0160b795797109d1b457" +dependencies = [ + "itoa", + "serde", + "serde_core", +] + +[[package]] +name = "serde_urlencoded" +version = "0.7.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d3491c14715ca2294c4d6a88f15e84739788c1d030eed8c110436aafdaa2f3fd" +dependencies = [ + "form_urlencoded", + "itoa", + "ryu", + "serde", +] + +[[package]] +name = "sha1" +version = "0.10.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a978451301f4db1d02937a4ab3ccce137717b81826e79b7d49ffe3244a13c3b8" +dependencies = [ + "cfg-if", + "cpufeatures", + "digest", +] + +[[package]] +name = "sharded-slab" +version = "0.1.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f40ca3c46823713e0d4209592e8d6e826aa57e928f09752619fc696c499637f6" +dependencies = [ + "lazy_static", +] + +[[package]] +name = "shlex" +version = "2.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba" + +[[package]] +name = "signal-hook-registry" +version = "1.4.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c4db69cba1110affc0e9f7bcd48bbf87b3f4fc7c61fc9155afd4c469eb3d6c1b" +dependencies = [ + "errno", + "libc", +] + +[[package]] +name = "slab" +version = "0.4.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5" + +[[package]] +name = "smallvec" +version = "1.16.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d0d5d4b1981b8bbbb7aed204cae5726d683d5d6ac7e74ec54122ea28f315e7c8" + +[[package]] +name = "socket2" +version = "0.6.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c3d1e2c7f27f8d4cb10542a02c49005dbd6e93095799d6f3be745fae9f8fedd4" +dependencies = [ + "libc", + "windows-sys", +] + +[[package]] +name = "sqlite-wasm-rs" +version = "0.5.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dc3efc0da82635d7e1ced0053bbbfa8c7ab9645d0bf36ceb4f7127bb85315d75" +dependencies = [ + "cc", + "js-sys", + "rsqlite-vfs", + "wasm-bindgen", +] + +[[package]] +name = "syn" +version = "2.0.119" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "syn" +version = "3.0.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d78c8dee4c7bf0e14673097256fed6142ce9d3b85a408189d07482442145823b" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "sync_wrapper" +version = "1.0.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0bf256ce5efdfa370213c1dabab5935a12e49f2c58d15e9eac2870d3b4f27263" + +[[package]] +name = "thiserror" +version = "2.0.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "09e52cb86a36cede5cb101bf8908837b3e4c6e5e59fe7fd85c23fb56200d189e" +dependencies = [ + "thiserror-impl", +] + +[[package]] +name = "thiserror-impl" +version = "2.0.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fe5197923287db20a58125f0bc85c062f7f2c892de97b18c356f9efb14b28524" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.9", +] + +[[package]] +name = "thread_local" +version = "1.1.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1ad99c4c6d32803332c548b1af0540b357b3f5fc0be8f6c6bfe8b2e6ae784070" +dependencies = [ + "cfg-if", +] + +[[package]] +name = "time" +version = "0.3.55" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cdb87b95ec50ddfa440816d227a17b2ccbdda963a316a727fda0fc4334f7d134" +dependencies = [ + "deranged", + "num-conv", + "powerfmt", + "serde_core", + "time-core", +] + +[[package]] +name = "time-core" +version = "0.1.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9e1c906769ad99c88eaa54e728060edef082f8e358ff32030cb7c7d315e81109" + +[[package]] +name = "tokio" +version = "1.54.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b52fd3255258d26fac7264ab5a76b53c13367136dc011d3d6ad4f8ed070396a3" +dependencies = [ + "bytes", + "libc", + "mio", + "pin-project-lite", + "signal-hook-registry", + "socket2", + "tokio-macros", + "windows-sys", +] + +[[package]] +name = "tokio-macros" +version = "2.7.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "78773a2a397f451582ce068015985c33193cf6dea8b74d2a639fe457b2f07b0e" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.9", +] + +[[package]] +name = "tokio-tungstenite" +version = "0.29.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8f72a05e828585856dacd553fba484c242c46e391fb0e58917c942ee9202915c" +dependencies = [ + "futures-util", + "log", + "tokio", + "tungstenite", +] + +[[package]] +name = "tower" +version = "0.5.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ebe5ef63511595f1344e2d5cfa636d973292adc0eec1f0ad45fae9f0851ab1d4" +dependencies = [ + "futures-core", + "futures-util", + "pin-project-lite", + "sync_wrapper", + "tokio", + "tower-layer", + "tower-service", + "tracing", +] + +[[package]] +name = "tower-layer" +version = "0.3.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "121c2a6cda46980bb0fcd1647ffaf6cd3fc79a013de288782836f6df9c48780e" + +[[package]] +name = "tower-service" +version = "0.3.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8df9b6e13f2d32c91b9bd719c00d1958837bc7dec474d94952798cc8e69eeec3" + +[[package]] +name = "tracing" +version = "0.1.44" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100" +dependencies = [ + "log", + "pin-project-lite", + "tracing-attributes", + "tracing-core", +] + +[[package]] +name = "tracing-attributes" +version = "0.1.31" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7490cfa5ec963746568740651ac6781f701c9c5ea257c58e057f3ba8cf69e8da" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "tracing-core" +version = "0.1.36" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "db97caf9d906fbde555dd62fa95ddba9eecfd14cb388e4f491a66d74cd5fb79a" +dependencies = [ + "once_cell", + "valuable", +] + +[[package]] +name = "tracing-log" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ee855f1f400bd0e5c02d150ae5de3840039a3f54b025156404e34c23c03f47c3" +dependencies = [ + "log", + "once_cell", + "tracing-core", +] + +[[package]] +name = "tracing-subscriber" +version = "0.3.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cb7f578e5945fb242538965c2d0b04418d38ec25c79d160cd279bf0731c8d319" +dependencies = [ + "matchers", + "nu-ansi-term", + "once_cell", + "regex-automata", + "sharded-slab", + "smallvec", + "thread_local", + "tracing", + "tracing-core", + "tracing-log", +] + +[[package]] +name = "tungstenite" +version = "0.29.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6c01152af293afb9c7c2a57e4b559c5620b421f6d133261c60dd2d0cdb38e6b8" +dependencies = [ + "bytes", + "data-encoding", + "http", + "httparse", + "log", + "rand", + "sha1", + "thiserror", +] + +[[package]] +name = "typenum" +version = "1.20.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20" + +[[package]] +name = "unicode-ident" +version = "1.0.27" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563" + +[[package]] +name = "valuable" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ba73ea9cf16a25df0c8caa16c51acb937d5712a8429db78a3ee29d5dcacd3a65" + +[[package]] +name = "vcpkg" +version = "0.2.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "accd4ea62f7bb7a82fe23066fb0957d48ef677f6eeb8215f372f52e48bb32426" + +[[package]] +name = "version_check" +version = "0.9.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a" + +[[package]] +name = "wasi" +version = "0.11.1+wasi-snapshot-preview1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b" + +[[package]] +name = "wasip2" +version = "1.0.4+wasi-0.2.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b67efb37e106e55ce722a510d6b5f9c17f083e5fc79afc2badeb12cc313d9487" +dependencies = [ + "wit-bindgen", +] + +[[package]] +name = "wasm-bindgen" +version = "0.2.130" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a0181c14ddd6c7b8b0b0132a5f1ea2f32be0d893cd3ea97b6e3b28886b8a3d1c" +dependencies = [ + "cfg-if", + "rustversion", + "wasm-bindgen-macro", + "wasm-bindgen-shared", +] + +[[package]] +name = "wasm-bindgen-macro" +version = "0.2.130" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6e931a02a39abdbf66966fc35902b5ed58344750a70885bed4ebb3d8eaf28ed9" +dependencies = [ + "quote", + "wasm-bindgen-macro-support", +] + +[[package]] +name = "wasm-bindgen-macro-support" +version = "0.2.130" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2ca4b54280e455bd831e33a6b8e734baf432fe63fbc35c42ac14ce67a043a53a" +dependencies = [ + "bumpalo", + "proc-macro2", + "quote", + "syn 3.0.9", + "wasm-bindgen-shared", +] + +[[package]] +name = "wasm-bindgen-shared" +version = "0.2.130" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3b1f9c3798725016c6ee5f2f57869ec0831e8bbc0ab0310a86e787e97f41389e" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "windows-link" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5" + +[[package]] +name = "windows-sys" +version = "0.61.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc" +dependencies = [ + "windows-link", +] + +[[package]] +name = "wit-bindgen" +version = "0.57.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1ebf944e87a7c253233ad6766e082e3cd714b5d03812acc24c318f549614536e" + +[[package]] +name = "zerocopy" +version = "0.8.63" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e5fe1f8f1b06191a00962174c61aa5005e0bb391a6d80d07e24d115c01a92ed8" +dependencies = [ + "zerocopy-derive", +] + +[[package]] +name = "zerocopy-derive" +version = "0.8.63" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "863ad3ac83293fb4d740aedbfdc9240dd8d1a50c1099acd76ce80ce7c7230c7f" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "zmij" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b" diff --git a/Cargo.toml b/Cargo.toml new file mode 100644 index 0000000..4af9a15 --- /dev/null +++ b/Cargo.toml @@ -0,0 +1,20 @@ +[workspace] +resolver = "2" +members = ["crates/server", "crates/fake-app"] + +[workspace.package] +version = "0.1.0" +edition = "2021" +license = "AGPL-3.0-or-later" +rust-version = "1.87" + +[workspace.lints.rust] +unsafe_code = "forbid" + +[workspace.lints.clippy] +all = { level = "warn", priority = -1 } + +[profile.release] +lto = "thin" +codegen-units = 1 +strip = true diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..29b48a2 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,48 @@ +# syntax=docker/dockerfile:1.7 +# +# OpenBikeNet server image: the Rust server, the bundled routes and nothing else. + +# --- Build ------------------------------------------------------------------- +FROM rust:1-slim-bookworm@sha256:ed2c95ca377d6571b124b05e75e01207973ded639dce7d5542eb7bcd797e32aa AS builder +WORKDIR /build + +COPY Cargo.toml Cargo.lock rustfmt.toml ./ +COPY crates ./crates + +RUN --mount=type=cache,target=/usr/local/cargo/registry \ + --mount=type=cache,target=/build/target \ + cargo build --release --bin obn-server \ + && cp target/release/obn-server /usr/local/bin/obn-server + +# --- Runtime ----------------------------------------------------------------- +FROM debian:bookworm-slim@sha256:99c0b25c46d0214d5a2091092e7908907dcaecd6a962cde0ac700acee222b6f3 AS runtime + +# Which build this is (git commit and date), passed by `make up` / `make update` and CI. +ARG OBN_BUILD_SHA=dev +ARG OBN_BUILD_DATE= + +RUN groupadd --system --gid 10001 obn \ + && useradd --system --uid 10001 --gid obn --no-create-home --shell /usr/sbin/nologin obn + +COPY --from=builder /usr/local/bin/obn-server /usr/local/bin/obn-server +# The routes come from the pinned protocol submodule, so they are baked into the image. +COPY protocol/routes /app/routes + +ENV OBN_BIND=0.0.0.0:8080 \ + OBN_ROUTES_DIR=/app/routes \ + OBN_DB=/app/data/obn.sqlite \ + OBN_BUILD_SHA=${OBN_BUILD_SHA} \ + OBN_BUILD_DATE=${OBN_BUILD_DATE} \ + RUST_LOG=info + +# The usage statistics (SQLite) live here (a volume in docker-compose.yml); owned by the server's user. +RUN mkdir -p /app/data && chown obn:obn /app/data + +USER obn +WORKDIR /app +EXPOSE 8080 + +HEALTHCHECK --interval=15s --timeout=3s --start-period=10s --retries=3 \ + CMD ["obn-server", "healthcheck"] + +ENTRYPOINT ["obn-server"] diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..980342c --- /dev/null +++ b/Makefile @@ -0,0 +1,139 @@ +# OpenBikeNet server — common tasks. Run `make` to see all targets. +# +# Rust is optional on the host: if `cargo` is missing, the targets run it in +# throwaway Docker containers instead. + +SHELL := /bin/bash +.DEFAULT_GOAL := help + +COMPOSE ?= docker compose +RUST_IMAGE ?= rust:1-bookworm +HEALTH_TIMEOUT ?= 90 + +# Build number shown in /internal/metrics (compose passes these as build args). +export OBN_BUILD_SHA ?= $(shell git rev-parse --short HEAD 2>/dev/null || echo dev) +export OBN_BUILD_DATE ?= $(shell date -u +%Y-%m-%dT%H:%MZ) + +# Host port, as in .env (default 8090). +PORT = $$(grep -E '^OBN_HTTP_PORT=' .env 2>/dev/null | cut -d= -f2 | grep . || echo 8090) + +ifneq ($(shell command -v cargo 2>/dev/null),) + CARGO := cargo +else + CARGO := docker run --rm -t --network host -v "$(CURDIR)":/src -w /src -v obn-cargo-registry:/usr/local/cargo/registry -v obn-cargo-target:/src/target $(RUST_IMAGE) sh -c 'rustup component add clippy rustfmt >/dev/null 2>&1; cargo "$$@"' cargo +endif + +.PHONY: help +help: ## Show this help + @awk 'BEGIN {FS = ":.*##"; printf "\nUsage: make \033[36m\033[0m\n"} \ + /^[a-zA-Z0-9_-]+:.*?##/ { printf " \033[36m%-14s\033[0m %s\n", $$1, $$2 } \ + /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) }' $(MAKEFILE_LIST) + +##@ Run + +.PHONY: setup +setup: ## Create .env from .env.example, or add settings that are new there + @if [ -f .env ]; then sh tools/env-sync.sh .env.example .env; \ + else cp .env.example .env && echo "Created .env — adjust it if needed."; fi + +.PHONY: up +up: setup ## Build and start in the background, then wait until healthy + $(COMPOSE) up -d --build --remove-orphans + @$(MAKE) --no-print-directory health + @echo "OpenBikeNet is running: http://localhost:$(PORT)" + +.PHONY: down +down: guard ## Stop and remove the containers (asks first if riders are on; FORCE=1 skips) + $(COMPOSE) down + +.PHONY: restart +restart: guard ## Restart the containers without rebuilding (asks first if riders are on; FORCE=1 skips) + $(COMPOSE) restart + +.PHONY: logs +logs: ## Follow the logs + $(COMPOSE) logs -f --tail=200 + +.PHONY: guard +guard: # Ask before dropping riders: used by update, restart and down (FORCE=1 skips it) + @if [ -n "$(FORCE)" ]; then exit 0; fi; \ + out=$$($(COMPOSE) exec -T server obn-server riders 2>/dev/null) || { echo "No running server to check for riders — continuing."; exit 0; }; \ + n=$$(printf '%s\n' "$$out" | head -1); \ + case "$$n" in ''|*[!0-9]*) echo "Could not read the rider count — continuing."; exit 0;; esac; \ + [ "$$n" -gt 0 ] || exit 0; \ + where=$$(printf '%s\n' "$$out" | tail -n +2 | awk -F'\t' '{ printf "%s%s %s", (NR > 1 ? ", " : ""), $$1, $$2 }'); \ + napps=$$(printf '%s\n' "$$out" | tail -n +2 | grep -c .); \ + if [ "$$n" -eq 1 ]; then who="1 rider"; verb=is; else who="$$n riders"; verb=are; fi; \ + if [ "$$napps" -eq 1 ]; then from="1 app"; else from="$$napps apps"; fi; \ + echo "$$who from $$from $$verb on the server ($$where)."; \ + echo "This restarts it and drops them."; \ + if [ ! -t 0 ]; then echo "No terminal to ask on: run with FORCE=1 to go ahead anyway."; exit 1; fi; \ + read -r -p "Go ahead anyway? [y/N] " answer; \ + case "$$answer" in y|Y|yes|YES) ;; *) echo "Aborted, nothing changed."; exit 1;; esac + +.PHONY: ps +ps: ## Show container status + $(COMPOSE) ps + +.PHONY: health +health: ## Wait until the server reports healthy + @echo -n "Waiting for the server to become healthy"; \ + for i in $$(seq 1 $(HEALTH_TIMEOUT)); do \ + if $(COMPOSE) exec -T server obn-server healthcheck >/dev/null 2>&1; then echo " ok"; exit 0; fi; \ + echo -n "."; sleep 1; \ + done; \ + echo " timed out"; $(COMPOSE) logs --tail=50 server; exit 1 + +##@ Deploy + +.PHONY: update +update: setup guard ## Pull, rebuild and restart (asks first if riders are on; FORCE=1 skips) + @if [ -n "$$(git status --porcelain --untracked-files=no)" ]; then \ + echo "Local changes found — commit or stash them before updating."; exit 1; fi + git pull --ff-only + git submodule update --init + @$(MAKE) --no-print-directory setup + $(COMPOSE) build --pull + $(COMPOSE) up -d --remove-orphans + @$(MAKE) --no-print-directory health + docker image prune -f >/dev/null + @echo "Updated to $$(git rev-parse --short HEAD)." + +.PHONY: build +build: ## Build the Docker image without starting it + $(COMPOSE) build --pull + +##@ Develop + +.PHONY: dev +dev: ## Run the server locally with cargo on http://localhost:8090 (reads .env.dev) + set -a && { [ ! -f .env.dev ] || . ./.env.dev; } && set +a && \ + OBN_BIND=127.0.0.1:8090 RUST_LOG=$${RUST_LOG:-info,obn_server=debug} cargo run -p obn-server + +.PHONY: fake +fake: ## Start fake riders against the local server (pass ARGS="--riders 3") + $(CARGO) run -p obn-fake-app -- --url ws://localhost:$(PORT)/v0 $(ARGS) + +.PHONY: test +test: ## Run the Rust tests (unit and end-to-end) + $(CARGO) test --workspace + +.PHONY: lint +lint: ## rustfmt check and clippy with warnings as errors + $(CARGO) fmt --all -- --check + $(CARGO) clippy --workspace --all-targets -- -D warnings + +.PHONY: fmt +fmt: ## Format the Rust code + $(CARGO) fmt --all + +.PHONY: check +check: lint test ## Everything CI runs + +.PHONY: lock +lock: ## Create or refresh Cargo.lock (commit it afterwards) + $(CARGO) generate-lockfile + +.PHONY: clean +clean: ## Remove build output + rm -rf target diff --git a/README.md b/README.md index 9667d27..c789462 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,116 @@ # OpenBikeNet Server -**Status: not started. There is no code here yet.** +**Status: early draft, implements protocol v0.** -This will be the reference server for the [OpenBikeNet protocol](https://github.com/OpenBikeNet/protocol): +This is the reference server for the [OpenBikeNet protocol](https://github.com/OpenBikeNet/protocol): a shared, neutral server that lets riders of different indoor cycling apps see each other on the same route. See the [organisation profile](https://github.com/OpenBikeNet) for the overall goal. -The protocol is designed first, in the [protocol repository](https://github.com/OpenBikeNet/protocol). -Code here follows once the first draft of the specification is agreed. Ideas and feedback are -welcome in the protocol repository's Discussions. +The protocol is designed in the [protocol repository](https://github.com/OpenBikeNet/protocol). +Ideas and feedback are welcome in its Discussions. -## Planned +## Running it + +With Docker (nothing else needed): + +```sh +git clone --recurse-submodules https://github.com/OpenBikeNet/server +cd server +make up +curl -s localhost:8090/v0/stats # {"apps":[]} +``` + +`make up` creates `.env`, builds the image and waits until the server is healthy. It listens on +port 8090 of this machine only, so it can run next to other servers. Run `make` to see all targets: + +| Target | What it does | +| --- | --- | +| `make up` | Build and start, then wait until healthy | +| `make down`, `make restart` | Stop or restart (asks first if riders are on) | +| `make logs`, `make ps`, `make health` | Look at the running server | +| `make update` | `git pull`, update the submodule, rebuild, restart | +| `make dev` | Run with cargo on `127.0.0.1:8090` (reads `.env.dev`) | +| `make fake ARGS="--riders 3"` | Start fake riders against the server | +| `make check` | What CI runs: format, clippy, tests | + +Settings are in `.env` (see `.env.example`): the host address and port, `OBN_TRUST_PROXY` and +`RUST_LOG`. `make update` adds settings that are new in `.env.example` and keeps your values. +If riders are on the server, `make update`, `make restart` and `make down` ask first. `FORCE=1` +skips the question. The usage statistics live in the `data` volume. + +Without Docker, run it with cargo: + +```sh +cargo run -p obn-server +curl -s localhost:8080/v0/stats # {"apps":[]} +``` + +The server reads these environment variables: + +| Variable | Default | Meaning | +| --- | --- | --- | +| `OBN_BIND` | `0.0.0.0:8080` | Address to listen on | +| `OBN_ROUTES_DIR` | `protocol/routes` | Directory with the route JSON files | +| `OBN_DB` | `obn.sqlite` | SQLite file for the per-app statistics | +| `OBN_TRUST_PROXY` | off | Set to `1` (or `true`) to take the client IP from `X-Forwarded-For` (behind a reverse proxy) | + +`RUST_LOG` sets the log level (default `info`). To see riders move, start a fake app that +sends three bots around the velodrome: + +```sh +make fake ARGS="--riders 3" +``` + +## Monitoring + +`GET /internal/metrics` returns Prometheus text. It holds only aggregate counts per app ID +(already public via `/v0/stats`), never rider names, rider values or IPs. The bundled Caddy +answers 404 on `/internal/*`, so it is not public. `GET /healthz` returns `ok`. + +| Series | Type | Meaning | +| --- | --- | --- | +| `obn_connections{app}` | gauge | Connections per live app | +| `obn_riders{app}` | gauge | Riders per live app | +| `obn_connections_total` | counter | WebSocket connections accepted | +| `obn_rider_updates_total` | counter | Accepted update entries | +| `obn_errors_total{code}` | counter | Errors sent, one series per error code | +| `obn_queue_full_drops_total` | counter | Connections dropped because they read too slowly | +| `obn_connections_rejected_total{reason="per_ip_limit"}` | counter | Connections refused by the per-IP limit | +| `obn_build_info{version,sha}` | gauge | Always 1; says which build runs | + +The server joins the Docker network `openbikenet-metrics` with the alias `obn-server`. Put your +Prometheus on that network and scrape it there: + +```yaml +scrape_configs: + - job_name: openbikenet + metrics_path: /internal/metrics + static_configs: + - targets: ["obn-server:8080"] +``` + +## HTTPS + +Apps in browsers need `wss://`. There are two ways: + +- **Bundled Caddy.** Point a DNS record at the server, then set `COMPOSE_PROFILES=tls`, + `OBN_DOMAIN=net.example.org` and `OBN_TRUST_PROXY=1` in `.env` and run `make up`. Caddy gets + and renews the certificate itself. +- **Your own reverse proxy.** Proxy to port 8090, allow WebSockets, block `/internal/*` + and set `OBN_TRUST_PROXY=1`. In Caddy: + + ``` + net.example.org { + handle /internal/* { + respond 404 + } + handle { + reverse_proxy localhost:8090 + } + } + ``` + +## Goals - **Shared presence first:** apps report their riders' positions on shared routes and receive the positions of riders from other apps. Each app keeps its own physics. diff --git a/crates/fake-app/Cargo.toml b/crates/fake-app/Cargo.toml new file mode 100644 index 0000000..bf0484f --- /dev/null +++ b/crates/fake-app/Cargo.toml @@ -0,0 +1,15 @@ +[package] +name = "obn-fake-app" +version.workspace = true +edition.workspace = true +license.workspace = true +rust-version.workspace = true + +[lints] +workspace = true + +[dependencies] +serde_json = "1" +futures-util = { version = "0.3", default-features = false, features = ["sink", "std"] } +tokio = { version = "1", features = ["macros", "rt-multi-thread", "time", "signal"] } +tokio-tungstenite = "0.29" diff --git a/crates/fake-app/src/main.rs b/crates/fake-app/src/main.rs new file mode 100644 index 0000000..0015ffd --- /dev/null +++ b/crates/fake-app/src/main.rs @@ -0,0 +1,207 @@ +//! A fake indoor cycling app for trying out an OpenBikeNet server. It speaks the protocol with plain +//! JSON and does not depend on `obn-server`, like any other app would. +//! +//! ```text +//! obn-fake-app [--url ws://127.0.0.1:8080/v0] [--route velodrome-250] [--length 250] +//! [--riders 3] [--speed 11.0] [--app fake-app] +//! ``` + +use std::process::ExitCode; +use std::time::Duration; + +use futures_util::{SinkExt, StreamExt}; +use serde_json::{json, Value}; +use tokio_tungstenite::tungstenite::Message; + +struct Args { + url: String, + route: String, + length: f64, + riders: u32, + speed: f64, + app: String, +} + +const USAGE: &str = + "usage: obn-fake-app [--url URL] [--route ID] [--length METRES] [--riders N] [--speed M/S] [--app ID]"; + +fn parse_args(args: impl IntoIterator) -> Result { + let mut a = Args { + url: "ws://127.0.0.1:8080/v0".into(), + route: "velodrome-250".into(), + length: 250.0, + riders: 3, + speed: 11.0, + app: "fake-app".into(), + }; + let mut it = args.into_iter(); + while let Some(flag) = it.next() { + if flag == "--help" || flag == "-h" { + return Err(USAGE.into()); + } + let value = it.next().ok_or_else(|| format!("{flag} needs a value\n{USAGE}"))?; + let bad = |what: &str| format!("{flag}: {value:?} is not {what}"); + match flag.as_str() { + "--url" => a.url = value, + "--route" => a.route = value, + "--app" => a.app = value, + "--length" => a.length = value.parse().map_err(|_| bad("a number"))?, + "--speed" => a.speed = value.parse().map_err(|_| bad("a number"))?, + "--riders" => a.riders = value.parse().map_err(|_| bad("a whole number"))?, + _ => return Err(format!("unknown option {flag}\n{USAGE}")), + } + } + if a.length <= 0.0 { + return Err("--length must be positive".into()); + } + Ok(a) +} + +/// Moves a rider forward by `speed * dt` metres, rolling over into the next lap at `length`. +fn advance(lap: u32, distance: f64, speed: f64, dt: f64, length: f64) -> (u32, f64) { + let d = distance + speed * dt; + if d >= length { + let laps = (d / length).floor(); + (lap + laps as u32, d - laps * length) + } else { + (lap, d) + } +} + +struct Bot { + id: String, + name: String, + lap: u32, + distance: f64, +} + +#[tokio::main] +async fn main() -> ExitCode { + let args = match parse_args(std::env::args().skip(1)) { + Ok(a) => a, + Err(e) => { + eprintln!("{e}"); + return ExitCode::FAILURE; + } + }; + match run(args).await { + Ok(()) => ExitCode::SUCCESS, + Err(e) => { + eprintln!("obn-fake-app: {e}"); + ExitCode::FAILURE + } + } +} + +async fn run(args: Args) -> Result<(), String> { + let (ws, _) = tokio_tungstenite::connect_async(args.url.as_str()) + .await + .map_err(|e| format!("cannot connect to {}: {e}", args.url))?; + let (mut tx, mut rx) = ws.split(); + let send = |v: Value| Message::text(v.to_string()); + + tx.send(send( + json!({"type":"hello","app":{"id":args.app,"version":env!("CARGO_PKG_VERSION")}}), + )) + .await + .map_err(|e| e.to_string())?; + tx.send(send(json!({"type":"subscribe","route":args.route,"room":"public"}))) + .await + .map_err(|e| e.to_string())?; + + let mut bots: Vec = (0..args.riders) + .map(|i| Bot { + id: format!("bot-{}", i + 1), + name: format!("Bot {}", i + 1), + lap: 0, + distance: args.length * f64::from(i) / f64::from(args.riders), + }) + .collect(); + for b in &bots { + let join = json!({ + "type":"join","rider":b.id,"route":args.route,"room":"public","name":b.name, + "lap":b.lap,"distance":b.distance,"speed":args.speed, + }); + tx.send(send(join)).await.map_err(|e| e.to_string())?; + } + + let mut tick = tokio::time::interval(Duration::from_secs(1)); + tick.tick().await; + loop { + tokio::select! { + _ = tick.tick() => { + let riders: Vec = bots + .iter_mut() + .map(|b| { + (b.lap, b.distance) = advance(b.lap, b.distance, args.speed, 1.0, args.length); + json!({"rider":b.id,"lap":b.lap,"distance":b.distance,"speed":args.speed}) + }) + .collect(); + if riders.is_empty() { + continue; + } + tx.send(send(json!({"type":"update","riders":riders}))).await.map_err(|e| e.to_string())?; + } + _ = tokio::signal::ctrl_c() => { + for b in &bots { + // Best effort: the server also expires riders on its own. + let _ = tx.send(send(json!({"type":"leave","rider":b.id}))).await; + } + let _ = tx.close().await; + println!("sent leave for {} riders, bye", bots.len()); + return Ok(()); + } + msg = rx.next() => match msg { + None => return Err("connection closed".into()), + Some(Err(e)) => return Err(format!("connection error: {e}")), + Some(Ok(Message::Text(t))) => report(t.as_str()), + Some(Ok(Message::Close(f))) => return Err(format!("server closed the connection: {f:?}")), + Some(Ok(_)) => {} + }, + } + } +} + +fn report(text: &str) { + let Ok(v) = serde_json::from_str::(text) else { + return; + }; + match v["type"].as_str() { + Some("joined") => { + let r = &v["rider"]; + println!( + "joined {:?} of {} as {}", + r["name"].as_str().unwrap_or("?"), + r["app"].as_str().unwrap_or("?"), + r["id"].as_str().unwrap_or("?") + ); + } + Some("left") => println!( + "left {} {}", + v["id"].as_str().unwrap_or("?"), + v["reason"].as_str().unwrap_or("?") + ), + Some("error") => println!( + "error {}: {}", + v["code"].as_str().unwrap_or("?"), + v["message"].as_str().unwrap_or("?") + ), + _ => {} + } +} + +#[cfg(test)] +mod tests { + use super::advance; + + #[test] + fn moves_forward_within_a_lap() { + assert_eq!(advance(0, 100.0, 10.0, 1.0, 250.0), (0, 110.0)); + } + + #[test] + fn wraps_into_the_next_lap() { + assert_eq!(advance(0, 245.0, 10.0, 1.0, 250.0), (1, 5.0)); + assert_eq!(advance(2, 249.0, 10.0, 1.0, 250.0), (3, 9.0)); + } +} diff --git a/crates/server/Cargo.toml b/crates/server/Cargo.toml new file mode 100644 index 0000000..f96e848 --- /dev/null +++ b/crates/server/Cargo.toml @@ -0,0 +1,32 @@ +[package] +name = "obn-server" +version.workspace = true +edition.workspace = true +license.workspace = true +rust-version.workspace = true + +[lints] +workspace = true + +[lib] +name = "obn_server" +path = "src/lib.rs" + +[[bin]] +name = "obn-server" +path = "src/main.rs" + +[dependencies] +serde = { version = "1", features = ["derive"] } +serde_json = "1" +rusqlite = { version = "0.40", features = ["bundled"] } +time = "0.3" +axum = { version = "0.8", features = ["ws"] } +futures-util = { version = "0.3", default-features = false, features = ["sink", "std"] } +tokio = { version = "1", features = ["macros", "rt-multi-thread", "net", "time", "sync", "signal"] } +tracing = "0.1" +tracing-subscriber = { version = "0.3", features = ["env-filter", "fmt"] } + +[dev-dependencies] +tokio-tungstenite = "0.29" +tokio = { version = "1", features = ["io-util"] } diff --git a/crates/server/src/config.rs b/crates/server/src/config.rs new file mode 100644 index 0000000..dbfd9a3 --- /dev/null +++ b/crates/server/src/config.rs @@ -0,0 +1,75 @@ +//! Server configuration, read from the environment. + +use std::net::SocketAddr; +use std::path::PathBuf; +use std::time::Duration; + +use crate::protocol::Limits; + +#[derive(Debug, Clone)] +pub struct Config { + pub bind: SocketAddr, + pub routes_dir: PathBuf, + pub db_path: PathBuf, + /// Take the client IP from the `X-Forwarded-For` header (set by a trusted reverse proxy). + pub trust_proxy: bool, + pub hello_timeout: Duration, + pub ping_interval: Duration, + pub pong_timeout: Duration, + pub max_connections_per_ip: u32, + pub limits: Limits, +} + +impl Default for Config { + fn default() -> Self { + Config { + bind: SocketAddr::from(([0, 0, 0, 0], 8080)), + routes_dir: PathBuf::from("protocol/routes"), + db_path: PathBuf::from("obn.sqlite"), + trust_proxy: false, + hello_timeout: Duration::from_secs(10), + ping_interval: Duration::from_secs(15), + pong_timeout: Duration::from_secs(30), + max_connections_per_ip: 10, + limits: Limits::default(), + } + } +} + +impl Config { + /// `OBN_BIND`, `OBN_ROUTES_DIR`, `OBN_DB` and `OBN_TRUST_PROXY=1` (or `true`); everything else is fixed. + pub fn from_env() -> Result { + let mut c = Config::default(); + if let Ok(v) = std::env::var("OBN_BIND") { + c.bind = v.parse().map_err(|e| format!("OBN_BIND {v:?}: {e}"))?; + } + if let Ok(v) = std::env::var("OBN_ROUTES_DIR") { + c.routes_dir = PathBuf::from(v); + } + if let Ok(v) = std::env::var("OBN_DB") { + c.db_path = PathBuf::from(v); + } + c.trust_proxy = std::env::var("OBN_TRUST_PROXY").is_ok_and(|v| is_on(&v)); + Ok(c) + } +} + +/// `1` or `true` switch a flag on; anything else, including an empty value, leaves it off. +fn is_on(value: &str) -> bool { + matches!(value.trim(), "1" | "true") +} + +#[cfg(test)] +mod tests { + use super::is_on; + + #[test] + fn flags_accept_one_and_true() { + assert!(is_on("1")); + assert!(is_on("true")); + assert!(!is_on("0")); + assert!(!is_on("false")); + assert!(!is_on("")); + assert!(!is_on("yes")); + } +} diff --git a/crates/server/src/healthcheck.rs b/crates/server/src/healthcheck.rs new file mode 100644 index 0000000..d225279 --- /dev/null +++ b/crates/server/src/healthcheck.rs @@ -0,0 +1,73 @@ +//! `obn-server healthcheck` — a tiny HTTP probe for Docker's +//! `HEALTHCHECK`, so the runtime image needs no curl or wget. + +use std::io::{Read, Write}; +use std::net::{SocketAddr, TcpStream}; +use std::time::Duration; + +/// Returns `true` if `GET /healthz` on `addr` answers with status 200. +pub fn check(addr: SocketAddr) -> bool { + get(addr, "/healthz").is_some() +} + +/// `GET path` on `addr`; the response body if the status is 200. +pub fn get(addr: SocketAddr, path: &str) -> Option { + let timeout = Duration::from_secs(2); + let mut stream = TcpStream::connect_timeout(&addr, timeout).ok()?; + let _ = stream.set_read_timeout(Some(timeout)); + let _ = stream.set_write_timeout(Some(timeout)); + let request = format!("GET {path} HTTP/1.1\r\nHost: {addr}\r\nConnection: close\r\n\r\n"); + stream.write_all(request.as_bytes()).ok()?; + let mut response = String::new(); + let _ = stream.read_to_string(&mut response); + if !is_ok_status(&response) { + return None; + } + response.split_once("\r\n\r\n").map(|(_, body)| body.to_string()) +} + +/// Parses the status line of a raw HTTP response. +pub fn is_ok_status(response: &str) -> bool { + response.lines().next().and_then(|line| line.split_whitespace().nth(1)) == Some("200") +} + +/// Address to probe: the configured bind address, with an unspecified IP +/// (`0.0.0.0`) replaced by loopback. +pub fn probe_addr(bind: SocketAddr) -> SocketAddr { + if bind.ip().is_unspecified() { + SocketAddr::from(([127, 0, 0, 1], bind.port())) + } else { + bind + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn recognises_ok_responses() { + assert!(is_ok_status("HTTP/1.1 200 OK\r\ncontent-length: 2\r\n\r\nok")); + assert!(is_ok_status("HTTP/1.0 200 OK\r\n\r\n")); + assert!(!is_ok_status("HTTP/1.1 503 Service Unavailable\r\n\r\n")); + assert!(!is_ok_status("")); + } + + #[test] + fn probes_loopback_for_wildcard_binds() { + assert_eq!( + probe_addr("0.0.0.0:8080".parse().unwrap()), + "127.0.0.1:8080".parse().unwrap() + ); + assert_eq!( + probe_addr("10.0.0.5:9000".parse().unwrap()), + "10.0.0.5:9000".parse().unwrap() + ); + } + + #[test] + fn unreachable_servers_are_unhealthy() { + // Port 9 (discard) is essentially never open on loopback in CI. + assert!(!check("127.0.0.1:9".parse().unwrap())); + } +} diff --git a/crates/server/src/lib.rs b/crates/server/src/lib.rs new file mode 100644 index 0000000..3a27771 --- /dev/null +++ b/crates/server/src/lib.rs @@ -0,0 +1,9 @@ +pub mod config; +pub mod healthcheck; +pub mod metrics; +pub mod presence; +pub mod prometheus; +pub mod protocol; +pub mod riders; +pub mod routes; +pub mod ws; diff --git a/crates/server/src/main.rs b/crates/server/src/main.rs new file mode 100644 index 0000000..df900ec --- /dev/null +++ b/crates/server/src/main.rs @@ -0,0 +1,90 @@ +use std::net::SocketAddr; +use std::process::ExitCode; + +use obn_server::config::Config; +use obn_server::metrics::Metrics; +use obn_server::routes::Routes; +use obn_server::ws::{router, spawn_tickers, AppState}; +use obn_server::{healthcheck, riders}; +use tracing_subscriber::EnvFilter; + +#[tokio::main] +async fn main() -> ExitCode { + // Subcommands for the container: `healthcheck` (Docker HEALTHCHECK) and `riders` (Makefile + // guard). They probe this server's own port, so they need no extra tools in the image. + match std::env::args().nth(1).as_deref() { + Some("healthcheck") => return probe(|addr| healthcheck::check(addr).then_some(String::new())), + Some("riders") => { + return probe(|addr| healthcheck::get(addr, "/v0/stats").and_then(|body| riders::summary(&body))) + } + _ => {} + } + tracing_subscriber::fmt() + .with_env_filter(EnvFilter::try_from_default_env().unwrap_or_else(|_| EnvFilter::new("info"))) + .init(); + match run().await { + Ok(()) => ExitCode::SUCCESS, + Err(e) => { + eprintln!("obn-server: {e}"); + ExitCode::FAILURE + } + } +} + +/// Runs a probe against the configured bind address and prints what it returns. +fn probe(f: impl FnOnce(SocketAddr) -> Option) -> ExitCode { + let config = match Config::from_env() { + Ok(config) => config, + Err(e) => { + eprintln!("configuration error: {e}"); + return ExitCode::FAILURE; + } + }; + match f(healthcheck::probe_addr(config.bind)) { + Some(out) => { + print!("{out}"); + ExitCode::SUCCESS + } + None => ExitCode::FAILURE, + } +} + +async fn run() -> Result<(), String> { + let config = Config::from_env()?; + let routes = Routes::load_dir(&config.routes_dir)?; + let metrics = + Metrics::open(&config.db_path).map_err(|e| format!("cannot open {}: {e}", config.db_path.display()))?; + let listener = tokio::net::TcpListener::bind(config.bind) + .await + .map_err(|e| format!("cannot bind {}: {e}", config.bind))?; + let ids: Vec<&str> = routes.ids().collect(); + tracing::info!("listening on {}, routes: {}", config.bind, ids.join(", ")); + let state = AppState::new(config, routes, metrics); + spawn_tickers(state.clone()); + axum::serve( + listener, + router(state).into_make_service_with_connect_info::(), + ) + .with_graceful_shutdown(shutdown()) + .await + .map_err(|e| format!("server error: {e}")) +} + +async fn shutdown() { + let ctrl_c = async { + let _ = tokio::signal::ctrl_c().await; + }; + #[cfg(unix)] + let term = async { + match tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate()) { + Ok(mut s) => { + s.recv().await; + } + Err(_) => std::future::pending::<()>().await, + } + }; + #[cfg(not(unix))] + let term = std::future::pending::<()>(); + tokio::select! { _ = ctrl_c => {}, _ = term => {} } + tracing::info!("shutting down"); +} diff --git a/crates/server/src/metrics.rs b/crates/server/src/metrics.rs new file mode 100644 index 0000000..5bfb326 --- /dev/null +++ b/crates/server/src/metrics.rs @@ -0,0 +1,278 @@ +//! Per-app usage counters in SQLite. This is the only module that writes to disk. It stores app +//! IDs, versions and dates, and rider counts per minute. It never stores names, rider values or +//! IP addresses (spec 10). + +use std::collections::BTreeMap; +use std::path::Path; + +use serde::Serialize; + +use crate::presence::AppCounts; + +/// The statistics served at `GET /v0/stats` (spec 8). +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct Stats { + pub apps: Vec, +} + +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct AppStats { + pub id: String, + pub versions: Vec, + pub connections: u32, + pub riders: u32, + pub first_seen: String, + pub last_seen: String, + pub rider_minutes_30d: u64, +} + +pub struct Metrics { + conn: rusqlite::Connection, +} + +impl Metrics { + pub fn open(path: &Path) -> rusqlite::Result { + Self::init(rusqlite::Connection::open(path)?) + } + + pub fn open_in_memory() -> rusqlite::Result { + Self::init(rusqlite::Connection::open_in_memory()?) + } + + fn init(conn: rusqlite::Connection) -> rusqlite::Result { + conn.execute_batch( + "CREATE TABLE IF NOT EXISTS apps ( + id TEXT PRIMARY KEY, + first_seen TEXT NOT NULL, + last_seen TEXT NOT NULL + ); + CREATE TABLE IF NOT EXISTS versions ( + app TEXT NOT NULL, + version TEXT NOT NULL, + last_day TEXT NOT NULL, + PRIMARY KEY (app, version) + ); + CREATE TABLE IF NOT EXISTS minutes ( + app TEXT NOT NULL, + day TEXT NOT NULL, + minutes INTEGER NOT NULL, + PRIMARY KEY (app, day) + );", + )?; + Ok(Self { conn }) + } + + /// Records a `hello` from `app` running `version` on the UTC day `day` (`YYYY-MM-DD`). + pub fn record_hello(&self, app: &str, version: &str, day: &str) -> rusqlite::Result<()> { + self.conn.execute( + "INSERT INTO apps (id, first_seen, last_seen) VALUES (?1, ?2, ?2) + ON CONFLICT(id) DO UPDATE SET + first_seen = MIN(first_seen, excluded.first_seen), + last_seen = MAX(last_seen, excluded.last_seen)", + rusqlite::params![app, day], + )?; + self.conn.execute( + "INSERT INTO versions (app, version, last_day) VALUES (?1, ?2, ?3) + ON CONFLICT(app, version) DO UPDATE SET last_day = MAX(last_day, excluded.last_day)", + rusqlite::params![app, version, day], + )?; + Ok(()) + } + + /// Adds one minute of the current live state: each app's riders count as rider-minutes on + /// `day`, and apps with open connections have `last_seen` set to `day`. + pub fn add_minute(&self, live: &BTreeMap, day: &str) -> rusqlite::Result<()> { + let tx = self.conn.unchecked_transaction()?; + for (app, counts) in live { + if counts.connections > 0 { + tx.execute( + "INSERT INTO apps (id, first_seen, last_seen) VALUES (?1, ?2, ?2) + ON CONFLICT(id) DO UPDATE SET last_seen = MAX(last_seen, excluded.last_seen)", + rusqlite::params![app, day], + )?; + } + if counts.riders > 0 { + tx.execute( + "INSERT INTO minutes (app, day, minutes) VALUES (?1, ?2, ?3) + ON CONFLICT(app, day) DO UPDATE SET minutes = minutes + excluded.minutes", + rusqlite::params![app, day, counts.riders], + )?; + } + } + tx.commit() + } + + /// The statistics as of the UTC day `today`, with `live` as the current connections and riders. + pub fn stats(&self, live: &BTreeMap, today: &str) -> rusqlite::Result { + // Keyed by app ID, so the output is sorted by ID. + let mut apps: BTreeMap = BTreeMap::new(); + let mut stmt = self.conn.prepare("SELECT id, first_seen, last_seen FROM apps")?; + let rows = stmt.query_map([], |r| Ok((r.get::<_, String>(0)?, r.get(1)?, r.get(2)?)))?; + for row in rows { + let (id, first_seen, last_seen) = row?; + apps.insert(id.clone(), AppStats::new(id, first_seen, last_seen)); + } + + // Live apps that have no row yet are new today. + for id in live.keys() { + apps.entry(id.clone()) + .or_insert_with(|| AppStats::new(id.clone(), today.to_string(), today.to_string())); + } + + let mut stmt = self.conn.prepare( + "SELECT app, version FROM versions + WHERE last_day >= date(?1, '-29 days') + ORDER BY app, version", + )?; + let rows = stmt.query_map([today], |r| Ok((r.get::<_, String>(0)?, r.get::<_, String>(1)?)))?; + for row in rows { + let (app, version) = row?; + if let Some(entry) = apps.get_mut(&app) { + entry.versions.push(version); + } + } + + let mut stmt = self.conn.prepare( + "SELECT app, SUM(minutes) FROM minutes + WHERE day >= date(?1, '-29 days') + GROUP BY app", + )?; + let rows = stmt.query_map([today], |r| Ok((r.get::<_, String>(0)?, r.get::<_, i64>(1)?)))?; + for row in rows { + let (app, minutes) = row?; + if let Some(entry) = apps.get_mut(&app) { + entry.rider_minutes_30d = u64::try_from(minutes).unwrap_or(0); + } + } + + for (id, counts) in live { + if let Some(entry) = apps.get_mut(id) { + entry.connections = counts.connections; + entry.riders = counts.riders; + } + } + + Ok(Stats { + apps: apps.into_values().collect(), + }) + } +} + +/// Today's UTC date as `YYYY-MM-DD`. +pub fn today_utc() -> String { + let d = time::OffsetDateTime::now_utc().date(); + format!("{:04}-{:02}-{:02}", d.year(), u8::from(d.month()), d.day()) +} + +impl AppStats { + fn new(id: String, first_seen: String, last_seen: String) -> Self { + Self { + id, + versions: Vec::new(), + connections: 0, + riders: 0, + first_seen, + last_seen, + rider_minutes_30d: 0, + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn live(app: &str, connections: u32, riders: u32) -> BTreeMap { + BTreeMap::from([(app.to_string(), AppCounts { connections, riders })]) + } + + #[test] + fn stats_matches_spec_example() { + let m = Metrics::open_in_memory().unwrap(); + m.record_hello("openradlr", "0.3.1", "2026-11-20").unwrap(); + m.add_minute(&live("openradlr", 1, 412), "2026-11-20").unwrap(); + m.add_minute(&live("openradlr", 1, 400), "2026-11-21").unwrap(); + let stats = m.stats(&live("openradlr", 1, 4), "2026-11-21").unwrap(); + + let got = serde_json::to_value(&stats).unwrap(); + let want: serde_json::Value = + serde_json::from_str(include_str!("../../../protocol/examples/stats.json")).unwrap(); + assert_eq!(got, want); + } + + #[test] + fn minutes_older_than_30_days_drop_out() { + let m = Metrics::open_in_memory().unwrap(); + m.record_hello("a", "1.0.0", "2026-10-01").unwrap(); + m.add_minute(&live("a", 0, 10), "2026-10-01").unwrap(); + // The window for 2026-11-21 is 2026-10-23 through 2026-11-21 (30 days). + m.add_minute(&live("a", 0, 100), "2026-10-22").unwrap(); + m.add_minute(&live("a", 0, 7), "2026-10-23").unwrap(); + m.add_minute(&live("a", 0, 5), "2026-11-20").unwrap(); + + let stats = m.stats(&live("a", 0, 0), "2026-11-21").unwrap(); + assert_eq!(stats.apps.len(), 1); + assert_eq!(stats.apps[0].rider_minutes_30d, 12); + assert!( + stats.apps[0].versions.is_empty(), + "a version last seen 2026-10-01 is outside the window" + ); + } + + #[test] + fn apps_without_live_connection_show_zero() { + let m = Metrics::open_in_memory().unwrap(); + m.record_hello("a", "1.0.0", "2026-11-20").unwrap(); + m.add_minute(&live("a", 1, 3), "2026-11-20").unwrap(); + m.record_hello("b", "2.0.0", "2026-11-20").unwrap(); + // "c" is live but was never recorded by a hello. + let now = BTreeMap::from([ + ( + "a".to_string(), + AppCounts { + connections: 1, + riders: 3, + }, + ), + ( + "c".to_string(), + AppCounts { + connections: 2, + riders: 7, + }, + ), + ]); + + let stats = m.stats(&now, "2026-11-21").unwrap(); + let ids: Vec<&str> = stats.apps.iter().map(|a| a.id.as_str()).collect(); + assert_eq!(ids, ["a", "b", "c"]); + + let b = &stats.apps[1]; + assert_eq!((b.connections, b.riders), (0, 0)); + assert_eq!(b.versions, ["2.0.0"]); + assert_eq!(b.rider_minutes_30d, 0); + + let c = &stats.apps[2]; + assert_eq!((c.connections, c.riders), (2, 7)); + assert!(c.versions.is_empty()); + } + + #[test] + fn reopen_keeps_data() { + let path = std::env::temp_dir().join(format!("obn-metrics-test-{}.sqlite", std::process::id())); + let _ = std::fs::remove_file(&path); + let now = live("a", 1, 2); + + let before = { + let m = Metrics::open(&path).unwrap(); + m.record_hello("a", "1.0.0", "2026-11-20").unwrap(); + m.add_minute(&now, "2026-11-20").unwrap(); + m.stats(&now, "2026-11-21").unwrap() + }; + let after = Metrics::open(&path).unwrap().stats(&now, "2026-11-21").unwrap(); + + let _ = std::fs::remove_file(&path); + assert_eq!(before, after); + assert_eq!(after.apps[0].rider_minutes_30d, 2); + } +} diff --git a/crates/server/src/presence.rs b/crates/server/src/presence.rs new file mode 100644 index 0000000..0c843d0 --- /dev/null +++ b/crates/server/src/presence.rs @@ -0,0 +1,796 @@ +//! Who is where: connections, their subscriptions and riders. A plain struct without async code or +//! a clock of its own (time is passed in). Every method returns the messages addressed to each +//! connection; the `ws` hub sends them. + +use std::collections::{BTreeMap, BTreeSet}; +use std::time::{Duration, Instant}; + +use crate::protocol::{ + AppInfo, ErrorCode, Join, LeftReason, Limits, ProtoError, RiderState, RiderUpdate, RiderView, ServerMsg, + UpdateEntry, +}; +use crate::routes::Routes; + +pub type ConnId = u64; + +/// One message for one connection. +#[derive(Debug, Clone, PartialEq)] +pub struct Delivery { + pub to: ConnId, + pub msg: ServerMsg, +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +pub struct AppCounts { + pub connections: u32, + pub riders: u32, +} + +type RoomKey = (String, String); + +#[derive(Debug)] +struct Rider { + /// The server ID (`r1`, `r2`, ...), unique across connections. + id: String, + route: String, + room: String, + name: String, + state: RiderState, + /// When the last state was accepted. + last: Instant, +} + +#[derive(Debug)] +struct Conn { + app: AppInfo, + subscriptions: BTreeSet, + /// The riders of this connection, keyed by the app's own rider value. + riders: BTreeMap, +} + +#[derive(Debug)] +pub struct Presence { + routes: Routes, + limits: Limits, + conns: BTreeMap, + /// Subscribers per route+room, in connection order so deliveries are deterministic. + rooms: BTreeMap>, + next_rider: u64, +} + +impl Presence { + pub fn new(routes: Routes, limits: Limits) -> Self { + Presence { + routes, + limits, + conns: BTreeMap::new(), + rooms: BTreeMap::new(), + next_rider: 1, + } + } + + pub fn connect(&mut self, conn: ConnId, app: AppInfo) { + self.conns.insert( + conn, + Conn { + app, + subscriptions: BTreeSet::new(), + riders: BTreeMap::new(), + }, + ); + } + + /// Subscribing again to a route+room already subscribed to is allowed (it does not count + /// against the limit) and returns a fresh snapshot. + pub fn subscribe(&mut self, conn: ConnId, route: &str, room: &str) -> Result, ProtoError> { + self.check_route(route)?; + let key = (route.to_string(), room.to_string()); + let Some(c) = self.conns.get_mut(&conn) else { + debug_assert!(false, "subscribe without connect"); + return Ok(Vec::new()); + }; + if !c.subscriptions.contains(&key) { + if c.subscriptions.len() >= self.limits.max_subscriptions as usize { + return Err(ProtoError::new( + ErrorCode::LimitExceeded, + format!("at most {} subscriptions per connection", self.limits.max_subscriptions), + )); + } + c.subscriptions.insert(key.clone()); + } + self.rooms.entry(key.clone()).or_default().insert(conn); + + let riders = self + .conns + .iter() + .filter(|(id, _)| **id != conn) + .flat_map(|(_, other)| { + other + .riders + .values() + .filter(|r| r.route == key.0 && r.room == key.1) + .map(|r| view(&other.app, r)) + }) + .collect(); + Ok(vec![Delivery { + to: conn, + msg: ServerMsg::Snapshot { + route: key.0, + room: key.1, + riders, + }, + }]) + } + + /// Unsubscribing from a route+room that is not subscribed to does nothing. + pub fn unsubscribe(&mut self, conn: ConnId, route: &str, room: &str) { + let key = (route.to_string(), room.to_string()); + if let Some(c) = self.conns.get_mut(&conn) { + c.subscriptions.remove(&key); + } + self.remove_subscriber(&key, conn); + } + + pub fn join(&mut self, conn: ConnId, join: Join, now: Instant) -> Result, ProtoError> { + let length = self.check_route(&join.route)?.length; + let rider_name = || Some(join.rider.clone()); + check_distance(length, join.state.distance, &join.rider)?; + let Some(c) = self.conns.get_mut(&conn) else { + debug_assert!(false, "join without connect"); + return Ok(Vec::new()); + }; + if c.riders.contains_key(&join.rider) { + return Err(ProtoError::new(ErrorCode::RiderExists, "rider has already joined").with_rider(rider_name())); + } + if c.riders.len() >= self.limits.max_riders as usize { + return Err(ProtoError::new( + ErrorCode::LimitExceeded, + format!("at most {} riders per connection", self.limits.max_riders), + ) + .with_rider(rider_name())); + } + let rider = Rider { + id: format!("r{:x}", self.next_rider), + route: join.route.clone(), + room: join.room.clone(), + name: join.name, + state: join.state, + last: now, + }; + self.next_rider += 1; + let joined = view(&c.app, &rider); + c.riders.insert(join.rider, rider); + let key = (join.route.clone(), join.room.clone()); + Ok(self.to_subscribers( + &key, + conn, + ServerMsg::Joined { + route: join.route, + room: join.room, + rider: joined, + }, + )) + } + + pub fn leave(&mut self, conn: ConnId, rider: &str) -> Result, ProtoError> { + let removed = self.conns.get_mut(&conn).and_then(|c| c.riders.remove(rider)); + match removed { + Some(r) => Ok(self.left(conn, &r, LeftReason::Leave)), + None => { + Err(ProtoError::new(ErrorCode::UnknownRider, "rider has not joined") + .with_rider(Some(rider.to_string()))) + } + } + } + + /// Applies a batch of state entries. Each entry is checked on its own: a bad one yields an error + /// and does not stop the others. The accepted entries go out as one `Updated` per route+room. + pub fn update( + &mut self, + conn: ConnId, + entries: Vec, + now: Instant, + ) -> (Vec, Vec) { + let mut errors = Vec::new(); + let mut accepted: BTreeMap> = BTreeMap::new(); + let min_interval = self.min_update_interval(); + if let Some(c) = self.conns.get_mut(&conn) { + for e in entries { + let fail = |code, msg: String| ProtoError::new(code, msg).with_rider(Some(e.rider.clone())); + let Some(r) = c.riders.get_mut(&e.rider) else { + errors.push(fail(ErrorCode::UnknownRider, "rider has not joined".to_string())); + continue; + }; + if let Some(route) = self.routes.get(&r.route) { + if let Err(err) = check_distance(route.length, e.state.distance, &e.rider) { + errors.push(err); + continue; + } + } + if now.saturating_duration_since(r.last) < min_interval { + errors.push(fail(ErrorCode::RateLimited, "updates are coming too fast".to_string())); + continue; + } + r.last = now; + r.state = e.state.clone(); + accepted + .entry((r.route.clone(), r.room.clone())) + .or_default() + .push(RiderUpdate { + id: r.id.clone(), + state: e.state, + }); + } + } else { + debug_assert!(false, "update without connect"); + } + let deliveries = accepted + .into_iter() + .flat_map(|(key, riders)| { + let msg = ServerMsg::Updated { + route: key.0.clone(), + room: key.1.clone(), + riders, + }; + self.to_subscribers(&key, conn, msg) + }) + .collect(); + (deliveries, errors) + } + + /// Removes the riders whose last accepted state is `rider_timeout_s` old or older. + pub fn expire(&mut self, now: Instant) -> Vec { + let timeout = Duration::from_secs(u64::from(self.limits.rider_timeout_s)); + let mut expired: Vec<(ConnId, Rider)> = Vec::new(); + for (id, c) in &mut self.conns { + let stale: Vec = c + .riders + .iter() + .filter(|(_, r)| now.saturating_duration_since(r.last) >= timeout) + .map(|(k, _)| k.clone()) + .collect(); + for k in stale { + if let Some(r) = c.riders.remove(&k) { + expired.push((*id, r)); + } + } + } + expired + .iter() + .flat_map(|(conn, r)| self.left(*conn, r, LeftReason::Timeout)) + .collect() + } + + /// 80% of the nominal interval between updates, which allows for network jitter. + fn min_update_interval(&self) -> Duration { + Duration::from_nanos(800_000_000 / u64::from(self.limits.max_update_hz.max(1))) + } + + /// Removes the connection with its riders and subscriptions. + pub fn disconnect(&mut self, conn: ConnId) -> Vec { + let Some(c) = self.conns.remove(&conn) else { + return Vec::new(); + }; + for key in &c.subscriptions { + self.remove_subscriber(key, conn); + } + c.riders + .values() + .flat_map(|r| self.left(conn, r, LeftReason::Disconnect)) + .collect() + } + + pub fn live_counts(&self) -> BTreeMap { + let mut counts: BTreeMap = BTreeMap::new(); + for c in self.conns.values() { + let e = counts.entry(c.app.id.clone()).or_default(); + e.connections += 1; + e.riders += c.riders.len() as u32; + } + counts + } + + fn check_route(&self, route: &str) -> Result<&crate::routes::Route, ProtoError> { + self.routes + .get(route) + .ok_or_else(|| ProtoError::new(ErrorCode::UnknownRoute, format!("unknown route {route:?}"))) + } + + fn remove_subscriber(&mut self, key: &RoomKey, conn: ConnId) { + if let Some(set) = self.rooms.get_mut(key) { + set.remove(&conn); + if set.is_empty() { + self.rooms.remove(key); + } + } + } + + /// `msg` for every subscriber of the room except `except`. + fn to_subscribers(&self, key: &RoomKey, except: ConnId, msg: ServerMsg) -> Vec { + self.rooms + .get(key) + .into_iter() + .flatten() + .filter(|c| **c != except) + .map(|c| Delivery { + to: *c, + msg: msg.clone(), + }) + .collect() + } + + fn left(&self, conn: ConnId, rider: &Rider, reason: LeftReason) -> Vec { + let key = (rider.route.clone(), rider.room.clone()); + self.to_subscribers( + &key, + conn, + ServerMsg::Left { + route: key.0.clone(), + room: key.1.clone(), + id: rider.id.clone(), + reason, + }, + ) + } +} + +fn check_distance(length: f64, distance: f64, rider: &str) -> Result<(), ProtoError> { + if distance >= length { + return Err(ProtoError::new( + ErrorCode::InvalidValue, + format!("distance must be less than the route length {length}"), + ) + .with_rider(Some(rider.to_string()))); + } + Ok(()) +} + +fn view(app: &AppInfo, r: &Rider) -> RiderView { + RiderView { + id: r.id.clone(), + app: app.id.clone(), + name: r.name.clone(), + state: r.state.clone(), + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::protocol::{AppInfo, ErrorCode, Join, LeftReason, Limits, RiderState, RiderView, ServerMsg}; + use crate::routes::{Route, Routes}; + use std::path::Path; + use std::time::Instant; + + const ROUTES_DIR: &str = concat!(env!("CARGO_MANIFEST_DIR"), "/../../protocol/routes"); + + fn app(id: &str) -> AppInfo { + AppInfo { + id: id.to_string(), + version: "1.0".to_string(), + name: None, + url: None, + } + } + + fn other_route() -> Route { + Route { + id: "other-100".to_string(), + name: "Other".to_string(), + length: 100.0, + looped: true, + profile: vec![[0.0, 0.0], [100.0, 0.0]], + } + } + + fn presence_with(limits: Limits) -> Presence { + let mut routes = Routes::load_dir(Path::new(ROUTES_DIR)).unwrap(); + let mut all: Vec = vec![routes.get("velodrome-250").unwrap().clone(), other_route()]; + routes = Routes::from_routes(std::mem::take(&mut all)).unwrap(); + Presence::new(routes, limits) + } + + fn presence() -> Presence { + presence_with(Limits::default()) + } + + fn state(distance: f64) -> RiderState { + RiderState { + lap: 0, + distance, + speed: 10.0, + power: None, + cadence: None, + heart_rate: None, + } + } + + fn join_in(rider: &str, route: &str, room: &str, name: &str) -> Join { + Join { + rider: rider.to_string(), + route: route.to_string(), + room: room.to_string(), + name: name.to_string(), + state: state(0.0), + } + } + + fn join_msg(rider: &str, name: &str) -> Join { + join_in(rider, "velodrome-250", "public", name) + } + + const V: &str = "velodrome-250"; + const P: &str = "public"; + + #[test] + fn late_subscriber_gets_snapshot() { + let mut p = presence(); + let t0 = Instant::now(); + p.connect(1, app("app-one")); + p.connect(2, app("app-two")); + p.join(1, join_msg("u-1", "Anna"), t0).unwrap(); + let d = p.subscribe(2, V, P).unwrap(); + assert_eq!(d.len(), 1); + assert_eq!(d[0].to, 2); + match &d[0].msg { + ServerMsg::Snapshot { route, room, riders } => { + assert_eq!((route.as_str(), room.as_str()), (V, P)); + assert_eq!(riders.len(), 1); + let r: &RiderView = &riders[0]; + assert_eq!( + (r.id.as_str(), r.app.as_str(), r.name.as_str()), + ("r1", "app-one", "Anna") + ); + } + m => panic!("unexpected {m:?}"), + } + } + + #[test] + fn snapshot_excludes_own_riders() { + let mut p = presence(); + p.connect(1, app("app-one")); + p.join(1, join_msg("u-1", "Anna"), Instant::now()).unwrap(); + let d = p.subscribe(1, V, P).unwrap(); + match &d[0].msg { + ServerMsg::Snapshot { riders, .. } => assert!(riders.is_empty()), + m => panic!("unexpected {m:?}"), + } + } + + #[test] + fn join_notifies_other_subscribers_only() { + let mut p = presence(); + p.connect(1, app("app-one")); + p.connect(2, app("app-two")); + p.subscribe(1, V, P).unwrap(); + p.subscribe(2, V, P).unwrap(); + let d = p.join(1, join_msg("u-1", "Anna"), Instant::now()).unwrap(); + assert_eq!(d.len(), 1); + assert_eq!(d[0].to, 2); + assert!(matches!(&d[0].msg, ServerMsg::Joined { rider, .. } if rider.id == "r1" && rider.app == "app-one")); + } + + #[test] + fn rooms_are_separate() { + let mut p = presence(); + p.connect(1, app("app-one")); + p.connect(2, app("app-two")); + p.subscribe(2, V, "a").unwrap(); + let d = p.join(1, join_msg("u-1", "Anna"), Instant::now()).unwrap(); + assert!(d.is_empty()); + } + + #[test] + fn same_rider_value_on_two_connections() { + let mut p = presence(); + p.connect(1, app("app-one")); + p.connect(2, app("app-two")); + p.subscribe(1, V, P).unwrap(); + p.subscribe(2, V, P).unwrap(); + let t0 = Instant::now(); + let d1 = p.join(1, join_msg("u-1", "Anna"), t0).unwrap(); + let d2 = p.join(2, join_msg("u-1", "Ben"), t0).unwrap(); + assert!(matches!(&d1[0].msg, ServerMsg::Joined { rider, .. } if rider.id == "r1")); + assert!(matches!(&d2[0].msg, ServerMsg::Joined { rider, .. } if rider.id == "r2")); + } + + #[test] + fn join_twice_on_other_route() { + let mut p = presence(); + p.connect(1, app("app-one")); + let t0 = Instant::now(); + p.join(1, join_msg("u-1", "Anna"), t0).unwrap(); + let e = p.join(1, join_in("u-1", "other-100", P, "Anna"), t0).unwrap_err(); + assert_eq!(e.code, ErrorCode::RiderExists); + } + + #[test] + fn join_unknown_route() { + let mut p = presence(); + p.connect(1, app("app-one")); + let e = p + .join(1, join_in("u-1", "nowhere", P, "Anna"), Instant::now()) + .unwrap_err(); + assert_eq!(e.code, ErrorCode::UnknownRoute); + } + + #[test] + fn subscribe_unknown_route() { + let mut p = presence(); + p.connect(1, app("app-one")); + assert_eq!(p.subscribe(1, "nowhere", P).unwrap_err().code, ErrorCode::UnknownRoute); + } + + #[test] + fn join_limit() { + let limits = Limits { + max_riders: 2, + ..Limits::default() + }; + let mut p = presence_with(limits); + p.connect(1, app("app-one")); + let t0 = Instant::now(); + p.join(1, join_msg("u-1", "A"), t0).unwrap(); + p.join(1, join_msg("u-2", "B"), t0).unwrap(); + let e = p.join(1, join_msg("u-3", "C"), t0).unwrap_err(); + assert_eq!(e.code, ErrorCode::LimitExceeded); + } + + #[test] + fn subscribe_limit() { + let limits = Limits { + max_subscriptions: 2, + ..Limits::default() + }; + let mut p = presence_with(limits); + p.connect(1, app("app-one")); + p.subscribe(1, V, "a").unwrap(); + p.subscribe(1, V, "b").unwrap(); + assert_eq!(p.subscribe(1, V, "c").unwrap_err().code, ErrorCode::LimitExceeded); + // Subscribing again to an existing one is not a new subscription. + p.subscribe(1, V, "a").unwrap(); + } + + #[test] + fn leave_notifies_with_reason_leave() { + let mut p = presence(); + 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", "Anna"), Instant::now()).unwrap(); + let d = p.leave(1, "u-1").unwrap(); + assert_eq!(d.len(), 1); + assert_eq!(d[0].to, 2); + assert!(matches!(&d[0].msg, ServerMsg::Left { id, reason: LeftReason::Leave, .. } if id == "r1")); + // The rider value can be joined again. + p.join(1, join_msg("u-1", "Anna"), Instant::now()).unwrap(); + } + + #[test] + fn leave_unknown_rider() { + let mut p = presence(); + p.connect(1, app("app-one")); + assert_eq!(p.leave(1, "u-1").unwrap_err().code, ErrorCode::UnknownRider); + } + + #[test] + fn disconnect_removes_riders_and_subscriptions() { + let mut p = presence(); + p.connect(1, app("app-one")); + p.connect(2, app("app-two")); + p.subscribe(2, V, P).unwrap(); + let t0 = Instant::now(); + p.join(1, join_msg("u-1", "Anna"), t0).unwrap(); + p.join(1, join_msg("u-2", "Ben"), t0).unwrap(); + let d = p.disconnect(1); + assert_eq!(d.len(), 2); + for x in &d { + assert_eq!(x.to, 2); + assert!(matches!( + &x.msg, + ServerMsg::Left { + reason: LeftReason::Disconnect, + .. + } + )); + } + let counts = p.live_counts(); + assert!(!counts.contains_key("app-one")); + assert_eq!(counts["app-two"].connections, 1); + assert!(p.disconnect(1).is_empty()); + } + + #[test] + fn unsubscribe_stops_events() { + let mut p = presence(); + p.connect(1, app("app-one")); + p.connect(2, app("app-two")); + p.subscribe(2, V, P).unwrap(); + p.unsubscribe(2, V, P); + p.unsubscribe(2, V, P); // not subscribed any more: no-op + let d = p.join(1, join_msg("u-1", "Anna"), Instant::now()).unwrap(); + assert!(d.is_empty()); + } + + #[test] + fn live_counts_per_app() { + let mut p = presence(); + p.connect(1, app("app-one")); + p.connect(2, app("app-one")); + let t0 = Instant::now(); + p.join(1, join_msg("u-1", "A"), t0).unwrap(); + p.join(1, join_msg("u-2", "B"), t0).unwrap(); + p.join(2, join_msg("u-1", "C"), t0).unwrap(); + let c = p.live_counts(); + assert_eq!(c.len(), 1); + assert_eq!((c["app-one"].connections, c["app-one"].riders), (2, 3)); + } + + use crate::protocol::{RiderUpdate, UpdateEntry}; + use std::time::Duration; + + fn entry(rider: &str, distance: f64) -> UpdateEntry { + UpdateEntry { + rider: rider.to_string(), + state: state(distance), + } + } + + fn updated(d: &Delivery) -> &Vec { + match &d.msg { + ServerMsg::Updated { riders, .. } => riders, + m => panic!("unexpected {m:?}"), + } + } + + #[test] + fn update_batches_per_room() { + let mut p = presence(); + let t0 = Instant::now(); + p.connect(1, app("app-one")); + p.connect(2, app("app-two")); + p.join(1, join_msg("u-1", "A"), t0).unwrap(); + p.join(1, join_msg("u-2", "B"), t0).unwrap(); + p.join(1, join_in("u-3", V, "a", "C"), t0).unwrap(); + p.subscribe(2, V, P).unwrap(); + p.subscribe(2, V, "a").unwrap(); + let t1 = t0 + Duration::from_secs(1); + let (d, errs) = p.update(1, vec![entry("u-1", 1.0), entry("u-3", 2.0), entry("u-2", 3.0)], t1); + assert!(errs.is_empty()); + assert_eq!(d.len(), 2); + assert!(d.iter().all(|x| x.to == 2)); + // Rooms in key order: "a" before "public". + assert!(matches!(&d[0].msg, ServerMsg::Updated { room, .. } if room == "a")); + assert_eq!(updated(&d[0]).len(), 1); + assert!(matches!(&d[1].msg, ServerMsg::Updated { room, .. } if room == "public")); + let ids: Vec<&str> = updated(&d[1]).iter().map(|r| r.id.as_str()).collect(); + assert_eq!(ids, ["r1", "r2"]); + assert_eq!(updated(&d[1])[1].state.distance, 3.0); + } + + #[test] + fn update_no_echo() { + let mut p = presence(); + let t0 = Instant::now(); + p.connect(1, app("app-one")); + p.join(1, join_msg("u-1", "A"), t0).unwrap(); + p.subscribe(1, V, P).unwrap(); + let (d, errs) = p.update(1, vec![entry("u-1", 1.0)], t0 + Duration::from_secs(1)); + assert!(d.is_empty()); + assert!(errs.is_empty()); + } + + #[test] + fn distance_equal_to_length_is_rejected() { + let mut p = presence(); + let t0 = Instant::now(); + p.connect(1, app("app-one")); + p.connect(2, app("app-two")); + p.join(1, join_msg("u-1", "A"), t0).unwrap(); + p.subscribe(2, V, P).unwrap(); + let t1 = t0 + Duration::from_secs(1); + let (d, errs) = p.update(1, vec![entry("u-1", 250.0)], t1); + assert!(d.is_empty()); + assert_eq!(errs.len(), 1); + assert_eq!(errs[0].code, ErrorCode::InvalidValue); + assert_eq!(errs[0].rider.as_deref(), Some("u-1")); + let (d, errs) = p.update(1, vec![entry("u-1", 249.99)], t1); + assert!(errs.is_empty()); + assert_eq!(d.len(), 1); + } + + #[test] + fn bad_entry_does_not_block_others() { + let mut p = presence(); + let t0 = Instant::now(); + p.connect(1, app("app-one")); + p.connect(2, app("app-two")); + p.join(1, join_msg("u-1", "A"), t0).unwrap(); + p.subscribe(2, V, P).unwrap(); + let (d, errs) = p.update( + 1, + vec![entry("nope", 1.0), entry("u-1", 2.0)], + t0 + Duration::from_secs(1), + ); + assert_eq!(errs.len(), 1); + assert_eq!(errs[0].code, ErrorCode::UnknownRider); + assert_eq!(errs[0].rider.as_deref(), Some("nope")); + assert_eq!(d.len(), 1); + assert_eq!(updated(&d[0]).len(), 1); + } + + #[test] + fn rate_limit() { + let mut p = presence(); + let t0 = Instant::now(); + let ms = Duration::from_millis; + p.connect(1, app("app-one")); + p.connect(2, app("app-two")); + p.join(1, join_msg("u-1", "A"), t0 - ms(1000)).unwrap(); + p.subscribe(2, V, P).unwrap(); + let (d, errs) = p.update(1, vec![entry("u-1", 1.0)], t0); + assert!(errs.is_empty() && d.len() == 1); + let (d, errs) = p.update(1, vec![entry("u-1", 2.0)], t0 + ms(150)); + assert!(d.is_empty()); + assert_eq!(errs.len(), 1); + assert_eq!(errs[0].code, ErrorCode::RateLimited); + assert_eq!(errs[0].rider.as_deref(), Some("u-1")); + // The rejected entry did not move `last`: 200 ms after t0 is accepted. + let (d, errs) = p.update(1, vec![entry("u-1", 3.0)], t0 + ms(200)); + assert!(errs.is_empty()); + assert_eq!(d.len(), 1); + } + + #[test] + fn timeout_after_rider_timeout_s() { + let mut p = presence(); + let t0 = Instant::now(); + let ms = Duration::from_millis; + 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(); + assert!(p.expire(t0 + ms(9900)).is_empty()); + let d = p.expire(t0 + ms(10_000)); + assert_eq!(d.len(), 1); + assert_eq!(d[0].to, 2); + assert!(matches!(&d[0].msg, ServerMsg::Left { id, reason: LeftReason::Timeout, .. } if id == "r1")); + // Gone: it cannot expire twice and its rider value is free again. + assert!(p.expire(t0 + ms(20_000)).is_empty()); + p.join(1, join_msg("u-1", "A"), t0 + ms(20_000)).unwrap(); + + // An update at 5 s pushes the timeout to 15 s. + let t1 = t0 + ms(30_000); + p.join(1, join_msg("u-2", "B"), t1).unwrap(); + let (_, errs) = p.update(1, vec![entry("u-2", 1.0)], t1 + ms(5000)); + assert!(errs.is_empty()); + assert!(p + .expire(t1 + ms(14_900)) + .iter() + .all(|x| !matches!(&x.msg, ServerMsg::Left { id, .. } if id == "r3"))); + let d = p.expire(t1 + ms(15_000)); + assert!(d + .iter() + .any(|x| matches!(&x.msg, ServerMsg::Left { id, reason: LeftReason::Timeout, .. } if id == "r3"))); + } + + #[test] + fn optional_fields_only_when_sent() { + let mut p = presence(); + let t0 = Instant::now(); + p.connect(1, app("app-one")); + p.connect(2, app("app-two")); + p.join(1, join_msg("u-1", "A"), t0).unwrap(); + p.subscribe(2, V, P).unwrap(); + let mut e = entry("u-1", 1.0); + e.state.power = Some(200); + let t1 = t0 + Duration::from_secs(1); + let (d, _) = p.update(1, vec![e], t1); + assert_eq!(updated(&d[0])[0].state.power, Some(200)); + let (d, _) = p.update(1, vec![entry("u-1", 2.0)], t1 + Duration::from_secs(1)); + let u = &updated(&d[0])[0]; + assert_eq!(u.state.power, None); + assert_eq!((u.state.cadence, u.state.heart_rate), (None, None)); + } +} diff --git a/crates/server/src/prometheus.rs b/crates/server/src/prometheus.rs new file mode 100644 index 0000000..d247a1b --- /dev/null +++ b/crates/server/src/prometheus.rs @@ -0,0 +1,206 @@ +//! Prometheus text export for `/internal/metrics`: live gauges per app and a few counters. +//! +//! Not to be confused with [`crate::metrics`], which holds the SQLite usage statistics. +//! Counters are plain atomics, so counting never blocks the connection tasks. + +use std::collections::BTreeMap; +use std::fmt::Write; +use std::sync::atomic::{AtomicU64, Ordering}; + +use crate::presence::AppCounts; +use crate::protocol::ErrorCode; + +/// The `Content-Type` of the Prometheus text format. +pub const CONTENT_TYPE: &str = "text/plain; version=0.0.4; charset=utf-8"; + +/// Counters since the server started. +#[derive(Default)] +pub struct Counters { + connections: AtomicU64, + rider_updates: AtomicU64, + /// Indexed by `ErrorCode as usize`. + errors: [AtomicU64; ErrorCode::ALL.len()], + queue_full_drops: AtomicU64, + rejected_per_ip: AtomicU64, +} + +/// A point-in-time copy of [`Counters`]. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Snapshot { + pub connections: u64, + pub rider_updates: u64, + /// Every error code, in declaration order, including those never sent. + pub errors: Vec<(&'static str, u64)>, + pub queue_full_drops: u64, + pub rejected_per_ip: u64, +} + +impl Counters { + pub fn connection_accepted(&self) { + self.connections.fetch_add(1, Ordering::Relaxed); + } + + pub fn updates_accepted(&self, entries: usize) { + self.rider_updates.fetch_add(entries as u64, Ordering::Relaxed); + } + + pub fn error_sent(&self, code: ErrorCode) { + self.errors[code as usize].fetch_add(1, Ordering::Relaxed); + } + + pub fn queue_full_drop(&self) { + self.queue_full_drops.fetch_add(1, Ordering::Relaxed); + } + + pub fn rejected_per_ip(&self) { + self.rejected_per_ip.fetch_add(1, Ordering::Relaxed); + } + + pub fn snapshot(&self) -> Snapshot { + Snapshot { + connections: self.connections.load(Ordering::Relaxed), + rider_updates: self.rider_updates.load(Ordering::Relaxed), + errors: ErrorCode::ALL + .iter() + .map(|&code| (code.as_str(), self.errors[code as usize].load(Ordering::Relaxed))) + .collect(), + queue_full_drops: self.queue_full_drops.load(Ordering::Relaxed), + rejected_per_ip: self.rejected_per_ip.load(Ordering::Relaxed), + } + } +} + +/// Escapes a label value for the text format. +fn label(value: &str) -> String { + value.replace('\\', "\\\\").replace('"', "\\\"").replace('\n', "\\n") +} + +/// The whole `/internal/metrics` body. Only live apps appear in the gauges, so label cardinality +/// stays bounded by the apps connected right now. +pub fn render(live: &BTreeMap, counters: &Snapshot, version: &str, sha: &str) -> String { + let mut out = String::new(); + let _ = writeln!( + out, + "# HELP obn_connections Current WebSocket connections per app.\n# TYPE obn_connections gauge" + ); + for (app, c) in live { + let _ = writeln!(out, "obn_connections{{app=\"{}\"}} {}", label(app), c.connections); + } + let _ = writeln!( + out, + "# HELP obn_riders Current riders per app.\n# TYPE obn_riders gauge" + ); + for (app, c) in live { + let _ = writeln!(out, "obn_riders{{app=\"{}\"}} {}", label(app), c.riders); + } + let _ = writeln!( + out, + "# HELP obn_connections_total WebSocket connections accepted since the server started.\n\ + # TYPE obn_connections_total counter\nobn_connections_total {}", + counters.connections + ); + let _ = writeln!( + out, + "# HELP obn_rider_updates_total Rider update entries accepted since the server started.\n\ + # TYPE obn_rider_updates_total counter\nobn_rider_updates_total {}", + counters.rider_updates + ); + let _ = writeln!( + out, + "# HELP obn_errors_total Error messages sent to apps, by error code.\n# TYPE obn_errors_total counter" + ); + for (code, n) in &counters.errors { + let _ = writeln!(out, "obn_errors_total{{code=\"{code}\"}} {n}"); + } + let _ = writeln!( + out, + "# HELP obn_queue_full_drops_total Connections dropped because their outgoing queue was full.\n\ + # TYPE obn_queue_full_drops_total counter\nobn_queue_full_drops_total {}", + counters.queue_full_drops + ); + let _ = writeln!( + out, + "# HELP obn_connections_rejected_total Connections refused before the upgrade.\n\ + # TYPE obn_connections_rejected_total counter\nobn_connections_rejected_total{{reason=\"per_ip_limit\"}} {}", + counters.rejected_per_ip + ); + let _ = writeln!( + out, + "# HELP obn_build_info Which build is running.\n# TYPE obn_build_info gauge\n\ + obn_build_info{{version=\"{}\",sha=\"{}\"}} 1", + label(version), + label(sha) + ); + out +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn error_index_matches_declaration_order() { + for (i, code) in ErrorCode::ALL.iter().enumerate() { + assert_eq!(*code as usize, i); + } + } + + #[test] + fn counters_count_and_prefill_every_error_code() { + let c = Counters::default(); + let snap = c.snapshot(); + assert_eq!(snap.errors.len(), 14); + assert!(snap.errors.iter().all(|(_, n)| *n == 0)); + c.connection_accepted(); + c.connection_accepted(); + c.updates_accepted(3); + c.error_sent(ErrorCode::RateLimited); + c.queue_full_drop(); + c.rejected_per_ip(); + let snap = c.snapshot(); + assert_eq!((snap.connections, snap.rider_updates), (2, 3)); + assert_eq!((snap.queue_full_drops, snap.rejected_per_ip), (1, 1)); + assert!(snap.errors.contains(&("rate_limited", 1))); + } + + #[test] + fn renders_gauges_and_counters() { + let mut live = BTreeMap::new(); + live.insert( + "openradlr".to_string(), + AppCounts { + connections: 2, + riders: 5, + }, + ); + let c = Counters::default(); + c.connection_accepted(); + c.error_sent(ErrorCode::UnknownRoute); + let out = render(&live, &c.snapshot(), "0.1.0", "abc123"); + assert!(out.contains("obn_connections{app=\"openradlr\"} 2\n")); + assert!(out.contains("obn_riders{app=\"openradlr\"} 5\n")); + assert!(out.contains("obn_connections_total 1\n")); + assert!(out.contains("obn_rider_updates_total 0\n")); + assert!(out.contains("obn_errors_total{code=\"unknown_route\"} 1\n")); + assert!(out.contains("obn_errors_total{code=\"hello_required\"} 0\n")); + assert_eq!(out.matches("obn_errors_total{").count(), 14); + assert!(out.contains("obn_queue_full_drops_total 0\n")); + assert!(out.contains("obn_connections_rejected_total{reason=\"per_ip_limit\"} 0\n")); + assert!(out.contains("obn_build_info{version=\"0.1.0\",sha=\"abc123\"} 1\n")); + for line in out.lines().filter(|l| !l.starts_with('#')) { + assert!(line.starts_with("obn_"), "{line}"); + } + } + + #[test] + fn offline_apps_have_no_series() { + let out = render(&BTreeMap::new(), &Counters::default().snapshot(), "0.1.0", "dev"); + assert!(!out.contains("obn_riders{")); + assert!(!out.contains("obn_connections{")); + } + + #[test] + fn label_values_are_escaped() { + assert_eq!(label("a\"b\\c\nd"), "a\\\"b\\\\c\\nd"); + } +} diff --git a/crates/server/src/protocol.rs b/crates/server/src/protocol.rs new file mode 100644 index 0000000..db9eeeb --- /dev/null +++ b/crates/server/src/protocol.rs @@ -0,0 +1,532 @@ +//! Wire types of protocol v0 (`protocol/spec/v0.md`): parsing of app messages and serialization of +//! server messages. +//! +//! App messages are read by hand from a `serde_json::Value`, because serde-derive errors do not +//! separate `invalid_message` (missing field or wrong type) from `invalid_value` (out of range). + +use serde::Serialize; +use serde_json::{Map, Value}; + +pub const DEFAULT_ROOM: &str = "public"; + +const MAX_REF: usize = 64; +const MAX_RIDER: usize = 64; +const MAX_NAME: usize = 32; +const MAX_VERSION: usize = 32; +const MAX_APP_NAME: usize = 32; +const MAX_APP_URL: usize = 200; + +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize)] +#[serde(rename_all = "snake_case")] +pub enum ErrorCode { + HelloRequired, + HelloRepeated, + InvalidMessage, + UnknownType, + InvalidAppId, + UnknownRoute, + InvalidRoom, + RiderExists, + UnknownRider, + InvalidValue, + RateLimited, + LimitExceeded, + MessageTooLarge, + TooManyErrors, +} + +impl ErrorCode { + /// Every code, in declaration order (so `code as usize` indexes it). + pub const ALL: [ErrorCode; 14] = [ + ErrorCode::HelloRequired, + ErrorCode::HelloRepeated, + ErrorCode::InvalidMessage, + ErrorCode::UnknownType, + ErrorCode::InvalidAppId, + ErrorCode::UnknownRoute, + ErrorCode::InvalidRoom, + ErrorCode::RiderExists, + ErrorCode::UnknownRider, + ErrorCode::InvalidValue, + ErrorCode::RateLimited, + ErrorCode::LimitExceeded, + ErrorCode::MessageTooLarge, + ErrorCode::TooManyErrors, + ]; + + pub fn as_str(self) -> &'static str { + match self { + ErrorCode::HelloRequired => "hello_required", + ErrorCode::HelloRepeated => "hello_repeated", + ErrorCode::InvalidMessage => "invalid_message", + ErrorCode::UnknownType => "unknown_type", + ErrorCode::InvalidAppId => "invalid_app_id", + ErrorCode::UnknownRoute => "unknown_route", + ErrorCode::InvalidRoom => "invalid_room", + ErrorCode::RiderExists => "rider_exists", + ErrorCode::UnknownRider => "unknown_rider", + ErrorCode::InvalidValue => "invalid_value", + ErrorCode::RateLimited => "rate_limited", + ErrorCode::LimitExceeded => "limit_exceeded", + ErrorCode::MessageTooLarge => "message_too_large", + ErrorCode::TooManyErrors => "too_many_errors", + } + } + + /// True if the server closes the connection after this error. + pub fn fatal(self) -> bool { + matches!( + self, + ErrorCode::HelloRequired | ErrorCode::InvalidAppId | ErrorCode::MessageTooLarge | ErrorCode::TooManyErrors + ) + } +} + +#[derive(Debug, Clone, PartialEq)] +pub struct ProtoError { + pub code: ErrorCode, + pub message: String, + pub rider: Option, + pub ref_: Option, +} + +impl ProtoError { + pub fn new(code: ErrorCode, message: impl Into) -> Self { + ProtoError { + code, + message: message.into(), + rider: None, + ref_: None, + } + } + + pub fn with_ref(mut self, ref_: Option) -> Self { + self.ref_ = ref_; + self + } + + pub fn with_rider(mut self, rider: Option) -> Self { + self.rider = rider; + self + } +} + +fn invalid_message(message: impl Into) -> ProtoError { + ProtoError::new(ErrorCode::InvalidMessage, message) +} + +fn invalid_value(message: impl Into) -> ProtoError { + ProtoError::new(ErrorCode::InvalidValue, message) +} + +#[derive(Debug, Clone, PartialEq)] +pub struct AppInfo { + pub id: String, + pub version: String, + pub name: Option, + pub url: Option, +} + +#[derive(Debug, Clone, PartialEq, Serialize)] +pub struct RiderState { + pub lap: u32, + pub distance: f64, + pub speed: f64, + #[serde(skip_serializing_if = "Option::is_none")] + pub power: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub cadence: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub heart_rate: Option, +} + +#[derive(Debug, Clone, PartialEq)] +pub struct Join { + pub rider: String, + pub route: String, + pub room: String, + pub name: String, + pub state: RiderState, +} + +#[derive(Debug, Clone, PartialEq)] +pub struct UpdateEntry { + pub rider: String, + pub state: RiderState, +} + +#[derive(Debug, Clone, PartialEq)] +pub enum AppMsg { + Hello(AppInfo), + Subscribe { + route: String, + room: String, + }, + Unsubscribe { + route: String, + room: String, + }, + Join(Join), + /// The raw rider entries; each is checked on its own with [`parse_update_entry`]. + Update(Vec), + Leave { + rider: String, + }, +} + +#[derive(Debug, Clone, PartialEq)] +pub struct Envelope { + pub ref_: Option, + pub msg: AppMsg, +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)] +pub struct Limits { + pub max_update_hz: u32, + pub rider_timeout_s: u32, + pub max_riders: u32, + pub max_subscriptions: u32, + pub max_message_bytes: u32, +} + +impl Default for Limits { + fn default() -> Self { + Limits { + max_update_hz: 4, + rider_timeout_s: 10, + max_riders: 200, + max_subscriptions: 16, + max_message_bytes: 65536, + } + } +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)] +#[serde(rename_all = "snake_case")] +pub enum LeftReason { + Leave, + Timeout, + Disconnect, +} + +#[derive(Debug, Clone, PartialEq, Serialize)] +pub struct RiderView { + pub id: String, + pub app: String, + pub name: String, + #[serde(flatten)] + pub state: RiderState, +} + +#[derive(Debug, Clone, PartialEq, Serialize)] +pub struct RiderUpdate { + pub id: String, + #[serde(flatten)] + pub state: RiderState, +} + +#[derive(Debug, Clone, PartialEq, Serialize)] +#[serde(tag = "type", rename_all = "snake_case")] +pub enum ServerMsg { + Welcome { + protocol: &'static str, + connection: String, + limits: Limits, + }, + Snapshot { + route: String, + room: String, + riders: Vec, + }, + Joined { + route: String, + room: String, + rider: RiderView, + }, + Updated { + route: String, + room: String, + riders: Vec, + }, + Left { + route: String, + room: String, + id: String, + reason: LeftReason, + }, + Error { + code: ErrorCode, + message: String, + #[serde(rename = "ref", skip_serializing_if = "Option::is_none")] + ref_: Option, + #[serde(skip_serializing_if = "Option::is_none")] + rider: Option, + fatal: bool, + }, +} + +impl From for ServerMsg { + fn from(e: ProtoError) -> Self { + ServerMsg::Error { + code: e.code, + fatal: e.code.fatal(), + message: e.message, + ref_: e.ref_, + rider: e.rider, + } + } +} + +fn is_lower_alnum(b: u8) -> bool { + b.is_ascii_lowercase() || b.is_ascii_digit() +} + +/// `^[a-z0-9][a-z0-9-]{min_rest,max_rest}$` +fn is_slug(s: &str, min_rest: usize, max_rest: usize) -> bool { + let b = s.as_bytes(); + if b.is_empty() || !is_lower_alnum(b[0]) { + return false; + } + let rest = &b[1..]; + (min_rest..=max_rest).contains(&rest.len()) && rest.iter().all(|&c| is_lower_alnum(c) || c == b'-') +} + +/// `^[a-z0-9][a-z0-9-]{1,31}$` +pub fn is_valid_app_id(s: &str) -> bool { + is_slug(s, 1, 31) +} + +/// `^[a-z0-9][a-z0-9-]{0,31}$` +pub fn is_valid_room(s: &str) -> bool { + is_slug(s, 0, 31) +} + +/// `^[a-z0-9][a-z0-9-]{1,63}$` +pub fn is_valid_route_id(s: &str) -> bool { + is_slug(s, 1, 63) +} + +/// Parses one app message. Checks every field except the `update` entries and whether the route +/// exists. Errors carry the message's `ref` when it could be read. +pub fn parse_app_msg(text: &str) -> Result { + let value: Value = serde_json::from_str(text).map_err(|_| invalid_message("not valid JSON"))?; + let obj = value + .as_object() + .ok_or_else(|| invalid_message("message must be a JSON object"))?; + let ref_ = read_ref(obj)?; + parse_body(obj) + .map(|msg| Envelope { + ref_: ref_.clone(), + msg, + }) + .map_err(|e| e.with_ref(ref_)) +} + +fn read_ref(obj: &Map) -> Result, ProtoError> { + match obj.get("ref") { + None => Ok(None), + Some(Value::String(s)) if s.chars().count() <= MAX_REF => Ok(Some(s.clone())), + Some(Value::String(_)) => Err(invalid_value("ref is longer than 64 characters")), + Some(_) => Err(invalid_message("ref must be a string")), + } +} + +fn parse_body(obj: &Map) -> Result { + let ty = match obj.get("type") { + Some(Value::String(s)) => s.as_str(), + _ => return Err(invalid_message("type must be a string")), + }; + match ty { + "hello" => parse_hello(obj), + "subscribe" => Ok(AppMsg::Subscribe { + route: route_field(obj)?, + room: room_field(obj)?, + }), + "unsubscribe" => Ok(AppMsg::Unsubscribe { + route: route_field(obj)?, + room: room_field(obj)?, + }), + "join" => Ok(AppMsg::Join(Join { + rider: rider_field(obj)?, + route: route_field(obj)?, + room: room_field(obj)?, + name: name_field(obj)?, + state: state_fields(obj)?, + })), + "update" => match obj.get("riders") { + Some(Value::Array(a)) => Ok(AppMsg::Update(a.clone())), + _ => Err(invalid_message("riders must be an array")), + }, + "leave" => Ok(AppMsg::Leave { + rider: rider_field(obj)?, + }), + other => Err(ProtoError::new( + ErrorCode::UnknownType, + format!("unknown type {:?}", truncate(other)), + )), + } +} + +fn truncate(s: &str) -> String { + s.chars().take(32).collect() +} + +/// A required string field; wrong type or missing is `invalid_message`. +fn req_str<'a>(obj: &'a Map, key: &str) -> Result<&'a str, ProtoError> { + match obj.get(key) { + Some(Value::String(s)) => Ok(s), + _ => Err(invalid_message(format!("{key} must be a string"))), + } +} + +/// An optional string field; wrong type is `invalid_message`. +fn opt_str<'a>(obj: &'a Map, key: &str) -> Result, ProtoError> { + match obj.get(key) { + None => Ok(None), + Some(Value::String(s)) => Ok(Some(s)), + Some(_) => Err(invalid_message(format!("{key} must be a string"))), + } +} + +fn parse_hello(obj: &Map) -> Result { + let app = obj + .get("app") + .and_then(Value::as_object) + .ok_or_else(|| invalid_message("app must be an object"))?; + let id = req_str(app, "id")?; + if !is_valid_app_id(id) { + return Err(ProtoError::new( + ErrorCode::InvalidAppId, + "app.id must match ^[a-z0-9][a-z0-9-]{1,31}$", + )); + } + let version = req_str(app, "version")?; + let len = version.chars().count(); + if len == 0 || len > MAX_VERSION { + return Err(invalid_value("app.version must be 1 to 32 characters")); + } + let name = opt_str(app, "name")?; + if name.is_some_and(|n| n.chars().count() > MAX_APP_NAME) { + return Err(invalid_value("app.name is longer than 32 characters")); + } + let url = opt_str(app, "url")?; + if url.is_some_and(|u| u.chars().count() > MAX_APP_URL) { + return Err(invalid_value("app.url is longer than 200 characters")); + } + Ok(AppMsg::Hello(AppInfo { + id: id.to_string(), + version: version.to_string(), + name: name.map(str::to_string), + url: url.map(str::to_string), + })) +} + +fn route_field(obj: &Map) -> Result { + let route = req_str(obj, "route")?; + if !is_valid_route_id(route) { + return Err(ProtoError::new( + ErrorCode::UnknownRoute, + "route is not a valid route ID", + )); + } + Ok(route.to_string()) +} + +fn room_field(obj: &Map) -> Result { + match opt_str(obj, "room")? { + None => Ok(DEFAULT_ROOM.to_string()), + Some(room) if is_valid_room(room) => Ok(room.to_string()), + Some(_) => Err(ProtoError::new( + ErrorCode::InvalidRoom, + "room must match ^[a-z0-9][a-z0-9-]{0,31}$", + )), + } +} + +fn rider_field(obj: &Map) -> Result { + let rider = req_str(obj, "rider")?; + let len = rider.chars().count(); + if len == 0 || len > MAX_RIDER { + return Err(invalid_value("rider must be 1 to 64 characters")); + } + Ok(rider.to_string()) +} + +fn name_field(obj: &Map) -> Result { + let name = req_str(obj, "name")?; + let len = name.chars().count(); + 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")); + } + Ok(name.to_string()) +} + +/// 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 { + let n = v + .as_f64() + .filter(|_| v.is_number()) + .ok_or_else(|| invalid_message(format!("{key} must be a number")))?; + if n.fract() != 0.0 { + return Err(invalid_value(format!("{key} must be an integer"))); + } + if n < min || n > max { + return Err(invalid_value(format!("{key} must be {min} to {max}"))); + } + Ok(n) +} + +fn float_value(v: &Value, key: &str, min: f64, max: f64) -> Result { + let n = v + .as_f64() + .filter(|_| v.is_number()) + .ok_or_else(|| invalid_message(format!("{key} must be a number")))?; + if !n.is_finite() || n < min || n > max { + return Err(invalid_value(format!("{key} must be {min} to {max}"))); + } + Ok(n) +} + +fn required<'a>(obj: &'a Map, key: &str) -> Result<&'a Value, ProtoError> { + obj.get(key).ok_or_else(|| invalid_message(format!("{key} is missing"))) +} + +/// `lap`, `distance`, `speed` and the optional sensor fields. The upper bound of `distance` is the +/// route length, which the caller checks. +fn state_fields(obj: &Map) -> Result { + let lap = int_value(required(obj, "lap")?, "lap", 0.0, f64::from(u32::MAX))? as u32; + let distance = float_value(required(obj, "distance")?, "distance", 0.0, f64::MAX)?; + let speed = float_value(required(obj, "speed")?, "speed", 0.0, 30.0)?; + let optional = |key: &str, min: f64, max: f64| -> Result, ProtoError> { + obj.get(key) + .map(|v| int_value(v, key, min, max).map(|n| n as u16)) + .transpose() + }; + Ok(RiderState { + lap, + distance, + speed, + power: optional("power", 0.0, 3000.0)?, + cadence: optional("cadence", 0.0, 250.0)?, + heart_rate: optional("heart_rate", 20.0, 250.0)?, + }) +} + +/// Parses one entry of an `update`. The error carries `rider` when the entry has a string `rider`. +pub fn parse_update_entry(v: &Value) -> Result { + let obj = v + .as_object() + .ok_or_else(|| invalid_message("update entry must be an object"))?; + let rider_name = obj.get("rider").and_then(Value::as_str).map(str::to_string); + let parse = || -> Result { + Ok(UpdateEntry { + rider: rider_field(obj)?, + state: state_fields(obj)?, + }) + }; + parse().map_err(|e| e.with_rider(rider_name)) +} diff --git a/crates/server/src/riders.rs b/crates/server/src/riders.rs new file mode 100644 index 0000000..4b5c94d --- /dev/null +++ b/crates/server/src/riders.rs @@ -0,0 +1,49 @@ +//! `obn-server riders` — who is riding right now, for the Makefile's guard before `update`, +//! `restart` and `down`. Probes `/v0/stats` like `healthcheck` does, so the runtime image still +//! needs no curl. + +use serde_json::Value; + +/// Reads the rider counts from a `/v0/stats` body. +/// +/// Output: the total on the first line, then one `app_idriders` line per app with riders on +/// it. `None` if the body is not a stats reply. +pub fn summary(stats: &str) -> Option { + let stats: Value = serde_json::from_str(stats).ok()?; + let apps = stats.get("apps")?.as_array()?; + let mut total = 0; + let mut lines = String::new(); + for app in apps { + let riders = app.get("riders").and_then(Value::as_u64).unwrap_or(0); + let id = app.get("id").and_then(Value::as_str).unwrap_or("?"); + total += riders; + if riders > 0 { + lines.push_str(&format!("{id}\t{riders}\n")); + } + } + Some(format!("{total}\n{lines}")) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn lists_riders_per_app() { + let stats = r#"{"apps":[{"id":"openradlr","riders":2,"connections":1}, + {"id":"idle","riders":0,"connections":1},{"id":"incyclist","riders":1,"connections":1}]}"#; + assert_eq!(summary(stats).unwrap(), "3\nopenradlr\t2\nincyclist\t1\n"); + } + + #[test] + fn empty_server_is_just_zero() { + assert_eq!(summary(r#"{"apps":[]}"#).unwrap(), "0\n"); + } + + #[test] + fn rejects_other_replies() { + assert!(summary("not json").is_none()); + assert!(summary(r#"{"name":"x"}"#).is_none()); + assert!(summary(r#"{"apps":3}"#).is_none()); + } +} diff --git a/crates/server/src/routes.rs b/crates/server/src/routes.rs new file mode 100644 index 0000000..476133c --- /dev/null +++ b/crates/server/src/routes.rs @@ -0,0 +1,164 @@ +//! Shared routes (`protocol/spec/v0.md` section 4): loading and validating the route files that the +//! protocol repository publishes under `routes/`. + +use std::collections::BTreeMap; +use std::fs; +use std::path::{Path, PathBuf}; + +use serde::Deserialize; + +use crate::protocol::is_valid_route_id; + +#[derive(Debug, Clone, PartialEq, Deserialize)] +pub struct Route { + pub id: String, + pub name: String, + pub length: f64, + #[serde(rename = "loop")] + pub looped: bool, + pub profile: Vec<[f64; 2]>, +} + +/// The validated routes of one server, keyed by route ID. +#[derive(Debug, Clone)] +pub struct Routes { + by_id: BTreeMap, +} + +impl Routes { + /// Loads every `*.json` file in `dir`, in sorted order. Each file must hold a valid route whose + /// name is `.json`. + pub fn load_dir(dir: &Path) -> Result { + let entries = fs::read_dir(dir).map_err(|e| format!("cannot read {}: {e}", dir.display()))?; + let mut paths: Vec = Vec::new(); + for entry in entries { + let entry = entry.map_err(|e| format!("cannot read {}: {e}", dir.display()))?; + let path = entry.path(); + if path.extension().is_some_and(|ext| ext == "json") { + paths.push(path); + } + } + paths.sort(); + + let mut routes = Vec::new(); + for path in &paths { + let name = path.display(); + let text = fs::read_to_string(path).map_err(|e| format!("{name}: {e}"))?; + let route: Route = serde_json::from_str(&text).map_err(|e| format!("{name}: {e}"))?; + check(&route).map_err(|e| format!("{name}: {e}"))?; + let stem = path.file_stem().and_then(|s| s.to_str()).unwrap_or_default(); + if stem != route.id { + return Err(format!("{name}: file name must be {}.json to match its id", route.id)); + } + routes.push(route); + } + Routes::from_routes(routes) + } + + /// Builds the set from routes already in memory. Each route is checked, and IDs must be unique. + pub fn from_routes(routes: Vec) -> Result { + let mut by_id = BTreeMap::new(); + for route in routes { + check(&route).map_err(|e| format!("route {}: {e}", route.id))?; + if by_id.contains_key(&route.id) { + return Err(format!("duplicate route ID {}", route.id)); + } + by_id.insert(route.id.clone(), route); + } + Ok(Routes { by_id }) + } + + pub fn get(&self, id: &str) -> Option<&Route> { + self.by_id.get(id) + } + + /// The loaded route IDs, sorted. + pub fn ids(&self) -> impl Iterator { + self.by_id.keys().map(String::as_str) + } +} + +/// Checks one route against the profile rules of spec 4.1. +pub fn check(route: &Route) -> Result<(), String> { + if !is_valid_route_id(&route.id) { + return Err(format!("id {:?} is not a valid route ID", route.id)); + } + if !route.length.is_finite() || route.length <= 0.0 { + return Err("length must be greater than 0".to_string()); + } + let (first, last) = match route.profile.as_slice() { + [first, .., last] => (first, last), + _ => return Err("profile needs at least two points".to_string()), + }; + if route.profile.iter().any(|p| !p[0].is_finite() || !p[1].is_finite()) { + return Err("profile values must be finite".to_string()); + } + if first[0] != 0.0 { + return Err("the first profile point must have distance 0".to_string()); + } + if last[0] != route.length { + return Err("the last profile point must have distance equal to length".to_string()); + } + if route.profile.windows(2).any(|pair| pair[1][0] <= pair[0][0]) { + return Err("profile distances must strictly increase".to_string()); + } + if route.looped && first[1] != last[1] { + return Err("on a loop, the first and last elevation must be equal".to_string()); + } + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::*; + + const ROUTES_DIR: &str = concat!(env!("CARGO_MANIFEST_DIR"), "/../../protocol/routes"); + const INVALID_DIR: &str = concat!( + env!("CARGO_MANIFEST_DIR"), + "/../../protocol/tools/fixtures/invalid-routes" + ); + const MISNAMED_DIR: &str = concat!( + env!("CARGO_MANIFEST_DIR"), + "/../../protocol/tools/fixtures/misnamed-route" + ); + + fn read_route(path: &Path) -> Route { + let text = fs::read_to_string(path).unwrap(); + serde_json::from_str(&text).unwrap() + } + + fn velodrome() -> Route { + read_route(&Path::new(ROUTES_DIR).join("velodrome-250.json")) + } + + #[test] + fn loads_velodrome_from_protocol_repo() { + let routes = Routes::load_dir(Path::new(ROUTES_DIR)).unwrap(); + let route = routes.get("velodrome-250").expect("velodrome-250 is loaded"); + assert_eq!(route.length, 250.0); + assert!(route.looped); + } + + #[test] + fn rejects_bad_profiles() { + let mut paths: Vec = fs::read_dir(INVALID_DIR).unwrap().map(|e| e.unwrap().path()).collect(); + paths.sort(); + assert_eq!(paths.len(), 5, "expected the five invalid route fixtures"); + for path in &paths { + let route = read_route(path); + assert!(check(&route).is_err(), "{} should be rejected", path.display()); + } + } + + #[test] + fn rejects_file_name_not_matching_id() { + let err = Routes::load_dir(Path::new(MISNAMED_DIR)).unwrap_err(); + assert!(err.contains("velodrome.json"), "error should name the file: {err}"); + } + + #[test] + fn rejects_duplicate_ids() { + let err = Routes::from_routes(vec![velodrome(), velodrome()]).unwrap_err(); + assert!(err.contains("duplicate"), "unexpected error: {err}"); + } +} diff --git a/crates/server/src/ws.rs b/crates/server/src/ws.rs new file mode 100644 index 0000000..79a8884 --- /dev/null +++ b/crates/server/src/ws.rs @@ -0,0 +1,571 @@ +//! WebSocket endpoint `/v0` and the stats endpoint `/v0/stats`. +//! +//! `presence` is pure and returns addressed deliveries; the [`Hub`] holds one bounded queue per +//! connection and sends them. A connection whose queue is full is dropped, so a slow reader can +//! never block the others. The std mutexes are never held across an `.await`. + +use std::collections::{HashMap, VecDeque}; +use std::net::{IpAddr, SocketAddr}; +use std::sync::atomic::{AtomicU16, AtomicU64, Ordering}; +use std::sync::{Arc, Mutex, MutexGuard}; +use std::time::Duration; + +use axum::extract::ws::{CloseFrame, Message, WebSocket, WebSocketUpgrade}; +use axum::extract::{ConnectInfo, State}; +use axum::http::{header, HeaderMap, StatusCode}; +use axum::response::{IntoResponse, Response}; +use axum::routing::get; +use axum::{Json, Router}; +use futures_util::stream::SplitSink; +use futures_util::{SinkExt, StreamExt}; +use tokio::sync::{mpsc, Notify}; +use tokio::time::Instant; + +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::routes::Routes; + +const QUEUE_CAPACITY: usize = 1024; +const MAX_AXUM_MESSAGE: usize = 1 << 20; +const ERROR_WINDOW: Duration = Duration::from_secs(10); +const MAX_ERRORS_IN_WINDOW: usize = 20; +const CLOSE_POLICY: u16 = 1008; +const CLOSE_UNSUPPORTED: u16 = 1003; +/// How long the writer may take to flush the last frames once the reader is done. +const WRITER_GRACE: Duration = Duration::from_secs(5); + +fn lock(m: &Mutex) -> MutexGuard<'_, T> { + m.lock().unwrap_or_else(|e| e.into_inner()) +} + +/// One bounded outgoing queue per connection, plus a signal that tells its reader to stop when +/// the hub drops the connection. +#[derive(Default)] +pub struct Hub { + queues: Mutex>, + counters: Arc, +} + +/// The sender side of a connection's queue and its "dropped" signal. +type Queue = (mpsc::Sender, Arc); + +impl Hub { + /// A hub that counts its queue-full drops in `counters`. + pub fn new(counters: Arc) -> Hub { + Hub { + queues: Mutex::default(), + counters, + } + } + + pub fn register(&self, conn: ConnId) -> mpsc::Receiver { + let (tx, rx) = mpsc::channel(QUEUE_CAPACITY); + lock(&self.queues).insert(conn, (tx, Arc::new(Notify::new()))); + rx + } + + /// Notified when [`Hub::deliver`] drops the connection because its queue is full. + pub fn dropped_signal(&self, conn: ConnId) -> Option> { + lock(&self.queues).get(&conn).map(|(_, n)| n.clone()) + } + + /// Dropping the sender lets the writer drain what is queued and then see the channel close. + pub fn unregister(&self, conn: ConnId) { + lock(&self.queues).remove(&conn); + } + + pub fn is_registered(&self, conn: ConnId) -> bool { + lock(&self.queues).contains_key(&conn) + } + + /// Never blocks. A connection whose queue is full (or already gone) is unregistered. + pub fn deliver(&self, deliveries: Vec) { + if deliveries.is_empty() { + return; + } + let mut queues = lock(&self.queues); + for d in deliveries { + let Some((tx, dropped)) = queues.get(&d.to) else { + continue; + }; + match tx.try_send(d.msg) { + Ok(()) => {} + Err(mpsc::error::TrySendError::Full(_)) => { + tracing::warn!(conn = %conn_name(d.to), "outgoing queue full, closing connection"); + self.counters.queue_full_drop(); + dropped.notify_one(); + queues.remove(&d.to); + } + Err(mpsc::error::TrySendError::Closed(_)) => { + queues.remove(&d.to); + } + } + } + } +} + +pub struct AppState { + pub config: Config, + pub presence: Mutex, + pub hub: Hub, + pub metrics: Mutex, + /// Counters for `/internal/metrics`, shared with the hub. + pub counters: Arc, + pub ip_counts: Mutex>, + /// The next connection number; connection IDs are `c` + its hex. + pub next_conn: AtomicU64, +} + +impl AppState { + pub fn new(config: Config, routes: Routes, metrics: Metrics) -> Arc { + let presence = Presence::new(routes, config.limits); + let counters = Arc::new(Counters::default()); + Arc::new(AppState { + config, + presence: Mutex::new(presence), + hub: Hub::new(counters.clone()), + metrics: Mutex::new(metrics), + counters, + ip_counts: Mutex::new(HashMap::new()), + next_conn: AtomicU64::new(1), + }) + } +} + +fn conn_name(conn: ConnId) -> String { + format!("c{conn:x}") +} + +/// Background tasks: expire silent riders every second and record rider-minutes every minute. +/// The std mutexes are locked, used and released before anything is awaited. +pub fn spawn_tickers(state: Arc) { + let expiry = state.clone(); + tokio::spawn(async move { + let mut tick = tokio::time::interval(Duration::from_secs(1)); + loop { + tick.tick().await; + let deliveries = lock(&expiry.presence).expire(std::time::Instant::now()); + expiry.hub.deliver(deliveries); + } + }); + tokio::spawn(async move { + let mut tick = tokio::time::interval(Duration::from_secs(60)); + tick.tick().await; // the first tick is immediate; counting starts after a full minute + loop { + tick.tick().await; + let live = lock(&state.presence).live_counts(); + if let Err(e) = lock(&state.metrics).add_minute(&live, &today_utc()) { + tracing::warn!("metrics write failed: {e}"); + } + } + }); +} + +pub fn router(state: Arc) -> Router { + Router::new() + .route("/v0", get(ws_handler)) + .route("/v0/stats", get(stats_handler)) + .route("/healthz", get(healthz)) + .route("/internal/metrics", get(metrics_handler)) + .with_state(state) +} + +async fn healthz() -> &'static str { + "ok" +} + +// This endpoint is intended for the host's private Prometheus network. It only exports aggregate +// counts per app ID (already public via /v0/stats) and server counters; never rider names, rider +// values, IPs or request details. +async fn metrics_handler(State(state): State>) -> ([(header::HeaderName, &'static str); 1], String) { + let live = lock(&state.presence).live_counts(); + let sha = std::env::var("OBN_BUILD_SHA").unwrap_or_else(|_| "dev".to_string()); + let body = render(&live, &state.counters.snapshot(), env!("CARGO_PKG_VERSION"), &sha); + ([(header::CONTENT_TYPE, CONTENT_TYPE)], body) +} + +async fn stats_handler(State(state): State>) -> Response { + let live = lock(&state.presence).live_counts(); + let stats = lock(&state.metrics).stats(&live, &today_utc()); + match stats { + Ok(s) => Json(s).into_response(), + Err(e) => { + tracing::error!("stats query failed: {e}"); + StatusCode::INTERNAL_SERVER_ERROR.into_response() + } + } +} + +/// Releases one slot of the per-IP count when dropped, wherever the connection ends. +struct IpGuard { + state: Arc, + ip: IpAddr, +} + +impl Drop for IpGuard { + fn drop(&mut self) { + let mut counts = lock(&self.state.ip_counts); + if let Some(n) = counts.get_mut(&self.ip) { + *n -= 1; + if *n == 0 { + counts.remove(&self.ip); + } + } + } +} + +fn client_ip(state: &AppState, peer: SocketAddr, headers: &HeaderMap) -> IpAddr { + if state.config.trust_proxy { + // The rightmost entry is the one our own proxy added. + let forwarded = headers + .get("x-forwarded-for") + .and_then(|v| v.to_str().ok()) + .and_then(|v| v.rsplit(',').next()) + .and_then(|v| v.trim().parse::().ok()); + if let Some(ip) = forwarded { + return ip; + } + } + peer.ip() +} + +async fn ws_handler( + State(state): State>, + ConnectInfo(peer): ConnectInfo, + headers: HeaderMap, + ws: WebSocketUpgrade, +) -> Response { + let ip = client_ip(&state, peer, &headers); + { + let mut counts = lock(&state.ip_counts); + let n = counts.entry(ip).or_insert(0); + if *n >= state.config.max_connections_per_ip { + state.counters.rejected_per_ip(); + return StatusCode::TOO_MANY_REQUESTS.into_response(); + } + *n += 1; + } + // Created before the upgrade, so the slot is also released if the upgrade never completes. + let guard = IpGuard { + state: state.clone(), + ip, + }; + ws.max_message_size(MAX_AXUM_MESSAGE) + .on_upgrade(move |socket| handle_socket(state, socket, guard)) +} + +async fn handle_socket(state: Arc, socket: WebSocket, _ip_guard: IpGuard) { + let conn = state.next_conn.fetch_add(1, Ordering::Relaxed); + state.counters.connection_accepted(); + let rx = state.hub.register(conn); + let dropped = state.hub.dropped_signal(conn).expect("just registered"); + let (sink, mut stream) = socket.split(); + let close_code = Arc::new(AtomicU16::new(CLOSE_POLICY)); + let writer = tokio::spawn(write_loop(sink, rx, state.config.ping_interval, close_code.clone())); + + let mut session = Session { + state: state.clone(), + conn, + app: None, + recent_errors: VecDeque::new(), + }; + session.read_loop(&mut stream, &close_code, &dropped).await; + + // Leave presence first (others get `left`), then close our queue; the writer drains it, sends + // the close frame and ends. An unresponsive peer must not hold the task forever. + let deliveries = lock(&state.presence).disconnect(conn); + state.hub.deliver(deliveries); + state.hub.unregister(conn); + let abort = writer.abort_handle(); + if tokio::time::timeout(WRITER_GRACE, writer).await.is_err() { + abort.abort(); + } + tracing::debug!(conn = %conn_name(conn), "connection closed"); +} + +async fn write_loop( + mut sink: SplitSink, + mut rx: mpsc::Receiver, + ping_interval: Duration, + close_code: Arc, +) { + let mut ping = tokio::time::interval_at(Instant::now() + ping_interval, ping_interval); + loop { + tokio::select! { + msg = rx.recv() => { + let Some(msg) = msg else { break }; + let Ok(text) = serde_json::to_string(&msg) else { continue }; + if sink.send(Message::text(text)).await.is_err() { + return; + } + } + _ = ping.tick() => { + if sink.send(Message::Ping(Default::default())).await.is_err() { + return; + } + } + } + } + let frame = CloseFrame { + code: close_code.load(Ordering::Relaxed), + reason: "".into(), + }; + let _ = sink.send(Message::Close(Some(frame))).await; + let _ = sink.close().await; +} + +enum Flow { + Continue, + Close, +} + +struct Session { + state: Arc, + conn: ConnId, + /// Set once `hello` was accepted. + app: Option, + /// When the recent non-fatal errors happened. + recent_errors: VecDeque, +} + +impl Session { + async fn read_loop( + &mut self, + stream: &mut futures_util::stream::SplitStream, + close_code: &AtomicU16, + dropped: &Notify, + ) { + let hello_timeout = self.state.config.hello_timeout; + let pong_timeout = self.state.config.pong_timeout; + let hello_deadline = Instant::now() + hello_timeout; + let mut pong_deadline = Instant::now() + pong_timeout; + loop { + let hello_wait = async { + if self.app.is_none() { + tokio::time::sleep_until(hello_deadline).await + } else { + std::future::pending().await + } + }; + let frame = tokio::select! { + f = stream.next() => f, + _ = hello_wait => { + self.fatal(ProtoError::new(ErrorCode::HelloRequired, "no hello within the time limit")); + return; + } + _ = tokio::time::sleep_until(pong_deadline) => { + tracing::debug!(conn = %conn_name(self.conn), "pong timeout"); + return; + } + // The hub dropped us (queue full): stop reading, so our riders leave now. + _ = dropped.notified() => return, + }; + match frame { + None | Some(Err(_)) | Some(Ok(Message::Close(_))) => return, + Some(Ok(Message::Pong(_))) => pong_deadline = Instant::now() + pong_timeout, + Some(Ok(Message::Ping(_))) => {} + Some(Ok(Message::Binary(_))) => { + close_code.store(CLOSE_UNSUPPORTED, Ordering::Relaxed); + self.state.hub.unregister(self.conn); + return; + } + Some(Ok(Message::Text(text))) => { + if let Flow::Close = self.handle_text(text.as_str()) { + return; + } + } + } + } + } + + fn send_self(&self, msg: ServerMsg) { + self.state.hub.deliver(vec![Delivery { to: self.conn, msg }]); + } + + /// Sends a fatal error and unregisters, so the writer flushes it and then closes the socket. + fn fatal(&self, err: ProtoError) { + self.state.counters.error_sent(err.code); + self.send_self(err.into()); + self.state.hub.unregister(self.conn); + } + + /// 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). + 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; + } + self.state.counters.error_sent(err.code); + self.send_self(err.into()); + Flow::Continue + } + + fn handle_text(&mut self, text: &str) -> Flow { + let limits = self.state.config.limits; + if text.len() > limits.max_message_bytes as usize { + return self.report( + ProtoError::new( + ErrorCode::MessageTooLarge, + format!("messages may be at most {} bytes", limits.max_message_bytes), + ), + &None, + ); + } + let parsed = parse_app_msg(text); + if self.app.is_none() { + return self.handle_first(text, parsed); + } + let env = match parsed { + Ok(env) => env, + Err(e) => { + let ref_ = e.ref_.clone(); + return self.report(e, &ref_); + } + }; + self.dispatch(env.ref_, env.msg) + } + + /// Before `hello`, anything but a valid `hello` is `hello_required`; a `hello` that is itself + /// invalid reports its own error (for example `invalid_app_id`). + fn handle_first(&mut self, text: &str, parsed: Result) -> Flow { + match parsed { + Ok(env) => match env.msg { + AppMsg::Hello(info) => self.hello(info), + _ => self.report( + ProtoError::new(ErrorCode::HelloRequired, "the first message must be hello"), + &env.ref_, + ), + }, + Err(e) => { + let is_hello = serde_json::from_str::(text) + .ok() + .and_then(|v| v.get("type").and_then(|t| t.as_str()).map(|t| t == "hello")) + .unwrap_or(false); + let ref_ = e.ref_.clone(); + if is_hello { + self.report(e, &ref_) + } else { + self.report( + ProtoError::new(ErrorCode::HelloRequired, "the first message must be hello"), + &ref_, + ) + } + } + } + } + + fn hello(&mut self, info: AppInfo) -> Flow { + let state = &self.state; + if let Err(e) = lock(&state.metrics).record_hello(&info.id, &info.version, &today_utc()) { + tracing::warn!(app = %info.id, "recording hello failed: {e}"); + } + tracing::info!(app = %info.id, conn = %conn_name(self.conn), "hello"); + self.app = Some(info.id.clone()); + lock(&state.presence).connect(self.conn, info); + self.send_self(ServerMsg::Welcome { + protocol: "0.1", + connection: conn_name(self.conn), + limits: state.config.limits, + }); + Flow::Continue + } + + fn dispatch(&mut self, ref_: Option, msg: AppMsg) -> Flow { + let state = self.state.clone(); + let conn = self.conn; + let now = std::time::Instant::now(); + let result = match msg { + AppMsg::Hello(_) => Err(ProtoError::new(ErrorCode::HelloRepeated, "hello was already sent")), + AppMsg::Subscribe { route, room } => lock(&state.presence).subscribe(conn, &route, &room), + AppMsg::Unsubscribe { route, room } => { + lock(&state.presence).unsubscribe(conn, &route, &room); + Ok(Vec::new()) + } + 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), + }; + match result { + Ok(deliveries) => { + state.hub.deliver(deliveries); + Flow::Continue + } + Err(e) => self.report(e, &ref_), + } + } + + fn update(&mut self, entries: Vec, ref_: Option, now: std::time::Instant) -> Flow { + let mut errors = Vec::new(); + let mut valid = Vec::new(); + for v in &entries { + match parse_update_entry(v) { + Ok(e) => valid.push(e), + Err(e) => errors.push(e), + } + } + let entries_in = valid.len(); + let (deliveries, more) = lock(&self.state.presence).update(self.conn, valid, now); + // Each rejected entry yields exactly one error. + self.state + .counters + .updates_accepted(entries_in.saturating_sub(more.len())); + self.state.hub.deliver(deliveries); + errors.extend(more); + for e in errors { + if let Flow::Close = self.report(e, &ref_) { + return Flow::Close; + } + } + Flow::Continue + } +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::protocol::LeftReason; + + #[test] + fn full_queue_closes_connection() { + let hub = Hub::default(); + let _rx = hub.register(1); + let dropped = hub.dropped_signal(1).unwrap(); + let msg = || Delivery { + to: 1, + msg: ServerMsg::Left { + route: "r".into(), + room: "public".into(), + id: "r1".into(), + reason: LeftReason::Leave, + }, + }; + for _ in 0..QUEUE_CAPACITY { + hub.deliver(vec![msg()]); + assert!(hub.is_registered(1)); + } + hub.deliver(vec![msg()]); + assert!(!hub.is_registered(1)); + // The reader is told to stop (notify_one keeps the permit until someone waits). + assert!(futures_util::FutureExt::now_or_never(dropped.notified()).is_some()); + // Delivering to a connection that is gone is fine. + hub.deliver(vec![msg()]); + } +} diff --git a/crates/server/tests/protocol_examples.rs b/crates/server/tests/protocol_examples.rs new file mode 100644 index 0000000..3945fe6 --- /dev/null +++ b/crates/server/tests/protocol_examples.rs @@ -0,0 +1,173 @@ +use std::fs; +use std::path::{Path, PathBuf}; + +use obn_server::protocol::*; +use serde_json::{json, Value}; + +const EXAMPLES: &str = concat!(env!("CARGO_MANIFEST_DIR"), "/../../protocol/examples"); + +/// Files in `dir` (relative to the examples directory), sorted by path. +fn json_files(dir: &str) -> Vec { + let path = Path::new(EXAMPLES).join(dir); + let mut files: Vec = fs::read_dir(&path) + .unwrap_or_else(|e| panic!("cannot read {}: {e}", path.display())) + .map(|entry| entry.expect("directory entry").path()) + .filter(|p| p.extension().is_some_and(|e| e == "json")) + .collect(); + files.sort(); + assert!(!files.is_empty(), "no examples in {}", path.display()); + files +} + +fn read(path: &Path) -> String { + fs::read_to_string(path).unwrap_or_else(|e| panic!("cannot read {}: {e}", path.display())) +} + +/// JSON numbers `0` and `0.0` are the same number on the wire, but `serde_json::Value` tells them apart. +fn normalize(v: Value) -> Value { + match v { + Value::Number(n) => json!(n.as_f64().expect("finite number")), + Value::Array(a) => Value::Array(a.into_iter().map(normalize).collect()), + Value::Object(o) => Value::Object(o.into_iter().map(|(k, v)| (k, normalize(v))).collect()), + other => other, + } +} + +/// The first error from parsing the message, or else from its update entries. +fn first_error(text: &str) -> Option { + match parse_app_msg(text) { + Err(e) => Some(e), + Ok(Envelope { + msg: AppMsg::Update(entries), + .. + }) => entries.iter().find_map(|v| parse_update_entry(v).err()), + Ok(_) => None, + } +} + +#[test] +fn valid_app_examples_parse() { + for path in json_files("app") { + let text = read(&path); + let env = parse_app_msg(&text).unwrap_or_else(|e| panic!("{}: {e:?}", path.display())); + if let AppMsg::Update(entries) = env.msg { + for entry in &entries { + parse_update_entry(entry).unwrap_or_else(|e| panic!("{}: {e:?}", path.display())); + } + } + } +} + +#[test] +fn invalid_app_examples_give_their_code() { + for path in json_files("invalid/app") { + let name = path.file_name().unwrap().to_string_lossy().into_owned(); + let code = name.split("--").next().unwrap(); + let err = first_error(&read(&path)).unwrap_or_else(|| panic!("{name}: expected error {code}, got none")); + assert_eq!(err.code.as_str(), code, "{name}: {err:?}"); + } +} + +fn expected(name: &str) -> Value { + let path = Path::new(EXAMPLES).join("server").join(name); + serde_json::from_str(&read(&path)).unwrap_or_else(|e| panic!("{}: {e}", path.display())) +} + +fn check(name: &str, msg: ServerMsg) { + let got = serde_json::to_value(&msg).unwrap(); + assert_eq!(normalize(got), normalize(expected(name)), "{name}"); +} + +#[test] +fn server_messages_match_examples() { + let state = |lap, distance, speed, power| RiderState { + lap, + distance, + speed, + power, + cadence: None, + heart_rate: None, + }; + let view = |s| RiderView { + id: "r7Kx2".into(), + app: "incyclist".into(), + name: "Ben".into(), + state: s, + }; + let route = || "velodrome-250".to_string(); + let room = || "public".to_string(); + + check( + "welcome.json", + ServerMsg::Welcome { + protocol: "0.1", + connection: "c9Qe4".into(), + limits: Limits::default(), + }, + ); + check( + "snapshot.json", + ServerMsg::Snapshot { + route: route(), + room: room(), + riders: vec![view(state(5, 201.3, 12.1, Some(260)))], + }, + ); + check( + "joined.json", + ServerMsg::Joined { + route: route(), + room: room(), + rider: view(state(0, 0.0, 0.0, None)), + }, + ); + check( + "updated.json", + ServerMsg::Updated { + route: route(), + room: room(), + riders: vec![RiderUpdate { + id: "r7Kx2".into(), + state: state(5, 213.4, 12.1, Some(262)), + }], + }, + ); + check( + "left.json", + ServerMsg::Left { + route: route(), + room: room(), + id: "r7Kx2".into(), + reason: LeftReason::Timeout, + }, + ); + check( + "error.json", + ServerMsg::Error { + code: ErrorCode::InvalidValue, + message: "distance must be below 250".into(), + ref_: Some("42".into()), + rider: Some("u-1842".into()), + fatal: false, + }, + ); +} + +#[test] +fn ref_is_kept_on_errors() { + let err = parse_app_msg(r#"{"type":"leave","ref":"7"}"#).unwrap_err(); + assert_eq!(err.code, ErrorCode::InvalidMessage); + assert_eq!(err.ref_.as_deref(), Some("7")); +} + +#[test] +fn room_defaults_to_public() { + let env = parse_app_msg(r#"{"type":"subscribe","route":"velodrome-250"}"#).unwrap(); + match env.msg { + AppMsg::Subscribe { route, room } => { + assert_eq!(route, "velodrome-250"); + assert_eq!(room, "public"); + } + other => panic!("unexpected {other:?}"), + } +} diff --git a/crates/server/tests/ws.rs b/crates/server/tests/ws.rs new file mode 100644 index 0000000..44e6cad --- /dev/null +++ b/crates/server/tests/ws.rs @@ -0,0 +1,362 @@ +//! End-to-end tests over real WebSockets. Nothing here sleeps: every wait is a read with a timeout, +//! and "nothing arrives" is shown by a later message being the next one. + +use std::net::SocketAddr; +use std::path::Path; +use std::time::Duration; + +use futures_util::{SinkExt, StreamExt}; +use obn_server::config::Config; +use obn_server::metrics::Metrics; +use obn_server::protocol::Limits; +use obn_server::routes::Routes; +use obn_server::ws::{router, spawn_tickers, AppState}; +use serde_json::{json, Value}; +use tokio::io::{AsyncReadExt, AsyncWriteExt}; +use tokio::net::TcpStream; +use tokio_tungstenite::tungstenite::Message; +use tokio_tungstenite::{connect_async, MaybeTlsStream, WebSocketStream}; + +type Client = WebSocketStream>; + +const WAIT: Duration = Duration::from_secs(2); + +fn test_config() -> Config { + Config { + hello_timeout: Duration::from_millis(300), + // A rate limit that a round trip always exceeds, so tests need not wait between updates. + limits: Limits { + max_update_hz: 1_000_000, + ..Limits::default() + }, + ..Config::default() + } +} + +async fn start(config: Config) -> SocketAddr { + let routes = Routes::load_dir(Path::new(concat!(env!("CARGO_MANIFEST_DIR"), "/../../protocol/routes"))).unwrap(); + let state = AppState::new(config, routes, Metrics::open_in_memory().unwrap()); + let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap(); + let addr = listener.local_addr().unwrap(); + spawn_tickers(state.clone()); + tokio::spawn(async move { + axum::serve( + listener, + router(state).into_make_service_with_connect_info::(), + ) + .await + .unwrap(); + }); + addr +} + +async fn raw(addr: SocketAddr) -> Client { + let (ws, _) = tokio::time::timeout(WAIT, connect_async(format!("ws://{addr}/v0"))) + .await + .expect("timeout connecting") + .expect("connect failed"); + ws +} + +async fn send(c: &mut Client, v: Value) { + c.send(Message::text(v.to_string())).await.unwrap(); +} + +async fn recv_json(c: &mut Client) -> Value { + recv_json_within(c, WAIT).await +} + +async fn recv_json_within(c: &mut Client, wait: Duration) -> Value { + loop { + match tokio::time::timeout(wait, c.next()).await { + Err(_) => panic!("timed out waiting for a message"), + Ok(None) => panic!("stream ended while waiting for a message"), + Ok(Some(Err(e))) => panic!("socket error while waiting for a message: {e}"), + Ok(Some(Ok(Message::Text(t)))) => return serde_json::from_str(t.as_str()).unwrap(), + Ok(Some(Ok(Message::Close(f)))) => panic!("closed while waiting for a message: {f:?}"), + Ok(Some(Ok(_))) => continue, + } + } +} + +/// The next frame must be a close frame or the end of the stream. +async fn expect_closed(c: &mut Client) { + loop { + match tokio::time::timeout(WAIT, c.next()).await { + Err(_) => panic!("timed out waiting for the close"), + Ok(None) | Ok(Some(Err(_))) | Ok(Some(Ok(Message::Close(_)))) => return, + Ok(Some(Ok(Message::Text(t)))) => panic!("expected close, got {t}"), + Ok(Some(Ok(_))) => continue, + } + } +} + +async fn app(addr: SocketAddr, id: &str) -> Client { + let mut c = raw(addr).await; + send(&mut c, json!({"type":"hello","app":{"id":id,"version":"1.0"}})).await; + let w = recv_json(&mut c).await; + assert_eq!(w["type"], "welcome"); + c +} + +async fn subscribe(c: &mut Client) -> Value { + send(c, json!({"type":"subscribe","route":"velodrome-250","room":"public"})).await; + let s = recv_json(c).await; + assert_eq!(s["type"], "snapshot", "{s}"); + s +} + +fn join_msg(rider: &str) -> Value { + json!({"type":"join","rider":rider,"route":"velodrome-250","room":"public","name":"Anna","lap":0,"distance":0,"speed":0}) +} + +#[tokio::test] +async fn full_lifecycle() { + let addr = start(test_config()).await; + let mut a = app(addr, "app-a").await; + subscribe(&mut a).await; + let mut b = app(addr, "app-b").await; + subscribe(&mut b).await; + send(&mut b, join_msg("u-1")).await; + // Barrier: once B's snapshot arrives, the join has been processed. + subscribe(&mut b).await; + let j = recv_json(&mut a).await; + assert_eq!(j["type"], "joined"); + assert_eq!(j["rider"]["app"], "app-b"); + assert_eq!(j["rider"]["name"], "Anna"); + send( + &mut b, + json!({"type":"update","riders":[{"rider":"u-1","lap":0,"distance":5.5,"speed":9}]}), + ) + .await; + let u = recv_json(&mut a).await; + assert_eq!(u["type"], "updated"); + assert_eq!(u["riders"][0]["id"], j["rider"]["id"]); + assert_eq!(u["riders"][0]["distance"], 5.5); + send(&mut b, json!({"type":"leave","rider":"u-1"})).await; + let l = recv_json(&mut a).await; + assert_eq!(l["type"], "left"); + assert_eq!(l["reason"], "leave"); + assert_eq!(l["id"], j["rider"]["id"]); +} + +#[tokio::test] +async fn welcome_has_limits() { + let addr = start(Config::default()).await; + let mut c = raw(addr).await; + 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["connection"], "c1"); + assert_eq!(w["limits"], serde_json::to_value(Limits::default()).unwrap()); +} + +#[tokio::test] +async fn no_hello_closes() { + let addr = start(test_config()).await; + let mut c = raw(addr).await; + let e = recv_json(&mut c).await; + assert_eq!(e["type"], "error"); + assert_eq!(e["code"], "hello_required"); + assert_eq!(e["fatal"], true); + expect_closed(&mut c).await; +} + +#[tokio::test] +async fn first_message_not_hello_closes() { + let addr = start(test_config()).await; + let mut c = raw(addr).await; + send( + &mut c, + json!({"type":"subscribe","route":"velodrome-250","room":"public"}), + ) + .await; + let e = recv_json(&mut c).await; + assert_eq!(e["code"], "hello_required"); + assert_eq!(e["fatal"], true); + expect_closed(&mut c).await; +} + +#[tokio::test] +async fn invalid_app_id_closes() { + let addr = start(test_config()).await; + let mut c = raw(addr).await; + send(&mut c, json!({"type":"hello","app":{"id":"Bad App","version":"1.0"}})).await; + let e = recv_json(&mut c).await; + assert_eq!(e["code"], "invalid_app_id"); + assert_eq!(e["fatal"], true); + expect_closed(&mut c).await; +} + +#[tokio::test] +async fn second_hello_is_not_fatal() { + let addr = start(test_config()).await; + let mut c = app(addr, "app-a").await; + send(&mut c, json!({"type":"hello","app":{"id":"app-a","version":"1.0"}})).await; + let e = recv_json(&mut c).await; + assert_eq!(e["code"], "hello_repeated"); + assert_eq!(e["fatal"], false); + subscribe(&mut c).await; +} + +#[tokio::test] +async fn oversized_message_closes() { + let addr = start(test_config()).await; + let mut c = app(addr, "app-a").await; + c.send(Message::text("x".repeat(70_000))).await.unwrap(); + let e = recv_json(&mut c).await; + assert_eq!(e["code"], "message_too_large"); + assert_eq!(e["fatal"], true); + expect_closed(&mut c).await; +} + +#[tokio::test] +async fn error_carries_ref() { + let addr = start(test_config()).await; + let mut c = app(addr, "app-a").await; + send(&mut c, json!({"type":"leave","rider":"x","ref":"9"})).await; + let e = recv_json(&mut c).await; + assert_eq!(e["code"], "unknown_rider"); + assert_eq!(e["ref"], "9"); + assert_eq!(e["fatal"], false); +} + +#[tokio::test] +async fn reconnect_gives_new_id() { + let addr = start(test_config()).await; + let mut a = app(addr, "app-a").await; + subscribe(&mut a).await; + let mut b = app(addr, "app-b").await; + send(&mut b, join_msg("u-1")).await; + let j = recv_json(&mut a).await; + assert_eq!(j["rider"]["id"], "r1"); + drop(b); + let l = recv_json(&mut a).await; + assert_eq!(l["type"], "left"); + assert_eq!(l["reason"], "disconnect"); + assert_eq!(l["id"], "r1"); + let mut b = app(addr, "app-b").await; + send(&mut b, join_msg("u-1")).await; + let j = recv_json(&mut a).await; + assert_eq!(j["type"], "joined"); + assert_eq!(j["rider"]["id"], "r2"); +} + +#[tokio::test] +async fn per_ip_limit() { + let mut config = test_config(); + config.max_connections_per_ip = 2; + let addr = start(config).await; + let _a = app(addr, "app-a").await; + let _b = app(addr, "app-b").await; + let err = connect_async(format!("ws://{addr}/v0")).await.unwrap_err(); + match err { + tokio_tungstenite::tungstenite::Error::Http(resp) => assert_eq!(resp.status().as_u16(), 429), + other => panic!("expected an HTTP 429, got {other}"), + } +} + +/// A raw HTTP GET: the status line and headers, then the body. +async fn http_get(addr: SocketAddr, path: &str) -> (String, String) { + let mut tcp = TcpStream::connect(addr).await.unwrap(); + tcp.write_all(format!("GET {path} HTTP/1.1\r\nHost: localhost\r\nConnection: close\r\n\r\n").as_bytes()) + .await + .unwrap(); + let mut buf = Vec::new(); + tokio::time::timeout(WAIT, tcp.read_to_end(&mut buf)) + .await + .expect("timeout reading response") + .unwrap(); + let text = String::from_utf8(buf).unwrap(); + let (head, body) = text.split_once("\r\n\r\n").unwrap(); + (head.to_string(), body.to_string()) +} + +#[tokio::test] +async fn healthz() { + let addr = start(test_config()).await; + let (head, body) = http_get(addr, "/healthz").await; + assert!(head.starts_with("HTTP/1.1 200"), "{head}"); + assert_eq!(body, "ok"); +} + +#[tokio::test] +async fn metrics_endpoint() { + let addr = start(test_config()).await; + let mut b = app(addr, "openradlr").await; + send(&mut b, join_msg("u-1")).await; + // Barrier: the gauges come after the join was processed. + subscribe(&mut b).await; + + let (head, body) = http_get(addr, "/internal/metrics").await; + assert!(head.starts_with("HTTP/1.1 200"), "{head}"); + assert!( + head.to_lowercase() + .contains("content-type: text/plain; version=0.0.4; charset=utf-8"), + "{head}" + ); + assert!(body.contains("obn_riders{app=\"openradlr\"} 1\n"), "{body}"); + assert!(body.contains("obn_connections{app=\"openradlr\"} 1\n"), "{body}"); + assert!(body.contains("obn_connections_total 1\n"), "{body}"); + assert!(body.contains("obn_errors_total{code=\"rate_limited\"} 0\n"), "{body}"); + // Only aggregate counts: no rider names, rider IDs or IPs. + assert!(!body.contains("Anna") && !body.contains("u-1") && !body.contains("127.0.0.1")); + + // An error that is sent shows up in its series. + send(&mut b, json!({"type":"nonsense"})).await; + assert_eq!(recv_json(&mut b).await["code"], "unknown_type"); + let (_, body) = http_get(addr, "/internal/metrics").await; + assert!(body.contains("obn_errors_total{code=\"unknown_type\"} 1\n"), "{body}"); +} + +#[tokio::test] +async fn stats_endpoint() { + let addr = start(test_config()).await; + let mut b = raw(addr).await; + send( + &mut b, + json!({"type":"hello","app":{"id":"openradlr","version":"0.3.1"}}), + ) + .await; + assert_eq!(recv_json(&mut b).await["type"], "welcome"); + send(&mut b, join_msg("u-1")).await; + // Barrier: the snapshot comes after the join was processed. + subscribe(&mut b).await; + + let mut tcp = TcpStream::connect(addr).await.unwrap(); + tcp.write_all(b"GET /v0/stats HTTP/1.1\r\nHost: localhost\r\nConnection: close\r\n\r\n") + .await + .unwrap(); + let mut buf = Vec::new(); + tokio::time::timeout(WAIT, tcp.read_to_end(&mut buf)) + .await + .expect("timeout reading stats") + .unwrap(); + let text = String::from_utf8(buf).unwrap(); + assert!(text.starts_with("HTTP/1.1 200"), "{text}"); + let body = text.split("\r\n\r\n").nth(1).unwrap(); + let v: Value = serde_json::from_str(body).unwrap(); + let app = &v["apps"][0]; + assert_eq!(app["id"], "openradlr"); + assert_eq!(app["connections"], 1); + assert_eq!(app["riders"], 1); +} + +#[tokio::test] +async fn ticker_expires_riders() { + let mut config = test_config(); + config.limits.rider_timeout_s = 1; + let addr = start(config).await; + let mut a = app(addr, "app-a").await; + subscribe(&mut a).await; + let mut b = app(addr, "app-b").await; + send(&mut b, join_msg("u-1")).await; + let j = recv_json(&mut a).await; + assert_eq!(j["type"], "joined"); + // B sends nothing more; the ticker must expire it. + let l = recv_json_within(&mut a, Duration::from_secs(3)).await; + assert_eq!(l["type"], "left"); + assert_eq!(l["reason"], "timeout"); + assert_eq!(l["id"], "r1"); +} diff --git a/deploy/Caddyfile b/deploy/Caddyfile new file mode 100644 index 0000000..18857e2 --- /dev/null +++ b/deploy/Caddyfile @@ -0,0 +1,23 @@ +# HTTPS reverse proxy for public OpenBikeNet servers. +# Caddy fetches and renews certificates automatically and proxies WebSockets. + +{$OBN_DOMAIN} { + encode zstd gzip + + header { + Strict-Transport-Security "max-age=31536000" + X-Content-Type-Options "nosniff" + Referrer-Policy "no-referrer" + } + + # Metrics are for the private Prometheus network only (see the README). + # Using your own reverse proxy instead? Block /internal/* there too, and + # set OBN_TRUST_PROXY=1 so the per-IP limit sees the real client address. + handle /internal/* { + respond 404 + } + + handle { + reverse_proxy server:8080 + } +} diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..6fe17e8 --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,80 @@ +# OpenBikeNet server +# +# make up build and start (http://localhost:8090) +# make update git pull, rebuild, restart +# +# All settings come from .env (see .env.example). Docker Compose reads .env +# automatically for the ${...} values below. + +name: openbikenet + +services: + server: + build: + context: . + dockerfile: Dockerfile + args: + # Exported by the Makefile (git commit and date); `dev` when built by hand. + OBN_BUILD_SHA: ${OBN_BUILD_SHA:-dev} + OBN_BUILD_DATE: ${OBN_BUILD_DATE:-} + image: obn-server:${OBN_IMAGE_TAG:-local} + restart: unless-stopped + environment: + OBN_TRUST_PROXY: ${OBN_TRUST_PROXY:-0} + RUST_LOG: ${RUST_LOG:-info} + ports: + # Defaults to localhost only. Set OBN_HTTP_BIND=0.0.0.0 to expose it. + - "${OBN_HTTP_BIND:-127.0.0.1}:${OBN_HTTP_PORT:-8090}:8080" + networks: + default: + metrics: + aliases: [obn-server] + volumes: + # The routes are baked into the image from the pinned protocol submodule. + # Usage statistics (SQLite), so they survive `make update`. Back this volume up. + - data:/app/data + read_only: true + cap_drop: + - ALL + security_opt: + - no-new-privileges:true + logging: + driver: json-file + options: + max-size: "10m" + max-file: "3" + + # Optional HTTPS for public servers without their own reverse proxy. + # Enable with COMPOSE_PROFILES=tls and OBN_DOMAIN in .env. Behind your own + # Caddy/nginx, leave it off. + caddy: + image: caddy:2-alpine@sha256:70b3180738b46cd88e49b300d790ae448a0aca3f58edef0f000bb57d619a9ab3 + profiles: ["tls"] + restart: unless-stopped + depends_on: + server: + condition: service_healthy + environment: + OBN_DOMAIN: ${OBN_DOMAIN:-localhost} + ports: + - "80:80" + - "443:443" + - "443:443/udp" + volumes: + - ./deploy/Caddyfile:/etc/caddy/Caddyfile:ro + - caddy_data:/data + - caddy_config:/config + logging: + driver: json-file + options: + max-size: "10m" + max-file: "3" + +volumes: + data: + caddy_data: + caddy_config: + +networks: + metrics: + name: openbikenet-metrics diff --git a/docs/design.md b/docs/design.md new file mode 100644 index 0000000..d160a2d --- /dev/null +++ b/docs/design.md @@ -0,0 +1,65 @@ +# Reference server design (protocol v0) + +**Status: draft**, written together with the +[v0 specification](https://github.com/OpenBikeNet/protocol/blob/main/spec/v0.md). The spec says what +the server does. This file says how this implementation is built. + +## Decisions + +- **WebSocket only.** MQTT gives little for a few long-lived backend connections and would add a + broker, a second binding and a second test set. Messages stay transport-neutral, so a binding + can come later. +- **Stateful presence server.** Rider state lives in memory, so late joiners get a snapshot and + riders of dropped apps are removed by the server instead of by every client. The only data on + disk are per-app daily statistics. +- **Rust, axum + tokio**, the same stack as the OpenRadlr server, which is the first app to use it. + +## Modules + +One binary in a Cargo workspace. Each module has one job: + +| Module | Job | Depends on | +|---|---|---| +| `protocol` | message types (serde), field validation, error codes; no I/O | – | +| `routes` | loads `routes/*.json` from the protocol repo (copied in at build time), checks the profile rules | `protocol` | +| `presence` | routes → rooms → riders; join, update, leave, timeout, snapshot; returns the events to send | `protocol`, `routes` | +| `metrics` | live counters per app ID, daily rider-minutes and versions in SQLite, `/v0/stats` | – | +| `ws` | axum WebSocket handler: hello timeout, limits, rate limiting, fan-out, pings, disconnect cleanup | all of the above | + +`presence` is a plain struct with methods that take a message and return the outgoing events. It +has no async code and no clock of its own (the time is passed in), so timeouts are tested without +waiting. + +Fan-out: `presence` returns the messages addressed to each connection, and the `ws` hub sends +them. + +## Testing + +- **Unit (`protocol`):** every example in the protocol repo's `examples/` parses, and each invalid + example gives the documented error code. +- **Unit (`presence`):** late join gets a snapshot, timeout after `rider_timeout_s`, disconnect + removes all riders of a connection, rooms are separate, no echo of own riders, `rider_exists`, + `unknown_rider`, out-of-range values, per-rider rate limit. +- **Integration:** start the server on a random port, connect two WebSocket clients as two apps, + check the full lifecycle of spec section 3.4, plus `/v0/stats`. +- **`obn-fake-app` CLI:** puts N bot riders on a route at a given speed. For manual tests, load + tests and as an example for app developers. + +## First app: OpenRadlr + +Planned separately in the OpenRadlr repository. Outline: + +- The OpenRadlr server opens one outgoing connection, sends `hello` with `app.id = "openradlr"` and + subscribes to `velodrome-250`. +- OpenRadlr gets a 250 m flat oval route in its own look. +- Human riders on that route are sent with `join` and one batched `update` per second from the sim + state. Bots are not sent. +- Remote riders appear as riders without physics, interpolated on the client, with their app name. +- If the connection drops it reconnects with backoff. Local riding is never affected. + +## Order of work + +1. Protocol repo: spec, JSON Schemas for route files and messages, examples, `routes/velodrome-250.json`, + `apps.md`, CI that validates examples and routes. +2. This server. +3. OpenRadlr integration. diff --git a/docs/superpowers/plans/2026-11-06-reference-server-v0.md b/docs/superpowers/plans/2026-11-06-reference-server-v0.md new file mode 100644 index 0000000..d720751 --- /dev/null +++ b/docs/superpowers/plans/2026-11-06-reference-server-v0.md @@ -0,0 +1,439 @@ +# Reference Server v0 Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Build the OpenBikeNet v0 server: WebSocket presence for shared routes, per-app statistics at `/v0/stats`, and an `obn-fake-app` CLI for testing. + +**Architecture:** A Rust workspace with a lib+bin crate `obn-server` and a bin crate `obn-fake-app`. Pure modules (`protocol`, `routes`, `presence`, `metrics`) are tested without a network. `ws` wires them to axum. `presence` returns addressed deliveries (`Vec`), and a `Hub` of per-connection channels sends them. The protocol repo is a git submodule at `protocol/`, which supplies the routes and the test examples. + +**Tech Stack:** Rust (edition 2021, MSRV 1.87), axum 0.8 (`ws`), tokio 1, serde/serde_json, rusqlite 0.40 (`bundled`), time 0.3, tracing; tokio-tungstenite 0.29 and futures-util 0.3 for tests and the fake app. These are the versions OpenRadlr's server uses. + +**Spec:** `protocol/spec/v0.md` (protocol repo, branch `spec-v0-draft`) and `docs/design.md` (this repo). + +## Global Constraints + +- **Prerequisite:** the protocol plan (`protocol/docs/superpowers/plans/2026-11-06-protocol-v0-artifacts.md`) is done. Until the protocol branch is pushed, add the submodule from the local path (`git submodule add ../protocol protocol` run from `/root/projects/OpenBikeNet/server`, then check out `spec-v0-draft` in it). Switch the URL to `https://github.com/OpenBikeNet/protocol` before pushing. +- Work on the branch `design-v0`. Commits end with `Co-Authored-By: Claude Opus 5.5 `. Do not push. +- Workspace settings are copied from OpenRadlr (`/root/projects/Open-Ride/server/Cargo.toml`): `resolver = "2"`, `license = "AGPL-3.0-or-later"`, `rust-version = "1.87"`, `unsafe_code = "forbid"`, clippy `all` warn, and the same release profile. Copy its `rustfmt.toml` too. +- Every change passes `cargo fmt --all -- --check`, `cargo clippy --workspace --all-targets -- -D warnings` and `cargo test --workspace`. +- Spec values: protocol minor version `"0.1"`; limits `max_update_hz` 4, `rider_timeout_s` 10, `max_riders` 200, `max_subscriptions` 16, `max_message_bytes` 65536; 10 connections per IP; `hello` within 10 s; ping every 15 s; close after 30 s without a pong; default room `public`; server rider IDs and connection IDs at most 16 characters. +- Choices the spec leaves open, decided here: rider IDs are `r` + the lowercase hex of a counter starting at 1 (`r1`, `r2`, …), and connection IDs are `c` + hex. A rider entry is rate-limited if it comes less than `0.8 × 1000 / max_update_hz` ms (200 ms) after that rider's last accepted state; the 0.8 allows for network jitter. More than 20 non-fatal errors within 10 s means `too_many_errors`. Each connection's outgoing queue holds 1024 messages, and a connection whose queue is full is closed. +- Error mapping (applies everywhere): a missing field or wrong JSON type → `invalid_message`; a number that is out of range or not an integer where an integer is required, a string that is too long or too short, or a name with control characters → `invalid_value`; a bad app ID format → `invalid_app_id`; a bad room format → `invalid_room`; an unknown or malformed route ID → `unknown_route`. +- Privacy (spec 10): log app IDs and connection IDs, never names, rider values or IP addresses. Only `metrics` writes to disk. + +## Review Focus + +1. **Two apps use the same rider value** (both call their rider `u-1`). Riders are scoped per connection, so the two must not collide. Test `same_rider_value_on_two_connections` (Task 3). +2. **A rider exactly on the start line at the wrong end** (`distance` 250 on the 250 m velodrome) must be `invalid_value`, while 249.99 is fine. Test `distance_equal_to_length_is_rejected` (Task 4). +3. **An app reconnects after a drop.** Others get `left` with `disconnect`, and the rejoined rider gets a new ID. Test `reconnect_gives_new_id` (Task 6). +4. **A slow app stops reading.** The server must not block other connections: `Hub::deliver` drops it instead. Test `full_queue_closes_connection` (Task 6). +5. **Joining a rider on a second route without leaving first** must give `rider_exists`, not a silent move. Test `join_twice_on_other_route` (Task 3). + +--- + +### Task 1: Workspace, submodule, CI and `protocol` module + +**Files:** +- Create: `Cargo.toml` (workspace), `rustfmt.toml`, `.gitignore` (`target/`, `*.sqlite`), `.gitmodules` (via `git submodule add`) +- Create: `crates/server/Cargo.toml` (package `obn-server`, lib + `[[bin]] obn-server`), `crates/server/src/lib.rs`, `crates/server/src/main.rs` (empty `fn main() {}` for now) +- Create: `crates/server/src/protocol.rs` +- Test: `crates/server/tests/protocol_examples.rs` +- Create: `.github/workflows/ci.yml` + +**Interfaces:** +- Produces (`obn_server::protocol`): + - `enum ErrorCode` with the 14 codes of spec 7.6, serialized in snake_case; `fn as_str(self) -> &'static str`; `fn fatal(self) -> bool` (true for `hello_required`, `invalid_app_id`, `message_too_large`, `too_many_errors`) + - `struct ProtoError { code: ErrorCode, message: String, rider: Option, ref_: Option }` + - `struct AppInfo { id: String, version: String, name: Option, url: Option }` + - `struct RiderState { lap: u32, distance: f64, speed: f64, power: Option, cadence: Option, heart_rate: Option }` (Serialize; `None` fields skipped) + - `struct Join { rider: String, route: String, room: String, name: String, state: RiderState }` + - `struct UpdateEntry { rider: String, state: RiderState }` + - `enum AppMsg { Hello(AppInfo), Subscribe { route: String, room: String }, Unsubscribe { route: String, room: String }, Join(Join), Update(Vec), Leave { rider: String } }` + - `struct Envelope { ref_: Option, msg: AppMsg }` + - `fn parse_app_msg(text: &str) -> Result`: checks all fields except the `update` entries and route existence; a missing `room` becomes `"public"` + - `fn parse_update_entry(v: &serde_json::Value) -> Result`: sets `rider` on the error when the entry has a string `rider` + - `struct Limits { max_update_hz: u32, rider_timeout_s: u32, max_riders: u32, max_subscriptions: u32, max_message_bytes: u32 }`, Serialize, `impl Default` with the spec values + - `enum LeftReason { Leave, Timeout, Disconnect }` (snake_case) + - `struct RiderView { id: String, app: String, name: String, #[serde(flatten)] state: RiderState }`, `struct RiderUpdate { id: String, #[serde(flatten)] state: RiderState }` + - `enum ServerMsg` (`#[serde(tag = "type", rename_all = "snake_case")]`): `Welcome { protocol: &'static str, connection: String, limits: Limits }`, `Snapshot { route, room, riders: Vec }`, `Joined { route, room, rider: RiderView }`, `Updated { route, room, riders: Vec }`, `Left { route, room, id, reason: LeftReason }`, `Error { code: ErrorCode, message: String, #[serde(rename = "ref")] ref_: Option, rider: Option, fatal: bool }` (`None` fields skipped) + - `impl From for ServerMsg` + - `fn is_valid_app_id(s: &str) -> bool`, `fn is_valid_room(s: &str) -> bool`, `fn is_valid_route_id(s: &str) -> bool` (hand-written checks for the spec patterns, no regex crate) + +- [ ] **Step 1: Set up the workspace, the submodule and CI** + +`git submodule add ../protocol protocol` (see Global Constraints), workspace files, and dependencies: `serde`, `serde_json` now; the rest when a task needs them. `ci.yml` is OpenRadlr's `server` job with the same pinned action SHAs (`/root/projects/Open-Ride/.github/workflows/ci.yml`), plus `with: submodules: true` on checkout and no `working-directory`. + +Run: `cargo build --workspace` +Expected: builds. + +- [ ] **Step 2: Write the failing tests in `tests/protocol_examples.rs`** + +```rust +const EXAMPLES: &str = concat!(env!("CARGO_MANIFEST_DIR"), "/../../protocol/examples"); + +#[test] +fn valid_app_examples_parse() // every file in examples/app: parse_app_msg is Ok, + // and for update every entry passes parse_update_entry + +#[test] +fn invalid_app_examples_give_their_code() // for every examples/invalid/app/--*.json: + // the first error from parse_app_msg, or else from the update entries, + // has code.as_str() == + +#[test] +fn server_messages_match_examples() // build welcome (connection "c9Qe4", Limits::default()), + // snapshot, joined, updated, left, error with the values of examples/server/*.json, + // serialize, compare as serde_json::Value to the file + +#[test] +fn ref_is_kept_on_errors() // parse_app_msg(r#"{"type":"leave","ref":"7"}"#) + // -> Err with code InvalidMessage and ref_ == Some("7") + +#[test] +fn room_defaults_to_public() // subscribe without room -> room == "public" +``` + +- [ ] **Step 3: Run the tests** + +Run: `cargo test -p obn-server --test protocol_examples` +Expected: compile errors (the module doesn't exist yet). + +- [ ] **Step 4: Implement `protocol.rs`** + +Parse to `serde_json::Value` first. Pull out `ref` (a string of at most 64 characters, otherwise `invalid_value`) and `type` (missing or not a string → `invalid_message`; unknown → `unknown_type`), then read the fields by hand following the error mapping in Global Constraints. Don't use serde-derive `Deserialize` for app messages: its errors don't separate `invalid_message` from `invalid_value`. + +- [ ] **Step 5: Run the tests** + +Run: `cargo test -p obn-server --test protocol_examples` +Expected: PASS. Then run fmt and clippy as in Global Constraints and expect them clean. + +- [ ] **Step 6: Commit** + +```bash +git add . +git commit -m "Add workspace, protocol submodule and protocol module" +``` + +### Task 2: `routes` module + +**Files:** +- Create: `crates/server/src/routes.rs` + +**Interfaces:** +- Consumes: `protocol::is_valid_route_id`. +- Produces: + - `struct Route { id: String, name: String, length: f64, #[serde(rename = "loop")] looped: bool, profile: Vec<[f64; 2]> }` (Deserialize) + - `struct Routes` with `fn load_dir(dir: &Path) -> Result`, `fn from_routes(routes: Vec) -> Result` and `fn get(&self, id: &str) -> Option<&Route>` + - `fn check(route: &Route) -> Result<(), String>`: the profile rules of spec 4.1 (first distance 0, last distance = `length`, strictly increasing distances, equal end elevations on a loop, valid ID) + +- [ ] **Step 1: Write the failing unit tests (in `routes.rs`)** + +- `loads_velodrome_from_protocol_repo`: `load_dir("/../../protocol/routes")` has `velodrome-250` with `length == 250.0` and `looped`. +- `rejects_bad_profiles`: `check` gives `Err` for each of the five defects in the protocol repo's `tools/fixtures/invalid-routes/` (load them from there). +- `rejects_file_name_not_matching_id` and `rejects_duplicate_ids`. + +- [ ] **Step 2: Run them** + +Run: `cargo test -p obn-server routes` +Expected: compile errors, or FAIL. + +- [ ] **Step 3: Implement `routes.rs`** + +`load_dir` reads every `*.json` file, deserializes it, runs `check`, compares the file stem with `id`, and errors on duplicates. Error strings name the file. + +- [ ] **Step 4: Run the tests** + +Run: `cargo test -p obn-server routes` +Expected: PASS. + +- [ ] **Step 5: Commit** + +```bash +git add crates/server/src +git commit -m "Add routes module" +``` + +### Task 3: `presence`: connections, subscriptions, join, leave, disconnect + +**Files:** +- Create: `crates/server/src/presence.rs` +- Modify: `docs/design.md` (Modules: replace the "Fan-out: each room has a `tokio::sync::broadcast` channel…" paragraph with: `presence` returns the messages addressed to each connection, and the `ws` hub sends them) + +**Interfaces:** +- Consumes: `protocol::{AppInfo, Join, RiderState, RiderView, ServerMsg, LeftReason, ProtoError, ErrorCode, Limits}`, `routes::Routes`. +- Produces: + - `type ConnId = u64` + - `struct Delivery { to: ConnId, msg: ServerMsg }` + - `struct AppCounts { connections: u32, riders: u32 }` + - `struct Presence` with: + - `fn new(routes: Routes, limits: Limits) -> Self` + - `fn connect(&mut self, conn: ConnId, app: AppInfo)` + - `fn subscribe(&mut self, conn: ConnId, route: &str, room: &str) -> Result, ProtoError>` (the snapshot for `conn`) + - `fn unsubscribe(&mut self, conn: ConnId, route: &str, room: &str)` + - `fn join(&mut self, conn: ConnId, join: Join, now: Instant) -> Result, ProtoError>` + - `fn leave(&mut self, conn: ConnId, rider: &str) -> Result, ProtoError>` + - `fn disconnect(&mut self, conn: ConnId) -> Vec` + - `fn live_counts(&self) -> BTreeMap` (keyed by app ID) + + Errors leave `ref_` as `None`; the caller sets it. Subscribers are kept in a `BTreeSet` so delivery order is deterministic. Riders without a `connect` are a programming error (`debug_assert`). + +- [ ] **Step 1: Write the failing unit tests** + +Use a helper `fn presence() -> Presence` (with the velodrome loaded from the submodule, as in Task 2) and `fn join_msg(rider, name) -> Join` at distance 0. + +- `late_subscriber_gets_snapshot`: conn 1 joins `u-1` "Anna"; conn 2 subscribes → one `Snapshot` to 2 with one rider `{id: "r1", app: , name: "Anna"}`. +- `snapshot_excludes_own_riders`: conn 1 joins, conn 1 subscribes → the snapshot has no riders. +- `join_notifies_other_subscribers_only`: conns 1 and 2 are subscribed, 1 joins → exactly one `Joined`, to 2. +- `rooms_are_separate`: a subscriber to room `a` gets nothing for a join in `public`. +- `same_rider_value_on_two_connections`: conns 1 and 2 both join `u-1` → both Ok, with IDs `r1` and `r2`. +- `join_twice_on_other_route`: a second join of `u-1` on conn 1 (with a second test route loaded through `Routes::from_routes`) → `RiderExists`. +- `join_unknown_route` → `UnknownRoute`; `subscribe_unknown_route` → `UnknownRoute`. +- `join_limit`: with `Limits { max_riders: 2, .. }`, the third join → `LimitExceeded`; likewise `max_subscriptions` for subscribe. +- `leave_notifies_with_reason_leave`; `leave_unknown_rider` → `UnknownRider`. +- `disconnect_removes_riders_and_subscriptions`: conn 1 has two riders and conn 2 is subscribed → two `Left { reason: Disconnect }` to 2; afterwards `live_counts` has no entry for conn 1's app. +- `unsubscribe_stops_events`. +- `live_counts_per_app`: two connections with the same app ID and three riders → `{connections: 2, riders: 3}`. + +- [ ] **Step 2: Run them** + +Run: `cargo test -p obn-server presence` +Expected: FAIL (does not compile). + +- [ ] **Step 3: Implement these methods of `Presence`** + +`join` checks the rider state against the route (`distance < length`, else `InvalidValue` with `rider` set). Each rider stores its `RiderState`, the time of its last state (`now`), and its server ID. + +- [ ] **Step 4: Run the tests** + +Run: `cargo test -p obn-server presence` +Expected: PASS. + +- [ ] **Step 5: Update `docs/design.md` as in Files, then commit** + +```bash +git add crates/server/src docs/design.md +git commit -m "Add presence: subscriptions, join, leave, disconnect" +``` + +### Task 4: `presence`: update, rate limit, timeout + +**Files:** +- Modify: `crates/server/src/presence.rs` + +**Interfaces:** +- Consumes: Task 3, `protocol::{UpdateEntry, RiderUpdate}`. +- Produces: + - `fn update(&mut self, conn: ConnId, entries: Vec, now: Instant) -> (Vec, Vec)`: one `Updated` per route+room per call, sent to every subscriber except `conn`, holding the accepted entries of that room + - `fn expire(&mut self, now: Instant) -> Vec`: removes riders whose last state is older than `rider_timeout_s`, with reason `Timeout` + +- [ ] **Step 1: Write the failing unit tests** + +- `update_batches_per_room`: conn 1 has riders in `public` (×2) and `a` (×1), and conn 2 is subscribed to both → one call gives two `Updated` to conn 2, one with 2 riders and one with 1. +- `update_no_echo`: conn 1 is subscribed itself and gets nothing. +- `distance_equal_to_length_is_rejected`: distance 250.0 → one `InvalidValue` error with `rider == Some("u-1")`, and no delivery; 249.99 → delivered. +- `bad_entry_does_not_block_others`: two entries, one with an unknown rider → one `UnknownRider` error, and the other is delivered. +- `rate_limit`: updates at t0, t0+150 ms and t0+200 ms → the second gives `RateLimited`, the third is accepted. +- `timeout_after_rider_timeout_s`: a join at t0; `expire(t0 + 9.9 s)` → nothing; `expire(t0 + 10 s)` → `Left { reason: Timeout }`. An update at t0 + 5 s pushes the timeout to t0 + 15 s. +- `optional_fields_only_when_sent`: an entry without `power` gives a `RiderUpdate` with `state.power == None`. + +- [ ] **Step 2: Run them** + +Run: `cargo test -p obn-server presence` +Expected: the new tests FAIL. + +- [ ] **Step 3: Implement `update` and `expire`** + +- [ ] **Step 4: Run the tests** + +Run: `cargo test -p obn-server presence` +Expected: PASS. + +- [ ] **Step 5: Commit** + +```bash +git add crates/server/src/presence.rs +git commit -m "Add presence updates, rate limit and timeouts" +``` + +### Task 5: `metrics` module + +**Files:** +- Create: `crates/server/src/metrics.rs` +- Modify: `crates/server/Cargo.toml` (`rusqlite = { version = "0.40", features = ["bundled"] }`, `time = "0.3"`) + +**Interfaces:** +- Consumes: `presence::AppCounts`. +- Produces: + - `struct Metrics` with: + - `fn open(path: &Path) -> rusqlite::Result`, `fn open_in_memory() -> rusqlite::Result` (both create the tables) + - `fn record_hello(&self, app: &str, version: &str, day: &str) -> rusqlite::Result<()>`: sets `first_seen` if it's a new app, sets `last_seen`, records the version for that day + - `fn add_minute(&self, live: &BTreeMap, day: &str) -> rusqlite::Result<()>`: adds each app's `riders` to that day's rider-minutes, and sets `last_seen = day` for apps with `connections > 0` + - `fn stats(&self, live: &BTreeMap, today: &str) -> rusqlite::Result` + - `struct Stats { apps: Vec }` and `struct AppStats { id, versions: Vec, connections: u32, riders: u32, first_seen: String, last_seen: String, rider_minutes_30d: u64 }`, Serialize; apps sorted by ID, versions sorted + - `fn today_utc() -> String` (`time::OffsetDateTime::now_utc().date()`, formatted as `YYYY-MM-DD`) + +Tables: `apps(id TEXT PRIMARY KEY, first_seen TEXT, last_seen TEXT)`, `versions(app TEXT, version TEXT, last_day TEXT, PRIMARY KEY(app, version))`, `minutes(app TEXT, day TEXT, minutes INTEGER, PRIMARY KEY(app, day))`. The 30-day window is `day >= date(today, '-29 days')` in SQL, and the same for versions. + +- [ ] **Step 1: Write the failing unit tests** + +- `stats_matches_spec_example`: `record_hello("openradlr", "0.3.1", "2026-11-20")`, then `add_minute` once on 2026-11-20 with `{openradlr: {connections: 1, riders: 412}}` and once on 2026-11-21 with `{openradlr: {connections: 1, riders: 400}}`, then `stats(live = {openradlr: {connections: 1, riders: 4}}, "2026-11-21")` → serialized, it equals `protocol/examples/stats.json`. +- `minutes_older_than_30_days_drop_out`: minutes on 2026-10-01 don't count for today 2026-11-21. +- `apps_without_live_connection_show_zero`. +- `reopen_keeps_data`: write to a temp file, reopen it, the stats are the same. + +- [ ] **Step 2: Run them** + +Run: `cargo test -p obn-server metrics` +Expected: FAIL. + +- [ ] **Step 3: Implement `metrics.rs`** + +- [ ] **Step 4: Run the tests** + +Run: `cargo test -p obn-server metrics` +Expected: PASS. + +- [ ] **Step 5: Commit** + +```bash +git add crates/server +git commit -m "Add per-app metrics in SQLite" +``` + +### Task 6: `ws`: config, hub, connection handling, `/v0/stats` + +**Files:** +- Create: `crates/server/src/config.rs`, `crates/server/src/ws.rs` +- Modify: `crates/server/Cargo.toml` (axum with `ws`, tokio, futures-util, tracing; dev: tokio-tungstenite) +- Test: `crates/server/tests/ws.rs` + +**Interfaces:** +- Consumes: all earlier modules. +- Produces: + - `struct Config { bind: SocketAddr, routes_dir: PathBuf, db_path: PathBuf, trust_proxy: bool, hello_timeout: Duration, ping_interval: Duration, pong_timeout: Duration, max_connections_per_ip: u32, limits: Limits }` with `fn from_env() -> Result` (`OBN_BIND` default `0.0.0.0:8080`, `OBN_ROUTES_DIR` default `protocol/routes`, `OBN_DB` default `obn.sqlite`, `OBN_TRUST_PROXY=1` turns on trust in the `X-Forwarded-For` header) and `impl Default` with the spec values + - `struct Hub` with `fn register(&self, conn: ConnId) -> mpsc::Receiver` (capacity 1024), `fn unregister(&self, conn: ConnId)`, `fn deliver(&self, deliveries: Vec)` (uses `try_send`; when a queue is full, it unregisters that connection, so its writer sees the channel close and closes the socket) + - `struct AppState { config, presence: Mutex, hub: Hub, metrics: Mutex, ip_counts: Mutex>, next_conn: AtomicU64 }`, where `Mutex` is `std::sync::Mutex`, never held across `.await` + - `fn router(state: Arc) -> axum::Router` with `GET /v0` (WebSocket upgrade) and `GET /v0/stats` (JSON from `metrics.stats(presence.live_counts(), today_utc())`). The caller serves it with `into_make_service_with_connect_info::()`. + +Each connection does the following: +- Per-IP limit at upgrade: over the limit → HTTP 429. +- Set axum's `max_message_size` to 1 MiB and check `text.len() > limits.max_message_bytes` yourself, so that `message_too_large` can be sent before the close. +- The writer task drains the `Hub` receiver into the socket. The reader loop handles messages in this order: the hello timeout (`hello_required`), then `hello` → `presence.connect` + `metrics.record_hello` + `Welcome`, then dispatch. +- For `Update`, parse each entry with `parse_update_entry`, send its errors, and pass the valid ones to `presence.update`. +- Every `ProtoError` gets the envelope's `ref` and goes to the connection itself. A fatal error is sent, then the socket is closed with close code 1008. +- More than 20 non-fatal errors in 10 s → `too_many_errors` (fatal). A binary frame → close 1003. +- Pings every `ping_interval`; close if no pong for `pong_timeout`. +- On any exit: `presence.disconnect` → `hub.deliver`, `hub.unregister`, and decrement the IP count. + +- [ ] **Step 1: Write the failing integration tests in `tests/ws.rs`** + +Use a helper `async fn start(config: Config) -> SocketAddr`: it binds `127.0.0.1:0`, uses in-memory metrics and the submodule routes, and spawns `axum::serve`. Another helper `async fn app(addr, id) -> Client` connects and does hello/welcome. Tests use `hello_timeout: 300 ms` and similar short timings. + +- `full_lifecycle`: A subscribes; B hellos, subscribes, joins `u-1`, and sends one update; A gets `Joined` then `Updated`; B sends leave; A gets `Left { reason: "leave" }`. +- `welcome_has_limits`: the `welcome` limits equal `Limits::default()` serialized, and `protocol == "0.1"`. +- `no_hello_closes`: connect, send nothing → `error hello_required, fatal: true`, then close. +- `first_message_not_hello_closes`: subscribe first → `hello_required`. +- `invalid_app_id_closes`. +- `second_hello_is_not_fatal`: a second `hello` → `error hello_repeated, fatal: false`, and the connection stays usable (a following subscribe gets a snapshot). +- `oversized_message_closes`: 70 000 bytes of text → `message_too_large`. +- `error_carries_ref`: `{"type":"leave","rider":"x","ref":"9"}` → `unknown_rider` with `ref == "9"`. +- `reconnect_gives_new_id`: B joins (gets ID `r1` at A) and drops its socket; A gets `Left { reason: "disconnect" }`; B reconnects and rejoins `u-1` → A gets `Joined` with `id == "r2"`. +- `per_ip_limit`: with `max_connections_per_ip: 2`, the third upgrade fails with HTTP 429. +- `stats_endpoint`: after B's hello as `openradlr` with one joined rider, `GET /v0/stats` (use a raw tokio `TcpStream` with an HTTP/1.1 request, or add `reqwest` as a dev-dependency) shows `connections: 1, riders: 1`. +- `full_queue_closes_connection` (unit test in `ws.rs`): register conn 1, deliver 1025 messages without reading → conn 1 is no longer registered and the 1025th `deliver` doesn't panic. + +- [ ] **Step 2: Run them** + +Run: `cargo test -p obn-server --test ws` +Expected: FAIL (does not compile). + +- [ ] **Step 3: Implement `config.rs` and `ws.rs`** + +- [ ] **Step 4: Run all tests** + +Run: `cargo test --workspace` +Expected: PASS. Then fmt and clippy clean. + +- [ ] **Step 5: Commit** + +```bash +git add crates/server +git commit -m "Add WebSocket handling, hub and stats endpoint" +``` + +### Task 7: Binary, tickers and README + +**Files:** +- Modify: `crates/server/src/main.rs`, `crates/server/src/lib.rs` +- Modify: `README.md` (status line plus a "Running it" section) + +**Interfaces:** +- Consumes: `Config::from_env`, `Routes::load_dir`, `Metrics::open`, `router`, `AppState`. +- Produces: `pub fn spawn_tickers(state: Arc)` in `ws.rs`: every 1 s `presence.expire(Instant::now())` → `hub.deliver`; every 60 s `metrics.add_minute(presence.live_counts(), today_utc())`. + +- [ ] **Step 1: Write the failing test** + +`ticker_expires_riders` in `tests/ws.rs`: with `limits.rider_timeout_s: 1`, B joins and then sends nothing. A gets `Left { reason: "timeout" }` within 3 s. + +- [ ] **Step 2: Run it** + +Run: `cargo test -p obn-server --test ws ticker_expires_riders` +Expected: FAIL (no `Left` arrives). + +- [ ] **Step 3: Implement `spawn_tickers` and `main`** + +`main` sets up `tracing_subscriber` with `env-filter` (default `info`), loads the config, routes and metrics (an error → print it and exit 1), calls `spawn_tickers`, and serves with a graceful shutdown on Ctrl-C/SIGTERM. Log the address and the loaded route IDs at startup. + +- [ ] **Step 4: Run all tests and a manual start** + +Run: `cargo test --workspace` +Expected: PASS. +Run: `cargo run -p obn-server`, and in another shell `curl -s localhost:8080/v0/stats` +Expected: `{"apps":[]}`. + +- [ ] **Step 5: Update the README and commit** + +README: change "Status: not started" to "Status: early draft, implements protocol v0", and add a "Running it" section (clone with `--recurse-submodules`, `cargo run -p obn-server`, the four `OBN_*` variables with their defaults, `cargo run -p obn-fake-app -- --riders 3`). + +```bash +git add crates/server README.md +git commit -m "Add server binary with timeout and metrics tickers" +``` + +### Task 8: `obn-fake-app` CLI + +**Files:** +- Create: `crates/fake-app/Cargo.toml` (package `obn-fake-app`; deps tokio, tokio-tungstenite, futures-util, serde_json) +- Create: `crates/fake-app/src/main.rs` + +**Interfaces:** +- Consumes: nothing from `obn-server` on purpose. It builds JSON with `serde_json::json!`, so it reads like what another developer would write. +- Produces: the CLI `obn-fake-app [--url ws://127.0.0.1:8080/v0] [--route velodrome-250] [--length 250] [--riders 3] [--speed 11.0] [--app fake-app]`. It sends `hello` (version from `CARGO_PKG_VERSION`), `subscribe`, a `join` for each rider (`bot-1`…, names `Bot 1`…, spaced evenly around the lap), then one batched `update` per second. It prints a line for each `joined`/`left`/`error` it receives, and on Ctrl-C sends `leave` for every rider and exits. + `fn advance(lap: u32, distance: f64, speed: f64, dt: f64, length: f64) -> (u32, f64)` + +- [ ] **Step 1: Write the failing unit tests for `advance`** + +- `advance(0, 100.0, 10.0, 1.0, 250.0) == (0, 110.0)` +- `advance(0, 245.0, 10.0, 1.0, 250.0) == (1, 5.0)` +- `advance(2, 249.0, 10.0, 1.0, 250.0) == (3, 9.0)` + +- [ ] **Step 2: Run them** + +Run: `cargo test -p obn-fake-app` +Expected: FAIL. + +- [ ] **Step 3: Implement `advance` and the CLI (args parsed by hand, no clap)** + +- [ ] **Step 4: Run the tests and a manual end-to-end check** + +Run: `cargo test --workspace` +Expected: PASS. +Run the server, then `cargo run -p obn-fake-app -- --riders 2 --app fake-a` and, in a third shell, `cargo run -p obn-fake-app -- --riders 1 --app fake-b`. +Expected: the second fake app prints `joined` for `Bot 1` and `Bot 2` of `fake-a`, and `curl -s localhost:8080/v0/stats` lists `fake-a` with `riders: 2` and `fake-b` with `riders: 1`. After Ctrl-C on `fake-a`, the other one prints two `left … leave` lines. + +- [ ] **Step 5: Commit** + +```bash +git add crates/fake-app Cargo.toml Cargo.lock +git commit -m "Add obn-fake-app CLI" +``` diff --git a/protocol b/protocol new file mode 160000 index 0000000..a557731 --- /dev/null +++ b/protocol @@ -0,0 +1 @@ +Subproject commit a557731beb0c2e364814a7440ae2309b3c631511 diff --git a/rustfmt.toml b/rustfmt.toml new file mode 100644 index 0000000..7530651 --- /dev/null +++ b/rustfmt.toml @@ -0,0 +1 @@ +max_width = 120 diff --git a/tools/env-sync.sh b/tools/env-sync.sh new file mode 100755 index 0000000..4616a33 --- /dev/null +++ b/tools/env-sync.sh @@ -0,0 +1,57 @@ +#!/bin/sh +# Adds settings that are new in .env.example to an existing .env. +# +# tools/env-sync.sh [example] [env] (defaults: .env.example .env) +# +# Only keys missing from .env are appended, each with the comment block that +# explains it in the example. Lines already in .env, including your values and +# comments, are never changed. A key counts as present when .env assigns it +# (KEY=...); commented-out keys don't count. Running it twice adds nothing. +set -eu + +example=${1:-.env.example} +env=${2:-.env} + +[ -f "$example" ] || { echo "env-sync: $example not found" >&2; exit 1; } +[ -f "$env" ] || { echo "env-sync: $env not found" >&2; exit 1; } + +key_re='^[A-Za-z_][A-Za-z0-9_]*=' + +added=$(awk -v key_re="$key_re" ' + # First file (.env): remember the keys it assigns. + FNR == NR { + if ($0 ~ key_re) { k = $0; sub(/=.*/, "", k); have[k] = 1 } + next + } + # Second file (.env.example): collect comment blocks, print a block with + # the first missing key that follows it. + $0 ~ key_re { + k = $0; sub(/=.*/, "", k) + if (!(k in have)) { + if (block != "") { printf "%s", block; block = "" } + print + have[k] = 1 + } else { + block = "" + } + next + } + # Blank line after a key ends the previous group; start a fresh block. + /^[[:space:]]*$/ { if (block != "") block = block "\n"; next } + { block = block $0 "\n" } +' "$env" "$example") + +if [ -z "$added" ]; then + exit 0 +fi + +{ + # Keep a newline between the old last line and the new section. + [ -n "$(tail -c1 "$env")" ] && echo + echo + echo "# === Added from $(basename "$example") on $(date +%Y-%m-%d) ===" + printf '%s\n' "$added" +} >> "$env" + +echo "Added new settings to $env:" +printf '%s\n' "$added" | grep -E "$key_re" | sed 's/=.*//; s/^/ /'