Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(config): describe the S3 endpoint check and the receipt cap

Yudhi Armyndharisc83d8fadd92c
diff --git a/.env.example b/.env.example
index 478600709..c127476a1 100644
--- a/.env.example
+++ b/.env.example
@@ -437,7 +437,8 @@ DATABASE_SYNCHRONIZE=false # WARNING: Set false in production! (data DB
# below for you when you pick the built-in MinIO. Setting MINIO_BUILTIN=true by hand does not: it
# starts the bundled container and nothing else, so a hand-edited file still needs the keys set.
# S3_ENDPOINT is OPTIONAL: leave it unset for standard AWS S3 (derived from region); set it only for
-# an S3-compatible store (MinIO, R2, …), which also enables path-style addressing.
+# an S3-compatible store (MinIO, R2, …), which also enables path-style addressing. A set value must
+# be an absolute http:// or https:// URL; the app refuses to start without the scheme.
# S3_ENDPOINT=http://localhost:9000 # uncomment / set ONLY for an S3-compatible store (MinIO, R2)
# S3_BUCKET=openwa
# S3_REGION=us-east-1
@@ -470,18 +471,16 @@ WEBHOOK_RETRY_DELAY=5000 # Base delay between retries in ms (doubles
# Opt-in events such as message.receipt are bounded per receiving
# webhook instead: a quarter of WEBHOOK_DISPATCH_CONCURRENCY
# deliveries run at once, divided among the session's webhooks
- # that name the event and one at least for each, and three
+ # that name the event, and three
# quarters of this many events wait; further ones are dropped,
# not replayed, and counted in
# openwa_webhook_delivery_failures_total. A webhook whose
# receiver never answers holds only its own places, but the pool
- # is shared: a session holds up to four at once (one per webhook
- # past four), and another session's events wait for a slot once
- # such sessions together hold all of them, four sessions at the
- # defaults. A webhook's share is fixed when its queue is created
- # and kept while it has events, so receipt webhooks added
- # meanwhile can briefly raise a session above four. The events
- # waiting are not capped process-wide.
+ # is shared: a session holds at most a quarter of the pool at once
+ # (four at the defaults) however many of its webhooks name the
+ # event, and another session's events wait for a slot once such
+ # sessions together hold all of them. The events waiting are not
+ # capped process-wide.
# Each inline delivery holds its event's inline media (up to
# 4/3 x WEBHOOK_MEDIA_INLINE_MAX_BYTES as base64), up to about
# 1.3 GiB per process at the defaults; QUEUE_ENABLED=true keeps
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 005ff723b..e816e5e74 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -54,6 +54,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Serve every page after the first of `GET /api/sessions/{sessionId}/chats` and `GET /api/sessions/{sessionId}/contacts` from the list the engine returned within the last 5 s, so walking a large account costs one engine read instead of one per page.
- Name the Go SDK status font constants after the WhatsApp protocol (`StatusFontSystemText`, `StatusFontFBScript`, `StatusFontMorningBreezeRegular`, `StatusFontCalistogaRegular`, `StatusFontExo2ExtraBold`, `StatusFontCourierPrimeBold`), from Go SDK 0.7.0; the old names, which did not match the font each id selects, stay as deprecated aliases.
- Refuse to start with `REDIS_TLS=true` or a `REDIS_USERNAME` other than `default` beside the built-in Redis, which serves plain TCP and only its default user, where every Redis connection failed; the Infrastructure page refuses to save that combination.
+- Refuse to start with `STORAGE_TYPE=s3` and an `S3_ENDPOINT` that is not an absolute `http://` or `https://` URL, where every S3 call failed and media went to local disk; the Infrastructure page refuses to save it.
### Fixed
@@ -305,6 +306,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Keep a plugin's registry entry until its uninstall has removed its files, so a failed uninstall can be repeated.
- Carry a plugin's stored data into the new tree before an update swaps it in.
- Refuse a plugin catalog entry whose id, name, version or text fields are not text, and accept null in its optional fields.
+- Log once each `SSRF_ALLOWED_HOSTS` entry that carries a scheme, port, path or wildcard, which never matches a host.
### Dependencies
@@ -339,6 +341,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- `envPinned` of `GET /api/infra/status` can list any of the 31 settings a save of the Infrastructure page writes, where 0.25.0 listed eight; a client that reads it must expect the database, Redis and S3 keys and the built-in flags too.
- The dashboard status composer offers only fonts 0 to 7 on whatsapp-web.js, which posts 8 to 10 in the default font; the API still accepts every font id.
- A boot with `REDIS_TLS=true` or a named `REDIS_USERNAME` beside the built-in Redis (`REDIS_BUILTIN=true` with the bundled host) is refused; set `REDIS_TLS=false` and clear the username, or use an external Redis.
+- A boot with `STORAGE_TYPE=s3` and an `S3_ENDPOINT` without `http://` or `https://` (for example `minio:9000`) is refused; add the scheme.
- `POST /api/sessions/{sessionId}/groups/{groupId}/membership-requests/approve` and `/reject` answer `400` for a JSON list body or a content type other than JSON or form encoding; they used to act on every pending request. Send `{}` or no body for that.
- On whatsapp-web.js, `POST /api/sessions/{sessionId}/pairing-code` answers `409` for a number that is the stored phone of another session of the gateway.
- On SQLite the first boot checks the message search index against all stored text and rebuilds it when they differ, so a large database starts more slowly while the port is closed.
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index 5c5f1b0a4..8ba6f75bc 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -5767,7 +5767,7 @@ Built-in flags: a section sent without `builtIn` follows its stored host or endp
}
```
-Write/IO errors are caught and returned as HTTP `200` with `{ "saved": false, "envPath": "", "profiles": [], "message": "Failed to save configuration: …" }`. DTO validation, an unknown engine type, an invalid `database.schema`, CR/LF injection, a value that cannot be stored so that it reads back unchanged, and a merged config the production boot guard would reject (an empty or default `DATABASE_PASSWORD` or S3 key on an external datastore, or a placeholder `REDIS_PASSWORD`; message starts `Refusing to save a configuration that would be rejected at production boot.`), and a merged config the boot environment validation rejects, such as a PostgreSQL selection without a host, a pool size that is not an integer or `REDIS_TLS=true` beside the built-in Redis (message starts `Refusing to save a configuration that fails boot validation.` and carries the boot message), and a local `storage.localPath` the app cannot create or write (message starts `Refusing to save the storage path`; the next start would refuse to boot on it, and a path pinned by the host environment or the project `.env` is not judged, as the boot never reads the submitted one) are real HTTP `400` responses, and nothing is written. `profiles` lists newly-required Docker profiles.
+Write/IO errors are caught and returned as HTTP `200` with `{ "saved": false, "envPath": "", "profiles": [], "message": "Failed to save configuration: …" }`. DTO validation, an unknown engine type, an invalid `database.schema`, CR/LF injection, a value that cannot be stored so that it reads back unchanged, and a merged config the production boot guard would reject (an empty or default `DATABASE_PASSWORD` or S3 key on an external datastore, or a placeholder `REDIS_PASSWORD`; message starts `Refusing to save a configuration that would be rejected at production boot.`), and a merged config the boot environment validation rejects, such as a PostgreSQL selection without a host, a pool size that is not an integer, `REDIS_TLS=true` beside the built-in Redis or an `S3_ENDPOINT` that is not an `http(s)` URL while `STORAGE_TYPE=s3` (message starts `Refusing to save a configuration that fails boot validation.` and carries the boot message), and a local `storage.localPath` the app cannot create or write (message starts `Refusing to save the storage path`; the next start would refuse to boot on it, and a path pinned by the host environment or the project `.env` is not judged, as the boot never reads the submitted one) are real HTTP `400` responses, and nothing is written. `profiles` lists newly-required Docker profiles.
**Errors:** `400` unknown/mistyped body field, a `database.type`/`storage.type` left out with none stored or pinned, unknown
`engine.type`, invalid `database.schema`, CR-LF in a value, a value that cannot round-trip through the