shared-SQS/README.md

# shared-SQS — AWS SQS Compatible Message Queue

Совместимый с Amazon SQS сервис очередей сообщений с поддержкой изолированных тенантов.

Сервис предназначен для работы через стандартные AWS SDK и AWS CLI: в обычном клиентском коде меняется только endpoint.

## Демо-стенд

| | |
|---|---|
| Web UI | https://qu.kube5s.ru/ui/ |
| SQS Endpoint | https://qu.kube5s.ru |
| Region | us-east-1 |
| Demo UI Token | demo-ui-shared-sqs-ngcloud-2026 |
| Demo Access Key | SSAK-demo-shared-sqs |
| Demo Secret Key | demo-secret-key-shared-sqs-ngcloud-2026 |

Demo token и demo credentials предназначены для ознакомительного доступа.
Для собственных write-сценариев используйте tenant credentials своего окружения.

Важно для demo stand:
- demo tenant общий, поэтому очереди и сообщения в нём могут меняться во время просмотра;
- `QueueUrl` может выглядеть как внутренний адрес сервиса, это нормально для данного стенда: передавайте его обратно как есть и продолжайте использовать `--endpoint-url https://qu.kube5s.ru`.

## Что поддерживается

shared-SQS покрывает 17 SQS-операций:

- CreateQueue
- DeleteQueue
- GetQueueAttributes
- GetQueueUrl
- ListQueues
- PurgeQueue
- SetQueueAttributes
- TagQueue
- UntagQueue
- ListQueueTags
- SendMessage
- SendMessageBatch
- ReceiveMessage
- DeleteMessage
- DeleteMessageBatch
- ChangeMessageVisibility
- ChangeMessageVisibilityBatch

## Где взять токен и ключи

Есть два сценария.

### 1. Просто посмотреть сервис

Для быстрого демо доступны оба публичных входа:

- Web UI: используйте `demo-ui-shared-sqs-ngcloud-2026`
- AWS CLI / SDK: используйте demo `Access Key / Secret Key`

Для ознакомительного доступа можно использовать demo credentials:

```bash
export AWS_ACCESS_KEY_ID="SSAK-demo-shared-sqs"
export AWS_SECRET_ACCESS_KEY="demo-secret-key-shared-sqs-ngcloud-2026"
export AWS_DEFAULT_REGION="us-east-1"
ENDPOINT="--endpoint-url https://qu.kube5s.ru"
```

Для входа в Web UI:

1. Откройте `https://qu.kube5s.ru/ui/`
2. Вставьте `demo-ui-shared-sqs-ngcloud-2026`
3. После входа вы попадёте в demo tenant и увидите его очереди и сообщения

### 2. Получить свои credentials через Web UI

Если нужен полноценный доступ к своим очередям и сообщениям, используйте Web UI:

1. Откройте `https://qu.kube5s.ru/ui/`
2. В поле входа вставьте свой `API Token (nubes JWT)`
3. Этот токен пользователь получает в панели управления облаком Nubes
4. После успешного входа shared-SQS автоматически создаёт tenant и показывает `Access Key` и `Secret Key`
5. Эти `Access Key / Secret Key` дальше используются в AWS CLI, boto3, AWS SDK for JavaScript и других клиентах

Важно:
- `Secret Key` показывается только один раз, его нужно сохранить
- для AWS CLI и SDK нужен не UI token, а именно выданные сервисом `Access Key / Secret Key`

Примеры ниже можно запускать либо с demo credentials, либо со своими tenant credentials.

## Быстрый старт через AWS CLI

```bash
export AWS_ACCESS_KEY_ID="YOUR_ACCESS_KEY"
export AWS_SECRET_ACCESS_KEY="YOUR_SECRET_KEY"
export AWS_DEFAULT_REGION="us-east-1"
ENDPOINT="--endpoint-url https://qu.kube5s.ru"
```

### Создать очередь

```bash
aws sqs create-queue --queue-name demo-queue $ENDPOINT
```

### Получить URL очереди

```bash
aws sqs get-queue-url --queue-name demo-queue $ENDPOINT
```

Примечание:
возвращённый `QueueUrl` на этом стенде может содержать внутренний hostname сервиса. Его не нужно редактировать вручную: используйте возвращённое значение как есть вместе с тем же `$ENDPOINT`.

### Отправить сообщение

```bash
QUEUE_URL=$(aws sqs get-queue-url --queue-name demo-queue $ENDPOINT --query QueueUrl --output text)
aws sqs send-message --queue-url "$QUEUE_URL" --message-body "Hello from shared-SQS" $ENDPOINT
```

### Получить сообщение

```bash
aws sqs receive-message --queue-url "$QUEUE_URL" --wait-time-seconds 5 $ENDPOINT
```

### Удалить очередь

```bash
aws sqs delete-queue --queue-url "$QUEUE_URL" $ENDPOINT
```

## Python (boto3)

```python
import boto3

sqs = boto3.client(
    "sqs",
    endpoint_url="https://qu.kube5s.ru",
    region_name="us-east-1",
    aws_access_key_id="YOUR_ACCESS_KEY",
    aws_secret_access_key="YOUR_SECRET_KEY",
)

queue = sqs.create_queue(QueueName="demo-queue")
queue_url = queue["QueueUrl"]

sqs.send_message(QueueUrl=queue_url, MessageBody="Hello from Python")
messages = sqs.receive_message(QueueUrl=queue_url, WaitTimeSeconds=5)
print(messages)
```

## Node.js (@aws-sdk/client-sqs)

```javascript
const {
  SQSClient,
  CreateQueueCommand,
  SendMessageCommand,
  ReceiveMessageCommand,
} = require("@aws-sdk/client-sqs");

const sqs = new SQSClient({
  endpoint: "https://qu.kube5s.ru",
  region: "us-east-1",
  credentials: {
    accessKeyId: "YOUR_ACCESS_KEY",
    secretAccessKey: "YOUR_SECRET_KEY",
  },
});

const queue = await sqs.send(new CreateQueueCommand({ QueueName: "demo-queue" }));
await sqs.send(new SendMessageCommand({ QueueUrl: queue.QueueUrl, MessageBody: "Hello" }));
const result = await sqs.send(new ReceiveMessageCommand({ QueueUrl: queue.QueueUrl, WaitTimeSeconds: 5 }));
console.log(result.Messages);
```

## Тесты

### quick_test.sh

Короткий smoke test основных операций:

```bash
AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=... bash quick_test.sh
```

Проверяет базовый lifecycle очереди и сообщения:
- CreateQueue
- ListQueues
- GetQueueUrl
- SendMessage
- ReceiveMessage
- DeleteMessage
- DeleteQueue

### hardcore_test.sh

Расширенный compatibility test:

```bash
AWS_ACCESS_KEY_ID=... AWS_SECRET_ACCESS_KEY=... bash hardcore_test.sh
```

Покрывает все 17 SQS-операций, включая:
- queue attributes
- tags
- batch операции
- visibility timeout
- purge
- queue lifecycle

## Сравнительные тесты

Краткий пользовательский summary лежит в файле `BENCHMARK-COMPARISON.md`.

Ключевой вывод: shared-SQS показывает конкурентоспособные результаты относительно Yandex MQ и покрывает полный набор заявленных пользовательских сценариев.