Add configurable UUID conversion for non-AWS SQS-compatible services by jm0514 · Pull Request #1433 · awspring/spring-cloud-aws

jm0514 · 2025-08-09T09:15:57Z

Add configurable UUID conversion for non-AWS SQS-compatible services

📢 Type of change

Bugfix
New feature
Enhancement
Refactoring

📜 Description

Added configurable support for SQS-compatible cloud services (like Yandex Message Queue) that use non-UUID MessageId formats. The framework now supports both UUID and non-UUID MessageId handling through a new configuration option.

Configuration:

# For AWS SQS (default behavior)
spring.cloud.aws.sqs.convert-message-id-to-uuid=true

# For non-AWS SQS-compatible services (Yandex, etc.)
spring.cloud.aws.sqs.convert-message-id-to-uuid=false

💡 Motivation and Context

Solves #814

💚 How did you test it?

Unit Tests: Added comprehensive tests for SqsHeaderMapper and MessageHeaderUtils

📝 Checklist

I reviewed submitted code
I added tests to verify changes
I updated reference documentation to reflect the change
All tests passing
No breaking changes

🔮 Next steps

maciejwalkowiak · 2025-08-22T13:38:19Z

spring-cloud-aws-sqs/src/main/java/io/awspring/cloud/sqs/support/converter/SqsHeaderMapper.java

+			accessor.setHeader(SqsHeaders.SQS_AWS_MESSAGE_ID_HEADER, source.messageId());
+			MessageHeaders messageHeaders = accessor.toMessageHeaders();
+			logger.trace("Mapped headers {} for message {}", messageHeaders, source.messageId());
+			return new MessagingMessageHeaders(messageHeaders, UUID.randomUUID());


Passing a random UUID does not feel right. Perhaps MessagingMessageHeaders can have id set as String instead of UUID? cc @tomazfernandes

Thanks for the suggestion! Updated to generate UUID from Message ID instead of random UUID.

tomazfernandes · 2025-09-02T20:52:52Z

Hey @jm0514, thanks for the PR!

Perhaps MessagingMessageHeaders can have id set as String instead of UUID? cc @tomazfernandes

@maciejwalkowiak, the issue there is that the MessagingMessageHeaders inherits from MessageHeaders from Spring, and that one requires an UUID type in the constructor.

Might be worth raising with the Spring Messaging team?

In the meantime, I think we can make the solution simpler if we leverage the fact that most ID-related operations are made through the MessageHeaderUtils#getId method, which already returns a String.

Instead of requiring a configuration change to support other ID types, we could simplify the logic by trying to parse the UUID, and if it fails we add the new header as suggested in the PR.

Then in the MessageHeaderUtils#getId method, we check for the header first, and return either that, or the Spring Message ID if the former is absent.

The caveat would be that for non UUID ids, the result from getting the ID header directly would be a random UUID, but I don't think there's a way around it with the existing MessageHeaders implementation, so properly documenting the behavior should suffice. And since we don't currently support that anyway, we wouldn't really need a breaking change.

What do you folks think?

jm0514 · 2026-02-20T13:07:55Z

Fail-fast: When convert-message-id-to-uuid=true (default), receiving a non-UUID message ID now throws a MessagingException with a clear error
message and instructions.
Send-side parity: SqsTemplate now handles non-UUID message IDs in send responses. SendResult.messageId() returns a deterministic UUID, and the raw
ID is available via SendResult.additionalInformation() under the rawMessageId key.
Naming consistency: Renamed Sqs_AWSMessageId → Sqs_RawMessageId and getAwsMessageId() → getRawMessageId() to be provider-neutral and consistent
across receive/send sides.
Documentation: Added Non-UUID Message IDs section in sqs.adoc and property entry in _configprops.adoc.

…nses

tomazfernandes

Hey @jm0514, thanks for the updates. Overall direction looks solid.

I have a couple of suggestions to simplify the design and reduce duplication.

tomazfernandes · 2026-03-08T16:00:07Z

...ws-autoconfigure/src/main/java/io/awspring/cloud/autoconfigure/sqs/SqsAutoConfiguration.java

-		public MessagingMessageConverter<Message> messageConverter(ObjectProvider<JsonMapper> jsonMapperProvider) {
-			JsonMapper jsonMapper = jsonMapperProvider.getIfAvailable();
-			return jsonMapper != null ? new SqsMessagingMessageConverter(jsonMapper)
+		public MessagingMessageConverter<Message> messageConverter(ObjectProvider<JsonMapper> jsonMapperProvider,


Currently the auto-config manually creates a SqsHeaderMapper and sets the flag on it. Instead, let's add convertMessageIdToUuid as a property on both SqsContainerOptions and SqsTemplateOptions, so auto-config just does:

factory.configure(options -> options.convertMessageIdToUuid(sqsProperties.getConvertMessageIdToUuid())); builder.configure(options -> options.convertMessageIdToUuid(sqsProperties.getConvertMessageIdToUuid()));

This keeps the configuration surface consistent between container and template, removes the manual SqsHeaderMapper creation from auto-config, and gives programmatic users (without auto-config) a clean way to set it through the standard options API.

Thanks for the great suggestion! This makes the configuration much cleaner and consistent with the existing patterns.

Applied in 1d32b0c. Moved convertMessageIdToUuid to both SqsContainerOptions and SqsTemplateOptions, so auto-config now uses factory.configure() and builder.configure() instead of manually creating SqsHeaderMapper.
Added getHeaderMapper() to AbstractMessagingMessageConverter to propagate the option to the header mapper.

tomazfernandes · 2026-03-08T16:12:49Z

spring-cloud-aws-sqs/src/main/java/io/awspring/cloud/sqs/support/converter/SqsHeaderMapper.java

-		MessageHeaders messageHeaders = accessor.toMessageHeaders();
-		logger.trace("Mapped headers {} for message {}", messageHeaders, source.messageId());
-		return new MessagingMessageHeaders(messageHeaders, UUID.fromString(source.messageId()));
+


Let's consolidate this logic so we get consistent behavior across both listener and template.

My suggestion would be to create a SqsMessageIdResolver utility class with a method such as:

public static MessageHeaders resolveAndAddMessageId(String messageId, MessageHeaders headers, boolean convertMessageIdToUuid) { MessageHeaders withRawId = MessageHeaderUtils.addHeaderIfAbsent( headers, SqsHeaders.SQS_RAW_MESSAGE_ID_HEADER, messageId); if (isValidUuid(messageId)) { return new MessagingMessageHeaders(withRawId, UUID.fromString(messageId)); } if (convertMessageIdToUuid) { throw new MessagingException(String.format( "Message ID '%s' is not a valid UUID. To support non-UUID message IDs, " + "set 'spring.cloud.aws.sqs.convert-message-id-to-uuid=false'. " + "The raw message ID will be available via the '%s' header.", messageId, SqsHeaders.SQS_RAW_MESSAGE_ID_HEADER)); } return new MessagingMessageHeaders(withRawId, UUID.nameUUIDFromBytes(messageId.getBytes(StandardCharsets.UTF_8))); } private static boolean isValidUuid(String value) { try { UUID.fromString(value); return true; } catch (IllegalArgumentException e) { return false; } }

Then we'd use it in both SqsHeaderMapper and SqsTemplate.

Open to suggestions if you have a different idea.

Your suggestion was clear and well thought out, so I followed it as proposed.

Applied in f1d7a50. Created SqsMessageIdResolver with resolveAndAddMessageId() for the listener side and resolveUuid() / isValidUuid() for the template side.
Both SqsHeaderMapper and SqsTemplate now delegate to this utility class.

tomazfernandes

@jm0514, thanks for the updates. I left a few comments, we're getting closer.

The main point is that there's a mismatch between what Spring Messaging exposes, which is a UUID-based Message, and the SQS contract, which uses String ids.

Therefore we need a consistent message-id translation layer exposed consistently to users regardless of whether they're using SQS directly or another compatible implementation.

This also makes it easier to move between SQS and SQS-compatible services over time.

Also, please add @since 4.1.0 to the new classes.

tomazfernandes · 2026-03-14T19:39:56Z

spring-cloud-aws-sqs/src/main/java/io/awspring/cloud/sqs/operations/SqsTemplate.java

+		if (sequenceNumber != null) {
+			additionalInfo.put(SqsTemplateParameters.SEQUENCE_NUMBER_PARAMETER_NAME, sequenceNumber);
+		}
+		UUID messageId = SqsMessageIdResolver.resolveUuid(rawMessageId);


I'd suggest always adding the new header to originalMessage through resolveAndAddMessageId, then reading the UUID value back from the resulting message.

That keeps the behavior consistent between receive and send paths and avoids silently handling the UUID conversion when not explicitly configured.

That also allows us to make the remaining methods of SqsMessageIdResolver private.

tomazfernandes · 2026-03-14T19:42:19Z

spring-cloud-aws-sqs/src/main/java/io/awspring/cloud/sqs/operations/SqsTemplateParameters.java

+	/**
+	 * The raw provider message ID when it is not a valid UUID.
+	 */
+	public static final String RAW_MESSAGE_ID_PARAMETER_NAME = "rawMessageId";


Let's name it "SQS_RAW_MESSAGE_ID_PARAMETER_NAME" for consistency with the header.

tomazfernandes · 2026-03-14T19:50:51Z

spring-cloud-aws-sqs/src/main/java/io/awspring/cloud/sqs/operations/SqsTemplate.java

+		}
+		UUID messageId = SqsMessageIdResolver.resolveUuid(rawMessageId);
+		if (!SqsMessageIdResolver.isValidUuid(rawMessageId)) {
+			additionalInfo.put(SqsTemplateParameters.RAW_MESSAGE_ID_PARAMETER_NAME, rawMessageId);


If this id is already added to the MessageHeaders, we may not need to also expose it through additionalInfo.

If we keep this parameter, we should always add it so users can rely on it regardless of whether they are using SQS or another implementation.

tomazfernandes · 2026-03-14T19:55:57Z

...src/main/java/io/awspring/cloud/sqs/support/converter/AbstractMessagingMessageConverter.java

+	 * {@link software.amazon.awssdk.services.sqs.model.Message} instances.
+	 * @return the header mapper instance.
+	 */
+	public HeaderMapper<S> getHeaderMapper() {


We could change to a configuration-style API here, for example configureHeaderMapper(Consumer<HeaderMapper<S>> configurer).

That preserves encapsulation and keeps the API aligned with the configuration patterns used in the project.

tomazfernandes · 2026-03-14T19:57:30Z

...ud-aws-sqs/src/main/java/io/awspring/cloud/sqs/listener/source/AbstractSqsMessageSource.java

+		configureHeaderMapper(sqsContainerOptions);
+	}
+
+	private void configureHeaderMapper(SqsContainerOptions sqsContainerOptions) {


Let's move the configuration logic to SqsMessageIdResolver and centralize all message id resolution logic there and keep behavior consistent between the template and message source.

I suggest something along these lines:

public static void configureMessageIdResolution( MessagingMessageConverter<Message> converter, boolean convertMessageIdToUuid)`.

tomazfernandes · 2026-03-14T20:05:47Z

spring-cloud-aws-sqs/src/main/java/io/awspring/cloud/sqs/operations/SqsTemplateOptions.java

 /**
 * Sqs specific options for the {@link SqsTemplate}.
 *
+ * @author Jeongmin Kim


Please add me as an author here as well, along with @since 3.0.0. I missed it when the class was originally created.

jm0514 requested review from MatejNedic, maciejwalkowiak and tomazfernandes as code owners August 9, 2025 09:15

github-actions bot added the component: sqs SQS integration related issue label Aug 9, 2025

injae-kim mentioned this pull request Aug 10, 2025

Add an option to receive MessageId as String rather than UUID #814

Open

maciejwalkowiak reviewed Aug 22, 2025

View reviewed changes

tomazfernandes added the status: waiting-for-feedback Waiting for feedback from issuer label Oct 4, 2025

github-actions bot added the type: documentation Documentation or Samples related issue label Feb 20, 2026

jm0514 added 6 commits February 21, 2026 13:43

Add an option to receive MessageId as String rather than UUID

73bb014

Add Jeongmin Kim to project contributors

1b24d21

Generate consistent UUID from Message ID instead of random UUID

787b42d

Add fail-fast for non-UUID message IDs and handle non-UUID send respo…

0eab76d

…nses

Add documentation for non-UUID message ID support

dce5a94

Rename AWSMessageId to RawMessageId for consistency

56cb5ec

jm0514 force-pushed the gh-814 branch from e9f43e3 to 56cb5ec Compare February 21, 2026 04:57

tomazfernandes requested changes Mar 8, 2026

View reviewed changes

jm0514 added 2 commits March 9, 2026 22:48

Extract SqsMessageIdResolver to consolidate message ID resolution logic

f1d7a50

Move convertMessageIdToUuid configuration to Options API

1d32b0c

tomazfernandes reviewed Mar 14, 2026

View reviewed changes

tomazfernandes removed the status: waiting-for-feedback Waiting for feedback from issuer label Mar 14, 2026

Uh oh!

Conversation

jm0514 commented Aug 9, 2025

Add configurable UUID conversion for non-AWS SQS-compatible services

📢 Type of change

📜 Description

Configuration:

💡 Motivation and Context

💚 How did you test it?

📝 Checklist

🔮 Next steps

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tomazfernandes commented Sep 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jm0514 commented Feb 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tomazfernandes left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jm0514 Mar 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tomazfernandes left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

tomazfernandes commented Sep 2, 2025 •

edited

Loading

jm0514 commented Feb 20, 2026 •

edited

Loading

jm0514 Mar 14, 2026 •

edited

Loading

tomazfernandes left a comment •

edited

Loading