chore(sqs): increase maximum message size limit to 1 MiB

[pahud]

Issue # (if applicable)

Closes #35276.

Reason for this change

AWS SQS recently increased the maximum message size limit from 256KB to 1MB (announced August 2025), but the CDK validation logic still enforces the old 256KB limit. This prevents users from creating SQS queues with the new maximum message size of 1MB, limiting their ability to fully utilize AWS SQS capabilities.

This enhancement aligns the CDK validation with the current AWS SQS service limits, enabling developers to create queues that can handle larger messages up to 1MB as supported by the underlying AWS service.

Description of changes

Updated the SQS queue validation logic and documentation to support the new 1MB maximum message size limit:

• Validation Logic Update: Modified validate-queue-props.ts to change the maximum limit from 262,144 bytes (256KB) to 1,048,576 bytes (1MB) in the validateRange function call
• Error Message Update: Updated validation error messages to reflect the new 1,048,576 byte limit for better user guidance
• JSDoc Documentation: Updated documentation in queue.ts to reflect the new maximum limit from "262144 bytes (256 KiB)" to "1048576 bytes (1 MiB)"
• TypeScript Definitions: Updated corresponding TypeScript definition files to maintain consistency
• Comprehensive Test Coverage: Added extensive test cases covering boundary validation, token handling, multi-error scenarios, and CloudFormation synthesis

Key Design Decisions:

• Maintained the minimum limit of 1,024 bytes (unchanged)
• Preserved the default value documentation as 256KB since AWS SQS service default remains unchanged
• Used consistent numeric formatting with underscores (1_048_576) following existing code patterns
• Ensured full backward compatibility - all existing valid values remain valid

Why These Changes Address the Issue:

• Expands the valid range from 1024-262144 bytes to 1024-1048576 bytes
• Enables users to create SQS queues with message sizes up to 1MB as supported by AWS
• Provides clear error messages when limits are exceeded
• Maintains all existing functionality while adding new capabilities

Describe any new or updated permissions being added

N/A - This change only updates validation limits and does not require any new IAM permissions or modify resource access patterns.

Description of how you validated changes

Unit Tests: Added comprehensive test coverage with 5 new test scenarios:

• Boundary validation tests for minimum (1023 invalid, 1024 valid) and maximum (1048576 valid, 1048577 invalid) limits
• CDK token handling test to ensure validation is properly skipped for tokens
• Multi-error validation test to verify maxMessageSizeBytes validation works alongside other property validation
• CloudFormation synthesis test to ensure correct CloudFormation property generation with new limits

Integration Tests: Verified that CDK synthesizes correct CloudFormation templates with the new maximum message size values and that the MaximumMessageSize property is correctly set to 1048576.

Manual Validation:

• Confirmed all existing tests continue to pass, ensuring no regression in functionality
• Verified that validation logic correctly accepts values up to 1MB and rejects values above 1MB
• Tested error message accuracy and helpfulness for out-of-range values
• Validated JSDoc documentation consistency across all modified files

Regression Testing: All existing SQS tests pass without modification, confirming full backward compatibility is maintained. No existing functionality is broken by these changes.

Performance Testing: No performance impact expected as this only changes validation constants and adds minimal test overhead.

Checklist

• My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

[pahud]

self-review and TODO notes:

The current tests are quite comprehensive and cover the essential scenarios: boundary conditions, token handling, and CloudFormation synthesis. They effectively validate the change.

However, if we were to raise the bar even higher, we could make a small improvement by using data-driven tests for the boundary validation. This would make the test more concise and easier to
extend in the future.

Here's how we could refactor the maxMessageSizeBytes validation enforces correct limits test using test.each:

    1 test.each([
    2   { size: 1023, valid: false, description: 'just below lower bound' },
    3   { size: 1024, valid: true, description: 'at lower bound' },
    4   { size: 1048576, valid: true, description: 'at upper bound' },
    5   { size: 1048577, valid: false, description: 'just above upper bound' },
    6 ])('maxMessageSizeBytes validation for $size bytes ($description)', ({ size, valid }) => {
    7   const stack = new Stack();
    8   const constructId = `QueueWithSize${size}`;
    9   const action = () => new sqs.Queue(stack, constructId, { maxMessageSizeBytes: size });
   10
   11   if (valid) {
   12     expect(action).not.toThrow();
   13   } else {
   14     expect(action).toThrow(`Queue initialization failed due to the following validation error(s):\\n- maximum message size must be between 1,024 and 1,048,576 bytes, but ${size} was
      provided`);
   15   }
   16 });

Benefits of this approach:

• Readability: The test cases are defined in a clear, tabular format, making it easy to see what's being tested.
• Maintainability: If we need to add more test cases in the future (e.g., for other invalid values), we can simply add a new entry to the array without writing any new test logic.
• Conciseness: It reduces the boilerplate code of having multiple expect statements for similar checks.

[mergify]

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

[mergify]

Thank you for contributing! Your pull request will be updated from main and then merged automatically (do not update manually, and be sure to allow changes to be pushed to your fork).

[github-actions]

Comments on closed issues and PRs are hard for our team to see.
If you need help, please open a new issue that references this one.