MatchingEnricher via Valhalla map matching

robert commented

2026-08-31 17:14:45 +02:00

(Migrated from git.butzei.de)

Goal

Online fallback for when BRouter is unavailable. One call at import time, so an internet connection is only needed at home.

Acceptance criteria

GPX posted to GraphHopper map matching with the bike profile and a language code so turn instructions are returned
Valhalla trace_attributes supported as an alternative backend
Response maneuvers mapped to the canonical enum
API key handled via configuration, never committed
Network failure and rate limiting degrade to the geometric enricher rather than erroring out
Result cached so a route is never matched twice

Files

companion/.../route/enrich/MatchingEnricher.kt

Update — 2026-09-01: Valhalla only; GraphHopper dropped

GraphHopper's map-matching API needs an API key. The repository is public and NFR-S3 forbids
committing keys, so "keys in configuration" means every user registers their own GraphHopper account —
which makes the tier dead for almost everyone (D26).

GraphHopper removed. Valhalla trace_attributes only
Endpoint configurable: a public instance under its usage policy, or a self-hosted one
No API key anywhere in the repository or the APK, satisfying NFR-S3 by construction rather
than by configuration discipline
The instance actually contacted is named in the consent prompt (#52), because it is now
configurable and the user must know where their route is going
Rate limits and failures fall through to tier 3 rather than blocking the import
Retitle to reflect Valhalla only

Update — 2026-09-03: no public default; user-supplied endpoint only (D61)

The named public instance refuses TCP from two independent networks (2026-09-03) and its terms
(1 call/user/sec, no SLA, please-notify) were never a foundation for a shipped feature. This issue
changes shape: the online tier becomes a user-configured endpoint with no default — the rider
points it at their own Valhalla or a commercial key they own. Nothing is hard-coded, so a dead demo
server can never break the app. ODbL attribution is a UI obligation, not just a licence file.

## Goal Online fallback for when BRouter is unavailable. One call at import time, so an internet connection is only needed at home. ## Acceptance criteria - [ ] GPX posted to GraphHopper map matching with the bike profile and a language code so turn instructions are returned - [ ] Valhalla `trace_attributes` supported as an alternative backend - [ ] Response maneuvers mapped to the canonical enum - [ ] API key handled via configuration, never committed - [ ] Network failure and rate limiting degrade to the geometric enricher rather than erroring out - [ ] Result cached so a route is never matched twice ## Files - `companion/.../route/enrich/MatchingEnricher.kt` ## Update — 2026-09-01: Valhalla only; GraphHopper dropped GraphHopper's map-matching API needs an API key. The repository is public and NFR-S3 forbids committing keys, so "keys in configuration" means every user registers their own GraphHopper account — which makes the tier dead for almost everyone (D26). - [ ] **GraphHopper removed.** Valhalla `trace_attributes` only - [ ] Endpoint configurable: a public instance under its usage policy, or a self-hosted one - [ ] **No API key anywhere in the repository or the APK**, satisfying NFR-S3 by construction rather than by configuration discipline - [ ] The instance actually contacted is named in the consent prompt (#52), because it is now configurable and the user must know where their route is going - [ ] Rate limits and failures fall through to tier 3 rather than blocking the import - [ ] Retitle to reflect Valhalla only ## Update — 2026-09-03: no public default; user-supplied endpoint only (D61) The named public instance refuses TCP from two independent networks (2026-09-03) and its terms (1 call/user/sec, no SLA, please-notify) were never a foundation for a shipped feature. This issue changes shape: the online tier becomes a **user-configured endpoint with no default** — the rider points it at their own Valhalla or a commercial key they own. Nothing is hard-coded, so a dead demo server can never break the app. ODbL attribution is a UI obligation, not just a licence file.