Skip to content

Configuration

mavrovde edited this page Nov 2, 2026 · 5 revisions

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.

Rules

  1. One declaration per key: type, default, bounds, description and a secret flag, declared once in the configuration module.
  2. 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_MAX for db.pool_max).
  3. Secrets only from the environment or a secret file (a *_FILE variant). A secret in the configuration file is refused, naming the key.
  4. 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.
  5. Subcommands: config check validates; config show prints the effective configuration with secrets shown only as <set>; config docs generates the reference table. CI fails if the published table drifts from the code.
  6. A lint finds duration and limit literals outside the configuration module (with a short, reasoned allow-list).
  7. 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=4 a 400.
  8. 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.

Planned keys

Defaults are design proposals. Ports shown are generic examples.

Server

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

Database

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

Deadline and contract

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

Keys and plans

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

Limits, tiers and quotas

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

Caching, HTTP and pagination

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

Features, sources and operations

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

Keys added by the technical specification

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

Stack differences

  • Go (the chosen stack, ADR-0001): configuration file in YAML; environment prefix VFAPI_ (for example VFAPI_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 docs generates the reference (docs/configuration.md in the repository) and CI fails when it is stale. Implemented in 0.2.0 for the keys the skeleton uses, http.hsts_max_age among 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.

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally