Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(env): say which numeric knobs now fail the boot

Yudhi Armyndharis62058f142a1b
diff --git a/.env.example b/.env.example
index 3d1d9a5ef..cb128ade2 100644
--- a/.env.example
+++ b/.env.example
@@ -359,7 +359,8 @@ DATABASE_SYNCHRONIZE=false # WARNING: Set false in production! (data DB
# DATABASE_SSL_REJECT_UNAUTHORIZED=true # Set false to allow self-signed certs (only when DATABASE_SSL=true)
# PostgreSQL connection pool size.
# DATABASE_POOL_SIZE=10
-# Postgres pool/query timeouts (ms). Defaults are conservative; set any to 0 to disable.
+# Postgres pool/query timeouts (ms). Defaults are conservative; set any to 0 to disable; a value
+# above 2147483647 fails the boot.
# DATABASE_STATEMENT_TIMEOUT_MS=30000 # Aborts a single runtime query that runs longer (server-side; not applied to migrations)
# DATABASE_IDLE_TIMEOUT_MS=30000 # Closes idle pooled connections after this long
# DATABASE_CONNECTION_TIMEOUT_MS=10000 # Fails fast if a new connection can't be acquired in time
@@ -498,7 +499,8 @@ WEBHOOK_SSRF_PROTECT=true
# a name that cannot resolve fails the create/update with a 400 until DNS answers for it.
# DNS resolution deadline (ms) inside the SSRF guard. The default (10000) is generous for healthy
# resolvers; lowering it shrinks the window a slow/hanging resolver can pin a worker, raising it
-# widens that window — tune deliberately. A non-positive/garbage value falls back to the default.
+# widens that window — tune deliberately. A value that is not a positive integer, or above
+# 2147483647, fails the boot.
# SSRF_DNS_TIMEOUT_MS=10000
# Server-side media size/time limits:
# MEDIA_DOWNLOAD_ENABLED=true # Set to false to skip downloading inbound media entirely
@@ -672,9 +674,9 @@ WEBHOOK_SSRF_PROTECT=true
# Outbound rows stuck PENDING (process died between the pre-send save and the final save) are marked
# FAILED with a `reapedAt` metadata marker by a periodic reaper, which also re-emits
# `message:persisted` so hook-driven search providers reconcile. Set the interval to 0 to disable
-# the reaper; a blank or unparseable value falls back to the default instead of disabling it, and a
-# value above 2147483647 ms (Node's timer ceiling) fails the boot. The same ceiling applies to the
-# INGRESS_ and WEBHOOK_RECONCILE_INTERVAL_MS knobs below.
+# the reaper; a blank value falls back to the default instead of disabling it, and a negative or
+# unparseable value, or one above 2147483647 ms (Node's timer ceiling), fails the boot. The same
+# rules apply to the INGRESS_ and WEBHOOK_RECONCILE_INTERVAL_MS knobs below.
# MESSAGE_REAPER_INTERVAL_MS=600000 # how often the reaper sweeps (default 10min)
# MESSAGE_REAPER_GRACE_MS=3600000 # only rows older than this are reaped (default 1h)
# MESSAGE_REAPER_BATCH_SIZE=50 # max rows reaped per sweep (default 50)
@@ -747,7 +749,7 @@ WEBHOOK_SSRF_PROTECT=true
# delivery id — a replay is idempotent against a job that did get enqueued, and re-checks the
# instance is still eligible first. Budget exhaustion marks the event failed and files a DLQ
# row, so recovery continues through the redrive endpoint instead of looping forever.
-# INGRESS_RECONCILE_INTERVAL_MS=60000 # sweep interval; 0 disables the reconciler (a negative value falls back to the default)
+# INGRESS_RECONCILE_INTERVAL_MS=60000 # sweep interval; 0 disables the reconciler
# INGRESS_RECONCILE_GRACE_MS=60000 # age a 'pending' row must pass before it counts as stuck
# INGRESS_RECONCILE_BATCH_SIZE=50 # stale rows replayed per sweep, oldest first
# INGRESS_RECONCILE_MAX_ATTEMPTS=5 # replays per event before it goes terminal + DLQ (min 1)
@@ -757,7 +759,7 @@ WEBHOOK_SSRF_PROTECT=true
# nothing left behind. Each delivery is now recorded before it is attempted and retired once a
# durable owner has it (handed to the queue, or completed inline), and this sweep replays whatever
# is still stranded, reusing the STORED idempotency key so a receiver can dedup the retry.
-# WEBHOOK_RECONCILE_INTERVAL_MS=60000 # sweep interval; 0 disables the reconciler (a negative value falls back to the default)
+# WEBHOOK_RECONCILE_INTERVAL_MS=60000 # sweep interval; 0 disables the reconciler
# WEBHOOK_RECONCILE_GRACE_MS=60000 # age a 'pending' row must pass before it counts as stranded
# WEBHOOK_RECONCILE_BATCH_SIZE=50 # stranded rows replayed per sweep, oldest first
# WEBHOOK_RECONCILE_MAX_ATTEMPTS=5 # replays before the row goes terminal (min 1)
@@ -932,6 +934,8 @@ PLUGINS_DIR=./data/plugins # Plugin directory (default: ./data/plugins)
# production instance without flipping NODE_ENV; false forces it off
# everywhere. Same exact-string contract as ENABLE_SWAGGER above.
# BODY_SIZE_LIMIT=25mb # Max request body size (base64 media sends ride in the JSON body)
+ # Units b, kb, mb, gb, tb, pb (a bare number is bytes); 0 or an
+ # unknown unit (e.g. 50M, 50MiB) fails the boot.
# Aggregate cap on request-body bytes buffered across ALL connections. Once exceeded, new requests
# get 503 + Retry-After without their body being read (protects against slow-body memory pinning).
# Keep it >= 2 x BODY_SIZE_LIMIT: an API key may hold at most half of it, so below that a full-size
diff --git a/docs/04-security-design.md b/docs/04-security-design.md
index 610445a35..aa04a18a3 100644
--- a/docs/04-security-design.md
+++ b/docs/04-security-design.md
@@ -318,7 +318,7 @@ The windows above run at the routing layer, after a request body has been buffer
### WebSocket (`/events`) limits
-Socket.IO frames never pass through the Nest enhancer pipeline, so the HTTP windows above do **not** apply to the WebSocket surface. `EventsGateway` enforces its own in-process limits instead (all keyed in-memory per process; any blank/non-positive/non-numeric env value falls back to the default):
+Socket.IO frames never pass through the Nest enhancer pipeline, so the HTTP windows above do **not** apply to the WebSocket surface. `EventsGateway` enforces its own in-process limits instead (all keyed in-memory per process; a blank env value falls back to the default, and one that is not a positive integer fails the boot):
| Limit | Keyed on | Default | Env overrides |
| ------------------------------------------------------------------- | --------------------------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------- |