[Feature] Add Sequential Message Processing to Mocked SQS Implementation #535

Description

The current mocked SQS implementation processes messages immediately and potentially in parallel when send() is called multiple times. This doesn't allow testing scenarios where strict sequential processing is required (emulating FIFO-like behavior without implementing full FIFO semantics).

Current Behavior

• Messages are processed immediately upon send()/sendBatch() calls
• No serialization between multiple send operations
• Batch messages process sequentially within the batch, but batches can run in parallel
• This allows parallel processing which may not match certain production scenarios

Proposed Solution

Implement a simple locking mechanism to ensure only one message processes at a time per queue:

Approach: Simple Locking

• Add per-queue message queues to store incoming messages
• Implement simple mutex/lock using promises
• Process messages sequentially with await
• Maintain backward compatibility with existing API

Implementation Plan

1. New Data Structures

const messageQueues = new Map<string, SendMessageRequest[]>();
const processingLocks = new Map<string, Promise<void>>();

2. Sequential Processing Function

private async processSequentially(queueUrl: string): Promise<void>

3. Modified Handlers

• SendMessageCommand: Queue message instead of immediate processing
• SendMessageBatchCommand: Queue all messages in batch
• Trigger sequential processing if no active lock exists

4. Optional Configuration

export function createSQSClient({
  queueUrl,
  sqsClient,
  onMessageSend,
  enableSequential = false  // New option
}: {
  queueUrl: string;
  sqsClient?: SQSClient;
  onMessageSend?: MessageCallback;
  enableSequential?: boolean;
}): SQSClient

Benefits

• Maintains existing API surface (no breaking changes)
• Simple implementation using existing patterns
• Preserves testability
• Enables testing of sequential processing scenarios
• Optional feature (backward compatible)

Files to Modify

• workspaces/templates-lib/packages/template-sqs/src/mockedSQS.ts

Testing Strategy

• Add tests for sequential processing behavior
• Verify multiple send() calls process in order
• Ensure batch messages process sequentially within and across batches
• Validate existing functionality remains unchanged

Acceptance Criteria

1. ✅ Messages are processed one at a time when sequential mode is enabled
2. ✅ Processing order matches send order (first-in, first-out)
3. ✅ Existing tests continue to pass without modification
4. ✅ Sequential mode is opt-in via configuration parameter
5. ✅ Error handling prevents blocking queue on processing failures
6. ✅ Performance impact is minimal for non-sequential usage

Additional Context

This enhancement will support testing scenarios where:

• Message ordering guarantees are critical
• Race conditions need to be eliminated
• Sequential business logic validation is required
• Production FIFO queue behavior needs to be approximated in tests

The approach avoids full FIFO implementation complexity while providing the core benefit of sequential processing that matches many real-world use cases.