Skip to content

Spec Configuration Cross Reference

mavrovde edited this page Nov 1, 2026 · 1 revision

Spec: Configuration Cross-Reference

Part of the Technical Specification. Requirement prefix: CFG. The rules and the full key list live on Configuration; this page states the requirements and maps every limit named in the specification to its key. Values are design defaults, not measurements.

Requirements

ID Requirement Verification
CFG-001 Every timeout, limit, size, TTL, threshold and retention named in this specification MUST be a configuration key with a declared type, default, bounds and description; none MAY be a literal in the code. Lint
CFG-002 Keys MUST be read from layered sources (defaults, file, environment) as described on [[Configuration Configuration]]; secrets MUST come only from the environment or a secret file.
CFG-003 Boot MUST refuse unknown keys, out-of-bounds values and cross-field violations, listing every violation before exiting with a configuration error. Config
CFG-004 Cross-field rules MUST include: deadline.request ≤ 2 s; compose.part_deadline < deadline.request; reserved permits ≤ db.pool_max; pagination.default_limit ≤ pagination.max_limit; roads.ahead_default_km ≤ roads.ahead_max_km; transit.default_window_min ≤ transit.max_window_min; briefing.default_horizon_min ≤ briefing.max_horizon_min; geo.default_radius_m ≤ geo.max_radius_m. Config
CFG-005 The published configuration reference MUST be generated from the declaration, and CI MUST fail when it drifts from this cross-reference's key names. Docs
CFG-006 A coverage test MUST set every key to a non-default value and observe a change in behaviour. Config
CFG-007 Secret values MUST NOT appear in logs, error responses, config show output or traces. Security
CFG-008 Operational switches (endpoints.disabled, sources.disabled, key revocation) MUST take effect without a deployment (OPS-010). Config

Limit-to-key map

Specification item Requirement or page Key Default
Request deadline NFR-PERF-001, CON-003 deadline.request 2 s
Per-part deadline in composed answers FR-BRIEF-003 compose.part_deadline 1.2 s
Composed fan-out FR-BRIEF-003, RATE-013 compose.max_parallel 2
Maximum URI length PROT-006 server.max_uri_bytes 8 KiB
Maximum header size PROT-006 server.max_header_bytes 16 KiB
Maximum query body (POST) NFR-SIZE-001 server.max_body_bytes 64 KiB
Maximum response size NFR-SIZE-002 http.max_response_bytes 8 MiB
HSTS max-age NFR-SEC-001 http.hsts_max_age 1 year
CORS origins PROT-050 http.cors.allowed_origins empty
Page size ENV-021 pagination.default_limit / max_limit 50 / 500
Cursor lifetime ENV-023 pagination.cursor_ttl 1 h
Default radius FR-LOC-006 geo.default_radius_m 5000 m
Maximum radius FR-LOC-006 geo.max_radius_m 50 000 m
Maximum bbox area FR-LOC-006 geo.max_bbox_km2 10 000 km²
Coverage margin outside Germany FR-LOC-003 geo.coverage_margin_m 10 000 m
Maximum route length FR-LOC-005 geo.max_route_km 1500 km
Maximum route points FR-LOC-005 geo.max_route_points 2000
Geometry vertices per feature ENV-012 geo.max_vertices 5000
Route buffer FR-LOC-004 geo.route_buffer_m 2000 m
Geometry simplification ENV-012 geo.simplify_tolerance_m 25 m
Place candidates on ambiguity FR-LOC-002 places.max_candidates 5
Describe-location search distance [[Places Spec-Endpoints-Places]] places.describe_max_distance_m
Road snapping distance FR-ROAD-011 roads.snap_distance_m 500 m
Roadworks ahead distance [[Roads Spec-Endpoints-Roads]], CFG-004 roads.ahead_default_km / ahead_max_km
Situation look-ahead [[Roads Spec-Endpoints-Roads]] roads.max_lookahead_h
Ended situations retained [[Roads Spec-Endpoints-Roads]] roads.ended_retention_h
History window FR-ROAD-008 history.max_window 24 h
Stop search radius [[Transit Spec-Endpoints-Transit-and-Accessibility]] transit.max_stop_radius_m
Departure window FR-TRANSIT-005 transit.default_window_min / max_window_min 60 / 240 min
Departures in the past [[Transit Spec-Endpoints-Transit-and-Accessibility]] transit.max_past_min
Departures ahead FR-TRANSIT-005 transit.max_ahead_h 24 h
Weather look-ahead [[Weather Spec-Endpoints-Weather-Rules-and-Composed]] weather.max_lookahead_h
Briefing horizon [[Route briefing Spec-Endpoints-Weather-Rules-and-Composed]], CFG-004 briefing.default_horizon_min / max_horizon_min
Stale thresholds per family NFR-FRESH-001, NFR-FRESH-002 freshness.stale_after.<family> see below
Cache max-age per family PROT-044 cache.max_age.<family> [[Performance and Caching
Serve stale on storage error NFR-RES-004 cache.stale_if_error 5 min
Circuit breaker NFR-RES-002 breaker.failure_threshold / window / open_for / half_open_probes 5 failures / 30 s / 15 s / 2
Readiness probe timeout [[Service Spec-Endpoints-Service]] health.ready_timeout
Read-contract check VER-009 contract.expected / contract.poll built in / 5 min
Admission queues and reservations RATE-009 tiers.*.queue_len / queue_max_wait [[Configuration
Per-key concurrency RATE-016 tiers.per_key_inflight 4
Anonymous per-IP limit RATE-001 ratelimit.anon_rps / anon_burst 1 / 5
Per-IP state lifetime NFR-PRIV-002, RATE-015 ratelimit.ip_state_ttl 10 min
Limiter instance count NFR-SCALE-003 ratelimit.instances 1
Quota reset zone RATE-003 quota.reset_tz Europe/Berlin
Metering flush and write RATE-014 metering.flush_interval / write_timeout 30 s / 1 s
Key cache SEC-022 auth.key_cache_ttl / negative_cache_ttl 60 s / 10 s
Revocation propagation SEC-042 auth.revocation_propagation 5 s
Expiry warning SEC-043 auth.expiry_warning_days 14 days
Authentication failure limit SEC-052 auth.failure_limit 10 per minute per address
Rotation overlap SEC-041 auth.rotation_overlap 7 days
Deprecation notice VER-003 deprecation.min_notice 183 days
Access-log address truncation NFR-OBS-004 log.ip_prefix / log.ip6_prefix 24 / 48
Access-log retention NFR-PRIV-003 log.retention_days 7
Trace retention GOV-001 otel.retention_days 7
Usage and audit retention GOV-001 metering.retention_days / audit.retention_days 400 / 395
Key holder and acceptance retention GOV-001 governance.keyholder_retention_days / acceptance_retention_days 30 / 1095

Stale thresholds (design defaults)

The thresholds are listed once, with their keys, in Spec: Non-Functional Requirements section 5 (freshness.stale_after.roads, .fuel, .charging, .parking, .departures, .accessibility, .weather, .places).

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally