Repository navigation
Configuration
Everything that can be configured is configurable. No timeout, limit, size, TTL or port is a literal in the code. This page describes the configuration rules and the planned key set. The authoritative reference will be generated from the code and published with the documentation.
- One declaration per key: type, default, bounds, description and a secret flag, declared once in the configuration module.
-
Layered sources: built-in defaults, then an optional configuration file, then environment variables (a fixed prefix plus the key path in upper snake case, for example
<PREFIX>_DB_POOL_MAXfordb.pool_max). -
Secrets only from the environment or a secret file (a
*_FILEvariant). A secret in the configuration file is refused, naming the key. -
Boot refuses unknown file keys, unknown environment variables with the prefix, out-of-bounds values and cross-field violations (for example
pool_min ≤ pool_max, reserved permits ≤ pool size, request deadline ≤ 2 s). It lists every violation, then exits with a configuration error code. -
Subcommands:
config checkvalidates;config showprints the effective configuration with secrets shown only as<set>;config docsgenerates the reference table. CI fails if the published table drifts from the code. - A lint finds duration and limit literals outside the configuration module (with a short, reasoned allow-list).
-
A coverage test sets every key to a non-default value and observes the change in behaviour. Example: setting the maximum page size to 3 makes
limit=4a400. - Secret values cannot be logged: they have a type whose text, JSON and log representations are
<redacted>, and a test logs the whole configuration and searches for planted values.
Defaults are design proposals. Ports shown are generic examples.
| Key | Default | Bounds | Purpose |
|---|---|---|---|
server.listen_addr |
127.0.0.1:8080 |
public listener, behind the TLS edge | |
server.public_base_url |
https://api.viafrei.de (recommended, see [[API Address |
API-Address]]) | https only |
server.trusted_proxies |
empty | CIDR list | whose forwarded-for header is believed |
server.read_header_timeout / read_timeout / write_timeout / idle_timeout
|
2 s / 5 s / 5 s / 60 s | 100 ms – 300 s | |
server.max_header_bytes / max_body_bytes
|
16 KiB / 64 KiB | 4 KiB – 1 MiB | |
server.shutdown_grace |
10 s | 1 – 60 s | drain and final metering flush |
| Key | Default | Bounds | Purpose |
|---|---|---|---|
db.url, db.admin_url
|
secret, required | read role and access-store role | |
db.pool_max / pool_min / admin_pool_max
|
4 / 1 / 2 | 1–16 / 0–max / 1–4 |
pool_max equals the admission permits |
db.connect_timeout / max_conn_lifetime / max_conn_idle
|
2 s / 30 min / 5 min | ||
db.statement_timeout_floor / cancel_grace
|
50 ms / 100 ms | 10 ms – 1 s | minimum useful budget; time allowed for a cancel to land |
db.prepared |
statement cache | cache, describe, exec | prepared-statement mode |
db.application_name |
viafrei-api |
≤ 63 characters |
| Key | Default | Bounds | Purpose |
|---|---|---|---|
deadline.request / deadline.reserve
|
2 s / 50 ms | 200 ms – 2 s / 0 – 500 ms | the request budget and the margin kept back |
contract.expected / contract.poll
|
built in / 5 min | major.minor / 30 s – 1 h | read-contract compatibility for readiness |
| Key | Default | Bounds | Purpose |
|---|---|---|---|
auth.key_prefix_live / auth.key_prefix_test
|
vf_live_ / vf_test_
|
short lowercase | |
auth.pepper, auth.pepper_previous
|
secret | ≥ 32 bytes | MAC pepper and its rotation |
auth.key_cache_ttl / negative_cache_ttl / key_cache_size
|
60 s / 10 s / 10 000 | ||
auth.rotation_overlap / default_expiry
|
7 days / 365 days | 0–30 days / 1–1095 days | |
plans.seed |
dev, standard, pro, bulk | seeded on first migration only |
| Key | Default | Bounds | Purpose |
|---|---|---|---|
tiers.{critical,standard,bulk}.reserved |
1 / 0 / 0 | 0 – pool | reserved permits |
tiers.*.queue_len |
32 / 32 / 4 | 0 – 1024 | |
tiers.*.queue_max_wait |
800 / 400 / 200 ms | 0 – 2 s | |
tiers.bulk.max_inflight |
1 | 0 – pool | |
admission.aging_after / ewma_alpha / shed_status / adaptive
|
500 ms / 0.2 / 429 / off | ||
ratelimit.anon_rps / anon_burst / headers
|
1 / 5 / on | 0 – 100 | per-IP limit before a key is known |
quota.reset_tz |
Europe/Berlin |
IANA zone | |
metering.flush_interval / max_keys_buffered
|
30 s / 100 000 | 5 s – 5 min | |
metering.retention_days / audit.retention_days
|
400 / 395 | 30 – 1825 | |
compose.max_parallel |
2 | 1 – 4 | fan-out of composed features |
| Key | Default | Bounds | Purpose |
|---|---|---|---|
cache.enabled / max_bytes / max_ttl / freshness_poll
|
on / 16 MiB / 1 h / 1 s | 0 – 256 MiB | |
cache.max_age.<family> |
see [[Performance and Caching | Performance-and-Caching]] | 0 – 86 400 s |
http.compress_min_bytes / gzip_level / brotli / zstd
|
1024 / 5 / on / off | ||
http.cors.allowed_origins / max_age
|
empty / 10 min |
* refused with credentials |
|
pagination.default_limit / max_limit / cursor_ttl
|
50 / 500 / 1 h | 1 – 5000 | |
pagination.cursor_key |
secret | ≥ 32 bytes | signs cursors |
history.max_window |
24 h | 1 h – 7 days | |
geo.max_radius_m / max_bbox_km2 / max_route_points / route_buffer_m / simplify_tolerance_m
|
50 000 / 10 000 / 2000 / 2000 / 25 | bounded areas |
| Key | Default | Purpose |
|---|---|---|
endpoints.disabled |
empty | operation ids; a disabled one answers 404 feature-disabled and disappears from the OpenAPI document |
sources.disabled |
empty | source families the licence gate always denies |
log.level / format / access_sample / ip_prefix
|
info / json / 1.0 / 24 | |
metrics.listen_addr |
127.0.0.1:9090 |
loopback only |
otel.enabled / endpoint / sample_ratio
|
off / — / 0.05 | tracing |
admin.enabled / listen_addr / token
|
off / 127.0.0.1:8081 / secret |
loopback-only admin listener for the owner console |
docs.enabled |
on |
/docs and /openapi.json
|
These keys are required by the Technical Specification; each limit is mapped to its requirement in Spec: Configuration Cross-Reference. Defaults are design proposals.
| Key | Default | Bounds | Purpose |
|---|---|---|---|
server.max_uri_bytes |
8 KiB | 2 – 64 KiB | longer request URI is 414
|
http.max_response_bytes |
8 MiB | 64 KiB – 64 MiB | a larger answer is cut at a page boundary |
http.hsts_max_age |
1 year | 0 – 2 years | Strict-Transport-Security |
geo.default_radius_m |
5 000 | 1 – geo.max_radius_m
|
default search radius |
geo.coverage_margin_m |
10 000 | 0 – 50 000 | border margin around Germany |
geo.max_route_km |
1 500 | 10 – 3 000 | longest accepted client route |
geo.max_vertices |
5 000 | 100 – 50 000 | vertices per feature with geometry=full
|
places.max_candidates |
5 | 1 – 20 | candidates in 422 ambiguous-place
|
places.describe_max_distance_m |
2 000 | 100 – 10 000 | nearest address and junction search |
freshness.stale_after.<family> |
per family, see [[Spec: Non-Functional Requirements | Spec-Non-Functional-Requirements]] | 1 min – 90 days |
deprecation.min_notice |
183 days | 90 – 730 days | shortest deprecation-to-sunset period |
roads.snap_distance_m |
500 | 50 – 5 000 | section ends projected onto the road |
roads.ahead_default_km / ahead_max_km
|
50 / 300 | 1 – 1 000 | roadworks ahead |
roads.max_lookahead_h |
168 | 1 – 720 |
active_at in the future |
roads.ended_retention_h |
24 | 1 – 168 | an ended situation still answers 200
|
transit.max_stop_radius_m |
1 000 | 100 – 5 000 | stop search with near
|
transit.default_window_min / max_window_min
|
60 / 240 | 1 – 1 440 | departure window |
transit.max_past_min / max_ahead_h
|
30 / 24 | 0 – 240 / 1 – 72 | bounds of from
|
weather.max_lookahead_h |
48 | 1 – 168 |
active_at for warnings |
briefing.default_horizon_min / max_horizon_min
|
180 / 720 | 1 – 1 440 | route briefing horizon |
compose.part_deadline |
1.2 s | 100 ms – < deadline.request
|
per-part deadline of composed answers |
breaker.failure_threshold / window / open_for / half_open_probes
|
5 / 30 s / 15 s / 2 | 1 – 100 / 1 – 300 s / 1 – 300 s / 1 – 10 | storage circuit breaker |
cache.stale_if_error |
5 min | 0 – 1 h | serve stale while storage is unavailable |
metering.write_timeout |
1 s | 100 ms – 10 s | flush write deadline |
ratelimit.ip_state_ttl |
10 min | 1 – 60 min | per-IP limiter state, memory only |
ratelimit.instances |
1 | 1 – 64 | divides per-key limits without shared state |
tiers.per_key_inflight |
4 | 1 – pool | permits one key may hold |
auth.revocation_propagation |
5 s | 1 – 60 s | revocation visible on every instance |
auth.expiry_warning_days |
14 | 0 – 90 |
key_expiring warning |
auth.failure_limit |
10 per minute per address | 1 – 1 000 | authentication failures before 429
|
log.ip6_prefix |
48 | 32 – 64 | IPv6 truncation in access logs |
log.retention_days |
7 | 1 – 30 | access-log deletion |
otel.retention_days |
7 | 1 – 30 | trace deletion |
health.ready_timeout |
500 ms | 50 ms – 2 s | readiness probe |
governance.keyholder_retention_days |
30 | 0 – 365 | after key end, then anonymised |
governance.acceptance_retention_days |
1 095 | 365 – 3 650 | terms acceptance evidence after key end |
-
Go (the chosen stack, ADR-0001): configuration file in YAML; environment prefix
VFAPI_(for exampleVFAPI_DB_POOL_MAX); the declaration is the configuration struct with tags carrying the default, bounds and description; validation by tag rules plus cross-field checks;viafrei-api config docsgenerates the reference (docs/configuration.mdin the repository) and CI fails when it is stale. Implemented in 0.2.0 for the keys the skeleton uses,http.hsts_max_ageamong them. -
Rust: configuration file in TOML; nested environment keys use a double underscore (
<PREFIX>_DB__POOL_MAX); the declaration is a constant table checked one-to-one against the configuration struct; one extra key for the number of async worker threads. -
TypeScript: configuration file in YAML; the declaration is a zod schema carrying types, defaults, bounds and descriptions; the reference is generated from its JSON Schema.
The key paths are identical in all three, and the generated documentation lists the environment spelling of the chosen stack.
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