c4874dc04c
The interim proxy (#239/#240/#242/#243) covers the day-one needs for Overpass — User-Agent compliance via server-side proxy, same-origin + rate limit + cache with coalescing, bbox quantization, observability. Further work on self-hosting the upstream is no longer urgent. Move the full OpenSpec artifact set out of openspec/changes/ so it doesn't clutter the active change list, and park it under docs/ideas/self-host-overpass/ as a reference for when we revive it. Adds a short README at the new location capturing: - current interim solution - triggers that would justify reviving (rate limits, >1 req/s, etc.) - key decisions already made (Hetzner-to-Hetzner firewall model, DOCKER-USER chain, capacity ceiling at DACH on current box) - how to switch when the time comes (flip OVERPASS_URL, no client changes) The files were never committed in the first place (WIP in the working tree through the proposal session), so no git history to preserve. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
76 lines
4.8 KiB
Markdown
76 lines
4.8 KiB
Markdown
## ADDED Requirements
|
|
|
|
### Requirement: Self-hosted Overpass service
|
|
The trails.cool infrastructure SHALL run an Overpass API instance as a Docker service on a dedicated host, populated from a configurable regional OpenStreetMap extract, and reachable only from the Planner host.
|
|
|
|
#### Scenario: Service reachable from the Planner host
|
|
- **WHEN** the Planner server sends an Overpass query from its configured egress address to the Overpass host on the configured port
|
|
- **THEN** the request is accepted and served
|
|
|
|
#### Scenario: Service not reachable from any other source
|
|
- **WHEN** any other host on the public internet attempts to connect to the Overpass host's Overpass port
|
|
- **THEN** the connection is dropped by the host firewall and the Overpass service never sees the packets
|
|
|
|
#### Scenario: Regional extract is configurable
|
|
- **WHEN** the operator sets a different `OVERPASS_PBF_URL` and runs the initial-load procedure
|
|
- **THEN** the service comes up populated from that extract without code changes
|
|
|
|
### Requirement: Firewall compatible with Docker
|
|
The Overpass host firewall SHALL enforce the allowlist in a way that survives Docker daemon restarts, container restarts, and port-publication rule changes — i.e. user rules MUST be placed on the chain Docker reserves for user-managed filtering rather than relying on chains that Docker bypasses when publishing container ports.
|
|
|
|
#### Scenario: Rule survives container restart
|
|
- **WHEN** the Overpass container is stopped and started
|
|
- **THEN** the firewall allowlist is still in effect and unauthorised sources are still dropped without operator intervention
|
|
|
|
#### Scenario: Rule survives Docker daemon restart
|
|
- **WHEN** the Docker daemon on the Overpass host is restarted
|
|
- **THEN** the firewall allowlist is still in effect and unauthorised sources are still dropped without operator intervention
|
|
|
|
#### Scenario: Planner host address change
|
|
- **WHEN** the Planner host's egress address changes and the operator updates the configured allowlist address
|
|
- **THEN** applying the updated ruleset restores Planner connectivity without requiring Docker or Overpass to restart
|
|
|
|
### Requirement: Overpass data refresh
|
|
The Overpass service SHALL keep its OSM database current by applying upstream diffs on a recurring schedule without manual intervention after the initial import.
|
|
|
|
#### Scenario: Daily replication
|
|
- **WHEN** 24 hours have passed since the last diff application
|
|
- **THEN** the container has fetched and applied the next diff from the upstream provider, and the replication timestamp advances
|
|
|
|
#### Scenario: Recoverable replication failure
|
|
- **WHEN** diff replication fails once (network blip, upstream 5xx)
|
|
- **THEN** the container retries on its next scheduled interval without requiring an operator to restart it
|
|
|
|
#### Scenario: Replication lag observable
|
|
- **WHEN** replication has been failing for more than 48 hours
|
|
- **THEN** a monitoring signal indicates the service is stale so the operator can investigate
|
|
|
|
### Requirement: Planner Overpass proxy route
|
|
The Planner server SHALL expose an authenticated, rate-limited proxy route that forwards Overpass QL queries to the Overpass host. This SHALL be the only path through which Overpass is reachable from outside the Overpass host.
|
|
|
|
#### Scenario: Forward valid query
|
|
- **WHEN** an authenticated Planner browser session POSTs a valid Overpass QL query to `/api/overpass`
|
|
- **THEN** the proxy forwards the query to the Overpass service and returns the upstream response body and status
|
|
|
|
#### Scenario: Reject unauthenticated request
|
|
- **WHEN** a request arrives at `/api/overpass` without a valid Planner session cookie
|
|
- **THEN** the proxy responds with HTTP 401 and does not contact the Overpass service
|
|
|
|
#### Scenario: Reject cross-origin request
|
|
- **WHEN** a request arrives at `/api/overpass` with an Origin header not matching the Planner's own origin
|
|
- **THEN** the proxy responds with HTTP 403 and does not contact the Overpass service
|
|
|
|
#### Scenario: Rate limit exceeded
|
|
- **WHEN** a session sends more Overpass queries than the configured per-session limit allows within the rate-limit window
|
|
- **THEN** the proxy responds with HTTP 429 and does not contact the Overpass service
|
|
|
|
### Requirement: Initial data load is out-of-band
|
|
The initial import of the regional OSM extract into the Overpass database SHALL NOT run as part of a normal deploy and SHALL NOT block routine container restarts once the data volume is populated.
|
|
|
|
#### Scenario: First-time setup
|
|
- **WHEN** the operator provisions a new Overpass host with an empty data volume
|
|
- **THEN** a documented one-shot procedure (e.g. a compose-run command) performs the initial PBF download and import, and exits cleanly
|
|
|
|
#### Scenario: Routine restart
|
|
- **WHEN** the `overpass` service is restarted with an already-populated data volume
|
|
- **THEN** the service comes up and is query-ready without re-importing data
|