Integration SQS Extension

Integration: Amazon SQS Extension

Track Amazon SQS operations in your test diagrams using the TestTrackingDiagrams.Extensions.SQS NuGet package. This extension intercepts SQS HTTP traffic via the AWS SDK's HttpClientFactory pipeline and logs operations for diagram generation.

Installation

dotnet add package TestTrackingDiagrams.Extensions.SQS

Quick Start

using Amazon.SQS;
using TestTrackingDiagrams.Extensions.SQS;

var config = new AmazonSQSConfig
{
    RegionEndpoint = Amazon.RegionEndpoint.EUWest1
}
.WithTestTracking(new SqsTrackingMessageHandlerOptions
{
    ServiceName = "SQS",
    CallingServiceName = "OrdersApi",
    Verbosity = SqsTrackingVerbosity.Detailed,
    CurrentTestInfoFetcher = () => (TestContext.CurrentTestName, TestContext.CurrentTestId)
});

var client = new AmazonSQSClient(config);

How It Works

The extension uses the same DelegatingHandler pattern as the S3 and DynamoDB extensions. WithTestTracking() injects a SqsTrackingMessageHandler via AmazonSQSConfig.HttpClientFactory, intercepting all HTTP requests made by the SQS SDK.

The handler:

1. Reads and classifies each request using SqsOperationClassifier
2. Reconstructs the request body so downstream processing is unaffected
3. Logs request/response pairs via RequestResponseLogger

Protocol Support

SQS supports two protocols:

Protocol	Detection	Example
JSON (modern)	X-Amz-Target: AmazonSQS.{Operation} header	AmazonSQS.SendMessage
Query (legacy)	Action={Operation} parameter in query string or form body	Action=ReceiveMessage

Both protocols are fully supported by the classifier.

Supported Operations

Operation	Enum Value
SendMessage	SqsOperation.SendMessage
SendMessageBatch	SqsOperation.SendMessageBatch
ReceiveMessage	SqsOperation.ReceiveMessage
DeleteMessage	SqsOperation.DeleteMessage
DeleteMessageBatch	SqsOperation.DeleteMessageBatch
ChangeMessageVisibility	SqsOperation.ChangeMessageVisibility
ChangeMessageVisibilityBatch	SqsOperation.ChangeMessageVisibilityBatch
CreateQueue	SqsOperation.CreateQueue
DeleteQueue	SqsOperation.DeleteQueue
GetQueueUrl	SqsOperation.GetQueueUrl
GetQueueAttributes	SqsOperation.GetQueueAttributes
SetQueueAttributes	SqsOperation.SetQueueAttributes
PurgeQueue	SqsOperation.PurgeQueue
ListQueues	SqsOperation.ListQueues

Unrecognised operations are classified as SqsOperation.Other.

Queue Name Extraction

The classifier extracts queue names from (in priority order):

1. URL path: /account-id/queue-name (e.g. https://sqs.us-east-1.amazonaws.com/123456789012/my-queue)
2. Body QueueUrl field: JSON body containing "QueueUrl": "https://.../{accountId}/{queueName}"
3. Body QueueName field: JSON body containing "QueueName": "my-queue" (used by CreateQueue)

FIFO queue names (e.g. orders.fifo) are preserved with the .fifo suffix.

Verbosity Levels

SqsTrackingVerbosity.Summarised

Minimal output for clean diagrams:

• Method label: Operation name (e.g. SendMessage)
• URI: sqs:///orders-queue
• Content: Omitted (both request and response)
• Headers: Omitted
• Other operations: Skipped entirely

SqsTrackingVerbosity.Detailed

Balanced output for debugging:

• Method label: Operation name (e.g. SendMessage)
• URI: sqs:///orders-queue
• Content: Included (request body and response body)
• Headers: Included (with default exclusions)

SqsTrackingVerbosity.Raw

Full HTTP-level output:

• Method: POST (actual HTTP method)
• URI: Original AWS endpoint URL
• Content: Full request/response bodies
• Headers: All headers (with default exclusions)
• Other operations: Included

Configuration Options

new SqsTrackingMessageHandlerOptions
{
    // Display name for this SQS instance in diagrams
    ServiceName = "SQS",

    // Name of the calling service in diagrams
    CallingServiceName = "OrdersApi",

    // Verbosity level (default: Detailed)
    Verbosity = SqsTrackingVerbosity.Detailed,

    // Required: provides test context for log correlation
    CurrentTestInfoFetcher = () => (testName, testId),

    // Headers excluded from logging (defaults below)
    ExcludedHeaders = new HashSet<string>
    {
        "Authorization", "x-amz-date", "x-amz-security-token",
        "x-amz-content-sha256", "User-Agent", "amz-sdk-invocation-id",
        "amz-sdk-request"
    }
}

ITrackingComponent

SqsTrackingMessageHandler implements ITrackingComponent and auto-registers with TrackingComponentRegistry on construction. This provides:

• ComponentName: "SqsTrackingMessageHandler ({ServiceName})"
• WasInvoked: true after first request
• InvocationCount: Total requests processed

URI Scheme

Classified requests use the sqs:/// URI scheme with the queue name in the path:

sqs:///orders-queue
sqs:///orders.fifo
sqs:///           (when queue name unavailable, e.g. ListQueues)

The path-based format (three slashes) preserves queue name casing, unlike host-based URIs which lowercase per RFC 3986.

See Also

• Integration: Amazon S3 Extension
• Integration: Amazon DynamoDB Extension
• Integration: Azure Service Bus Extension