Version 0.2.1

Configuration reference

Every tunable of the service is one key below. Sources are layered: the built-in default, then an optional YAML file (path in VFAPI_CONFIG_FILE), then environment variables. The service refuses to start on an unknown key, an unknown variable with the prefix, a value out of bounds or a broken cross-field rule, and lists every violation. Secrets are read only from the environment or from a file named by the _FILE variant (one of the two, never both), never from the YAML file, and are never printed. Exit status on a configuration error: 78.

Cross-field rules: db.pool_min ≤ db.pool_max; deadline.reserve < deadline.request; health.ready_timeout ≤ deadline.request; db.statement_timeout_floor < deadline.request − deadline.reserve.

Key Environment Type Default Bounds Description
server.listen_addr VFAPI_SERVER_LISTEN_ADDR string localhost:8080 host:port Address of the public listener, host:port. Behind the TLS edge in production.
server.public_base_url VFAPI_SERVER_PUBLIC_BASE_URL string https://api.viafrei.de absolute URL; starts with https:// Absolute base URL used in links, problem type URIs and the OpenAPI servers entry. https only.
server.read_header_timeout VFAPI_SERVER_READ_HEADER_TIMEOUT duration 2s 100ms to 300s Time allowed to read the request headers.
server.read_timeout VFAPI_SERVER_READ_TIMEOUT duration 5s 100ms to 300s Time allowed to read the whole request.
server.write_timeout VFAPI_SERVER_WRITE_TIMEOUT duration 5s 100ms to 300s Time allowed to write the response.
server.idle_timeout VFAPI_SERVER_IDLE_TIMEOUT duration 60s 100ms to 300s Time an idle keep-alive connection is kept open.
server.max_header_bytes VFAPI_SERVER_MAX_HEADER_BYTES int 16384 4096 to 1048576 Largest accepted request header block, in bytes (431 above).
server.max_uri_bytes VFAPI_SERVER_MAX_URI_BYTES int 8192 2048 to 65536 Longest accepted request URI, in bytes (414 above).
server.shutdown_grace VFAPI_SERVER_SHUTDOWN_GRACE duration 10s 1s to 60s Time in-flight requests get to finish on shutdown.
http.hsts_max_age VFAPI_HTTP_HSTS_MAX_AGE duration 8760h 0s to 17520h max-age of Strict-Transport-Security on every answer, sent in whole seconds; 0s sends max-age=0, which tells browsers to forget the policy.
db.url VFAPI_DB_URL or VFAPI_DB_URL_FILE secret secret, no default — Connection URL of the service's read-only role. Required to serve. Secret: environment or *_FILE only.
db.pool_max VFAPI_DB_POOL_MAX int 4 1 to 16 Largest number of pooled connections.
db.pool_min VFAPI_DB_POOL_MIN int 1 0 to 16 Connections kept open when idle. At most pool_max.
db.connect_timeout VFAPI_DB_CONNECT_TIMEOUT duration 2s 100ms to 30s Time allowed to open one connection.
db.max_conn_lifetime VFAPI_DB_MAX_CONN_LIFETIME duration 30m 1m to 24h A connection older than this is closed after use.
db.max_conn_idle VFAPI_DB_MAX_CONN_IDLE duration 5m 10s to 24h An idle connection older than this is closed.
db.statement_timeout_floor VFAPI_DB_STATEMENT_TIMEOUT_FLOOR duration 50ms 10ms to 1s Smallest useful remaining budget; below it a read is refused without touching storage.
db.cancel_grace VFAPI_DB_CANCEL_GRACE duration 100ms 10ms to 1s Time a cancel request gets to land before the connection is abandoned.
db.application_name VFAPI_DB_APPLICATION_NAME string viafrei-api at most 63 characters application_name reported to the database.
deadline.request VFAPI_DEADLINE_REQUEST duration 2s 200ms to 2s Hard deadline of every request (NFR-PERF-001).
deadline.reserve VFAPI_DEADLINE_RESERVE duration 50ms 0s to 500ms Margin kept back from the deadline when the statement timeout is set. Less than deadline.request.
contract.expected VFAPI_CONTRACT_EXPECTED string empty major.minor Read-contract version (major.minor) this instance requires; empty means the version built in. Readiness fails on another major or an older minor.
health.ready_timeout VFAPI_HEALTH_READY_TIMEOUT duration 500ms 50ms to 2s Time the readiness probe gives storage to answer. At most deadline.request.
health.probe_timeout VFAPI_HEALTH_PROBE_TIMEOUT duration 1s 100ms to 10s Time the healthcheck subcommand waits for /healthz.
log.level VFAPI_LOG_LEVEL string info one of debug, info, warn, error Lowest level written: debug, info, warn or error.
log.format VFAPI_LOG_FORMAT string json one of json, text Log line format on standard output: json or text.
docs.enabled VFAPI_DOCS_ENABLED bool true — Serve the OpenAPI document at /v1/openapi.json and /openapi.json.
endpoints.disabled VFAPI_ENDPOINTS_DISABLED list empty — Operation ids switched off: they answer 404 feature-disabled and leave the OpenAPI document. Comma-separated in the environment.