BareWire.Transport.AWS.SQS 2.0.4

BareWire.Transport.AWS.SQS

Amazon SQS transport adapter for BareWire. Implements ITransportAdapter with long-polling consumer, batched send (up to 10 messages per SQS batch), credit-based flow control (ADR-004), and native DLQ via RedrivePolicy.

Configuration

// DefaultChain (recommended for production — IAM roles, environment variables)
services.AddBareWireSqs(sqs =>
{
    sqs.Region("eu-central-1");
});

// Explicit credentials (local development only)
services.AddBareWireSqs(sqs =>
{
    sqs.UseExplicitCredentials("AKIAIOSFODNN7EXAMPLE", "<secret>");
    sqs.Region("us-east-1");
});

// IAM instance profile (EC2 instance profile / ECS task role) — R4.3
services.AddBareWireSqs(sqs =>
{
    sqs.UseInstanceProfileCredentials();           // default role attached to the profile
    // sqs.UseInstanceProfileCredentials("MyAppRole"); // or an explicit role name
    sqs.Region("eu-central-1");
});

// LocalStack (http allowed via opt-in)
services.AddBareWireSqs(sqs =>
{
    sqs.ServiceUrl("http://localhost:4566");
    sqs.AllowInsecureEndpoint(); // SEC-01 opt-out for test environments
    sqs.Region("us-east-1");
});

Available options

Capabilities

TransportCapabilities.NativeDeduplication | DlqNative | BatchReceive

• NativeDeduplication — FIFO queues support MessageGroupId-based ordering and content-based deduplication. Full BareWire-level MessageGroupId/MessageDeduplicationId mapping implemented in R4.2 — see FIFO (R4.2) section.
• DlqNative — Exhausted messages are routed to a DLQ automatically via RedrivePolicy. Configure bw.sqs.max-receive-count on your QueueDeclaration.
• BatchReceive — ReceiveMessage retrieves up to 10 messages per call.

Settlement semantics (ADR-014)

Why Reject does not call DeleteMessage: SQS has no native dead-letter API. Deleting the message would silently discard it without triggering the DLQ. See ADR-014 for the full rationale.

Topology arguments

Topology is declared via QueueDeclaration.Arguments:

var topology = new TopologyDeclaration
{
    Queues =
    [
        new QueueDeclaration("my-queue", Arguments: new Dictionary<string, object>
        {
            ["bw.sqs.visibility-timeout"] = TimeSpan.FromSeconds(60),
            ["bw.sqs.wait-time-seconds"] = 20,
            ["bw.sqs.max-receive-count"] = 5,
        }),
    ],
};

FIFO (R4.2)

BareWire fully supports SQS FIFO queues. FIFO fields (MessageGroupId, MessageDeduplicationId) are set only when the target queue name ends with .fifo — standard queues are unaffected (backward-compatible).

MessageGroupId mapping

Security note (ADR-015): MessageGroupId is an ordering boundary, NOT an authorization or tenant-isolation boundary. A sender can supply any group id they choose. Do not use BW-MessageGroupId for access-control decisions. See ADR-015 for the full rationale.

MessageDeduplicationId

Content-based deduplication

Enable content-based dedup (requires the queue to have ContentBasedDeduplication=true):

// Configurator (produce side):
services.AddBareWireSqs(sqs =>
{
    sqs.Region("eu-central-1");
    sqs.ContentBasedDeduplication(); // do not generate explicit MessageDeduplicationId
});

// Topology (queue creation):
new QueueDeclaration("my-orders.fifo", Arguments: new Dictionary<string, object>
{
    ["bw.sqs.fifo"] = true,
    ["bw.sqs.content-based-deduplication"] = true, // sets ContentBasedDeduplication=true on queue
});

Inbound stamping (BW-MessageGroupId / BW-SequenceNumber)

For consumed FIFO messages the following BareWire headers are stamped from SQS system attributes (broker-set, not sender-controlled):

Stamping happens after MapInbound (which copies sender-supplied MessageAttributes). This means a sender cannot spoof BW-MessageGroupId via a MessageAttribute — the trusted broker value always wins (SEC-3 anti-squatting, consistent with ADR-011 pattern for ASB sessions).

Consumer ordering note

SQS FIFO guarantees ordering within a MessageGroupId at the broker level. BareWire R4.2 does not add a per-group sequential consumer channel (unlike ASB per-session consumers). The long-polling consumer receives messages from a single group sequentially as long as they remain un-settled. Full per-group consumer sequencing is deferred to R4.4.

Known limitations by phase

R4.3 (IAM / Encryption — implemented)

• IAM instance-profile authentication via UseInstanceProfileCredentials(role?) — Amazon.Runtime.InstanceProfileAWSCredentials, lazy IMDS credential refresh (EC2 instance profile / ECS task role). See ADR-016.
• SSE-SQS / SSE-KMS encryption at rest via topology arguments bw.sqs.sse-managed / bw.sqs.kms-master-key-id / bw.sqs.kms-data-key-reuse-period (see Encryption at rest (R4.3)). At-rest encryption is opt-in (off by default) — a queue declared without an SSE argument is not encrypted by BareWire.
• Note: full credential rotation strategy is handled by the AWS SDK refresh cycle for InstanceProfile; static Explicit credentials are not auto-rotated.

R4.4 (Integration tests — not yet implemented)

• LocalStack integration tests in CI (Aspire orchestration).
• Real-queue round-trip, DLQ routing, visibility timeout renewal.

Encryption at rest (R4.3)

At-rest encryption is configured per queue via topology arguments (it is a queue attribute, not a client setting). It is opt-in — a queue without an SSE argument is not encrypted by BareWire. SSE-SQS and SSE-KMS are mutually exclusive: setting both bw.sqs.sse-managed=true and bw.sqs.kms-master-key-id throws BareWireConfigurationException at deploy (fail-fast, order-independent).

// SSE-SQS (SQS-managed key)
new QueueDeclaration("orders", Arguments: new Dictionary<string, object>
{
    ["bw.sqs.sse-managed"] = true,
});

// SSE-KMS (customer CMK)
new QueueDeclaration("payments", Arguments: new Dictionary<string, object>
{
    ["bw.sqs.kms-master-key-id"] = "alias/my-cmk",      // key id or ARN
    ["bw.sqs.kms-data-key-reuse-period"] = 300,          // optional, 60–86400
});

See ADR-016 for the full rationale (per-queue config, mutual exclusion, off-by-default posture).

Security notes

• Production: prefer UseDefaultCredentials() or UseInstanceProfileCredentials() with IAM roles over UseExplicitCredentials().
• IAM (R4.3): UseInstanceProfileCredentials(role?) fetches credentials lazily from IMDS (EC2 instance profile / ECS task role). The IAM role name is an identifier (not a secret) and may appear in ToString() / logs, like AccessKeyId.
• TLS: all requests use HTTPS by default. AllowInsecureEndpoint() is for test environments only (SEC-01).
• Secrets: SecretAccessKey is never logged and never appears in ToString() output (SEC-02).
• Encryption at rest (R4.3): opt-in per queue via bw.sqs.sse-managed (SSE-SQS) or bw.sqs.kms-master-key-id (SSE-KMS). See Encryption at rest (R4.3) and ADR-016.