Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(api): say a session delete is not atomic
Yudhi Armyndharise1fbd606c6b4
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.mdindex b68fee563..db245990d 100644--- a/docs/06-api-specification.md+++ b/docs/06-api-specification.md@@ -1286,7 +1286,7 @@ Delete a session.**Response** `204` — empty body (`@HttpCode(204)`, returns void). A `findOne` lookup runs first, so a missing id yields `404`.-The delete removes, in one transaction, the session's messages, message batches, chat states, received statuses, webhooks, templates, stored Baileys messages, automation rules, webhook outbox rows, webhook delivery-failure records, integration dead-letter rows and send idempotency claims, then purges its on-disk auth data. It keeps the audit log, the LID mappings, and the integration conversation mappings (so a re-paired session keeps its provider conversations); ingress dedup rows age out on their own after `INGRESS_DEDUP_RETENTION_DAYS` (default 7).+The delete first removes the session's messages, webhook outbox rows and webhook delivery-failure records in batches that are not atomic with the rest: a failure part-way (a database error, a timeout, a restart) leaves the session in place with fewer rows, and repeating the delete finishes it. It then removes, in one transaction, the session's message batches, chat states, received statuses, webhooks, templates, stored Baileys messages, automation rules, integration dead-letter rows and send idempotency claims together with the session itself, then purges its on-disk auth data. It keeps the audit log, the LID mappings, and the integration conversation mappings (so a re-paired session keeps its provider conversations); ingress dedup rows age out on their own after `INGRESS_DEDUP_RETENTION_DAYS` (default 7).**Errors:** `401` missing/invalid key · `403` key not scoped to this session, or key role below OPERATOR · `404` session not found · `409` credential teardown for the same session name still in flight (retryable; body carries `code: 'SESSION_NAME_TEARDOWN_PENDING'`; on a `409` the row is **not** deleted and no hook/auth-purge runs — retry after cleanup settles), or, on a multi-node deployment, another node currently holds this session's live engine (no `code`; nothing is deleted; send the delete to the owning node)diff --git a/docs/31-session-lifecycle-design.md b/docs/31-session-lifecycle-design.mdindex a4e7a551d..9fa3c1d0f 100644--- a/docs/31-session-lifecycle-design.md+++ b/docs/31-session-lifecycle-design.md@@ -70,7 +70,8 @@ FAILED + reason while an init that never completes returns 504 + eviction.### INV-5 — Delete racing a start re-purges auth directories after init resolves-**Interleaving:** delete runs (purges dirs, removes the session row and its child rows in one+**Interleaving:** delete runs (purges dirs, removes the session's messages, outbox rows and+delivery failures in batches, then the session row and its other child rows in onetransaction); the in-flight start's `initialize()` resolves and re-creates the auth dir; a phantomsession lingers on disk.**Defense:** the post-init guards in `start()` (`session-engine-controls.ts`) and `executeReconnect`