# shared-SQS — AWS SQS Compatible Message Queue

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

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

## Быстрый старт — деплой

### 1. Заполнить параметры

Отредактировать `deploy/values.yaml`:
- Redis хост и пароль
- Ingress домен (для доступа извне)
- PostgreSQL credentials (опционально, для биллинга)

### 2. Деплоить

```bash
kubectl create namespace shared-sqs
helm install shared-sqs ./deploy -n shared-sqs
```

### 3. Проверить что работает

```bash
# Дождаться pod ready (1/1)
kubectl -n shared-sqs get pod -w

# Запустить тесты
cd tests-deploy
bash run.sh
```

**Результат:** PASS=7 FAIL=0 ✅

Полная инструкция с примерами параметров → [tests-deploy/README.md](tests-deploy/README.md)

---

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

| | |
|---|---|
| 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
```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

## Биллинг

Каждая успешная SQS-операция автоматически записывается в базу данных для учёта использования.

| Поле | Описание |
|------|----------|
| `tenant_id` | Идентификатор тенанта |
| `operation` | SQS-операция (SendMessage, ReceiveMessage и т.д.) |
| `queue_name` | Имя очереди |
| `msg_count` | Количество сообщений в запросе |
| `msg_bytes` | Объём тел сообщений в байтах |
| `recorded_at` | Время записи |

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

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

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

## Self-hosted — развернуть у себя

Если хотите запустить shared-SQS в собственном Kubernetes-кластере — см. [deploy/README.md](deploy/README.md).

> **Деплой через AI-агента** — в репозитории есть [AGENTS.md](AGENTS.md): машиночитаемая пошаговая инструкция.
> Если AI-агент встроен в вашу среду разработки (Copilot, Cursor, Claude Dev и др.) — он найдёт файл сам и проведёт весь деплой.
> Если нет — просто скопируйте содержимое [AGENTS.md](AGENTS.md) в любой веб-чат (ChatGPT, Claude и др.) и AI пошагово поможет вам задеплоить.