GH-1143 Add IGNORE QueueNotFoundStrategy option for SQS

[BK202503]

Closes #1143.

What

Adds a third option to QueueNotFoundStrategy — IGNORE — that logs a warning and skips starting the listener container's message source when its queue does not exist, so application startup is not blocked. Subsequent polls for that source return empty.

This restores the default behavior of Spring Cloud AWS 2.x (spring-cloud-starter-aws-messaging) for users that rely on it during the 2.x → 3.x migration, as flagged by several commenters on #1143.

Why

Today the two strategies are:

• FAIL — throws on a missing queue and blocks application startup. Wrong for deployments where the queue is legitimately optional.
• CREATE — calls CreateQueue on a missing queue. Requires sqs:CreateQueue IAM and can interfere with externally-managed queue configuration / cross-team queue ownership.

Neither fits the case where a queue may legitimately be absent in some deployments (optional feature queues, multi-region rollout where the queue hasn't been created yet, etc.) and the listener should simply skip rather than crash the app.

@tomazfernandes wrote on the issue: "I don't have a solution in mind, but happy to take a look at a PR with a proposal." — this is that proposal.

How

The main concern from the issue was "graciously handle the error thrown by the QueueAttributesResolver and interrupting container startup". The patch routes that through a typed signal rather than reusing the generic resolver exception:

• QueueNotFoundStrategy gets a new IGNORE constant with Javadoc that cross-references the 2.x default behavior.
• QueueAttributesResolver.handleException, on QueueDoesNotExistException + IGNORE, logs a warning and fails the future with a new QueueNotFoundException (subtype of QueueAttributesResolvingException, so existing catch sites keep working; the dedicated subtype is what lets the source distinguish "ignore this queue" from a generic resolver failure). The CREATE path is unchanged.
• QueueAttributesResolver.wrapException passes QueueNotFoundException through unwrapped instead of re-wrapping in QueueAttributesResolvingException, so the source sees the typed signal.
• AbstractSqsMessageSource.doStart catches CompletionException with QueueNotFoundException as its cause, flips a skipped flag, logs a warning, and returns without setting queueAttributes / queueUrl or configuring the conversion context.
• AbstractSqsMessageSource.doPollForMessages short-circuits to an empty future when skipped, so the polling loop is a no-op for the lifetime of the source.

The @RetryableTopic-style or FAIL paths are untouched — only the new IGNORE constant exercises the new branches. The property binding for spring.cloud.aws.sqs.queue-not-found-strategy=IGNORE picks up automatically because SqsProperties already exposes the enum directly.

Test plan

• New QueueAttributesResolverIntegrationTests#shouldIgnoreQueueWhenStrategyIsIgnore mirrors the existing #shouldNotCreateQueue pattern against LocalStack, asserting that resolving a non-existent queue with IGNORE surfaces a QueueNotFoundException whose cause is QueueDoesNotExistException (rather than the generic QueueAttributesResolvingException that FAIL produces).
• Full QueueAttributesResolverIntegrationTests class (7 tests) passes locally on LocalStack — the existing FAIL / CREATE paths still produce their original exception types because wrapException only passes through QueueNotFoundException specifically.
• ./mvnw -B spotless:apply clean.

Docs

• docs/src/main/asciidoc/sqs.adoc — the table entry for queueNotFoundStrategy gets a sentence on the IGNORE behavior next to the existing FAIL note.

AI agent disclosure

I used an AI coding agent (Claude Code) to navigate the existing strategy / resolver / source code paths and draft this patch. I have read every line, verified the dispatch through the CompletionException unwrap in doStart, traced the property-binding to confirm no SqsProperties change is needed, and confirmed the new IGNORE test passes against LocalStack alongside the existing 6 resolver tests. I will be the one responding to review.

[maciejwalkowiak]

Looks good to me but @tomazfernandes please take a look

[tomazfernandes]

Thanks @maciejwalkowiak. Let's not block release on this - I'll review it for 4.2.0, since 4.1.0 is already overdue and packed with SQS changes.

[BK202503]

@tomazfernandes when do you expect to merge this one?

[tomazfernandes]

@BK202503 4.1.0 should be out this week, I'll review and merge this PR after that for 4.2.0.

We're working on releasing more often, so 4.2.0 should follow in a timely manner.

Thanks for the PR.

[tomazfernandes]

Thanks for the PR @BK202503.

The main issue I see is that as is the initialization fails nevertheless, since other components such as the acknowledgement processor are not initialized, which causes the code to throw IllegalArgumentException: acknowledgementExecutor not set.

One other issue is that, even if the source successfully initializes, the polling method would keep being called and the thread would keep spinning.

Perhaps we could instead handle this scenario at the AbstractPollingMessageSource level, and prevent the source from starting at all (isRunning = false).

Let me know your thoughts.

[BK202503]

@tomazfernandes Thank you for your comment and moving the guard to AbstractPollingMessageSource#start(): catch QueueNotFoundException from doStart(), set running=false, and skip the ack processor + polling thread setup. Source-level skipped flag drops.

[tomazfernandes]

Thanks for the update @BK202503, the behavior looks good now.

I've left a suggestion for a path for us to simplify the design further, let me know your thoughts.

[tomazfernandes]

We could simplify the design further by inspecting the QueueAttributesResolvingException directly here (wrapped in a CompletionException), and adding a isQueueIgnored() method to it that we'd set in the resolver.

This way we don't need to introduce a new exception type, the catch in the AbstractSqsMessageSource, and we also don't change semantics for the SqsTemplate between IGNORE and FAIL.

What do you think?

[BK202503]

Agreed. Folding the signal into QueueAttributesResolvingException via isQueueIgnored() (set by the resolver on the IGNORE branch) drops the new exception type and keeps SqsTemplate semantics identical between IGNORE and FAIL. Pushed as 7e8a3c5.

[tomazfernandes]

Thanks for the quick turnaround @BK202503.

Left one remaining design comment in the diff.

A few last points:

• Please update the docs and the IGNORE javadocs to reflect the new behavior.
• Also, please add @since 4.2 on the new QueueAttributesResolvingException constructor and isQueueIgnored().

And it would be great if we could add integration tests for these scenarios:

1. Container with IGNORE and a missing queue starts successfully, never polls, and stops normally
2. Container with IGNORE and a missing queue starts polling normally after the queue is created and the container is restarted
3. Container with multiple queues where one is missing consumes normally from the existing queue while the missing one is skipped
4. FAIL with a missing queue still throws on startup, with isQueueIgnored() returning false

[tomazfernandes]

Let's move the IGNORE logic to wrapException instead, this way we only create the QueueAttributesResolvingException in one place and avoid having the pass through there.

I also think we don't need to log here since we'll be logging in the source. The exception will carry the information in this layer.