docs: rebuild showcase repository

2026-04-12 09:12:31 +03:00
parent f69ad4cd23
commit 3ca73a6c96
4 changed files with 292 additions and 1114 deletions
@@ -1,132 +1,84 @@
-# NGCloud Shared SQS — Multi-Tenant Message Queue Service
+# shared-SQS — AWS SQS Compatible Message Queue

-Совместимый с Amazon SQS мультитенантный сервис очередей сообщений.  
-Один кластер — много тенантов, каждый с изолированными очередями и credentials.
+Совместимый с Amazon SQS сервис очередей сообщений с поддержкой изолированных тенантов.
+
+Сервис предназначен для работы через стандартные AWS SDK и AWS CLI: в обычном клиентском коде меняется только endpoint.

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

 | | |
 |---|---|
-| **Web UI** | https://qu.kube5s.ru/ui/ |
-| **SQS Endpoint** | `https://qu.kube5s.ru` |
-| **Access Key** | `SSAK-demo-shared-sqs` |
-| **Secret Key** | `demo-secret-key-shared-sqs-ngcloud-2026` |
-| **Region** | `us-east-1` (любая) |
+| Web UI | https://qu.kube5s.ru/ui/ |
+| SQS Endpoint | https://qu.kube5s.ru |
+| Region | us-east-1 |
+| Demo Access Key | SSAK-demo-shared-sqs |
+| Demo Secret Key | demo-secret-key-shared-sqs-ngcloud-2026 |

-Демо-тенант `demo-service` предустановлен с 5 очередями и сообщениями.  
-Credentials фиксированы — работают после любого рестарта стенда.
+Demo credentials предназначены для ознакомительного доступа.
+Для собственных write-сценариев используйте tenant credentials своего окружения.

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

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

-### Настройка AWS CLI
+- CreateQueue
+- DeleteQueue
+- GetQueueAttributes
+- GetQueueUrl
+- ListQueues
+- PurgeQueue
+- SetQueueAttributes
+- TagQueue
+- UntagQueue
+- ListQueueTags
+- SendMessage
+- SendMessageBatch
+- ReceiveMessage
+- DeleteMessage
+- DeleteMessageBatch
+- ChangeMessageVisibility
+- ChangeMessageVisibilityBatch
+
+## Быстрый старт через AWS CLI

 ```bash
-export AWS_ACCESS_KEY_ID="SSAK-demo-shared-sqs"
-export AWS_SECRET_ACCESS_KEY="demo-secret-key-shared-sqs-ngcloud-2026"
+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"
 ```

---
-
-## 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
+aws sqs create-queue --queue-name demo-queue $ENDPOINT
 ```

-### Список очередей
+### Получить URL очереди

 ```bash
-aws sqs list-queues $ENDPOINT
+aws sqs get-queue-url --queue-name demo-queue $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
+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 "$(aws sqs get-queue-url --queue-name myqueue $ENDPOINT --query QueueUrl --output text)" \
-  $ENDPOINT
+aws sqs receive-message --queue-url "$QUEUE_URL" --wait-time-seconds 5 $ENDPOINT
 ```

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

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

-> **Совет:** `--endpoint-url` — единственное отличие от работы с Amazon SQS.  
-> Весь остальной код без изменений.
-
---
-
-## curl
-
-### Создать очередь
-
-```bash
-curl -s -u "SSAK-demo-shared-sqs:demo-secret-key-shared-sqs-ngcloud-2026" \
-  "https://qu.kube5s.ru/?Action=CreateQueue&QueueName=myqueue&Version=2012-11-05"
-```
-
-### Отправить сообщение
-
-```bash
-curl -s -u "SSAK-demo-shared-sqs:demo-secret-key-shared-sqs-ngcloud-2026" \
-  "https://qu.kube5s.ru/?Action=SendMessage&QueueUrl=https://qu.kube5s.ru/queue/myqueue&MessageBody=HelloWorld&Version=2012-11-05"
-```
-
-### Получить сообщение
-
-```bash
-curl -s -u "SSAK-demo-shared-sqs:demo-secret-key-shared-sqs-ngcloud-2026" \
-  "https://qu.kube5s.ru/?Action=ReceiveMessage&QueueUrl=https://qu.kube5s.ru/queue/myqueue&Version=2012-11-05"
-```
-
---
-
 ## Python (boto3)

 ```python
@@ -136,92 +88,80 @@ sqs = boto3.client(
    "sqs",
    endpoint_url="https://qu.kube5s.ru",
    region_name="us-east-1",
-    aws_access_key_id="SSAK-demo-shared-sqs",
-    aws_secret_access_key="demo-secret-key-shared-sqs-ngcloud-2026",
+    aws_access_key_id="YOUR_ACCESS_KEY",
+    aws_secret_access_key="YOUR_SECRET_KEY",
 )

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

-# Отправить сообщение
-sqs.send_message(QueueUrl=queue["QueueUrl"], MessageBody="Hello from Python!")
-
-# Получить сообщение
-msgs = sqs.receive_message(QueueUrl=queue["QueueUrl"])
-print(msgs["Messages"][0]["Body"])
+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 {
+  SQSClient,
+  CreateQueueCommand,
+  SendMessageCommand,
+  ReceiveMessageCommand,
+} = require("@aws-sdk/client-sqs");

 const sqs = new SQSClient({
  endpoint: "https://qu.kube5s.ru",
  region: "us-east-1",
  credentials: {
-    accessKeyId: "SSAK-demo-shared-sqs",
-    secretAccessKey: "demo-secret-key-shared-sqs-ngcloud-2026",
+    accessKeyId: "YOUR_ACCESS_KEY",
+    secretAccessKey: "YOUR_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);
+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

-### quick_test.sh — быстрая проверка
-
-Требования: `aws cli`, `bash`
+Короткий smoke test основных операций:

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

-19 тестов: health, создание тенанта, CRUD через AWS CLI, UI API (создание/удаление очереди, send/peek/purge сообщений).
+Проверяет базовый lifecycle очереди и сообщения:
+- CreateQueue
+- ListQueues
+- GetQueueUrl
+- SendMessage
+- ReceiveMessage
+- DeleteMessage
+- DeleteQueue

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

-Требования: `aws cli`, `curl`, `bash`
+Расширенный compatibility test:

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

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

- 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 сообщений, изоляция
+## Сравнительные тесты

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

-## Особенности
-
- **Полная совместимость с Amazon SQS API** — AWS SDK и CLI работают без изменений, только endpoint меняется
- **Мультитенантность** — каждый тенант с изолированными credentials (Access Key / Secret Key) и лимитами
- **Изоляция** — тенант видит только свои очереди, чужие недоступны
- **Persistence на Redis** — очереди и сообщения сохраняются при перезапуске сервиса (write-through через Redis)
- **Web UI** — визуальное управление тенантами и мониторинг очередей
- **Admin API** — программное управление тенантами (создание, удаление, просмотр)
- **Batch операции** — SendMessageBatch, DeleteMessageBatch для высокой пропускной способности
+Ключевой вывод: shared-SQS показывает конкурентоспособные результаты относительно Yandex MQ и покрывает полный набор заявленных пользовательских сценариев.