trails/infrastructure/.env.example
Ullrich Schäfer 963902514b
Failover across multiple Overpass upstreams
Public Overpass instances go bad without warning — we just lived
through a day where overpass.private.coffee (our single upstream)
returned 504s after 60s while lz4.overpass-api.de served the same
query in 0.6s. Survive that by trying a list of upstreams in order
until one responds usefully.

Server changes:
- OVERPASS_URLS env — comma-separated list, tried in order. Falls
  back to OVERPASS_URL for backward compat, then to a built-in
  default pair (lz4.overpass-api.de, overpass-api.de).
- Per-upstream timeout of 10s via AbortSignal.timeout, so a saturated
  instance fails over in seconds, not minutes.
- Client abort propagation via AbortSignal.any — if the browser
  cancels (e.g. user panned the map), the in-flight upstream fetch is
  aborted too. Stops wasting upstream capacity on requests nobody
  wants.
- Rate-limited-body detection (Overpass returns 200 with a
  `rate_limited` marker when throttling) triggers failover.
- Per-upstream labels on overpass_upstream_requests_total and
  overpass_upstream_duration_seconds so the dashboard can break out
  health + latency by instance. Histogram buckets extended to 30s.

Compose: OVERPASS_URLS passthrough with the default pair hard-wired,
overridable via SOPS.

Tests: 8 cases covering the new fetchWithFailover helper — happy
path, 5xx failover, rate_limited failover, network error failover,
timeout tagging, all-upstreams-fail, client abort stops the loop,
per-attempt latency observation.

Follow-ups left out of scope:
- Client-side debounce (UI concern).
- Moving `.observe()` after body read for accuracy in measurement.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-21 07:36:10 +02:00

26 lines
1.2 KiB
Text

# trails.cool infrastructure environment variables
# Copy to .env and fill in values
DOMAIN=trails.cool
POSTGRES_PASSWORD=change-me
JWT_SECRET=change-me
S3_ACCESS_KEY=
S3_SECRET_KEY=
# Overpass upstream failover. Comma-separated list tried in order;
# first 2xx response wins. Falls back to the single-URL OVERPASS_URL
# if this is unset, and to a built-in default list if neither is set.
# OVERPASS_URLS=https://lz4.overpass-api.de/api/interpreter,https://overpass-api.de/api/interpreter
# Demo-activity-bot. Only enable in prod. When true, the journal worker
# bootstraps a demo user and generates public demo routes + activities
# every 90 min. Retention is in days (default 14).
# DEMO_BOT_ENABLED=true
# DEMO_BOT_RETENTION_DAYS=14
# DEMO_BOT_REGION={"bbox":[13.25,52.45,13.55,52.60]}
#
# Override the default Bruno persona (identity + generated copy) via
# either an inline JSON blob or a file path. See docs/demo-persona.md
# for the schema.
# DEMO_BOT_PERSONA=file:/etc/trails-cool/persona.json
# DEMO_BOT_PERSONA={"username":"hamish","displayName":"Hamish","bio":"...","locales":["en"],"content":{"names":{"en":["...","...","..."]},"descriptions":{"en":["...","...","..."]}}}