shared-SQS/README.md

# NGCloud Shared SQS — Multi-Tenant Message Queue Service

Совместимый с Amazon SQS мультитенантный сервис очередей сообщений.  
Один кластер — много тенантов, каждый с изолированными очередями и credentials.

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

| | |
|---|---|
| **Web UI** | https://qu.kube5s.ru/ui/ |
| **SQS Endpoint** | `https://qu.kube5s.ru` |
| **Region** | `us-east-1` (любая) |

Демо-стенд запущен с преднастроенным тенантом и несколькими очередями.  
Чтобы работать с SQS API (AWS CLI, boto3, SDK) — создайте своего тенанта через Web UI и используйте выданные credentials.

---

## Быстрый старт

### Создать тенанта

1. Откройте [Web UI](https://qu.kube5s.ru/ui/)
2. Нажмите **"Создать тенанта"**, введите имя
3. Скопируйте выданные **Access Key** и **Secret Key**

### Настройка AWS CLI

```bash
export AWS_ACCESS_KEY_ID="<ваш Access Key>"
export AWS_SECRET_ACCESS_KEY="<ваш Secret Key>"
export AWS_DEFAULT_REGION="us-east-1"
ENDPOINT="--endpoint-url https://qu.kube5s.ru"
```

---

## AWS CLI

Самый простой способ работы — через стандартный AWS CLI.

### Установка

Linux / macOS (pip):

```bash
pip install awscli
```

Linux (пакет):

```bash
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o awscliv2.zip
unzip awscliv2.zip && sudo ./aws/install
```

macOS (brew):

```bash
brew install awscli
```

Windows: скачайте установщик с [https://aws.amazon.com/cli/](https://aws.amazon.com/cli/)

Проверка: `aws --version`

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

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

### Список очередей

```bash
aws sqs list-queues $ENDPOINT
```

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

```bash
aws sqs send-message \
  --queue-url "$(aws sqs get-queue-url --queue-name myqueue $ENDPOINT --query QueueUrl --output text)" \
  --message-body "Hello from CLI!" \
  $ENDPOINT
```

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

```bash
aws sqs receive-message \
  --queue-url "$(aws sqs get-queue-url --queue-name myqueue $ENDPOINT --query QueueUrl --output text)" \
  $ENDPOINT
```

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

```bash
aws sqs delete-queue \
  --queue-url "$(aws sqs get-queue-url --queue-name myqueue $ENDPOINT --query QueueUrl --output text)" \
  $ENDPOINT
```

> **Совет:** `--endpoint-url` — единственное отличие от работы с Amazon SQS.  
> Весь остальной код без изменений.

---

## curl

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

```bash
curl -s -u "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
  "https://qu.kube5s.ru/?Action=CreateQueue&QueueName=myqueue&Version=2012-11-05"
```

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

```bash
curl -s -u "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
  "https://qu.kube5s.ru/?Action=SendMessage&QueueUrl=https://qu.kube5s.ru/queue/myqueue&MessageBody=HelloWorld&Version=2012-11-05"
```

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

```bash
curl -s -u "$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY" \
  "https://qu.kube5s.ru/?Action=ReceiveMessage&QueueUrl=https://qu.kube5s.ru/queue/myqueue&Version=2012-11-05"
```

---

## Python (boto3)

```python
import boto3

sqs = boto3.client(
    "sqs",
    endpoint_url="https://qu.kube5s.ru",
    region_name="us-east-1",
    aws_access_key_id="<ваш Access Key>",
    aws_secret_access_key="<ваш Secret Key>",
)

# Создать очередь
queue = sqs.create_queue(QueueName="myqueue")
print(queue["QueueUrl"])

# Отправить сообщение
sqs.send_message(QueueUrl=queue["QueueUrl"], MessageBody="Hello from Python!")

# Получить сообщение
msgs = sqs.receive_message(QueueUrl=queue["QueueUrl"])
print(msgs["Messages"][0]["Body"])
```

---

## 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: "<ваш Access Key>",
    secretAccessKey: "<ваш Secret Key>",
  },
});

const queue = await sqs.send(new CreateQueueCommand({ QueueName: "myqueue" }));
await sqs.send(new SendMessageCommand({ QueueUrl: queue.QueueUrl, MessageBody: "Hello!" }));
const res = await sqs.send(new ReceiveMessageCommand({ QueueUrl: queue.QueueUrl }));
console.log(res.Messages[0].Body);
```

---

## Тесты

В репозитории два тестовых скрипта.

### quick_test.sh — быстрая проверка

Требования: `aws cli`, `bash`

```bash
bash quick_test.sh
```

19 тестов: health, создание тенанта, CRUD через AWS CLI, UI API (создание/удаление очереди, send/peek/purge сообщений).

### hardcore_test.sh — полный тест (AWS CLI + curl)

Требования: `aws cli`, `curl`, `bash`

```bash
bash hardcore_test.sh
```

28 групп тестов:

- Admin API: создание, список, удаление тенантов
- CRUD через AWS CLI и через curl
- Кросс-доставка: CLI отправляет → curl получает (и наоборот)
- Изоляция тенантов: тенант A не видит очереди тенанта B
- Невалидный ввод: неавторизованный доступ, несуществующие очереди
- Спецсимволы: JSON, XML-сущности, Unicode, эмодзи
- Batch операции: SendMessageBatch, DeleteMessageBatch
- Visibility timeout: сообщение скрыто → снова доступно
- Лимиты: максимум очередей на тенанта
- Load test: 20 сообщений throughput
- Целостность: проверка MD5
- Edge cases: длинные имена, большие сообщения, граничные параметры
- UI API: создание/удаление очередей, send/peek/purge сообщений, изоляция

---

## Особенности

- **Полная совместимость с Amazon SQS API** — AWS SDK и CLI работают без изменений, только endpoint меняется
- **Мультитенантность** — каждый тенант с изолированными credentials (Access Key / Secret Key) и лимитами
- **Изоляция** — тенант видит только свои очереди, чужие недоступны
- **Web UI** — визуальное управление тенантами и мониторинг очередей
- **Admin API** — программное управление тенантами (создание, удаление, просмотр)
- **Batch операции** — SendMessageBatch, DeleteMessageBatch для высокой пропускной способности