Repository navigation
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.
| 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 |
| 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 |
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).
ViaFrei API: a public, keyed, read-only REST API to live German mobility data. Design phase; nothing on these pages is a measurement of a running service. Data on viafrei.de and in every API answer is attributed to its publishers under their licences.
About
Design
- Domain Model
- API Design
- Architecture Overview
- Security and Access Keys
- Rate Limits and Priority
- Performance and Caching
- Configuration
- Observability
Data Model
Technical specification
-
Technical Specification
- Interface
- Scope, Conventions and References
- Protocol
- Common Envelope
- Resource Model
- Endpoints, Places
- Endpoints, Roads
- Endpoints, Energy and Parking
- Endpoints, Public Transport and Accessibility
- Endpoints, Weather Risk, Driving Rules and Composed Features
- Service Endpoints
- Errors
- Authentication and Authorisation
- Rate Limiting, Quotas and Priority
- Data Licensing and Attribution
- Compatibility and Versioning
- OpenAPI Skeleton
- Quality
- Delivery and operations
- Interface
Testing
- Testing Strategy
- Testing and Quality (design summary)
Engineering
Technology choice
- Technology Evaluation
- Architecture: Go
- Architecture: Rust
- Architecture: TypeScript
- Stack Comparison
- Benchmark Plan
Reference