Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix: bound the ids a request can store at the index entry size

Yudhi Armyndharis766213a81d91
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2c35e8617..e81520002 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -48,7 +48,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Fixed
- Bound each webhook and ingress queue command at 2 s once Redis has connected, so a Redis that stops answering falls back to direct delivery and inline dispatch instead of holding every dispatch and ingress request.
-- Answer `400` for a send route's `chatId` or a bulk `batchId` over 255 characters, where PostgreSQL answered `500` once the value passed its index entry limit.
+- Answer `400` for a send route's, a chat action's or a product send's `chatId`, or a bulk `batchId`, over 255 characters, where PostgreSQL answered `500` once the value passed its index entry limit.
+- Use the body hash as the delivery id of an ingress request whose dedup header is longer than 255 characters, where PostgreSQL answered `500`.
- MCP tools refuse a `chatId`, `fromChatId` or `toChatId` over 255 characters, as the send routes do, where PostgreSQL answered an internal tool error.
- A start that fails while another start of the same session is in flight leaves the claim to that start, so its engine is no longer left on a row no node holds.
- Uninstalling a plugin hands the chats it had taken over back to the bot, so other plugins are no longer silent there.
diff --git a/openapi.json b/openapi.json
index 0ae455cd4..9eabf2489 100644
--- a/openapi.json
+++ b/openapi.json
@@ -18975,6 +18975,7 @@
"properties": {
"chatId": {
"type": "string",
+ "maxLength": 255,
"description": "Chat ID in the active engine's native format (e.g. [email protected] on whatsapp-web.js)",
"example": "[email protected]"
},
@@ -19014,6 +19015,7 @@
"properties": {
"chatId": {
"type": "string",
+ "maxLength": 255,
"description": "Chat ID in the active engine's native format (e.g. [email protected] on whatsapp-web.js)",
"example": "[email protected]"
}
@@ -19102,6 +19104,7 @@
"properties": {
"chatId": {
"type": "string",
+ "maxLength": 255,
"description": "Chat ID in the active engine's native format (e.g. [email protected] on whatsapp-web.js)",
"example": "[email protected]"
}
@@ -19115,6 +19118,7 @@
"properties": {
"chatId": {
"type": "string",
+ "maxLength": 255,
"description": "Chat ID in the active engine's native format (e.g. [email protected] on whatsapp-web.js)",
"example": "[email protected]"
},
@@ -19133,6 +19137,7 @@
"properties": {
"chatId": {
"type": "string",
+ "maxLength": 255,
"description": "Chat ID in the active engine's native format (e.g. [email protected] on whatsapp-web.js)",
"example": "[email protected]"
},
@@ -19154,6 +19159,7 @@
"properties": {
"chatId": {
"type": "string",
+ "maxLength": 255,
"description": "Chat ID in the active engine's native format (e.g. [email protected] on whatsapp-web.js)",
"example": "[email protected]"
},
@@ -19172,6 +19178,7 @@
"properties": {
"chatId": {
"type": "string",
+ "maxLength": 255,
"description": "Chat ID in the active engine's native format (e.g. [email protected] on whatsapp-web.js)",
"example": "[email protected]"
}
@@ -19185,6 +19192,7 @@
"properties": {
"chatId": {
"type": "string",
+ "maxLength": 255,
"description": "Chat ID, in the active engine's native format (e.g. [email protected])",
"example": "[email protected]"
},
@@ -25022,6 +25030,7 @@
"properties": {
"chatId": {
"type": "string",
+ "maxLength": 255,
"description": "Chat to send the product card to (@c.us or @g.us).",
"example": "[email protected]"
},
diff --git a/src/modules/catalog/dto/send-product.dto.ts b/src/modules/catalog/dto/send-product.dto.ts
index 80ca9d617..02720a131 100644
--- a/src/modules/catalog/dto/send-product.dto.ts
+++ b/src/modules/catalog/dto/send-product.dto.ts
@@ -2,14 +2,20 @@ import { IsString, IsOptional, IsInt, Min, IsNotEmpty, MaxLength } from 'class-v
import { Type } from 'class-transformer';
import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
import { MESSAGE_TEXT_MAX_LENGTH } from '../../message/dto/send-message.dto';
+import { CHAT_ID_MAX_LENGTH } from '../../message/dto/send-message.dto';
/** WhatsApp catalog product ids are numeric strings of about 16-20 digits; this leaves wide headroom. */
export const PRODUCT_ID_MAX_LENGTH = 255;
export class SendProductDto {
- @ApiProperty({ description: 'Chat to send the product card to (@c.us or @g.us).', example: '[email protected]' })
+ @ApiProperty({
+ maxLength: CHAT_ID_MAX_LENGTH,
+ description: 'Chat to send the product card to (@c.us or @g.us).',
+ example: '[email protected]',
+ })
@IsString()
@IsNotEmpty()
+ @MaxLength(CHAT_ID_MAX_LENGTH)
chatId!: string;
@ApiProperty({ description: 'Catalog product id to send.', example: 'product-42', maxLength: PRODUCT_ID_MAX_LENGTH })
diff --git a/src/modules/integration/ingress.service.spec.ts b/src/modules/integration/ingress.service.spec.ts
index fbac0c079..0f8b21ed3 100644
--- a/src/modules/integration/ingress.service.spec.ts
+++ b/src/modules/integration/ingress.service.spec.ts
@@ -592,6 +592,17 @@ describe('dedupOn: body (a provider that rotates its delivery id on retry)', ()
expect((d.enqueue.mock.calls[0] as [unknown, string])[1]).toBe('d-1');
});
+ it('falls back to the body hash when the dedup header is longer than the delivery id column', async () => {
+ const d = deps();
+ await new IngressService(d).handle({ ...req, headers: { 'x-delivery': 'x'.repeat(256) }, rawBody: '{"n":1}' });
+ const id = (d.enqueue.mock.calls[0] as [unknown, string])[1];
+ expect(id).toMatch(/^[0-9a-f]{64}$/);
+ // The bound is the column's: an id of exactly 255 characters is still the provider's.
+ const edge = deps();
+ await new IngressService(edge).handle({ ...req, headers: { 'x-delivery': 'y'.repeat(255) }, rawBody: '{"n":1}' });
+ expect((edge.enqueue.mock.calls[0] as [unknown, string])[1]).toBe('y'.repeat(255));
+ });
+
// A header that is present but blank is no id at all. Taking it as one gave every delivery the
// same empty key, so the dedup row admitted the first and dropped the rest while still answering
// each provider with the route's success ack.
diff --git a/src/modules/integration/ingress.service.ts b/src/modules/integration/ingress.service.ts
index 238cdbe8c..779f8ce15 100644
--- a/src/modules/integration/ingress.service.ts
+++ b/src/modules/integration/ingress.service.ts
@@ -209,7 +209,12 @@ export class IngressService {
// dead-lettered, and the deliveries were simply gone. Fall through to the body hash, which is
// exactly the "provider supplied no id" case it already exists for.
const headerId = req.headers[dedupHeader]?.trim();
- const deliveryId = route.dedupOn === 'body' || !headerId ? deriveDeliveryId(req) : headerId;
+ // An id longer than the column holding it is no id the provider could have minted: it is stored under the
+ // unique index on PostgreSQL, which refuses a long entry with a 500, so such a header gets the body hash too.
+ const deliveryId =
+ route.dedupOn === 'body' || !headerId || headerId.length > MAX_DELIVERY_ID_LENGTH
+ ? deriveDeliveryId(req)
+ : headerId;
// Provider request headers persist with the event (redrive/debugging); credentials must not.
// Signature headers are re-derivable, auth material is not — redact before the first write.
// A shared-secret route carries the instance secret itself in its declared header, and an hmac
@@ -287,6 +292,9 @@ export class IngressService {
}
}
+/** The longest dedup header value taken as a delivery id; the column and its unique index hold 255 characters. */
+const MAX_DELIVERY_ID_LENGTH = 255;
+
/**
* Derives a DETERMINISTIC delivery id when the provider sends no dedup header, so a provider retry of
* the same delivery dedups instead of being treated as new. A random UUID would silently disable both
diff --git a/src/modules/session/dto/archive-chat.dto.ts b/src/modules/session/dto/archive-chat.dto.ts
index 0f3e8b2f3..f99acbba8 100644
--- a/src/modules/session/dto/archive-chat.dto.ts
+++ b/src/modules/session/dto/archive-chat.dto.ts
@@ -1,14 +1,17 @@
import { ApiProperty } from '@nestjs/swagger';
-import { IsBoolean, IsNotEmpty, IsString, Matches } from 'class-validator';
+import { IsBoolean, IsNotEmpty, IsString, Matches, MaxLength } from 'class-validator';
import { ToStrictBoolean } from '../../../common/utils/strict-boolean';
+import { CHAT_ID_MAX_LENGTH } from '../../message/dto/send-message.dto';
export class ArchiveChatDto {
@ApiProperty({
+ maxLength: CHAT_ID_MAX_LENGTH,
description: "Chat ID in the active engine's native format (e.g. [email protected] on whatsapp-web.js)",
example: '[email protected]',
})
@IsString()
@IsNotEmpty()
+ @MaxLength(CHAT_ID_MAX_LENGTH)
// Engine-neutral structural check (localpart@host, no whitespace) so a different engine's JID scheme
// (e.g. Baileys `…@s.whatsapp.net`) is accepted too; the adapter validates/normalises for its engine.
@Matches(/^[^\s@]+@[^\s@]+$/, {
diff --git a/src/modules/session/dto/chat-id-bound.dto.spec.ts b/src/modules/session/dto/chat-id-bound.dto.spec.ts
new file mode 100644
index 000000000..b853ab83b
--- /dev/null
+++ b/src/modules/session/dto/chat-id-bound.dto.spec.ts
@@ -0,0 +1,39 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import { validate } from 'class-validator';
+import { SendProductDto } from '../../catalog/dto/send-product.dto';
+import { ArchiveChatDto } from './archive-chat.dto';
+import { DeleteChatDto } from './delete-chat.dto';
+import { MarkChatReadDto } from './mark-chat-read.dto';
+import { MarkChatUnreadDto } from './mark-chat-unread.dto';
+import { MuteChatDto } from './mute-chat.dto';
+import { PinChatDto } from './pin-chat.dto';
+import { SubscribePresenceDto } from './presence.dto';
+import { SendChatStateDto } from './send-chat-state.dto';
+
+// A chat id is stored in an indexed column; PostgreSQL refuses an index entry past about 2.7 KB, which
+// used to surface as a 500 where SQLite stored the value. The send routes bound it at 255, and so does
+// every other request body that names a chat.
+describe('chatId is bounded at 255 characters on the chat action bodies', () => {
+ const exact = `${'1'.repeat(250)}@c.us`;
+ const over = `${'1'.repeat(251)}@c.us`;
+
+ it.each([
+ ['ArchiveChatDto', ArchiveChatDto, { archive: true }],
+ ['DeleteChatDto', DeleteChatDto, {}],
+ ['MarkChatReadDto', MarkChatReadDto, {}],
+ ['MarkChatUnreadDto', MarkChatUnreadDto, {}],
+ ['MuteChatDto', MuteChatDto, {}],
+ ['PinChatDto', PinChatDto, { pin: true }],
+ ['SubscribePresenceDto', SubscribePresenceDto, {}],
+ ['SendChatStateDto', SendChatStateDto, { state: 'typing' }],
+ ['SendProductDto', SendProductDto, { productId: 'p1' }],
+ ] as const)('%s', async (_name, Dto, rest) => {
+ const constraintsOf = async (chatId: string): Promise<string[]> => {
+ const errors = await validate(plainToInstance(Dto as new () => object, { ...rest, chatId }));
+ return errors.filter(e => e.property === 'chatId').flatMap(e => Object.keys(e.constraints ?? {}));
+ };
+ expect(await constraintsOf(over)).toContain('maxLength');
+ expect(await constraintsOf(exact)).not.toContain('maxLength');
+ });
+});
diff --git a/src/modules/session/dto/delete-chat.dto.ts b/src/modules/session/dto/delete-chat.dto.ts
index b561eee9c..5f8ddb565 100644
--- a/src/modules/session/dto/delete-chat.dto.ts
+++ b/src/modules/session/dto/delete-chat.dto.ts
@@ -1,13 +1,16 @@
import { ApiProperty } from '@nestjs/swagger';
-import { IsNotEmpty, IsString, Matches } from 'class-validator';
+import { IsNotEmpty, IsString, Matches, MaxLength } from 'class-validator';
+import { CHAT_ID_MAX_LENGTH } from '../../message/dto/send-message.dto';
export class DeleteChatDto {
@ApiProperty({
+ maxLength: CHAT_ID_MAX_LENGTH,
description: "Chat ID in the active engine's native format (e.g. [email protected] on whatsapp-web.js)",
example: '[email protected]',
})
@IsString()
@IsNotEmpty()
+ @MaxLength(CHAT_ID_MAX_LENGTH)
// Engine-neutral structural check (localpart@host, no whitespace) so a different engine's JID scheme
// (e.g. Baileys `…@s.whatsapp.net`) is accepted too; the adapter validates/normalises for its engine.
@Matches(/^[^\s@]+@[^\s@]+$/, {
diff --git a/src/modules/session/dto/mark-chat-read.dto.ts b/src/modules/session/dto/mark-chat-read.dto.ts
index 3e35c57e4..dcde985f3 100644
--- a/src/modules/session/dto/mark-chat-read.dto.ts
+++ b/src/modules/session/dto/mark-chat-read.dto.ts
@@ -1,5 +1,15 @@
import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
-import { ArrayMaxSize, ArrayNotEmpty, IsArray, IsNotEmpty, IsString, Matches, ValidateIf } from 'class-validator';
+import {
+ ArrayMaxSize,
+ ArrayNotEmpty,
+ IsArray,
+ IsNotEmpty,
+ IsString,
+ Matches,
+ ValidateIf,
+ MaxLength,
+} from 'class-validator';
+import { CHAT_ID_MAX_LENGTH } from '../../message/dto/send-message.dto';
/**
* Ceiling on one request's receipt batch, so a single call cannot hand the engine an unbounded key
@@ -20,11 +30,13 @@ export const MARK_READ_MESSAGE_ID_MESSAGE = 'each messageIds entry must be a non
export class MarkChatReadDto {
@ApiProperty({
+ maxLength: CHAT_ID_MAX_LENGTH,
description: "Chat ID in the active engine's native format (e.g. [email protected] on whatsapp-web.js)",
example: '[email protected]',
})
@IsString()
@IsNotEmpty()
+ @MaxLength(CHAT_ID_MAX_LENGTH)
// Engine-neutral structural check (localpart@host, no whitespace) so a different engine's JID
// scheme (e.g. Baileys [email protected]) is accepted too; the adapter validates/normalises
// further for its own engine. Keeps the early-400 on obvious garbage without coupling to wwebjs.
diff --git a/src/modules/session/dto/mark-chat-unread.dto.ts b/src/modules/session/dto/mark-chat-unread.dto.ts
index 4d8ca6d69..6a1806b80 100644
--- a/src/modules/session/dto/mark-chat-unread.dto.ts
+++ b/src/modules/session/dto/mark-chat-unread.dto.ts
@@ -1,5 +1,6 @@
import { ApiProperty } from '@nestjs/swagger';
-import { IsNotEmpty, IsString, Matches } from 'class-validator';
+import { IsNotEmpty, IsString, Matches, MaxLength } from 'class-validator';
+import { CHAT_ID_MAX_LENGTH } from '../../message/dto/send-message.dto';
/**
* Deliberately separate from {@link MarkChatReadDto}, which the unread route used to share. The read
@@ -8,11 +9,13 @@ import { IsNotEmpty, IsString, Matches } from 'class-validator';
*/
export class MarkChatUnreadDto {
@ApiProperty({
+ maxLength: CHAT_ID_MAX_LENGTH,
description: "Chat ID in the active engine's native format (e.g. [email protected] on whatsapp-web.js)",
example: '[email protected]',
})
@IsString()
@IsNotEmpty()
+ @MaxLength(CHAT_ID_MAX_LENGTH)
// Engine-neutral structural check (localpart@host, no whitespace) so a different engine's JID
// scheme (e.g. Baileys [email protected]) is accepted too; the adapter normalises further.
@Matches(/^[^\s@]+@[^\s@]+$/, {
diff --git a/src/modules/session/dto/mute-chat.dto.ts b/src/modules/session/dto/mute-chat.dto.ts
index daf01014e..d43ff3ee1 100644
--- a/src/modules/session/dto/mute-chat.dto.ts
+++ b/src/modules/session/dto/mute-chat.dto.ts
@@ -1,13 +1,16 @@
import { ApiProperty } from '@nestjs/swagger';
-import { IsInt, IsNotEmpty, IsString, Matches, Min, ValidateIf } from 'class-validator';
+import { IsInt, IsNotEmpty, IsString, Matches, Min, ValidateIf, MaxLength } from 'class-validator';
+import { CHAT_ID_MAX_LENGTH } from '../../message/dto/send-message.dto';
export class MuteChatDto {
@ApiProperty({
+ maxLength: CHAT_ID_MAX_LENGTH,
description: "Chat ID in the active engine's native format (e.g. [email protected] on whatsapp-web.js)",
example: '[email protected]',
})
@IsString()
@IsNotEmpty()
+ @MaxLength(CHAT_ID_MAX_LENGTH)
// Engine-neutral structural check (localpart@host, no whitespace) so a different engine's JID scheme
// (e.g. Baileys `…@s.whatsapp.net`) is accepted too; the adapter validates/normalises for its engine.
@Matches(/^[^\s@]+@[^\s@]+$/, {
diff --git a/src/modules/session/dto/pin-chat.dto.ts b/src/modules/session/dto/pin-chat.dto.ts
index 8e02499ae..47e5b35dd 100644
--- a/src/modules/session/dto/pin-chat.dto.ts
+++ b/src/modules/session/dto/pin-chat.dto.ts
@@ -1,14 +1,17 @@
import { ApiProperty } from '@nestjs/swagger';
-import { IsBoolean, IsNotEmpty, IsString, Matches } from 'class-validator';
+import { IsBoolean, IsNotEmpty, IsString, Matches, MaxLength } from 'class-validator';
import { ToStrictBoolean } from '../../../common/utils/strict-boolean';
+import { CHAT_ID_MAX_LENGTH } from '../../message/dto/send-message.dto';
export class PinChatDto {
@ApiProperty({
+ maxLength: CHAT_ID_MAX_LENGTH,
description: "Chat ID in the active engine's native format (e.g. [email protected] on whatsapp-web.js)",
example: '[email protected]',
})
@IsString()
@IsNotEmpty()
+ @MaxLength(CHAT_ID_MAX_LENGTH)
// Engine-neutral structural check (localpart@host, no whitespace) so a different engine's JID scheme
// (e.g. Baileys `…@s.whatsapp.net`) is accepted too; the adapter validates/normalises for its engine.
@Matches(/^[^\s@]+@[^\s@]+$/, {
diff --git a/src/modules/session/dto/presence.dto.ts b/src/modules/session/dto/presence.dto.ts
index 300cbfd13..1070e0079 100644
--- a/src/modules/session/dto/presence.dto.ts
+++ b/src/modules/session/dto/presence.dto.ts
@@ -1,6 +1,7 @@
import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
-import { IsBoolean, IsNotEmpty, IsString, Matches } from 'class-validator';
+import { IsBoolean, IsNotEmpty, IsString, Matches, MaxLength } from 'class-validator';
import { ToStrictBoolean } from '../../../common/utils/strict-boolean';
+import { CHAT_ID_MAX_LENGTH } from '../../message/dto/send-message.dto';
export class SetOwnPresenceDto {
@ApiProperty({
@@ -15,11 +16,13 @@ export class SetOwnPresenceDto {
export class SubscribePresenceDto {
@ApiProperty({
+ maxLength: CHAT_ID_MAX_LENGTH,
description: "Chat ID in the active engine's native format (e.g. [email protected] on whatsapp-web.js)",
example: '[email protected]',
})
@IsString()
@IsNotEmpty()
+ @MaxLength(CHAT_ID_MAX_LENGTH)
// Same engine-neutral structural check the other chat-scoped DTOs use: localpart@host, no
// whitespace, so a different engine's JID scheme is accepted and the adapter normalises further.
@Matches(/^[^\s@]+@[^\s@]+$/, {
diff --git a/src/modules/session/dto/send-chat-state.dto.ts b/src/modules/session/dto/send-chat-state.dto.ts
index 0c3036fc9..c86436a99 100644
--- a/src/modules/session/dto/send-chat-state.dto.ts
+++ b/src/modules/session/dto/send-chat-state.dto.ts
@@ -1,9 +1,11 @@
import { ApiProperty } from '@nestjs/swagger';
-import { IsIn, IsNotEmpty, IsString } from 'class-validator';
+import { IsIn, IsNotEmpty, IsString, MaxLength } from 'class-validator';
import type { ChatState } from '../../../engine/interfaces/whatsapp-engine.interface';
+import { CHAT_ID_MAX_LENGTH } from '../../message/dto/send-message.dto';
export class SendChatStateDto {
@ApiProperty({
+ maxLength: CHAT_ID_MAX_LENGTH,
// Engine-neutral on purpose: the chat id is whatever the active engine uses
// (e.g. <number>@c.us on whatsapp-web.js, <number>@s.whatsapp.net on Baileys).
// The adapter validates/normalises it — we only require a non-empty string here.
@@ -12,6 +14,7 @@ export class SendChatStateDto {
})
@IsString()
@IsNotEmpty()
+ @MaxLength(CHAT_ID_MAX_LENGTH)
chatId!: string;
@ApiProperty({