feat(event-handler): warn when AppSync Events payload exceeds 240 KB per-event limit

[dreamorosi]

Summary

Changes

Adds an opt-in warnOnLargePayload option to the AppSyncEventsResolver. When enabled, the resolver emits a warn log whenever an individual event in the response exceeds the AWS AppSync Events per-event size limit of 240 KB (including the event id).

Events larger than this limit are silently dropped by AppSync and never delivered to subscribers, which is hard to diagnose. This gives customers a way to detect the problem before messages are lost.

Details:

• New warnOnLargePayload flag on RouterOptions, disabled by default (measuring size requires serializing each event, which has a cost on large batches).
• Works in both per-event and aggregate modes, since the limit applies per event regardless of how the handler is invoked.
• The check measures the assembled { id, payload } item with Buffer.byteLength(JSON.stringify(...)) so it reflects what AppSync sees on the wire (including the id, which the library injects in non-aggregate mode and the customer cannot otherwise measure).
• Warnings are deduplicated once per channel path to avoid log spam.

This implements the outcome discussed in the issue: a warning rather than a public getSize() (which cannot see the library-injected id in non-aggregate mode) or a post-publish hook.

Tests and documentation (new "Detecting oversized events" section + snippet) are included.

Issue number: closes #4020

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
19.3% Duplication on New Code

See analysis details on SonarQube Cloud