# Channel Mapping (/connectors/aws/reference/channel-mapping)
This is the master reference for how the embedded KubeMQ AWS connector maps SQS queues and SNS
topics onto KubeMQ. An SQS queue is backed by exactly one KubeMQ **Queue** channel; an SNS topic
is **virtual** — a registry entry whose publish fans out to subscribed queues and webhooks.
## SQS queue grammar [#sqs-queue-grammar]
Every SQS queue maps to exactly one KubeMQ Queue channel:
```text
sqs.{name}
└┬─┘ └──┬──┘
│ └─ the SQS queue name (the same name you pass to CreateQueue)
└─ fixed connector prefix
```
| SQS queue | KubeMQ channel |
| ---------- | -------------- |
| `orders` | `sqs.orders` |
| `events` | `sqs.events` |
| `work-dlq` | `sqs.work-dlq` |
## FIFO group grammar [#fifo-group-grammar]
A FIFO queue `{name}.fifo` fans each **message group** onto its own per-group channel:
```text
sqs.{name}.fifo.g.{enc(group)}
└─────┬────────┘ └┬┘ └───┬────┘
│ │ └─ the MessageGroupId, percent-encoded
│ └─ fixed ".g." group separator
└─ the FIFO queue channel (the name includes the ".fifo" suffix)
```
`enc` percent-encodes any byte outside `[a-zA-Z0-9_-]`.
| FIFO queue | MessageGroupId | KubeMQ channel |
| ------------ | -------------- | ----------------------------- |
| `tasks.fifo` | `g1` | `sqs.tasks.fifo.g.g1` |
| `tasks.fifo` | `order/42` | `sqs.tasks.fifo.g.order%2F42` |
## SNS topics are virtual [#sns-topics-are-virtual]
SNS topics have **no native channel**. A topic is a registry entry, **synced/replicated across
cluster nodes**; its authorization pseudo-resource is `sns.{topic}`. Fan-out resolves to the
target SQS channels (one batched send) plus HTTP/HTTPS webhooks at publish time. See
[Fan-out](/connectors/aws/how-to/fan-out).
## ARNs & queue URLs [#arns--queue-urls]
| Form | Value |
| --------- | ---------------------------------------------------------------------------------------------------- |
| SQS ARN | `arn:aws:sqs:{Region}:{AccountId}:{name}` |
| SNS ARN | `arn:aws:sns:{Region}:{AccountId}:{name}` |
| Queue URL | `{scheme}://{host}/{AccountId}/{name}` (path-style; host from `AdvertisedUrl` or the request `Host`) |
`Region` defaults to `kubemq` (not enforced); `AccountId` defaults to `000000000000`. Resolution
parses the **path only**, so a stale host in a saved URL still works.
## The registry is authoritative [#the-registry-is-authoritative]
Only resources created through the AWS API are visible. Operating on a native `sqs.foo` channel
that was never `CreateQueue`d returns `NonExistentQueue`.
## Cross-protocol interoperability [#cross-protocol-interoperability]
Because the backing store is a normal KubeMQ Queue channel, an SQS `SendMessage` to `sqs.orders`
is consumable by a gRPC/REST queue client on the same channel, and vice-versa.
**Native-interop caveat (gotcha #7).** A message produced by a **native** KubeMQ client on
`sqs.*` lacks the `sqs_*` tags, so its `MessageId` falls back to the broker MessageID, it has no
`SenderId`, and no policy stamping is applied. See
[Cross-protocol interop](/connectors/aws/concepts/cross-protocol-interop).
## Message attribute ⇄ tag mapping [#message-attribute--tag-mapping]
SQS message attributes round-trip losslessly through the KubeMQ **Tags** codec.
| AWS field | KubeMQ Tag | Notes |
| --------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Message attribute `{Name}` | `sqs_attr_{Name}` | value is `{DataType}\|{value}`; Binary is base64; ≤ 10 attributes, name ≤ 256 chars, no `AWS.`/`Amazon.` prefix; DataType `String` / `Number` / `Binary` (+ subtypes `String.x`) |
| System attribute `AWSTraceHeader` | `sqs_trace_header` | the **only** accepted system attribute; anything else → `InvalidParameterValue` |
| *(connector-stamped)* `MessageId` | `sqs_message_id` | generated UUID |
| *(connector-stamped)* `SenderId` | `sqs_sender_id` | the authenticated ClientID |
| FIFO `MessageGroupId` | `sqs_group_id` | |
| FIFO `MessageDeduplicationId` | `sqs_dedup_id` | |
### Receive-side decoded system attributes [#receive-side-decoded-system-attributes]
`SentTimestamp`, `ApproximateReceiveCount`, `ApproximateFirstReceiveTimestamp` (node-local
approx), `SenderId`, `DeadLetterQueueSourceArn` (redriven messages), and FIFO `MessageGroupId` /
`SequenceNumber` / `MessageDeduplicationId`. Attribute-name filtering on receive supports `All`,
exact names, and `prefix.*`.
## SNS raw / enveloped tags [#sns-raw--enveloped-tags]
| Context | Mapping |
| -------------------------- | -------------------------------------------------------------------------------------------------------- |
| SQS **enveloped** delivery | the SNS `Notification` JSON carries `MessageAttributes` as `{Type, Value}` per attribute (Binary base64) |
| SQS **raw** delivery | bare body + the attribute tag codec + `sns_topic_arn` / `sns_subject` tags |
| HTTP **raw** delivery | bare payload with attributes mapped to `x-amz-sns-attr-{name}` headers |
**Raw-HTTP attribute-drop deviation.** AWS drops message attributes for raw HTTP delivery; this
connector instead surfaces them as `x-amz-sns-attr-{name}` headers.
## MD5 [#md5]
| Field | Algorithm |
| ------------------------------ | ----------------------------------------- |
| `MD5OfMessageBody` | MD5 of the body bytes |
| `MD5OfMessageAttributes` | AWS length-prefixed message-attribute MD5 |
| `MD5OfMessageSystemAttributes` | present only when `AWSTraceHeader` is set |
## FIFO SequenceNumber deviation [#fifo-sequencenumber-deviation]
The 20-digit zero-padded `SequenceNumber` is the broker **send-timestamp (UnixNano)** on SEND and
the **true broker sequence** on RECEIVE. It is still strictly increasing per group for serialized
sends. See [Reliability](/connectors/aws/how-to/reliability).
## Related [#related]