Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(events): explain a subscribe that can never fit

Yudhi Armyndharisf3e9d52a74cd
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index 84138319d..b8373d383 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -7111,7 +7111,7 @@ Live events are pushed as a **nested** envelope (note: `data` is under `payload`
}
```
-Error `code` values include `UNAUTHORIZED`, `INVALID_MESSAGE`, `INVALID_SESSION`, `INVALID_EVENTS`, `FORBIDDEN_SESSION`, `FORBIDDEN_EVENTS`, `TOO_MANY_SUBSCRIPTIONS`, and `RATE_LIMITED`. `RATE_LIMITED` is followed by a disconnect when a handshake exceeds the per-IP connection-attempt window or the key's concurrent-socket cap; a frame over the per-key frame budget gets `RATE_LIMITED` and is dropped undispatched, and the socket stays open. A subscribe answers `INVALID_SESSION` when `sessionId` is missing, or is neither `"*"` nor a session id of at most 128 letters, digits and hyphens. An unsubscribe answers `INVALID_SESSION` when `sessionId` is missing, empty, not a string, or neither `"*"` nor such a session id. A subscribe answers `TOO_MANY_SUBSCRIPTIONS` when it would take the connection past 4096 rooms; chat-restricted subscriptions count every literal chat address form for each session and event. Unsubscribe before subscribing to more.
+Error `code` values include `UNAUTHORIZED`, `INVALID_MESSAGE`, `INVALID_SESSION`, `INVALID_EVENTS`, `FORBIDDEN_SESSION`, `FORBIDDEN_EVENTS`, `TOO_MANY_SUBSCRIPTIONS`, and `RATE_LIMITED`. `RATE_LIMITED` is followed by a disconnect when a handshake exceeds the per-IP connection-attempt window or the key's concurrent-socket cap; a frame over the per-key frame budget gets `RATE_LIMITED` and is dropped undispatched, and the socket stays open. A subscribe answers `INVALID_SESSION` when `sessionId` is missing, or is neither `"*"` nor a session id of at most 128 letters, digits and hyphens. An unsubscribe answers `INVALID_SESSION` when `sessionId` is missing, empty, not a string, or neither `"*"` nor such a session id. A subscribe answers `TOO_MANY_SUBSCRIPTIONS` when it would take the connection past 4096 rooms; chat-restricted subscriptions count every literal chat address form for each session and event. When the rooms already held are the cause, unsubscribe before subscribing to more. A chat-restricted frame can also need more than 4096 on its own (its address forms times the events it names); unsubscribing cannot help there: name fewer events or subscribe with `"*"`, and a list stored before the 2000-entry bound whose address forms alone exceed 4096 has to be shortened.
### Subscribable events
diff --git a/src/modules/events/events.gateway.chat-scope.spec.ts b/src/modules/events/events.gateway.chat-scope.spec.ts
index fe602c40b..494a535c4 100644
--- a/src/modules/events/events.gateway.chat-scope.spec.ts
+++ b/src/modules/events/events.gateway.chat-scope.spec.ts
@@ -187,8 +187,39 @@ describe('chat-scoped WebSocket rooms', () => {
'group.update',
'presence.update',
];
- expect(await subscribe(restricted, chatEvents)).toMatchObject({ type: 'error', code: 'TOO_MANY_SUBSCRIPTIONS' });
+ const refused = await subscribe(restricted, chatEvents);
+ expect(refused).toMatchObject({ type: 'error', code: 'TOO_MANY_SUBSCRIPTIONS' });
expect(reads).toBe(0);
+ // The socket holds nothing, so unsubscribing cannot make this fit: the reply names what each event
+ // costs this key and the way out.
+ const { message } = refused as { message: string };
+ expect(message).toContain('every event 900 subscriptions');
+ expect(message).toContain('name fewer events or use "*"');
+ expect(message).not.toContain('unsubscribe');
+ });
+
+ it('does not suggest "*" to a key whose allowlist alone is over the cap', async () => {
+ // A list stored before allowedChats was bounded: its address forms exceed what one socket may hold,
+ // so even one event never fits and only a shorter list helps.
+ const chats = Array.from({ length: 2100 }, (_, index) => `62811${String(index).padStart(7, '0')}@c.us`);
+ const restricted = await connect('restricted', chats);
+ const refused = await subscribe(restricted, ['*']);
+ expect(refused).toMatchObject({ type: 'error', code: 'TOO_MANY_SUBSCRIPTIONS' });
+ const { message } = refused as { message: string };
+ expect(message).toContain('every event 4200 subscriptions');
+ expect(message).toContain('shorten the allowlist');
+ expect(message).not.toContain('use "*"');
+ expect(message).not.toContain('unsubscribe');
+ });
+
+ it('tells a subscriber that is over the cap because of what it already holds to unsubscribe first', async () => {
+ const chats = Array.from({ length: 450 }, (_, index) => `62811${String(index).padStart(7, '0')}@c.us`);
+ const restricted = await connect('restricted', chats);
+ // The wildcard subscription holds 900 rooms; four more events add 3600, each frame within the cap alone.
+ const fourEvents = ['message.received', 'message.sent', 'message.ack', 'message.revoked'];
+ const refused = await subscribe(restricted, fourEvents, 's1');
+ expect(refused).toMatchObject({ type: 'error', code: 'TOO_MANY_SUBSCRIPTIONS' });
+ expect((refused as { message: string }).message).toContain('unsubscribe first');
});
it('performs no chat lookups for a local stream without restricted subscribers', async () => {
diff --git a/src/modules/events/events.gateway.ts b/src/modules/events/events.gateway.ts
index 4d5ced985..34e64894d 100644
--- a/src/modules/events/events.gateway.ts
+++ b/src/modules/events/events.gateway.ts
@@ -661,8 +661,15 @@ export class EventsGateway implements OnGatewayInit, OnGatewayConnection, OnGate
const chats = chatRestricted ? [...this.chatScope.scopeFor(subscriberKey)!.allowed] : undefined;
// A socket holds every room it asks for, so events x chats rooms that exceed the cap can never fit.
// Refused here, before the names are built: a large allowlist made each refused frame cost real time.
+ // No amount of unsubscribing makes that fit, so the reply names the cost per event, not the generic text.
if (chats && permittedEvents.length * chats.length > MAX_ROOMS_PER_SOCKET) {
- return this.createError('TOO_MANY_SUBSCRIPTIONS', TOO_MANY_SUBSCRIPTIONS_MESSAGE, requestId);
+ // Fewer events help only while one event fits: a list stored before allowedChats was bounded may not.
+ const remedy = chats.length <= MAX_ROOMS_PER_SOCKET ? 'name fewer events or use "*"' : 'shorten the allowlist';
+ return this.createError(
+ 'TOO_MANY_SUBSCRIPTIONS',
+ `This key's chat allowlist makes every event ${chats.length} subscriptions and a connection may hold at most ${MAX_ROOMS_PER_SOCKET}; ${remedy}`,
+ requestId,
+ );
}
const rooms = permittedEvents.flatMap(event =>
chats ? chats.map(chatId => chatRoom(sessionId, event, chatId)) : [buildRoomName(sessionId, event)],