Version 0.2.1
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. |