+
+
+ falcot && futriix
+ +
+ Futriix-встроенная распределённая субд в сервер-приложений (falcot) с поддержкой модулей на языке lua, написанная на языке Rust
+
+
+
+
+
+
+
+ Futriix-встроенная распределённая субд в сервер-приложений (falcot) с поддержкой модулей на языке lua, написанная на языке Rust
+
+
+
+
(К началу)
+ +## +**Почему именно HTAP? Анализ характеристик falcot:** + +OLTP (Online Transactional Processing- Онлайн оработка транзакций) черты, присущие falcot: + +1. **Поддержка транзакций - есть BEGIN/COMMIT/ROLLBACK** +2. **CRUD операции - полноценные Create, Read, Update, Delete** +3. **Wait-free архитектура - оптимизирована для быстрых коротких операций** +4. **Поддержка индексов - ускоряет поиск и точки доступа** +5. **ACID-подобное поведение - на уровне отдельных операций** +(К началу)
+ + +## Лицензия + +Проект распространяется под 3-пунктной лицензией BSD. Подробнсти смотрите в файле `LICENSE.txt`. +Эта лицензия является одной из самых демократичных лицензий свободного программного обеспечения. Она позволяет использовать, изменять и распространять код в коммерческих целях без каких-либо ограничений, за исключением сохранения уведомления об авторских правах. + +В том числе, вы можете использовать falcot и futriix в своих коммерческих продуктах, приложениях или сервисах, не беспокоясь о каких-либо юридических ограничениях, связанных с лицензией. + +Все дополнительное программное обеспечение (включая модули на языке lua, утилиту тестирования) предоставляются "как есть", без гарантий и обязательств со стороны разработчиков. Разработчики не несут ответственности за прямой или косвенный ущерб, вызванный использованием открытого кода falcot и futriix или технических решений, использующих этот код. + +(К началу)
+ + +## Подготовка + +**Для операционных систем семейства Debian** выполните следующие шаги: +* Устанавливаем язык программирования Rust + + ```sh + # apt update + # apt upgrade + # curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh + ``` + +**Для операционных систем семейства Red Hat (Fedora, Aurora)** выполните следующие шаги: +* Устанавливаем язык программирования Rust + + ```sh + # dnf update + # curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh + ``` + +**Для операционной системы Alpine** выполните следующие шаги: +* Устанавливаем язык программирования Rust + + ```sh + # apk update + # curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh + ``` + +(К началу)
+ +## Компиляция + +1. Копируем репозиторий + ```sh + $ git clone https://source.futriix.ru/gvsafronov/falcot + ``` +2. Переходим в каталог с исходном кодом src + ```sh + $ cd falcot/ + ``` +3. Компилируем Futriix с помощью пакетного менеджера `Cargo` + ```sh + $ cargo build + ``` + > [!WARNING] +> **Futriix может быть скомпилирован для следующих операционных систем: `Linux`, `OSX`, `Open Indiana`, `FreeBSD`, но сборка для этих операционных систем не проводилась!!!** +(К началу)
+ +## Тестирование + +В состав проекта, входит утилита `integration_tests.rs` **integration_tests.rs** - это интеграционный тестовый набор, который при запуске создает и выполняет сразу несколько различных типов тестов. С её помощью можно запустить как сразу все тесты, так и определённый тест. +Вышеописанная утилита - является мощным инструментом для комплексного тестирования всей системы Falcot, позволяющий быстро выявлять проблемы на разных уровнях приложения и обеспечивать высокое качество кода. + +**Falcot поддерживает пять типов тестов:** + + * **Регрессионный тест - проверяет базовую функциональность** + * **Unit-тест - тестирует конкретный модуль (индексы)** + * **Smoke-тест - проверяет запуск системы** + * **Нагрузочный тест - проверяет производительность** + * **Стресс-тест - проверяет устойчивость при высокой нагрузке** + +**Запуск всех тестов** + +Для запуска всех тестов сразу используйте команду в терминале: + +```sh +$ cargo test --test integration_tests -- --nocapture +``` + +**Запуск конкретного теста** + +```sh +#### Только регрессионный тест +$ cargo test --test integration_tests regression_test -- --nocapture + +#### Только нагрузочный тест +$ cargo test --test integration_tests load_test -- --nocapture + +``` + +**Запуск теста с фильтром** + +```sh +#### Все тесты, содержащие "test" в названии +$ cargo test --test integration_tests test -- --nocapture +``` + +**Что происходит при запуске** +> [!TIP] +> * Создается изолированная тестовая среда - каждый тест работает с чистой копией базы данных +> * Тесты выполняются параллельно (где это безопасно) +> * Каждый тест независим - результаты одного теста не влияют на другие +> * Выводятся подробные логи о ходе выполнения тестов + +(К началу)
+ + + +## Примеры команд субд +```sh +./falcot config.toml + +В интерактивном режиме: + +Loading configuration from: config.toml +Database initialized with system collections + +Falcot Database Server +Version: 1.0.0 +Features: Wait-Free Architecture, Master-Master Replication, Lua Scripting, HTTP/HTTPS Support +HTTP server started on 127.0.0.1:8082 +Starting Lua interpreter... +Lua interpreter ready. Type 'inbox.start' to enter database mode. +Type 'exit' to quit. +lua> falcot_log("Добро пожаловать в Falcot!") +LUA: Добро пожаловать в Falcot! + +lua> inbox.start +Entering database mode. Type CRUD commands or 'inbox.stop' to exit. + +falcot:~> create users '{"name": "Иван", "age": 25, "city": "Москва"}' +Document created with ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + +falcot:~> create users '{"name": "Мария", "age": 30, "city": "Санкт-Петербург"}' +Document created with ID: b2c3d4e5-f6g7-8901-bcde-f23456789012 + +falcot:~> list users +Documents in collection: [{"_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","name":"Иван","age":25,"city":"Москва"},{"_id":"b2c3d4e5-f6g7-8901-bcde-f23456789012","name":"Мария","age":30,"city":"Санкт-Петербург"}] + +falcot:~> begin trans1 +Transaction started successfully + +falcot:~> create products '{"name": "Ноутбук", "price": 50000, "category": "электроника"}' +Document created with ID: c3d4e5f6-g7h8-9012-cdef-345678901234 + +falcot:~> create products '{"name": "Телефон", "price": 25000, "category": "электроника"}' +Document created with ID: d4e5f6g7-h8i9-0123-defg-456789012345 + +falcot:~> commit trans1 +Transaction committed successfully + +falcot:~> inbox.stop +Exiting database mode. Back to Lua interpreter. + +lua> procedure create count_users ' +function count_users() + local result = falcot_db.query("users", "{}") + local count = 0 + for _ in string.gmatch(result, "\\\"name\\\":") do + count = count + 1 + end + return "Всего пользователей: " .. count +end +return count_users +' +Stored procedure created successfully + +lua> procedure call count_users +Procedure result: Всего пользователей: 2 + +lua> exit +Shutting down Falcot server... +``` + +**Параллельно запускаем в другом терминале:** + +```sh +#### Проверка HTTP API +curl http://127.0.0.1:8082/api/ +#### {"status": "ok", "message": "Falcot Server is running"} + +#### Получение списка пользователей +curl http://127.0.0.1:8082/api/query?collection=users +#### [{"_id":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","name":"Иван","age":25,"city":"Москва"},...] +``` +(К началу)
+ + +## Обработка статических страниц + +Запуск статических веб-страниц, из сервера приложений falcot + +Falcot имеет встроенную поддержку статических файлов: +Настройка статических файлов: + +```sh + Создайте каталог `static` в корневой директории приложения: + + $ mkdir static + ``` + Разместите файлы в каталоге static: + ```sh + falcot/ +├── static/ +│ ├── index.html +│ ├── style.css +│ ├── script.js +│ ├── images/ +│ │ └── logo.png +│ └── api-docs.html +└── config.toml +``` + +После чего HTTP сервер автоматически будет обслуживать эти файлы: +```sh +Примеры доступа: + +# Главная страница +http://127.0.0.1:8082/ + +# Конкретный файл +http://127.0.0.1:8082/index.html +http://127.0.0.1:8082/style.css +http://127.0.0.1:8082/images/logo.png + +# API документация +http://127.0.0.1:8082/api-docs.html +``` + +**Falcot поддерживает следующие типы файлов:** + + * HTML (.html) + * CSS (.css) + * JavaScript (.js) + * Изображения (.png, .jpg, .jpeg) + * Аудио (.mp3) + * Видео (.mp4) + * JSON (.json) + * Текстовые файлы (.txt) + * Файлы в формате **pdf** (.pdf) + * Markdown (.md) + + + +(К началу)
+ + +## Репликация + +Сервер-приложенй falcot поддерживает синхронную мастер-мастер репликацию. +За управление репликацией отвечает секция `[replication]` в конфигурационном файле `config.toml` + +```sh +# config.toml +[server] +host = "127.0.0.1" +port = 8081 +http_port = 8082 + +[replication] +enabled = true +master_nodes = [ + "127.0.0.1:8081", + "127.0.0.1:8083", + "127.0.0.1:8085" +] +sync_interval = 2000 # 2 секунды +``` + +**Запуск нескольких экземпляров сервера** + +```sh +# Терминал 1 - основной сервер на порту 8081 +$ cargo run -- config1.toml + +# Терминал 2 - реплика на порту 8083 +$ cargo run -- config2.toml + +# Терминал 3 - реплика на порту 8085 +$ cargo run -- config3.toml +``` + +**Тестирование репликации** + +```sh +-- replication_test.lua +falcot_log("Testing replication...") + +-- Добавляем данные на основном сервере +local doc1 = falcot_db.create("test_data", '{"type": "main", "value": "from_server_1"}') +local doc2 = falcot_db.create("test_data", '{"type": "main", "value": "from_server_1_again"}') + +falcot_log("Documents created on main server: " .. doc1 .. ", " .. doc2) + +-- Ждем синхронизации +falcot_log("Waiting for replication...") +os.execute("sleep 3") -- Ждем дольше интервала синхронизации + +-- Проверяем на репликах (это нужно делать с разных клиентов) +falcot_log("Checking replicated data...") +local all_data = falcot_db.query("test_data", "{}") +falcot_log("All data: " .. all_data) +``` + +**Мониторинг репликации** + +```sh +# В Lua shell можно проверять статус репликации +lua> inbox.start + +# Проверяем статус репликации +falcot:~> print(falcot.engine.replication.status()) + +# Смотрим список узлов +falcot:~> print("Nodes: " .. table.concat(falcot.engine.replication.get_nodes(), ", ")) + +# Запускаем принудительную синхронизацию +falcot:~> falcot.engine.replication.sync() +``` + +(К началу)
+ +**Пример конфигурационных файлов репликации для узлов кластера** + +**config1.toml (основной сервер):** + +```sh +[server] +host = "127.0.0.1" +port = 8081 +http_port = 8082 + +[replication] +enabled = true +master_nodes = ["127.0.0.1:8083", "127.0.0.1:8085"] +sync_interval = 1000 + +[lua] +scripts_dir = "lua_scripts" +auto_execute = ["init.lua"] +``` + +**config2.toml (Реплика 1):** + +```sh +[server] +host = "127.0.0.1" +port = 8083 +http_port = 8084 + +[replication] +enabled = true +master_nodes = ["127.0.0.1:8081", "127.0.0.1:8085"] +sync_interval = 1000 +``` + +**config3.toml (Реплика 2):** + +```sh +[server] +host = "127.0.0.1" +port = 8085 +http_port = 8086 + +[replication] +enabled = true +master_nodes = ["127.0.0.1:8081", "127.0.0.1:8084"] +sync_interval = 1000 +``` + +**config4.toml (Реплика 3):** + +```sh +[server] +host = "127.0.0.1" +port = 8086 +http_port = 8087 + +[replication] +enabled = true +master_nodes = ["127.0.0.1:8081", "127.0.0.1:8083"]4sync_interval = 1000 +``` + +**Мониторинг и управление** + +```sh +#### Проверка статуса репликации через HTTP API +curl http://127.0.0.1:8082/api/replication/status + +#### Принудительная синхронизация +curl -X POST http://127.0.0.1:8082/api/replication/sync + +#### Просмотр статистики +curl http://127.0.0.1:8082/api/stats +``` + +**Пример lua-скрипта по обработки ошибок репликации** + +```sh +-- error_handling.lua +falcot_log("Testing replication error handling") + +-- Пытаемся добавить данные при недоступности реплик +local success, result = pcall(function() + return falcot_db.create("test_collection", '{"data": "test"}') +end) + +if success then + falcot_log("Data created successfully: " .. result) + + -- Проверяем статус репликации + local rep_status = falcot.engine.replication.status() + if rep_status ~= "active" then + falcot_log("Warning: Replication is not active. Status: " .. rep_status) + end + +else + falcot_error("Failed to create data: " .. result) + + -- Пытаемся работать в offline режиме + falcot_log("Trying offline operation...") + local offline_data = falcot_db.query("test_collection", "{}") + falcot_log("Offline data available: " .. #offline_data) +end +``` + +## Резервное копирование + +Для встроенной в сервер-приложений falcot, субд **futriix** предусмотрен механизм восстановления из резервных копий (бекапов) +Бекапы можно создавать c помощью языка lua. + +**Создание бекапа через lua** + +```sh +-- Создаем бэкап +local result = falcot.engine.backup.start() +print(result) -- "Backup created successfully: /falcot/backups/backup_20231201_143022.json" + +-- Или через прямое обращение к функции +local result = falcot_db.backup_start() +print(result) + +-- Создаем несколько тестовых документов перед бэкапом +falcot_db.create('products', '{"name": "Laptop", "price": 999.99, "category": "electronics"}') +falcot_db.create('products', '{"name": "Phone", "price": 499.99, "category": "electronics"}') +falcot_db.create('users', '{"name": "Alice", "email": "alice@example.com", "role": "admin"}') + +-- Создаем бэкап с данными +local backup_result = falcot.engine.backup.start() +``` + +**Восстановление из бекапа** + +```sh +-- Восстанавливаем из конкретного бэкапа +local restore_result = falcot.engine.backup.restore('/falcot/backups/backup_20231201_143022.json') +print(restore_result) -- "Backup restored successfully" + +-- Или через прямое обращение +local restore_result = falcot_db.backup_restore('/falcot/backups/backup_20231201_143022.json') + +-- Проверяем, что данные восстановились +local users = falcot_db.read('users', 'user123') +local products = falcot_db.query('products', '{}') +print('Users:', users) +print('Products count:', #products) + +``` +**Использование бекапов в интерактивной оболочке** + +```sh +#### Создаем бэкап +backup start +# Output: Backup created successfully: /falcot/backups/backup_20231201_143022.json + +#### Восстанавливаем из бэкапа +backup restore /falcot/backups/backup_20231201_143022.json +#### Output: Backup restored successfully + +#### Смотрим список доступных бэкапов +!ls /falcot/backups/ +#### Output: backup_20231201_143022.json backup_20231202_020001.json + +#### Создаем тестовые данные +create products '{"name": "Test Product", "price": 100}' +create users '{"name": "Test User", "email": "test@example.com"}' + +#### Создаем бэкап и сразу проверяем восстановление +backup start +delete products test_product_id +delete users test_user_id +backup restore /falcot/backups/backup_20231201_143022.json +read products test_product_id +#### Данные восстановяться +``` + +**Интеграция с триггерами для создания автоматических бекапов** + +```sh +-- Триггер для создания бэкапа при критических изменениях +falcot_db.add_trigger('auto_backup_on_change', 'after_update', 'config', [[ + local config = json.decode(document) + if config.critical_setting then + -- Создаем бэкап при изменении критических настроек + local backup_result = falcot_db.backup_start() + falcot_log('Auto-backup created due to config change: ' .. backup_result) + end +]]) + +-- Триггер для бэкапа перед массовыми операциями +falcot_db.add_trigger('backup_before_bulk_operation', 'before_delete', 'users', [[ + -- Проверяем, это одиночное удаление или массовая операция + if bulk_operation then + local backup_result = falcot_db.backup_start() + falcot_log('Backup created before bulk operation: ' .. backup_result) + end +]]) + +``` + +(К началу)
+ + +## HTTP API + +Использование curl для работы с HTTP API: + +```sh +#### Проверка статуса сервера +curl http://127.0.0.1:8082/ + +##### Создание документа +curl -X POST http://127.0.0.1:8082/api/create \ + -H "Content-Type: application/json" \ + -d '{ + "collection": "users", + "document": {"name": "John Doe", "email": "john@example.com", "age": 30} + }' + +#### Чтение документа +curl "http://127.0.0.1:8082/api/read?collection=users&id=document_id_here" + +#### Запрос документов +curl -X POST http://127.0.0.1:8082/api/query \ + -H "Content-Type: application/json" \ + -d '{ + "collection": "users", + "filter": {"age": {"$gt": 25}} + }' + +#### Обновление документа +curl -X PUT http://127.0.0.1:8082/api/update \ + -H "Content-Type: application/json" \ + -d '{ + "collection": "users", + "id": "document_id_here", + "document": {"name": "John Updated", "age": 31} + }' + +#### Удаление документа +curl -X DELETE http://127.0.0.1:8082/api/delete \ + -H "Content-Type: application/json" \ + -d '{ + "collection": "users", + "id": "document_id_here" + }' + ``` + +(К началу)
+ + +## Аутентификация + +Для повышения безопасности в сервере-приложений falcot используется `Аутентификация`. +За параметры авторизации отвечает секция `[security]` в конфигурационном файле `./falcot/config.toml` + +```sh +[security] +require_authentication = false +jwt_secret = "your-secret-key-here" +password_hashing_rounds = 12 +``` +(К началу)
+ +## HTTPS + +Сервер-приложенй falcot поддерживает протоколы https и http2. +Утилита `generate_certs` - Генерация сертификатов + +Назначение: Генерация самоподписанных SSL/TLS сертификатов для HTTPS. +Запуск утилиты для генерации тестовых сертификатов: `cargo run --bin generate_certs` + +По итогу работы утитилиты создаётся следующее дерево каталогов: + +```sh +certs/ +├── cert.pem # Публичный сертификат +└── key.pem # Приватный ключ +``` + +Процесс генерации сертификата: + + **1.Создается пара ключей (публичный и приватный)** + **2.Генерируется самоподписанный сертификат** + **3.Сертификат подписывается приватным ключом** + **4.Файлы сохраняются в папку `certs` ** + + +**Примеры конфигураций** + + +**Пример 1: Базовая конфигурация** + +```sh +[tls] +enabled = true +cert_path = "certs/cert.pem" +key_path = "certs/key.pem" + +[server] +https_port = 8443 +``` + +**Пример 2: Генерация сертификатов и запуск** + +```sh +# Генерируем сертификаты +cargo run --bin generate_certs + +# Запускаем сервер +cargo run + +# Тестируем подключение +curl -k https://localhost:8443/api/status +curl http://localhost:8082/api/status +``` + +> [!TIP] +> Безопасность: +> * Самоподписанные сертификаты подходят для разработки и внутреннего использования +> * Для продакшена рекомендуется использовать сертификаты от Let's Encrypt или других CA +> * ACL обеспечивает дополнительный уровень безопасности +> * HTTPS шифрует трафик между клиентом и сервером +> * ACL защищает от нежелательных подключений, а `generate_certs` позволяет быстро настроить HTTPS для безопасного соединения. + + +(К началу)
+ + +## ACL + +**ACL** - это система управления доступом, которая позволяет разрешать или запрещать подключения к серверу на основе IP-адресов. +Как работает ACL в Falcot: + +Принцип работы: + + **1.Проверка запрещенных IP - если IP в списке denied_ips, доступ блокируется** + **2.Проверка разрешенных IP - если список allowed_ips не пустой, проверяется наличие IP в нем** + **3.Если ACL отключен - все подключения разрешены** + + +**Примеры использования в конфигурации:** + +```sh +#### Разрешить только локальные подключения +[acl] +enabled = true +allowed_ips = ["127.0.0.1", "::1"] +denied_ips = [] + +#### Заблокировать конкретные проблемные IP +[acl] +enabled = true +allowed_ips = [] # Пустой список = разрешены все +denied_ips = ["192.168.1.100", "10.0.0.25"] + +#### Разрешить только внутреннюю сеть +[acl] +enabled = true +allowed_ips = ["192.168.1.0/24", "10.0.0.0/8"] +denied_ips = [] +``` +(К началу)
+ + +## Индексы + +Falcot поддерживает два стандартных типа индекса: первичные индексы и вторичные индексы + +**Различия между первичным и вторичным индексом** + +1. **Первичный индекс (Primary Index)** + +**Особенности:** + + 1. **Обязательно уникальный - не допускает дублирования значений** + 2. **Автоматически создается для поля id в каждой коллекции и не требует ручного создания** + 3. **Используется для быстрого поиска документов по их идентификатору** + 4. **Гарантирует целостность данных - предотвращает создание документов с одинаковым `ID`** + +**Пример создания** + +```sh +-- Поиск по ID (использует первичный индекс) +local document = falcot_db.read("users", "550e8400-e29b-41d4-a716-446655440000") +``` + +2. **Вторичный индекс (Secondary Index)** + +**Особенности:** + + 1. **Может быть как уникальным, так и неуникальным** + 2. **Создается вручную для любых полей документа** + 3. **Используется для оптимизации запросов по не-`ID полям`** + 4. **Поддерживает различные типы данных (строки, числа, булевы значения)** + + +**Пример создания** + +```sh +-- Неуникальный индекс по полю 'email' +falcot_db.create_index("users", "email_idx", "email", false) + +-- Уникальный индекс по полю 'username' +falcot_db.create_index("users", "username_idx", "username", true) +``` + + +**Создание и использование индексов через Lua shell** + +```sh +#### Запускаем сервер +$ cargo run + +#### Входим в режим inbox +$ lua> inbox.start + +#### Создаем коллекцию пользователей +falcot:~> create users '{"name": "Alice", "age": 30, "email": "alice@example.com"}' +falcot:~> create users '{"name": "Bob", "age": 25, "email": "bob@example.com"}' +falcot:~> create users '{"name": "Charlie", "age": 35, "email": "charlie@example.com"}' + +#### Создаем вторичный индекс по полю "name" +falcot:~> index create users name_index name + +#### Создаем уникальный индекс по полю "email" +falcot:~> index create users email_index email unique + +#### Ищем по индексу name +falcot:~> index query users name_index "Alice" + +#### Ищем по индексу email +falcot:~> index query users email_index "bob@example.com" + +#### Пытаемся создать дубликат email (должна быть ошибка) +falcot:~> create users '{"name": "Another Bob", "age": 28, "email": "bob@example.com"}' +``` +**Создание и использование индексов через Lua скрипты:** + +```sh +-- create_indexes.lua +falcot_log("Creating indexes...") + +-- Создаем индексы +falcot_db.create_index("users", "name_index", "name", false) +falcot_db.create_index("users", "email_index", "email", true) + +-- Добавляем данные +falcot_db.create("users", '{"name": "Alice", "age": 30, "email": "alice@example.com"}') +falcot_db.create("users", '{"name": "Bob", "age": 25, "email": "bob@example.com"}') + +-- Поиск по индексу +local result = falcot_db.query_by_index("users", "name_index", "Alice") +falcot_log("Search result: " .. result) + +-- Проверка уникальности (должна вызвать ошибку) +local status, err = pcall(function() + falcot_db.create("users", '{"name": "Another", "age": 28, "email": "bob@example.com"}') +end) +if not status then + falcot_error("Unique constraint violation: " .. err) +end +``` + +**Производительность индексов** + +**Первичный индекс:** + + * ** Максимальная скорость поиска по ID** + * **Всегда в памяти (кешируется)** + * **Минимальные накладные расходы** + +**Вторичный индекс:** + + * **Скорость зависит от размера индексируемых данных** + * **Может требовать дополнительной памяти** + * **Оптимизирует конкретные типы запросов** + +**Рекомендации по использованию индексов** + +Используйте первичный индекс для: + + * **Быстрого доступа к документам по их ID** + * **Операций обновления/удаления конкретных документов** + * **Гарантии уникальности идентификаторов** + +Используйте вторичный индекс для: + + * **Поиска документов по любым другим полям** + * **Оптимизации часто выполняемых запросов** + * **Обеспечения уникальности бизнес-ключей (email, username и т.д.)** + * **Ускорения сортировки и фильтрации** + + +#### Обработка ошибок индексов + +**Первичный индекс (автоматическая проверка) на языке lua: ** + +```sh +-- Попытка создать документ с существующим ID вызовет ошибку +local status, err = pcall(function() + falcot_db.create("users", '{"id": "existing_id", "name": "Duplicate"}') +end) +``` + +**Вторичный индекс (ручная проверка уникальности) на языке lua: :** + +```sh +-- При unique=true попытка дублирования вызовет ошибку +local status, err = pcall(function() + falcot_db.create("users", '{"email": "existing@example.com", "name": "Duplicate"}') + falcot_db.create("users", '{"email": "existing@example.com", "name": "Duplicate2"}') +end) +if not status then + falcot_error("Unique constraint violation: " .. err) +end +``` + +Таким образом, первичный индекс в falcot - это автоматически создаваемый уникальный индекс для поля `id`, в то время как вторичные индексы создаются вручную для оптимизации произвольных запросов и могут быть как уникальными, так и неуникальными. + +(К началу)
+ + +## Constraints (Ограничения) + +**Ограничения (Constraints)** — это правила, применяемые к данным в таблице в реляционных субд (или её аналоге в не реляцционных субд) для поддержания их корректности и надёжности. Они играют важную роль в обеспечении целостности данных и соответствия бизнес-правилам. + +При создании таблицы или измененинии её структуры, можно определить различные ограничения,предотвращающие добавление, изменение или удаление данных, нарушающих установленные правила. Это помогает избежать нежелательных ситуаций, например таких как: + + * **Наличие нескольких пользователей с одинаковыми идентификаторами** + * **Ссылки на несуществующие записи в других таблицах** + * **Отсутствие данных обязательных для заполнения** + * **Ввод некорректных значений (например, отрицательного возраста или будущей даты рождения)** + + Ограничения реализованы на уровне встроенной субд **futriix**, ниже приведы примеры использования Ограничений: +(К началу)
+ + +## Хранимые процедуры + +**Хранимая процедура в falcot** – это откомпилированная во внутреннее представление сервера субд подпрограмма, хранящаяся в базе данных. Хранимые процедуры пишутся на специальном языке хранимых процедур и триггеров, в котором имеются операторы присваивания, ветвлений и циклов, и в которых можно использовать операторы SQL, такие как INSERT, DELETE, UPDATE и SELECT. + + **Создание хранимой процедуры** + + ```sh + -- Создание хранимой процедуры для расчета статистики + local procedure_code = [[ function calculate_stats(collection_name) + local documents = falcot_db.query(collection_name, "{}") + local count = 0 + local total_age = 0 + + for doc in string.gmatch(documents, '([^,]+)') do + count = count + 1 + -- Здесь можно парсить JSON и считать статистику + end + + return "Документов: " .. count .. ", Средний возраст: " .. (total_age / count) + end + return calculate_stats ]] + version = "1.0.0" + edition = "2024" + ``` + + ```sh +-- Сохраняем процедуру +falcot_db.create_procedure("calculate_stats", procedure_code) +``` + +**Работа с хранимыми процедурами в lua интерпретаторе:** + +```sh +-- Создание процедуры +procedure create calculate_stats ' +function calculate_stats(collection_name) + local result = falcot_db.query(collection_name, "{}") + local count = 0 + for _ in string.gmatch(result, "\\\"_id\\\":") do + count = count + 1 + end + return "Количество документов в " .. collection_name .. ": " .. count +end +return calculate_stats +' + +-- Вызов процедуры +procedure call calculate_stats +``` + +**Создание хранимых процедур во одноимённой встроенной субд** + +```sh +# Создание процедуры +procedure create user_stats ' +function calculate_user_stats() + local users = falcot_db.query("users", "{}") + local count = 0 + for _ in string.gmatch(users, "\\\"name\\\":") do + count = count + 1 + end + return "Всего пользователей: " .. count +end +return calculate_user_stats +' +``` + +```sh +#### Вызов процедуры +procedure call user_stats +``` + +(К началу)
+ + +## Триггеры + +Falcot помимо хранимых процедур поддерживает триггеры (обратные вызовы) +Триггеры можно создавать тремя способами: через lua-shell, через интерактивную оболочку, через хранимые процедуры встроенной субд + +**Создание триггеров через lua-shell** + +```sh + +-- Создаем триггер, который логирует создание документов в коллекции 'users' +falcot_db.add_trigger('log_user_creation', 'after_create', 'users', [[ + falcot_log('New user created with data: ' .. document) + -- Можно добавить дополнительную логику, например: + -- - Отправка уведомления + -- - Валидация данных + -- - Обновление связанных документов +]]) + +-- Триггер для проверки данных перед обновлением +falcot_db.add_trigger('validate_user_update', 'before_update', 'users', [[ + local user_data = json.decode(document) + if not user_data.email or not user_data.email:match('^[^@]+@[^@]+%.[^@]+$') then + error('Invalid email format') + end + if user_data.age and user_data.age < 0 then + error('Age cannot be negative') + end +]]) + +-- Триггер для очистки связанных данных при удалении +falcot_db.add_trigger('cleanup_user_data', 'before_delete', 'users', [[ + -- Удаляем связанные записи из других коллекций + falcot_db.delete('user_sessions', id) + falcot_db.delete('user_preferences', id) + falcot_log('Cleaned up user data for ID: ' .. id) +]]) +``` + +**Создание триггеров через интерактивную оболочку** + +```sh +##### Переходим в режим inbox +inbox.start + +##### Создаем триггер для логирования +trigger add log_creation after_create orders "falcot_log('New order created: ' .. document)" + +#### Триггер для автоматического обновления статистики +trigger add update_stats after_create orders [[ + -- Увеличиваем счетчик заказов + local stats = falcot_db.read('statistics', 'order_count') or '0' + local count = tonumber(stats) + 1 + falcot_db.update('statistics', 'order_count', tostring(count)) +]] + +#### Триггер для проверки цены перед созданием +trigger add validate_price before_create products [[ + local product = json.decode(document) + if product.price <= 0 then + error('Price must be positive') + end +]] + +``` + +**Пример создание триггеров через хранимые процедуры** + +```sh + +-- Создаем документ - сработает триггер after_create +falcot_db.create('users', '{"name": "John", "email": "john@example.com", "age": 25}') +-- В логах появится: "LUA: New user created with data: {"name": "John", "email": "john@example.com", "age": 25}" + +-- Попытка создать пользователя с невалидным email +falcot_db.create('users', '{"name": "Invalid", "email": "invalid", "age": 30}') +-- Получим ошибку: "Invalid email format" + +-- Обновляем пользователя +falcot_db.update('users', 'user123', '{"name": "John Updated", "email": "john.new@example.com", "age": 26}') +-- Сработает триггер before_update для валидации + +-- Удаляем пользователя +falcot_db.delete('users', 'user123') +-- Сработает триггер before_delete для очистки связанных данных + +``` + +(К началу)
+ +## Lua-скрипты + +> [!CAUTION] +> **Поддержка работы lua в настоящий момент эксперементальная и может вызвать аварийное завершение сервера!!!** + +В Falcot существует несколько способов запуска Lua скриптов + + +**Способ 1: Непосредственный ввод кода в lua-интерпретатор** +```sh +lua> falcot_log("Привет, мир!") +LUA: Привет, мир! + +lua> local x = 10 + 5 +lua> falcot_log("Результат: " .. x) +LUA: Результат: 15 +``` + +**Способ 2: Многострочный ввод (через конкатенацию)** +```sh +lua> local script = [[ +>> for i = 1, 3 do +>> falcot_log("Итерация: " .. i) +>> end +>> ]] +lua> falcot.engine.execute_script(script) +LUA: Итерация: 1 +LUA: Итерация: 2 +LUA: Итерация: 3 +``` + +**Способ 3: Запуск из файла** + + 1. **`lua_scripts` - это каталог (директория), где хранятся Lua-скрипты для выполнения сервером Falcot** + 2. **При запуске сервера автоматически выполняются скрипты из `auto_execute` списка, находящиеся в этой директории** + 3. **Сервер автоматически создает этот каталог при первом запуске, если он не существует** + +**Как это работает:** + + 1. **Сервер при запуске создает каталог lua_scripts (если его нет)** + 2. **В этот каталог можно помещать Lua-скрипты** + 3. **Скрипты из списка auto_execute выполняются автоматически при старте сервера** + 4. **Другие скрипты можно выполнять вручную через Lua-интерпретатор командой falcot.engine.lua.execute("имя_скрипта.lua")** + + +```sh + +Пример структуры каталогов falcot: + +lua_scripts/ +├── init.lua (автоматически выполняется при старте) +├── utils.lua (вспомогательные функции) +├── procedures/ (подкаталог для хранимых процедур) +│ ├── user_management.lua +│ └── data_processing.lua +└── config/ (подкаталог для конфигурационных скриптов) + └── system_config.lua +``` + +### Примеры lua-скриптов +```sh +-- Простой Lua скрипт для демонстрации +falcot_log("Запуск примера Lua скрипта") + +-- Создание документа +falcot_db.create("users", '{"name": "John", "age": 30, "email": "john@example.com"}') + +-- Чтение документа +local result = falcot_db.read("users", "some-document-id") +falcot_log("Результат чтения: " .. result) +``` + +```sh +-- Математические операции +local x = 10 +local y = 20 +falcot_log("Сумма: " .. (x + y)) + +-- Циклы и условия +for i = 1, 5 do + if i % 2 == 0 then + falcot_log("Четное число: " .. i) + else + falcot_log("Нечетное число: " .. i) + end +end + +``` +(К началу)
+ +## Транзакции + +Работа с транзакциями, во встроенной субд: + +```sh +# Начало транзакции +begin transaction_123 + +# Несколько операций в транзакции +create users '{"name": "Alice", "age": 25}' +create users '{"name": "Bob", "age": 30}' +create users '{"name": "Charlie", "age": 35}' + +# Фиксация транзакции +commit transaction_123 + +# Или откат при ошибке +begin transaction_456 +create users '{"name": "David", "age": 40}' +rollback transaction_456 +``` +(К началу)
+ + +## Шардинг + +Встроенная в falcot субд **futriix** поддерживает горинзонтальный шардинг, т.е. горизонтальное масштабирование. +По умолчанию шардинг производится `по алгоритму Hash-based с консистентным хэшированием`. Шифрование производится согласно алгоритму `SipHasher13`. +Но также поддерживается возможность управлять шардингом вручную. Ниже приведены команды по управлению шардингом: + +**Пример добавления узла** + +```sh +#### Добавляем новый узел шардинга +falcot:~> shard add node1 127.0.0.1:8084 1024 + +#### Где: +#### - node1: идентификатор узла +#### - 127.0.0.1:8084: адрес узла +#### - 1024: емкость в MB +``` + +**Пример удаления узла** + +```sh +#### Удаляем узел из кластера +falcot:~> shard remove node1 +``` + +**Пример миграции между шардами узла** + +```sh +#### Мигрируем данные коллекции между узлами +falcot:~> shard migrate users node1 node2 user_id + +#### Где: +#### - users: коллекция для миграции +#### - node1: исходный узел +#### - node2: целевой узел +#### - user_id: ключ шардирования +``` + +**Пример просмотра статуса кластера** + +```sh +#### Показывает статус всего кластера +falcot:~> shard status + +#### Пример вывода: +#### === Cluster Status === +#### Total capacity: 2048 GB +#### Total used: 512 MB +#### Rebalance needed: false +#### +#### Node node1: +#### Address: 127.0.0.1:8081 +#### Capacity: 1024 MB +#### Used: 256 MB +#### Usage: 25.0% +#### Collections: users, products +``` + +**Пример ручной ребалансировки кластера** + +```sh +#### Запускает автоматическую ребалансировку +falcot:~> cluster rebalance +``` + +**Пример создания шардированной системы пользователей** + +```sh +#### Добавляем узлы +falcot:~> shard add node1 127.0.0.1:8081 1024 +falcot:~> shard add node2 127.0.0.1:8082 1024 + +#### Создаем constraints для пользователей +falcot:~> constraint add users unique_email unique email +falcot:~> constraint add users valid_age range age "{\"min\":13,\"max\":150}" +falcot:~> constraint add users valid_username pattern username "^[a-zA-Z0-9_]{3,20}$" + +#### Распределяем пользователей по шардам +shard migrate users node1 node2 user_id +``` + +**Мониторинг шардинга** + +```sh +#### Проверяем статус +falcot:~> shard status + +#### Если нужно перебалансировать +falcot:~> cluster rebalance + +#### Проверяем constraints +falcot:~> constraint list users +``` + +(К началу)
+ + +## Сферы применения + +Идеальными сферами применения проекта falcot, являются следующие: + +1. **Микросервисы с потребностью в оперативной аналитике** +2. **Работающая в режиме реального времени панель мониторинга - для администрирования бекенда** +3. **Приложения, тербующие среднего масштабирования со смешанными рабочими нагузками (англ. workload)** +4. **Прототипирование перед выбором специализированного решения** + +(К началу)
+ + +## Дорожная карта + +- [x] Реализовать поддержку хранимых процедур +- [x] Реализовать поддержку триггеров (обратных вызовов) +- [x] Реализовать поддержку многопоточности +- [x] Реализовать неблокирующие чтение/запись +- [x] Реализовать мульти-мастер асинхронную репликацию через файл конфигурации +- [x] Реализовать логирование +- [x] Реализовать поддержку синхронной мастер-мастер репликации +- [x] Реализовать поддержку протоколов HTTPS и HTTP2 +- [x] Реализовать поддержку первичных индексов +- [x] Реализовать поддержку протокола MessagePack +- [x] Реализовать поддержку транзакций +- [x] Реализовать поддержку первичных и вторичных индексов +- [x] Добавить механизм сторонних модулей на языке lua, расширяющих базовый функционал сервера +- [x] Реализовать проверку запуска сервера при запуске клиента (если сервер НЕ запущен клиент не запускается) +- [x] Реализовать поддержку HTTP-restfull API +- [x] Исправить ошибки записи журнала логов (в журнал лога кроме текущего времени добавить текущий год) +- [x] Реализовать утилиту тестирования сервера на количество запросов на чтение/запись +- [x] Переписать асинхронную мастер-мастер репликацию на синхронную мастер-мастер репликацию +- [ ] Реализовать журнал WAL +- [ ] Реализовать графический веб-интерфейс для упраления кластером +- [x] Реализовать автоматический шардинг с консистентным хэшированием +- [ ] Реализовать поддержку алгоритма Raft +- [ ] Реализовать поддержку SQL +- [ ] Реализовать поддержку ACID-транзакций +- [ ] Интегрировать интеллектуального помощник FutBot на официальный сайт +- [ ] Реализовать полноценного интеллектуального помощника FutBot, задачами которого будут быстрый поиск ответов на вопросы, возникающие при эксплуатации субд Futrix. + +См. [Открытые проблемы](https://source.futriix.ru/gvsafronov/futriixw/issues) полный список предлагаемых функций (и известных проблем). + +(К началу)
+ + + + + +## Контакты + +Григорий Сафронов - [E-mail](gvsafronov@yandex.ru) + +Ссылка на Интеллектуальный помощник - [FutBot](https://t.me/Futriix_bot) + +(К началу)