Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(env): say boot-validated knobs fail the boot on a bad value

Yudhi Armyndharisedaf23bf00a2
diff --git a/.env.example b/.env.example
index 1de9e1f5b..63e09ac20 100644
--- a/.env.example
+++ b/.env.example
@@ -548,14 +548,16 @@ WEBHOOK_SSRF_PROTECT=true
# Aggregate base64 budget for media inlined by ONE GET .../messages/:chatId/history?includeMedia=true
# call. Once the running total crosses it, remaining media messages return the declared-only `omitted`
# marker instead of a download, so a media-heavy history can't stack ~100 × the per-message cap into a
-# single response. A non-positive/garbage value falls back to the default.
+# single response. Unset takes the default; a value that is not a positive integer fails the boot.
# CHAT_HISTORY_MEDIA_BUDGET_BYTES=26214400 # default 25 MiB
# Per-file cap on status (Story) media persisted to disk/S3. A status whose media exceeds this is
-# stored omitted (mediaOmitted=true) rather than rejected. A non-positive/garbage value falls back.
+# stored omitted (mediaOmitted=true) rather than rejected. Unset takes the default; a value that is
+# not a positive integer fails the boot.
# STATUS_MEDIA_MAX_BYTES=10485760 # default 10 MiB
# Orphaned status media reconciliation: how often the sweep re-lists status media files to find
# ones no row references (crash leftovers), and how long a file must be seen unreferenced before
-# it is deleted. Non-positive/garbage values fall back to the defaults.
+# it is deleted. Unset takes the default; a value that is not a positive integer fails the boot, and
+# so does a sweep interval above 2147483647 ms (Node's timer ceiling).
# STATUS_ORPHAN_SWEEP_INTERVAL_MS=3600000 # default 1h
# STATUS_ORPHAN_GRACE_MS=3600000 # default 1h
# Chat-media archiving (opt-in). When enabled, each inbound message's media is also written to the
@@ -570,13 +572,16 @@ WEBHOOK_SSRF_PROTECT=true
# URL rather than any bytes.
# CHAT_MEDIA_ARCHIVE_OUTBOUND=false # default false
# Per-file cap on archived chat media. Media above it is simply not archived; the message row and
-# its inline copy are unaffected. A non-positive/garbage value falls back.
+# its inline copy are unaffected. Unset takes the default; a value that is not a positive integer
+# fails the boot.
# CHAT_MEDIA_ARCHIVE_MAX_BYTES=26214400 # default 25 MiB
# How long archived files are kept, in days. 0 = forever. Expiry clears the FILE and the row's
# media columns; the message row itself is never deleted by this.
# CHAT_MEDIA_ARCHIVE_TTL_DAYS=0 # default 0 (keep forever)
# Orphaned chat-media reconciliation: how often the sweep re-lists chat-media files to find ones no
# row references (crash leftovers), and how long a file must be seen unreferenced before deletion.
+# Unset takes the default; a value that is not a positive integer fails the boot, and so does a
+# sweep interval above 2147483647 ms (Node's timer ceiling).
# CHAT_MEDIA_ORPHAN_SWEEP_INTERVAL_MS=3600000 # default 1h
# CHAT_MEDIA_ORPHAN_GRACE_MS=3600000 # default 1h
# Cap on the final rendered text of a send-template request (after variable substitution). Over-cap
@@ -590,7 +595,9 @@ WEBHOOK_SSRF_PROTECT=true
# STORAGE_IMPORT_MAX_ENTRIES=100000 # max entries in an import archive; aborts beyond this (default 100000)
# STORAGE_EXPORT_TTL_MS=3600000 # auto-delete an export archive after this long (default 1h)
# How often an S3-configured service re-probes a bucket that was unreachable at boot (media storage is
-# degraded to the local fallback dir until it recovers; writes return to S3 automatically).
+# degraded to the local fallback dir until it recovers; writes return to S3 automatically). Unset
+# takes the default; a value that is not a positive integer, or above 2147483647 ms (Node's timer
+# ceiling), fails the boot.
# S3_REPROBE_INTERVAL_MS=60000 # default 60s
# STORAGE_EXPORT_SWEEP_MAX_AGE_MS=86400000 # boot sweep deletes export archives orphaned by a restart, older than this (default 24h)
# Outbound rows stuck PENDING (process died between the pre-send save and the final save) are marked
@@ -613,7 +620,8 @@ WEBHOOK_SSRF_PROTECT=true
# RATE_LIMIT_LONG_LIMIT=1000
# WebSocket (/events Socket.IO) limits, enforced in-process by the gateway (WS frames bypass
-# the HTTP guard pipeline). Any blank/non-positive/non-numeric value falls back to the default.
+# the HTTP guard pipeline). Unset or blank takes the default; a value that is not a positive integer
+# fails the boot.
# Per-key token bucket on client frames (subscribe/unsubscribe/ping): the dashboard sends ~8
# subscribe frames at page mount and only occasional frames afterwards, so 60/s sustained with
# a 120-frame burst is ~6x headroom over legitimate traffic while bounding a flooding key.